@affordance/core 0.1.0

package/dist/execution/replay.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Audit reconstruction.
+ *
+ * "Why was this affordance available last Tuesday?" is answered from the
+ * journaled record of what the system actually believed at the time, never by
+ * re-deriving the past through present-day code. A `claimed` entry
+ * carries everything that answer needs: the guard evaluation, the instant it
+ * was made as of, the Actor, and the Case State it was evaluated against.
+ *
+ * `replayGuard` re-runs **today's** definition against **that** recorded
+ * moment and reports both results side by side. A mismatch is not a bug in
+ * the journal — it is the interesting signal: cases float to the latest
+ * definitions, so it means the step's guard changed since the
+ * Execution ran, and it says exactly how.
+ *
+ * Replay is a sweep over the Journal, so it is the lenient filter over
+ * {@link addressTarget}: a journaled moment today's definitions can no
+ * longer address — the step was removed, the element its scope key named no
+ * longer selects, the selector throws over the historical document — is
+ * itself definition drift, reported as `unaddressable` rather than thrown.
+ * One drifted entry must never take down an audit of the rest.
+ */
+import type { GuardEvaluation } from '../guards/index.js';
+import type { AnyCaseType } from '../model/index.js';
+import type { ClaimedJournalEntry } from './journal.js';
+/** What today's definitions make of a journaled moment. */
+export interface GuardReplay {
+    readonly executionId: string;
+    readonly step: string;
+    readonly scopeKey: string | null;
+    /** The instant the recorded evaluation was made as of. */
+    readonly asOf: string;
+    /** The guard results as journaled at the enforcement moment. */
+    readonly recorded: GuardEvaluation;
+    /**
+     * The same guard, re-evaluated now against the journaled state, actor and
+     * instant — or `null` when today's definitions cannot address the
+     * journaled (step × scope key) at all.
+     */
+    readonly reproduced: GuardEvaluation | null;
+    /** True when the two agree exactly — the definitions have not drifted for this step. */
+    readonly matches: boolean;
+    /**
+     * Why today's definitions could not address the journaled moment, when
+     * they could not — the strongest form of drift. `null` when `reproduced`
+     * is present.
+     */
+    readonly unaddressable: {
+        readonly reason: string;
+    } | null;
+}
+/**
+ * Re-evaluate a `claimed` entry's guard against the state, actor and instant
+ * the entry recorded. Only `claimed` entries carry an evaluation to
+ * reproduce, and the parameter type says so — narrow a read entry with
+ * `isClaimedEntry` first.
+ */
+export declare const replayGuard: (definition: AnyCaseType, entry: ClaimedJournalEntry) => GuardReplay;

package/dist/execution/replay.js

@@ -0,0 +1,59 @@
+/**
+ * Audit reconstruction.
+ *
+ * "Why was this affordance available last Tuesday?" is answered from the
+ * journaled record of what the system actually believed at the time, never by
+ * re-deriving the past through present-day code. A `claimed` entry
+ * carries everything that answer needs: the guard evaluation, the instant it
+ * was made as of, the Actor, and the Case State it was evaluated against.
+ *
+ * `replayGuard` re-runs **today's** definition against **that** recorded
+ * moment and reports both results side by side. A mismatch is not a bug in
+ * the journal — it is the interesting signal: cases float to the latest
+ * definitions, so it means the step's guard changed since the
+ * Execution ran, and it says exactly how.
+ *
+ * Replay is a sweep over the Journal, so it is the lenient filter over
+ * {@link addressTarget}: a journaled moment today's definitions can no
+ * longer address — the step was removed, the element its scope key named no
+ * longer selects, the selector throws over the historical document — is
+ * itself definition drift, reported as `unaddressable` rather than thrown.
+ * One drifted entry must never take down an audit of the rest.
+ */
+import { addressTarget, evaluateTarget } from '../model/index.js';
+import { jsonEqual } from './delta.js';
+/**
+ * Re-evaluate a `claimed` entry's guard against the state, actor and instant
+ * the entry recorded. Only `claimed` entries carry an evaluation to
+ * reproduce, and the parameter type says so — narrow a read entry with
+ * `isClaimedEntry` first.
+ */
+export const replayGuard = (definition, entry) => {
+    const identity = {
+        executionId: entry.executionId,
+        step: entry.step,
+        scopeKey: entry.scopeKey,
+        asOf: entry.asOf,
+        recorded: entry.guard,
+    };
+    const address = addressTarget(definition, entry.state, entry.step, entry.scopeKey ?? undefined);
+    if (address.failure !== null) {
+        return {
+            ...identity,
+            reproduced: null,
+            matches: false,
+            unaddressable: { reason: address.failure.error.message },
+        };
+    }
+    const reproduced = evaluateTarget(address.target, {
+        actor: entry.actor,
+        asOf: entry.asOf,
+    });
+    return {
+        ...identity,
+        reproduced,
+        matches: jsonEqual(entry.guard, reproduced),
+        unaddressable: null,
+    };
+};
+//# sourceMappingURL=replay.js.map

package/dist/execution/replay.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"replay.js","sourceRoot":"","sources":["../../src/execution/replay.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAIH,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAA;AACjE,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AA4BtC;;;;;GAKG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CACzB,UAAuB,EACvB,KAA0B,EACb,EAAE;IACf,MAAM,QAAQ,GAAG;QACf,WAAW,EAAE,KAAK,CAAC,WAAW;QAC9B,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,QAAQ,EAAE,KAAK,CAAC,KAAK;KACtB,CAAA;IACD,MAAM,OAAO,GAAG,aAAa,CAC3B,UAAU,EACV,KAAK,CAAC,KAAK,EACX,KAAK,CAAC,IAAI,EACV,KAAK,CAAC,QAAQ,IAAI,SAAS,CAC5B,CAAA;IACD,IAAI,OAAO,CAAC,OAAO,KAAK,IAAI,EAAE,CAAC;QAC7B,OAAO;YACL,GAAG,QAAQ;YACX,UAAU,EAAE,IAAI;YAChB,OAAO,EAAE,KAAK;YACd,aAAa,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,OAAO,EAAE;SACzD,CAAA;IACH,CAAC;IACD,MAAM,UAAU,GAAG,cAAc,CAAC,OAAO,CAAC,MAAM,EAAE;QAChD,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,IAAI,EAAE,KAAK,CAAC,IAAI;KACjB,CAAC,CAAA;IACF,OAAO;QACL,GAAG,QAAQ;QACX,UAAU;QACV,OAAO,EAAE,SAAS,CAAC,KAAK,CAAC,KAAK,EAAE,UAAU,CAAC;QAC3C,aAAa,EAAE,IAAI;KACpB,CAAA;AACH,CAAC,CAAA","sourcesContent":["/**\n * Audit reconstruction.\n *\n * \"Why was this affordance available last Tuesday?\" is answered from the\n * journaled record of what the system actually believed at the time, never by\n * re-deriving the past through present-day code. A `claimed` entry\n * carries everything that answer needs: the guard evaluation, the instant it\n * was made as of, the Actor, and the Case State it was evaluated against.\n *\n * `replayGuard` re-runs **today's** definition against **that** recorded\n * moment and reports both results side by side. A mismatch is not a bug in\n * the journal — it is the interesting signal: cases float to the latest\n * definitions, so it means the step's guard changed since the\n * Execution ran, and it says exactly how.\n *\n * Replay is a sweep over the Journal, so it is the lenient filter over\n * {@link addressTarget}: a journaled moment today's definitions can no\n * longer address — the step was removed, the element its scope key named no\n * longer selects, the selector throws over the historical document — is\n * itself definition drift, reported as `unaddressable` rather than thrown.\n * One drifted entry must never take down an audit of the rest.\n */\n\nimport type { GuardEvaluation } from '../guards/index.js'\nimport type { AnyCaseType } from '../model/index.js'\nimport { addressTarget, evaluateTarget } from '../model/index.js'\nimport { jsonEqual } from './delta.js'\nimport type { ClaimedJournalEntry } from './journal.js'\n\n/** What today's definitions make of a journaled moment. */\nexport interface GuardReplay {\n  readonly executionId: string\n  readonly step: string\n  readonly scopeKey: string | null\n  /** The instant the recorded evaluation was made as of. */\n  readonly asOf: string\n  /** The guard results as journaled at the enforcement moment. */\n  readonly recorded: GuardEvaluation\n  /**\n   * The same guard, re-evaluated now against the journaled state, actor and\n   * instant — or `null` when today's definitions cannot address the\n   * journaled (step × scope key) at all.\n   */\n  readonly reproduced: GuardEvaluation | null\n  /** True when the two agree exactly — the definitions have not drifted for this step. */\n  readonly matches: boolean\n  /**\n   * Why today's definitions could not address the journaled moment, when\n   * they could not — the strongest form of drift. `null` when `reproduced`\n   * is present.\n   */\n  readonly unaddressable: { readonly reason: string } | null\n}\n\n/**\n * Re-evaluate a `claimed` entry's guard against the state, actor and instant\n * the entry recorded. Only `claimed` entries carry an evaluation to\n * reproduce, and the parameter type says so — narrow a read entry with\n * `isClaimedEntry` first.\n */\nexport const replayGuard = (\n  definition: AnyCaseType,\n  entry: ClaimedJournalEntry,\n): GuardReplay => {\n  const identity = {\n    executionId: entry.executionId,\n    step: entry.step,\n    scopeKey: entry.scopeKey,\n    asOf: entry.asOf,\n    recorded: entry.guard,\n  }\n  const address = addressTarget(\n    definition,\n    entry.state,\n    entry.step,\n    entry.scopeKey ?? undefined,\n  )\n  if (address.failure !== null) {\n    return {\n      ...identity,\n      reproduced: null,\n      matches: false,\n      unaddressable: { reason: address.failure.error.message },\n    }\n  }\n  const reproduced = evaluateTarget(address.target, {\n    actor: entry.actor,\n    asOf: entry.asOf,\n  })\n  return {\n    ...identity,\n    reproduced,\n    matches: jsonEqual(entry.guard, reproduced),\n    unaddressable: null,\n  }\n}\n"]}

package/dist/execution/timers.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The process-timer half of the lifecycle's clock.
+ *
+ * `now` answers "what time is it"; these answer "wake me later" — the retry
+ * delay and the heartbeat. They are a seam for the same reason `now` is:
+ * the lease story (renewal past the TTL, backoff between attempts) is only
+ * testable when a test can drive elapsed time instead of sleeping through
+ * it. The engine always binds {@link realTimers}; the in-memory lifecycle
+ * tests bind a virtual clock that advances `now` and fires due timers
+ * together.
+ */
+export interface Timers {
+    /** Resolve after `ms` — the delay between retry attempts. */
+    readonly sleep: (ms: number) => Promise<void>;
+    /**
+     * Run `fn` every `ms` until the returned stop function is called — the
+     * heartbeat.
+     */
+    readonly every: (ms: number, fn: () => void) => () => void;
+}
+export declare const realTimers: Timers;

package/dist/execution/timers.js

@@ -0,0 +1,26 @@
+/**
+ * The process-timer half of the lifecycle's clock.
+ *
+ * `now` answers "what time is it"; these answer "wake me later" — the retry
+ * delay and the heartbeat. They are a seam for the same reason `now` is:
+ * the lease story (renewal past the TTL, backoff between attempts) is only
+ * testable when a test can drive elapsed time instead of sleeping through
+ * it. The engine always binds {@link realTimers}; the in-memory lifecycle
+ * tests bind a virtual clock that advances `now` and fires due timers
+ * together.
+ */
+export const realTimers = {
+    // Deliberately not unref'd: a retry delay is work in progress, and a
+    // process that exits during one abandons a claimed Execution.
+    sleep: (ms) => ms <= 0
+        ? Promise.resolve()
+        : new Promise((resolve) => {
+            setTimeout(resolve, ms);
+        }),
+    every: (ms, fn) => {
+        const timer = setInterval(fn, ms);
+        timer.unref?.();
+        return () => clearInterval(timer);
+    },
+};
+//# sourceMappingURL=timers.js.map

package/dist/execution/timers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"timers.js","sourceRoot":"","sources":["../../src/execution/timers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAYH,MAAM,CAAC,MAAM,UAAU,GAAW;IAChC,qEAAqE;IACrE,8DAA8D;IAC9D,KAAK,EAAE,CAAC,EAAE,EAAE,EAAE,CACZ,EAAE,IAAI,CAAC;QACL,CAAC,CAAC,OAAO,CAAC,OAAO,EAAE;QACnB,CAAC,CAAC,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;YACtB,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAA;QACzB,CAAC,CAAC;IACR,KAAK,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE;QAChB,MAAM,KAAK,GAAG,WAAW,CAAC,EAAE,EAAE,EAAE,CAAC,CAAA;QACjC,KAAK,CAAC,KAAK,EAAE,EAAE,CAAA;QACf,OAAO,GAAG,EAAE,CAAC,aAAa,CAAC,KAAK,CAAC,CAAA;IACnC,CAAC;CACF,CAAA","sourcesContent":["/**\n * The process-timer half of the lifecycle's clock.\n *\n * `now` answers \"what time is it\"; these answer \"wake me later\" — the retry\n * delay and the heartbeat. They are a seam for the same reason `now` is:\n * the lease story (renewal past the TTL, backoff between attempts) is only\n * testable when a test can drive elapsed time instead of sleeping through\n * it. The engine always binds {@link realTimers}; the in-memory lifecycle\n * tests bind a virtual clock that advances `now` and fires due timers\n * together.\n */\n\nexport interface Timers {\n  /** Resolve after `ms` — the delay between retry attempts. */\n  readonly sleep: (ms: number) => Promise<void>\n  /**\n   * Run `fn` every `ms` until the returned stop function is called — the\n   * heartbeat.\n   */\n  readonly every: (ms: number, fn: () => void) => () => void\n}\n\nexport const realTimers: Timers = {\n  // Deliberately not unref'd: a retry delay is work in progress, and a\n  // process that exits during one abandons a claimed Execution.\n  sleep: (ms) =>\n    ms <= 0\n      ? Promise.resolve()\n      : new Promise((resolve) => {\n          setTimeout(resolve, ms)\n        }),\n  every: (ms, fn) => {\n    const timer = setInterval(fn, ms)\n    timer.unref?.()\n    return () => clearInterval(timer)\n  },\n}\n"]}

package/dist/execution/transaction.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The transaction seam.
+ *
+ * The claim and the commit are each one short transaction; the handler runs
+ * between them, outside both — so no transaction is ever held open
+ * across a handler's external calls. `withTransaction` is how the execution
+ * lifecycle gets one, and it is also what a handler's `ctx.onCommit` writes
+ * ride along inside.
+ */
+import type { DatabaseAccess, Transaction } from '../store/index.js';
+/**
+ * Run `fn` inside a transaction and hand it the handle to use — a checked-out
+ * client when the caller brought a pool, the client itself when they brought
+ * one (issuing `begin` on a *pool* would put each statement on a different
+ * connection, so the distinction is not cosmetic). Which case applies is the
+ * caller's declaration — {@link DatabaseAccess} — never sniffed from the
+ * object.
+ *
+ * Commits on return, rolls back on throw, and always releases what it
+ * checked out. A rollback that itself fails is swallowed: the original error
+ * is what the caller needs, and a connection too broken to roll back is
+ * discarded by the pool anyway.
+ */
+export declare const withTransaction: <T>(db: DatabaseAccess, fn: (tx: Transaction) => Promise<T>) => Promise<T>;

package/dist/execution/transaction.js

@@ -0,0 +1,49 @@
+/**
+ * The transaction seam.
+ *
+ * The claim and the commit are each one short transaction; the handler runs
+ * between them, outside both — so no transaction is ever held open
+ * across a handler's external calls. `withTransaction` is how the execution
+ * lifecycle gets one, and it is also what a handler's `ctx.onCommit` writes
+ * ride along inside.
+ */
+/**
+ * Run `fn` inside a transaction and hand it the handle to use — a checked-out
+ * client when the caller brought a pool, the client itself when they brought
+ * one (issuing `begin` on a *pool* would put each statement on a different
+ * connection, so the distinction is not cosmetic). Which case applies is the
+ * caller's declaration — {@link DatabaseAccess} — never sniffed from the
+ * object.
+ *
+ * Commits on return, rolls back on throw, and always releases what it
+ * checked out. A rollback that itself fails is swallowed: the original error
+ * is what the caller needs, and a connection too broken to roll back is
+ * discarded by the pool anyway.
+ */
+export const withTransaction = async (db, fn) => {
+    if (!('pool' in db))
+        return runTransaction(db.client, fn);
+    const client = await db.pool.connect();
+    try {
+        return await runTransaction(client, fn);
+    }
+    finally {
+        client.release();
+    }
+};
+const runTransaction = async (handle, fn) => {
+    // The one place the brand is applied: past the `begin` below, this handle
+    // really is inside a transaction.
+    const tx = handle;
+    await tx.query('begin');
+    try {
+        const result = await fn(tx);
+        await tx.query('commit');
+        return result;
+    }
+    catch (error) {
+        await tx.query('rollback').catch(() => undefined);
+        throw error;
+    }
+};
+//# sourceMappingURL=transaction.js.map

package/dist/execution/transaction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transaction.js","sourceRoot":"","sources":["../../src/execution/transaction.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,KAAK,EAClC,EAAkB,EAClB,EAAmC,EACvB,EAAE;IACd,IAAI,CAAC,CAAC,MAAM,IAAI,EAAE,CAAC;QAAE,OAAO,cAAc,CAAC,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,CAAA;IACzD,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC,IAAI,CAAC,OAAO,EAAE,CAAA;IACtC,IAAI,CAAC;QACH,OAAO,MAAM,cAAc,CAAC,MAAM,EAAE,EAAE,CAAC,CAAA;IACzC,CAAC;YAAS,CAAC;QACT,MAAM,CAAC,OAAO,EAAE,CAAA;IAClB,CAAC;AACH,CAAC,CAAA;AAED,MAAM,cAAc,GAAG,KAAK,EAC1B,MAAiB,EACjB,EAAmC,EACvB,EAAE;IACd,0EAA0E;IAC1E,kCAAkC;IAClC,MAAM,EAAE,GAAG,MAAqB,CAAA;IAChC,MAAM,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,CAAA;IACvB,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC,EAAE,CAAC,CAAA;QAC3B,MAAM,EAAE,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAA;QACxB,OAAO,MAAM,CAAA;IACf,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,EAAE,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAA;QACjD,MAAM,KAAK,CAAA;IACb,CAAC;AACH,CAAC,CAAA","sourcesContent":["/**\n * The transaction seam.\n *\n * The claim and the commit are each one short transaction; the handler runs\n * between them, outside both — so no transaction is ever held open\n * across a handler's external calls. `withTransaction` is how the execution\n * lifecycle gets one, and it is also what a handler's `ctx.onCommit` writes\n * ride along inside.\n */\n\nimport type { DatabaseAccess, Queryable, Transaction } from '../store/index.js'\n\n/**\n * Run `fn` inside a transaction and hand it the handle to use — a checked-out\n * client when the caller brought a pool, the client itself when they brought\n * one (issuing `begin` on a *pool* would put each statement on a different\n * connection, so the distinction is not cosmetic). Which case applies is the\n * caller's declaration — {@link DatabaseAccess} — never sniffed from the\n * object.\n *\n * Commits on return, rolls back on throw, and always releases what it\n * checked out. A rollback that itself fails is swallowed: the original error\n * is what the caller needs, and a connection too broken to roll back is\n * discarded by the pool anyway.\n */\nexport const withTransaction = async <T>(\n  db: DatabaseAccess,\n  fn: (tx: Transaction) => Promise<T>,\n): Promise<T> => {\n  if (!('pool' in db)) return runTransaction(db.client, fn)\n  const client = await db.pool.connect()\n  try {\n    return await runTransaction(client, fn)\n  } finally {\n    client.release()\n  }\n}\n\nconst runTransaction = async <T>(\n  handle: Queryable,\n  fn: (tx: Transaction) => Promise<T>,\n): Promise<T> => {\n  // The one place the brand is applied: past the `begin` below, this handle\n  // really is inside a transaction.\n  const tx = handle as Transaction\n  await tx.query('begin')\n  try {\n    const result = await fn(tx)\n    await tx.query('commit')\n    return result\n  } catch (error) {\n    await tx.query('rollback').catch(() => undefined)\n    throw error\n  }\n}\n"]}

package/dist/guards/condition.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Named conditions — the unit of explainability.
+ *
+ * A guard is a set of independently-evaluated named conditions, never an
+ * opaque boolean closure. Every consumer of the framework's answer to "what
+ * can happen now" — affordance listings, `explain`, the journal's
+ * guard-results field — leans on conditions being
+ * structured, synchronous, and side-effect-free.
+ */
+/**
+ * The escape-hatch result form: a condition may return `{ ok, reason? }`
+ * instead of a bare boolean when it wants to say *why* it failed (or passed)
+ * in domain language. The `reason` surfaces verbatim in the evaluation
+ * record, and from there in `explain` and the journal.
+ */
+export interface ConditionVerdict {
+    readonly ok: boolean;
+    readonly reason?: string;
+}
+/**
+ * What a condition may return: a bare boolean, or a {@link ConditionVerdict}
+ * carrying a reason. Nothing else — in particular no `Promise`. A `Promise`
+ * is not assignable to this type, which is what makes async conditions
+ * inexpressible rather than merely discouraged.
+ */
+export type ConditionOutcome = boolean | ConditionVerdict;
+/**
+ * The context a condition receives alongside case state.
+ *
+ * Carries the acting actor — opaque to the framework; the app owns identity
+ * and roles. Deliberately carries no
+ * clock: a condition can never read "now", so that evaluation
+ * "as of T" stays well-defined and deterministic.
+ *
+ * Scoped steps: when a scoped step's guard is evaluated for
+ * one element of its scoped collection, the bound element rides here as
+ * `ctx.scope` — e.g. one buyer of `s.buyers` — so a condition can read
+ * both the whole case state (its first argument) and the element the
+ * affordance is about. For unscoped evaluation `scope` is absent. This is the
+ * additive extension the original context reserved; conditions written
+ * before it exist keep compiling and behaving identically.
+ */
+export interface ConditionContext<TActor = unknown, TScope = unknown> {
+    /** The acting actor — app-defined shape; the framework never owns identity. */
+    readonly actor: TActor;
+    /**
+     * The bound scope element, when evaluating a scoped step's guard for one
+     * element of its scoped collection. Absent for unscoped steps.
+     * The model layer's scoped-condition types narrow this to the element type
+     * and make it non-optional for scoped-step authors.
+     */
+    readonly scope?: TScope;
+}
+/**
+ * One named, pure, synchronous predicate within a guard — the unit of
+ * explainability.
+ *
+ * A condition must be:
+ *
+ * - **Synchronous.** Enforced by type: the return type admits no `Promise`,
+ *   so an `async` condition is a type error.
+ * - **Side-effect-free.** Conditions are evaluated freely and repeatedly —
+ *   for affordance listings, `explain`, transactional re-evaluation at
+ *   execution time, and historical reconstruction. They must not mutate
+ *   state, log, or touch the outside world.
+ * - **Total over historical state.** Cases float to the latest
+ *   definitions, so a condition WILL be evaluated against state written
+ *   before the condition existed. Handle absence deliberately with the
+ *   `?? fallback` discipline — `s.split?.confirmed ?? false` — and
+ *   never assume a field exists just because current handlers write it.
+ *   This cannot be enforced by types; it is the baseline discipline every
+ *   condition author owes the cases already in flight.
+ * - **Clock-free.** Never read `Date.now()` or `new Date()` — a condition's
+ *   answer must be a function of (state, actor) alone.
+ *
+ * A condition should never throw. If one does (typically a totality bug
+ * against sparse historical state), evaluation does not propagate the throw:
+ * the condition is reported as failed with the thrown message as its reason,
+ * so one buggy condition degrades one answer, not the whole case.
+ *
+ * @typeParam TState - the case state document the condition reads. Conditions
+ *   of a scoped step also receive the whole case state here; the
+ *   bound scope element arrives via `ctx.scope`.
+ * @typeParam TActor - the app-defined actor shape; opaque to the framework.
+ */
+export type Condition<TState, TActor = unknown> = (state: TState, ctx: ConditionContext<TActor>) => ConditionOutcome;

package/dist/guards/condition.js

@@ -0,0 +1,11 @@
+/**
+ * Named conditions — the unit of explainability.
+ *
+ * A guard is a set of independently-evaluated named conditions, never an
+ * opaque boolean closure. Every consumer of the framework's answer to "what
+ * can happen now" — affordance listings, `explain`, the journal's
+ * guard-results field — leans on conditions being
+ * structured, synchronous, and side-effect-free.
+ */
+export {};
+//# sourceMappingURL=condition.js.map

package/dist/guards/condition.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"condition.js","sourceRoot":"","sources":["../../src/guards/condition.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG","sourcesContent":["/**\n * Named conditions — the unit of explainability.\n *\n * A guard is a set of independently-evaluated named conditions, never an\n * opaque boolean closure. Every consumer of the framework's answer to \"what\n * can happen now\" — affordance listings, `explain`, the journal's\n * guard-results field — leans on conditions being\n * structured, synchronous, and side-effect-free.\n */\n\n/**\n * The escape-hatch result form: a condition may return `{ ok, reason? }`\n * instead of a bare boolean when it wants to say *why* it failed (or passed)\n * in domain language. The `reason` surfaces verbatim in the evaluation\n * record, and from there in `explain` and the journal.\n */\nexport interface ConditionVerdict {\n  readonly ok: boolean\n  readonly reason?: string\n}\n\n/**\n * What a condition may return: a bare boolean, or a {@link ConditionVerdict}\n * carrying a reason. Nothing else — in particular no `Promise`. A `Promise`\n * is not assignable to this type, which is what makes async conditions\n * inexpressible rather than merely discouraged.\n */\nexport type ConditionOutcome = boolean | ConditionVerdict\n\n/**\n * The context a condition receives alongside case state.\n *\n * Carries the acting actor — opaque to the framework; the app owns identity\n * and roles. Deliberately carries no\n * clock: a condition can never read \"now\", so that evaluation\n * \"as of T\" stays well-defined and deterministic.\n *\n * Scoped steps: when a scoped step's guard is evaluated for\n * one element of its scoped collection, the bound element rides here as\n * `ctx.scope` — e.g. one buyer of `s.buyers` — so a condition can read\n * both the whole case state (its first argument) and the element the\n * affordance is about. For unscoped evaluation `scope` is absent. This is the\n * additive extension the original context reserved; conditions written\n * before it exist keep compiling and behaving identically.\n */\nexport interface ConditionContext<TActor = unknown, TScope = unknown> {\n  /** The acting actor — app-defined shape; the framework never owns identity. */\n  readonly actor: TActor\n  /**\n   * The bound scope element, when evaluating a scoped step's guard for one\n   * element of its scoped collection. Absent for unscoped steps.\n   * The model layer's scoped-condition types narrow this to the element type\n   * and make it non-optional for scoped-step authors.\n   */\n  readonly scope?: TScope\n}\n\n/**\n * One named, pure, synchronous predicate within a guard — the unit of\n * explainability.\n *\n * A condition must be:\n *\n * - **Synchronous.** Enforced by type: the return type admits no `Promise`,\n *   so an `async` condition is a type error.\n * - **Side-effect-free.** Conditions are evaluated freely and repeatedly —\n *   for affordance listings, `explain`, transactional re-evaluation at\n *   execution time, and historical reconstruction. They must not mutate\n *   state, log, or touch the outside world.\n * - **Total over historical state.** Cases float to the latest\n *   definitions, so a condition WILL be evaluated against state written\n *   before the condition existed. Handle absence deliberately with the\n *   `?? fallback` discipline — `s.split?.confirmed ?? false` — and\n *   never assume a field exists just because current handlers write it.\n *   This cannot be enforced by types; it is the baseline discipline every\n *   condition author owes the cases already in flight.\n * - **Clock-free.** Never read `Date.now()` or `new Date()` — a condition's\n *   answer must be a function of (state, actor) alone.\n *\n * A condition should never throw. If one does (typically a totality bug\n * against sparse historical state), evaluation does not propagate the throw:\n * the condition is reported as failed with the thrown message as its reason,\n * so one buggy condition degrades one answer, not the whole case.\n *\n * @typeParam TState - the case state document the condition reads. Conditions\n *   of a scoped step also receive the whole case state here; the\n *   bound scope element arrives via `ctx.scope`.\n * @typeParam TActor - the app-defined actor shape; opaque to the framework.\n */\nexport type Condition<TState, TActor = unknown> = (\n  state: TState,\n  ctx: ConditionContext<TActor>,\n) => ConditionOutcome\n"]}

package/dist/guards/evaluate.d.ts

@@ -0,0 +1,143 @@
+/**
+ * Guard evaluation — pure, deterministic, explainable.
+ *
+ * `evaluateGuard(guard, ctx)` turns a guard and an evaluation context
+ * (case state, actor, asOf) into a full per-condition evaluation record:
+ * the raw material for affordance computation, `explain`, and
+ * the journal's guard-results field.
+ */
+import type { Guard, GuardSection } from './guard.js';
+import type { Instant } from './time.js';
+/**
+ * Everything guard evaluation is a function of: case state, the acting
+ * actor, and the instant to evaluate as of. Nothing else — no ambient
+ * clock, no I/O — so the same context always produces the same record.
+ *
+ * `asOf` is explicit and mandatory: it is the instant the evaluation is
+ * made as of, stated on the record so the journal's claim-time evidence is
+ * self-contained.
+ *
+ * Scoped steps: when evaluating a scoped step's guard for
+ * one element of its scoped collection, bind the element as `scope`. It is
+ * threaded through to conditions via {@link ConditionContext}. When
+ * `scope` is absent, evaluation is exactly what it always was.
+ */
+export interface GuardEvaluationContext<TState, TActor = unknown> {
+    readonly state: TState;
+    readonly actor: TActor;
+    readonly asOf: Instant;
+    /**
+     * The bound scope element, when evaluating a scoped step's guard for one
+     * element. Threaded to conditions as `ctx.scope`. Omit for unscoped
+     * evaluation. `undefined` means "not scoped" — a scope binding is always a
+     * present element of a state collection.
+     */
+    readonly scope?: unknown;
+}
+/** Fields common to every per-condition result in an evaluation record. */
+export interface ConditionResultBase {
+    /** The condition's name in its section map (or its arm name, within an anyOf group). */
+    readonly name: string;
+    /** Which guard section the condition came from — `requires` or `permits`. */
+    readonly section: GuardSection;
+    readonly passed: boolean;
+    /**
+     * Present when the condition supplied one via the `{ ok, reason? }`
+     * escape hatch, or when evaluation had to absorb a defect (a condition
+     * that threw, or returned an unrecognized result).
+     */
+    readonly reason?: string;
+}
+/** Result of one plain (predicate) condition. */
+export interface SingleConditionResult extends ConditionResultBase {
+    readonly kind: 'condition';
+}
+/** Result of one arm of an `anyOf` group; `name` is the arm name. */
+export type AnyOfArmResult = SingleConditionResult;
+/**
+ * Result of an `anyOf` group: passed when at least one arm passed. Every
+ * arm is always evaluated and reported, so a failing group names each
+ * failing arm and a passing group shows which arm carried it.
+ */
+export interface AnyOfConditionResult extends ConditionResultBase {
+    readonly kind: 'anyOf';
+    readonly arms: readonly AnyOfArmResult[];
+}
+/** Result of one named entry in a guard section. */
+export type ConditionResult = SingleConditionResult | AnyOfConditionResult;
+/**
+ * The full record of one guard evaluation — a plain, JSON-serializable
+ * object, deterministic in (guard, state, actor, asOf). This is what
+ * affordance computation filters on, what `explain` renders, and what the
+ * journal stores as an execution's guard results.
+ *
+ * The `possible` / `permitted` pair is the requires/permits split made mechanical:
+ * `possible` is false when a `requires` condition is unmet (the step is not
+ * possible on this case, for anyone); `permitted` is false when a `permits`
+ * condition is unmet (not permitted for this actor). `available` is their
+ * conjunction. An omitted section is vacuously satisfied.
+ */
+export interface GuardEvaluation {
+    /** The instant evaluated as of, normalized to ISO-8601 UTC. */
+    readonly asOf: string;
+    /** Every `requires` condition holds — the step is possible on this case. */
+    readonly possible: boolean;
+    /** Every `permits` condition holds — the actor is permitted. */
+    readonly permitted: boolean;
+    /** `possible && permitted` — the step is an affordance for this actor. */
+    readonly available: boolean;
+    /** Per-condition results, in guard declaration order (`requires` first). */
+    readonly conditions: readonly ConditionResult[];
+}
+/**
+ * Marker for evaluating a guard with no actor at hand — `explain`'s
+ * requires-only probe. A `permits` condition is the only kind of entry
+ * that reads the actor, so it alone is skipped: reported failed with
+ * {@link NOT_EVALUATED_REASON} rather than run against nothing and absorbed
+ * as a thrown `TypeError`.
+ */
+export declare const NO_ACTOR: unique symbol;
+/** The stated reason a `permits` condition reports under {@link NO_ACTOR}. */
+export declare const NOT_EVALUATED_REASON = "not evaluated: no actor supplied";
+/**
+ * Evaluate a guard against (case state, actor, asOf) and return the full
+ * evaluation record.
+ *
+ * Guarantees the rest of the engine leans on:
+ *
+ * - **Pure and deterministic.** No I/O, no ambient clock; the same
+ *   (guard, state, actor, asOf) always yields a deeply-equal record.
+ * - **Complete.** Every condition — including every arm of every `anyOf`
+ *   group — is evaluated and reported; there is no short-circuiting, so the
+ *   record always answers "why / why not" in full.
+ * - **Total.** A condition that throws, or returns a malformed
+ *   outcome, becomes a failed result with a diagnostic `reason`; one
+ *   defective condition can never take down affordance computation for a
+ *   case. (The only throw is a `TypeError` when `ctx.asOf` itself is not a
+ *   determinable instant — that is a caller bug, not case data.)
+ * - **Serializable.** The record is a plain object with only JSON-safe
+ *   values, ready for the journal's guard-results field verbatim.
+ */
+export declare const evaluateGuard: <TState, TActor = unknown>(guard: Guard<TState, TActor>, ctx: GuardEvaluationContext<TState, TActor>) => GuardEvaluation;
+/**
+ * The unmet conditions of an evaluation — the derived view every consumer
+ * of a refusal renders. A view, not a convention: the error message, the
+ * blocked entry and the wire payload all call this instead of each spelling
+ * `conditions.filter(!passed)` for themselves.
+ */
+export declare const unmetConditions: (evaluation: GuardEvaluation) => readonly ConditionResult[];
+/** One unmet condition, addressed — `requires.financing.preApproved` — with its reason when it gave one. */
+export interface AddressedUnmet {
+    /** See {@link conditionAddress}: `section.name`, or `section.name.arm` inside an `anyOf`. */
+    readonly address: string;
+    readonly reason?: string;
+}
+/**
+ * The unmet conditions of an evaluation, flattened to addresses. An `anyOf`
+ * group that failed names each failing arm — the same addresses `explain`
+ * uses — so a refusal never says less than the
+ * evaluation knows.
+ */
+export declare const unmetAddresses: (evaluation: GuardEvaluation) => readonly AddressedUnmet[];
+/** Render the unmet conditions as one message clause: `requires.a — why; permits.b`. */
+export declare const describeUnmet: (evaluation: GuardEvaluation) => string;