@affordance/core 0.1.0

package/dist/guards/evaluate.js

@@ -0,0 +1,167 @@
+/**
+ * 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 { thrownMessage } from '../errors.js';
+import { conditionAddress, guardEntries } from './guard.js';
+import { toIso } from './time.js';
+/**
+ * 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 const NO_ACTOR = Symbol('affordance.no-actor');
+/** The stated reason a `permits` condition reports under {@link NO_ACTOR}. */
+export const NOT_EVALUATED_REASON = 'not evaluated: no actor supplied';
+const withReason = (result, reason) => reason === undefined ? result : { ...result, reason };
+/** Evaluate one plain condition, absorbing throws and malformed outcomes into a failed result. */
+const evaluateCondition = (name, section, condition, state, ctx) => {
+    if (section === 'permits' && ctx.actor === NO_ACTOR) {
+        return {
+            name,
+            section,
+            kind: 'condition',
+            passed: false,
+            reason: NOT_EVALUATED_REASON,
+        };
+    }
+    let outcome;
+    try {
+        outcome = condition(state, ctx);
+    }
+    catch (err) {
+        return {
+            name,
+            section,
+            kind: 'condition',
+            passed: false,
+            reason: `condition threw: ${thrownMessage(err)}`,
+        };
+    }
+    if (typeof outcome === 'boolean') {
+        return { name, section, kind: 'condition', passed: outcome };
+    }
+    if (typeof outcome === 'object' &&
+        outcome !== null &&
+        typeof outcome.ok === 'boolean') {
+        return withReason({ name, section, kind: 'condition', passed: outcome.ok }, outcome.reason);
+    }
+    return {
+        name,
+        section,
+        kind: 'condition',
+        passed: false,
+        reason: 'condition returned neither a boolean nor an { ok, reason? } verdict',
+    };
+};
+const MALFORMED = 'entry is not a condition function or an anyOf(...) group';
+const malformed = (name, section) => ({
+    name,
+    section,
+    kind: 'condition',
+    passed: false,
+    reason: MALFORMED,
+});
+/** Evaluate one arm of an `anyOf` group; the arm's own name is what it reports under. */
+const evaluateArm = (arm, state, ctx) => {
+    if (arm.kind === 'condition') {
+        return evaluateCondition(arm.arm, arm.section, arm.entry, state, ctx);
+    }
+    return malformed(arm.arm, arm.section);
+};
+/** Evaluate one walked guard entry (plain condition or anyOf group). */
+const evaluateEntry = (entry, state, ctx) => {
+    const { name, section } = entry;
+    if (entry.kind === 'condition') {
+        return evaluateCondition(name, section, entry.entry, state, ctx);
+    }
+    if (entry.kind === 'anyOf') {
+        const arms = entry.arms.map((arm) => evaluateArm(arm, state, ctx));
+        return {
+            name,
+            section,
+            kind: 'anyOf',
+            passed: arms.some((a) => a.passed),
+            arms,
+        };
+    }
+    return malformed(name, section);
+};
+/**
+ * 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 const evaluateGuard = (guard, ctx) => {
+    const asOf = toIso(ctx.asOf);
+    const conditionCtx = ctx.scope === undefined
+        ? { actor: ctx.actor }
+        : { actor: ctx.actor, scope: ctx.scope };
+    const conditions = guardEntries(guard).map((entry) => evaluateEntry(entry, ctx.state, conditionCtx));
+    const holds = (section) => conditions.every((result) => result.section !== section || result.passed);
+    const possible = holds('requires');
+    const permitted = holds('permits');
+    return {
+        asOf,
+        possible,
+        permitted,
+        available: possible && permitted,
+        conditions,
+    };
+};
+/**
+ * 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 const unmetConditions = (evaluation) => evaluation.conditions.filter((condition) => !condition.passed);
+/**
+ * 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 const unmetAddresses = (evaluation) => unmetConditions(evaluation).flatMap((result) => {
+    if (result.kind === 'anyOf') {
+        return result.arms
+            .filter((arm) => !arm.passed)
+            .map((arm) => ({
+            address: conditionAddress(result.section, result.name, arm.name),
+            ...(arm.reason !== undefined && { reason: arm.reason }),
+        }));
+    }
+    return [
+        {
+            address: conditionAddress(result.section, result.name),
+            ...(result.reason !== undefined && { reason: result.reason }),
+        },
+    ];
+});
+/** Render the unmet conditions as one message clause: `requires.a — why; permits.b`. */
+export const describeUnmet = (evaluation) => unmetAddresses(evaluation)
+    .map((unmet) => unmet.reason === undefined
+    ? unmet.address
+    : `${unmet.address} — ${unmet.reason}`)
+    .join('; ');
+//# sourceMappingURL=evaluate.js.map

package/dist/guards/evaluate.js.map

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

package/dist/guards/guard.d.ts

@@ -0,0 +1,136 @@
+/**
+ * The guard model.
+ *
+ * A guard is two flat AND-maps of named conditions — a map is satisfied
+ * only when every entry is: `requires` (case conditions — is this step
+ * possible on this case?) and `permits` (actor conditions — is this actor
+ * permitted to take it?). The algebra is
+ * deliberately small: a map value is a plain condition or exactly one level
+ * of named `anyOf` group. No nested and/or trees — the type of an `anyOf`
+ * arm makes deeper nesting inexpressible.
+ */
+import type { Condition } from './condition.js';
+/**
+ * What may sit inside an `anyOf` group: a plain condition. Never another
+ * `anyOf` — the algebra allows exactly one level of grouping, and this type
+ * is what enforces it.
+ */
+export type AnyOfArm<TState, TActor = unknown> = Condition<TState, TActor>;
+/**
+ * A named disjunction within a guard's AND-map: the group is satisfied when
+ * at least one arm is. The group is named by its key in the map; each arm is
+ * named by its key in `arms`, and every arm is always evaluated and reported
+ * individually in the evaluation record.
+ */
+export interface AnyOfGroup<TState, TActor = unknown> {
+    readonly kind: 'anyOf';
+    readonly arms: Readonly<Record<string, AnyOfArm<TState, TActor>>>;
+}
+/**
+ * Declare a named disjunction: satisfied when at least one arm is.
+ *
+ * ```ts
+ * requires: {
+ *   financing: anyOf({
+ *     preApproved:  s => s.buyer?.preApproved ?? false,
+ *     proofOfFunds: s => s.buyer?.proofOfFunds ?? false,
+ *   }),
+ * }
+ * ```
+ *
+ * Arms are plain conditions; nesting another `anyOf` is a type error (one
+ * level only). Throws at definition time on an empty or malformed arms map —
+ * a guard definition bug should fail the deploy, not an evaluation.
+ */
+export declare const anyOf: <TState, TActor = unknown>(arms: Readonly<Record<string, AnyOfArm<TState, TActor>>>) => AnyOfGroup<TState, TActor>;
+/**
+ * Anything that may sit under a name in a guard section: a plain condition
+ * or one `anyOf` group.
+ */
+export type ConditionMapEntry<TState, TActor = unknown> = Condition<TState, TActor> | AnyOfGroup<TState, TActor>;
+/**
+ * A flat AND-map of named conditions: the section is satisfied when every
+ * entry is. An empty or absent map is vacuously satisfied. Entry names are
+ * the unit of explainability — they surface verbatim in evaluation records,
+ * `explain`, and the journal.
+ */
+export type ConditionMap<TState, TActor = unknown> = Readonly<Record<string, ConditionMapEntry<TState, TActor>>>;
+/** The two sections of a guard: `requires` (case) and `permits` (actor). */
+export type GuardSection = 'requires' | 'permits';
+/**
+ * A step's guard: the full set of named conditions under which the step is
+ * available (CONTEXT.md).
+ *
+ * - `requires` — case conditions. When one fails, the step is **not
+ *   possible** on this case, for anyone.
+ * - `permits` — actor conditions. When one fails (and `requires` holds), the
+ *   step is possible but **not permitted for this actor**.
+ *
+ * The two sections evaluate identically; the split exists so evaluation can
+ * mechanically distinguish those two answers. An omitted section is
+ * vacuously satisfied.
+ */
+export interface Guard<TState, TActor = unknown> {
+    readonly requires?: ConditionMap<TState, TActor>;
+    readonly permits?: ConditionMap<TState, TActor>;
+}
+/**
+ * The stable address of one condition within a guard: `requires.escrowReady`,
+ * or `requires.financing.preApproved` for an arm of an `anyOf` group.
+ *
+ * Human-legible and unique within a guard, which is why a refusal's list of
+ * unmet conditions names each condition by it.
+ */
+export declare const conditionAddress: (section: GuardSection, name: string, arm?: string) => string;
+/**
+ * What kind of thing sits under a name in a guard section. `'unknown'` is an
+ * entry that is neither: a definition bug, which `step()` rejects
+ * at construction and evaluation absorbs into a failed condition — never a
+ * crash.
+ */
+export type GuardEntryKind = 'condition' | 'anyOf' | 'unknown';
+/** One arm of an `anyOf` group, located, classified and addressed. */
+export interface GuardArm<TState, TActor = unknown> {
+    readonly section: GuardSection;
+    /** The *group's* name in its section map. */
+    readonly name: string;
+    /** This arm's name within the group. */
+    readonly arm: string;
+    /** Never `'anyOf'` — the algebra allows exactly one level of grouping. */
+    readonly kind: 'condition' | 'unknown';
+    readonly entry: AnyOfArm<TState, TActor>;
+    /** `requires.financing.preApproved` — see {@link conditionAddress}. */
+    readonly address: string;
+}
+/** One named entry of a guard section, located, classified and addressed. */
+export interface GuardEntry<TState, TActor = unknown> {
+    readonly section: GuardSection;
+    readonly name: string;
+    readonly kind: GuardEntryKind;
+    readonly entry: ConditionMapEntry<TState, TActor>;
+    /** `requires.escrowReady` — see {@link conditionAddress}. */
+    readonly address: string;
+    /** The group's arms when `kind` is `'anyOf'`; empty otherwise. */
+    readonly arms: readonly GuardArm<TState, TActor>[];
+}
+/**
+ * Walk a guard: every named entry of both sections, in declaration order
+ * (`requires` first), classified and addressed, with `anyOf` arms attached.
+ *
+ * **This is the only place that knows the guard's shape.** Evaluation
+ * (`evaluateGuard`) and definition-time validation (`step()`) are maps and
+ * filters over this — so the algebra grows in one
+ * edit instead of two, and a condition's address is spelled once instead
+ * of twice.
+ *
+ * Total: a malformed entry is classified `'unknown'` and reported — the
+ * walk itself never throws — because every consumer's own totality rests on
+ * this walk.
+ *
+ * Cached per guard object: a guard is constructed once (by `step()`, or by
+ * hand in a test) and never mutated afterwards — every map on it is declared
+ * readonly — so the walk is a pure function of the guard's identity.
+ * Evaluation calls this on every affordance computation, and the cache makes
+ * each call after the first a lookup instead of a re-walk.
+ */
+export declare const guardEntries: <TState, TActor = unknown>(guard: Guard<TState, TActor>) => readonly GuardEntry<TState, TActor>[];

package/dist/guards/guard.js

@@ -0,0 +1,118 @@
+/**
+ * The guard model.
+ *
+ * A guard is two flat AND-maps of named conditions — a map is satisfied
+ * only when every entry is: `requires` (case conditions — is this step
+ * possible on this case?) and `permits` (actor conditions — is this actor
+ * permitted to take it?). The algebra is
+ * deliberately small: a map value is a plain condition or exactly one level
+ * of named `anyOf` group. No nested and/or trees — the type of an `anyOf`
+ * arm makes deeper nesting inexpressible.
+ */
+/**
+ * Declare a named disjunction: satisfied when at least one arm is.
+ *
+ * ```ts
+ * requires: {
+ *   financing: anyOf({
+ *     preApproved:  s => s.buyer?.preApproved ?? false,
+ *     proofOfFunds: s => s.buyer?.proofOfFunds ?? false,
+ *   }),
+ * }
+ * ```
+ *
+ * Arms are plain conditions; nesting another `anyOf` is a type error (one
+ * level only). Throws at definition time on an empty or malformed arms map —
+ * a guard definition bug should fail the deploy, not an evaluation.
+ */
+export const anyOf = (arms) => {
+    const names = Object.keys(arms ?? {});
+    if (names.length === 0) {
+        throw new TypeError('anyOf(arms): at least one named arm is required');
+    }
+    for (const name of names) {
+        const arm = arms[name];
+        if (typeof arm !== 'function') {
+            throw new TypeError(`anyOf(arms): arm '${name}' must be a condition function — nested anyOf groups are not part of the guard algebra`);
+        }
+    }
+    return { kind: 'anyOf', arms: { ...arms } };
+};
+/**
+ * The stable address of one condition within a guard: `requires.escrowReady`,
+ * or `requires.financing.preApproved` for an arm of an `anyOf` group.
+ *
+ * Human-legible and unique within a guard, which is why a refusal's list of
+ * unmet conditions names each condition by it.
+ */
+export const conditionAddress = (section, name, arm) => arm === undefined ? `${section}.${name}` : `${section}.${name}.${arm}`;
+const entryKind = (entry) => {
+    if (typeof entry === 'function')
+        return 'condition';
+    if (typeof entry !== 'object' || entry === null)
+        return 'unknown';
+    if (entry.kind === 'anyOf')
+        return 'anyOf';
+    return 'unknown';
+};
+const walkedEntries = new WeakMap();
+/**
+ * Walk a guard: every named entry of both sections, in declaration order
+ * (`requires` first), classified and addressed, with `anyOf` arms attached.
+ *
+ * **This is the only place that knows the guard's shape.** Evaluation
+ * (`evaluateGuard`) and definition-time validation (`step()`) are maps and
+ * filters over this — so the algebra grows in one
+ * edit instead of two, and a condition's address is spelled once instead
+ * of twice.
+ *
+ * Total: a malformed entry is classified `'unknown'` and reported — the
+ * walk itself never throws — because every consumer's own totality rests on
+ * this walk.
+ *
+ * Cached per guard object: a guard is constructed once (by `step()`, or by
+ * hand in a test) and never mutated afterwards — every map on it is declared
+ * readonly — so the walk is a pure function of the guard's identity.
+ * Evaluation calls this on every affordance computation, and the cache makes
+ * each call after the first a lookup instead of a re-walk.
+ */
+export const guardEntries = (guard) => {
+    const cached = walkedEntries.get(guard);
+    if (cached !== undefined) {
+        return cached;
+    }
+    const entries = [];
+    for (const section of ['requires', 'permits']) {
+        for (const [name, entry] of Object.entries(guard[section] ?? {})) {
+            const kind = entryKind(entry);
+            const arms = [];
+            if (kind === 'anyOf') {
+                const group = entry;
+                for (const [arm, armEntry] of Object.entries(group.arms ?? {})) {
+                    const armKind = entryKind(armEntry);
+                    arms.push({
+                        section,
+                        name,
+                        arm,
+                        // A nested group is inexpressible in the type and meaningless
+                        // here, so it is classified as a malformed arm.
+                        kind: armKind === 'anyOf' ? 'unknown' : armKind,
+                        entry: armEntry,
+                        address: conditionAddress(section, name, arm),
+                    });
+                }
+            }
+            entries.push({
+                section,
+                name,
+                kind,
+                entry,
+                address: conditionAddress(section, name),
+                arms,
+            });
+        }
+    }
+    walkedEntries.set(guard, entries);
+    return entries;
+};
+//# sourceMappingURL=guard.js.map

package/dist/guards/guard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"guard.js","sourceRoot":"","sources":["../../src/guards/guard.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The guard model.\n *\n * A guard is two flat AND-maps of named conditions — a map is satisfied\n * only when every entry is: `requires` (case conditions — is this step\n * possible on this case?) and `permits` (actor conditions — is this actor\n * permitted to take it?). The algebra is\n * deliberately small: a map value is a plain condition or exactly one level\n * of named `anyOf` group. No nested and/or trees — the type of an `anyOf`\n * arm makes deeper nesting inexpressible.\n */\n\nimport type { Condition } from './condition.js'\n\n/**\n * What may sit inside an `anyOf` group: a plain condition. Never another\n * `anyOf` — the algebra allows exactly one level of grouping, and this type\n * is what enforces it.\n */\nexport type AnyOfArm<TState, TActor = unknown> = Condition<TState, TActor>\n\n/**\n * A named disjunction within a guard's AND-map: the group is satisfied when\n * at least one arm is. The group is named by its key in the map; each arm is\n * named by its key in `arms`, and every arm is always evaluated and reported\n * individually in the evaluation record.\n */\nexport interface AnyOfGroup<TState, TActor = unknown> {\n  readonly kind: 'anyOf'\n  readonly arms: Readonly<Record<string, AnyOfArm<TState, TActor>>>\n}\n\n/**\n * Declare a named disjunction: satisfied when at least one arm is.\n *\n * ```ts\n * requires: {\n *   financing: anyOf({\n *     preApproved:  s => s.buyer?.preApproved ?? false,\n *     proofOfFunds: s => s.buyer?.proofOfFunds ?? false,\n *   }),\n * }\n * ```\n *\n * Arms are plain conditions; nesting another `anyOf` is a type error (one\n * level only). Throws at definition time on an empty or malformed arms map —\n * a guard definition bug should fail the deploy, not an evaluation.\n */\nexport const anyOf = <TState, TActor = unknown>(\n  arms: Readonly<Record<string, AnyOfArm<TState, TActor>>>,\n): AnyOfGroup<TState, TActor> => {\n  const names = Object.keys(arms ?? {})\n  if (names.length === 0) {\n    throw new TypeError('anyOf(arms): at least one named arm is required')\n  }\n  for (const name of names) {\n    const arm: unknown = arms[name]\n    if (typeof arm !== 'function') {\n      throw new TypeError(\n        `anyOf(arms): arm '${name}' must be a condition function — nested anyOf groups are not part of the guard algebra`,\n      )\n    }\n  }\n  return { kind: 'anyOf', arms: { ...arms } }\n}\n\n/**\n * Anything that may sit under a name in a guard section: a plain condition\n * or one `anyOf` group.\n */\nexport type ConditionMapEntry<TState, TActor = unknown> =\n  | Condition<TState, TActor>\n  | AnyOfGroup<TState, TActor>\n\n/**\n * A flat AND-map of named conditions: the section is satisfied when every\n * entry is. An empty or absent map is vacuously satisfied. Entry names are\n * the unit of explainability — they surface verbatim in evaluation records,\n * `explain`, and the journal.\n */\nexport type ConditionMap<TState, TActor = unknown> = Readonly<\n  Record<string, ConditionMapEntry<TState, TActor>>\n>\n\n/** The two sections of a guard: `requires` (case) and `permits` (actor). */\nexport type GuardSection = 'requires' | 'permits'\n\n/**\n * A step's guard: the full set of named conditions under which the step is\n * available (CONTEXT.md).\n *\n * - `requires` — case conditions. When one fails, the step is **not\n *   possible** on this case, for anyone.\n * - `permits` — actor conditions. When one fails (and `requires` holds), the\n *   step is possible but **not permitted for this actor**.\n *\n * The two sections evaluate identically; the split exists so evaluation can\n * mechanically distinguish those two answers. An omitted section is\n * vacuously satisfied.\n */\nexport interface Guard<TState, TActor = unknown> {\n  readonly requires?: ConditionMap<TState, TActor>\n  readonly permits?: ConditionMap<TState, TActor>\n}\n\n/**\n * The stable address of one condition within a guard: `requires.escrowReady`,\n * or `requires.financing.preApproved` for an arm of an `anyOf` group.\n *\n * Human-legible and unique within a guard, which is why a refusal's list of\n * unmet conditions names each condition by it.\n */\nexport const conditionAddress = (\n  section: GuardSection,\n  name: string,\n  arm?: string,\n): string =>\n  arm === undefined ? `${section}.${name}` : `${section}.${name}.${arm}`\n\n/**\n * What kind of thing sits under a name in a guard section. `'unknown'` is an\n * entry that is neither: a definition bug, which `step()` rejects\n * at construction and evaluation absorbs into a failed condition — never a\n * crash.\n */\nexport type GuardEntryKind = 'condition' | 'anyOf' | 'unknown'\n\nconst entryKind = (entry: unknown): GuardEntryKind => {\n  if (typeof entry === 'function') return 'condition'\n  if (typeof entry !== 'object' || entry === null) return 'unknown'\n  if ((entry as { kind?: unknown }).kind === 'anyOf') return 'anyOf'\n  return 'unknown'\n}\n\n/** One arm of an `anyOf` group, located, classified and addressed. */\nexport interface GuardArm<TState, TActor = unknown> {\n  readonly section: GuardSection\n  /** The *group's* name in its section map. */\n  readonly name: string\n  /** This arm's name within the group. */\n  readonly arm: string\n  /** Never `'anyOf'` — the algebra allows exactly one level of grouping. */\n  readonly kind: 'condition' | 'unknown'\n  readonly entry: AnyOfArm<TState, TActor>\n  /** `requires.financing.preApproved` — see {@link conditionAddress}. */\n  readonly address: string\n}\n\n/** One named entry of a guard section, located, classified and addressed. */\nexport interface GuardEntry<TState, TActor = unknown> {\n  readonly section: GuardSection\n  readonly name: string\n  readonly kind: GuardEntryKind\n  readonly entry: ConditionMapEntry<TState, TActor>\n  /** `requires.escrowReady` — see {@link conditionAddress}. */\n  readonly address: string\n  /** The group's arms when `kind` is `'anyOf'`; empty otherwise. */\n  readonly arms: readonly GuardArm<TState, TActor>[]\n}\n\nconst walkedEntries = new WeakMap<object, readonly GuardEntry<never, never>[]>()\n\n/**\n * Walk a guard: every named entry of both sections, in declaration order\n * (`requires` first), classified and addressed, with `anyOf` arms attached.\n *\n * **This is the only place that knows the guard's shape.** Evaluation\n * (`evaluateGuard`) and definition-time validation (`step()`) are maps and\n * filters over this — so the algebra grows in one\n * edit instead of two, and a condition's address is spelled once instead\n * of twice.\n *\n * Total: a malformed entry is classified `'unknown'` and reported — the\n * walk itself never throws — because every consumer's own totality rests on\n * this walk.\n *\n * Cached per guard object: a guard is constructed once (by `step()`, or by\n * hand in a test) and never mutated afterwards — every map on it is declared\n * readonly — so the walk is a pure function of the guard's identity.\n * Evaluation calls this on every affordance computation, and the cache makes\n * each call after the first a lookup instead of a re-walk.\n */\nexport const guardEntries = <TState, TActor = unknown>(\n  guard: Guard<TState, TActor>,\n): readonly GuardEntry<TState, TActor>[] => {\n  const cached = walkedEntries.get(guard)\n  if (cached !== undefined) {\n    return cached as readonly GuardEntry<TState, TActor>[]\n  }\n  const entries: GuardEntry<TState, TActor>[] = []\n  for (const section of ['requires', 'permits'] as const) {\n    for (const [name, entry] of Object.entries(guard[section] ?? {})) {\n      const kind = entryKind(entry)\n      const arms: GuardArm<TState, TActor>[] = []\n      if (kind === 'anyOf') {\n        const group = entry as AnyOfGroup<TState, TActor>\n        for (const [arm, armEntry] of Object.entries(group.arms ?? {})) {\n          const armKind = entryKind(armEntry)\n          arms.push({\n            section,\n            name,\n            arm,\n            // A nested group is inexpressible in the type and meaningless\n            // here, so it is classified as a malformed arm.\n            kind: armKind === 'anyOf' ? 'unknown' : armKind,\n            entry: armEntry,\n            address: conditionAddress(section, name, arm),\n          })\n        }\n      }\n      entries.push({\n        section,\n        name,\n        kind,\n        entry,\n        address: conditionAddress(section, name),\n        arms,\n      })\n    }\n  }\n  walkedEntries.set(guard, entries)\n  return entries\n}\n"]}

package/dist/guards/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The guard model and evaluation engine.
+ *
+ * A **guard** is a step's full set of named **conditions** — pure,
+ * synchronous predicates over (case state, actor) — split into
+ * `requires` (case conditions) and `permits` (actor conditions).
+ * `evaluateGuard` turns a guard and (state, actor, asOf) into a full,
+ * serializable per-condition evaluation record: the raw material for
+ * affordances, `explain`, and the journal.
+ *
+ * See `docs/architecture.md` for why guards are shaped this way, and
+ * CONTEXT.md for the vocabulary.
+ */
+export type { Condition, ConditionContext, ConditionOutcome, ConditionVerdict, } from './condition.js';
+export type { AddressedUnmet, AnyOfArmResult, AnyOfConditionResult, ConditionResult, ConditionResultBase, GuardEvaluation, GuardEvaluationContext, SingleConditionResult, } from './evaluate.js';
+export { describeUnmet, evaluateGuard, NO_ACTOR, NOT_EVALUATED_REASON, unmetAddresses, unmetConditions, } from './evaluate.js';
+export type { AnyOfArm, AnyOfGroup, ConditionMap, ConditionMapEntry, Guard, GuardArm, GuardEntry, GuardEntryKind, GuardSection, } from './guard.js';
+export { anyOf, conditionAddress, guardEntries } from './guard.js';
+export type { Instant } from './time.js';
+export { toEpochMs, toIso } from './time.js';

package/dist/guards/index.js

@@ -0,0 +1,17 @@
+/**
+ * The guard model and evaluation engine.
+ *
+ * A **guard** is a step's full set of named **conditions** — pure,
+ * synchronous predicates over (case state, actor) — split into
+ * `requires` (case conditions) and `permits` (actor conditions).
+ * `evaluateGuard` turns a guard and (state, actor, asOf) into a full,
+ * serializable per-condition evaluation record: the raw material for
+ * affordances, `explain`, and the journal.
+ *
+ * See `docs/architecture.md` for why guards are shaped this way, and
+ * CONTEXT.md for the vocabulary.
+ */
+export { describeUnmet, evaluateGuard, NO_ACTOR, NOT_EVALUATED_REASON, unmetAddresses, unmetConditions, } from './evaluate.js';
+export { anyOf, conditionAddress, guardEntries } from './guard.js';
+export { toEpochMs, toIso } from './time.js';
+//# sourceMappingURL=index.js.map

package/dist/guards/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/guards/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAkBH,OAAO,EACL,aAAa,EACb,aAAa,EACb,QAAQ,EACR,oBAAoB,EACpB,cAAc,EACd,eAAe,GAChB,MAAM,eAAe,CAAA;AAYtB,OAAO,EAAE,KAAK,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAElE,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,WAAW,CAAA","sourcesContent":["/**\n * The guard model and evaluation engine.\n *\n * A **guard** is a step's full set of named **conditions** — pure,\n * synchronous predicates over (case state, actor) — split into\n * `requires` (case conditions) and `permits` (actor conditions).\n * `evaluateGuard` turns a guard and (state, actor, asOf) into a full,\n * serializable per-condition evaluation record: the raw material for\n * affordances, `explain`, and the journal.\n *\n * See `docs/architecture.md` for why guards are shaped this way, and\n * CONTEXT.md for the vocabulary.\n */\n\nexport type {\n  Condition,\n  ConditionContext,\n  ConditionOutcome,\n  ConditionVerdict,\n} from './condition.js'\nexport type {\n  AddressedUnmet,\n  AnyOfArmResult,\n  AnyOfConditionResult,\n  ConditionResult,\n  ConditionResultBase,\n  GuardEvaluation,\n  GuardEvaluationContext,\n  SingleConditionResult,\n} from './evaluate.js'\nexport {\n  describeUnmet,\n  evaluateGuard,\n  NO_ACTOR,\n  NOT_EVALUATED_REASON,\n  unmetAddresses,\n  unmetConditions,\n} from './evaluate.js'\nexport type {\n  AnyOfArm,\n  AnyOfGroup,\n  ConditionMap,\n  ConditionMapEntry,\n  Guard,\n  GuardArm,\n  GuardEntry,\n  GuardEntryKind,\n  GuardSection,\n} from './guard.js'\nexport { anyOf, conditionAddress, guardEntries } from './guard.js'\nexport type { Instant } from './time.js'\nexport { toEpochMs, toIso } from './time.js'\n"]}

package/dist/guards/time.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Instant normalization.
+ *
+ * Conditions never read the clock. Evaluation takes an explicit `asOf`
+ * instant, so "evaluate this guard as of T" is always well-defined and the
+ * evaluation record can state the instant it was made as of. The helpers
+ * here normalize the forms callers and case state plausibly hold an instant
+ * in.
+ */
+/**
+ * An instant in time, in any of the forms case state and callers plausibly
+ * hold one: a `Date`, an ISO-8601 (or otherwise `Date.parse`-able) string,
+ * or epoch milliseconds. Normalized internally; evaluation records always
+ * report instants as ISO-8601 UTC strings.
+ */
+export type Instant = Date | string | number;
+/**
+ * Normalize any {@link Instant} form to epoch milliseconds; `null` when the
+ * value is absent or not a determinable instant. **Total** by design — never
+ * throws, because absence and rubbish in historical Case State are ordinary
+ * and mean "not determinable", not "error".
+ */
+export declare const toEpochMs: (value: unknown) => number | null;
+/**
+ * Normalize any {@link Instant} to ISO-8601 UTC, **loudly** — every record
+ * the framework emits reports instants as strings.
+ *
+ * The loud counterpart of {@link toEpochMs}: this one reads *caller input*
+ * (an `asOf`, a dormancy marker), where a value that is not an instant is a
+ * caller bug rather than a pending fact.
+ */
+export declare const toIso: (value: Instant) => string;

package/dist/guards/time.js

@@ -0,0 +1,45 @@
+/**
+ * Instant normalization.
+ *
+ * Conditions never read the clock. Evaluation takes an explicit `asOf`
+ * instant, so "evaluate this guard as of T" is always well-defined and the
+ * evaluation record can state the instant it was made as of. The helpers
+ * here normalize the forms callers and case state plausibly hold an instant
+ * in.
+ */
+/**
+ * Normalize any {@link Instant} form to epoch milliseconds; `null` when the
+ * value is absent or not a determinable instant. **Total** by design — never
+ * throws, because absence and rubbish in historical Case State are ordinary
+ * and mean "not determinable", not "error".
+ */
+export const toEpochMs = (value) => {
+    if (value instanceof Date) {
+        const ms = value.getTime();
+        return Number.isNaN(ms) ? null : ms;
+    }
+    if (typeof value === 'number') {
+        return Number.isFinite(value) ? value : null;
+    }
+    if (typeof value === 'string') {
+        const ms = Date.parse(value);
+        return Number.isNaN(ms) ? null : ms;
+    }
+    return null;
+};
+/**
+ * Normalize any {@link Instant} to ISO-8601 UTC, **loudly** — every record
+ * the framework emits reports instants as strings.
+ *
+ * The loud counterpart of {@link toEpochMs}: this one reads *caller input*
+ * (an `asOf`, a dormancy marker), where a value that is not an instant is a
+ * caller bug rather than a pending fact.
+ */
+export const toIso = (value) => {
+    const ms = toEpochMs(value);
+    if (ms === null) {
+        throw new TypeError('asOf/endedAt must be a Date, ISO-8601 string, or epoch milliseconds');
+    }
+    return new Date(ms).toISOString();
+};
+//# sourceMappingURL=time.js.map

package/dist/guards/time.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"time.js","sourceRoot":"","sources":["../../src/guards/time.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAUH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,KAAc,EAAiB,EAAE;IACzD,IAAI,KAAK,YAAY,IAAI,EAAE,CAAC;QAC1B,MAAM,EAAE,GAAG,KAAK,CAAC,OAAO,EAAE,CAAA;QAC1B,OAAO,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAA;IACrC,CAAC;IACD,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,OAAO,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAA;IAC9C,CAAC;IACD,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,MAAM,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAA;QAC5B,OAAO,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAA;IACrC,CAAC;IACD,OAAO,IAAI,CAAA;AACb,CAAC,CAAA;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG,CAAC,KAAc,EAAU,EAAE;IAC9C,MAAM,EAAE,GAAG,SAAS,CAAC,KAAK,CAAC,CAAA;IAC3B,IAAI,EAAE,KAAK,IAAI,EAAE,CAAC;QAChB,MAAM,IAAI,SAAS,CACjB,qEAAqE,CACtE,CAAA;IACH,CAAC;IACD,OAAO,IAAI,IAAI,CAAC,EAAE,CAAC,CAAC,WAAW,EAAE,CAAA;AACnC,CAAC,CAAA","sourcesContent":["/**\n * Instant normalization.\n *\n * Conditions never read the clock. Evaluation takes an explicit `asOf`\n * instant, so \"evaluate this guard as of T\" is always well-defined and the\n * evaluation record can state the instant it was made as of. The helpers\n * here normalize the forms callers and case state plausibly hold an instant\n * in.\n */\n\n/**\n * An instant in time, in any of the forms case state and callers plausibly\n * hold one: a `Date`, an ISO-8601 (or otherwise `Date.parse`-able) string,\n * or epoch milliseconds. Normalized internally; evaluation records always\n * report instants as ISO-8601 UTC strings.\n */\nexport type Instant = Date | string | number\n\n/**\n * Normalize any {@link Instant} form to epoch milliseconds; `null` when the\n * value is absent or not a determinable instant. **Total** by design — never\n * throws, because absence and rubbish in historical Case State are ordinary\n * and mean \"not determinable\", not \"error\".\n */\nexport const toEpochMs = (value: unknown): number | null => {\n  if (value instanceof Date) {\n    const ms = value.getTime()\n    return Number.isNaN(ms) ? null : ms\n  }\n  if (typeof value === 'number') {\n    return Number.isFinite(value) ? value : null\n  }\n  if (typeof value === 'string') {\n    const ms = Date.parse(value)\n    return Number.isNaN(ms) ? null : ms\n  }\n  return null\n}\n\n/**\n * Normalize any {@link Instant} to ISO-8601 UTC, **loudly** — every record\n * the framework emits reports instants as strings.\n *\n * The loud counterpart of {@link toEpochMs}: this one reads *caller input*\n * (an `asOf`, a dormancy marker), where a value that is not an instant is a\n * caller bug rather than a pending fact.\n */\nexport const toIso = (value: Instant): string => {\n  const ms = toEpochMs(value)\n  if (ms === null) {\n    throw new TypeError(\n      'asOf/endedAt must be a Date, ISO-8601 string, or epoch milliseconds',\n    )\n  }\n  return new Date(ms).toISOString()\n}\n"]}