# Praxis Config AI Registry Manifests

> Use when implementing, reviewing, debugging, or validating praxis-config-starter AI registry persistence, component registry ingestion, bootstrap snapshots, templates, semantic search, RAG publication, executable authoring manifest projection, target resolution, validators, effect compilers, presentation affordances, or /api/praxis/config/ai-registry/** and /api/praxis/config/ai/authoring/manifests/** contracts.

- Skill: `codexrodrigues/praxis-config-ai-registry-manifests` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx get-skill add codexrodrigues/praxis-config-ai-registry-manifests`
- Raw SKILL.md: https://api.skillmd.com/api/skills/codexrodrigues/praxis-config-ai-registry-manifests/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: codexrodrigues (https://skillmd.com/u/codexrodrigues)
- Updated: 2026-11-15
- Page: https://skillmd.com/skills/codexrodrigues/praxis-config-ai-registry-manifests

---


# Praxis Config AI Registry Manifests

Use this skill for the canonical backend registry that persists component definitions, templates,
snapshot metadata, and their executable authoring projection in `praxis-config-starter`.
`ai_registry` is governed persistence. It is not a documentation cache, an Angular runtime registry,
or permission to execute whatever appears in a generated JSON document.

## Source Audit

Inspect the owner before editing:

- `praxis-config-starter/AGENTS.md`
- `src/main/java/org/praxisplatform/config/domain/AiRegistry.java`
- `src/main/java/org/praxisplatform/config/repository/AiRegistryRepository.java`
- `src/main/java/org/praxisplatform/config/controller/RegistryIngestionController.java`
- `src/main/java/org/praxisplatform/config/service/RegistryIngestionService.java`
- `src/main/java/org/praxisplatform/config/registry/AiRegistryBootstrapService.java`
- `src/main/java/org/praxisplatform/config/registry/AiRegistryStatusService.java`
- `src/main/java/org/praxisplatform/config/controller/AiRegistryTemplateController.java`
- `src/main/java/org/praxisplatform/config/service/AiRegistryTemplateService.java`
- `src/main/java/org/praxisplatform/config/controller/AgenticAuthoringManifestController.java`
- `src/main/java/org/praxisplatform/config/ai/authoring/AgenticAuthoringManifestService.java`
- `src/main/java/org/praxisplatform/config/ai/authoring/AgenticAuthoringToolRegistry.java`
- `src/main/java/org/praxisplatform/config/ai/authoring/AgenticAuthoringTargetResolverRegistry.java`
- `src/main/java/org/praxisplatform/config/ai/authoring/AgenticAuthoringValidatorRegistry.java`
- `src/main/java/org/praxisplatform/config/ai/authoring/AgenticAuthoringEffectCompilerRegistry.java`
- manifest contract validator, target resolver, validator, effect compiler, capability catalog, and
  presentation-affordance services under `src/main/java/org/praxisplatform/config/ai/authoring/`
- `src/main/resources/ai-registry/registry-snapshot.json`
- `docs/ai/contracts/**` and focused registry, bootstrap, manifest, compiler, controller, and OpenAPI tests.

Inspect the Angular producer with `praxis-ai-registry-ingestion` before changing ingestion shape:

- `praxis-ui-angular/tools/ai-registry/AGENTS.md`
- `generate-registry-ingestion.ts`, its JSON schema, catalog governance, authoring acceptance,
  upload, package-assets, RAG/provider projection, and backend-sync tools
- the owning component manifest and spec with `praxis-ai-authoring-manifests`.

## Canonical Flow

Preserve this ownership chain:

`Angular public API + component metadata + authoring manifest + recipes`
`-> canonical aggregate ingestion registry`
`-> POST /api/praxis/config/ai-registry/component-definitions`
`-> SYSTEM/GLOBAL component_definition records in ai_registry`
`-> release-scoped RAG documents as a derived index`
`-> executable /api/praxis/config/ai/authoring/manifests/{componentId}/** projection`

The Angular aggregate `dist/praxis-component-registry-ingestion.json` is the canonical generated
publication input. Package `ai/component-registry.json`, provider projections, compact registry RAG,
and the backend classpath snapshot are derived artifacts. Regenerate or synchronize them; do not
edit them as independent sources of truth.

The classpath snapshot is an operational fallback/bootstrap artifact. Compare its component count,
manifest coverage, chunks, hash, version, and `generatedAt` with the current Angular ingestion corpus
before claiming that the backend represents current platform capabilities. Registry health proves
configured minimum counts and required IDs, not semantic completeness or release parity.

## Persistence And Scope

`AiRegistry` identity is the tuple:

`registryType + registryKey + componentType + scope + scopeKey`

Current component definitions and templates are persisted as `Scope.SYSTEM` / `GLOBAL`. Ingestion
headers `X-Tenant-ID` and `X-Env` scope the derived RAG publication identity; they do not silently
turn the canonical component definition into tenant-owned registry state. Do not invent tenant or
environment persistence semantics without an explicit public-contract decision.

Keep these record families distinct:

- `component_definition`: generated component contract, including `componentDefinition.jsonSchema`
  and optional `authoringManifest`;
- `template`: reusable component config plus `aiDescription` and `templateMeta`, with semantic search;
- `registry_snapshot_metadata`: bootstrap hash, source, location, release identity, count, and time;
- release-scoped RAG documents: derived retrieval copies, never the persistence source of truth.

Upsert behavior must preserve stable identity and explicitly govern payload, embedding, source,
status, version, ETag, and timestamps. Do not claim optimistic concurrency or incremental versioning
unless update tests prove that `version` and `etag` actually change under the documented policy.

## Executable Manifest Boundary

The backend reads an executable manifest only from:

`component_definition.payload.componentDefinition.jsonSchema.authoringManifest`

A missing manifest is valid for a consult-only/non-authorable component. It must produce a clear
not-found/configuration outcome when an executable manifest endpoint is requested; it must not fall
back to arbitrary JSON patching.

For family components, child-entry `authoringManifestProfiles` are registry applicability
projections, not executable manifests. `AgenticAuthoringManifestService.getManifest(...)` does not
read them as a fallback source. If a child dynamic-fields component appears to have profile chunks but
`/api/praxis/config/ai/authoring/manifests/{componentId}` cannot resolve an executable manifest,
audit the aggregate family `authoringManifest`, component-definition payload, Angular ingestion
projection, and backend registry snapshot instead of compiling from the child projection.

For an authorable component, preserve the complete chain:

`editableTargets -> operationId -> target resolver -> input schema -> validators -> effects/handler`
`-> affected paths -> destructive confirmation -> compiledOperations/patchOperations/proposedConfig`

The executable HTTP surface is:

- `GET /api/praxis/config/ai/authoring/manifests/{componentId}`
- `GET /api/praxis/config/ai/authoring/manifests/{componentId}/editable-targets`
- `GET /api/praxis/config/ai/authoring/manifests/{componentId}/operations`
- `GET /api/praxis/config/ai/authoring/manifests/{componentId}/presentation-affordances`
- `POST /api/praxis/config/ai/authoring/manifests/{componentId}/resolve-target`
- `POST /api/praxis/config/ai/authoring/manifests/{componentId}/validate-plan`
- `POST /api/praxis/config/ai/authoring/manifests/{componentId}/compile-patch`

These endpoints return configuration-invalid responses for missing manifests, undeclared operations,
contract failures, unresolved targets, unsupported validators, or unsupported effects. Do not convert
those failures into local patch generation.

Apply these rules:

- Resolve only operations declared by the selected component manifest.
- Require deterministic target resolution and fail on missing or ambiguous required targets.
- Require explicit confirmation for destructive operations.
- Treat `presentationAffordances` as semantic grounding for compatible presentation choices, not as
  business authorization or an effect compiler.
- Treat runtime observations, chunks, examples, labels, aliases, and templates as grounding evidence,
  never as permissions.
- Treat granular component corpus retrieval (`getComponentAuthoringContext` / `authoringEvidence`) as
  read-only pre-preview grounding. It may enrich planner context with bounded source refs, release,
  chunk kind, content hash, corpus version, visibility, score, and snippet evidence, but it must not
  by itself authorize preview, apply, component selection, operation selection, target resolution,
  validator success, or effect compilation.
- Treat `AgenticAuthoringToolRegistry` tools as phase-scoped, route-scoped read-only grounding unless
  their `AgenticAuthoringToolDefinition` declares otherwise. Tool execution without an explicit phase
  must fail with `tool-phase-required`; an unregistered tool must fail with `tool-not-found`.
- Treat manifest-declared resolvers, validators, and effect handlers as executable only when the
  backend registry implements them. `AgenticAuthoringTargetResolverRegistry`,
  `AgenticAuthoringValidatorRegistry`, and `AgenticAuthoringEffectCompilerRegistry` are the execution
  boundary, not the generated manifest text by itself.
- Fail closed when a referenced validator, target resolver, or domain effect handler has no backend
  implementation. A warning is not sufficient evidence for executable compile/apply.
- Keep `compiledOperations` as normalized audit output, `patchOperations` as applicable materialization,
  and `proposedConfig` as preview. None of them bypasses persistence ETag, authorization, or domain
  decision governance.
- Templates may seed or rank a configuration candidate; they cannot override component manifests,
  backend resource semantics, metadata capabilities, or domain decisions.

`compile-domain-patch` effects are only safe when `supportsDomainPatchHandler(handler)` is true and the
focused compiler tests prove the handler updates `proposedConfig`, `compiledOperations`, and
`patchOperations` as intended. A manifest that names a new handler without backend compiler support is
`suportado-parcialmente` at most.

## Semantic Routing

Do not select component, operation, target, validator, compiler, or template through command words,
regexes, aliases, labels, or fuzzy matching as the primary decision. Use governed context, component
registry keys, declared manifests/tools, metadata and capability catalogs, and LLM semantic intent.
Vector search or textual matching may rank templates or candidates only after semantic scope is known.

If an operation or tool is absent, add it to the canonical owner and synchronize the publication
pipeline. Do not replace the missing contract with a backend fast path or frontend-only patch.

## Aderence Inventory

Before adding registry fields/types, scope variants, endpoint variants, template metadata, manifest
operations, validator IDs, resolver IDs, compiler handlers, health signals, or generated artifacts,
ask what the platform already knows and classify the need:

- `ja-suportado-so-ux`
- `ja-suportado-mal-nomeado-ou-mal-materializado`
- `suportado-parcialmente`
- `lacuna-real-de-contrato`

Only `lacuna-real-de-contrato` justifies a new public contract. Name the missing evidence, canonical
owner, persistence and migration impact, Angular producer, assistant/quickstart consumers, generated
artifacts, docs/OpenAPI impact, compatibility risk, and minimum proof before editing.

## Validation

Run the smallest local gate that proves the changed boundary:

- ingestion identity, invalid manifests, chunk/RAG publication, bootstrap refresh/prune, and snapshot:
  `mvn "-Dtest=RegistryIngestionServiceTest,RegistryIngestionServiceIdentityTest,AiRegistryRevisionPolicyTest,AiRegistryBootstrapServiceTest,AiRegistrySnapshotContractTest" test`
- executable manifests, target resolution, validators, compilers, and HTTP projection:
  `mvn "-Dtest=AgenticAuthoringManifestServiceTest,AgenticAuthoringManifestControllerTest,AgenticAuthoringManifestContractValidatorTest,AgenticAuthoringTargetResolverRegistryTest,AgenticAuthoringValidatorRegistryTest,AgenticAuthoringEffectCompilerRegistryTest" test`
- templates object validation, default description, identity-preserving upsert, semantic search,
  bulk partial failure, delete/not-found, and HTTP mapping:
  `mvn "-Dtest=AiRegistryTemplateServiceTest,AiRegistryTemplateControllerTest" test`
- public AI contract changes:
  `mvn "-Dtest=AiApiContractOpenApiTest,AiContractSpecConsistencyTest,AiContractV11RetroCompatibilityTest" test`
- Angular producer changes: focused tool specs, then `npm run validate:catalog` and
  `npm run validate:authoring-contracts`; use `npm run generate:registry:ingestion` when aggregate
  publication must be regenerated.

Changes to any source in the eleven-source Java compiler closure also affect the receipt in
`docs/ai/agentic-authoring/proofs/ui-composition-compiler-parity-corpus.v1.json`, including
`CanonicalJsonHashService` and `AiRegistryTemplateService` (whose repository boundary is mocked).
Run `UiCompositionGoldenCorpusRunnerTest` alongside the affected service tests; a service-only
green result does not establish source/class closure integrity.
When source/class hashes change, regenerate only `compilerReceipts.java` from the runner report's
`compilerIdentity.sourceReceipt`; review the closure and keep all corpus cases and expected
projections intact. Re-run the golden/compiler/template-resolver/snapshot gate documented in
`docs/ai/agentic-authoring/ui-composition-compiler-parity-corpus-v1.md`, including deliberate
mismatch tests. Do not weaken receipt validation to publish a release. When the first run detects stale receipt
hashes, preserve its RED report and require every semantic case to pass before deriving the new
receipt; any semantic failure requires diagnosis rather than a receipt refresh. The release
profile also requires classification tags on every JUnit `*Test.java` class. Explicit focal
execution does not replace `CiSmokeUnitConventionTest` or the official release gate.

For templates, prove object validation, default description, identity-preserving upsert, semantic
search scoping/limits, payload mapping, bulk partial failure, delete/not-found, and HTTP behavior.
If the owner has no focal template tests for the changed behavior, record that as a platform test
gap instead of presenting unrelated registry tests as proof.

Audit one happy path and these adversarial paths:

- invalid or missing manifest, undeclared operation, unresolved/ambiguous target;
- destructive edit without confirmation;
- validator/resolver/compiler declared but not implemented;
- stale classpath snapshot versus current Angular aggregate;
- component removal and release-scoped RAG cleanup;
- malformed template config and cross-component template search;
- tenant/environment headers incorrectly assumed to change persisted registry scope.

Use the quickstart HTTP/SSE smoke only when registry behavior changes downstream authoring execution.
Reserve GitHub Actions for the final phase/release gate after local proof.

## Derived Artifacts

After public registry or manifest changes, review and synchronize as applicable:

- Angular aggregate ingestion registry and package-scoped AI assets;
- backend classpath snapshot and snapshot contract tests;
- compact RAG compatibility and provider projections;
- template plans/uploads and registry sync scripts;
- `docs/ai/contracts/**`, OpenAPI consistency, public docs/examples, and quickstart smokes.

State explicitly when an artifact does not need an update and why.

## Companion Skills

- Use `praxis-ai-authoring-manifests` for the owning Angular component manifest.
- Use `praxis-ai-registry-ingestion` for generation, governance, packaging, and upload tooling.
- Use `praxis-config-agentic-authoring-streaming` for semantic turn resolution, preview/apply, SSE,
  quick replies, diagnostics, and replay.
- Use `praxis-config-runtime-persistence` for applying a compiled component config with scope and ETag.
- Use `praxis-config-api-metadata-grounding` for API/resource RAG and metadata grounding; do not store
  resource-domain truth in component registry records.
- Use `praxis-config-domain-decisions` when an authoring operation materializes a governed business
  decision rather than component configuration.

