@affordance/core 0.1.0

package/dist/execution/journal.d.ts

@@ -0,0 +1,190 @@
+/**
+ * The journal: the immutable, append-only record of a case's Executions
+ * (CONTEXT.md).
+ *
+ * Historical questions are answered from what the system actually believed at
+ * the time, never by re-deriving the past through present-day code — so a
+ * `claimed` entry stores the guard evaluation *and* the Case State it was
+ * evaluated against, and every entry repeats the Execution's identity (step,
+ * scope key, actor). Per-track audit — "everything that happened on buyer
+ * #7" — is therefore a filter, not a reconstruction.
+ *
+ * Only inserts exist in this module. There is no update or delete path for a
+ * journal row anywhere in the library.
+ */
+import type { JournalEntryKind } from '@affordance/contract';
+import type { GuardEvaluation } from '../guards/index.js';
+import type { Queryable } from '../store/index.js';
+import type { StateDelta } from './delta.js';
+/**
+ * Which lifecycle moment an entry records.
+ *
+ * - `claimed` — the claim's transactional guard re-evaluation passed and the
+ *   Execution took the case; carries `guard`, `asOf` and `state`
+ * - `attempt-failed` — one attempt threw and another will follow
+ * - `completed` — the handler's Case State was committed; carries `delta`
+ * - `failed` — retries exhausted (or a deterministic defect); case released
+ * - `expired` — the claim lapsed without a terminal entry: the handler's
+ *   process died, and a later claimant recorded the abandonment
+ */
+export type JournalEntryType = JournalEntryKind;
+/** A failure as journaled — the error's identity, not a live Error object. */
+export interface JournalError {
+    readonly name: string;
+    readonly message: string;
+}
+/** One journal entry, JSON-serializable throughout (timestamps are ISO-8601 UTC). */
+export interface JournalEntry {
+    /** Total insertion order across all cases; per-case order is `(caseId, ordinal)`. */
+    readonly ordinal: number;
+    readonly id: string;
+    readonly caseId: string;
+    /** The Execution this entry belongs to — several entries share one. */
+    readonly executionId: string;
+    readonly entry: JournalEntryType;
+    /** 1-based attempt this entry is about. */
+    readonly attempt: number;
+    readonly step: string;
+    /** The bound scope key, or `null` for an unscoped step. */
+    readonly scopeKey: string | null;
+    /** The acting Actor, as supplied by the app. */
+    readonly actor: unknown;
+    /** The step input, post-validation (schema output), or `null`. */
+    readonly input: unknown;
+    /** The instant the claim's guard re-evaluation was made as of, on `claimed` entries. */
+    readonly asOf: string | null;
+    /** The claim-time guard evaluation — the enforcement moment's full record. */
+    readonly guard: GuardEvaluation | null;
+    /** The Case State the guard was evaluated against, on `claimed` entries. */
+    readonly state: unknown;
+    /** The committed state delta, on `completed` entries. */
+    readonly delta: StateDelta | null;
+    /** `end()` / `reopen()` called by the handler, on `completed` entries. */
+    readonly dormancy: 'ended' | 'reopened' | null;
+    /** The failure, on `attempt-failed` / `failed` / `expired` entries. */
+    readonly error: JournalError | null;
+    readonly recordedAt: string;
+}
+/** The identity every journal entry carries, whatever its kind. */
+interface JournalEntryIdentity {
+    readonly caseId: string;
+    readonly executionId: string;
+    readonly attempt: number;
+    readonly step: string;
+    readonly scopeKey?: string | null;
+    readonly actor?: unknown;
+    readonly input?: unknown;
+}
+/**
+ * A `claimed` entry records the enforcement moment, so the evidence is
+ * required: the instant, the guard evaluation, and the Case State it ran
+ * against.
+ */
+export interface ClaimedEntryInput extends JournalEntryIdentity {
+    readonly entry: 'claimed';
+    readonly asOf: string;
+    readonly guard: GuardEvaluation;
+    readonly state: unknown;
+}
+/** A `completed` entry records what the commit changed. */
+export interface CompletedEntryInput extends JournalEntryIdentity {
+    readonly entry: 'completed';
+    readonly delta: StateDelta;
+    readonly dormancy?: 'ended' | 'reopened' | null;
+}
+/** Every way an Execution stops without committing carries the failure that stopped it. */
+export interface FailureEntryInput extends JournalEntryIdentity {
+    readonly entry: 'attempt-failed' | 'failed' | 'expired';
+    readonly error: JournalError;
+}
+/**
+ * What {@link appendEntry} needs — a discriminated union on `entry`, so
+ * which fields accompany which lifecycle moment is stated by the type
+ * itself rather than re-derived from prose by every reader.
+ * `{ entry: 'failed', guard, delta }` is unrepresentable rather than
+ * quietly journaled.
+ */
+export type JournalEntryInput = ClaimedEntryInput | CompletedEntryInput | FailureEntryInput;
+/**
+ * A `claimed` entry as read back, with the enforcement-moment evidence
+ * present — what {@link appendEntry}'s input union guarantees was written.
+ */
+export type ClaimedJournalEntry = JournalEntry & {
+    readonly entry: 'claimed';
+    readonly asOf: string;
+    readonly guard: GuardEvaluation;
+};
+/**
+ * Narrow a read entry to the claimed moment. The one predicate every reader
+ * of claim-time evidence (`foldExecutions`, audit replay) shares, so what
+ * counts as "carries the evidence" is decided once.
+ */
+export declare const isClaimedEntry: (entry: JournalEntry) => entry is ClaimedJournalEntry;
+/** Filters for {@link readJournal}; all optional, all AND-ed. */
+export interface JournalFilter {
+    /** Per-track audit: only entries bound to this scope key. */
+    readonly scopeKey?: string;
+    /** Only entries for this step. */
+    readonly step?: string;
+    /** Only entries belonging to this Execution. */
+    readonly executionId?: string;
+    /** Only these entry types. */
+    readonly entry?: JournalEntryType | readonly JournalEntryType[];
+    /** Only entries after this ordinal (exclusive) — cursor paging. */
+    readonly since?: number;
+    /** Cap the number of entries returned; the oldest matching entries win. */
+    readonly limit?: number;
+}
+/** A stored entry minus what storage assigns: `ordinal`, `id`, `recordedAt`. */
+export type JournalEntryColumns = Omit<JournalEntry, 'ordinal' | 'id' | 'recordedAt'>;
+/**
+ * Project an input onto a stored entry's fields — the one statement of the
+ * defaulting and of which fields accompany which lifecycle moment. Every
+ * adapter persists exactly this and assigns the rest; an adapter that could
+ * disagree with another about what a `failed` entry looks like would be
+ * a second, divergent copy of the journal's semantics.
+ */
+export declare const projectEntry: (input: JournalEntryInput) => JournalEntryColumns;
+/** Append one entry. Inserts only — journal rows are never updated or deleted. */
+export declare const appendEntry: (db: Queryable, input: JournalEntryInput) => Promise<JournalEntry>;
+/**
+ * Read a case's journal in insertion order, oldest first. With no filter this
+ * is the whole story of the case; with `scopeKey` it is one track's audit.
+ */
+export declare const readJournal: (db: Queryable, caseId: string, filter?: JournalFilter) => Promise<readonly JournalEntry[]>;
+/** How an Execution ended up, folded from its entries. */
+export type ExecutionStatus = 'in-progress' | 'completed' | 'failed' | 'expired';
+/**
+ * One Execution as a single record: its identity, the claim-time evidence,
+ * and how it settled. This is a fold over entries of the *same* Execution —
+ * assembling one record from the moments that constitute it, not deriving
+ * state from a log (the design rejects the latter, not the former).
+ */
+export interface ExecutionRecord {
+    readonly executionId: string;
+    readonly caseId: string;
+    readonly step: string;
+    readonly scopeKey: string | null;
+    readonly actor: unknown;
+    readonly input: unknown;
+    readonly status: ExecutionStatus;
+    /** Attempts observed — the highest attempt number any of its entries carries. */
+    readonly attempts: number;
+    readonly asOf: string | null;
+    readonly guard: GuardEvaluation | null;
+    /** The Case State the claim's guard was evaluated against. */
+    readonly state: unknown;
+    readonly delta: StateDelta | null;
+    readonly dormancy: 'ended' | 'reopened' | null;
+    readonly error: JournalError | null;
+    readonly claimedAt: string | null;
+    /** When the Execution reached a terminal entry; `null` while in progress. */
+    readonly settledAt: string | null;
+}
+/**
+ * Fold journal entries into one record per Execution, in first-appearance
+ * order. Feed it a filtered read (by scope key, say) to get that track's
+ * Executions.
+ */
+export declare const foldExecutions: (entries: readonly JournalEntry[]) => readonly ExecutionRecord[];
+export {};

package/dist/execution/journal.js

@@ -0,0 +1,192 @@
+/**
+ * The journal: the immutable, append-only record of a case's Executions
+ * (CONTEXT.md).
+ *
+ * Historical questions are answered from what the system actually believed at
+ * the time, never by re-deriving the past through present-day code — so a
+ * `claimed` entry stores the guard evaluation *and* the Case State it was
+ * evaluated against, and every entry repeats the Execution's identity (step,
+ * scope key, actor). Per-track audit — "everything that happened on buyer
+ * #7" — is therefore a filter, not a reconstruction.
+ *
+ * Only inserts exist in this module. There is no update or delete path for a
+ * journal row anywhere in the library.
+ */
+import { FRAMEWORK_SCHEMA, mintId, sqlWhere } from '../store/index.js';
+const JOURNAL = `${FRAMEWORK_SCHEMA}.journal`;
+const JOURNAL_COLUMNS = 'ordinal, id, case_id, execution_id, entry, attempt, step, scope_key, actor, input, as_of, guard, state, delta, dormancy, error, recorded_at';
+/**
+ * Narrow a read entry to the claimed moment. The one predicate every reader
+ * of claim-time evidence (`foldExecutions`, audit replay) shares, so what
+ * counts as "carries the evidence" is decided once.
+ */
+export const isClaimedEntry = (entry) => entry.entry === 'claimed' && entry.guard !== null && entry.asOf !== null;
+const toEntry = (row) => ({
+    ordinal: Number(row.ordinal),
+    id: row.id,
+    caseId: row.case_id,
+    executionId: row.execution_id,
+    entry: row.entry,
+    attempt: row.attempt,
+    step: row.step,
+    scopeKey: row.scope_key,
+    actor: row.actor,
+    input: row.input,
+    asOf: row.as_of === null ? null : row.as_of.toISOString(),
+    guard: row.guard,
+    state: row.state,
+    delta: row.delta,
+    dormancy: row.dormancy,
+    error: row.error,
+    recordedAt: row.recorded_at.toISOString(),
+});
+/**
+ * Serialize a value for a jsonb column. Actors and inputs are app-owned
+ * shapes, and a journal append must never be the thing that fails an
+ * otherwise-good Execution: a value that will not stringify (a cycle, a
+ * BigInt) is journaled as a marker string rather than thrown over.
+ */
+const toJsonb = (value) => {
+    if (value === undefined || value === null)
+        return null;
+    try {
+        const json = JSON.stringify(value);
+        return json === undefined ? null : json;
+    }
+    catch {
+        return JSON.stringify({ '~unserializable': String(value) });
+    }
+};
+/**
+ * Project an input onto a stored entry's fields — the one statement of the
+ * defaulting and of which fields accompany which lifecycle moment. Every
+ * adapter persists exactly this and assigns the rest; an adapter that could
+ * disagree with another about what a `failed` entry looks like would be
+ * a second, divergent copy of the journal's semantics.
+ */
+export const projectEntry = (input) => {
+    const claimed = input.entry === 'claimed' ? input : null;
+    const completed = input.entry === 'completed' ? input : null;
+    const failure = input.entry !== 'claimed' && input.entry !== 'completed' ? input : null;
+    return {
+        caseId: input.caseId,
+        executionId: input.executionId,
+        entry: input.entry,
+        attempt: input.attempt,
+        step: input.step,
+        scopeKey: input.scopeKey ?? null,
+        actor: input.actor ?? null,
+        input: input.input ?? null,
+        asOf: claimed?.asOf ?? null,
+        guard: claimed?.guard ?? null,
+        state: claimed?.state ?? null,
+        delta: completed?.delta ?? null,
+        dormancy: completed?.dormancy ?? null,
+        error: failure?.error ?? null,
+    };
+};
+/** Append one entry. Inserts only — journal rows are never updated or deleted. */
+export const appendEntry = async (db, input) => {
+    const entry = projectEntry(input);
+    const { rows } = await db.query(`insert into ${JOURNAL}
+       (id, case_id, execution_id, entry, attempt, step, scope_key, actor, input, as_of, guard, state, delta, dormancy, error)
+     values ($1, $2, $3, $4, $5, $6, $7, $8::jsonb, $9::jsonb, $10::timestamptz, $11::jsonb, $12::jsonb, $13::jsonb, $14, $15::jsonb)
+     returning ${JOURNAL_COLUMNS}`, [
+        mintId('journal'),
+        entry.caseId,
+        entry.executionId,
+        entry.entry,
+        entry.attempt,
+        entry.step,
+        entry.scopeKey,
+        toJsonb(entry.actor),
+        toJsonb(entry.input),
+        entry.asOf,
+        toJsonb(entry.guard),
+        toJsonb(entry.state),
+        toJsonb(entry.delta),
+        entry.dormancy,
+        toJsonb(entry.error),
+    ]);
+    const row = rows[0];
+    if (!row)
+        throw new Error(`insert into ${JOURNAL} returned no row`);
+    return toEntry(row);
+};
+/**
+ * Read a case's journal in insertion order, oldest first. With no filter this
+ * is the whole story of the case; with `scopeKey` it is one track's audit.
+ */
+export const readJournal = async (db, caseId, filter = {}) => {
+    const { conditions, values, bind, where } = sqlWhere(['case_id = $1'], [caseId]);
+    if (filter.scopeKey !== undefined)
+        conditions.push(`scope_key = ${bind(filter.scopeKey)}`);
+    if (filter.step !== undefined)
+        conditions.push(`step = ${bind(filter.step)}`);
+    if (filter.executionId !== undefined)
+        conditions.push(`execution_id = ${bind(filter.executionId)}`);
+    if (filter.entry !== undefined) {
+        const entries = Array.isArray(filter.entry) ? filter.entry : [filter.entry];
+        conditions.push(`entry = any(${bind(entries)}::text[])`);
+    }
+    if (filter.since !== undefined)
+        conditions.push(`ordinal > ${bind(filter.since)}`);
+    const limit = filter.limit === undefined ? '' : ` limit ${bind(filter.limit)}`;
+    const { rows } = await db.query(`select ${JOURNAL_COLUMNS} from ${JOURNAL}
+     where ${where()}
+     order by ordinal asc${limit}`, values);
+    return rows.map(toEntry);
+};
+const TERMINAL = {
+    completed: 'completed',
+    failed: 'failed',
+    expired: 'expired',
+};
+/**
+ * Fold journal entries into one record per Execution, in first-appearance
+ * order. Feed it a filtered read (by scope key, say) to get that track's
+ * Executions.
+ */
+export const foldExecutions = (entries) => {
+    const byExecution = new Map();
+    for (const entry of entries) {
+        const previous = byExecution.get(entry.executionId);
+        const terminal = TERMINAL[entry.entry];
+        const claimed = isClaimedEntry(entry) ? entry : null;
+        const base = previous ?? {
+            executionId: entry.executionId,
+            caseId: entry.caseId,
+            step: entry.step,
+            scopeKey: entry.scopeKey,
+            actor: entry.actor,
+            input: entry.input,
+            status: 'in-progress',
+            attempts: entry.attempt,
+            asOf: null,
+            guard: null,
+            state: undefined,
+            delta: null,
+            dormancy: null,
+            error: null,
+            claimedAt: null,
+            settledAt: null,
+        };
+        byExecution.set(entry.executionId, {
+            ...base,
+            attempts: Math.max(base.attempts, entry.attempt),
+            status: terminal ?? base.status,
+            asOf: claimed !== null ? claimed.asOf : base.asOf,
+            guard: claimed !== null ? claimed.guard : base.guard,
+            state: claimed !== null ? claimed.state : base.state,
+            delta: entry.delta ?? base.delta,
+            dormancy: entry.dormancy ?? base.dormancy,
+            // The terminal error is the one that matters; an attempt-failed error
+            // only stands while nothing has superseded it.
+            error: entry.error ?? base.error,
+            claimedAt: claimed !== null ? claimed.recordedAt : base.claimedAt,
+            settledAt: terminal === undefined ? base.settledAt : entry.recordedAt,
+        });
+    }
+    return [...byExecution.values()];
+};
+//# sourceMappingURL=journal.js.map

package/dist/execution/journal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"journal.js","sourceRoot":"","sources":["../../src/execution/journal.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The journal: the immutable, append-only record of a case's Executions\n * (CONTEXT.md).\n *\n * Historical questions are answered from what the system actually believed at\n * the time, never by re-deriving the past through present-day code — so a\n * `claimed` entry stores the guard evaluation *and* the Case State it was\n * evaluated against, and every entry repeats the Execution's identity (step,\n * scope key, actor). Per-track audit — \"everything that happened on buyer\n * #7\" — is therefore a filter, not a reconstruction.\n *\n * Only inserts exist in this module. There is no update or delete path for a\n * journal row anywhere in the library.\n */\n\nimport type { JournalEntryKind } from '@affordance/contract'\nimport type { GuardEvaluation } from '../guards/index.js'\nimport type { Queryable } from '../store/index.js'\nimport { FRAMEWORK_SCHEMA, mintId, sqlWhere } from '../store/index.js'\nimport type { StateDelta } from './delta.js'\n\nconst JOURNAL = `${FRAMEWORK_SCHEMA}.journal`\nconst JOURNAL_COLUMNS =\n  'ordinal, id, case_id, execution_id, entry, attempt, step, scope_key, actor, input, as_of, guard, state, delta, dormancy, error, recorded_at'\n\n/**\n * Which lifecycle moment an entry records.\n *\n * - `claimed` — the claim's transactional guard re-evaluation passed and the\n *   Execution took the case; carries `guard`, `asOf` and `state`\n * - `attempt-failed` — one attempt threw and another will follow\n * - `completed` — the handler's Case State was committed; carries `delta`\n * - `failed` — retries exhausted (or a deterministic defect); case released\n * - `expired` — the claim lapsed without a terminal entry: the handler's\n *   process died, and a later claimant recorded the abandonment\n */\nexport type JournalEntryType = JournalEntryKind\n\n/** A failure as journaled — the error's identity, not a live Error object. */\nexport interface JournalError {\n  readonly name: string\n  readonly message: string\n}\n\n/** One journal entry, JSON-serializable throughout (timestamps are ISO-8601 UTC). */\nexport interface JournalEntry {\n  /** Total insertion order across all cases; per-case order is `(caseId, ordinal)`. */\n  readonly ordinal: number\n  readonly id: string\n  readonly caseId: string\n  /** The Execution this entry belongs to — several entries share one. */\n  readonly executionId: string\n  readonly entry: JournalEntryType\n  /** 1-based attempt this entry is about. */\n  readonly attempt: number\n  readonly step: string\n  /** The bound scope key, or `null` for an unscoped step. */\n  readonly scopeKey: string | null\n  /** The acting Actor, as supplied by the app. */\n  readonly actor: unknown\n  /** The step input, post-validation (schema output), or `null`. */\n  readonly input: unknown\n  /** The instant the claim's guard re-evaluation was made as of, on `claimed` entries. */\n  readonly asOf: string | null\n  /** The claim-time guard evaluation — the enforcement moment's full record. */\n  readonly guard: GuardEvaluation | null\n  /** The Case State the guard was evaluated against, on `claimed` entries. */\n  readonly state: unknown\n  /** The committed state delta, on `completed` entries. */\n  readonly delta: StateDelta | null\n  /** `end()` / `reopen()` called by the handler, on `completed` entries. */\n  readonly dormancy: 'ended' | 'reopened' | null\n  /** The failure, on `attempt-failed` / `failed` / `expired` entries. */\n  readonly error: JournalError | null\n  readonly recordedAt: string\n}\n\n/** The identity every journal entry carries, whatever its kind. */\ninterface JournalEntryIdentity {\n  readonly caseId: string\n  readonly executionId: string\n  readonly attempt: number\n  readonly step: string\n  readonly scopeKey?: string | null\n  readonly actor?: unknown\n  readonly input?: unknown\n}\n\n/**\n * A `claimed` entry records the enforcement moment, so the evidence is\n * required: the instant, the guard evaluation, and the Case State it ran\n * against.\n */\nexport interface ClaimedEntryInput extends JournalEntryIdentity {\n  readonly entry: 'claimed'\n  readonly asOf: string\n  readonly guard: GuardEvaluation\n  readonly state: unknown\n}\n\n/** A `completed` entry records what the commit changed. */\nexport interface CompletedEntryInput extends JournalEntryIdentity {\n  readonly entry: 'completed'\n  readonly delta: StateDelta\n  readonly dormancy?: 'ended' | 'reopened' | null\n}\n\n/** Every way an Execution stops without committing carries the failure that stopped it. */\nexport interface FailureEntryInput extends JournalEntryIdentity {\n  readonly entry: 'attempt-failed' | 'failed' | 'expired'\n  readonly error: JournalError\n}\n\n/**\n * What {@link appendEntry} needs — a discriminated union on `entry`, so\n * which fields accompany which lifecycle moment is stated by the type\n * itself rather than re-derived from prose by every reader.\n * `{ entry: 'failed', guard, delta }` is unrepresentable rather than\n * quietly journaled.\n */\nexport type JournalEntryInput =\n  | ClaimedEntryInput\n  | CompletedEntryInput\n  | FailureEntryInput\n\n/**\n * A `claimed` entry as read back, with the enforcement-moment evidence\n * present — what {@link appendEntry}'s input union guarantees was written.\n */\nexport type ClaimedJournalEntry = JournalEntry & {\n  readonly entry: 'claimed'\n  readonly asOf: string\n  readonly guard: GuardEvaluation\n}\n\n/**\n * Narrow a read entry to the claimed moment. The one predicate every reader\n * of claim-time evidence (`foldExecutions`, audit replay) shares, so what\n * counts as \"carries the evidence\" is decided once.\n */\nexport const isClaimedEntry = (\n  entry: JournalEntry,\n): entry is ClaimedJournalEntry =>\n  entry.entry === 'claimed' && entry.guard !== null && entry.asOf !== null\n\n/** Filters for {@link readJournal}; all optional, all AND-ed. */\nexport interface JournalFilter {\n  /** Per-track audit: only entries bound to this scope key. */\n  readonly scopeKey?: string\n  /** Only entries for this step. */\n  readonly step?: string\n  /** Only entries belonging to this Execution. */\n  readonly executionId?: string\n  /** Only these entry types. */\n  readonly entry?: JournalEntryType | readonly JournalEntryType[]\n  /** Only entries after this ordinal (exclusive) — cursor paging. */\n  readonly since?: number\n  /** Cap the number of entries returned; the oldest matching entries win. */\n  readonly limit?: number\n}\n\ntype JournalRow = {\n  ordinal: string | number\n  id: string\n  case_id: string\n  execution_id: string\n  entry: string\n  attempt: number\n  step: string\n  scope_key: string | null\n  actor: unknown\n  input: unknown\n  as_of: Date | null\n  guard: GuardEvaluation | null\n  state: unknown\n  delta: StateDelta | null\n  dormancy: string | null\n  error: JournalError | null\n  recorded_at: Date\n}\n\nconst toEntry = (row: JournalRow): JournalEntry => ({\n  ordinal: Number(row.ordinal),\n  id: row.id,\n  caseId: row.case_id,\n  executionId: row.execution_id,\n  entry: row.entry as JournalEntryType,\n  attempt: row.attempt,\n  step: row.step,\n  scopeKey: row.scope_key,\n  actor: row.actor,\n  input: row.input,\n  asOf: row.as_of === null ? null : row.as_of.toISOString(),\n  guard: row.guard,\n  state: row.state,\n  delta: row.delta,\n  dormancy: row.dormancy as 'ended' | 'reopened' | null,\n  error: row.error,\n  recordedAt: row.recorded_at.toISOString(),\n})\n\n/**\n * Serialize a value for a jsonb column. Actors and inputs are app-owned\n * shapes, and a journal append must never be the thing that fails an\n * otherwise-good Execution: a value that will not stringify (a cycle, a\n * BigInt) is journaled as a marker string rather than thrown over.\n */\nconst toJsonb = (value: unknown): string | null => {\n  if (value === undefined || value === null) return null\n  try {\n    const json = JSON.stringify(value)\n    return json === undefined ? null : json\n  } catch {\n    return JSON.stringify({ '~unserializable': String(value) })\n  }\n}\n\n/** A stored entry minus what storage assigns: `ordinal`, `id`, `recordedAt`. */\nexport type JournalEntryColumns = Omit<\n  JournalEntry,\n  'ordinal' | 'id' | 'recordedAt'\n>\n\n/**\n * Project an input onto a stored entry's fields — the one statement of the\n * defaulting and of which fields accompany which lifecycle moment. Every\n * adapter persists exactly this and assigns the rest; an adapter that could\n * disagree with another about what a `failed` entry looks like would be\n * a second, divergent copy of the journal's semantics.\n */\nexport const projectEntry = (input: JournalEntryInput): JournalEntryColumns => {\n  const claimed = input.entry === 'claimed' ? input : null\n  const completed = input.entry === 'completed' ? input : null\n  const failure =\n    input.entry !== 'claimed' && input.entry !== 'completed' ? input : null\n  return {\n    caseId: input.caseId,\n    executionId: input.executionId,\n    entry: input.entry,\n    attempt: input.attempt,\n    step: input.step,\n    scopeKey: input.scopeKey ?? null,\n    actor: input.actor ?? null,\n    input: input.input ?? null,\n    asOf: claimed?.asOf ?? null,\n    guard: claimed?.guard ?? null,\n    state: claimed?.state ?? null,\n    delta: completed?.delta ?? null,\n    dormancy: completed?.dormancy ?? null,\n    error: failure?.error ?? null,\n  }\n}\n\n/** Append one entry. Inserts only — journal rows are never updated or deleted. */\nexport const appendEntry = async (\n  db: Queryable,\n  input: JournalEntryInput,\n): Promise<JournalEntry> => {\n  const entry = projectEntry(input)\n  const { rows } = await db.query<JournalRow>(\n    `insert into ${JOURNAL}\n       (id, case_id, execution_id, entry, attempt, step, scope_key, actor, input, as_of, guard, state, delta, dormancy, error)\n     values ($1, $2, $3, $4, $5, $6, $7, $8::jsonb, $9::jsonb, $10::timestamptz, $11::jsonb, $12::jsonb, $13::jsonb, $14, $15::jsonb)\n     returning ${JOURNAL_COLUMNS}`,\n    [\n      mintId('journal'),\n      entry.caseId,\n      entry.executionId,\n      entry.entry,\n      entry.attempt,\n      entry.step,\n      entry.scopeKey,\n      toJsonb(entry.actor),\n      toJsonb(entry.input),\n      entry.asOf,\n      toJsonb(entry.guard),\n      toJsonb(entry.state),\n      toJsonb(entry.delta),\n      entry.dormancy,\n      toJsonb(entry.error),\n    ],\n  )\n  const row = rows[0]\n  if (!row) throw new Error(`insert into ${JOURNAL} returned no row`)\n  return toEntry(row)\n}\n\n/**\n * Read a case's journal in insertion order, oldest first. With no filter this\n * is the whole story of the case; with `scopeKey` it is one track's audit.\n */\nexport const readJournal = async (\n  db: Queryable,\n  caseId: string,\n  filter: JournalFilter = {},\n): Promise<readonly JournalEntry[]> => {\n  const { conditions, values, bind, where } = sqlWhere(\n    ['case_id = $1'],\n    [caseId],\n  )\n\n  if (filter.scopeKey !== undefined)\n    conditions.push(`scope_key = ${bind(filter.scopeKey)}`)\n  if (filter.step !== undefined) conditions.push(`step = ${bind(filter.step)}`)\n  if (filter.executionId !== undefined)\n    conditions.push(`execution_id = ${bind(filter.executionId)}`)\n  if (filter.entry !== undefined) {\n    const entries = Array.isArray(filter.entry) ? filter.entry : [filter.entry]\n    conditions.push(`entry = any(${bind(entries)}::text[])`)\n  }\n  if (filter.since !== undefined)\n    conditions.push(`ordinal > ${bind(filter.since)}`)\n\n  const limit = filter.limit === undefined ? '' : ` limit ${bind(filter.limit)}`\n  const { rows } = await db.query<JournalRow>(\n    `select ${JOURNAL_COLUMNS} from ${JOURNAL}\n     where ${where()}\n     order by ordinal asc${limit}`,\n    values,\n  )\n  return rows.map(toEntry)\n}\n\n/** How an Execution ended up, folded from its entries. */\nexport type ExecutionStatus = 'in-progress' | 'completed' | 'failed' | 'expired'\n\n/**\n * One Execution as a single record: its identity, the claim-time evidence,\n * and how it settled. This is a fold over entries of the *same* Execution —\n * assembling one record from the moments that constitute it, not deriving\n * state from a log (the design rejects the latter, not the former).\n */\nexport interface ExecutionRecord {\n  readonly executionId: string\n  readonly caseId: string\n  readonly step: string\n  readonly scopeKey: string | null\n  readonly actor: unknown\n  readonly input: unknown\n  readonly status: ExecutionStatus\n  /** Attempts observed — the highest attempt number any of its entries carries. */\n  readonly attempts: number\n  readonly asOf: string | null\n  readonly guard: GuardEvaluation | null\n  /** The Case State the claim's guard was evaluated against. */\n  readonly state: unknown\n  readonly delta: StateDelta | null\n  readonly dormancy: 'ended' | 'reopened' | null\n  readonly error: JournalError | null\n  readonly claimedAt: string | null\n  /** When the Execution reached a terminal entry; `null` while in progress. */\n  readonly settledAt: string | null\n}\n\nconst TERMINAL: Record<string, ExecutionStatus | undefined> = {\n  completed: 'completed',\n  failed: 'failed',\n  expired: 'expired',\n}\n\n/**\n * Fold journal entries into one record per Execution, in first-appearance\n * order. Feed it a filtered read (by scope key, say) to get that track's\n * Executions.\n */\nexport const foldExecutions = (\n  entries: readonly JournalEntry[],\n): readonly ExecutionRecord[] => {\n  const byExecution = new Map<string, ExecutionRecord>()\n  for (const entry of entries) {\n    const previous = byExecution.get(entry.executionId)\n    const terminal = TERMINAL[entry.entry]\n    const claimed = isClaimedEntry(entry) ? entry : null\n    const base: ExecutionRecord = previous ?? {\n      executionId: entry.executionId,\n      caseId: entry.caseId,\n      step: entry.step,\n      scopeKey: entry.scopeKey,\n      actor: entry.actor,\n      input: entry.input,\n      status: 'in-progress',\n      attempts: entry.attempt,\n      asOf: null,\n      guard: null,\n      state: undefined,\n      delta: null,\n      dormancy: null,\n      error: null,\n      claimedAt: null,\n      settledAt: null,\n    }\n    byExecution.set(entry.executionId, {\n      ...base,\n      attempts: Math.max(base.attempts, entry.attempt),\n      status: terminal ?? base.status,\n      asOf: claimed !== null ? claimed.asOf : base.asOf,\n      guard: claimed !== null ? claimed.guard : base.guard,\n      state: claimed !== null ? claimed.state : base.state,\n      delta: entry.delta ?? base.delta,\n      dormancy: entry.dormancy ?? base.dormancy,\n      // The terminal error is the one that matters; an attempt-failed error\n      // only stands while nothing has superseded it.\n      error: entry.error ?? base.error,\n      claimedAt: claimed !== null ? claimed.recordedAt : base.claimedAt,\n      settledAt: terminal === undefined ? base.settledAt : entry.recordedAt,\n    })\n  }\n  return [...byExecution.values()]\n}\n"]}

package/dist/execution/port.d.ts

@@ -0,0 +1,81 @@
+/**
+ * The lifecycle port: what claim → run → commit asks of storage, and nothing
+ * else.
+ *
+ * An **internal** seam, deliberately. `docs/architecture.md` stands:
+ * Postgres is a hard dependency and there is no public storage-adapter
+ * abstraction — an app never sees this interface. It exists because the
+ * claim state machine (busy vs. takeover, the holder check, retry
+ * classification, per-attempt write discard) upholds more always-true
+ * rules in one place than anything else in the package, and testing those
+ * rules means staging precise situations — an expired lease, a takeover
+ * mid-run — that should not require a running database. Two adapters make
+ * the seam real: the pg one below for production, and the in-memory one in
+ * `test/execution/memory-port.ts` for the tests.
+ *
+ * The shape keeps the lifecycle's transactional structure explicit:
+ * {@link LifecyclePort.withCaseLock} is "one short transaction holding the
+ * case row's lock" — the claim and the commit are each exactly one of those
+ * — and everything else deliberately runs outside any transaction, because
+ * a handler is running and the lease, not a lock, carries exclusivity.
+ */
+import type { CommitWrite } from '../model/index.js';
+import type { CaseTypeLookup, DatabaseAccess, Dormancy, ResolvedCase } from '../store/index.js';
+import type { JournalEntry, JournalEntryInput } from './journal.js';
+/** The claim sitting on a case, as the lifecycle needs to judge it. */
+export interface HeldClaim {
+    readonly executionId: string;
+    readonly step: string;
+    readonly scopeKey: string | null;
+    readonly attempt: number;
+    readonly expiresAt: string;
+    /** True when the lease has lapsed — the next claimant may take the case over. */
+    readonly expired: boolean;
+}
+/** What the lifecycle asks of storage inside one case-locked transaction. */
+export interface LifecycleTx {
+    /**
+     * The case, loaded under its lock and resolved whole — definition looked
+     * up, stored state validated against its schema — the serialization
+     * point. Returning the resolved triple rather than a raw row is what
+     * keeps "load, resolve, validate, in that order" spelled once (in
+     * `store/resolve.ts`) instead of re-derived by each adapter's caller.
+     */
+    readonly loadCase: () => Promise<ResolvedCase>;
+    /**
+     * Take the case row's lock without interpreting the row — the commit's
+     * serialization point. The commit already holds everything it computed at
+     * the claim; what it needs from the row is only the lock (and proof the
+     * row exists), never a second read-and-validate of the state document.
+     */
+    readonly lockCase: () => Promise<void>;
+    /** The claim on the case, `null` when nobody holds it. */
+    readonly currentClaim: () => Promise<HeldClaim | null>;
+    readonly insertClaim: (executionId: string, step: string, scopeKey: string | null, ttlMs: number) => Promise<{
+        readonly claimedAt: string;
+    }>;
+    readonly deleteClaim: (executionId: string) => Promise<void>;
+    readonly appendEntry: (input: JournalEntryInput) => Promise<JournalEntry>;
+    /** Write the next Case State, bump `seq`, apply the dormancy transition. */
+    readonly updateCaseState: (state: unknown, dormancy: Dormancy | null) => Promise<{
+        readonly seq: number;
+        readonly endedAt: string | null;
+    }>;
+    /** The app's own `ctx.onCommit` writes, riding the same transaction. */
+    readonly appWrites: (writes: readonly CommitWrite[]) => Promise<void>;
+}
+/** The verbs the execution lifecycle needs from storage. */
+export interface LifecyclePort {
+    /** One short transaction holding the case row's lock — a claim or a commit. */
+    readonly withCaseLock: <T>(caseId: string, fn: (tx: LifecycleTx) => Promise<T>) => Promise<T>;
+    /** Journal outside any transaction — `attempt-failed` / `failed` entries. */
+    readonly appendEntry: (input: JournalEntryInput) => Promise<JournalEntry>;
+    /** Refresh the lease. Best-effort: a failed beat just lets the claim age. */
+    readonly heartbeat: (caseId: string, executionId: string, ttlMs: number) => Promise<void>;
+    /** Keep the lease's attempt counter current across retries. Best-effort. */
+    readonly bumpAttempt: (caseId: string, executionId: string, attempt: number) => Promise<void>;
+    /** Delete this Execution's claim — scoped to `executionId`, so releasing a lease we no longer hold is a no-op. */
+    readonly releaseClaim: (caseId: string, executionId: string) => Promise<void>;
+}
+/** The production adapter: each port verb implemented as SQL over the claims, journal and cases tables. */
+export declare const pgLifecyclePort: (db: DatabaseAccess, caseTypeFor: CaseTypeLookup) => LifecyclePort;

package/dist/execution/port.js

@@ -0,0 +1,101 @@
+/**
+ * The lifecycle port: what claim → run → commit asks of storage, and nothing
+ * else.
+ *
+ * An **internal** seam, deliberately. `docs/architecture.md` stands:
+ * Postgres is a hard dependency and there is no public storage-adapter
+ * abstraction — an app never sees this interface. It exists because the
+ * claim state machine (busy vs. takeover, the holder check, retry
+ * classification, per-attempt write discard) upholds more always-true
+ * rules in one place than anything else in the package, and testing those
+ * rules means staging precise situations — an expired lease, a takeover
+ * mid-run — that should not require a running database. Two adapters make
+ * the seam real: the pg one below for production, and the in-memory one in
+ * `test/execution/memory-port.ts` for the tests.
+ *
+ * The shape keeps the lifecycle's transactional structure explicit:
+ * {@link LifecyclePort.withCaseLock} is "one short transaction holding the
+ * case row's lock" — the claim and the commit are each exactly one of those
+ * — and everything else deliberately runs outside any transaction, because
+ * a handler is running and the lease, not a lock, carries exclusivity.
+ */
+import { CaseNotFoundError, FRAMEWORK_SCHEMA, queryableOf, resolveCaseForUpdate, updateCaseState, } from '../store/index.js';
+import { appendEntry } from './journal.js';
+import { withTransaction } from './transaction.js';
+const CASES = `${FRAMEWORK_SCHEMA}.cases`;
+const CLAIMS = `${FRAMEWORK_SCHEMA}.claims`;
+/** `now() + <ms>` as a SQL expression against a bound millisecond parameter. */
+const expiryExpression = (parameter) => `now() + (${parameter}::double precision * interval '1 millisecond')`;
+/** The production adapter: each port verb implemented as SQL over the claims, journal and cases tables. */
+export const pgLifecyclePort = (db, caseTypeFor) => {
+    // The lease verbs are single self-contained statements; only the
+    // case-locked transactions care which arm of the access the caller brought.
+    const q = queryableOf(db);
+    return {
+        withCaseLock: (caseId, fn) => withTransaction(db, (tx) => fn({
+            loadCase: () => resolveCaseForUpdate(tx, caseTypeFor, caseId),
+            lockCase: async () => {
+                const { rows } = await tx.query(`select id from ${CASES} where id = $1 for update`, [caseId]);
+                if (rows.length === 0)
+                    throw new CaseNotFoundError(caseId);
+            },
+            currentClaim: async () => {
+                const { rows } = await tx.query(`select execution_id, step, scope_key, attempt, expires_at, expires_at <= now() as expired
+             from ${CLAIMS} where case_id = $1`, [caseId]);
+                const row = rows[0];
+                if (!row)
+                    return null;
+                return {
+                    executionId: row.execution_id,
+                    step: row.step,
+                    scopeKey: row.scope_key,
+                    attempt: row.attempt,
+                    expiresAt: row.expires_at.toISOString(),
+                    expired: row.expired,
+                };
+            },
+            insertClaim: async (executionId, step, scopeKey, ttlMs) => {
+                const { rows } = await tx.query(`insert into ${CLAIMS} (case_id, execution_id, step, scope_key, expires_at)
+             values ($1, $2, $3, $4, ${expiryExpression('$5')})
+             returning claimed_at`, [caseId, executionId, step, scopeKey, ttlMs]);
+                return {
+                    claimedAt: rows[0]?.claimed_at.toISOString() ?? new Date().toISOString(),
+                };
+            },
+            deleteClaim: async (executionId) => {
+                await tx.query(`delete from ${CLAIMS} where case_id = $1 and execution_id = $2`, [caseId, executionId]);
+            },
+            appendEntry: (input) => appendEntry(tx, input),
+            updateCaseState: async (state, dormancy) => {
+                const updated = await updateCaseState(tx, caseId, state, dormancy);
+                return {
+                    seq: updated.seq,
+                    endedAt: updated.endedAt === null ? null : updated.endedAt.toISOString(),
+                };
+            },
+            appWrites: async (writes) => {
+                for (const write of writes)
+                    await write(tx);
+            },
+        })),
+        appendEntry: (input) => appendEntry(q, input),
+        heartbeat: async (caseId, executionId, ttlMs) => {
+            await q
+                .query(`update ${CLAIMS}
+           set heartbeat_at = now(), expires_at = ${expiryExpression('$3')}
+           where case_id = $1 and execution_id = $2`, [caseId, executionId, ttlMs])
+                .catch(() => undefined);
+        },
+        bumpAttempt: async (caseId, executionId, attempt) => {
+            await q
+                .query(`update ${CLAIMS} set attempt = $3 where case_id = $1 and execution_id = $2`, [caseId, executionId, attempt])
+                .catch(() => undefined);
+        },
+        releaseClaim: async (caseId, executionId) => {
+            await q
+                .query(`delete from ${CLAIMS} where case_id = $1 and execution_id = $2`, [caseId, executionId])
+                .catch(() => undefined);
+        },
+    };
+};
+//# sourceMappingURL=port.js.map

package/dist/execution/port.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"port.js","sourceRoot":"","sources":["../../src/execution/port.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The lifecycle port: what claim → run → commit asks of storage, and nothing\n * else.\n *\n * An **internal** seam, deliberately. `docs/architecture.md` stands:\n * Postgres is a hard dependency and there is no public storage-adapter\n * abstraction — an app never sees this interface. It exists because the\n * claim state machine (busy vs. takeover, the holder check, retry\n * classification, per-attempt write discard) upholds more always-true\n * rules in one place than anything else in the package, and testing those\n * rules means staging precise situations — an expired lease, a takeover\n * mid-run — that should not require a running database. Two adapters make\n * the seam real: the pg one below for production, and the in-memory one in\n * `test/execution/memory-port.ts` for the tests.\n *\n * The shape keeps the lifecycle's transactional structure explicit:\n * {@link LifecyclePort.withCaseLock} is \"one short transaction holding the\n * case row's lock\" — the claim and the commit are each exactly one of those\n * — and everything else deliberately runs outside any transaction, because\n * a handler is running and the lease, not a lock, carries exclusivity.\n */\n\nimport type { CommitWrite } from '../model/index.js'\nimport type {\n  CaseTypeLookup,\n  DatabaseAccess,\n  Dormancy,\n  ResolvedCase,\n} from '../store/index.js'\nimport {\n  CaseNotFoundError,\n  FRAMEWORK_SCHEMA,\n  queryableOf,\n  resolveCaseForUpdate,\n  updateCaseState,\n} from '../store/index.js'\nimport type { JournalEntry, JournalEntryInput } from './journal.js'\nimport { appendEntry } from './journal.js'\nimport { withTransaction } from './transaction.js'\n\nconst CASES = `${FRAMEWORK_SCHEMA}.cases`\nconst CLAIMS = `${FRAMEWORK_SCHEMA}.claims`\n\n/** `now() + <ms>` as a SQL expression against a bound millisecond parameter. */\nconst expiryExpression = (parameter: string): string =>\n  `now() + (${parameter}::double precision * interval '1 millisecond')`\n\n/** The claim sitting on a case, as the lifecycle needs to judge it. */\nexport interface HeldClaim {\n  readonly executionId: string\n  readonly step: string\n  readonly scopeKey: string | null\n  readonly attempt: number\n  readonly expiresAt: string\n  /** True when the lease has lapsed — the next claimant may take the case over. */\n  readonly expired: boolean\n}\n\n/** What the lifecycle asks of storage inside one case-locked transaction. */\nexport interface LifecycleTx {\n  /**\n   * The case, loaded under its lock and resolved whole — definition looked\n   * up, stored state validated against its schema — the serialization\n   * point. Returning the resolved triple rather than a raw row is what\n   * keeps \"load, resolve, validate, in that order\" spelled once (in\n   * `store/resolve.ts`) instead of re-derived by each adapter's caller.\n   */\n  readonly loadCase: () => Promise<ResolvedCase>\n  /**\n   * Take the case row's lock without interpreting the row — the commit's\n   * serialization point. The commit already holds everything it computed at\n   * the claim; what it needs from the row is only the lock (and proof the\n   * row exists), never a second read-and-validate of the state document.\n   */\n  readonly lockCase: () => Promise<void>\n  /** The claim on the case, `null` when nobody holds it. */\n  readonly currentClaim: () => Promise<HeldClaim | null>\n  readonly insertClaim: (\n    executionId: string,\n    step: string,\n    scopeKey: string | null,\n    ttlMs: number,\n  ) => Promise<{ readonly claimedAt: string }>\n  readonly deleteClaim: (executionId: string) => Promise<void>\n  readonly appendEntry: (input: JournalEntryInput) => Promise<JournalEntry>\n  /** Write the next Case State, bump `seq`, apply the dormancy transition. */\n  readonly updateCaseState: (\n    state: unknown,\n    dormancy: Dormancy | null,\n  ) => Promise<{ readonly seq: number; readonly endedAt: string | null }>\n  /** The app's own `ctx.onCommit` writes, riding the same transaction. */\n  readonly appWrites: (writes: readonly CommitWrite[]) => Promise<void>\n}\n\n/** The verbs the execution lifecycle needs from storage. */\nexport interface LifecyclePort {\n  /** One short transaction holding the case row's lock — a claim or a commit. */\n  readonly withCaseLock: <T>(\n    caseId: string,\n    fn: (tx: LifecycleTx) => Promise<T>,\n  ) => Promise<T>\n  /** Journal outside any transaction — `attempt-failed` / `failed` entries. */\n  readonly appendEntry: (input: JournalEntryInput) => Promise<JournalEntry>\n  /** Refresh the lease. Best-effort: a failed beat just lets the claim age. */\n  readonly heartbeat: (\n    caseId: string,\n    executionId: string,\n    ttlMs: number,\n  ) => Promise<void>\n  /** Keep the lease's attempt counter current across retries. Best-effort. */\n  readonly bumpAttempt: (\n    caseId: string,\n    executionId: string,\n    attempt: number,\n  ) => Promise<void>\n  /** Delete this Execution's claim — scoped to `executionId`, so releasing a lease we no longer hold is a no-op. */\n  readonly releaseClaim: (caseId: string, executionId: string) => Promise<void>\n}\n\ntype ClaimRow = {\n  execution_id: string\n  step: string\n  scope_key: string | null\n  attempt: number\n  expires_at: Date\n  expired: boolean\n}\n\n/** The production adapter: each port verb implemented as SQL over the claims, journal and cases tables. */\nexport const pgLifecyclePort = (\n  db: DatabaseAccess,\n  caseTypeFor: CaseTypeLookup,\n): LifecyclePort => {\n  // The lease verbs are single self-contained statements; only the\n  // case-locked transactions care which arm of the access the caller brought.\n  const q = queryableOf(db)\n  return {\n    withCaseLock: (caseId, fn) =>\n      withTransaction(db, (tx) =>\n        fn({\n          loadCase: () => resolveCaseForUpdate(tx, caseTypeFor, caseId),\n          lockCase: async () => {\n            const { rows } = await tx.query<{ id: string }>(\n              `select id from ${CASES} where id = $1 for update`,\n              [caseId],\n            )\n            if (rows.length === 0) throw new CaseNotFoundError(caseId)\n          },\n          currentClaim: async () => {\n            const { rows } = await tx.query<ClaimRow>(\n              `select execution_id, step, scope_key, attempt, expires_at, expires_at <= now() as expired\n             from ${CLAIMS} where case_id = $1`,\n              [caseId],\n            )\n            const row = rows[0]\n            if (!row) return null\n            return {\n              executionId: row.execution_id,\n              step: row.step,\n              scopeKey: row.scope_key,\n              attempt: row.attempt,\n              expiresAt: row.expires_at.toISOString(),\n              expired: row.expired,\n            }\n          },\n          insertClaim: async (executionId, step, scopeKey, ttlMs) => {\n            const { rows } = await tx.query<{ claimed_at: Date }>(\n              `insert into ${CLAIMS} (case_id, execution_id, step, scope_key, expires_at)\n             values ($1, $2, $3, $4, ${expiryExpression('$5')})\n             returning claimed_at`,\n              [caseId, executionId, step, scopeKey, ttlMs],\n            )\n            return {\n              claimedAt:\n                rows[0]?.claimed_at.toISOString() ?? new Date().toISOString(),\n            }\n          },\n          deleteClaim: async (executionId) => {\n            await tx.query(\n              `delete from ${CLAIMS} where case_id = $1 and execution_id = $2`,\n              [caseId, executionId],\n            )\n          },\n          appendEntry: (input) => appendEntry(tx, input),\n          updateCaseState: async (state, dormancy) => {\n            const updated = await updateCaseState(tx, caseId, state, dormancy)\n            return {\n              seq: updated.seq,\n              endedAt:\n                updated.endedAt === null ? null : updated.endedAt.toISOString(),\n            }\n          },\n          appWrites: async (writes) => {\n            for (const write of writes) await write(tx)\n          },\n        }),\n      ),\n    appendEntry: (input) => appendEntry(q, input),\n    heartbeat: async (caseId, executionId, ttlMs) => {\n      await q\n        .query(\n          `update ${CLAIMS}\n           set heartbeat_at = now(), expires_at = ${expiryExpression('$3')}\n           where case_id = $1 and execution_id = $2`,\n          [caseId, executionId, ttlMs],\n        )\n        .catch(() => undefined)\n    },\n    bumpAttempt: async (caseId, executionId, attempt) => {\n      await q\n        .query(\n          `update ${CLAIMS} set attempt = $3 where case_id = $1 and execution_id = $2`,\n          [caseId, executionId, attempt],\n        )\n        .catch(() => undefined)\n    },\n    releaseClaim: async (caseId, executionId) => {\n      await q\n        .query(\n          `delete from ${CLAIMS} where case_id = $1 and execution_id = $2`,\n          [caseId, executionId],\n        )\n        .catch(() => undefined)\n    },\n  }\n}\n"]}