Praxis API Quickstart Domain Pilots
Use this skill when a concrete quickstart domain must prove a Praxis capability in a real Spring Boot host. A pilot is not a disposable CRUD example: it is executable, didactic evidence that semantic grounding, metadata, discovery, governed decisions, and runtime behavior agree end to end.
Classify And Map Impact
Classify a change before editing:
local-pequena: one host resource, with no public contract change.
transversal: a pilot plus another quickstart domain, docs, HTTP evidence, or a runtime consumer.
contrato-publico: ApiPaths, @ApiResource, OpenAPI groups, schemas, option-source endpoints, _links, actions, surfaces, capabilities, stats, or export behavior changes.
arquitetural: ownership or lifecycle crosses the quickstart, metadata starter, config starter, or Angular runtime.
For transversal, contrato-publico, or arquitetural, map the canonical owner, affected resource keys and paths, consumers, cockpit/docs/HTTP evidence, focused tests, and breaking-change risk before patching.
Source Audit
Read the host and the exact pilot before deciding that it needs a new contract:
praxis-api-quickstart/AGENTS.md
src/main/java/com/example/praxis/apiquickstart/constants/ApiPaths.java
src/main/java/com/example/praxis/apiquickstart/config/OptionSourceConfig.java
- the affected
controller, service, dto, dto/filter, dto/actions, mapper, entity, and repository
db/operational-migrations/** and docs/DEMO-DATABASE.md when persistence or seed data changes
docs/SEMANTIC-DOMAIN-CATALOG-CONTRACT.md
docs/COCKPIT-QUICKSTART-REFERENCE.md and its verification scripts when a published pilot contract changes
- focused integration tests in
src/test/java/com/example/praxis/apiquickstart/**
The current reference families are intentionally complementary:
| Pilot family |
Primary proof |
| Human resources |
resource CRUD, payroll workflow, privacy/governance, export, and people lookup |
| Operations |
explicit lifecycle actions, cross-domain relationships, mission and incident workflows |
| Assets |
custody, readiness, allocation, fleet/missions, and analytics |
| Procurement |
governed entity lookup, supplier eligibility, contract/product/order lifecycle, and config decision materialization |
| Risk intelligence |
threat lookup, triage actions, derived incident analytics, and chart-ready stats |
Do not copy one pilot mechanically into another. Start with the business question, existing resource keys, published schemas, capability/action catalogs, and decision evidence.
Canonical Ownership
The quickstart owns concrete example resources, host composition, paths, demo persistence, security exposure, and downstream proof. It is not the source of canonical platform semantics.
praxis-metadata-starter owns x-ui, /schemas/filtered, schema resolution and headers, surfaces, actions, capabilities, HATEOAS, resource bases, option-source runtime contracts, and metadata discovery.
praxis-config-starter owns governed Domain Catalog/Federation/Knowledge, domain-rule intake, simulation, approval, publication, diagnostics, and materialization lifecycle.
praxis-rules-engine owns runtime-neutral RuleSet/snapshot contracts, deterministic planning and evaluation; Config Starter owns their governed snapshot store/head, while the quickstart owns only the executable host registry and activation adapter.
praxis-ui-angular consumes materialized contracts and decisions; it must not become an alternative owner of backend semantics.
- The quickstart proves all of the above with real resources, HTTP contracts, and focused tests.
If a metadata or config behavior is missing, reproduce it with the pilot, fix it in the responsible starter, and keep the quickstart change as a minimal downstream proof. Do not add host-local endpoint aliases, schema patches, decision engines, or UI conventions to hide a platform gap.
ApiPaths Is An Identity Ledger
ApiPaths is a public synchronization point, not a string helper. A path or lookup-source change must be audited as one identity change across:
@ApiResource(value, resourceKey) and OpenAPI group resolution.
- Controller mappings, resource base behavior,
_links, and schema operation URLs.
@UISchema(endpoint=...), filter DTOs, option-source descriptors, filter/by-ids endpoints, and dependency maps.
- Related-resource/surface/action references, stats/export endpoints, test fixtures, HTTP scripts, and cockpit documentation.
- Existing external consumers and the breaking-change plan.
Prefer the existing ApiPaths constant everywhere. Do not construct an equivalent URL in a DTO, service, test, documentation script, or frontend consumer. A resource key is the stable semantic identity; a label or path fragment is not a substitute for it.
Build A Resource As A Complete Contract
For a mutable pilot, use the resource-oriented baseline: AbstractResourceController, AbstractBaseResourceService, ResourceMapper, and RestApiResponse. For read-only analytics/views, use the read-only counterpart. Keep the controller, service, mapper, response ID, filter, and test evidence aligned.
For each resource, verify:
- a stable
@ApiResource(resourceKey=...), canonical ApiPaths path, and correct @ApiGroup;
- operation-specific create, update, response, filter, action, and stats schemas resolve through
/schemas/filtered rather than a host map;
- DTO
@Schema(description=...) explains business meaning, boundary, relationship, or lifecycle in the context of that operation;
@UISchema publishes presentation/control behavior only; it does not redefine business or governance meaning;
- filters express query semantics and option-source dependencies, rather than being create DTOs with a few fields removed;
- resource identity,
_links, capabilities, export, and stats remain inherited from the canonical resource base where applicable.
Never use a generic PATCH or ordinary CRUD update to conceal an explicit business transition. A command such as approval, triage, activation, custody resolution, cancellation, or payment must be a documented workflow action with its own request/response schema, state checks, outcome, and discovery metadata.
For a real collection-level command that has no queryable or persisted collection, extend the metadata starter's AbstractCollectionCommandResourceController. Publish the action, capabilities, schemas, and governed command response without fabricating a repository, query service, CRUD endpoints, or decorative surface. Move that pilot to the resource-oriented persistent baseline only when the domain gains real item identity, persistence, and read operations; update host proof, discovery evidence, and consumers in the same change.
When that persistent resource has a mutable lifecycle but ordinary CRUD would bypass its business states, use the read-only resource baseline for query/filter/stats and publish every mutation as an explicit workflow action. Publish item GET and action ETags from the version captured with the returned representation, not a later getResourceVersion query. Require If-Match on item commands, but check for a completed idempotent replay before rejecting a now-stale ETag: a retry of an already committed command must return the original result without repeating the transition.
For the quickstart's mission team pilot, inspect operations/service/MissionTeamConcurrency, MissionTeamRules, MissaoService#planTeam, and MissaoParticipanteService together. The current/proposed employee union, missions, and participants share one sorted lock order across planning, item/batch CRUD, mission lifecycle, and employee deletion. Every non-empty team must retain exactly one leader in every status; planning status determines when composition may change. Historical team composition or removal, participant reparenting, and status changes through ordinary CRUD are denied; they are not alternate workflow routes. A result may be updated or cleared only in a terminal mission, after validating the current team and reference. A retained-reference swap may defer only the named team uniqueness constraint inside the protected planTeam transaction, then flush and restore immediate checking before return. This is domain integrity, not P3 bulk admission or a new authority grant.
For the host-owned mission leadership index, inspect
db/operational-migrations/V20261003_001__mission_team_leader_uniqueness.sql,
config/OperationalDatasourceMigrator, and
scripts/ApiOperationalSchemaDriftCheck.java together. Use the deploy-time migration
identity and packaged operational lane; do not grant runtime DDL or apply it on startup.
The migration holds SHARE ROW EXCLUSIVE before data/catalog reads, then creates a
missing index or validates the exact existing ux_miss_part_principal_por_missao.
Require immediate valid/ready/live unique btree, one nonnull int32 missao_id key,
pg_catalog.int4_ops, default collation/options, no INCLUDE/expression, and the
canonical principal IS TRUE predicate. A namesake alone does not prove integrity.
Duplicate leaders or mismatched topology must abort without rewriting data or
silently replacing an object. Diagnose and remediate through the approved maintenance
procedure before retry; migration rollback must also roll back newly created DDL.
The index guarantees at most one leader, while MissionTeamRules requires exactly
one in each nonempty final team. Do not defer the partial index to make a collective
swap pass; validate immutable before/after candidates and stage the writer under the
existing team locks. Candidate preparation is not proof of ATOMIC domain/receipt
execution or HTTP availability. Prove the packaged lane and the actual drift checker
with MissionTeamLeaderUniquenessPostgresTest and
OperationalDatasourceMigratorPostgresTest, including a concurrent writer blocked
until the migration commits, incompatible objects preserved, both bootstrap modes,
and a second migration run that changes nothing. For collective update-only staging,
inspect MissaoParticipanteService's prepared-set path and the shared
MissionTeamReferenceConstraint with MissaoService#planTeam. Validate every
selected preimage/version and every complete final team before the first write.
Prove the retained JPA graph shares the kernel's actual JDBC connection; an active
JPA transaction alone is insufficient. Bind the transient prepared set to
pg_current_xact_id()::text on that connection and reject reuse in a later
transaction, even when the connection and EntityManager are reused. Verify that
every selected entity belongs to the service persistence context that will flush;
ownership by the retained graph alone is insufficient. Recheck every managed preimage/version
before the first mutation and reject a different physical connection with zero
writes. Reject prepared-state reuse after any apply attempt, including an all-no-op
set or an intermediate failure; preserve unchanged members and no-op versions. Apply the complete final state of outgoing
leaders before the first flush, then other selected final states; defer only the
reference constraint and restore IMMEDIATE before return. All stages share the
caller's transaction and live budget; never create a transaction per member or
commit inside this writer. Prove this domain boundary with PostgreSQL/JPA staging
tests; those do not certify the later domain/receipt/HTTP ATOMIC composition. Validate global selection
cardinality, duplicate targets and ordinals before mapping or partitioning in the
coordinator; a map alone cannot certify those original inputs. Use
praxis-api-quickstart-operational-proof for the wider host/starter adoption gate.
Scope an idempotency key by resource key, collection/item target, action and authenticated actor, and fingerprint the complete command. Persist the domain mutation, append-only transition/effect ledger and completed idempotent response in one operational transaction; a committed mutation without a replayable result is not an acceptable corporate proof. A batch that promises partial success must declare itself non-atomic, preserve input order and run each item in its own transaction. If an effect leaves the operational database, replace direct remote execution with a transactional outbox and an idempotent consumer; same-database ledgers prove local atomicity only.
Metadata, Governance, And Lookup
Use the published contract rather than local UI knowledge:
@Schema states business semantics; it is not a duplicate of a screen label or Java type.
@UISchema declares UI behavior such as control type, endpoint, read-only, formatting, or field mechanics.
@DomainGovernance and the semantic domain catalog express privacy, compliance, AI-use, visibility, and governance context. UI hints do not enforce security or replace this meaning.
- Register option sources in
OptionSourceConfig and publish a descriptor for every declared source.
- Use
RESOURCE_ENTITY with canonical source key, resource path, value/display fields, dependencies, filter endpoint, by-ids reload behavior, selection policy, and entity-lookup capability metadata when a relation points at a Praxis resource.
- Use a provider-backed option source only when the source truly is not a resource entity; do not build a separate autocomplete endpoint.
When a lookup crosses domains, prove the chain from the consuming field's x-ui.optionSource through its source key, source resource, filter/by-ids endpoints, dependency filters, selected-value reload, and authorization behavior. The ResourceEntityLookupGovernanceIntegrationTest pattern is the reference inventory, not an optional UI enhancement.
For a dependent RESOURCE_ENTITY or governed option-source pilot, schema presence is not enough. Prove the runtime contract that removes cognitive load from consumers:
/schemas/filtered must publish type, key, entityKey, resourcePath, filterEndpoint, byIdsEndpoint, dependsOn, dependencyFilterMap, selectedReloadPolicy, invalidSortPolicy, capability flags, and selection policy from the canonical descriptor.
dependencyFilterMap is backend x-ui.optionSource grounding: it maps observed schema fields to backend filter payload names. Do not replace it with Angular metadata-editor cascade patches or local field-name translations in the consumer.
- The filter endpoint must accept the mapped dependency payload and return selectable/disabled metadata, including code/status/description/disabled reason when the descriptor declares those semantics.
- The by-ids endpoint must rehydrate existing values, preserve requested order, and return invalid/non-selectable rows with enough metadata for the runtime to retain or reject according to policy.
- If a pilot uses provider-backed options instead of
RESOURCE_ENTITY, still prove filterEndpoint, byIdsEndpoint, selected reload, invalid sort, dependencies, and lightweight OptionDTO{id,label} behavior, while making clear that it does not publish rich entity lookup metadata.
Use ProcurementEntityLookupPilotIntegrationTest for dependent supplier/contract/product lookup proof, VwStatsSmokeHttpTest and VwAnalyticsFolhaPagamentoServiceStatsTest for dependencyFilterMap on analytical option sources, and ProcurementExternalOptionSourceProviderIntegrationTest for provider-backed dependency and reload policies. This distinction is especially important in migrations such as Ergon: Praxis should publish the canonical lookup and reload contract so migrators do not hand-code cascade, rehydration, or invalid-selection decisions per screen.
Do not decide a resource, field, lookup, action, relation, or domain intent from labels, aliases, regexes, routes, or fuzzy matching as the primary mechanism. Resolve semantic scope through resource keys, schemas, governed catalogs, actions, capabilities, and declared tools. Textual matching can only rank candidates after that scope is known.
Actions, Surfaces, And Decision Materializations
@WorkflowAction publishes a business command; @UiSurface publishes a composed business experience. Both must say what decision or journey is supported, which resource/action contract it uses, and how a runtime can discover it. Do not create decorative surfaces or labels that have no executable contract.
For a workflow action, check action id, scope, allowed states, request/response schema, HTTP status semantics, success/failure result, HATEOAS schema links when the controller exposes them, action catalog, capabilities, and negative-path test. Collection actions such as payroll bulk approval must preserve per-item outcomes instead of pretending that every transition is atomic.
When a pilot consumes a shared domain decision:
- Resolve the domain and target through metadata/catalog grounding before authoring a rule.
- Treat Domain Rule/Domain Knowledge definitions, evidence, simulation, approval, publication, diagnostics, statuses, source hashes, and materialization outcomes as config-starter contracts.
- Consume only an applied materialization in the host, such as procurement supplier selection eligibility, backend validation, or workflow-action policy.
- Keep the host enforcement narrow and deterministic; it must not recreate authoring, publication, status transitions, or policy inference locally.
- Prove a published materialization changes runtime behavior, including the relevant rejected state, without presenting simulation as business-data execution.
When a pilot demonstrates shadow or dual-run operation, keep it host-owned and
strictly non-authoritative. The baseline must be independent of the candidate:
it cannot copy the candidate result, read its snapshot payload, or use a
persisted candidate outcome as its oracle. Freeze facts, nowUtc, timezone and
resolved actor context once, then run both sides with isolated, bounded timeout,
concurrency and saturation behavior. Classify MATCH, MISMATCH,
INCONCLUSIVE and TECHNICAL_ERROR without converting failures into business
denials. A shadow path must not use mutation/idempotency ledgers, advance a
lifecycle, skip the approved baseline route, or execute an EffectIntent. Publish
only allowlisted observations and low-cardinality metrics; never tag or log
facts, request references, actors, amounts, exception messages, secrets, or
snapshot payloads. Unit/integration proof establishes only Shadow Implemented;
live baseline evidence is required for Shadow Running or Shadow Passed.
For operational validation and workflow pilots, inspect Config's OperationalPolicyService,
OperationalPolicyResolution and the host's OperationalPolicyGate. Consult the exact
canonical target mandatorily. Preserve all four states: a proved NEVER_APPLIED permits
continuation only when that caller explicitly declares ALLOW_IF_NEVER_APPLIED;
ELIGIBLE_APPLIED_HEAD supplies the validated policy; withdrawn, inconsistent, missing
infrastructure or failed reads deny operational continuation. ALLOW only clears this gate,
never authority, scope, version or domain invariants. Retain the resolution fingerprint for
capture and later rechecks. DomainRuleBackendValidationPolicyResolver and
DomainRuleWorkflowActionPolicyResolver use this typed gate; do not teach a generic
latest-or-empty fallback. Interpret a specialized BLOCK only through its actual supported
governed domain evaluator; unknown or unsupported semantics fail closed, without borrowing
another pilot's resolver or treating it as initial absence.
DomainRuleOptionSourcePolicyResolver retains a separate optional lookup projection through
DomainRuleService. Its empty result is not operational mutation authorization or proof that
a rule never existed. Do not synthesize fallback rules from labels, prompts, demo data, Java
defaults or migration assumptions, and do not generalize lookup absence to operational gates.
The quickstart may demonstrate a materialization, but no pilot may route rules through command words, local keyword rules, or copied assistant text. Governed semantic resolution remains the primary path.
Governed RuleSet Parameters And Publication
For a parameterizable domain decision, inspect the host's DecisionSlot.parameterTemplate,
Config's approved source definition and snapshot composition service, and the Engine's
RuleParameterResolver before changing a JSON Logic condition. The product-owned template
declares the expression, allowed scalar paths, bounds, units, required facts and false outcome;
the host may offer declared values, not a customer-supplied executable or a second copy of
those outcomes. Persist the template in definition.parameterTemplate and declared values in
parameters.parameterValues; derive the persisted condition on the server. A draft condition,
when supplied, must match that derivation. Composition must compare the source template to
the host slot and retain only the exact template reference and values in a
CUSTOMER/PARAMETERIZE binding. Reject unknown, null or out-of-range values and attempts to
replace facts, operators or outcome semantics.
For the next immutable RuleSet version, query Config's maximum in the exact tenant,
environment and RuleSet scope, then add one with checked arithmetic. The selected head,
publication order and a page of the version catalog do not establish that maximum. This read
does not reserve a version: a concurrent publisher must still meet Config's atomic uniqueness
and precondition checks, without silent retry under a different digest. Publishing stores
immutable content only; it neither selects nor bootstraps the active head. Head selection
requires the separate governed operator rollout, host preload/admission and explicit
activation with the current head ETag or verified head absence.
Use ExtraordinaryGrantRuleSetFactory, PolicyStudioSandboxRuleSetMaterializer,
PolicyStudioRuleSetCompositionService, PolicyStudioRuleParameterizationTest and
PolicyStudioRuleSetCompositionServiceTest as the Quickstart source/proof slice at
e6bf30fa (Config rc.166 and Engine beta.17 public coordinates). Check the current POM
and run focused tests for derived values, unchanged facts, template mismatch, scoped maximum,
and publication without activation; prove remote operational adoption separately. Source
tests or historical SNAPSHOT rehearsals do not certify a public release or full gate.
Governed Snapshot Consumption
When a pilot consumes an active runtime snapshot, keep it as a downstream data-plane proof:
- Load only the configured tenant, environment, owner, RuleSet and host-contract identity from the Config Starter head/read boundary.
- Revalidate immutable content hash, validity interval and strictly monotonic activation revision. Cache hits may use the same head ETag; stale or reordered activations must be rejected.
- Compile the complete candidate with the host's executable Java registry before exposing it. The authoring/config boundary uses only planning coordinates and must never receive host executor instances.
- Swap the compiled plan atomically. Network failure, invalid content, incompatibility or missing executor preserves the last-known-good; do not rebuild a bootstrap-local fallback as a parallel authority.
- Prove rollback v1 → v2 → v1: v1's content hash repeats, but the opaque head ETag and activation revision must advance so ABA is rejected.
- Make polling/startup loading operationally opt-in where the host profile does not provide the snapshot tables. Publish health as unavailable/out-of-service until an effective plan exists, without leaking snapshot payloads, facts or approval evidence.
Candidate prewarm must cover every affected RuleSet family, using the same host-owned registry and admission verifier as active loading. A candidate job reads immutable published content by key/hash, reports real probes and never reads it through an active-head fallback, mutates the head, or installs candidate content as last-known-good. Keep preload execution isolated from Spring startup side effects, schedulers and business mutation; use the official host job/script and authenticated Config transport.
For a runtime contract upgrade, retain legitimate old publications and approvals unchanged, author and approve new compatible compositions, publish candidates without selection, prewarm each family, then activate through rollout quorum and strong conditional selection. Prove partial family activation and recovery under the documented maintenance boundary, same-line rollback, and rejection of the incompatible historical version. A synthetic JSON version rewrite or fabricated probe is not migration evidence. Resolve exact officially published engine, Config, Contracts and Metadata coordinates before final host acceptance; candidate packages and isolated source tests remain preliminary.
After each candidate A/B activation and same-line rollback, exercise an existing non-persisting consumer operation and verify the official host observation against the selected scope, snapshot key, content hash and activation identity. A positive candidate probe or Config READY state does not prove active host adoption or establish LKG.
The loader changes which governed plan is evaluated; it does not authorize business effects. Keep business endpoints, persistence, idempotency, shadow, effect execution and authority behind their own pilot gates.
For Reactive Determination pilots, resolve the complete active snapshot as one
compatible unit, validate tenant/scope/content/head identity, atomically retain
last-known-good on an invalid candidate, and expose only sanitized health. Prove
the operation-specific Metadata projection and Angular/HTTP consumer rather than
embedding the formula in the demo controller.
For the private ATOMIC mission kernel consumer, preserve the public PER_ITEM adapter.
Resolve the two adapters through the concrete shared canonical contract resolver,
with their own Metadata bindings and explicit expected atomicity; never reinterpret
a PER_ITEM proposal as an ATOMIC photograph. The canonical profile already validates
SYNC/EXPLICIT and hard request/deadline ceilings; enforce the contextual ATOMIC limit
of 50 before protected capture and before maps or team partitioning. Retain one
decoded ordered input together with the transient prepared updates for the callback
attempt. Recheck the whole grant, policy, facts, versions and collective candidates
under one G→E→M→P fence, physical connection and live set budget. Outcome ordinals
come from the original kernel units, not sorted domain IDs.
Read detailed admission reasons from the immutable atomic rejection record. The
execution terminal is aggregated as UNIT_ROLLED_BACK except deadline; a policy BLOCK
must preserve POLICY_BLOCKED in the detailed rejection, while domain dependency
conflicts retain their own reason. Prove real last-write rollback, zero domain/header/
child prefix and receipt-first replay without admission/mutation reentry after grant
or policy changes. Inject the same transaction-bound EntityManager into both graph
and domain service in isolated JPA fixtures; a manually constructed service does not
receive production injection automatically. A test-only compiled MVC binding with
mocked OpenAPI resolution proves only kernel consumption. It does not certify
producer grounding, lifecycle, HTTP, composer or READY. Keep these gates closed
until their concrete consumer proofs and exact public artifact adoption are complete.
Recover a genuinely reserved RUNNING execution through the canonical SDK: require
STOPPED/RECOVERY_STOPPED, an advanced owner epoch, FENCED for the old control and zero
admission/mutation callbacks or domain/evidence writes. Do not fabricate ledger state
with SQL. This proves neither in-flight nor uncertain-commit recovery; in-flight
recovery must respect the SDK unit deadline. Include effect references only for real
durable effects committed in the same transaction; never invent an outbox.
Persistence And Demo Data
Operational migrations and deterministic demo data support proof; they do not define canonical platform semantics. Preserve resource relationships, lifecycle states, and representative data needed for filters, lookups, actions, analytics, governance, and negative paths. Update docs/DEMO-DATABASE.md when the operational model or seed assumptions change.
Do not make a test only pass by changing production-like seed data without proving the contract it represents. Keep sensitive business data fictional and respect published governance/visibility restrictions in fixtures, exports, and docs.
Before enriching demo data, inspect live triggers/functions and derived views as
well as DTOs, services and determination rules. A field can have different meanings
in a trigger and the published form contract; prove the small arithmetic example
in an isolated branch before normalizing existing totals. If they disagree, retain
the failed transaction/readback and open the canonical owner follow-up. Do not
silently disable triggers or overwrite their results to make an import pass.
A seed compatible with the current database does not certify API create/update,
approval or payment. Preserve existing lifecycle versions and receipts; distinguish
imported synthetic status and future projections from executed business actions.
Adherence Inventory
Before adding a path, DTO field, endpoint, filter, option source, stat, export, action, surface, migration, or domain materialization, 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 contract. State the missing behavior, canonical owner, impacted consumers, derived artifacts, and minimum proof. In particular, inspect whether existing schema, action, capability, option-source, domain-governance, decision diagnostic, or materialization data simply is not being materialized well by the cockpit or Angular runtime.
Proof Matrix And Validation
Choose the smallest focused proof that covers the changed contract:
| Changed behavior |
Minimum local proof |
| resource identity, schema, groups, actions |
mvn "-Dtest=QuickstartMetadataMigrationIntegrationTest,EventosFolhaPilotIntegrationTest,OpenApiGroupResolutionIsolatedIntegrationTest" test |
| cross-domain entity lookup/option-source contract |
mvn "-Dtest=FuncionarioEntityLookupIntegrationTest,ResourceEntityLookupGovernanceIntegrationTest" test |
dependent RESOURCE_ENTITY lookup |
mvn "-Dtest=ProcurementEntityLookupPilotIntegrationTest,ResourceEntityLookupGovernanceIntegrationTest" test plus the affected pilot test |
| dependent provider-backed option source |
mvn "-Dtest=ProcurementExternalOptionSourceProviderIntegrationTest" test plus the affected pilot test |
| analytical option-source dependency mapping |
mvn "-Dtest=StatsSchemaSmokeHttpTest,VwStatsSmokeHttpTest,VwAnalyticsFolhaPagamentoServiceStatsTest" test |
| stats, analytics, or export |
mvn "-Dtest=StatsSchemaSmokeHttpTest,FuncionarioExportSmokeHttpTest" test plus the affected pilot test |
| Domain Knowledge/config host wiring |
mvn "-Dtest=DomainKnowledgeProjectionWiringIntegrationTest" test; use the config-starter smoke for authoring/publication lifecycle |
| governed snapshot loader/hot reload |
focused runtime/health tests proving scope, hash, compatibility, monotonic activation, atomic last-known-good, invalid-candidate rejection and v1 → v2 → v1 rollback; then package/verify against released engine and Config Starter coordinates |
| persistent action lifecycle |
focused HTTP proof for read-only query, contextual capabilities, ETag 428/412, replay before stale ETag, actor/item-scoped idempotency, state transition, atomic ledger rollback and exactly-once effect; add mixed ordered batch proof when partial success is supported |
| one pilot implementation |
its focused *PilotIntegrationTest plus any directly affected lookup/action/stats/export proof |
ApiPaths or cross-domain public identity |
focused proofs above and cockpit verification scripts; use mvn test only if those cannot cover the resulting identity graph |
For public cockpit evidence, run the relevant documented script, such as scripts/verify-cockpit-inventory-doc.sh, scripts/verify-cockpit-action-contracts.sh, scripts/verify-cockpit-surface-contracts.sh, scripts/verify-cockpit-related-resource-contracts.sh, scripts/verify-cockpit-analytics-contracts.sh, scripts/verify-cockpit-option-source-contracts.sh, or scripts/verify-cockpit-structural-ui-contracts.sh.
Review README.md, docs/DEMO-DATABASE.md, docs/COCKPIT-QUICKSTART-REFERENCE.md, relevant quickstart scripts, public landing docs, and executable HTTP examples when behavior is published. State explicitly when no derived artifact changes.
Companion Skills
praxis-reactive-determinations: metadata, host resolver, Angular runtime, and corpus proof.
Use praxis-api-quickstart-operational-proof for host/starter ownership, dependency versions, and host validation.
Use praxis-api-quickstart-cockpit-http-validation for cockpit docs, HTTP scripts, and published proof.
Use praxis-metadata-resource-baseline for resource controller/service/HATEOAS behavior.
Use praxis-metadata-schema-contracts for /schemas/filtered, operation resolution, x-ui, ETag, and schema headers.
Use praxis-metadata-discovery-capabilities for surfaces, actions, capabilities, availability, stats, export, and _links discovery.
Use praxis-metadata-domain-option-sources for @DomainGovernance, semantic domain catalog, option-source, and lookup contracts.
Use praxis-config-domain-decisions for governed domain rules, Domain Knowledge, publications, and runtime materializations.
1---2name: praxis-api-quickstart-domain-pilots3description: "Use when Codex must implement, audit, or extend Praxis API Quickstart pilot domains: ApiPaths, resource-oriented controllers and services, DTO/filter meaning, @UISchema, @DomainGovernance, option sources and entity lookup, stats/export, surfaces/actions, demo data, operational migrations, cockpit evidence, or governed domain-decision materializations across HR, operations, assets, procurement, and risk intelligence."4metadata:5 source: https://skillmd.com/skills/codexrodrigues/praxis-api-quickstart-domain-pilots6---78# Praxis API Quickstart Domain Pilots910Use this skill when a concrete quickstart domain must prove a Praxis capability in a real Spring Boot host. A pilot is not a disposable CRUD example: it is executable, didactic evidence that semantic grounding, metadata, discovery, governed decisions, and runtime behavior agree end to end.1112## Classify And Map Impact1314Classify a change before editing:1516- `local-pequena`: one host resource, with no public contract change.17- `transversal`: a pilot plus another quickstart domain, docs, HTTP evidence, or a runtime consumer.18- `contrato-publico`: `ApiPaths`, `@ApiResource`, OpenAPI groups, schemas, option-source endpoints, `_links`, actions, surfaces, capabilities, stats, or export behavior changes.19- `arquitetural`: ownership or lifecycle crosses the quickstart, metadata starter, config starter, or Angular runtime.2021For `transversal`, `contrato-publico`, or `arquitetural`, map the canonical owner, affected resource keys and paths, consumers, cockpit/docs/HTTP evidence, focused tests, and breaking-change risk before patching.2223## Source Audit2425Read the host and the exact pilot before deciding that it needs a new contract:2627- `praxis-api-quickstart/AGENTS.md`28- `src/main/java/com/example/praxis/apiquickstart/constants/ApiPaths.java`29- `src/main/java/com/example/praxis/apiquickstart/config/OptionSourceConfig.java`30- the affected `controller`, `service`, `dto`, `dto/filter`, `dto/actions`, `mapper`, `entity`, and repository31- `db/operational-migrations/**` and `docs/DEMO-DATABASE.md` when persistence or seed data changes32- `docs/SEMANTIC-DOMAIN-CATALOG-CONTRACT.md`33- `docs/COCKPIT-QUICKSTART-REFERENCE.md` and its verification scripts when a published pilot contract changes34- focused integration tests in `src/test/java/com/example/praxis/apiquickstart/**`3536The current reference families are intentionally complementary:3738| Pilot family | Primary proof |39| --- | --- |40| Human resources | resource CRUD, payroll workflow, privacy/governance, export, and people lookup |41| Operations | explicit lifecycle actions, cross-domain relationships, mission and incident workflows |42| Assets | custody, readiness, allocation, fleet/missions, and analytics |43| Procurement | governed entity lookup, supplier eligibility, contract/product/order lifecycle, and config decision materialization |44| Risk intelligence | threat lookup, triage actions, derived incident analytics, and chart-ready stats |4546Do not copy one pilot mechanically into another. Start with the business question, existing resource keys, published schemas, capability/action catalogs, and decision evidence.4748## Canonical Ownership4950The quickstart owns concrete example resources, host composition, paths, demo persistence, security exposure, and downstream proof. It is not the source of canonical platform semantics.5152- `praxis-metadata-starter` owns `x-ui`, `/schemas/filtered`, schema resolution and headers, surfaces, actions, capabilities, HATEOAS, resource bases, option-source runtime contracts, and metadata discovery.53- `praxis-config-starter` owns governed Domain Catalog/Federation/Knowledge, domain-rule intake, simulation, approval, publication, diagnostics, and materialization lifecycle.54- `praxis-rules-engine` owns runtime-neutral RuleSet/snapshot contracts, deterministic planning and evaluation; Config Starter owns their governed snapshot store/head, while the quickstart owns only the executable host registry and activation adapter.55- `praxis-ui-angular` consumes materialized contracts and decisions; it must not become an alternative owner of backend semantics.56- The quickstart proves all of the above with real resources, HTTP contracts, and focused tests.5758If a metadata or config behavior is missing, reproduce it with the pilot, fix it in the responsible starter, and keep the quickstart change as a minimal downstream proof. Do not add host-local endpoint aliases, schema patches, decision engines, or UI conventions to hide a platform gap.5960## ApiPaths Is An Identity Ledger6162`ApiPaths` is a public synchronization point, not a string helper. A path or lookup-source change must be audited as one identity change across:63641. `@ApiResource(value, resourceKey)` and OpenAPI group resolution.652. Controller mappings, resource base behavior, `_links`, and schema operation URLs.663. `@UISchema(endpoint=...)`, filter DTOs, option-source descriptors, filter/by-ids endpoints, and dependency maps.674. Related-resource/surface/action references, stats/export endpoints, test fixtures, HTTP scripts, and cockpit documentation.685. Existing external consumers and the breaking-change plan.6970Prefer the existing `ApiPaths` constant everywhere. Do not construct an equivalent URL in a DTO, service, test, documentation script, or frontend consumer. A resource key is the stable semantic identity; a label or path fragment is not a substitute for it.7172## Build A Resource As A Complete Contract7374For a mutable pilot, use the resource-oriented baseline: `AbstractResourceController`, `AbstractBaseResourceService`, `ResourceMapper`, and `RestApiResponse`. For read-only analytics/views, use the read-only counterpart. Keep the controller, service, mapper, response ID, filter, and test evidence aligned.7576For each resource, verify:7778- a stable `@ApiResource(resourceKey=...)`, canonical `ApiPaths` path, and correct `@ApiGroup`;79- operation-specific create, update, response, filter, action, and stats schemas resolve through `/schemas/filtered` rather than a host map;80- DTO `@Schema(description=...)` explains business meaning, boundary, relationship, or lifecycle in the context of that operation;81- `@UISchema` publishes presentation/control behavior only; it does not redefine business or governance meaning;82- filters express query semantics and option-source dependencies, rather than being create DTOs with a few fields removed;83- resource identity, `_links`, capabilities, export, and stats remain inherited from the canonical resource base where applicable.8485Never use a generic PATCH or ordinary CRUD update to conceal an explicit business transition. A command such as approval, triage, activation, custody resolution, cancellation, or payment must be a documented workflow action with its own request/response schema, state checks, outcome, and discovery metadata.8687For a real collection-level command that has no queryable or persisted collection, extend the metadata starter's `AbstractCollectionCommandResourceController`. Publish the action, capabilities, schemas, and governed command response without fabricating a repository, query service, CRUD endpoints, or decorative surface. Move that pilot to the resource-oriented persistent baseline only when the domain gains real item identity, persistence, and read operations; update host proof, discovery evidence, and consumers in the same change.8889When that persistent resource has a mutable lifecycle but ordinary CRUD would bypass its business states, use the read-only resource baseline for query/filter/stats and publish every mutation as an explicit workflow action. Publish item GET and action ETags from the version captured with the returned representation, not a later `getResourceVersion` query. Require `If-Match` on item commands, but check for a completed idempotent replay before rejecting a now-stale ETag: a retry of an already committed command must return the original result without repeating the transition.9091For the quickstart's mission team pilot, inspect `operations/service/MissionTeamConcurrency`, `MissionTeamRules`, `MissaoService#planTeam`, and `MissaoParticipanteService` together. The current/proposed employee union, missions, and participants share one sorted lock order across planning, item/batch CRUD, mission lifecycle, and employee deletion. Every non-empty team must retain exactly one leader in every status; planning status determines when composition may change. Historical team composition or removal, participant reparenting, and status changes through ordinary CRUD are denied; they are not alternate workflow routes. A result may be updated or cleared only in a terminal mission, after validating the current team and reference. A retained-reference swap may defer only the named team uniqueness constraint inside the protected `planTeam` transaction, then flush and restore immediate checking before return. This is domain integrity, not P3 bulk admission or a new authority grant.929394For the host-owned mission leadership index, inspect95`db/operational-migrations/V20261003_001__mission_team_leader_uniqueness.sql`,96`config/OperationalDatasourceMigrator`, and97`scripts/ApiOperationalSchemaDriftCheck.java` together. Use the deploy-time migration98identity and packaged operational lane; do not grant runtime DDL or apply it on startup.99The migration holds `SHARE ROW EXCLUSIVE` before data/catalog reads, then creates a100missing index or validates the exact existing `ux_miss_part_principal_por_missao`.101Require immediate valid/ready/live unique btree, one nonnull int32 `missao_id` key,102`pg_catalog.int4_ops`, default collation/options, no INCLUDE/expression, and the103canonical `principal IS TRUE` predicate. A namesake alone does not prove integrity.104Duplicate leaders or mismatched topology must abort without rewriting data or105silently replacing an object. Diagnose and remediate through the approved maintenance106procedure before retry; migration rollback must also roll back newly created DDL.107The index guarantees at most one leader, while `MissionTeamRules` requires exactly108one in each nonempty final team. Do not defer the partial index to make a collective109swap pass; validate immutable before/after candidates and stage the writer under the110existing team locks. Candidate preparation is not proof of ATOMIC domain/receipt111execution or HTTP availability. Prove the packaged lane and the actual drift checker112with `MissionTeamLeaderUniquenessPostgresTest` and113`OperationalDatasourceMigratorPostgresTest`, including a concurrent writer blocked114until the migration commits, incompatible objects preserved, both bootstrap modes,115and a second migration run that changes nothing. For collective update-only staging,116inspect `MissaoParticipanteService`'s prepared-set path and the shared117`MissionTeamReferenceConstraint` with `MissaoService#planTeam`. Validate every118selected preimage/version and every complete final team before the first write.119Prove the retained JPA graph shares the kernel's actual JDBC connection; an active120JPA transaction alone is insufficient. Bind the transient prepared set to121`pg_current_xact_id()::text` on that connection and reject reuse in a later122transaction, even when the connection and EntityManager are reused. Verify that123every selected entity belongs to the service persistence context that will flush;124ownership by the retained graph alone is insufficient. Recheck every managed preimage/version125before the first mutation and reject a different physical connection with zero126writes. Reject prepared-state reuse after any apply attempt, including an all-no-op127set or an intermediate failure; preserve unchanged members and no-op versions. Apply the complete final state of outgoing128leaders before the first flush, then other selected final states; defer only the129reference constraint and restore IMMEDIATE before return. All stages share the130caller's transaction and live budget; never create a transaction per member or131commit inside this writer. Prove this domain boundary with PostgreSQL/JPA staging132tests; those do not certify the later domain/receipt/HTTP ATOMIC composition. Validate global selection133cardinality, duplicate targets and ordinals before mapping or partitioning in the134coordinator; a map alone cannot certify those original inputs. Use135`praxis-api-quickstart-operational-proof` for the wider host/starter adoption gate.136137Scope an idempotency key by resource key, collection/item target, action and authenticated actor, and fingerprint the complete command. Persist the domain mutation, append-only transition/effect ledger and completed idempotent response in one operational transaction; a committed mutation without a replayable result is not an acceptable corporate proof. A batch that promises partial success must declare itself non-atomic, preserve input order and run each item in its own transaction. If an effect leaves the operational database, replace direct remote execution with a transactional outbox and an idempotent consumer; same-database ledgers prove local atomicity only.138139## Metadata, Governance, And Lookup140141Use the published contract rather than local UI knowledge:142143- `@Schema` states business semantics; it is not a duplicate of a screen label or Java type.144- `@UISchema` declares UI behavior such as control type, endpoint, read-only, formatting, or field mechanics.145- `@DomainGovernance` and the semantic domain catalog express privacy, compliance, AI-use, visibility, and governance context. UI hints do not enforce security or replace this meaning.146- Register option sources in `OptionSourceConfig` and publish a descriptor for every declared source.147- Use `RESOURCE_ENTITY` with canonical source key, resource path, value/display fields, dependencies, filter endpoint, by-ids reload behavior, selection policy, and entity-lookup capability metadata when a relation points at a Praxis resource.148- Use a provider-backed option source only when the source truly is not a resource entity; do not build a separate autocomplete endpoint.149150When a lookup crosses domains, prove the chain from the consuming field's `x-ui.optionSource` through its source key, source resource, filter/by-ids endpoints, dependency filters, selected-value reload, and authorization behavior. The `ResourceEntityLookupGovernanceIntegrationTest` pattern is the reference inventory, not an optional UI enhancement.151152For a dependent `RESOURCE_ENTITY` or governed option-source pilot, schema presence is not enough. Prove the runtime contract that removes cognitive load from consumers:153154- `/schemas/filtered` must publish `type`, `key`, `entityKey`, `resourcePath`, `filterEndpoint`, `byIdsEndpoint`, `dependsOn`, `dependencyFilterMap`, `selectedReloadPolicy`, `invalidSortPolicy`, capability flags, and selection policy from the canonical descriptor.155- `dependencyFilterMap` is backend `x-ui.optionSource` grounding: it maps observed schema fields to backend filter payload names. Do not replace it with Angular metadata-editor cascade patches or local field-name translations in the consumer.156- The filter endpoint must accept the mapped dependency payload and return selectable/disabled metadata, including code/status/description/disabled reason when the descriptor declares those semantics.157- The by-ids endpoint must rehydrate existing values, preserve requested order, and return invalid/non-selectable rows with enough metadata for the runtime to retain or reject according to policy.158- If a pilot uses provider-backed options instead of `RESOURCE_ENTITY`, still prove `filterEndpoint`, `byIdsEndpoint`, selected reload, invalid sort, dependencies, and lightweight `OptionDTO{id,label}` behavior, while making clear that it does not publish rich entity lookup metadata.159160Use `ProcurementEntityLookupPilotIntegrationTest` for dependent supplier/contract/product lookup proof, `VwStatsSmokeHttpTest` and `VwAnalyticsFolhaPagamentoServiceStatsTest` for `dependencyFilterMap` on analytical option sources, and `ProcurementExternalOptionSourceProviderIntegrationTest` for provider-backed dependency and reload policies. This distinction is especially important in migrations such as Ergon: Praxis should publish the canonical lookup and reload contract so migrators do not hand-code cascade, rehydration, or invalid-selection decisions per screen.161162Do not decide a resource, field, lookup, action, relation, or domain intent from labels, aliases, regexes, routes, or fuzzy matching as the primary mechanism. Resolve semantic scope through resource keys, schemas, governed catalogs, actions, capabilities, and declared tools. Textual matching can only rank candidates after that scope is known.163164## Actions, Surfaces, And Decision Materializations165166`@WorkflowAction` publishes a business command; `@UiSurface` publishes a composed business experience. Both must say what decision or journey is supported, which resource/action contract it uses, and how a runtime can discover it. Do not create decorative surfaces or labels that have no executable contract.167168For a workflow action, check action id, scope, allowed states, request/response schema, HTTP status semantics, success/failure result, HATEOAS schema links when the controller exposes them, action catalog, capabilities, and negative-path test. Collection actions such as payroll bulk approval must preserve per-item outcomes instead of pretending that every transition is atomic.169170When a pilot consumes a shared domain decision:1711721. Resolve the domain and target through metadata/catalog grounding before authoring a rule.1732. Treat Domain Rule/Domain Knowledge definitions, evidence, simulation, approval, publication, diagnostics, statuses, source hashes, and materialization outcomes as config-starter contracts.1743. Consume only an applied materialization in the host, such as procurement supplier selection eligibility, backend validation, or workflow-action policy.1754. Keep the host enforcement narrow and deterministic; it must not recreate authoring, publication, status transitions, or policy inference locally.1765. Prove a published materialization changes runtime behavior, including the relevant rejected state, without presenting simulation as business-data execution.177178When a pilot demonstrates shadow or dual-run operation, keep it host-owned and179strictly non-authoritative. The baseline must be independent of the candidate:180it cannot copy the candidate result, read its snapshot payload, or use a181persisted candidate outcome as its oracle. Freeze facts, `nowUtc`, timezone and182resolved actor context once, then run both sides with isolated, bounded timeout,183concurrency and saturation behavior. Classify `MATCH`, `MISMATCH`,184`INCONCLUSIVE` and `TECHNICAL_ERROR` without converting failures into business185denials. A shadow path must not use mutation/idempotency ledgers, advance a186lifecycle, skip the approved baseline route, or execute an EffectIntent. Publish187only allowlisted observations and low-cardinality metrics; never tag or log188facts, request references, actors, amounts, exception messages, secrets, or189snapshot payloads. Unit/integration proof establishes only `Shadow Implemented`;190live baseline evidence is required for `Shadow Running` or `Shadow Passed`.191192For operational validation and workflow pilots, inspect Config's `OperationalPolicyService`,193`OperationalPolicyResolution` and the host's `OperationalPolicyGate`. Consult the exact194canonical target mandatorily. Preserve all four states: a proved `NEVER_APPLIED` permits195continuation only when that caller explicitly declares `ALLOW_IF_NEVER_APPLIED`;196`ELIGIBLE_APPLIED_HEAD` supplies the validated policy; withdrawn, inconsistent, missing197infrastructure or failed reads deny operational continuation. ALLOW only clears this gate,198never authority, scope, version or domain invariants. Retain the resolution fingerprint for199capture and later rechecks. `DomainRuleBackendValidationPolicyResolver` and200`DomainRuleWorkflowActionPolicyResolver` use this typed gate; do not teach a generic201latest-or-empty fallback. Interpret a specialized BLOCK only through its actual supported202governed domain evaluator; unknown or unsupported semantics fail closed, without borrowing203another pilot's resolver or treating it as initial absence.204205`DomainRuleOptionSourcePolicyResolver` retains a separate optional lookup projection through206`DomainRuleService`. Its empty result is not operational mutation authorization or proof that207a rule never existed. Do not synthesize fallback rules from labels, prompts, demo data, Java208defaults or migration assumptions, and do not generalize lookup absence to operational gates.209210The quickstart may demonstrate a materialization, but no pilot may route rules through command words, local keyword rules, or copied assistant text. Governed semantic resolution remains the primary path.211212## Governed RuleSet Parameters And Publication213214For a parameterizable domain decision, inspect the host's `DecisionSlot.parameterTemplate`,215Config's approved source definition and snapshot composition service, and the Engine's216`RuleParameterResolver` before changing a JSON Logic condition. The product-owned template217declares the expression, allowed scalar paths, bounds, units, required facts and false outcome;218the host may offer declared values, not a customer-supplied executable or a second copy of219those outcomes. Persist the template in `definition.parameterTemplate` and declared values in220`parameters.parameterValues`; derive the persisted condition on the server. A draft condition,221when supplied, must match that derivation. Composition must compare the source template to222the host slot and retain only the exact template reference and values in a223`CUSTOMER/PARAMETERIZE` binding. Reject unknown, null or out-of-range values and attempts to224replace facts, operators or outcome semantics.225226For the next immutable RuleSet version, query Config's maximum in the exact tenant,227environment and RuleSet scope, then add one with checked arithmetic. The selected head,228publication order and a page of the version catalog do not establish that maximum. This read229does not reserve a version: a concurrent publisher must still meet Config's atomic uniqueness230and precondition checks, without silent retry under a different digest. Publishing stores231immutable content only; it neither selects nor bootstraps the active head. Head selection232requires the separate governed operator rollout, host preload/admission and explicit233activation with the current head ETag or verified head absence.234235Use `ExtraordinaryGrantRuleSetFactory`, `PolicyStudioSandboxRuleSetMaterializer`,236`PolicyStudioRuleSetCompositionService`, `PolicyStudioRuleParameterizationTest` and237`PolicyStudioRuleSetCompositionServiceTest` as the Quickstart source/proof slice at238`e6bf30fa` (Config rc.166 and Engine beta.17 public coordinates). Check the current POM239and run focused tests for derived values, unchanged facts, template mismatch, scoped maximum,240and publication without activation; prove remote operational adoption separately. Source241tests or historical SNAPSHOT rehearsals do not certify a public release or full gate.242243## Governed Snapshot Consumption244245When a pilot consumes an active runtime snapshot, keep it as a downstream data-plane proof:2462471. Load only the configured tenant, environment, owner, RuleSet and host-contract identity from the Config Starter head/read boundary.2482. Revalidate immutable content hash, validity interval and strictly monotonic activation revision. Cache hits may use the same head ETag; stale or reordered activations must be rejected.2493. Compile the complete candidate with the host's executable Java registry before exposing it. The authoring/config boundary uses only planning coordinates and must never receive host executor instances.2504. Swap the compiled plan atomically. Network failure, invalid content, incompatibility or missing executor preserves the last-known-good; do not rebuild a bootstrap-local fallback as a parallel authority.2515. Prove rollback v1 → v2 → v1: v1's content hash repeats, but the opaque head ETag and activation revision must advance so ABA is rejected.2526. Make polling/startup loading operationally opt-in where the host profile does not provide the snapshot tables. Publish health as unavailable/out-of-service until an effective plan exists, without leaking snapshot payloads, facts or approval evidence.253254Candidate prewarm must cover every affected RuleSet family, using the same host-owned registry and admission verifier as active loading. A candidate job reads immutable published content by key/hash, reports real probes and never reads it through an active-head fallback, mutates the head, or installs candidate content as last-known-good. Keep preload execution isolated from Spring startup side effects, schedulers and business mutation; use the official host job/script and authenticated Config transport.255256For a runtime contract upgrade, retain legitimate old publications and approvals unchanged, author and approve new compatible compositions, publish candidates without selection, prewarm each family, then activate through rollout quorum and strong conditional selection. Prove partial family activation and recovery under the documented maintenance boundary, same-line rollback, and rejection of the incompatible historical version. A synthetic JSON version rewrite or fabricated probe is not migration evidence. Resolve exact officially published engine, Config, Contracts and Metadata coordinates before final host acceptance; candidate packages and isolated source tests remain preliminary.257258After each candidate A/B activation and same-line rollback, exercise an existing non-persisting consumer operation and verify the official host observation against the selected scope, snapshot key, content hash and activation identity. A positive candidate probe or Config READY state does not prove active host adoption or establish LKG.259260The loader changes which governed plan is evaluated; it does not authorize business effects. Keep business endpoints, persistence, idempotency, shadow, effect execution and authority behind their own pilot gates.261262For Reactive Determination pilots, resolve the complete active snapshot as one263compatible unit, validate tenant/scope/content/head identity, atomically retain264last-known-good on an invalid candidate, and expose only sanitized health. Prove265the operation-specific Metadata projection and Angular/HTTP consumer rather than266embedding the formula in the demo controller.267268269For the private ATOMIC mission kernel consumer, preserve the public PER_ITEM adapter.270Resolve the two adapters through the concrete shared canonical contract resolver,271with their own Metadata bindings and explicit expected atomicity; never reinterpret272a PER_ITEM proposal as an ATOMIC photograph. The canonical profile already validates273SYNC/EXPLICIT and hard request/deadline ceilings; enforce the contextual ATOMIC limit274of 50 before protected capture and before maps or team partitioning. Retain one275decoded ordered input together with the transient prepared updates for the callback276attempt. Recheck the whole grant, policy, facts, versions and collective candidates277under one G→E→M→P fence, physical connection and live set budget. Outcome ordinals278come from the original kernel units, not sorted domain IDs.279280Read detailed admission reasons from the immutable atomic rejection record. The281execution terminal is aggregated as UNIT_ROLLED_BACK except deadline; a policy BLOCK282must preserve POLICY_BLOCKED in the detailed rejection, while domain dependency283conflicts retain their own reason. Prove real last-write rollback, zero domain/header/284child prefix and receipt-first replay without admission/mutation reentry after grant285or policy changes. Inject the same transaction-bound EntityManager into both graph286and domain service in isolated JPA fixtures; a manually constructed service does not287receive production injection automatically. A test-only compiled MVC binding with288mocked OpenAPI resolution proves only kernel consumption. It does not certify289producer grounding, lifecycle, HTTP, composer or READY. Keep these gates closed290until their concrete consumer proofs and exact public artifact adoption are complete.291Recover a genuinely reserved RUNNING execution through the canonical SDK: require292STOPPED/RECOVERY_STOPPED, an advanced owner epoch, FENCED for the old control and zero293admission/mutation callbacks or domain/evidence writes. Do not fabricate ledger state294with SQL. This proves neither in-flight nor uncertain-commit recovery; in-flight295recovery must respect the SDK unit deadline. Include effect references only for real296durable effects committed in the same transaction; never invent an outbox.297298## Persistence And Demo Data299300Operational migrations and deterministic demo data support proof; they do not define canonical platform semantics. Preserve resource relationships, lifecycle states, and representative data needed for filters, lookups, actions, analytics, governance, and negative paths. Update `docs/DEMO-DATABASE.md` when the operational model or seed assumptions change.301302Do not make a test only pass by changing production-like seed data without proving the contract it represents. Keep sensitive business data fictional and respect published governance/visibility restrictions in fixtures, exports, and docs.303304Before enriching demo data, inspect live triggers/functions and derived views as305well as DTOs, services and determination rules. A field can have different meanings306in a trigger and the published form contract; prove the small arithmetic example307in an isolated branch before normalizing existing totals. If they disagree, retain308the failed transaction/readback and open the canonical owner follow-up. Do not309silently disable triggers or overwrite their results to make an import pass.310A seed compatible with the current database does not certify API create/update,311approval or payment. Preserve existing lifecycle versions and receipts; distinguish312imported synthetic status and future projections from executed business actions.313314315## Adherence Inventory316317Before adding a path, DTO field, endpoint, filter, option source, stat, export, action, surface, migration, or domain materialization, classify the need:318319- `ja-suportado-so-ux`320- `ja-suportado-mal-nomeado-ou-mal-materializado`321- `suportado-parcialmente`322- `lacuna-real-de-contrato`323324Only `lacuna-real-de-contrato` justifies a new contract. State the missing behavior, canonical owner, impacted consumers, derived artifacts, and minimum proof. In particular, inspect whether existing schema, action, capability, option-source, domain-governance, decision diagnostic, or materialization data simply is not being materialized well by the cockpit or Angular runtime.325326## Proof Matrix And Validation327328Choose the smallest focused proof that covers the changed contract:329330| Changed behavior | Minimum local proof |331| --- | --- |332| resource identity, schema, groups, actions | `mvn "-Dtest=QuickstartMetadataMigrationIntegrationTest,EventosFolhaPilotIntegrationTest,OpenApiGroupResolutionIsolatedIntegrationTest" test` |333| cross-domain entity lookup/option-source contract | `mvn "-Dtest=FuncionarioEntityLookupIntegrationTest,ResourceEntityLookupGovernanceIntegrationTest" test` |334| dependent `RESOURCE_ENTITY` lookup | `mvn "-Dtest=ProcurementEntityLookupPilotIntegrationTest,ResourceEntityLookupGovernanceIntegrationTest" test` plus the affected pilot test |335| dependent provider-backed option source | `mvn "-Dtest=ProcurementExternalOptionSourceProviderIntegrationTest" test` plus the affected pilot test |336| analytical option-source dependency mapping | `mvn "-Dtest=StatsSchemaSmokeHttpTest,VwStatsSmokeHttpTest,VwAnalyticsFolhaPagamentoServiceStatsTest" test` |337| stats, analytics, or export | `mvn "-Dtest=StatsSchemaSmokeHttpTest,FuncionarioExportSmokeHttpTest" test` plus the affected pilot test |338| Domain Knowledge/config host wiring | `mvn "-Dtest=DomainKnowledgeProjectionWiringIntegrationTest" test`; use the config-starter smoke for authoring/publication lifecycle |339| governed snapshot loader/hot reload | focused runtime/health tests proving scope, hash, compatibility, monotonic activation, atomic last-known-good, invalid-candidate rejection and v1 → v2 → v1 rollback; then package/verify against released engine and Config Starter coordinates |340| persistent action lifecycle | focused HTTP proof for read-only query, contextual capabilities, ETag `428/412`, replay before stale ETag, actor/item-scoped idempotency, state transition, atomic ledger rollback and exactly-once effect; add mixed ordered batch proof when partial success is supported |341| one pilot implementation | its focused `*PilotIntegrationTest` plus any directly affected lookup/action/stats/export proof |342| `ApiPaths` or cross-domain public identity | focused proofs above and cockpit verification scripts; use `mvn test` only if those cannot cover the resulting identity graph |343344For public cockpit evidence, run the relevant documented script, such as `scripts/verify-cockpit-inventory-doc.sh`, `scripts/verify-cockpit-action-contracts.sh`, `scripts/verify-cockpit-surface-contracts.sh`, `scripts/verify-cockpit-related-resource-contracts.sh`, `scripts/verify-cockpit-analytics-contracts.sh`, `scripts/verify-cockpit-option-source-contracts.sh`, or `scripts/verify-cockpit-structural-ui-contracts.sh`.345346Review `README.md`, `docs/DEMO-DATABASE.md`, `docs/COCKPIT-QUICKSTART-REFERENCE.md`, relevant quickstart scripts, public landing docs, and executable HTTP examples when behavior is published. State explicitly when no derived artifact changes.347348## Companion Skills349350- `praxis-reactive-determinations`: metadata, host resolver, Angular runtime, and corpus proof.351352- Use `praxis-api-quickstart-operational-proof` for host/starter ownership, dependency versions, and host validation.353- Use `praxis-api-quickstart-cockpit-http-validation` for cockpit docs, HTTP scripts, and published proof.354- Use `praxis-metadata-resource-baseline` for resource controller/service/HATEOAS behavior.355- Use `praxis-metadata-schema-contracts` for `/schemas/filtered`, operation resolution, `x-ui`, ETag, and schema headers.356- Use `praxis-metadata-discovery-capabilities` for surfaces, actions, capabilities, availability, stats, export, and `_links` discovery.357- Use `praxis-metadata-domain-option-sources` for `@DomainGovernance`, semantic domain catalog, option-source, and lookup contracts.358- Use `praxis-config-domain-decisions` for governed domain rules, Domain Knowledge, publications, and runtime materializations.