@angriff36/manifest 2.18.0

package/docs/spec/semantics.md

@@ -0,0 +1,630 @@
+# Manifest IR v1 Semantics
+
+Last updated: 2026-05-20
+Status: Active
+Authority: Binding
+Enforced by: src/manifest/conformance/**, npm test
+Applies to: `@angriff36/manifest@0.5.0+`
+
+This document defines the runtime meaning of IR v1. The IR schema is authoritative; this document defines how conforming runtimes MUST interpret it.
+
+## Governance Primitive Surface
+
+Manifest exposes the following primitives for downstream governance
+integrations to consume:
+
+- runtime command execution
+- typed runtime context (tenantId, orgId, actorId, requestId, source, deterministic)
+- IR-derived command and governed-entity registries
+- canonical Next.js dispatcher projection
+- deterministic mode (effect-boundary enforcement)
+- governance audit CLI surfaces (`manifest emit registries`,
+  `manifest audit-bypasses`, `manifest audit-governance`)
+- adapter contracts: `AuditSink`, `OutboxStore`, store adapters (runtime-integrated — see `adapters.md` § "Audit Sink" and § "Outbox Store" for emission/enqueue semantics)
+
+A downstream application's governance policy (which entities are governed,
+which commands require tenant context, which bypasses are allowed) is
+expressed in the registries, the bypass file, and runtime options the
+consumer passes — never inside Manifest itself.
+
+Any Manifest behavior change that touches one of these primitives
+(runtime context shape, dispatcher route shape, registry shape, audit
+finding codes, deterministic mode, semantic event emission, adapter
+boundary) MUST update this spec and SHOULD bump `compilerVersion` so
+downstream `irHash` checks surface the change.
+
+Downstream integration examples live under `docs/integrations/` and are
+not authoritative for Manifest semantics.
+
+## Runtime Model
+- A runtime hosts an IR program plus execution state (stores, context, event log).
+- A runtime evaluates IRExpressions against an evaluation context, producing a value or undefined.
+- A runtime MAY expose a context object containing `user` and arbitrary fields.
+
+## Runtime Context Schema
+- The runtime context object MAY carry the following typed fields. None are required by the IR itself; downstream consumers MAY require subsets via runtime options:
+  - `tenantId: string` — active tenant identifier
+  - `orgId: string` — active organization identifier (e.g. Clerk `orgId`)
+  - `actorId: string` — acting user identifier
+  - `requestId: string` — caller-supplied request id, surfaced in diagnostics and on emitted events
+  - `source: string` — origin surface (`route` | `job` | `cli` | `test` | `ui` | `workflow` | other)
+  - `deterministic: boolean` — when true, adapter actions (persist/publish/effect) MUST throw `ManifestEffectBoundaryError`
+- All typed fields are surfaced inside expression evaluation under the existing `context.*` binding. Adding these fields does NOT change IR shape.
+- A runtime MAY accept the option `requireTenantContext: true`. When set, `runCommand` MUST fail closed with diagnostic `MISSING_TENANT_CONTEXT` when `context.tenantId` is absent.
+- If both `options.deterministicMode` and `context.deterministic` are set, `options.deterministicMode` takes precedence (explicit caller intent overrides ambient context).
+- The runtime context object remains open (additional ad-hoc keys MAY be present). The typed fields are a minimum contract, not an exhaustive shape.
+
+## Modules
+- IR modules are a logical grouping only.
+- Module membership does not change runtime behavior.
+
+## Entities
+- Entities define structured data and behavior. The runtime MUST support:
+  - properties (IRProperty)
+  - computedProperties (IRComputedProperty)
+  - relationships (IRRelationship)
+  - commands (references to IRCommand by name)
+  - constraints (IRConstraint)
+  - policies (IRPolicy references by name)
+
+### Properties
+- Each property has a type, optional defaultValue, and modifiers.
+- Modifiers are declarative; the runtime MAY enforce them but is not required to.
+- When creating an instance, if a property is omitted from the provided data, the runtime MUST apply the property's defaultValue if present, or the type's default value if no defaultValue is specified.
+- If a property is explicitly provided (even with an empty string `""`), that value is used and defaults do not apply.
+
+### Computed Properties
+- A computed property MUST be derived by evaluating its expression in a context containing:
+  - `self` and `this` bound to the entity instance
+  - the instance's fields
+  - any computed dependencies listed in `dependencies`
+  - `user` and `context` if provided by the runtime
+- The runtime MUST prevent infinite recursion. If a dependency cycle is detected, the computed value MUST evaluate to `undefined`.
+
+### Relationships
+- Relationships define connections between entities. A conforming runtime MUST support relationship traversal in expressions.
+- Relationship kinds:
+  - `hasMany`: One-to-many; returns an array of related instances (may be empty)
+  - `hasOne`: One-to-one; returns a single related instance or `null`
+  - `belongsTo`: Many-to-one; returns a single related instance or `null`
+  - `ref`: Simple reference; returns a single related instance or `null`
+
+#### Relationship Traversal in Expressions
+- When a member expression references a relationship (e.g., `self.author` or `post.comments`), the runtime MUST resolve the relationship by:
+  1. Identifying the relationship metadata on the current entity
+  2. Looking up related instance(s) from the store using the foreign key or inverse relationship
+  3. Returning the resolved instance(s) or `null`/`[]` for empty relationships
+
+#### Relationship Resolution Rules
+- For `belongsTo` and `ref`: The foreign key property on the source instance contains the ID of the target instance. The runtime MUST look up the target instance by that ID.
+- For `hasOne`: The inverse `belongsTo` relationship on the target entity is used. The runtime MUST query the target entity where the foreign key equals the current instance's ID.
+- For `hasMany`: The inverse `belongsTo` relationship on the target entity is used. The runtime MUST query all target instances where the foreign key equals the current instance's ID.
+
+#### Relationship Constraints
+- Relationship resolution is synchronous within the current store context.
+- Circular relationships MUST be handled gracefully; runtime MAY prevent infinite recursion.
+- Accessing a relationship on a non-existent instance returns `null` for `hasOne`/`belongsTo`/`ref` or `[]` for `hasMany`.
+- If the target entity or instance does not exist, the relationship returns `null` or `[]`.
+
+#### Entity Concurrency (vNext)
+- Entities MAY define optimistic concurrency controls via `versionProperty` and `versionAtProperty`.
+- `versionProperty`: Name of a numeric field that increments on each update (e.g., "version")
+- `versionAtProperty`: Name of a timestamp field that tracks when the version was last updated (e.g., "versionAt")
+- When a command attempts to mutate an entity with concurrency controls:
+  - The runtime MUST compare the provided `versionProperty` value against the current stored value
+  - If values match, the mutation proceeds and the version is incremented
+  - If values differ, a `ConcurrencyConflict` is returned:
+    - `entityType`: Type of entity that conflicted
+    - `entityId`: ID of the entity instance
+    - `expectedVersion`: Version number provided by the caller
+    - `actualVersion`: Current version in storage
+    - `conflictCode`: Stable code for categorizing the conflict type
+- Commands receiving a `ConcurrencyConflict` MUST NOT apply mutations and SHOULD surface the conflict to the caller.
+
+#### State Transitions (vNext)
+- Entities MAY define `transitions`: an array of `IRTransition` objects specifying allowed state changes.
+- Each `IRTransition` has: `property` (the field name), `from` (current value), `to` (array of allowed new values).
+- When a command mutates a property that has transition rules:
+  - The runtime MUST find the transition rule matching the property's current value via `from`.
+  - If a matching rule exists and the new value is NOT in `to`, the command MUST fail with a descriptive error.
+  - If no matching rule exists for the current value, the transition is unconstrained from that state.
+- Properties not referenced in any transition rule are unconstrained.
+- Transition validation occurs before entity constraint validation.
+
+### Constraints
+- Constraints are boolean expressions. A runtime MAY enforce them when mutating properties or creating instances.
+
+#### Constraint Severity (vNext)
+- Each constraint has a `severity` field: `ok`, `warn`, or `block` (default: `block`).
+- `ok` constraints are informational only; their outcome is always `passed` regardless of expression result.
+- `warn` constraints produce a `ConstraintOutcome` with `passed` based on expression evaluation but do not halt execution.
+- `block` constraints produce a `ConstraintOutcome` with `passed` based on expression evaluation and halt execution on failure.
+
+#### Constraint Codes (vNext)
+- Each constraint has a `code` field that provides a stable identifier for overrides and auditing.
+- The `code` defaults to the constraint `name` if not specified.
+- `code` MUST be unique within the scope of an entity for proper override matching.
+
+#### Constraint Evaluation (vNext)
+- When evaluated, constraints produce a `ConstraintOutcome` containing:
+  - `code`: Stable constraint identifier
+  - `constraintName`: Human-readable constraint name
+  - `severity`: The constraint's severity level
+  - `formatted`: String representation of the constraint expression
+  - `message`: Optional message from the constraint
+  - `details`: Resolved `detailsMapping` key-value pairs
+  - `passed`: Boolean indicating if expression evaluated truthily
+  - `overridden`: Boolean indicating if constraint was overridden
+  - `overriddenBy`: User ID who authorized the override (if applicable)
+  - `resolved`: Array of `{expression, value}` pairs for debugging
+
+## Date/Time Types
+
+Four primitive type names with fixed runtime representations:
+
+| Type       | Representation                                                                                      |
+| ---------- | --------------------------------------------------------------------------------------------------- |
+| `datetime` | finite number, epoch milliseconds UTC, within ±8,640,000,000,000,000 (the representable Date range) |
+| `duration` | finite number, milliseconds (may be negative)                                                       |
+| `date`     | string `"YYYY-MM-DD"`, must be a valid calendar date (leap years honored; `"2026-02-30"` invalid)   |
+| `time`     | string `"HH:MM:SS"`, `00:00:00`–`23:59:59` (no `24:00:00`, no leap seconds)                         |
+
+**Write-time validation.** On create and update mutations in the reference runtime, properties of these four types are validated after guards, alongside entity constraints. A malformed value produces a blocking constraint outcome with code `E_TYPE_DATE`, `E_TYPE_TIME`, `E_TYPE_DATETIME`, or `E_TYPE_DURATION`, carrying the property name and offending value. `null`/`undefined` always passes this validation (nullability is enforced separately). Validation applies only to these four type names — no behavior change for any existing program.
+
+**Generated defaults.** Code generators emit `""` as the default for non-nullable `date`/`time` properties — an intentionally invalid sentinel; the reference runtime's write-time validation blocks it (generated standalone code performs no date/time validation itself). Generated defaults for `datetime`/`duration` are `0` — a *valid* value (epoch / zero duration), not a sentinel. Deterministic "today" defaults are impossible by design.
+
+## Property Masking
+
+Properties MAY carry the `masked` modifier, which transforms sensitive values **at read time**. The strategy is explicit in source; modifiers precede the property name:
+
+```manifest
+entity Patient {
+  property masked(partial, 0, 4) ssn: string
+  property masked(email) contact: string unmask when user.role == "admin"
+  property masked notes: string
+}
+```
+
+### Strategies
+
+The masked output is always a string; the input value is converted with `String(value)` before masking. `null`/`undefined` values pass through unmasked (nothing to leak).
+
+| Strategy                             | Transform                                                                                                                                                                                                                    |
+| ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `redact` (default for bare `masked`) | `"***"`                                                                                                                                                                                                                      |
+| `partial(keepStart, keepEnd)`        | keep first `keepStart` and last `keepEnd` characters; every middle character replaced by `*`. If `keepStart + keepEnd >= length`, the entire string is replaced by `*` per character. Written flat: `masked(partial, 0, 4)`. |
+| `email`                              | first character of the local part + `***@` + everything after the first `@`. If the string contains no `@` or the `@` is the first character, the value is fully redacted to `"***"`.                                        |
+| `phone`                              | `***-***-` + last 4 digits of the digit-only form. If the value contains fewer than 4 digits, it is fully redacted to `"***"`.                                                                                               |
+| `last4`                              | `****` + last 4 characters. If the string has 4 or fewer characters, the result is `"****"`.                                                                                                                                 |
+
+Examples: `partial(0, 4)` on `"123-45-6789"` → `"*******6789"`; `email` on `"alice@example.com"` → `"a***@example.com"`; `phone` on `"555-867-5309"` → `"***-***-5309"`; `last4` on `"4111111111111111"` → `"****1111"`.
+
+### Compile-time rules
+
+- `masked` is a contextual identifier, NOT a reserved word: `property masked: string` remains a valid plain property declaration (one-token lookahead — if the token after `masked` is `:`, it is the property name).
+- Unknown strategy or wrong parameter arity is a compile error. `partial` requires exactly two non-negative integer parameters; `redact`, `email`, `phone`, and `last4` take none.
+- An `unmask when <expr>` clause MAY appear at the end of the property declaration; it is a compile error without the `masked` modifier.
+- **IR invariant**: `'masked' ∈ modifiers` ⇔ `maskStrategy` present on the IRProperty. Bare `masked` compiles to `maskStrategy: { type: "redact" }`.
+
+### Runtime semantics
+
+- Masking is applied in `getInstance` / `getAllInstances`, **after** `encrypted` decryption (masking operates on plaintext) and after tenant filtering, before returning data.
+- If a property is both `private` and `masked`, `private` wins: the property is excluded entirely from `getInstance` / `getAllInstances` results.
+- `unmaskWhen` bindings are the spec-guaranteed bindings only: `self.*` / `this.*` (the instance being read, real values) and `user.*` / `context.*` from the engine's runtime context. With no user in context, `user.*` resolves undefined → falsy → masked.
+- **Secure by default; diagnostics explain, never compensate**: if `unmaskWhen` evaluates falsy, the value stays masked. If `unmaskWhen` *throws*, the value stays masked AND the runtime surfaces a diagnostic carrying the expression and resolved values — the diagnostic never changes the masked outcome.
+- Masking is a read-projection transform only: guards, constraints, computed properties, relationship resolution in expressions, and command actions always see real values. Identical IR + identical runtime context still produce identical execution results.
+
+### Scope boundaries (v2.3.0 limitations, not guarantees)
+
+1. Generated Next.js read routes query the store directly and bypass the engine — they are NOT masked in this release (follow-up feature).
+2. Computed properties derived from masked properties return computed-from-real values unmasked (`emailCopy: email` bypasses masking). Mark the computed property's source data appropriately; do not assume derivation preserves masking.
+3. Event payloads contain whatever commands explicitly emit — author's responsibility.
+4. Write-back hazard: the runtime does not detect a masked placeholder (e.g. `"***"`) being round-tripped into an update. Clients must not write masked reads back.
+
+## Stores
+- Stores define persistence targets for entities.
+- A runtime MUST support at least `memory` stores.
+- Other targets (`localStorage`, `postgres`, `supabase`) are adapters (see `adapters.md`).
+- When creating an instance via a store, omitted properties receive their default values as specified in the Properties section.
+
+## Policies
+- Policies are boolean expressions with an action scope.
+- The default runtime behavior is:
+  - Policies with action `execute` or `all` MUST be checked for command execution.
+  - Policies with action `read`, `write`, or `delete` are not enforced by default.
+  - Policies with action `override` MUST be checked when authorizing constraint overrides (vNext).
+- A policy with an `entity` applies only to commands bound to that entity.
+
+### Default Policies (vNext)
+- Entities MAY define `defaultPolicies` — an array of policy names that apply to all commands bound to that entity unless overridden at the command level.
+- Default policies provide entity-level authorization baseline, reducing boilerplate for common authorization patterns.
+
+#### Inheritance Rules
+- When an entity defines `defaultPolicies`, those policies are implicitly applied to every command bound to that entity.
+- A command MAY override default policies by declaring its own `policies` array. When command-level policies are declared, default policies are NOT merged — the command's explicit policies replace the defaults entirely.
+- If a command declares no policies and the entity has no `defaultPolicies`, the command has no policy protection (scanner SHOULD warn).
+
+#### Evaluation Order
+- When evaluating policies for a command:
+  1. If the command has explicit policies declared, evaluate only those policies.
+  2. If the command has no explicit policies but the entity has `defaultPolicies`, evaluate the entity's default policies.
+  3. If neither command nor entity has policies, no policy check is performed (scanner SHOULD warn about missing policy coverage).
+
+#### Override Semantics
+- Default policies are a compile-time convenience, not a runtime construct.
+- The IR compiler MUST expand entity `defaultPolicies` into each command's effective policy list during transformation.
+- The runtime evaluates the command's expanded policy list exactly as if the policies were declared directly on the command.
+- This means:
+  - A command that overrides defaults by declaring its own policies has a different IR representation than one that inherits defaults.
+  - Scanner tools can detect inherited vs. declared policies by comparing source AST to IR output.
+
+#### IR Representation
+- `IREntity.defaultPolicies`: Array of policy name strings (references to policies in `IR.policies`).
+- `IRCommand.policies`: Array of policy name strings (explicitly declared or expanded from entity defaults).
+- When compiling, if a command has no declared policies and the entity has `defaultPolicies`, the compiler MUST copy the entity's `defaultPolicies` into the command's `policies` array.
+- This expansion ensures runtime behavior is consistent regardless of whether policies were inherited or declared.
+
+#### Example
+
+From conformance fixture `55-default-policies.manifest`:
+
+```manifest
+entity Task {
+  default policy RequireAuth execute: user.id != null "Authentication required"
+
+  property required title: string
+  property status: string = "pending"
+  property assigneeId: string
+
+  command complete() {
+    guard self.assigneeId == user.id or user.role == "admin"
+    mutate status = "completed"
+  }
+
+  command reassign(newAssigneeId: string) {
+    guard user.role == "admin" or user.role == "manager"
+    mutate assigneeId = newAssigneeId
+  }
+}
+```
+
+In this example:
+- `complete` inherits the default policy (`RequireAuth`)
+- `reassign` also inherits `RequireAuth` and adds its own guard for role checks
+- The IR for `complete` will include the inherited default policy name in its `policies` array
+- The IR for `reassign` will include the same inherited default policy name in its `policies` array
+
+## Commands
+- The IR root `commands` array is the authoritative command definition list.
+- `IREntity.commands` is a list of command names that reference definitions in the root `commands` array.
+- A command referenced by an entity MUST have its `entity` field equal to that entity's name.
+- Command name matching is case-sensitive.
+- Command names in the root `commands` array MUST be unique.
+- During compilation, the compiler MUST reject duplicate command intent within the same entity before IR emission. This includes:
+  - exact duplicate `entity.command` names across all loaded manifest source files;
+  - canonical duplicates for the same entity after conservative normalization: lowercase command names, strip separators, strip the entity name as a prefix or suffix, and normalize the verbs `create`/`add`/`new`, `update`/`edit`/`modify`, and `delete`/`remove`/`deactivate`/`archive` to one canonical intent.
+- Duplicate command-intent diagnostics MUST name the duplicate command, the existing command, both source paths when available, and instruct the author to use or extend the existing command.
+- Different entities MAY define the same normal command names, such as `create`, `update`, or `delete`; canonical duplicate checks are scoped to the same entity or resolved entity alias.
+- If an entity references a command name that does not exist in the root command list, compilation MUST fail.
+- Commands take parameters, optional guards, actions, emits, and optional return type.
+- On execution, a runtime MUST:
+  1) Build an evaluation context containing `self`, `this`, input parameters, and runtime context.
+  2) If the command declares `rateLimit`, evaluate the rate-limit gate for the configured scope (`user`, `tenant`, or `global`). If denied, execution MUST stop with a `rateLimitDenial` on the CommandResult.
+  3) Evaluate applicable policies (see Policies). Policy-level `rateLimit` gates run before each policy expression. If any policy fails (expression or rate limit), execution MUST stop with a denial.
+  4) Evaluate command-level constraints (see Command Constraints). If any `block` constraint fails without an authorized override, execution MUST stop.
+  5) Evaluate guards in order; if any guard is falsey, execution MUST stop with a guard failure.
+  6) Execute actions in order.
+  7) Emit declared events in order.
+  8) Return a CommandResult with success status, emitted events, and the last action result.
+- Commands may declare a `retry` policy. When present, the runtime wraps execution and retries only on `CONCURRENCY_CONFLICT` and `TIMEOUT` outcomes (or the explicit `retryOn` list). Policy denials, guard failures, and blocking constraint outcomes MUST NOT be retried.
+- `schedule` declarations compile to IR `schedules`. Runtimes expose `getSchedules()` and `runSchedule(name)`; adapters decide when to invoke schedules — the reference runtime does not include a built-in timer.
+- Entity `extends` and `mixin` composition is resolved at compile time. Precedence on name collision: own > later mixin > earlier mixin > parent. Cycles and unknown parents are compile errors.
+
+### Command Constraints (vNext)
+- Commands may define a `constraints` array for pre-execution validation.
+- Command constraints are evaluated after policies but before guards.
+- Command constraints use the same constraint schema as entity constraints (code, severity, overrideable, etc.).
+- Command constraints support all three severity levels: `ok`, `warn`, `block`.
+- A command with failing `block` constraints MUST NOT execute unless an override is authorized.
+
+### Override Mechanism (vNext)
+- Constraints may be marked `overrideable: true` to allow authorized bypass.
+- An `overridePolicyRef` may be specified to reference the policy that authorizes overrides.
+- To override a constraint, the runtime receives an `OverrideRequest` containing:
+  - `constraintCode`: The code of the constraint to override
+  - `reason`: Human-readable explanation for the override
+  - `authorizedBy`: User ID of the authorizer
+  - `timestamp`: When the override was requested
+- Override authorization flow:
+  1. Runtime checks if constraint is marked `overrideable`
+  2. If `overridePolicyRef` is specified, the referenced policy is evaluated
+  3. If policy passes, the constraint outcome is marked with `overridden: true` and `overriddenBy` set to the authorizer
+  4. An `OverrideApplied` event MUST be emitted with the override details
+- Constraints NOT marked `overrideable` MAY NOT be overridden; override attempts MUST be rejected.
+
+### Generated Artifacts
+Generated code MUST conform to the same semantics as the IR runtime:
+
+- **Server code**: MUST enforce policies (action `execute` or `all`) before executing commands
+- **Client code**: Commands MUST return the last action result (not void)
+
+Generated server endpoints SHALL:
+1. Check applicable policies for the entity/command
+2. Check guards in order
+3. Execute the command
+4. Return the result with success status
+
+Generated client command methods SHALL:
+1. Check applicable policies (if entity has policies)
+2. Check guards in order
+3. Execute actions in order
+4. Emit declared events
+5. Return the last action result
+
+### Generated Projections
+- Projections are generated views/outputs derived from IR, not semantic authority.
+- Runtime meaning remains anchored in IR semantics.
+- Projections MUST NOT diverge from IR semantics.
+
+Brief source alignment:
+- `README.md`: "Projections are tooling, not runtime semantics."
+- `docs/guides/usage-patterns.md`: "Projections are tooling, not language semantics."
+
+See also:
+- `../patterns/usage-patterns.md`
+- `../patterns/embedded-runtime-pattern.md`
+- `adapters.md`
+
+## Actions
+- `mutate`: Evaluate expression and, if a current instance is bound, assign the result to the target field and return the value. If no instance is bound, the action has no storage effect and returns the value.
+- `emit`: Evaluate expression; return the value. Runtimes MAY emit a generic action event.
+- `publish`: Evaluate expression; return the value. Runtimes MAY emit a generic action event.
+- `persist`: Evaluate expression; return the value. Runtimes MAY persist via adapters.
+- `compute`: Evaluate expression; return the value.
+- `effect`: Evaluate expression; return the value. Runtimes MAY invoke side effects via adapters.
+
+### Deterministic Mode (vNext)
+- When `deterministicMode` is `true`, a conforming runtime MUST throw `ManifestEffectBoundaryError` for `persist`, `publish`, and `effect` action kinds instead of the default no-op behavior.
+- This enforces the effect boundary contract: adapter actions in a deterministic context are programming errors, not runtime domain failures.
+- See `adapters.md` for the normative exception to default no-op behavior.
+
+## Events
+- Commands declare `emits` as a list of event names.
+- When a command emits an event, the runtime MUST log an EmittedEvent with:
+  - `name`: the emitted event name
+  - `channel`: the event channel if defined in IR, otherwise the event name
+  - `payload`: an object containing command input and the last action result
+  - `timestamp`: the runtime time source
+
+### Event Workflow Metadata (vNext)
+- A conforming runtime MUST attach `emitIndex` (zero-based per-command emission index) to emitted events. `emitIndex` resets to 0 at the start of each `runCommand` invocation.
+- If `correlationId` or `causationId` are provided in command options, the runtime MUST propagate them to emitted events.
+- `emitIndex` is a per-command counter only. It is NOT a global sequence. Cross-command ordering is the caller's responsibility.
+- Given identical IR + identical runtime context (including injected `now`/`generateId`) + identical input + identical options, emitted events MUST have identical `emitIndex` values.
+
+### Realtime Entities
+
+Entities MAY declare a bare `realtime` flag inside the entity block:
+
+```manifest
+entity Order {
+  property id: string
+  realtime
+}
+```
+
+- `realtime` is a contextual identifier, NOT a reserved word: `property realtime: boolean` remains a valid plain property declaration.
+- The flag compiles to `IREntity.realtime: true`.
+- **`realtime` has no runtime execution semantics.** It is a projection hint only: projections (Next.js, Express) use it to emit SSE subscription surfaces for the flagged entity. Identical IR with and without the flag produces identical command execution results, identical events, and identical state.
+
+#### Runtime `subscribe()` contract
+
+The reference runtime exposes `subscribe(entityName, listener): () => void` — a convenience over `onEvent` that exists regardless of any entity's `realtime` flag:
+
+- The listener receives only events whose `subject.entity === entityName`.
+- Events **without** a `subject.entity` are NOT delivered to `subscribe` listeners (use `onEvent` for the unfiltered firehose).
+- The return value is an unsubscribe function; after it is called the listener receives no further events.
+- Multiple subscribers (same or different entity names) are independent; listener errors are swallowed exactly as for `onEvent` listeners and never affect execution.
+
+#### Deployment constraint (generated SSE surfaces)
+
+The event stream is per-engine-instance and in-memory. Generated SSE code therefore uses a module-scoped singleton engine (a generated `getSharedRuntime()` accessor shared by SSE routes and command routes). This requires a long-lived Node server process and a **single-instance deployment**; serverless or multi-instance fan-out needs an external event bus and is out of scope.
+
+### Idempotency (vNext)
+- A conforming runtime MAY support an `IdempotencyStore` for command deduplication.
+- When configured, the runtime MUST require a caller-provided `idempotencyKey` in command options. If no key is provided, the runtime MUST return an error.
+- If the key exists in the store, the runtime MUST return the cached `CommandResult` without re-executing the command.
+- Both successful and failed results MUST be cached.
+- The idempotency check occurs BEFORE any command evaluation (before building evaluation context, policy checks, constraints, guards, actions, or event emission).
+
+## Reactions
+
+Reactions declare event-driven command dispatch within the Manifest governance boundary.
+
+### Syntax
+```
+on <EventName> run <EntityType>.<commandName>
+  resolve <expression>
+  params { <paramName>: <expression>, ... }
+```
+
+### Compilation
+- Each reaction declaration compiles to an `IRReactionRule` node in the IR `reactions` array.
+- `event`: The triggering event name (MUST reference a declared event).
+- `targetEntity`: Entity type to invoke the command on.
+- `targetCommand`: Command name on the target entity.
+- `resolve`: Expression evaluated against the event payload to produce the target instance ID.
+- `params`: Optional array of `{name, expression}` mappings from event payload to command input.
+
+### Runtime Semantics
+- After a command emits events (step 6 in command execution), the runtime MUST evaluate all reaction rules whose `event` matches each emitted event name.
+- Matching reactions are evaluated in **declaration order** (order in the IR `reactions` array).
+- For each matching reaction:
+  1. Evaluate `resolve` expression with the event payload as context → produces `instanceId`.
+  2. Evaluate each `params[].expression` with the event payload as context → produces command input.
+  3. Invoke `runCommand(targetEntity.targetCommand, input, {instanceId, correlationId, causationId})`.
+- Reaction-triggered commands are full command executions (policies, guards, actions, emits apply).
+- Events emitted by reaction-triggered commands MAY trigger further reactions (cascading).
+- A conforming runtime MUST enforce a maximum reaction depth (default: 10) to prevent infinite loops. When exceeded, the runtime MUST throw a `ManifestReactionDepthError`.
+- Reaction execution is **synchronous within the same turn** (in-process). The triggering command's result includes all events from cascaded reactions.
+- The `correlationId` from the triggering command MUST propagate to all reaction-triggered commands. Each reaction-triggered command receives the triggering event's name as its `causationId`.
+
+### Determinism
+- Given identical IR + identical runtime context + identical input, reactions MUST produce identical results in identical order.
+- Reaction evaluation order is fixed by IR declaration order. No priority or weighting.
+
+## User-Facing Boundary
+
+Manifest is not a form builder that exposes plumbing. Downstream products use it so
+**people never paste internal ids or platform fields** — they do normal work; the
+runtime supplies tenant scope, auth, parent links, audit metadata, and timestamps.
+
+**End users MUST NOT be required to provide:**
+
+- Tenant or organization scope (`tenantId`, `orgId`, …) — comes from login/session
+- Who is acting (`userId`, `createdById`, `updatedById`, `actorId`) — comes from auth
+- Parent record links (`{parent}Id`) — comes from "add child on this page" or automation
+- Fields copied from the parent record (e.g. venue on an event when creating a child board)
+- Timestamps and version fields the engine auto-fills
+- Request/tracing ids (`requestId`, `correlationId`, `causationId`)
+
+**Allowed user inputs** are business data: names, amounts, dates they pick, choices
+among real options (status, category, assignee when assignment is the feature).
+
+RBAC stays in policies and guards (`user.role`, `user.id`) — not in create forms.
+
+The compiler MUST reject create commands that violate this boundary. See § Domain Completeness.
+
+## Domain Completeness (Compile-Time Product Wiring)
+
+The compiler MUST enforce domain wiring so half-wired models fail at compile time, not in generated APIs with no product path. These rules implement the product-quality bar from Capsule-Pro `manifest/scripts/script-index.md` Part 1: no unwired entities, no required fields the runtime auto-provides, no child creates that demand parent IDs or parent-owned context with no supply path, and no reactions that silently no-op.
+
+### Unwired foreign keys (error)
+
+When entity `Child` declares a property or required command parameter `{parent}Id` that resolves to an existing entity `Parent` (camelCase stem match, e.g. `disciplinaryActionId` → `DisciplinaryAction`), the compiler MUST emit an **error** unless `Child` declares `belongsTo` or `ref` targeting `Parent` for that FK field.
+
+Cross-cutting ids (`tenantId`, `userId`, `ownerId`, etc.) are excluded.
+
+When this diagnostic fires, compilation MUST fail (`ir` is null), same as other error-severity diagnostics.
+
+### One-sided relationships (warning)
+
+When `Child` belongsTo `Parent` but `Parent` has no `hasMany`/`hasOne` back to `Child`, the compiler MUST emit a **warning**. Minimal relationship fixtures (e.g. conformance Author/Book) may omit the inverse side; product manifests SHOULD declare both sides.
+
+### Manual parent id on create (error)
+
+When `Child.create` requires a `{parent}Id` parameter and `Parent` has no nested command that creates `Child` with an implicit FK, and no event reaction supplies that parameter, the compiler MUST emit an **error**. Compilation MUST fail (`ir` is null).
+
+Exempt when an `on Event run Child.create` reaction includes the parent FK field in `params` (reaction-wired create path).
+
+### Auto-provided create parameters (error)
+
+When `Entity.create` requires a parameter the runtime or compiler auto-provides, the compiler MUST emit an **error**:
+
+- Tenant discriminator property when `tenant` is declared
+- `tenantId`, `orgId`, `organizationId` — scope from session/context (even when `tenant` block is absent)
+- `userId`, `createdById`, `updatedById`, `actorId` — acting user from auth/context
+- `requestId`, `correlationId`, `causationId` — tracing metadata, never end-user input
+- `createdAt` / `updatedAt` when entity `timestamps` is enabled
+- `versionProperty` / `versionAtProperty` when declared on the entity
+
+Business assignment fields (e.g. `ownerId`, `assigneeId`) MAY remain on create when
+choosing another user/record is the feature; they MUST NOT be used as a stand-in for
+"current user" or parent linkage.
+
+Callers must not be forced to supply values they cannot access or that the engine fills automatically.
+
+### Parent-context inferable fields (error)
+
+When `Child.create` requires a parameter whose name and scalar type match a property on a `belongsTo` parent (excluding identity, tenant, lifecycle, and generic child-specific fields such as `name`, `title`, `notes`), the compiler MUST emit an **error**. Such fields MUST be populated via parent-context propagation (create from the parent command), not re-entered by the user.
+
+### Unreachable persisted entities (error or warning)
+
+A persisted entity (has store) with no entity-scoped commands and not referenced as a relationship target MUST produce:
+
+- **error** when the entity has domain wiring signals (`belongsTo`/`ref`, or a `{entity}Id` FK that resolves to another declared entity) and no constraint-only fixture role
+- **warning** for property-only persisted fixtures used in language tests (no domain FK wiring)
+- **warning** when the entity exists only to test constraints (has constraint declarations, no commands)
+
+An entity with no store, no commands, and no relationship references SHOULD produce a **declared but unused** warning.
+
+### Reaction wiring (error)
+
+For each `on Event run Entity.command` reaction:
+
+- **Orphan event**: ERROR when no command emits that event.
+- **Invalid payload reference**: ERROR when `payload.X` references a field not present on the emitting command's parameters, the event's declared payload schema, enriched fields (`_subject`, `_eventName`, `_channel`), or (for create emitters) valid `payload.result.Y` entity properties.
+- **Non-create `payload.result.*` member access**: ERROR — non-create commands set `result` to the last action value, not the instance; use `payload._subject.id` or an input param instead.
+
+## Expressions
+- Literal, identifier, member access, unary, binary, call, conditional, array, object, and lambda expressions are supported.
+- The following operators MUST be supported by the default runtime:
+  - Binary: `+`, `-`, `*`, `/`, `%`, `==`, `!=`, `<`, `>`, `<=`, `>=`, `and`, `or`, `in`, `contains`
+  - Unary: `!`, `not`, `-`
+- Operator semantics:
+  - `==` and `is` use loose equality (JavaScript `==` semantics): `undefined == null` is `true`, type coercion applies.
+  - `!=` uses loose inequality (JavaScript `!=` semantics): `undefined != null` is `false`, type coercion applies.
+  - `and` and `or` evaluate with boolean truthiness.
+  - `in` checks membership in an array or substring in a string.
+  - `contains` checks membership where the left side is array or string.
+
+## Async Commands
+
+Commands may be declared with the `async` modifier to defer action execution to a background worker queue.
+
+### Syntax
+```manifest
+async command processOrder(amount: number) {
+  guard self.status == "pending"
+  mutate status = "processing"
+  mutate total = amount
+  emit OrderProcessed
+}
+```
+
+### IR Representation
+When a command has `async: true`, the IR compiler adds:
+- `async: true` on the `IRCommand`
+- `completionEvent: "{commandName}Completed"` — auto-derived name
+- `failureEvent: "{commandName}Failed"` — auto-derived name
+
+Two synthesized `IREvent` entries are appended to `ir.events`:
+- `{commandName}Completed` on channel `jobs.{commandName}` with payload: `jobId: string`, `result: any`, `completedAt: number`
+- `{commandName}Failed` on channel `jobs.{commandName}` with payload: `jobId: string`, `error: string`, `failedAt: number`
+
+If a user-declared event collides with a synthesized event name, the compiler MUST emit a diagnostic error.
+
+### Execution Semantics
+
+When an async command is invoked (and `context.source !== 'job'`):
+
+1. **Fail-fast validation**: Policies, constraints, and guards are evaluated synchronously. If any fail, the command returns a failure result immediately — no job is enqueued.
+2. **Enqueue**: If validation passes, a `JobRecord` is enqueued via the `JobQueue` adapter. The command returns immediately with `{ jobId, status: 'pending', enqueuedAt }`.
+3. **No actions executed**: Mutations and emits are deferred to the background worker.
+4. **No emitted events**: The immediate return has an empty `emittedEvents` array.
+
+When `context.source === 'job'` (re-entry from the job worker):
+- The async branch is bypassed; the full command body executes (policies → guards → actions → emits → return).
+
+### Job Lifecycle
+- `pending` → enqueued, awaiting worker pickup
+- `running` → worker is executing the command body
+- `completed` → actions succeeded; `{commandName}Completed` event emitted
+- `failed` → actions failed; `{commandName}Failed` event emitted
+
+### Missing JobQueue
+If `RuntimeOptions.jobQueue` is not configured and an async command is invoked, the runtime returns `{ success: false, error: 'MISSING_JOB_QUEUE: ...' }`.
+
+### Deterministic Testing
+The `drainJobs()` method on `RuntimeEngine` drains all pending jobs synchronously in FIFO order, executing each via `_executeCommandInternal` with `context.source = 'job'`. This enables deterministic conformance testing without real worker infrastructure.
+
+### Determinism
+- Job IDs are generated via `RuntimeOptions.generateId()` (deterministic in tests)
+- Timestamps use `RuntimeOptions.now()` (deterministic in tests)
+- Jobs drain in FIFO enqueue order
+
+## Nonconformance
+There are no known nonconformances. All implementations conform to this specification.
+
+
+