@affordance/core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mochicode LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,52 @@
+# @affordance/core
+
+Compute what a case can do now, for a particular actor. A case is a persisted
+object with state and independently guarded steps. Steps become available
+through state changes, without a predefined ordering.
+
+Requires Node 22.12+ and Postgres. ESM JavaScript and TypeScript declarations
+are included. Zod is one option for the Standard Schema validation interface.
+
+```bash
+npm install @affordance/core pg zod
+```
+
+```ts
+import { actor, bootstrap, caseType, createEngine, stepsOf } from '@affordance/core'
+import { Pool } from 'pg'
+import { z } from 'zod'
+
+const State = z.object({ ownerId: z.string(), approved: z.boolean() })
+const step = stepsOf(State, actor<{ id: string }>())
+const approval = caseType({
+  name: 'approval',
+  state: State,
+  steps: [step({
+    name: 'approve',
+    requires: { pending: (state) => !state.approved },
+    permits: { owner: (state, ctx) => state.ownerId === ctx.actor.id },
+    handler: async (state) => ({ ...state, approved: true }),
+  })],
+})
+
+const pool = new Pool({ connectionString: process.env.DATABASE_URL })
+try {
+  await bootstrap(pool)
+  const engine = createEngine({ db: { pool }, caseTypes: [approval] })
+  const current = await engine.createCase('approval', { ownerId: 'alice', approved: false })
+  console.log(await engine.affordances(current.id, { id: 'alice' }))
+  await engine.execute(current.id, 'approve', { actor: { id: 'alice' } })
+  console.log(await engine.journal(current.id))
+} finally {
+  await pool.end()
+}
+```
+
+The engine claims a case, runs its async handler outside a database transaction,
+then commits state and journal together. Executions serialize per case;
+external effects must tolerate retries.
+
+Read the [introduction](https://github.com/mochicodecom/affordance/blob/main/docs/tutorial/README.md)
+and [architecture](https://github.com/mochicodecom/affordance/blob/main/docs/architecture.md).
+The optional [HTTP adapter](https://github.com/mochicodecom/affordance/tree/main/packages/http)
+exposes available steps as links. Licensed under [MIT](./LICENSE).

package/dist/engine/compute.d.ts

@@ -0,0 +1,147 @@
+/**
+ * Affordance computation — the pure core of the engine.
+ *
+ * `computeAffordances` turns (case type, case snapshot, actor, asOf) into
+ * the framework's HATEOAS answer: every step's guard evaluated (with scope
+ * fan-out), split into available **affordances** and blocked steps with
+ * their unmet named conditions, "not possible" mechanically distinct from
+ * "not permitted for this actor". `computeExplanation` is the same
+ * machinery pointed at one step, returning the full per-condition record.
+ *
+ * Both are pure: no I/O, no clock — `asOf` is explicit (the
+ * *engine* defaults it to now at its boundary, never a condition). The
+ * records are plain JSON-serializable objects, deterministic in their
+ * inputs — the affordance JSON contract will serialize them
+ * verbatim.
+ *
+ * Addressing a step and binding its scope element is `../model/target.js`'s
+ * job rather than this module's: it is a fact about a step definition and a
+ * state, and every other consumer of it — the claim,
+ * audit replay — would otherwise have to import the engine to reach it.
+ */
+import type { StandardSchemaV1 } from '@standard-schema/spec';
+import type { ConditionResult, GuardEvaluation, Instant } from '../guards/index.js';
+import type { CaseTypeDefinition, ComputationContext } from '../model/index.js';
+/**
+ * The slice of a case the pure computation needs: identity, state, dormancy.
+ * The engine builds it from a store handle; tests may construct one directly.
+ */
+export interface CaseSnapshot<TState> {
+    readonly id: string;
+    readonly state: TState;
+    /** Dormancy marker (`end()`): a dormant case still computes — dormancy is never a freeze. */
+    readonly endedAt: Date | string | null;
+}
+/**
+ * One available affordance: a step (with its scope binding, if scoped) this
+ * actor can take now. Deliberately silent about the step's input — how an
+ * input is described to a caller is the adapter's translation
+ * (`Engine.inputSchemaFor` is the registry read it serializes from), and a
+ * second channel here could only drift from it.
+ */
+export interface Affordance {
+    readonly step: string;
+    /** The bound element's scope key — present iff the step is scoped. */
+    readonly scopeKey?: string;
+}
+/**
+ * A step (× scope element, if scoped) that is currently not available, with
+ * the unmet named conditions saying why. `possible === false` means unmet
+ * `requires` — not possible on this case, for anyone; `permitted === false`
+ * means unmet `permits` — not permitted for this actor.
+ */
+export interface BlockedStep {
+    readonly step: string;
+    readonly scopeKey?: string;
+    readonly possible: boolean;
+    readonly permitted: boolean;
+    /**
+     * The failed condition results, verbatim from guard evaluation — named,
+     * sectioned, with reasons and (for `after` conditions) basis/flip instants.
+     */
+    readonly unmet: readonly ConditionResult[];
+}
+/** The serializable affordances record for one case, one actor, one instant. */
+export interface CaseAffordances {
+    readonly caseId: string;
+    readonly caseTypeName: string;
+    /** The instant evaluated as of (ISO-8601 UTC). */
+    readonly asOf: string;
+    /** Dormancy marker (ISO-8601 UTC), `null` while the case is active. A dormant case still computes. */
+    readonly endedAt: string | null;
+    /** Available affordances, in step declaration order (scoped: selection order within a step). */
+    readonly affordances: readonly Affordance[];
+    /** Blocked steps (× scope element) with their unmet named conditions. */
+    readonly blocked: readonly BlockedStep[];
+}
+/** The full per-condition breakdown for one step (× scope element, if scoped). */
+export interface AffordanceExplanation {
+    readonly caseId: string;
+    readonly caseTypeName: string;
+    readonly step: string;
+    /** The scope binding the explanation is about — present iff the step is scoped. */
+    readonly scopeKey?: string;
+    readonly asOf: string;
+    readonly endedAt: string | null;
+    /** The guards module's full evaluation record: every condition, passed and failed. */
+    readonly evaluation: GuardEvaluation;
+}
+/**
+ * Compute the affordances record for one case snapshot: every step's guard
+ * evaluated against (state, actor, asOf); scoped steps fan out to one
+ * independent evaluation per selected element. Handlers are never
+ * touched — this is a read (guards advise; enforcement is the claim's job).
+ *
+ * A scoped step whose selector is defective is absorbed into a blocked entry
+ * under the synthetic `$scope` condition (one defective selector must not
+ * take down the case's listing); scope-*key* integrity violations throw
+ * `ScopeKeyError` (identity corruption — `selectTargets` never absorbs it).
+ * A scoped step selecting zero elements contributes nothing to either list.
+ */
+export declare const computeAffordances: <S extends StandardSchemaV1, TActor>(definition: CaseTypeDefinition<S, TActor>, snapshot: CaseSnapshot<StandardSchemaV1.InferOutput<S>>, ctx: ComputationContext<TActor>) => CaseAffordances;
+/** An `explain` request as a caller states it: everything optional. */
+export interface ExplainRequest {
+    /** Required when the step is scoped; identifies the element. */
+    readonly scopeKey?: string;
+    /** The actor to evaluate `permits` against; omit to probe `requires` alone. */
+    readonly actor?: unknown;
+    /** The instant to evaluate as of; defaults through the supplied clock. */
+    readonly asOf?: Instant;
+}
+/**
+ * Normalize an {@link ExplainRequest} into the {@link ComputationContext}
+ * the pure computation runs on — the engine boundary's one normalization,
+ * stated here so the rule and {@link computeExplanation} share a test
+ * surface:
+ *
+ * - An **absent** `actor` key means the requires-only probe ({@link NO_ACTOR}
+ *   — `permits` conditions are reported un-evaluated). A key that is
+ *   *present but `undefined`* is an actor like any other: the caller said
+ *   who is asking, and the answer is about them.
+ * - `asOf` defaults through `now` — the clock stops here; everything below
+ *   is pure.
+ * - `scopeKey` is carried only when given, so "unscoped" stays an absent
+ *   key rather than an `undefined` value.
+ */
+export declare const explainContext: <TActor = unknown>(request: ExplainRequest, now: () => Instant) => ComputationContext<TActor> & {
+    readonly scopeKey?: string;
+};
+/**
+ * The full per-condition breakdown for one step. Loud where the listing is
+ * lenient — `explain` is a targeted probe, so a step name the case type
+ * doesn't declare, a missing/unknown scope key on a scoped step, or a scope
+ * key on an unscoped step all throw with precise messages (including the
+ * currently-valid scope keys, where knowable).
+ *
+ * One deliberate exception: a scoped step whose selector is **defective**
+ * answers rather than throws. The listing publishes exactly that condition
+ * as a blocked `$scope` entry with an `explain` link, so the link must be
+ * followable — the explanation *is* the `$scope` failure, in the same shape
+ * the listing reported it.
+ *
+ * `actor` is whatever the caller supplies; to ask "why can't *this* actor",
+ * pass that actor — `permits` conditions are evaluated against it verbatim.
+ */
+export declare const computeExplanation: <S extends StandardSchemaV1, TActor>(definition: CaseTypeDefinition<S, TActor>, snapshot: CaseSnapshot<StandardSchemaV1.InferOutput<S>>, stepName: string, ctx: ComputationContext<TActor> & {
+    readonly scopeKey?: string;
+}) => AffordanceExplanation;

package/dist/engine/compute.js

@@ -0,0 +1,152 @@
+/**
+ * Affordance computation — the pure core of the engine.
+ *
+ * `computeAffordances` turns (case type, case snapshot, actor, asOf) into
+ * the framework's HATEOAS answer: every step's guard evaluated (with scope
+ * fan-out), split into available **affordances** and blocked steps with
+ * their unmet named conditions, "not possible" mechanically distinct from
+ * "not permitted for this actor". `computeExplanation` is the same
+ * machinery pointed at one step, returning the full per-condition record.
+ *
+ * Both are pure: no I/O, no clock — `asOf` is explicit (the
+ * *engine* defaults it to now at its boundary, never a condition). The
+ * records are plain JSON-serializable objects, deterministic in their
+ * inputs — the affordance JSON contract will serialize them
+ * verbatim.
+ *
+ * Addressing a step and binding its scope element is `../model/target.js`'s
+ * job rather than this module's: it is a fact about a step definition and a
+ * state, and every other consumer of it — the claim,
+ * audit replay — would otherwise have to import the engine to reach it.
+ */
+import { NO_ACTOR, toIso, unmetConditions } from '../guards/index.js';
+import { addressTarget, evaluateTarget, scopeFailureEvaluation, selectTargets, } from '../model/index.js';
+const toIsoOrNull = (value) => value === null ? null : toIso(value);
+// The verdict lives with the model (`scopeFailureEvaluation`); this only
+// reshapes it into a blocked entry.
+const scopeFailureEntry = (stepName, asOf, reason) => {
+    const evaluation = scopeFailureEvaluation(asOf, { reason });
+    return {
+        step: stepName,
+        possible: evaluation.possible,
+        permitted: evaluation.permitted,
+        unmet: unmetConditions(evaluation),
+    };
+};
+const toAffordance = (stepName, scopeKey) => ({
+    step: stepName,
+    ...(scopeKey !== undefined && { scopeKey }),
+});
+const toBlocked = (stepName, evaluation, scopeKey) => ({
+    step: stepName,
+    ...(scopeKey !== undefined && { scopeKey }),
+    possible: evaluation.possible,
+    permitted: evaluation.permitted,
+    unmet: unmetConditions(evaluation),
+});
+/**
+ * Compute the affordances record for one case snapshot: every step's guard
+ * evaluated against (state, actor, asOf); scoped steps fan out to one
+ * independent evaluation per selected element. Handlers are never
+ * touched — this is a read (guards advise; enforcement is the claim's job).
+ *
+ * A scoped step whose selector is defective is absorbed into a blocked entry
+ * under the synthetic `$scope` condition (one defective selector must not
+ * take down the case's listing); scope-*key* integrity violations throw
+ * `ScopeKeyError` (identity corruption — `selectTargets` never absorbs it).
+ * A scoped step selecting zero elements contributes nothing to either list.
+ */
+export const computeAffordances = (definition, snapshot, ctx) => {
+    const asOf = toIso(ctx.asOf);
+    const affordances = [];
+    const blocked = [];
+    for (const stepDefinition of definition.steps) {
+        const { targets, failure } = selectTargets(stepDefinition, snapshot.state);
+        if (failure !== null) {
+            blocked.push(scopeFailureEntry(stepDefinition.name, asOf, failure.reason));
+            continue;
+        }
+        for (const target of targets) {
+            const evaluation = evaluateTarget(target, { actor: ctx.actor, asOf });
+            const scopeKey = target.binding?.key;
+            if (evaluation.available)
+                affordances.push(toAffordance(stepDefinition.name, scopeKey));
+            else
+                blocked.push(toBlocked(stepDefinition.name, evaluation, scopeKey));
+        }
+    }
+    return {
+        caseId: snapshot.id,
+        caseTypeName: definition.name,
+        asOf,
+        endedAt: toIsoOrNull(snapshot.endedAt),
+        affordances,
+        blocked,
+    };
+};
+/**
+ * Normalize an {@link ExplainRequest} into the {@link ComputationContext}
+ * the pure computation runs on — the engine boundary's one normalization,
+ * stated here so the rule and {@link computeExplanation} share a test
+ * surface:
+ *
+ * - An **absent** `actor` key means the requires-only probe ({@link NO_ACTOR}
+ *   — `permits` conditions are reported un-evaluated). A key that is
+ *   *present but `undefined`* is an actor like any other: the caller said
+ *   who is asking, and the answer is about them.
+ * - `asOf` defaults through `now` — the clock stops here; everything below
+ *   is pure.
+ * - `scopeKey` is carried only when given, so "unscoped" stays an absent
+ *   key rather than an `undefined` value.
+ */
+export const explainContext = (request, now) => ({
+    // The request's actor is caller-supplied and untyped, and NO_ACTOR is the
+    // evaluator's own marker; the assertion papers over neither — `permits`
+    // conditions must be total over whatever an actor turns out to be.
+    actor: ('actor' in request ? request.actor : NO_ACTOR),
+    asOf: request.asOf ?? now(),
+    ...(request.scopeKey !== undefined && { scopeKey: request.scopeKey }),
+});
+/**
+ * The full per-condition breakdown for one step. Loud where the listing is
+ * lenient — `explain` is a targeted probe, so a step name the case type
+ * doesn't declare, a missing/unknown scope key on a scoped step, or a scope
+ * key on an unscoped step all throw with precise messages (including the
+ * currently-valid scope keys, where knowable).
+ *
+ * One deliberate exception: a scoped step whose selector is **defective**
+ * answers rather than throws. The listing publishes exactly that condition
+ * as a blocked `$scope` entry with an `explain` link, so the link must be
+ * followable — the explanation *is* the `$scope` failure, in the same shape
+ * the listing reported it.
+ *
+ * `actor` is whatever the caller supplies; to ask "why can't *this* actor",
+ * pass that actor — `permits` conditions are evaluated against it verbatim.
+ */
+export const computeExplanation = (definition, snapshot, stepName, ctx) => {
+    const asOf = toIso(ctx.asOf);
+    const identity = {
+        caseId: snapshot.id,
+        caseTypeName: definition.name,
+        step: stepName,
+        asOf,
+        endedAt: toIsoOrNull(snapshot.endedAt),
+    };
+    const address = addressTarget(definition, snapshot.state, stepName, ctx.scopeKey);
+    if (address.failure !== null) {
+        if (address.failure.kind === 'defective-selector') {
+            return {
+                ...identity,
+                evaluation: scopeFailureEvaluation(asOf, address.failure),
+            };
+        }
+        throw address.failure.error;
+    }
+    const target = address.target;
+    return {
+        ...identity,
+        ...(target.binding !== null && { scopeKey: target.binding.key }),
+        evaluation: evaluateTarget(target, { actor: ctx.actor, asOf }),
+    };
+};
+//# sourceMappingURL=compute.js.map

package/dist/engine/compute.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compute.js","sourceRoot":"","sources":["../../src/engine/compute.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Affordance computation — the pure core of the engine.\n *\n * `computeAffordances` turns (case type, case snapshot, actor, asOf) into\n * the framework's HATEOAS answer: every step's guard evaluated (with scope\n * fan-out), split into available **affordances** and blocked steps with\n * their unmet named conditions, \"not possible\" mechanically distinct from\n * \"not permitted for this actor\". `computeExplanation` is the same\n * machinery pointed at one step, returning the full per-condition record.\n *\n * Both are pure: no I/O, no clock — `asOf` is explicit (the\n * *engine* defaults it to now at its boundary, never a condition). The\n * records are plain JSON-serializable objects, deterministic in their\n * inputs — the affordance JSON contract will serialize them\n * verbatim.\n *\n * Addressing a step and binding its scope element is `../model/target.js`'s\n * job rather than this module's: it is a fact about a step definition and a\n * state, and every other consumer of it — the claim,\n * audit replay — would otherwise have to import the engine to reach it.\n */\n\nimport type { StandardSchemaV1 } from '@standard-schema/spec'\nimport type {\n  ConditionResult,\n  GuardEvaluation,\n  Instant,\n} from '../guards/index.js'\nimport { NO_ACTOR, toIso, unmetConditions } from '../guards/index.js'\nimport type { CaseTypeDefinition, ComputationContext } from '../model/index.js'\nimport {\n  addressTarget,\n  evaluateTarget,\n  scopeFailureEvaluation,\n  selectTargets,\n} from '../model/index.js'\n\n/**\n * The slice of a case the pure computation needs: identity, state, dormancy.\n * The engine builds it from a store handle; tests may construct one directly.\n */\nexport interface CaseSnapshot<TState> {\n  readonly id: string\n  readonly state: TState\n  /** Dormancy marker (`end()`): a dormant case still computes — dormancy is never a freeze. */\n  readonly endedAt: Date | string | null\n}\n\n/**\n * One available affordance: a step (with its scope binding, if scoped) this\n * actor can take now. Deliberately silent about the step's input — how an\n * input is described to a caller is the adapter's translation\n * (`Engine.inputSchemaFor` is the registry read it serializes from), and a\n * second channel here could only drift from it.\n */\nexport interface Affordance {\n  readonly step: string\n  /** The bound element's scope key — present iff the step is scoped. */\n  readonly scopeKey?: string\n}\n\n/**\n * A step (× scope element, if scoped) that is currently not available, with\n * the unmet named conditions saying why. `possible === false` means unmet\n * `requires` — not possible on this case, for anyone; `permitted === false`\n * means unmet `permits` — not permitted for this actor.\n */\nexport interface BlockedStep {\n  readonly step: string\n  readonly scopeKey?: string\n  readonly possible: boolean\n  readonly permitted: boolean\n  /**\n   * The failed condition results, verbatim from guard evaluation — named,\n   * sectioned, with reasons and (for `after` conditions) basis/flip instants.\n   */\n  readonly unmet: readonly ConditionResult[]\n}\n\n/** The serializable affordances record for one case, one actor, one instant. */\nexport interface CaseAffordances {\n  readonly caseId: string\n  readonly caseTypeName: string\n  /** The instant evaluated as of (ISO-8601 UTC). */\n  readonly asOf: string\n  /** Dormancy marker (ISO-8601 UTC), `null` while the case is active. A dormant case still computes. */\n  readonly endedAt: string | null\n  /** Available affordances, in step declaration order (scoped: selection order within a step). */\n  readonly affordances: readonly Affordance[]\n  /** Blocked steps (× scope element) with their unmet named conditions. */\n  readonly blocked: readonly BlockedStep[]\n}\n\n/** The full per-condition breakdown for one step (× scope element, if scoped). */\nexport interface AffordanceExplanation {\n  readonly caseId: string\n  readonly caseTypeName: string\n  readonly step: string\n  /** The scope binding the explanation is about — present iff the step is scoped. */\n  readonly scopeKey?: string\n  readonly asOf: string\n  readonly endedAt: string | null\n  /** The guards module's full evaluation record: every condition, passed and failed. */\n  readonly evaluation: GuardEvaluation\n}\n\nconst toIsoOrNull = (value: Instant | null): string | null =>\n  value === null ? null : toIso(value)\n\n// The verdict lives with the model (`scopeFailureEvaluation`); this only\n// reshapes it into a blocked entry.\nconst scopeFailureEntry = (\n  stepName: string,\n  asOf: string,\n  reason: string,\n): BlockedStep => {\n  const evaluation = scopeFailureEvaluation(asOf, { reason })\n  return {\n    step: stepName,\n    possible: evaluation.possible,\n    permitted: evaluation.permitted,\n    unmet: unmetConditions(evaluation),\n  }\n}\n\nconst toAffordance = (stepName: string, scopeKey?: string): Affordance => ({\n  step: stepName,\n  ...(scopeKey !== undefined && { scopeKey }),\n})\n\nconst toBlocked = (\n  stepName: string,\n  evaluation: GuardEvaluation,\n  scopeKey?: string,\n): BlockedStep => ({\n  step: stepName,\n  ...(scopeKey !== undefined && { scopeKey }),\n  possible: evaluation.possible,\n  permitted: evaluation.permitted,\n  unmet: unmetConditions(evaluation),\n})\n\n/**\n * Compute the affordances record for one case snapshot: every step's guard\n * evaluated against (state, actor, asOf); scoped steps fan out to one\n * independent evaluation per selected element. Handlers are never\n * touched — this is a read (guards advise; enforcement is the claim's job).\n *\n * A scoped step whose selector is defective is absorbed into a blocked entry\n * under the synthetic `$scope` condition (one defective selector must not\n * take down the case's listing); scope-*key* integrity violations throw\n * `ScopeKeyError` (identity corruption — `selectTargets` never absorbs it).\n * A scoped step selecting zero elements contributes nothing to either list.\n */\nexport const computeAffordances = <S extends StandardSchemaV1, TActor>(\n  definition: CaseTypeDefinition<S, TActor>,\n  snapshot: CaseSnapshot<StandardSchemaV1.InferOutput<S>>,\n  ctx: ComputationContext<TActor>,\n): CaseAffordances => {\n  const asOf = toIso(ctx.asOf)\n  const affordances: Affordance[] = []\n  const blocked: BlockedStep[] = []\n\n  for (const stepDefinition of definition.steps) {\n    const { targets, failure } = selectTargets(stepDefinition, snapshot.state)\n    if (failure !== null) {\n      blocked.push(scopeFailureEntry(stepDefinition.name, asOf, failure.reason))\n      continue\n    }\n    for (const target of targets) {\n      const evaluation = evaluateTarget(target, { actor: ctx.actor, asOf })\n      const scopeKey = target.binding?.key\n      if (evaluation.available)\n        affordances.push(toAffordance(stepDefinition.name, scopeKey))\n      else blocked.push(toBlocked(stepDefinition.name, evaluation, scopeKey))\n    }\n  }\n\n  return {\n    caseId: snapshot.id,\n    caseTypeName: definition.name,\n    asOf,\n    endedAt: toIsoOrNull(snapshot.endedAt),\n    affordances,\n    blocked,\n  }\n}\n\n/** An `explain` request as a caller states it: everything optional. */\nexport interface ExplainRequest {\n  /** Required when the step is scoped; identifies the element. */\n  readonly scopeKey?: string\n  /** The actor to evaluate `permits` against; omit to probe `requires` alone. */\n  readonly actor?: unknown\n  /** The instant to evaluate as of; defaults through the supplied clock. */\n  readonly asOf?: Instant\n}\n\n/**\n * Normalize an {@link ExplainRequest} into the {@link ComputationContext}\n * the pure computation runs on — the engine boundary's one normalization,\n * stated here so the rule and {@link computeExplanation} share a test\n * surface:\n *\n * - An **absent** `actor` key means the requires-only probe ({@link NO_ACTOR}\n *   — `permits` conditions are reported un-evaluated). A key that is\n *   *present but `undefined`* is an actor like any other: the caller said\n *   who is asking, and the answer is about them.\n * - `asOf` defaults through `now` — the clock stops here; everything below\n *   is pure.\n * - `scopeKey` is carried only when given, so \"unscoped\" stays an absent\n *   key rather than an `undefined` value.\n */\nexport const explainContext = <TActor = unknown>(\n  request: ExplainRequest,\n  now: () => Instant,\n): ComputationContext<TActor> & { readonly scopeKey?: string } => ({\n  // The request's actor is caller-supplied and untyped, and NO_ACTOR is the\n  // evaluator's own marker; the assertion papers over neither — `permits`\n  // conditions must be total over whatever an actor turns out to be.\n  actor: ('actor' in request ? request.actor : NO_ACTOR) as TActor,\n  asOf: request.asOf ?? now(),\n  ...(request.scopeKey !== undefined && { scopeKey: request.scopeKey }),\n})\n\n/**\n * The full per-condition breakdown for one step. Loud where the listing is\n * lenient — `explain` is a targeted probe, so a step name the case type\n * doesn't declare, a missing/unknown scope key on a scoped step, or a scope\n * key on an unscoped step all throw with precise messages (including the\n * currently-valid scope keys, where knowable).\n *\n * One deliberate exception: a scoped step whose selector is **defective**\n * answers rather than throws. The listing publishes exactly that condition\n * as a blocked `$scope` entry with an `explain` link, so the link must be\n * followable — the explanation *is* the `$scope` failure, in the same shape\n * the listing reported it.\n *\n * `actor` is whatever the caller supplies; to ask \"why can't *this* actor\",\n * pass that actor — `permits` conditions are evaluated against it verbatim.\n */\nexport const computeExplanation = <S extends StandardSchemaV1, TActor>(\n  definition: CaseTypeDefinition<S, TActor>,\n  snapshot: CaseSnapshot<StandardSchemaV1.InferOutput<S>>,\n  stepName: string,\n  ctx: ComputationContext<TActor> & { readonly scopeKey?: string },\n): AffordanceExplanation => {\n  const asOf = toIso(ctx.asOf)\n  const identity = {\n    caseId: snapshot.id,\n    caseTypeName: definition.name,\n    step: stepName,\n    asOf,\n    endedAt: toIsoOrNull(snapshot.endedAt),\n  }\n\n  const address = addressTarget(\n    definition,\n    snapshot.state,\n    stepName,\n    ctx.scopeKey,\n  )\n  if (address.failure !== null) {\n    if (address.failure.kind === 'defective-selector') {\n      return {\n        ...identity,\n        evaluation: scopeFailureEvaluation(asOf, address.failure),\n      }\n    }\n    throw address.failure.error\n  }\n  const target = address.target\n  return {\n    ...identity,\n    ...(target.binding !== null && { scopeKey: target.binding.key }),\n    evaluation: evaluateTarget(target, { actor: ctx.actor, asOf }),\n  }\n}\n"]}

package/dist/engine/engine.d.ts

@@ -0,0 +1,162 @@
+/**
+ * The engine: the case-type registry bound to the case store.
+ *
+ * `createEngine({ db, caseTypes })` wires the halves together — persistence
+ * (`../store`), guard evaluation (`../guards`), the definition API
+ * (`../model`) and the execution lifecycle (`../execution`) — into the
+ * framework's public face: `affordances`, `explain`, `execute`, `journal`.
+ *
+ * The engine is where `asOf` defaults to now: conditions never read the
+ * clock, so `EngineOptions.now` — wall clock by default — is the one clock,
+ * threaded through the environment to everything below, and everything below
+ * it is pure and reconstructable.
+ */
+import type { StandardSchemaV1 } from '@standard-schema/spec';
+import type { ExecuteOptions, ExecutionResult, JournalEntry, JournalFilter } from '../execution/index.js';
+import type { Instant } from '../guards/index.js';
+import type { Correlation, CorrelationRegistration, DeadLetter, DeadLetterFilter, ExternalEvent, IngestionOptions, IngestionResult } from '../ingestion/index.js';
+import type { MigrationOptions, MigrationReport, MigrationTransform } from '../migration/index.js';
+import type { AnyCaseType, StepMetadata } from '../model/index.js';
+import type { CaseHandle, DatabaseAccess } from '../store/index.js';
+import type { AffordanceExplanation, CaseAffordances, ExplainRequest } from './compute.js';
+/** Options for {@link createEngine}. */
+export interface EngineOptions {
+    /**
+     * The app brings its database, declaring which kind of handle it has:
+     * `{ pool }` for anything that checks out connections (`pg.Pool`, or any
+     * wrapper declaring `connect()`), `{ client }` for a single connection
+     * dedicated to the engine. The declaration is what lets `execute` run its
+     * transactions on one connection without guessing — see
+     * {@link DatabaseAccess}.
+     */
+    readonly db: DatabaseAccess;
+    /** Every case type this engine serves; a loaded case's `case_type` must name one of them. */
+    readonly caseTypes: readonly AnyCaseType[];
+    /**
+     * How long an Execution's claim survives without a heartbeat (default 30s).
+     * The floor on how long a crashed handler can hold a case.
+     */
+    readonly claimTtlMs?: number;
+    /** How often a running handler refreshes its claim (default 5s). */
+    readonly heartbeatMs?: number;
+    /**
+     * Event ingestion: how an external event's Actor is derived.
+     * Correlation needs no configuration — it is a registry, not a policy.
+     */
+    readonly ingestion?: IngestionOptions;
+    /**
+     * The clock — every process-side "as of now" below the boundary reads
+     * through it: guard evaluation instants, journal timestamps, ingestion
+     * receipt times. Defaults to the wall clock. Two "nows" it deliberately
+     * does not govern: lease expiry is judged by the storage adapter's own
+     * clock (the one clock all competing processes share), and the retry
+     * delay / heartbeat cadence run on process timers (an internal seam the
+     * lifecycle's own tests drive virtually).
+     */
+    readonly now?: () => Date;
+}
+/**
+ * Options for {@link Engine.explain}. Omit `actor` to probe `requires`
+ * alone: `permits` conditions are then reported un-evaluated (failed, with
+ * the stated reason `'not evaluated: no actor supplied'`) rather than run
+ * against nothing. The normalization rule is `explainContext`, stated and
+ * tested beside the pure computation it feeds.
+ */
+export type ExplainOptions = ExplainRequest;
+export interface Engine {
+    /**
+     * Create a case of a registered case type. The initial state is validated
+     * against the type's schema.
+     */
+    createCase(caseTypeName: string, initialState: unknown): Promise<CaseHandle<unknown>>;
+    /**
+     * Compute the affordances record for a case: load it, evaluate every
+     * step's guard for `actor` (with scope fan-out), and return the
+     * serializable available + blocked answer. Dormant (ended) cases compute
+     * like any other — dormancy is annotation, never a freeze.
+     */
+    affordances(caseId: string, actor: unknown, asOf?: Instant): Promise<CaseAffordances>;
+    /**
+     * {@link Engine.affordances} for a case already in hand — no second load,
+     * no re-validation. Synchronous: a registry read plus the pure
+     * computation. The handle must be one this engine issued
+     * ({@link Engine.createCase}, {@link Engine.case}) — their `state` is the
+     * validated document; a hand-built handle carries no such guarantee.
+     * This is how a create route answers with the fresh case's affordances
+     * without re-reading what it just wrote.
+     */
+    affordancesOf(handle: CaseHandle<unknown>, actor: unknown, asOf?: Instant): CaseAffordances;
+    /** The full per-condition breakdown for one step (× scope element) of a case. */
+    explain(caseId: string, stepName: string, options?: ExplainOptions): Promise<AffordanceExplanation>;
+    /**
+     * Execute a step on a case: claim → run → commit. The claim
+     * re-evaluates the guard transactionally — the enforcement moment — so an
+     * affordance that has since gone away rejects with `StepNotAvailableError`
+     * carrying the current unmet conditions, and a case with an Execution
+     * already in flight rejects with `CaseBusyError`.
+     */
+    execute(caseId: string, stepName: string, options: ExecuteOptions): Promise<ExecutionResult>;
+    /**
+     * Read a case's journal, oldest first. Filter by `scopeKey` for
+     * a per-track audit — "everything that happened on buyer #7".
+     */
+    journal(caseId: string, filter?: JournalFilter): Promise<readonly JournalEntry[]>;
+    /**
+     * Read one case as persisted: the row plus its Case State validated
+     * against the registered schema. Loud — an addressed read owes an answer,
+     * so an unknown case or a state its schema no longer accepts throws.
+     * The read ops surfaces, tests and consoles would otherwise each
+     * hand-write in SQL.
+     */
+    case(caseId: string): Promise<CaseHandle<unknown>>;
+    /** Where an external identifier routes — the reverse of {@link Engine.correlations}. */
+    correlationOf(system: string, externalId: string): Promise<Correlation | null>;
+    /**
+     * The declared input schema of one step of a registered case type, or
+     * `null` when the step takes no input. Synchronous — a registry read. The
+     * engine owns the registry and a case names its type, so an adapter never
+     * needs to be handed the case types a second time to describe inputs.
+     */
+    inputSchemaFor(caseTypeName: string, stepName: string): StandardSchemaV1 | null;
+    /**
+     * The declared human metadata of one step of a registered case type —
+     * `title` and `description`, each `null` when undeclared — or `null` for
+     * an unknown step. Synchronous, a registry read like
+     * {@link Engine.inputSchemaFor}, and for the same reason: adapters
+     * serialize step metadata from here rather than being handed the case
+     * types a second time.
+     */
+    stepMetadataFor(caseTypeName: string, stepName: string): StepMetadata | null;
+    /**
+     * Ingest one external event: dedup, correlate, then an ordinary Execution
+     * with the external system as the actor. Never throws for an
+     * event's own sake — an event that could not be applied is dead-lettered
+     * with a reason, so a webhook endpoint can acknowledge and move on.
+     */
+    ingest(event: ExternalEvent): Promise<IngestionResult>;
+    /**
+     * Register an external identifier against a case out of band. Handlers
+     * should prefer `ctx.correlate(...)`, which rides the same commit as the
+     * state recording that the interaction was started.
+     */
+    correlate(registration: CorrelationRegistration): Promise<Correlation>;
+    /** Every external identifier registered against a case (× scope element). */
+    correlations(caseId: string, scopeKey?: string): Promise<readonly Correlation[]>;
+    /** The dead-letter surface: events that arrived and changed nothing, with why. */
+    deadLetters(filter?: DeadLetterFilter): Promise<readonly DeadLetter[]>;
+    /**
+     * Restructure the state of every case of a case type, as journaled system
+     * Executions (float's escape hatch). Idempotent: a case that
+     * already carries the migration's marker is skipped, so re-running is a
+     * no-op and an interrupted run resumes. Reach for it only when no total
+     * condition can read the old shape — see `docs/migration.md`.
+     */
+    migrate(caseTypeName: string, name: string, transform: MigrationTransform, options?: MigrationOptions): Promise<MigrationReport>;
+}
+/**
+ * Build an engine from the app's database and its case type definitions.
+ * Throws at construction on duplicate case type names — the registry is
+ * keyed by name, which is all a case row records (definitions
+ * float; only the name is persisted).
+ */
+export declare const createEngine: (options: EngineOptions) => Engine;