Praxis Reactive Determinations
Use this skill for the end-to-end handoff from a governed semantic decision to
reactive form behavior. Reactive Determinations replaced the former Form Effect
contract; do not reintroduce removed @FormEffect annotations, formEffects
schema blocks, or frontend-authored business formulas.
Canonical Owners
praxis-config-starterowns governed domain-rule authoring, approvals, publication, immutable snapshots, active heads, rollback, and materialization.praxis-metadata-starterowns the public metadata vocabulary and compiles registered determination definitions into operation-specificx-uischema.- The Java host owns facts, executable provider/registry implementations, authorization, transactions, and business effects.
praxis-ui-angularowns the generic runtime materialization and diagnostics. It does not become the business-rule owner.- Quickstart and HTTP Examples prove the chain; they do not redefine it.
Required Source Audit
Inspect the affected owner and direct consumers:
- Metadata
docs/spec/reactive-determinations.md,uischema/determination/**, compiler and contract specs - Config
DomainRuleReactiveDeterminationSpec, snapshot/control-plane services, materialization migration, rule tests, and active-head rules - Quickstart
ReactiveDeterminationPilotConfiguration, applied resolver, provider/ruleset, tenant-scope and resolver tests - Angular Core reactive-determination model, Dynamic Form runtime service/spec, CRUD dialog/drawer handoff, Stepper adapter, Metadata Editor diagnostics, and component metadata/registry projection
- HTTP examples, payloads, manifest, corpus verifier, and smoke
Contract Rules
- A definition has stable identity, scope, applicable form modes, trigger mode, typed input bindings, typed output bindings, and provenance.
- Resolve operation-specific metadata for the actual create/edit/action surface. A definition present on another operation is not applicable evidence.
- Input bindings read the current governed form snapshot. Output bindings write only declared targets under their documented write policy; do not patch arbitrary config or component state.
- Preserve definition/snapshot provenance through metadata, runtime diagnostics, HTTP evidence, and authoring explanations. Labels and prompts cannot select a determination.
- Order executions deterministically. When inputs change again, stale results must not overwrite a newer form state. Cancellation, debounce, concurrency, and partial output behavior must be explicit and tested.
- Fail closed for unknown definitions, invalid bindings, missing provider, incompatible snapshot, denied scope, malformed result, or unresolved output. Do not fall back to a local formula or legacy Form Effect.
- A host consuming governed snapshots validates scope, compatibility, content hash, head identity, and monotonic activation before an atomic last-known-good swap. A failed candidate leaves the last valid runtime active and visible in health/diagnostics without leaking snapshot payloads.
- Dynamic Form owns generic execution and form-state application. CRUD and Stepper pass the correct operation/form context; they do not duplicate the determination engine.
Implementing Reactive Determinations in a New Java/Spring Boot Host (Step-by-Step)
When building or evolving a Spring Boot host that uses praxis-metadata-starter, implement Reactive Determinations with the following exact contract so ReactiveDeterminationMetadataCompiler compiles x-ui.reactiveDeterminations into GET /schemas/filtered without failing closed:
1. Declare Output/Preview Fields on CreateDTO and UpdateDTO
ReactiveDeterminationMetadataCompilerverifies that everyinput.fieldPathandoutput.fieldPathexists in the form operation's request body schema (CreateDTOforCREATE,UpdateDTOforEDIT).- If a reactive determination populates a read-only preview or calculated field (e.g.,
netSalary,availableVacanciesPreview,expectedEndDate), declare that field on bothCreateDTOandUpdateDTO(annotated with@UISchema(readOnly = true, ...)when the user should not edit it manually).
2. Declare Explicit @Operation(operationId = ...) on Form Operations and the Capability Endpoint
Because AbstractResourceController inherits create and update, SpringDoc generates unstable default operationIds (create_1, create_2) across multiple controllers unless overridden. Always override create and update with explicit operationIds and expose a non-persisting POST determination endpoint (without path variables):
@PostMapping
@Operation(
operationId = "createEmployee",
summary = "Create employee record",
description = "Creates an employee record after validating position capacity and compensation."
)
@Override
public ResponseEntity<RestApiResponse<EmployeeResponseDTO>> create(@Valid @RequestBody CreateEmployeeDTO dto) {
return super.create(dto);
}
@PutMapping("/{id}")
@Operation(
operationId = "updateEmployee",
summary = "Update employee record",
description = "Updates an existing employee record and revalidates compensation and assignment."
)
@Override
public ResponseEntity<RestApiResponse<EmployeeResponseDTO>> update(
@PathVariable Long id,
@Valid @RequestBody UpdateEmployeeDTO dto) {
return super.update(id, dto);
}
@PostMapping("/determinations/position-compensation-preview")
@Operation(
operationId = "determineEmployeePositionCompensationPreview",
summary = "Determine position floor, work schedule, and available vacancies",
description = "Non-persisting reactive determination that projects position parameters and vacancy balance while editing the employee form."
)
public ResponseEntity<PositionCompensationPreviewResponse> determinePositionCompensationPreview(
@Valid @RequestBody PositionCompensationPreviewRequest request) {
return ResponseEntity.ok(service.determinePositionCompensationPreview(request));
}
3. Register @Bean ReactiveDeterminationDefinitionProvider
Bind the form operation operationIds (ReactiveDeterminationScope) to the determination capability operationId using valid JSON Pointers starting with "/":
@Configuration(proxyBeanMethods = false)
public class EmployeeReactiveDeterminationConfig {
@Bean
ReactiveDeterminationDefinitionProvider employeePositionCompensationDeterminationProvider() {
return () -> List.of(
new ReactiveDeterminationDefinition(
"human-resources.employees.position-compensation-preview",
List.of(
new ReactiveDeterminationScope("createEmployee", ReactiveDeterminationFormMode.CREATE),
new ReactiveDeterminationScope("updateEmployee", ReactiveDeterminationFormMode.EDIT)
),
"determineEmployeePositionCompensationPreview",
ReactiveDeterminationTriggerMode.ON_CHANGE,
List.of("/positionId", "/departmentId"),
List.of(
new ReactiveDeterminationInputBinding("/positionId", "/positionId"),
new ReactiveDeterminationInputBinding("/departmentId", "/departmentId")
),
List.of(
new ReactiveDeterminationOutputBinding("/baseSalaryFloor", "/baseSalaryFloor"),
new ReactiveDeterminationOutputBinding("/defaultWeeklyHours", "/weeklyHours"),
new ReactiveDeterminationOutputBinding("/availableVacanciesPreview", "/availableVacanciesPreview")
),
new ReactiveDeterminationProvenance(
ReactiveDeterminationProvenanceKind.HOST,
"hr-host-service",
"1"
)
)
);
}
}
4. Five Strict Compiler Invariants (ReactiveDeterminationMetadataCompiler)
- Valid JSON Pointers (
/): EverysourcePath,input.fieldPath,input.requestPath,output.responsePath, andoutput.fieldPathmust start with"/"(e.g.,"/positionId"). sourcePathsSubset ofinputs: Every path insourcePathsmust also appear as aninput.fieldPathininputs. (InEDITmode, you may pass additional context inputs such asnew ReactiveDeterminationInputBinding("/id", "/employeeId")ininputswithout listing"/id"insourcePaths).- Schema Property Existence: Every
input.fieldPathandoutput.fieldPathmust resolve in theCreateDTO/UpdateDTOOpenAPI schema, everyinput.requestPathmust resolve in the determinationRequestDTO schema, and everyoutput.responsePathmust resolve in the determination200 OKResponseDTO schema. - Non-Overlapping Inputs and Outputs:
input.fieldPathandoutput.fieldPathmust never be identical or parent/child of each other within the same definition (prevents infinite trigger loops). - Form Mode HTTP Method Match:
ReactiveDeterminationFormMode.CREATErequires aPOSTform operation;ReactiveDeterminationFormMode.EDITrequires aPUTorPATCHform operation; and the determination capability operation (definition.operationId()) must be aPOSToperation without{...}path parameters.
5. Deep Domain Discovery for Reactive Determinations ("Além do Óbvio" — 4 Families)
Do not leave enterprise forms passive until submit. Audit CreateDTO, UpdateDTO, and entity relationships to discover Reactive Determinations across four families:
- Cross-Entity Lookup & Directory Projection: When the user selects a foreign key or code (
"/postalCode","/positionId","/departmentId","/contractPlanId"), auto-populate address fields, salary floor, standard work schedule, cost center, or responsible manager. - Multi-Field Deterministic Calculations: When gross amount, deductions, rate, or start date + duration change (
"/grossSalary","/baseDeductions","/startDate","/probationDays"), compute net amount, total deductions, or expected end/review date in real time. - Chained Reactive Determinations (
A -> B -> C): When Determination 1 writes an output field (e.g.,"/netSalary"), a secondReactiveDeterminationDefinitionthat lists"/netSalary"in itssourcePathsandinputsis automatically triggered by@praxisui/dynamic-formto compute downstream fields (e.g.,"/expectedPaymentDate"or approval tier). - Draft Policy, Quota & Eligibility Preview: While the user fills out an assignment or movement form, evaluate vacancy balance, qualification compatibility, or schedule conflict and populate read-only preview fields (
"/availableVacanciesPreview","/eligibilityDiagnosticPreview") before submit.
Chained governed calculations
For an engine contract that supports direct dependency outputs (1.5 G1), compose versioned host Java calculations through the approved RuleSet DAG and evaluate once per request. The engine runtime skill defines the restricted output channel; metadata input/output bindings are not an alternative dataflow engine. Validate the published engine coordinate before adoption: beta.15/contract 1.4 does not transport intermediate outputs. G1 source tests alone do not prove an operational Reactive Determination or an adopted dependency.
Keep derived facts out of submitted authority. Preview, command and sandbox must use the same executable registry and evaluation service. A downstream calculation consumes and validates its direct predecessor's typed output; never repair missing output with a second evaluation, local formula or client value. The Java output channel does not expose prior outputs to JSON Logic or replace form cancellation, provenance, precondition capture and stale-result handling. Use existing execution status/pending/unsatisfied evidence for UX; completion of pending alone is not satisfaction. Preserve the draft on technical failure or precondition conflict, distinguish prior displayed values from current valid results, and never automatically refresh concurrency tokens and resubmit. Do not expose raw engine results or mistake concurrent unit tests for tenant authorization proof. Test the actual package and authenticated HTTP/UI handoff. Prove the chain without prefilled derived values before claiming the example is ready, then prove the actual published packages and HTTP/UI handoff separately.
Financial draft and dependent-resource handoff
For payroll facts, three payment dates or event create/edit/move, read the financial handoff procedure. It separates the host's financial/CAS authority from the consumer's snapshot capture, real metadata FormArray, persistent validation and runtime satisfaction. Inspect the actual published Core/Dynamic Form packages before changing a generic contract. Treat G4 source and mocked consumer tests as candidate evidence until the corresponding schema, authenticated HTTP, isolated Neon and UI gates pass.
Governed runtime upgrades
Before adopting a new engine contract, inventory every active-snapshot consumer, including secondary pilots, caches, preload jobs, fixtures and public receipts. Config owns historical verification versus executable admission: an intact incompatible snapshot remains history, while an invalid one must not be relabeled merely incompatible. Never rewrite hashes, approvals or engine tuples in persisted snapshots.
Publish a newly approved compatible composition without activating it, prewarm with the real host registry, report canonical probes and perform explicit conditional activation. Absence of a head requires the governed bootstrap rollout; it is not a shortcut around readiness. Candidate preload cannot establish last-known-good. Run the 1.4→1.5 cutover under maintenance without mixed-version traffic. After the first 1.5 selection, recover forward to the compatible line; do not resume the old runtime over migrated heads. Test all affected families, partial cutover/recovery, rollback within the compatible line and rejection of old-line activation. Preserve draft/result diagnostics in UI and distinguish source tests, candidate package tests, published dependency adoption and real authenticated HTTP/UI proof.
Close the upgrade proof only after a real non-persisting consumer operation and official host observation confirm active adoption after A, B and same-line rollback. Match the selected scope, snapshot/hash and activation identity; candidate readiness alone is insufficient.
Implementation Workflow
- Inventory what the platform already publishes: active decision/snapshot, registered definition, operation schema, bindings, runtime service, diagnostics, and HTTP proof.
- Classify the gap. Missing UI diagnostics or adapter propagation is not a new metadata contract. Missing business logic belongs to Config/host, not Angular.
- Implement at the canonical owner and update the complete handoff only where its public projection changed.
- Preserve beta cleanup: migrate consumers and derived docs in the same cycle; do not keep parallel Form Effect and Reactive Determination paths without an explicit operational requirement.
- Prove tenant/operation/form-mode isolation and sanitized diagnostics.
Proof Matrix
Minimum focused gates:
# metadata owner
mvn "-Dtest=ReactiveDeterminationMetadataCompilerTest,ReactiveDeterminationSpecContractTest" test
# Angular runtime
npm run test:core -- --include=projects/praxis-core/src/lib/models/form/reactive-determination.model.spec.ts
npm run test:form -- --include=projects/praxis-dynamic-form/src/lib/services/reactive-determination-runtime.service.spec.ts
# quickstart host
mvn "-Dtest=AppliedReactiveDeterminationResolverTest,ReactiveDeterminationTenantScopeHttpTest" test
# HTTP corpus
node smoke/verify-reactive-determination-corpus.mjs
node smoke/smoke-reactive-determinations.mjs
Run each command from its owning repository and add Config snapshot/rule tests when authoring, publication, head, or materialization changes.
Prove happy execution, invalid inputs/business rejection, stale/cancel race, tenant or operation mismatch, incompatible snapshot/LKG behavior, and absence of legacy Form Effect output. Review Metadata docs, Angular JSON API/registry, Quickstart pilot docs, HTTP manifest/LLM surface, and public examples whenever the mirrored contract changes.
Companion Skills
praxis-config-domain-decisionsandpraxis-rules-engine-runtime: governed rule/snapshot lifecycle.praxis-metadata-schema-contracts: operation-specific schema andx-uipublication.praxis-form-schema-runtime-modesandpraxis-form-actions-hooks-runtime: Angular form context and lifecycle.praxis-crud-dialog-form-host-lifecycleandpraxis-stepper-wizard-runtime: host adapters.praxis-api-quickstart-domain-pilotsandpraxis-http-examples-contract-surfaces: operational/public proof.