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.mdsrc/main/java/org/praxisplatform/config/domain/AiRegistry.javasrc/main/java/org/praxisplatform/config/repository/AiRegistryRepository.javasrc/main/java/org/praxisplatform/config/controller/RegistryIngestionController.javasrc/main/java/org/praxisplatform/config/service/RegistryIngestionService.javasrc/main/java/org/praxisplatform/config/registry/AiRegistryBootstrapService.javasrc/main/java/org/praxisplatform/config/registry/AiRegistryStatusService.javasrc/main/java/org/praxisplatform/config/controller/AiRegistryTemplateController.javasrc/main/java/org/praxisplatform/config/service/AiRegistryTemplateService.javasrc/main/java/org/praxisplatform/config/controller/AgenticAuthoringManifestController.javasrc/main/java/org/praxisplatform/config/ai/authoring/AgenticAuthoringManifestService.javasrc/main/java/org/praxisplatform/config/ai/authoring/AgenticAuthoringToolRegistry.javasrc/main/java/org/praxisplatform/config/ai/authoring/AgenticAuthoringTargetResolverRegistry.javasrc/main/java/org/praxisplatform/config/ai/authoring/AgenticAuthoringValidatorRegistry.javasrc/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.jsondocs/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.mdgenerate-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, includingcomponentDefinition.jsonSchemaand optionalauthoringManifest;template: reusable component config plusaiDescriptionandtemplateMeta, 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-targetsGET /api/praxis/config/ai/authoring/manifests/{componentId}/operationsGET /api/praxis/config/ai/authoring/manifests/{componentId}/presentation-affordancesPOST /api/praxis/config/ai/authoring/manifests/{componentId}/resolve-targetPOST /api/praxis/config/ai/authoring/manifests/{componentId}/validate-planPOST /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
presentationAffordancesas 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
AgenticAuthoringToolRegistrytools as phase-scoped, route-scoped read-only grounding unless theirAgenticAuthoringToolDefinitiondeclares otherwise. Tool execution without an explicit phase must fail withtool-phase-required; an unregistered tool must fail withtool-not-found. - Treat manifest-declared resolvers, validators, and effect handlers as executable only when the
backend registry implements them.
AgenticAuthoringTargetResolverRegistry,AgenticAuthoringValidatorRegistry, andAgenticAuthoringEffectCompilerRegistryare 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
compiledOperationsas normalized audit output,patchOperationsas applicable materialization, andproposedConfigas 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-uxja-suportado-mal-nomeado-ou-mal-materializadosuportado-parcialmentelacuna-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:catalogandnpm run validate:authoring-contracts; usenpm run generate:registry:ingestionwhen 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-manifestsfor the owning Angular component manifest. - Use
praxis-ai-registry-ingestionfor generation, governance, packaging, and upload tooling. - Use
praxis-config-agentic-authoring-streamingfor semantic turn resolution, preview/apply, SSE, quick replies, diagnostics, and replay. - Use
praxis-config-runtime-persistencefor applying a compiled component config with scope and ETag. - Use
praxis-config-api-metadata-groundingfor API/resource RAG and metadata grounding; do not store resource-domain truth in component registry records. - Use
praxis-config-domain-decisionswhen an authoring operation materializes a governed business decision rather than component configuration.