@affordance/core 0.1.0

package/dist/model/step.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"step.js","sourceRoot":"","sources":["../../src/model/step.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Step definitions.\n *\n * A **step** is an independently-defined unit of possible work on a case: a\n * guard plus a handler (CONTEXT.md). Steps never declare ordering —\n * sequencing is data dependencies between guards. `step()` validates the\n * definition loudly at construction time: a malformed step should fail the\n * deploy, not an evaluation.\n */\n\nimport type { StandardSchemaV1 } from '@standard-schema/spec'\nimport { AffordanceError } from '../errors.js'\nimport type { ConditionMap, Guard, GuardSection } from '../guards/index.js'\nimport { guardEntries } from '../guards/index.js'\nimport type {\n  ErasedStepHandler,\n  ScopedStepHandler,\n  StepHandler,\n} from './handler.js'\nimport type { RetryOptions, RetryPolicy } from './retry.js'\nimport { normalizeRetry } from './retry.js'\nimport type { ScopeDeclaration, ScopedConditionMap } from './scope.js'\nimport { eraseScopedConditionMap } from './scope.js'\n\n/** Options for an unscoped step. */\nexport interface StepOptions<TState, TActor = unknown, TInput = undefined> {\n  /** The step's name — unique within its case type; half of a scoped affordance's identity. */\n  readonly name: string\n  /**\n   * A short human label for the step (\"Issue the funding call\"). Definition\n   * metadata, not identity: journal entries and refusals name the step by\n   * `name`; adapters serialize the title so a client renders steps without\n   * an out-of-band label table.\n   */\n  readonly title?: string\n  /**\n   * A sentence on what the step does and when to take it — what makes the\n   * affordance contract a usable tool list for a caller (an agent included)\n   * that has never seen this case type.\n   */\n  readonly description?: string\n  /** Case conditions: when one fails the step is not possible on this case, for anyone. */\n  readonly requires?: ConditionMap<TState, TActor>\n  /** Actor conditions: when one fails the step is possible but not permitted for this actor. */\n  readonly permits?: ConditionMap<TState, TActor>\n  /**\n   * Optional input schema (any Standard Schema — zod v4 qualifies). Validated\n   * by `validateStepInput` before the handler runs.\n   */\n  readonly input?: StandardSchemaV1<unknown, TInput>\n  /**\n   * How many times a failed attempt is retried, and how long between\n   * attempts. Defaults to three attempts with exponential backoff; set\n   * `{ maxAttempts: 1 }` to disable retry for this step.\n   */\n  readonly retry?: RetryOptions\n  /** The step's effect function — the only thing that mutates Case State. */\n  readonly handler: StepHandler<TState, TActor, TInput>\n}\n\n/** Options for a scoped step: an unscoped step plus the scope declaration. */\nexport interface ScopedStepOptions<\n  TState,\n  TElement,\n  TActor = unknown,\n  TInput = undefined,\n> {\n  readonly name: string\n  readonly title?: string\n  readonly description?: string\n  /** The collection the step ranges over and how each element is identified. */\n  readonly scope: ScopeDeclaration<TState, TElement>\n  readonly requires?: ScopedConditionMap<TState, TElement, TActor>\n  readonly permits?: ScopedConditionMap<TState, TElement, TActor>\n  readonly input?: StandardSchemaV1<unknown, TInput>\n  readonly retry?: RetryOptions\n  readonly handler: ScopedStepHandler<TState, TElement, TActor, TInput>\n}\n\n/**\n * A step definition as held by a case type and consumed by the engine — the\n * authoring generics (scope element, input) erased to the case-state level.\n * The options types above carry the precise authoring shapes; this is the\n * machine-facing normal form.\n */\nexport interface StepDefinition<TState, TActor = unknown> {\n  readonly name: string\n  /** The declared human label, or `null` — clients fall back to `name`. */\n  readonly title: string | null\n  /** The declared what-and-when sentence, or `null`. */\n  readonly description: string | null\n  /**\n   * The step's guard in the guards module's shape, ready for `evaluateGuard`.\n   * For a scoped step the engine evaluates it once per selected element with\n   * the element bound as `scope`.\n   */\n  readonly guard: Guard<TState, TActor>\n  /** The scope declaration (element type erased), or `null` for an unscoped step. */\n  readonly scope: {\n    readonly select: (state: TState) => readonly unknown[]\n    readonly key: (element: unknown) => string\n  } | null\n  /** The declared input schema, or `null` when the step takes no input. */\n  readonly input: StandardSchemaV1 | null\n  /** The normalized retry policy the execution lifecycle applies to this step. */\n  readonly retry: RetryPolicy\n  /** The step's handler — invoked only by the execution lifecycle. */\n  readonly handler: ErasedStepHandler<TState, TActor>\n}\n\n/**\n * A step's declared human metadata, as `Engine.stepMetadataFor` answers it —\n * the serializable slice of a {@link StepDefinition} an adapter puts on the\n * wire.\n */\nexport interface StepMetadata {\n  readonly title: string | null\n  readonly description: string | null\n}\n\n/** Whether a value is a Standard-Schema instance — the one spelling of the check. */\nexport const isStandardSchema = (value: unknown): value is StandardSchemaV1 =>\n  typeof value === 'object' &&\n  value !== null &&\n  typeof (value as { '~standard'?: unknown })['~standard'] === 'object'\n\n/**\n * Whether a value is plausibly a {@link StepDefinition} — the structural\n * check `caseType()` applies to every step it is given.\n */\nexport const looksLikeStepDefinition = (\n  value: unknown,\n): value is StepDefinition<unknown, unknown> =>\n  typeof value === 'object' &&\n  value !== null &&\n  typeof (value as { name?: unknown }).name === 'string' &&\n  typeof (value as { handler?: unknown }).handler === 'function' &&\n  typeof (value as { guard?: unknown }).guard === 'object'\n\n/**\n * Validate one guard section map at definition time: every entry must be a\n * condition function or an `anyOf(...)` group\n * (unscoped only — scoped maps admit conditions alone).\n *\n * The classification and the `requires.escrowReady` addressing both come from\n * `guardEntries`, so what a definition is allowed to contain is decided\n * against the same walk evaluation uses — a definition `step()` accepts is\n * one `evaluateGuard` can read.\n */\nconst validateConditionMap = (\n  stepName: string,\n  section: GuardSection,\n  map: Readonly<Record<string, unknown>> | undefined,\n  allowAnyOf: boolean,\n): void => {\n  if (map === undefined) return\n  if (typeof map !== 'object' || map === null || Array.isArray(map)) {\n    throw new TypeError(\n      `step '${stepName}': ${section} must be a plain object of named conditions`,\n    )\n  }\n  const section_ = { [section]: map } as Guard<unknown, unknown>\n  for (const entry of guardEntries(section_)) {\n    if (entry.kind === 'condition') continue\n    if (entry.kind === 'anyOf' && allowAnyOf) continue\n    const allowed = allowAnyOf\n      ? 'a condition function or an anyOf(...) group'\n      : 'a condition function (anyOf is not part of the scoped guard surface)'\n    throw new TypeError(\n      `step '${stepName}': ${entry.address} must be ${allowed}`,\n    )\n  }\n}\n\nconst validateCommon = (options: {\n  name: unknown\n  title?: unknown\n  description?: unknown\n  input?: unknown\n  handler: unknown\n}): string => {\n  const { name } = options\n  if (typeof name !== 'string' || name.trim() === '') {\n    throw new TypeError('step: name must be a non-empty string')\n  }\n  if (typeof options.handler !== 'function') {\n    throw new TypeError(`step '${name}': handler must be an async function`)\n  }\n  if (options.input !== undefined && !isStandardSchema(options.input)) {\n    throw new TypeError(\n      `step '${name}': input must be a Standard Schema (e.g. a zod schema)`,\n    )\n  }\n  for (const field of ['title', 'description'] as const) {\n    const value = options[field]\n    if (\n      value !== undefined &&\n      (typeof value !== 'string' || value.trim() === '')\n    ) {\n      throw new TypeError(\n        `step '${name}': ${field} must be a non-empty string when given`,\n      )\n    }\n  }\n  return name\n}\n\n/**\n * Define a step. Two shapes, discriminated by the presence of `scope`:\n *\n * ```ts\n * // Standalone form (internal — apps author through {@link stepsOf}, which\n * // binds the generics once and takes the same options annotation-free):\n * // type parameters are inferred from annotations in the options — annotate\n * // the state parameter of a condition (and the actor on a permits ctx).\n * step({\n *   name: 'issue-funding-call',\n *   requires: { escrowReady: (s: Purchase) => s.escrow?.status === 'open' },\n *   permits: { isOrganizer: (_s: Purchase, ctx: ConditionContext<Ops>) => ctx.actor.roles.includes('organizer') },\n *   handler: async (s, ctx) => s,\n * })\n *\n * // Scoped, standalone form: annotating scope.select anchors both the state\n * // and element types; conditions then read the bound element as ctx.scope,\n * // fully typed (through stepsOf, even the select annotation goes away):\n * step({\n *   name: 'escalate-verification',\n *   scope: { select: (s: Purchase) => s.buyers.filter(b => b.verification?.status === 'review'), key: b => b.id },\n *   requires: { flagged: (s: Purchase, ctx) => (ctx.scope as Buyer).verification?.flaggedAt != null },\n *   handler: async (s, ctx) => s,\n * })\n * ```\n *\n * Validates loudly at construction time — malformed guard entries, a\n * malformed scope declaration, a non-function handler, or a non-schema\n * `input` all throw `TypeError` (definition-time validation; a definition\n * bug should fail the deploy, not an evaluation).\n *\n * The scoped overload is declared first: type parameters are meant to be\n * inferred, and inference resolves each call shape against its own overload\n * (explicit type-argument lists interact badly with overloaded\n * context-sensitive options — annotate inside the options instead).\n */\nexport function step<TState, TElement, TActor = unknown, TInput = undefined>(\n  options: ScopedStepOptions<TState, TElement, TActor, TInput>,\n): StepDefinition<TState, TActor>\nexport function step<TState, TActor = unknown, TInput = undefined>(\n  options: StepOptions<TState, TActor, TInput>,\n): StepDefinition<TState, TActor>\nexport function step<TState, TActor>(\n  options:\n    | StepOptions<TState, TActor, unknown>\n    | ScopedStepOptions<TState, unknown, TActor, unknown>,\n): StepDefinition<TState, TActor> {\n  const name = validateCommon(options)\n  const scoped = 'scope' in options && options.scope !== undefined\n  let scope: StepDefinition<TState, TActor>['scope'] = null\n  let guard: Guard<TState, TActor>\n\n  if (scoped) {\n    const declaration = (\n      options as ScopedStepOptions<TState, unknown, TActor, unknown>\n    ).scope\n    if (\n      typeof declaration !== 'object' ||\n      declaration === null ||\n      typeof declaration.select !== 'function' ||\n      typeof declaration.key !== 'function'\n    ) {\n      throw new TypeError(\n        `step '${name}': scope must be { select: state => elements, key: element => string }`,\n      )\n    }\n    validateConditionMap(name, 'requires', options.requires, false)\n    validateConditionMap(name, 'permits', options.permits, false)\n    scope = { select: declaration.select, key: declaration.key }\n    // Erasure, not conversion: scoped maps are runtime-identical to unscoped\n    // ones; evaluation binds the scope element the scoped types promise.\n    const scopedOptions = options as ScopedStepOptions<\n      TState,\n      unknown,\n      TActor,\n      unknown\n    >\n    guard = {\n      ...(scopedOptions.requires !== undefined && {\n        requires: eraseScopedConditionMap(scopedOptions.requires),\n      }),\n      ...(scopedOptions.permits !== undefined && {\n        permits: eraseScopedConditionMap(scopedOptions.permits),\n      }),\n    }\n  } else {\n    const unscoped = options as StepOptions<TState, TActor, unknown>\n    validateConditionMap(name, 'requires', unscoped.requires, true)\n    validateConditionMap(name, 'permits', unscoped.permits, true)\n    guard = {\n      ...(unscoped.requires !== undefined && { requires: unscoped.requires }),\n      ...(unscoped.permits !== undefined && { permits: unscoped.permits }),\n    }\n  }\n\n  return {\n    name,\n    title: options.title ?? null,\n    description: options.description ?? null,\n    guard,\n    scope,\n    input: options.input ?? null,\n    retry: normalizeRetry(name, options.retry),\n    // The one erasure cast for handlers: the authored context (typed input,\n    // typed scope element) is what the execution lifecycle constructs; see\n    // ErasedStepHandler.\n    handler: options.handler as unknown as ErasedStepHandler<TState, TActor>,\n  }\n}\n\n/**\n * The `step()` authoring surface with the case's state and actor types fixed.\n *\n * Same two call shapes as `step()` — scoped first, discriminated by the\n * presence of `scope` — but `TState`/`TActor` are already substituted, so\n * only the per-step generics (scope element, input) remain to be inferred.\n * That is what makes annotation-free authoring work: conditions and handlers\n * no longer participate in inferring the state type, they just receive it\n * contextually, and a scoped step's element type anchors on `scope.select`\n * alone (so `ctx.scope` is the element, with no `undefined` to narrow away).\n */\nexport interface BoundStep<TState, TActor = unknown> {\n  <TElement, TInput = undefined>(\n    options: ScopedStepOptions<TState, TElement, TActor, TInput>,\n  ): StepDefinition<TState, TActor>\n  <TInput = undefined>(\n    options: StepOptions<TState, TActor, TInput>,\n  ): StepDefinition<TState, TActor>\n}\n\n/**\n * A value-level carrier for `stepsOf`'s actor type — nothing but the type.\n * Exists because `TActor` has no value to be inferred from (a case's actor\n * shape is app-defined and never materializes at definition time), and\n * spelling it as a type argument would force spelling the schema's type too\n * (TypeScript has no partial type-argument inference).\n */\nexport interface ActorMarker<TActor> {\n  readonly __actor?: TActor\n}\n\nconst ACTOR_MARKER: ActorMarker<never> = Object.freeze({})\n\n/** Name the actor type of a `stepsOf` factory: `stepsOf(PurchaseState, actor<PurchaseActor>())`. */\nexport const actor = <TActor>(): ActorMarker<TActor> => ACTOR_MARKER\n\n/**\n * Bind `step()` to a case's state schema — the schema-anchored authoring\n * factory.\n *\n * ```ts\n * const purchaseStep = stepsOf(PurchaseState, actor<PurchaseActor>())\n *\n * purchaseStep({\n *   name: 'issue-funding-call',\n *   requires: { escrowReady: s => s.escrow.status === 'open' },        // s: inferred from the schema\n *   permits:  { isOrganizer: (_s, ctx) => hasRole(ctx.actor, 'organizer') },\n *   handler: async s => s,\n * })\n *\n * purchaseStep({\n *   name: 'escalate-verification',\n *   scope: { select: s => s.buyers.filter(b => b.verification.status === 'review'), key: b => b.id },\n *   requires: { flagged: (_s, ctx) => ctx.scope.verification.flaggedAt !== null },  // ctx.scope: Buyer\n *   handler: async s => s,\n * })\n * ```\n *\n * The state type is derived from the schema *value* — the same\n * `InferOutput` derivation `caseType` performs — so the factory and the case\n * type are anchored to one declaration and cannot drift apart: the state a\n * condition sees is definitionally the state the engine validates against.\n * The per-condition annotations the bare `step()` needs\n * (`(s: Purchase) => …`) disappear, because `TState` is no longer inferred\n * from the options.\n *\n * The second argument exists only to name the actor type and carries no\n * runtime information; omit it for an untyped actor. Define one factory per\n * case type module, next to the schema, and author every step of that case\n * type through it.\n *\n * Returns `step` itself, re-typed — a step authored through the factory is\n * bit-for-bit an ordinary step definition. `step` is deliberately not part\n * of the package barrel: this factory is the public authoring surface, and\n * a helper that builds steps generically should accept a\n * {@link BoundStep} rather than reach for the unbound `step`.\n * Throws at definition time when `state` is not a Standard Schema, like\n * every other malformed-definition case in this module.\n */\nexport const stepsOf = <S extends StandardSchemaV1, TActor = unknown>(\n  state: S,\n  _actor?: ActorMarker<TActor>,\n): BoundStep<StandardSchemaV1.InferOutput<S>, TActor> => {\n  if (!isStandardSchema(state)) {\n    throw new TypeError(\n      'stepsOf: state must be a Standard Schema (e.g. a zod schema)',\n    )\n  }\n  return step\n}\n\n/** A step's declared input failed validation against its input schema. */\nexport class StepInputValidationError extends AffordanceError {\n  readonly stepName: string\n  readonly issues: readonly StandardSchemaV1.Issue[]\n\n  constructor(stepName: string, issues: readonly StandardSchemaV1.Issue[]) {\n    super(\n      'invalid-input',\n      `invalid input for step '${stepName}': ${issues.map((issue) => issue.message).join('; ')}`,\n    )\n    this.name = 'StepInputValidationError'\n    this.stepName = stepName\n    this.issues = issues\n  }\n}\n\n/**\n * Validate a step's input against its declared input schema — the validation\n * plumbing the execution lifecycle runs before invoking the handler (\"validated before the\n * handler runs\"). Returns the schema *output* (defaults applied). A step\n * without an input schema accepts only `undefined` and yields `undefined`;\n * anything else is a caller bug and throws.\n */\nexport const validateStepInput = async <TState, TActor>(\n  definition: StepDefinition<TState, TActor>,\n  input: unknown,\n): Promise<unknown> => {\n  if (definition.input === null) {\n    if (input !== undefined) {\n      throw new StepInputValidationError(definition.name, [\n        { message: 'step declares no input schema, but input was provided' },\n      ])\n    }\n    return undefined\n  }\n  const result = await definition.input['~standard'].validate(input)\n  if (result.issues)\n    throw new StepInputValidationError(definition.name, result.issues)\n  return result.value\n}\n"]}

package/dist/model/target.d.ts

@@ -0,0 +1,175 @@
+/**
+ * Step targeting: resolving "step X, of element K, on this state".
+ *
+ * A **step target** is a step definition plus its scope binding — the pair
+ * that an affordance's identity (step × scope key) names. Everything
+ * that acts on a step goes through here first: the execution lifecycle's
+ * claim, `explain`, audit replay, and the affordance listing itself.
+ *
+ * It lives in the model because it is a fact about a {@link StepDefinition}
+ * and a Case State, and nothing more — no store, no registry, no clock. Put
+ * anywhere higher it would drag every consumer's imports upward toward the
+ * engine, which is a facade none of them should need.
+ *
+ * ## One fan-out, filtered
+ *
+ * {@link selectTargets} is the only implementation of fan-out — expanding
+ * one scoped step into its per-element targets — and it makes the one
+ * distinction every consumer needs:
+ *
+ * - A **defective selector** — one that throws over historical state, or
+ *   returns something other than an array — is a *selection failure*,
+ *   reported as `failure` with no targets. Each caller decides what its
+ *   audience deserves: the affordance listing renders it as a blocked
+ *   `$scope` entry, a sweep skips the step, {@link resolveTarget} throws.
+ * - A **key integrity violation** — duplicate or malformed scope keys —
+ *   corrupts affordance identity itself, so {@link ScopeKeyError} is loud
+ *   through every path. No caller may absorb it into an empty selection.
+ *
+ * Addressing — "step X (of element K) on this state" — is likewise one
+ * implementation, {@link addressTarget}, answering with the target or a
+ * {@link TargetAddressFailure} that names its kind. Its filters:
+ * {@link resolveTarget} (loud: an addressed caller is owed the precise
+ * failure, so it throws), audit replay (lenient: a sweep over the Journal
+ * reports the failure as a value and keeps going), and `explain` (loud,
+ * with one deliberate exception — a `defective-selector` failure is
+ * *answered*, because the listing published that exact link).
+ */
+import { SCOPE_FAILURE_CONDITION } from '@affordance/contract';
+import type { StandardSchemaV1 } from '@standard-schema/spec';
+import type { GuardEvaluation, Instant } from '../guards/index.js';
+import type { CaseTypeDefinition } from './casetype.js';
+import { ScopeKeyError, UnknownStepError } from './errors.js';
+import type { StepDefinition } from './step.js';
+/**
+ * The synthetic condition name under which a throwing or malformed scope
+ * selector is reported. `$`-prefixed so it can never collide with an
+ * author's condition names. Declared by `@affordance/contract` — it reaches
+ * clients through `blocked[].unmet[].name`, so it is wire vocabulary, and
+ * the wire owns it; re-exported here for the engine's own consumers.
+ */
+export { SCOPE_FAILURE_CONDITION };
+/**
+ * A defective selection as a full evaluation record — the
+ * possible/permitted/available verdict stated once. The selection failed, so
+ * nothing about the step is possible
+ * on this case; `permits` were never reachable (they may read the element),
+ * reported vacuously satisfied — the requires-level `$scope` failure is the
+ * answer. The listing's blocked entry and `explain`'s answer for the same
+ * link both derive from this.
+ */
+export declare const scopeFailureEvaluation: (asOf: string, failure: {
+    readonly reason: string;
+}) => GuardEvaluation;
+/** What a guard is evaluated against, beyond state: the actor and the instant. */
+export interface ComputationContext<TActor = unknown> {
+    readonly actor: TActor;
+    /**
+     * The instant to evaluate as of — always explicit. Conditions cannot read
+     * the clock, so defaulting to now is the engine's job, done once at its
+     * boundary; everything below it is pure and reconstructable.
+     */
+    readonly asOf: Instant;
+}
+/** One element of a scoped step's selection, with the key that identifies it. */
+export interface ScopeBinding {
+    readonly element: unknown;
+    readonly key: string;
+}
+/**
+ * A step addressed by name (× scope key, if scoped): the step definition and
+ * its scope binding, resolved against a given Case State.
+ */
+export interface StepTarget<TState, TActor = unknown> {
+    readonly step: StepDefinition<TState, TActor>;
+    /**
+     * The Case State the target was resolved against — the document its guard
+     * is evaluated over. Carried on the target so a binding can never be
+     * evaluated against a different document than the one that produced it.
+     */
+    readonly state: TState;
+    /** The bound element and its key, or `null` for an unscoped step. */
+    readonly binding: ScopeBinding | null;
+}
+/** The outcome of scope fan-out: the step's targets, or why selection produced none. */
+export interface TargetSelection<TState, TActor = unknown> {
+    readonly targets: readonly StepTarget<TState, TActor>[];
+    /** The selection failure — a defective selector — or `null` when selection succeeded. */
+    readonly failure: {
+        readonly reason: string;
+    } | null;
+}
+/**
+ * The one implementation of scope fan-out — every consumer (the affordance
+ * listing, read tracing, addressing)
+ * is a filter over this function.
+ *
+ * An unscoped step yields exactly one target; a scoped step yields one per
+ * selected element, or none with a `failure` naming why when the selector is
+ * defective. {@link ScopeKeyError} — identity corruption — propagates: it is
+ * never a selection failure, and no caller may absorb it into "no targets".
+ */
+export declare const selectTargets: <TState, TActor>(step: StepDefinition<TState, TActor>, state: TState) => TargetSelection<TState, TActor>;
+/**
+ * Why an address does not resolve, by kind. Each failure carries the error
+ * the loud filter would throw, so the diagnosis (including the
+ * currently-valid scope keys, where knowable) is constructed exactly once
+ * and reads identically whether it is thrown at an addressed caller or
+ * reported by a sweep. The kind is what lets a filter treat one failure
+ * differently without re-deriving how the address failed — `explain`
+ * *answers* a defective selector (the listing published that exact link)
+ * and throws everything else.
+ */
+export type TargetAddressFailure = {
+    /** The named step is not declared on the case type. */
+    readonly kind: 'unknown-step';
+    readonly error: UnknownStepError;
+} | {
+    /** The selector threw or returned a non-array over this Case State. */
+    readonly kind: 'defective-selector';
+    /** The selection failure's own words — what the listing's `$scope` entry reports. */
+    readonly reason: string;
+    readonly error: ScopeKeyError;
+} | {
+    /**
+     * A scope-key problem on an otherwise healthy step: a key given for an
+     * unscoped step, a missing key on a scoped one, or a key no selected
+     * element carries.
+     */
+    readonly kind: 'unscoped-key' | 'missing-key' | 'unknown-key';
+    readonly error: ScopeKeyError;
+};
+/** The outcome of addressing a step: the target, or the precise failure. */
+export type TargetAddress<TState, TActor = unknown> = {
+    readonly target: StepTarget<TState, TActor>;
+    readonly failure: null;
+} | {
+    readonly target: null;
+    readonly failure: TargetAddressFailure;
+};
+/**
+ * The one implementation of addressing — "step X (of element K) on this
+ * state". Total over everything except key integrity: an undeclared step
+ * name, a missing/unknown scope key on a scoped step, a scope key on an
+ * unscoped step, and a defective scope selector all come back as `failure`.
+ * {@link ScopeKeyError} raised for duplicate or malformed keys (identity
+ * corruption, from {@link selectScope}) still propagates — no filter may
+ * absorb it.
+ */
+export declare const addressTarget: <S extends StandardSchemaV1, TActor>(definition: CaseTypeDefinition<S, TActor>, state: StandardSchemaV1.InferOutput<S>, stepName: string, scopeKey?: string) => TargetAddress<StandardSchemaV1.InferOutput<S>, TActor>;
+/**
+ * Resolve "step X (of element K) on this state" — the addressing shared by
+ * `explain` (a targeted probe) and the execution lifecycle's claim.
+ *
+ * The loud filter over {@link addressTarget}: an addressed caller named a
+ * case and a step and is owed an answer about *those*, so every way of
+ * failing to address throws with its precise message. Addressing a step you
+ * cannot name is a caller bug, not a blocked affordance.
+ */
+export declare const resolveTarget: <S extends StandardSchemaV1, TActor>(definition: CaseTypeDefinition<S, TActor>, state: StandardSchemaV1.InferOutput<S>, stepName: string, scopeKey?: string) => StepTarget<StandardSchemaV1.InferOutput<S>, TActor>;
+/**
+ * Evaluate one addressed step's guard against the state it was resolved on —
+ * the single evaluation shared by `explain` and the claim, so the enforcement
+ * moment and the explanation of it can never drift apart.
+ */
+export declare const evaluateTarget: <TState, TActor>(target: StepTarget<TState, TActor>, ctx: ComputationContext<TActor>) => GuardEvaluation;

package/dist/model/target.js

@@ -0,0 +1,236 @@
+/**
+ * Step targeting: resolving "step X, of element K, on this state".
+ *
+ * A **step target** is a step definition plus its scope binding — the pair
+ * that an affordance's identity (step × scope key) names. Everything
+ * that acts on a step goes through here first: the execution lifecycle's
+ * claim, `explain`, audit replay, and the affordance listing itself.
+ *
+ * It lives in the model because it is a fact about a {@link StepDefinition}
+ * and a Case State, and nothing more — no store, no registry, no clock. Put
+ * anywhere higher it would drag every consumer's imports upward toward the
+ * engine, which is a facade none of them should need.
+ *
+ * ## One fan-out, filtered
+ *
+ * {@link selectTargets} is the only implementation of fan-out — expanding
+ * one scoped step into its per-element targets — and it makes the one
+ * distinction every consumer needs:
+ *
+ * - A **defective selector** — one that throws over historical state, or
+ *   returns something other than an array — is a *selection failure*,
+ *   reported as `failure` with no targets. Each caller decides what its
+ *   audience deserves: the affordance listing renders it as a blocked
+ *   `$scope` entry, a sweep skips the step, {@link resolveTarget} throws.
+ * - A **key integrity violation** — duplicate or malformed scope keys —
+ *   corrupts affordance identity itself, so {@link ScopeKeyError} is loud
+ *   through every path. No caller may absorb it into an empty selection.
+ *
+ * Addressing — "step X (of element K) on this state" — is likewise one
+ * implementation, {@link addressTarget}, answering with the target or a
+ * {@link TargetAddressFailure} that names its kind. Its filters:
+ * {@link resolveTarget} (loud: an addressed caller is owed the precise
+ * failure, so it throws), audit replay (lenient: a sweep over the Journal
+ * reports the failure as a value and keeps going), and `explain` (loud,
+ * with one deliberate exception — a `defective-selector` failure is
+ * *answered*, because the listing published that exact link).
+ */
+import { SCOPE_FAILURE_CONDITION } from '@affordance/contract';
+import { thrownMessage } from '../errors.js';
+import { evaluateGuard } from '../guards/index.js';
+import { ScopeKeyError, UnknownStepError } from './errors.js';
+/**
+ * The synthetic condition name under which a throwing or malformed scope
+ * selector is reported. `$`-prefixed so it can never collide with an
+ * author's condition names. Declared by `@affordance/contract` — it reaches
+ * clients through `blocked[].unmet[].name`, so it is wire vocabulary, and
+ * the wire owns it; re-exported here for the engine's own consumers.
+ */
+export { SCOPE_FAILURE_CONDITION };
+/**
+ * The synthetic `$scope` entry as a condition result — the one spelling of
+ * how a failed scope selection reports into an evaluation-shaped record: a
+ * failed condition carrying the selector's reason.
+ */
+const scopeConditionResult = (failure) => ({
+    name: SCOPE_FAILURE_CONDITION,
+    section: 'requires',
+    kind: 'condition',
+    passed: false,
+    reason: failure.reason,
+});
+/**
+ * A defective selection as a full evaluation record — the
+ * possible/permitted/available verdict stated once. The selection failed, so
+ * nothing about the step is possible
+ * on this case; `permits` were never reachable (they may read the element),
+ * reported vacuously satisfied — the requires-level `$scope` failure is the
+ * answer. The listing's blocked entry and `explain`'s answer for the same
+ * link both derive from this.
+ */
+export const scopeFailureEvaluation = (asOf, failure) => ({
+    asOf,
+    possible: false,
+    permitted: true,
+    available: false,
+    conditions: [scopeConditionResult(failure)],
+});
+/**
+ * Select a scoped step's elements and derive their keys, enforcing key
+ * integrity: every key a non-empty string, unique within the selection —
+ * scope keys are affordance identity, so violations throw
+ * {@link ScopeKeyError} instead of degrading. A `select` that throws
+ * (totality bug) is left to the caller to absorb or report.
+ */
+const selectScope = (definition, scope, state) => {
+    const selected = scope.select(state);
+    if (!Array.isArray(selected)) {
+        throw new ScopeKeyError(definition.name, null, 'scope.select must return an array of elements');
+    }
+    const seen = new Set();
+    return selected.map((element) => {
+        let key;
+        try {
+            key = scope.key(element);
+        }
+        catch (err) {
+            throw new ScopeKeyError(definition.name, null, `scope.key threw: ${thrownMessage(err)}`);
+        }
+        if (typeof key !== 'string' || key === '') {
+            throw new ScopeKeyError(definition.name, null, 'scope.key must return a non-empty string for every element');
+        }
+        if (seen.has(key)) {
+            throw new ScopeKeyError(definition.name, key, `duplicate scope key '${key}' — scope keys are affordance identity and must be unique`);
+        }
+        seen.add(key);
+        return { element, key };
+    });
+};
+/**
+ * The one implementation of scope fan-out — every consumer (the affordance
+ * listing, read tracing, addressing)
+ * is a filter over this function.
+ *
+ * An unscoped step yields exactly one target; a scoped step yields one per
+ * selected element, or none with a `failure` naming why when the selector is
+ * defective. {@link ScopeKeyError} — identity corruption — propagates: it is
+ * never a selection failure, and no caller may absorb it into "no targets".
+ */
+export const selectTargets = (step, state) => {
+    if (step.scope === null)
+        return { targets: [{ step, state, binding: null }], failure: null };
+    try {
+        return {
+            targets: selectScope(step, step.scope, state).map((binding) => ({
+                step,
+                state,
+                binding,
+            })),
+            failure: null,
+        };
+    }
+    catch (err) {
+        if (err instanceof ScopeKeyError)
+            throw err;
+        return {
+            targets: [],
+            failure: { reason: `scope selector threw: ${thrownMessage(err)}` },
+        };
+    }
+};
+/**
+ * The one implementation of addressing — "step X (of element K) on this
+ * state". Total over everything except key integrity: an undeclared step
+ * name, a missing/unknown scope key on a scoped step, a scope key on an
+ * unscoped step, and a defective scope selector all come back as `failure`.
+ * {@link ScopeKeyError} raised for duplicate or malformed keys (identity
+ * corruption, from {@link selectScope}) still propagates — no filter may
+ * absorb it.
+ */
+export const addressTarget = (definition, state, stepName, scopeKey) => {
+    const stepDefinition = definition.getStep(stepName);
+    if (stepDefinition === undefined) {
+        return {
+            target: null,
+            failure: {
+                kind: 'unknown-step',
+                error: new UnknownStepError(definition.name, stepName, definition.steps.map((declared) => declared.name)),
+            },
+        };
+    }
+    if (stepDefinition.scope === null) {
+        if (scopeKey !== undefined) {
+            return {
+                target: null,
+                failure: {
+                    kind: 'unscoped-key',
+                    error: new ScopeKeyError(stepName, scopeKey, `scope key '${scopeKey}' given, but the step is not scoped`),
+                },
+            };
+        }
+        return {
+            target: { step: stepDefinition, state, binding: null },
+            failure: null,
+        };
+    }
+    const selection = selectTargets(stepDefinition, state);
+    if (selection.failure !== null) {
+        return {
+            target: null,
+            failure: {
+                kind: 'defective-selector',
+                reason: selection.failure.reason,
+                error: new ScopeKeyError(stepName, scopeKey ?? null, selection.failure.reason),
+            },
+        };
+    }
+    const known = selection.targets.map((target) => target.binding?.key ?? '');
+    const selected = known.length > 0 ? known.join(', ') : '(no elements in scope)';
+    if (scopeKey === undefined) {
+        return {
+            target: null,
+            failure: {
+                kind: 'missing-key',
+                error: new ScopeKeyError(stepName, null, `scoped step: a scopeKey is required — currently selected: ${selected}`),
+            },
+        };
+    }
+    const bound = selection.targets.find((target) => target.binding?.key === scopeKey);
+    if (bound === undefined) {
+        return {
+            target: null,
+            failure: {
+                kind: 'unknown-key',
+                error: new ScopeKeyError(stepName, scopeKey, `no element in scope has key '${scopeKey}' — currently selected: ${selected}`),
+            },
+        };
+    }
+    return { target: bound, failure: null };
+};
+/**
+ * Resolve "step X (of element K) on this state" — the addressing shared by
+ * `explain` (a targeted probe) and the execution lifecycle's claim.
+ *
+ * The loud filter over {@link addressTarget}: an addressed caller named a
+ * case and a step and is owed an answer about *those*, so every way of
+ * failing to address throws with its precise message. Addressing a step you
+ * cannot name is a caller bug, not a blocked affordance.
+ */
+export const resolveTarget = (definition, state, stepName, scopeKey) => {
+    const address = addressTarget(definition, state, stepName, scopeKey);
+    if (address.failure !== null)
+        throw address.failure.error;
+    return address.target;
+};
+/**
+ * Evaluate one addressed step's guard against the state it was resolved on —
+ * the single evaluation shared by `explain` and the claim, so the enforcement
+ * moment and the explanation of it can never drift apart.
+ */
+export const evaluateTarget = (target, ctx) => evaluateGuard(target.step.guard, {
+    state: target.state,
+    actor: ctx.actor,
+    asOf: ctx.asOf,
+    ...(target.binding !== null && { scope: target.binding.element }),
+});
+//# sourceMappingURL=target.js.map

package/dist/model/target.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"target.js","sourceRoot":"","sources":["../../src/model/target.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,OAAO,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAA;AAE9D,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAM5C,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAElD,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAG7D;;;;;;GAMG;AACH,OAAO,EAAE,uBAAuB,EAAE,CAAA;AAElC;;;;GAIG;AACH,MAAM,oBAAoB,GAAG,CAAC,OAE7B,EAAyB,EAAE,CAAC,CAAC;IAC5B,IAAI,EAAE,uBAAuB;IAC7B,OAAO,EAAE,UAAU;IACnB,IAAI,EAAE,WAAW;IACjB,MAAM,EAAE,KAAK;IACb,MAAM,EAAE,OAAO,CAAC,MAAM;CACvB,CAAC,CAAA;AAEF;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,CACpC,IAAY,EACZ,OAAoC,EACnB,EAAE,CAAC,CAAC;IACrB,IAAI;IACJ,QAAQ,EAAE,KAAK;IACf,SAAS,EAAE,IAAI;IACf,SAAS,EAAE,KAAK;IAChB,UAAU,EAAE,CAAC,oBAAoB,CAAC,OAAO,CAAC,CAAC;CAC5C,CAAC,CAAA;AA0CF;;;;;;GAMG;AACH,MAAM,WAAW,GAAG,CAClB,UAA0C,EAC1C,KAA2D,EAC3D,KAAa,EACY,EAAE;IAC3B,MAAM,QAAQ,GAAG,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;IACpC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC7B,MAAM,IAAI,aAAa,CACrB,UAAU,CAAC,IAAI,EACf,IAAI,EACJ,+CAA+C,CAChD,CAAA;IACH,CAAC;IACD,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAA;IAC9B,OAAO,QAAQ,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE;QAC9B,IAAI,GAAY,CAAA;QAChB,IAAI,CAAC;YACH,GAAG,GAAG,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC,CAAA;QAC1B,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,IAAI,aAAa,CACrB,UAAU,CAAC,IAAI,EACf,IAAI,EACJ,oBAAoB,aAAa,CAAC,GAAG,CAAC,EAAE,CACzC,CAAA;QACH,CAAC;QACD,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,EAAE,EAAE,CAAC;YAC1C,MAAM,IAAI,aAAa,CACrB,UAAU,CAAC,IAAI,EACf,IAAI,EACJ,4DAA4D,CAC7D,CAAA;QACH,CAAC;QACD,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YAClB,MAAM,IAAI,aAAa,CACrB,UAAU,CAAC,IAAI,EACf,GAAG,EACH,wBAAwB,GAAG,2DAA2D,CACvF,CAAA;QACH,CAAC;QACD,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;QACb,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,CAAA;IACzB,CAAC,CAAC,CAAA;AACJ,CAAC,CAAA;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,CAC3B,IAAoC,EACpC,KAAa,EACoB,EAAE;IACnC,IAAI,IAAI,CAAC,KAAK,KAAK,IAAI;QACrB,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAA;IACrE,IAAI,CAAC;QACH,OAAO;YACL,OAAO,EAAE,WAAW,CAAC,IAAI,EAAE,IAAI,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;gBAC9D,IAAI;gBACJ,KAAK;gBACL,OAAO;aACR,CAAC,CAAC;YACH,OAAO,EAAE,IAAI;SACd,CAAA;IACH,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,GAAG,YAAY,aAAa;YAAE,MAAM,GAAG,CAAA;QAC3C,OAAO;YACL,OAAO,EAAE,EAAE;YACX,OAAO,EAAE,EAAE,MAAM,EAAE,yBAAyB,aAAa,CAAC,GAAG,CAAC,EAAE,EAAE;SACnE,CAAA;IACH,CAAC;AACH,CAAC,CAAA;AAwCD;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,CAC3B,UAAyC,EACzC,KAAsC,EACtC,QAAgB,EAChB,QAAiB,EACuC,EAAE;IAC1D,MAAM,cAAc,GAAG,UAAU,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAA;IACnD,IAAI,cAAc,KAAK,SAAS,EAAE,CAAC;QACjC,OAAO;YACL,MAAM,EAAE,IAAI;YACZ,OAAO,EAAE;gBACP,IAAI,EAAE,cAAc;gBACpB,KAAK,EAAE,IAAI,gBAAgB,CACzB,UAAU,CAAC,IAAI,EACf,QAAQ,EACR,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,CAClD;aACF;SACF,CAAA;IACH,CAAC;IAED,IAAI,cAAc,CAAC,KAAK,KAAK,IAAI,EAAE,CAAC;QAClC,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;YAC3B,OAAO;gBACL,MAAM,EAAE,IAAI;gBACZ,OAAO,EAAE;oBACP,IAAI,EAAE,cAAc;oBACpB,KAAK,EAAE,IAAI,aAAa,CACtB,QAAQ,EACR,QAAQ,EACR,cAAc,QAAQ,qCAAqC,CAC5D;iBACF;aACF,CAAA;QACH,CAAC;QACD,OAAO;YACL,MAAM,EAAE,EAAE,IAAI,EAAE,cAAc,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE;YACtD,OAAO,EAAE,IAAI;SACd,CAAA;IACH,CAAC;IAED,MAAM,SAAS,GAAG,aAAa,CAAC,cAAc,EAAE,KAAK,CAAC,CAAA;IACtD,IAAI,SAAS,CAAC,OAAO,KAAK,IAAI,EAAE,CAAC;QAC/B,OAAO;YACL,MAAM,EAAE,IAAI;YACZ,OAAO,EAAE;gBACP,IAAI,EAAE,oBAAoB;gBAC1B,MAAM,EAAE,SAAS,CAAC,OAAO,CAAC,MAAM;gBAChC,KAAK,EAAE,IAAI,aAAa,CACtB,QAAQ,EACR,QAAQ,IAAI,IAAI,EAChB,SAAS,CAAC,OAAO,CAAC,MAAM,CACzB;aACF;SACF,CAAA;IACH,CAAC;IACD,MAAM,KAAK,GAAG,SAAS,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,OAAO,EAAE,GAAG,IAAI,EAAE,CAAC,CAAA;IAC1E,MAAM,QAAQ,GACZ,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,wBAAwB,CAAA;IAChE,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC3B,OAAO;YACL,MAAM,EAAE,IAAI;YACZ,OAAO,EAAE;gBACP,IAAI,EAAE,aAAa;gBACnB,KAAK,EAAE,IAAI,aAAa,CACtB,QAAQ,EACR,IAAI,EACJ,6DAA6D,QAAQ,EAAE,CACxE;aACF;SACF,CAAA;IACH,CAAC;IACD,MAAM,KAAK,GAAG,SAAS,CAAC,OAAO,CAAC,IAAI,CAClC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,OAAO,EAAE,GAAG,KAAK,QAAQ,CAC7C,CAAA;IACD,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxB,OAAO;YACL,MAAM,EAAE,IAAI;YACZ,OAAO,EAAE;gBACP,IAAI,EAAE,aAAa;gBACnB,KAAK,EAAE,IAAI,aAAa,CACtB,QAAQ,EACR,QAAQ,EACR,gCAAgC,QAAQ,2BAA2B,QAAQ,EAAE,CAC9E;aACF;SACF,CAAA;IACH,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,CAAA;AACzC,CAAC,CAAA;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,CAC3B,UAAyC,EACzC,KAAsC,EACtC,QAAgB,EAChB,QAAiB,EACoC,EAAE;IACvD,MAAM,OAAO,GAAG,aAAa,CAAC,UAAU,EAAE,KAAK,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAA;IACpE,IAAI,OAAO,CAAC,OAAO,KAAK,IAAI;QAAE,MAAM,OAAO,CAAC,OAAO,CAAC,KAAK,CAAA;IACzD,OAAO,OAAO,CAAC,MAAM,CAAA;AACvB,CAAC,CAAA;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAC5B,MAAkC,EAClC,GAA+B,EACd,EAAE,CACnB,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,EAAE;IAC/B,KAAK,EAAE,MAAM,CAAC,KAAK;IACnB,KAAK,EAAE,GAAG,CAAC,KAAK;IAChB,IAAI,EAAE,GAAG,CAAC,IAAI;IACd,GAAG,CAAC,MAAM,CAAC,OAAO,KAAK,IAAI,IAAI,EAAE,KAAK,EAAE,MAAM,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC;CAClE,CAAC,CAAA","sourcesContent":["/**\n * Step targeting: resolving \"step X, of element K, on this state\".\n *\n * A **step target** is a step definition plus its scope binding — the pair\n * that an affordance's identity (step × scope key) names. Everything\n * that acts on a step goes through here first: the execution lifecycle's\n * claim, `explain`, audit replay, and the affordance listing itself.\n *\n * It lives in the model because it is a fact about a {@link StepDefinition}\n * and a Case State, and nothing more — no store, no registry, no clock. Put\n * anywhere higher it would drag every consumer's imports upward toward the\n * engine, which is a facade none of them should need.\n *\n * ## One fan-out, filtered\n *\n * {@link selectTargets} is the only implementation of fan-out — expanding\n * one scoped step into its per-element targets — and it makes the one\n * distinction every consumer needs:\n *\n * - A **defective selector** — one that throws over historical state, or\n *   returns something other than an array — is a *selection failure*,\n *   reported as `failure` with no targets. Each caller decides what its\n *   audience deserves: the affordance listing renders it as a blocked\n *   `$scope` entry, a sweep skips the step, {@link resolveTarget} throws.\n * - A **key integrity violation** — duplicate or malformed scope keys —\n *   corrupts affordance identity itself, so {@link ScopeKeyError} is loud\n *   through every path. No caller may absorb it into an empty selection.\n *\n * Addressing — \"step X (of element K) on this state\" — is likewise one\n * implementation, {@link addressTarget}, answering with the target or a\n * {@link TargetAddressFailure} that names its kind. Its filters:\n * {@link resolveTarget} (loud: an addressed caller is owed the precise\n * failure, so it throws), audit replay (lenient: a sweep over the Journal\n * reports the failure as a value and keeps going), and `explain` (loud,\n * with one deliberate exception — a `defective-selector` failure is\n * *answered*, because the listing published that exact link).\n */\n\nimport { SCOPE_FAILURE_CONDITION } from '@affordance/contract'\nimport type { StandardSchemaV1 } from '@standard-schema/spec'\nimport { thrownMessage } from '../errors.js'\nimport type {\n  GuardEvaluation,\n  Instant,\n  SingleConditionResult,\n} from '../guards/index.js'\nimport { evaluateGuard } from '../guards/index.js'\nimport type { CaseTypeDefinition } from './casetype.js'\nimport { ScopeKeyError, UnknownStepError } from './errors.js'\nimport type { StepDefinition } from './step.js'\n\n/**\n * The synthetic condition name under which a throwing or malformed scope\n * selector is reported. `$`-prefixed so it can never collide with an\n * author's condition names. Declared by `@affordance/contract` — it reaches\n * clients through `blocked[].unmet[].name`, so it is wire vocabulary, and\n * the wire owns it; re-exported here for the engine's own consumers.\n */\nexport { SCOPE_FAILURE_CONDITION }\n\n/**\n * The synthetic `$scope` entry as a condition result — the one spelling of\n * how a failed scope selection reports into an evaluation-shaped record: a\n * failed condition carrying the selector's reason.\n */\nconst scopeConditionResult = (failure: {\n  readonly reason: string\n}): SingleConditionResult => ({\n  name: SCOPE_FAILURE_CONDITION,\n  section: 'requires',\n  kind: 'condition',\n  passed: false,\n  reason: failure.reason,\n})\n\n/**\n * A defective selection as a full evaluation record — the\n * possible/permitted/available verdict stated once. The selection failed, so\n * nothing about the step is possible\n * on this case; `permits` were never reachable (they may read the element),\n * reported vacuously satisfied — the requires-level `$scope` failure is the\n * answer. The listing's blocked entry and `explain`'s answer for the same\n * link both derive from this.\n */\nexport const scopeFailureEvaluation = (\n  asOf: string,\n  failure: { readonly reason: string },\n): GuardEvaluation => ({\n  asOf,\n  possible: false,\n  permitted: true,\n  available: false,\n  conditions: [scopeConditionResult(failure)],\n})\n\n/** What a guard is evaluated against, beyond state: the actor and the instant. */\nexport interface ComputationContext<TActor = unknown> {\n  readonly actor: TActor\n  /**\n   * The instant to evaluate as of — always explicit. Conditions cannot read\n   * the clock, so defaulting to now is the engine's job, done once at its\n   * boundary; everything below it is pure and reconstructable.\n   */\n  readonly asOf: Instant\n}\n\n/** One element of a scoped step's selection, with the key that identifies it. */\nexport interface ScopeBinding {\n  readonly element: unknown\n  readonly key: string\n}\n\n/**\n * A step addressed by name (× scope key, if scoped): the step definition and\n * its scope binding, resolved against a given Case State.\n */\nexport interface StepTarget<TState, TActor = unknown> {\n  readonly step: StepDefinition<TState, TActor>\n  /**\n   * The Case State the target was resolved against — the document its guard\n   * is evaluated over. Carried on the target so a binding can never be\n   * evaluated against a different document than the one that produced it.\n   */\n  readonly state: TState\n  /** The bound element and its key, or `null` for an unscoped step. */\n  readonly binding: ScopeBinding | null\n}\n\n/** The outcome of scope fan-out: the step's targets, or why selection produced none. */\nexport interface TargetSelection<TState, TActor = unknown> {\n  readonly targets: readonly StepTarget<TState, TActor>[]\n  /** The selection failure — a defective selector — or `null` when selection succeeded. */\n  readonly failure: { readonly reason: string } | null\n}\n\n/**\n * Select a scoped step's elements and derive their keys, enforcing key\n * integrity: every key a non-empty string, unique within the selection —\n * scope keys are affordance identity, so violations throw\n * {@link ScopeKeyError} instead of degrading. A `select` that throws\n * (totality bug) is left to the caller to absorb or report.\n */\nconst selectScope = <TState, TActor>(\n  definition: StepDefinition<TState, TActor>,\n  scope: NonNullable<StepDefinition<TState, TActor>['scope']>,\n  state: TState,\n): readonly ScopeBinding[] => {\n  const selected = scope.select(state)\n  if (!Array.isArray(selected)) {\n    throw new ScopeKeyError(\n      definition.name,\n      null,\n      'scope.select must return an array of elements',\n    )\n  }\n  const seen = new Set<string>()\n  return selected.map((element) => {\n    let key: unknown\n    try {\n      key = scope.key(element)\n    } catch (err) {\n      throw new ScopeKeyError(\n        definition.name,\n        null,\n        `scope.key threw: ${thrownMessage(err)}`,\n      )\n    }\n    if (typeof key !== 'string' || key === '') {\n      throw new ScopeKeyError(\n        definition.name,\n        null,\n        'scope.key must return a non-empty string for every element',\n      )\n    }\n    if (seen.has(key)) {\n      throw new ScopeKeyError(\n        definition.name,\n        key,\n        `duplicate scope key '${key}' — scope keys are affordance identity and must be unique`,\n      )\n    }\n    seen.add(key)\n    return { element, key }\n  })\n}\n\n/**\n * The one implementation of scope fan-out — every consumer (the affordance\n * listing, read tracing, addressing)\n * is a filter over this function.\n *\n * An unscoped step yields exactly one target; a scoped step yields one per\n * selected element, or none with a `failure` naming why when the selector is\n * defective. {@link ScopeKeyError} — identity corruption — propagates: it is\n * never a selection failure, and no caller may absorb it into \"no targets\".\n */\nexport const selectTargets = <TState, TActor>(\n  step: StepDefinition<TState, TActor>,\n  state: TState,\n): TargetSelection<TState, TActor> => {\n  if (step.scope === null)\n    return { targets: [{ step, state, binding: null }], failure: null }\n  try {\n    return {\n      targets: selectScope(step, step.scope, state).map((binding) => ({\n        step,\n        state,\n        binding,\n      })),\n      failure: null,\n    }\n  } catch (err) {\n    if (err instanceof ScopeKeyError) throw err\n    return {\n      targets: [],\n      failure: { reason: `scope selector threw: ${thrownMessage(err)}` },\n    }\n  }\n}\n\n/**\n * Why an address does not resolve, by kind. Each failure carries the error\n * the loud filter would throw, so the diagnosis (including the\n * currently-valid scope keys, where knowable) is constructed exactly once\n * and reads identically whether it is thrown at an addressed caller or\n * reported by a sweep. The kind is what lets a filter treat one failure\n * differently without re-deriving how the address failed — `explain`\n * *answers* a defective selector (the listing published that exact link)\n * and throws everything else.\n */\nexport type TargetAddressFailure =\n  | {\n      /** The named step is not declared on the case type. */\n      readonly kind: 'unknown-step'\n      readonly error: UnknownStepError\n    }\n  | {\n      /** The selector threw or returned a non-array over this Case State. */\n      readonly kind: 'defective-selector'\n      /** The selection failure's own words — what the listing's `$scope` entry reports. */\n      readonly reason: string\n      readonly error: ScopeKeyError\n    }\n  | {\n      /**\n       * A scope-key problem on an otherwise healthy step: a key given for an\n       * unscoped step, a missing key on a scoped one, or a key no selected\n       * element carries.\n       */\n      readonly kind: 'unscoped-key' | 'missing-key' | 'unknown-key'\n      readonly error: ScopeKeyError\n    }\n\n/** The outcome of addressing a step: the target, or the precise failure. */\nexport type TargetAddress<TState, TActor = unknown> =\n  | { readonly target: StepTarget<TState, TActor>; readonly failure: null }\n  | { readonly target: null; readonly failure: TargetAddressFailure }\n\n/**\n * The one implementation of addressing — \"step X (of element K) on this\n * state\". Total over everything except key integrity: an undeclared step\n * name, a missing/unknown scope key on a scoped step, a scope key on an\n * unscoped step, and a defective scope selector all come back as `failure`.\n * {@link ScopeKeyError} raised for duplicate or malformed keys (identity\n * corruption, from {@link selectScope}) still propagates — no filter may\n * absorb it.\n */\nexport const addressTarget = <S extends StandardSchemaV1, TActor>(\n  definition: CaseTypeDefinition<S, TActor>,\n  state: StandardSchemaV1.InferOutput<S>,\n  stepName: string,\n  scopeKey?: string,\n): TargetAddress<StandardSchemaV1.InferOutput<S>, TActor> => {\n  const stepDefinition = definition.getStep(stepName)\n  if (stepDefinition === undefined) {\n    return {\n      target: null,\n      failure: {\n        kind: 'unknown-step',\n        error: new UnknownStepError(\n          definition.name,\n          stepName,\n          definition.steps.map((declared) => declared.name),\n        ),\n      },\n    }\n  }\n\n  if (stepDefinition.scope === null) {\n    if (scopeKey !== undefined) {\n      return {\n        target: null,\n        failure: {\n          kind: 'unscoped-key',\n          error: new ScopeKeyError(\n            stepName,\n            scopeKey,\n            `scope key '${scopeKey}' given, but the step is not scoped`,\n          ),\n        },\n      }\n    }\n    return {\n      target: { step: stepDefinition, state, binding: null },\n      failure: null,\n    }\n  }\n\n  const selection = selectTargets(stepDefinition, state)\n  if (selection.failure !== null) {\n    return {\n      target: null,\n      failure: {\n        kind: 'defective-selector',\n        reason: selection.failure.reason,\n        error: new ScopeKeyError(\n          stepName,\n          scopeKey ?? null,\n          selection.failure.reason,\n        ),\n      },\n    }\n  }\n  const known = selection.targets.map((target) => target.binding?.key ?? '')\n  const selected =\n    known.length > 0 ? known.join(', ') : '(no elements in scope)'\n  if (scopeKey === undefined) {\n    return {\n      target: null,\n      failure: {\n        kind: 'missing-key',\n        error: new ScopeKeyError(\n          stepName,\n          null,\n          `scoped step: a scopeKey is required — currently selected: ${selected}`,\n        ),\n      },\n    }\n  }\n  const bound = selection.targets.find(\n    (target) => target.binding?.key === scopeKey,\n  )\n  if (bound === undefined) {\n    return {\n      target: null,\n      failure: {\n        kind: 'unknown-key',\n        error: new ScopeKeyError(\n          stepName,\n          scopeKey,\n          `no element in scope has key '${scopeKey}' — currently selected: ${selected}`,\n        ),\n      },\n    }\n  }\n  return { target: bound, failure: null }\n}\n\n/**\n * Resolve \"step X (of element K) on this state\" — the addressing shared by\n * `explain` (a targeted probe) and the execution lifecycle's claim.\n *\n * The loud filter over {@link addressTarget}: an addressed caller named a\n * case and a step and is owed an answer about *those*, so every way of\n * failing to address throws with its precise message. Addressing a step you\n * cannot name is a caller bug, not a blocked affordance.\n */\nexport const resolveTarget = <S extends StandardSchemaV1, TActor>(\n  definition: CaseTypeDefinition<S, TActor>,\n  state: StandardSchemaV1.InferOutput<S>,\n  stepName: string,\n  scopeKey?: string,\n): StepTarget<StandardSchemaV1.InferOutput<S>, TActor> => {\n  const address = addressTarget(definition, state, stepName, scopeKey)\n  if (address.failure !== null) throw address.failure.error\n  return address.target\n}\n\n/**\n * Evaluate one addressed step's guard against the state it was resolved on —\n * the single evaluation shared by `explain` and the claim, so the enforcement\n * moment and the explanation of it can never drift apart.\n */\nexport const evaluateTarget = <TState, TActor>(\n  target: StepTarget<TState, TActor>,\n  ctx: ComputationContext<TActor>,\n): GuardEvaluation =>\n  evaluateGuard(target.step.guard, {\n    state: target.state,\n    actor: ctx.actor,\n    asOf: ctx.asOf,\n    ...(target.binding !== null && { scope: target.binding.element }),\n  })\n"]}

package/dist/store/bootstrap.d.ts

@@ -0,0 +1,57 @@
+import type { Queryable } from './queryable.js';
+/**
+ * Dedicated Postgres schema owning all framework tables.
+ * Named `affordance` because `case` itself is a SQL reserved word.
+ */
+export declare const FRAMEWORK_SCHEMA = "affordance";
+/**
+ * The DDL revision below. Bump it whenever the DDL changes: a database
+ * already carrying this version skips the DDL entirely, which is what keeps
+ * a start-up from touching a busy database at all.
+ */
+export declare const SCHEMA_VERSION = 4;
+/**
+ * Every framework table that holds rows belonging to one case, with the
+ * column that names the case — listed in an order safe to delete from
+ * (children first; everything references `cases`). **The one answer to
+ * "which tables does the framework own"** outside the DDL above: a consumer
+ * that sweeps per-case rows (a dev console's case purge, a test harness's
+ * cleanup) iterates this instead of keeping a private copy that goes stale
+ * the release a table is added.
+ *
+ * `ingested_events.case_id` is nullable — an unrouted event belongs to no
+ * case and survives a per-case sweep, which is correct: it was never about
+ * the deleted case.
+ */
+export declare const CASE_TABLES: readonly [{
+    readonly table: "journal";
+    readonly caseColumn: "case_id";
+}, {
+    readonly table: "claims";
+    readonly caseColumn: "case_id";
+}, {
+    readonly table: "correlations";
+    readonly caseColumn: "case_id";
+}, {
+    readonly table: "ingested_events";
+    readonly caseColumn: "case_id";
+}, {
+    readonly table: "cases";
+    readonly caseColumn: "id";
+}];
+/**
+ * Idempotent DDL bootstrap for the framework schema. Safe to call on every
+ * app start and from concurrent processes: the statements are sent as one
+ * multi-statement simple query, which Postgres runs on one connection inside
+ * a single implicit transaction, and the leading `pg_advisory_xact_lock`
+ * serializes racing bootstraps (concurrent `CREATE ... IF NOT EXISTS` can
+ * otherwise fail on catalog uniqueness).
+ *
+ * Also safe to call against a *busy* database, which is the harder promise,
+ * and is answered twice over. First, a bootstrap with nothing to do does
+ * nothing at all: {@link isCurrent} checks the version marker and returns
+ * before any DDL runs, so the common case takes no table locks whatsoever.
+ * Second, when there *is* work, the transaction bounds its own lock wait and
+ * this retries it — schema management yields to live work, never the reverse.
+ */
+export declare const bootstrap: (db: Queryable, attempts?: number) => Promise<void>;