@affordance/core 0.1.0

package/dist/execution/errors.js

@@ -0,0 +1,132 @@
+/**
+ * The ways an Execution can be refused or fail.
+ *
+ * Each is a distinct answer to "why didn't this run", and callers are
+ * expected to branch on them: {@link StepNotAvailableError} is a client-facing
+ * *no* with reasons attached; {@link CaseBusyError} is "not now, try again";
+ * {@link ClaimLostError} and {@link StepExecutionError} are failures of a run
+ * that did start.
+ */
+import { AffordanceError, thrownMessage } from '../errors.js';
+import { describeUnmet, unmetConditions } from '../guards/index.js';
+/**
+ * How a step (× scope element) is named in prose: `'close-purchase'`, or
+ * `'request-re-sign' (buyer_7)` when scoped. One spelling, because refusal
+ * messages and adapter renderings must name the same affordance identically.
+ */
+export const stepLabel = (stepName, scopeKey) => scopeKey === null ? `'${stepName}'` : `'${stepName}' (${scopeKey})`;
+/**
+ * The claim's transactional guard re-evaluation said no — the enforcement
+ * moment. Guards advise; handlers enforce: an affordance computed
+ * for a render is advice, and by the time the execute request arrives, state
+ * may have moved (another Execution committed) or the definitions may have
+ * (a deploy tightened the guard — definition drift is handled by the
+ * same mechanism as state races).
+ *
+ * The unmet conditions carried here are the *current* ones, evaluated inside
+ * the claim transaction, so a rejection is self-explaining: hand `unmet`
+ * straight back to the caller.
+ */
+export class StepNotAvailableError extends AffordanceError {
+    caseId;
+    stepName;
+    scopeKey;
+    /** False when a `requires` condition is unmet: not possible on this case, for anyone. */
+    possible;
+    /** False when a `permits` condition is unmet: possible, but not for this actor. */
+    permitted;
+    /** The failed condition results, verbatim from the claim-time evaluation. */
+    unmet;
+    /** The full evaluation record, for journaling or `explain`-style rendering. */
+    evaluation;
+    constructor(caseId, stepName, scopeKey, evaluation) {
+        const unmet = unmetConditions(evaluation);
+        const target = stepLabel(stepName, scopeKey);
+        super('step-not-available', `step ${target} is not available on case ${caseId}: ${describeUnmet(evaluation) || '(no unmet conditions reported)'}`);
+        this.name = 'StepNotAvailableError';
+        this.caseId = caseId;
+        this.stepName = stepName;
+        this.scopeKey = scopeKey;
+        this.possible = evaluation.possible;
+        this.permitted = evaluation.permitted;
+        this.unmet = unmet;
+        this.evaluation = evaluation;
+    }
+}
+/**
+ * Another Execution is already in flight on this case and its claim has not
+ * expired. Executions are serialized per case in v1 — cases advance at human
+ * pace, so one Execution at a time costs no real throughput — which makes
+ * this "not now", not "never": retry after
+ * {@link CaseBusyError.expiresAt} at the latest.
+ */
+export class CaseBusyError extends AffordanceError {
+    caseId;
+    /** The in-flight Execution holding the case. */
+    executionId;
+    stepName;
+    scopeKey;
+    /** When the in-flight claim lapses if its handler stops heartbeating (ISO-8601 UTC). */
+    expiresAt;
+    constructor(caseId, holder) {
+        super('case-busy', `case ${caseId} is busy: execution ${holder.executionId} is running step ${stepLabel(holder.stepName, holder.scopeKey)}, claim expires ${holder.expiresAt}`);
+        this.name = 'CaseBusyError';
+        this.caseId = caseId;
+        this.executionId = holder.executionId;
+        this.stepName = holder.stepName;
+        this.scopeKey = holder.scopeKey;
+        this.expiresAt = holder.expiresAt;
+    }
+}
+/**
+ * The claim was gone (or belonged to someone else) when this Execution tried
+ * to commit: its lease expired mid-handler and another claimant took the case
+ * over. The handler's effects on the outside world already happened — they are
+ * at-least-once by contract and deduplicated on `executionId` — but
+ * its Case State write is refused, because the state it computed from is stale.
+ */
+export class ClaimLostError extends AffordanceError {
+    caseId;
+    executionId;
+    /** The Execution now holding the case, if any. */
+    heldBy;
+    constructor(caseId, executionId, heldBy) {
+        super(
+        // The case moved on under this Execution: somebody else holds it now,
+        // and the state this Execution computed from is stale. That is the
+        // same "not now" answer a busy case gives, so it reuses 'case-busy' —
+        // a code an adapter already knows how to render.
+        'case-busy', `execution ${executionId} lost its claim on case ${caseId}${heldBy === null
+            ? ' (claim expired and was released)'
+            : ` (now held by ${heldBy})`} — its state write was refused`);
+        this.name = 'ClaimLostError';
+        this.caseId = caseId;
+        this.executionId = executionId;
+        this.heldBy = heldBy;
+    }
+}
+/**
+ * The Execution ran and failed: the handler threw on every allowed attempt,
+ * or it returned a Case State the case type's schema rejects (a deterministic
+ * defect, failed without retry). A `failed` journal entry records it and the
+ * case is released.
+ */
+export class StepExecutionError extends AffordanceError {
+    caseId;
+    executionId;
+    stepName;
+    scopeKey;
+    /** How many attempts ran before the Execution was given up on. */
+    attempts;
+    constructor(caseId, executionId, stepName, scopeKey, attempts, cause) {
+        const reason = thrownMessage(cause);
+        super('execution-failed', `step ${stepLabel(stepName, scopeKey)} failed on case ${caseId} after ${attempts} attempt${attempts === 1 ? '' : 's'}: ${reason}`, { cause });
+        this.name = 'StepExecutionError';
+        this.caseId = caseId;
+        this.executionId = executionId;
+        this.stepName = stepName;
+        this.scopeKey = scopeKey;
+        this.attempts = attempts;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/execution/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/execution/errors.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The ways an Execution can be refused or fail.\n *\n * Each is a distinct answer to \"why didn't this run\", and callers are\n * expected to branch on them: {@link StepNotAvailableError} is a client-facing\n * *no* with reasons attached; {@link CaseBusyError} is \"not now, try again\";\n * {@link ClaimLostError} and {@link StepExecutionError} are failures of a run\n * that did start.\n */\n\nimport { AffordanceError, thrownMessage } from '../errors.js'\nimport type { ConditionResult, GuardEvaluation } from '../guards/index.js'\nimport { describeUnmet, unmetConditions } from '../guards/index.js'\n\n/**\n * How a step (× scope element) is named in prose: `'close-purchase'`, or\n * `'request-re-sign' (buyer_7)` when scoped. One spelling, because refusal\n * messages and adapter renderings must name the same affordance identically.\n */\nexport const stepLabel = (stepName: string, scopeKey: string | null): string =>\n  scopeKey === null ? `'${stepName}'` : `'${stepName}' (${scopeKey})`\n\n/**\n * The claim's transactional guard re-evaluation said no — the enforcement\n * moment. Guards advise; handlers enforce: an affordance computed\n * for a render is advice, and by the time the execute request arrives, state\n * may have moved (another Execution committed) or the definitions may have\n * (a deploy tightened the guard — definition drift is handled by the\n * same mechanism as state races).\n *\n * The unmet conditions carried here are the *current* ones, evaluated inside\n * the claim transaction, so a rejection is self-explaining: hand `unmet`\n * straight back to the caller.\n */\nexport class StepNotAvailableError extends AffordanceError {\n  readonly caseId: string\n  readonly stepName: string\n  readonly scopeKey: string | null\n  /** False when a `requires` condition is unmet: not possible on this case, for anyone. */\n  readonly possible: boolean\n  /** False when a `permits` condition is unmet: possible, but not for this actor. */\n  readonly permitted: boolean\n  /** The failed condition results, verbatim from the claim-time evaluation. */\n  readonly unmet: readonly ConditionResult[]\n  /** The full evaluation record, for journaling or `explain`-style rendering. */\n  readonly evaluation: GuardEvaluation\n\n  constructor(\n    caseId: string,\n    stepName: string,\n    scopeKey: string | null,\n    evaluation: GuardEvaluation,\n  ) {\n    const unmet = unmetConditions(evaluation)\n    const target = stepLabel(stepName, scopeKey)\n    super(\n      'step-not-available',\n      `step ${target} is not available on case ${caseId}: ${\n        describeUnmet(evaluation) || '(no unmet conditions reported)'\n      }`,\n    )\n    this.name = 'StepNotAvailableError'\n    this.caseId = caseId\n    this.stepName = stepName\n    this.scopeKey = scopeKey\n    this.possible = evaluation.possible\n    this.permitted = evaluation.permitted\n    this.unmet = unmet\n    this.evaluation = evaluation\n  }\n}\n\n/**\n * Another Execution is already in flight on this case and its claim has not\n * expired. Executions are serialized per case in v1 — cases advance at human\n * pace, so one Execution at a time costs no real throughput — which makes\n * this \"not now\", not \"never\": retry after\n * {@link CaseBusyError.expiresAt} at the latest.\n */\nexport class CaseBusyError extends AffordanceError {\n  readonly caseId: string\n  /** The in-flight Execution holding the case. */\n  readonly executionId: string\n  readonly stepName: string\n  readonly scopeKey: string | null\n  /** When the in-flight claim lapses if its handler stops heartbeating (ISO-8601 UTC). */\n  readonly expiresAt: string\n\n  constructor(\n    caseId: string,\n    holder: {\n      executionId: string\n      stepName: string\n      scopeKey: string | null\n      expiresAt: string\n    },\n  ) {\n    super(\n      'case-busy',\n      `case ${caseId} is busy: execution ${holder.executionId} is running step ${stepLabel(\n        holder.stepName,\n        holder.scopeKey,\n      )}, claim expires ${holder.expiresAt}`,\n    )\n    this.name = 'CaseBusyError'\n    this.caseId = caseId\n    this.executionId = holder.executionId\n    this.stepName = holder.stepName\n    this.scopeKey = holder.scopeKey\n    this.expiresAt = holder.expiresAt\n  }\n}\n\n/**\n * The claim was gone (or belonged to someone else) when this Execution tried\n * to commit: its lease expired mid-handler and another claimant took the case\n * over. The handler's effects on the outside world already happened — they are\n * at-least-once by contract and deduplicated on `executionId` — but\n * its Case State write is refused, because the state it computed from is stale.\n */\nexport class ClaimLostError extends AffordanceError {\n  readonly caseId: string\n  readonly executionId: string\n  /** The Execution now holding the case, if any. */\n  readonly heldBy: string | null\n\n  constructor(caseId: string, executionId: string, heldBy: string | null) {\n    super(\n      // The case moved on under this Execution: somebody else holds it now,\n      // and the state this Execution computed from is stale. That is the\n      // same \"not now\" answer a busy case gives, so it reuses 'case-busy' —\n      // a code an adapter already knows how to render.\n      'case-busy',\n      `execution ${executionId} lost its claim on case ${caseId}${\n        heldBy === null\n          ? ' (claim expired and was released)'\n          : ` (now held by ${heldBy})`\n      } — its state write was refused`,\n    )\n    this.name = 'ClaimLostError'\n    this.caseId = caseId\n    this.executionId = executionId\n    this.heldBy = heldBy\n  }\n}\n\n/**\n * The Execution ran and failed: the handler threw on every allowed attempt,\n * or it returned a Case State the case type's schema rejects (a deterministic\n * defect, failed without retry). A `failed` journal entry records it and the\n * case is released.\n */\nexport class StepExecutionError extends AffordanceError {\n  readonly caseId: string\n  readonly executionId: string\n  readonly stepName: string\n  readonly scopeKey: string | null\n  /** How many attempts ran before the Execution was given up on. */\n  readonly attempts: number\n\n  constructor(\n    caseId: string,\n    executionId: string,\n    stepName: string,\n    scopeKey: string | null,\n    attempts: number,\n    cause: unknown,\n  ) {\n    const reason = thrownMessage(cause)\n    super(\n      'execution-failed',\n      `step ${stepLabel(stepName, scopeKey)} failed on case ${caseId} after ${attempts} attempt${\n        attempts === 1 ? '' : 's'\n      }: ${reason}`,\n      { cause },\n    )\n    this.name = 'StepExecutionError'\n    this.caseId = caseId\n    this.executionId = executionId\n    this.stepName = stepName\n    this.scopeKey = scopeKey\n    this.attempts = attempts\n  }\n}\n"]}

package/dist/execution/execute.d.ts

@@ -0,0 +1,179 @@
+/**
+ * The execution lifecycle: **claim → run → commit**.
+ *
+ * ```
+ *   ┌── transaction ──────────────┐                    ┌── transaction ──────────────┐
+ *   │ lock the case row           │                    │ lock the case row           │
+ *   │ take over an expired claim  │   handler runs     │ verify the claim is ours    │
+ *   │ re-evaluate the guard  ←────┼── here, outside ───┼→ write state, bump seq      │
+ *   │ insert the claim (lease)    │   any transaction  │ run ctx.onCommit writes     │
+ *   │ journal `claimed`           │   (heartbeating)   │ journal `completed`         │
+ *   └─────────────────────────────┘                    └─────────────────────────────┘
+ * ```
+ *
+ * Three things this shape buys, each load-bearing:
+ *
+ * 1. **Guards advise, handlers enforce.** The affordance a client rendered is
+ *    advice; the claim's transactional re-evaluation is the enforcement
+ *    moment. State may have moved (another Execution committed) or the
+ *    definitions may have (a deploy — definition drift is the
+ *    same race, handled the same way). A claim that fails rejects with the
+ *    *current* unmet conditions and writes nothing at all.
+ * 2. **No transaction spans a handler.** Handlers call the outside world;
+ *    a transaction held across an escrow API call would tie up a pooled
+ *    connection and the case row's lock for as long as the external service
+ *    takes to answer. The lease (a `claims` row keyed by case id) carries
+ *    the exclusivity instead, and a heartbeat keeps it alive.
+ * 3. **A crashed handler cannot deadlock a case.** The lease expires. The
+ *    next claimant takes the case over, journaling the abandonment; if the
+ *    zombie ever comes back to commit, it is refused ({@link ClaimLostError})
+ *    — at-least-once effects are the handler's problem to deduplicate on
+ *    `ctx.executionId`, but a stale state write is the framework's to refuse.
+ */
+import type { GuardEvaluation, Instant } from '../guards/index.js';
+import type { AnyCaseType, RetryOptions } from '../model/index.js';
+import type { DatabaseAccess, Dormancy } from '../store/index.js';
+import type { StateDelta } from './delta.js';
+import type { LifecyclePort } from './port.js';
+import type { Timers } from './timers.js';
+/** How long a claim survives without a heartbeat, and how often the heartbeat beats. */
+export declare const DEFAULT_CLAIM_TTL_MS = 30000;
+export declare const DEFAULT_HEARTBEAT_MS = 5000;
+/** What {@link executeStep} needs from its caller (the engine supplies all of it). */
+export interface ExecutionEnvironment {
+    readonly db: DatabaseAccess;
+    /** Resolve a persisted `case_type` name to its registered definition; throws if unknown. */
+    readonly caseTypeFor: (caseTypeName: string) => AnyCaseType;
+    readonly claimTtlMs: number;
+    readonly heartbeatMs: number;
+    /**
+     * The clock. Conditions never read it; every process-side "as of now"
+     * comes through here, so a test can hand the lifecycle a deterministic
+     * instant instead of building fixtures around far-future dates. (Lease
+     * expiry is judged by the storage adapter's own clock — see
+     * {@link LifecyclePort}.)
+     */
+    readonly now: () => Date;
+    /** The process timers — retry delays and the heartbeat. See {@link Timers}. */
+    readonly timers: Timers;
+}
+/** Options for one execute call. */
+export interface ExecuteOptions<TActor = unknown> {
+    /** The Actor executing the step; `permits` conditions are evaluated against it. */
+    readonly actor: TActor;
+    /** Required for a scoped step, forbidden otherwise — the element's scope key. */
+    readonly scopeKey?: string;
+    /** The step's input, validated against its declared input schema before the handler runs. */
+    readonly input?: unknown;
+    /** The instant to re-evaluate the guard as of; defaults to now. */
+    readonly asOf?: Instant;
+    /** Override the claim lease for this Execution (long-running handler). */
+    readonly claimTtlMs?: number;
+    /** Override the heartbeat interval for this Execution. */
+    readonly heartbeatMs?: number;
+    /** Override the step's declared retry policy for this Execution. */
+    readonly retry?: RetryOptions;
+}
+/** A committed Execution — what `execute` resolves to. */
+export interface ExecutionResult<TState = unknown> {
+    readonly executionId: string;
+    readonly caseId: string;
+    readonly caseTypeName: string;
+    readonly step: string;
+    /** Present iff the step is scoped. */
+    readonly scopeKey?: string;
+    /** How many attempts ran, including the one that succeeded. */
+    readonly attempts: number;
+    /** The claim-time guard evaluation — the enforcement moment, as journaled. */
+    readonly guard: GuardEvaluation;
+    /** The committed Case State. */
+    readonly state: TState;
+    /** What changed, as JSON Patch. */
+    readonly delta: StateDelta;
+    /** The case's sequence counter after this Execution. */
+    readonly seq: number;
+    /** `end()` / `reopen()` called by the handler, if either was. */
+    readonly dormancy: Dormancy | null;
+    /** The case's dormancy marker after this Execution (ISO-8601 UTC), `null` while active. */
+    readonly endedAt: string | null;
+    readonly claimedAt: string;
+    readonly committedAt: string;
+}
+/**
+ * What the lifecycle core needs besides storage: the clock, the timers, and
+ * the lease timings. Definition resolution is the port's own (its `loadCase`
+ * returns the case resolved whole), so it is no part of this interface.
+ */
+export interface LifecycleDeps {
+    readonly now: () => Date;
+    readonly timers: Timers;
+    readonly claimTtlMs: number;
+    readonly heartbeatMs: number;
+}
+/**
+ * The lifecycle core: claim → run → commit against a {@link LifecyclePort}.
+ *
+ * {@link executeStep} binds this to the pg port; the claim state machine's
+ * own tests bind it to an in-memory port instead. Same body either way — the
+ * port is the only storage the lifecycle knows.
+ */
+export declare const runLifecycle: (port: LifecyclePort, deps: LifecycleDeps, caseId: string, stepName: string, options: ExecuteOptions) => Promise<ExecutionResult>;
+/**
+ * Execute one step on one case: claim it, run its handler, commit the result.
+ *
+ * Rejections before anything runs — {@link StepNotAvailableError} (the guard
+ * said no), {@link CaseBusyError} (another Execution holds the case),
+ * `UnknownStepError` / `ScopeKeyError` (bad address) — write nothing, not
+ * even a journal entry: the journal records Executions, and a refused claim
+ * never became one.
+ *
+ * A handler that throws is retried per the step's retry policy (same
+ * `executionId`, same claim, same starting state — nothing else can have
+ * moved it), each failure journaled as `attempt-failed`. When the attempts
+ * run out, a `failed` entry is journaled, the case is released, and
+ * {@link StepExecutionError} is thrown.
+ *
+ * This is {@link runLifecycle} bound to the pg port.
+ */
+export declare const executeStep: (env: ExecutionEnvironment, caseId: string, stepName: string, options: ExecuteOptions) => Promise<ExecutionResult>;
+/** A committed system run. */
+export interface SystemCommit {
+    readonly outcome: 'committed';
+    readonly result: ExecutionResult;
+}
+/**
+ * A system run that did not commit, carrying whatever the lifecycle threw —
+ * a Refusal keeps its identity (its code is the answer, projectable by
+ * `isAffordanceError`, never re-derived from a class), a bug or an
+ * infrastructure failure passes through as itself. One settled variant, not
+ * a refused/failed pair: no sweep ever treated the halves differently, and a
+ * discriminant nobody branches on is interface without behaviour.
+ */
+export interface SystemSettled {
+    readonly outcome: 'settled';
+    readonly error: Error;
+}
+/** How a step the system ran ended — total over every way the lifecycle can answer. */
+export type SystemRunOutcome = SystemCommit | SystemSettled;
+/** What a sweep may ask for beyond the lifecycle's own execute options. */
+export interface SystemRunOptions extends ExecuteOptions {
+    /**
+     * Run against this definition instead of the registry's — how a migration
+     * executes its synthetic `migrate:<name>` step. First-class here so no
+     * sweep has to smuggle a definition in by rewriting `caseTypeFor`.
+     */
+    readonly definition?: AnyCaseType;
+}
+/**
+ * Turn a throw into the settled value. No classification happens here —
+ * "is this a Refusal" is asked exactly once, where a consumer needs the
+ * distinction (ingestion's `classifyDeadLetter`), via `isAffordanceError`.
+ */
+export declare const settleSystemRun: (error: unknown) => SystemSettled;
+/**
+ * Run one step on behalf of the system and say how it ended. Never throws:
+ * a sweep ranges over many cases with no caller waiting on any single one,
+ * so the answer is a value — committed (with the result) or settled (with
+ * the error) — and each sweep decides what its kind of sweep does with it.
+ */
+export declare const runAsSystem: (env: ExecutionEnvironment, caseId: string, stepName: string, options: SystemRunOptions) => Promise<SystemRunOutcome>;