@affordance/core 0.1.0

package/dist/store/bootstrap.js

@@ -0,0 +1,268 @@
+/**
+ * Dedicated Postgres schema owning all framework tables.
+ * Named `affordance` because `case` itself is a SQL reserved word.
+ */
+export 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 const SCHEMA_VERSION = 4;
+/**
+ * Framework DDL, `IF NOT EXISTS` throughout — no migration framework.
+ *
+ * `cases` columns:
+ * - `id`         text — a typed id (`case:<uuid>`), minted by the store on
+ *                creation; every framework id carries its kind (see `ids.ts`)
+ * - `case_type`  the Case Type name (the code definition floats; only the
+ *                name is persisted)
+ * - `state`      the materialized Case State document
+ * - `seq`        per-case monotonic sequence counter, starts at 0; bumped by
+ *                every committed Execution
+ * - `ended_at`   dormancy marker written by `end()` — null while active;
+ *                dormancy, never a freeze (spec §Core model)
+ *
+ * `journal` is the immutable per-Execution record. The framework
+ * only ever **inserts** into it — no update or delete path exists anywhere in
+ * the library. One Execution contributes several entries (`claimed`, then any
+ * `attempt-failed`, then a terminal `completed` / `failed` / `expired`), each
+ * self-contained so a per-track audit is a filter, never a join:
+ * - `ordinal`      bigserial — total insertion order; per-case order is
+ *                  `(case_id, ordinal)`
+ * - `entry`        which lifecycle moment this row records
+ * - `step`/`scope_key`/`actor`/`input` — the Execution's identity, repeated on
+ *                  every entry so `where scope_key = …` is the per-track audit
+ * - `as_of`/`guard`/`state` — on `claimed`: the transactional guard
+ *                  re-evaluation, the instant it was evaluated as of, and the
+ *                  Case State it was evaluated against. Together they make
+ *                  audit reconstruction exact rather than approximate.
+ * - `delta`        on `completed`: the JSON-Patch delta (previous → next)
+ * - `dormancy`     on `completed`: `end()` / `reopen()` called by the handler
+ * - `error`        on `attempt-failed` / `failed` / `expired`
+ *
+ * `correlations` and `ingested_events` are the two integration primitives.
+ * A correlation maps an external identifier to (case, scope
+ * element); it is written by the handler that starts the external
+ * interaction, and `unique (system, external_id)` makes re-registering the
+ * same envelope idempotent — a repeat changes nothing. `ingested_events` is
+ * both the dedup gate and the dead-letter surface: `unique (idempotency_key)`
+ * is what makes "three deliveries, one Execution" a database fact rather than
+ * a hope, and the `status` / `reason` columns are why an event that changed
+ * nothing is still visible.
+ *
+ * `claims` is the opposite kind of table: mutable, transient lease
+ * bookkeeping, one row per **in-flight** Execution, deleted the moment the
+ * Execution settles. `case_id` is its primary key — that single constraint is
+ * "one in-flight execution per case". `expires_at` is what keeps a crash
+ * from stranding a case: a crashed handler stops heartbeating and the next
+ * claimant takes the case over (journaling an `expired` entry for the
+ * abandoned Execution).
+ */
+const DDL = `
+select pg_advisory_xact_lock(hashtextextended('${FRAMEWORK_SCHEMA}.bootstrap', 0));
+
+-- DDL must never be what blocks live work. "create index if not exists" and
+-- friends take table locks whether or not they have anything to do, so a
+-- bootstrap running against a busy database can queue behind -- or deadlock
+-- with -- Executions committing. Bounding the wait makes this transaction
+-- the one that yields, and bootstrap() retries it.
+set local lock_timeout = '2s';
+
+create schema if not exists ${FRAMEWORK_SCHEMA};
+
+-- Schema v2 stores typed text ids ('case:<uuid>', 'execution:<uuid>', …); v1
+-- stored bare uuids in uuid columns, which cannot hold them. There is no DDL
+-- migration framework, so a v1 database fails loudly here rather than
+-- corrupting silently on the first insert.
+do $$
+begin
+  if exists (
+    select 1 from information_schema.columns
+    where table_schema = '${FRAMEWORK_SCHEMA}' and table_name = 'cases'
+      and column_name = 'id' and data_type = 'uuid'
+  ) then
+    raise exception 'affordance schema v1 detected (uuid ids); v2 ids are text of the form kind:uuid. No automatic conversion exists — export anything you need, then: drop schema ${FRAMEWORK_SCHEMA} cascade; and re-bootstrap.';
+  end if;
+end $$;
+
+create table if not exists ${FRAMEWORK_SCHEMA}.cases (
+  id text primary key,
+  case_type text not null,
+  state jsonb not null,
+  seq bigint not null default 0,
+  ended_at timestamptz,
+  created_at timestamptz not null default now(),
+  updated_at timestamptz not null default now()
+);
+
+create table if not exists ${FRAMEWORK_SCHEMA}.journal (
+  ordinal bigserial primary key,
+  id text not null unique,
+  case_id text not null references ${FRAMEWORK_SCHEMA}.cases (id),
+  execution_id text not null,
+  entry text not null,
+  attempt integer not null default 1,
+  step text not null,
+  scope_key text,
+  actor jsonb,
+  input jsonb,
+  as_of timestamptz,
+  guard jsonb,
+  state jsonb,
+  delta jsonb,
+  dormancy text,
+  error jsonb,
+  recorded_at timestamptz not null default now()
+);
+
+-- Schema v4 removed rule automation, and with it the \`cause\` column (the
+-- causality record an automatic Execution carried). The column is left in
+-- place on a database that has it: journal rows are immutable history, and
+-- old automatic Executions keep the cause they were recorded with. New
+-- entries simply never write it.
+
+create index if not exists journal_case_idx
+  on ${FRAMEWORK_SCHEMA}.journal (case_id, ordinal);
+create index if not exists journal_scope_idx
+  on ${FRAMEWORK_SCHEMA}.journal (case_id, scope_key, ordinal);
+create index if not exists journal_execution_idx
+  on ${FRAMEWORK_SCHEMA}.journal (execution_id, ordinal);
+
+create table if not exists ${FRAMEWORK_SCHEMA}.claims (
+  case_id text primary key references ${FRAMEWORK_SCHEMA}.cases (id),
+  execution_id text not null,
+  step text not null,
+  scope_key text,
+  attempt integer not null default 1,
+  claimed_at timestamptz not null default now(),
+  heartbeat_at timestamptz not null default now(),
+  expires_at timestamptz not null
+);
+
+-- Schema v3 removed timer scheduling. Timer rows were derived state (a
+-- case's future time-flips, recomputable from nothing but Case State), so
+-- dropping the table on a v2 database loses no facts.
+drop table if exists ${FRAMEWORK_SCHEMA}.timers;
+
+create table if not exists ${FRAMEWORK_SCHEMA}.correlations (
+  id text primary key,
+  system text not null,
+  external_id text not null,
+  case_id text not null references ${FRAMEWORK_SCHEMA}.cases (id),
+  scope_key text,
+  step text,
+  metadata jsonb,
+  created_at timestamptz not null default now(),
+  unique (system, external_id)
+);
+
+create index if not exists correlations_case_idx
+  on ${FRAMEWORK_SCHEMA}.correlations (case_id, scope_key);
+
+create table if not exists ${FRAMEWORK_SCHEMA}.ingested_events (
+  id text primary key,
+  system text not null,
+  external_id text not null,
+  type text not null,
+  idempotency_key text not null unique,
+  case_id text,
+  scope_key text,
+  step text,
+  status text not null,
+  reason text,
+  detail text,
+  execution_id text,
+  event jsonb not null,
+  received_at timestamptz not null default now()
+);
+
+create index if not exists ingested_events_dead_letter_idx
+  on ${FRAMEWORK_SCHEMA}.ingested_events (status, received_at desc);
+
+create table if not exists ${FRAMEWORK_SCHEMA}.schema_version (
+  version integer primary key,
+  applied_at timestamptz not null default now()
+);
+
+insert into ${FRAMEWORK_SCHEMA}.schema_version (version)
+values (${SCHEMA_VERSION}) on conflict do nothing;
+`;
+/**
+ * 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 const CASE_TABLES = [
+    { table: 'journal', caseColumn: 'case_id' },
+    { table: 'claims', caseColumn: 'case_id' },
+    { table: 'correlations', caseColumn: 'case_id' },
+    { table: 'ingested_events', caseColumn: 'case_id' },
+    { table: 'cases', caseColumn: 'id' },
+];
+/**
+ * Whether the schema is already at {@link SCHEMA_VERSION} — two catalog reads
+ * that take no lock any Execution could ever be waiting on.
+ *
+ * This is what makes `bootstrap` free on every start after the first. The DDL
+ * below is idempotent, but idempotent is not the same as *harmless*: `create
+ * index if not exists` takes a table lock whether or not it has work to do,
+ * and a bootstrap holding one while Executions commit can deadlock with them
+ * — not as a rare race, but predictably, on every start against a busy
+ * database. Asking first means the locks are only ever taken when there is
+ * genuinely something to create.
+ */
+const isCurrent = async (db) => {
+    const marker = await db.query(`select to_regclass('${FRAMEWORK_SCHEMA}.schema_version') is not null as present`);
+    if (marker.rows[0]?.present !== true)
+        return false;
+    const applied = await db.query(`select max(version) as version from ${FRAMEWORK_SCHEMA}.schema_version`);
+    return (applied.rows[0]?.version ?? 0) >= SCHEMA_VERSION;
+};
+/** Postgres says the transaction lost a race it can retry: deadlock, or the bounded lock wait. */
+const isContention = (error) => {
+    const code = error?.code;
+    return code === '40P01' || code === '55P03' || code === '40001';
+};
+const wait = (ms) => new Promise((resolve) => {
+    setTimeout(resolve, ms);
+});
+/**
+ * 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 const bootstrap = async (db, attempts = 5) => {
+    if (await isCurrent(db))
+        return;
+    for (let attempt = 1;; attempt += 1) {
+        try {
+            await db.query(DDL);
+            return;
+        }
+        catch (error) {
+            if (attempt >= attempts || !isContention(error))
+                throw error;
+            await wait(50 * attempt);
+        }
+    }
+};
+//# sourceMappingURL=bootstrap.js.map

package/dist/store/bootstrap.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bootstrap.js","sourceRoot":"","sources":["../../src/store/bootstrap.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Queryable } from './queryable.js'\n\n/**\n * Dedicated Postgres schema owning all framework tables.\n * Named `affordance` because `case` itself is a SQL reserved word.\n */\nexport const FRAMEWORK_SCHEMA = 'affordance'\n\n/**\n * The DDL revision below. Bump it whenever the DDL changes: a database\n * already carrying this version skips the DDL entirely, which is what keeps\n * a start-up from touching a busy database at all.\n */\nexport const SCHEMA_VERSION = 4\n\n/**\n * Framework DDL, `IF NOT EXISTS` throughout — no migration framework.\n *\n * `cases` columns:\n * - `id`         text — a typed id (`case:<uuid>`), minted by the store on\n *                creation; every framework id carries its kind (see `ids.ts`)\n * - `case_type`  the Case Type name (the code definition floats; only the\n *                name is persisted)\n * - `state`      the materialized Case State document\n * - `seq`        per-case monotonic sequence counter, starts at 0; bumped by\n *                every committed Execution\n * - `ended_at`   dormancy marker written by `end()` — null while active;\n *                dormancy, never a freeze (spec §Core model)\n *\n * `journal` is the immutable per-Execution record. The framework\n * only ever **inserts** into it — no update or delete path exists anywhere in\n * the library. One Execution contributes several entries (`claimed`, then any\n * `attempt-failed`, then a terminal `completed` / `failed` / `expired`), each\n * self-contained so a per-track audit is a filter, never a join:\n * - `ordinal`      bigserial — total insertion order; per-case order is\n *                  `(case_id, ordinal)`\n * - `entry`        which lifecycle moment this row records\n * - `step`/`scope_key`/`actor`/`input` — the Execution's identity, repeated on\n *                  every entry so `where scope_key = …` is the per-track audit\n * - `as_of`/`guard`/`state` — on `claimed`: the transactional guard\n *                  re-evaluation, the instant it was evaluated as of, and the\n *                  Case State it was evaluated against. Together they make\n *                  audit reconstruction exact rather than approximate.\n * - `delta`        on `completed`: the JSON-Patch delta (previous → next)\n * - `dormancy`     on `completed`: `end()` / `reopen()` called by the handler\n * - `error`        on `attempt-failed` / `failed` / `expired`\n *\n * `correlations` and `ingested_events` are the two integration primitives.\n * A correlation maps an external identifier to (case, scope\n * element); it is written by the handler that starts the external\n * interaction, and `unique (system, external_id)` makes re-registering the\n * same envelope idempotent — a repeat changes nothing. `ingested_events` is\n * both the dedup gate and the dead-letter surface: `unique (idempotency_key)`\n * is what makes \"three deliveries, one Execution\" a database fact rather than\n * a hope, and the `status` / `reason` columns are why an event that changed\n * nothing is still visible.\n *\n * `claims` is the opposite kind of table: mutable, transient lease\n * bookkeeping, one row per **in-flight** Execution, deleted the moment the\n * Execution settles. `case_id` is its primary key — that single constraint is\n * \"one in-flight execution per case\". `expires_at` is what keeps a crash\n * from stranding a case: a crashed handler stops heartbeating and the next\n * claimant takes the case over (journaling an `expired` entry for the\n * abandoned Execution).\n */\nconst DDL = `\nselect pg_advisory_xact_lock(hashtextextended('${FRAMEWORK_SCHEMA}.bootstrap', 0));\n\n-- DDL must never be what blocks live work. \"create index if not exists\" and\n-- friends take table locks whether or not they have anything to do, so a\n-- bootstrap running against a busy database can queue behind -- or deadlock\n-- with -- Executions committing. Bounding the wait makes this transaction\n-- the one that yields, and bootstrap() retries it.\nset local lock_timeout = '2s';\n\ncreate schema if not exists ${FRAMEWORK_SCHEMA};\n\n-- Schema v2 stores typed text ids ('case:<uuid>', 'execution:<uuid>', …); v1\n-- stored bare uuids in uuid columns, which cannot hold them. There is no DDL\n-- migration framework, so a v1 database fails loudly here rather than\n-- corrupting silently on the first insert.\ndo $$\nbegin\n  if exists (\n    select 1 from information_schema.columns\n    where table_schema = '${FRAMEWORK_SCHEMA}' and table_name = 'cases'\n      and column_name = 'id' and data_type = 'uuid'\n  ) then\n    raise exception 'affordance schema v1 detected (uuid ids); v2 ids are text of the form kind:uuid. No automatic conversion exists — export anything you need, then: drop schema ${FRAMEWORK_SCHEMA} cascade; and re-bootstrap.';\n  end if;\nend $$;\n\ncreate table if not exists ${FRAMEWORK_SCHEMA}.cases (\n  id text primary key,\n  case_type text not null,\n  state jsonb not null,\n  seq bigint not null default 0,\n  ended_at timestamptz,\n  created_at timestamptz not null default now(),\n  updated_at timestamptz not null default now()\n);\n\ncreate table if not exists ${FRAMEWORK_SCHEMA}.journal (\n  ordinal bigserial primary key,\n  id text not null unique,\n  case_id text not null references ${FRAMEWORK_SCHEMA}.cases (id),\n  execution_id text not null,\n  entry text not null,\n  attempt integer not null default 1,\n  step text not null,\n  scope_key text,\n  actor jsonb,\n  input jsonb,\n  as_of timestamptz,\n  guard jsonb,\n  state jsonb,\n  delta jsonb,\n  dormancy text,\n  error jsonb,\n  recorded_at timestamptz not null default now()\n);\n\n-- Schema v4 removed rule automation, and with it the \\`cause\\` column (the\n-- causality record an automatic Execution carried). The column is left in\n-- place on a database that has it: journal rows are immutable history, and\n-- old automatic Executions keep the cause they were recorded with. New\n-- entries simply never write it.\n\ncreate index if not exists journal_case_idx\n  on ${FRAMEWORK_SCHEMA}.journal (case_id, ordinal);\ncreate index if not exists journal_scope_idx\n  on ${FRAMEWORK_SCHEMA}.journal (case_id, scope_key, ordinal);\ncreate index if not exists journal_execution_idx\n  on ${FRAMEWORK_SCHEMA}.journal (execution_id, ordinal);\n\ncreate table if not exists ${FRAMEWORK_SCHEMA}.claims (\n  case_id text primary key references ${FRAMEWORK_SCHEMA}.cases (id),\n  execution_id text not null,\n  step text not null,\n  scope_key text,\n  attempt integer not null default 1,\n  claimed_at timestamptz not null default now(),\n  heartbeat_at timestamptz not null default now(),\n  expires_at timestamptz not null\n);\n\n-- Schema v3 removed timer scheduling. Timer rows were derived state (a\n-- case's future time-flips, recomputable from nothing but Case State), so\n-- dropping the table on a v2 database loses no facts.\ndrop table if exists ${FRAMEWORK_SCHEMA}.timers;\n\ncreate table if not exists ${FRAMEWORK_SCHEMA}.correlations (\n  id text primary key,\n  system text not null,\n  external_id text not null,\n  case_id text not null references ${FRAMEWORK_SCHEMA}.cases (id),\n  scope_key text,\n  step text,\n  metadata jsonb,\n  created_at timestamptz not null default now(),\n  unique (system, external_id)\n);\n\ncreate index if not exists correlations_case_idx\n  on ${FRAMEWORK_SCHEMA}.correlations (case_id, scope_key);\n\ncreate table if not exists ${FRAMEWORK_SCHEMA}.ingested_events (\n  id text primary key,\n  system text not null,\n  external_id text not null,\n  type text not null,\n  idempotency_key text not null unique,\n  case_id text,\n  scope_key text,\n  step text,\n  status text not null,\n  reason text,\n  detail text,\n  execution_id text,\n  event jsonb not null,\n  received_at timestamptz not null default now()\n);\n\ncreate index if not exists ingested_events_dead_letter_idx\n  on ${FRAMEWORK_SCHEMA}.ingested_events (status, received_at desc);\n\ncreate table if not exists ${FRAMEWORK_SCHEMA}.schema_version (\n  version integer primary key,\n  applied_at timestamptz not null default now()\n);\n\ninsert into ${FRAMEWORK_SCHEMA}.schema_version (version)\nvalues (${SCHEMA_VERSION}) on conflict do nothing;\n`\n\n/**\n * Every framework table that holds rows belonging to one case, with the\n * column that names the case — listed in an order safe to delete from\n * (children first; everything references `cases`). **The one answer to\n * \"which tables does the framework own\"** outside the DDL above: a consumer\n * that sweeps per-case rows (a dev console's case purge, a test harness's\n * cleanup) iterates this instead of keeping a private copy that goes stale\n * the release a table is added.\n *\n * `ingested_events.case_id` is nullable — an unrouted event belongs to no\n * case and survives a per-case sweep, which is correct: it was never about\n * the deleted case.\n */\nexport const CASE_TABLES = [\n  { table: 'journal', caseColumn: 'case_id' },\n  { table: 'claims', caseColumn: 'case_id' },\n  { table: 'correlations', caseColumn: 'case_id' },\n  { table: 'ingested_events', caseColumn: 'case_id' },\n  { table: 'cases', caseColumn: 'id' },\n] as const\n\n/**\n * Whether the schema is already at {@link SCHEMA_VERSION} — two catalog reads\n * that take no lock any Execution could ever be waiting on.\n *\n * This is what makes `bootstrap` free on every start after the first. The DDL\n * below is idempotent, but idempotent is not the same as *harmless*: `create\n * index if not exists` takes a table lock whether or not it has work to do,\n * and a bootstrap holding one while Executions commit can deadlock with them\n * — not as a rare race, but predictably, on every start against a busy\n * database. Asking first means the locks are only ever taken when there is\n * genuinely something to create.\n */\nconst isCurrent = async (db: Queryable): Promise<boolean> => {\n  const marker = await db.query<{ present: boolean }>(\n    `select to_regclass('${FRAMEWORK_SCHEMA}.schema_version') is not null as present`,\n  )\n  if (marker.rows[0]?.present !== true) return false\n  const applied = await db.query<{ version: number }>(\n    `select max(version) as version from ${FRAMEWORK_SCHEMA}.schema_version`,\n  )\n  return (applied.rows[0]?.version ?? 0) >= SCHEMA_VERSION\n}\n\n/** Postgres says the transaction lost a race it can retry: deadlock, or the bounded lock wait. */\nconst isContention = (error: unknown): boolean => {\n  const code = (error as { code?: unknown } | null)?.code\n  return code === '40P01' || code === '55P03' || code === '40001'\n}\n\nconst wait = (ms: number): Promise<void> =>\n  new Promise((resolve) => {\n    setTimeout(resolve, ms)\n  })\n\n/**\n * Idempotent DDL bootstrap for the framework schema. Safe to call on every\n * app start and from concurrent processes: the statements are sent as one\n * multi-statement simple query, which Postgres runs on one connection inside\n * a single implicit transaction, and the leading `pg_advisory_xact_lock`\n * serializes racing bootstraps (concurrent `CREATE ... IF NOT EXISTS` can\n * otherwise fail on catalog uniqueness).\n *\n * Also safe to call against a *busy* database, which is the harder promise,\n * and is answered twice over. First, a bootstrap with nothing to do does\n * nothing at all: {@link isCurrent} checks the version marker and returns\n * before any DDL runs, so the common case takes no table locks whatsoever.\n * Second, when there *is* work, the transaction bounds its own lock wait and\n * this retries it — schema management yields to live work, never the reverse.\n */\nexport const bootstrap = async (db: Queryable, attempts = 5): Promise<void> => {\n  if (await isCurrent(db)) return\n  for (let attempt = 1; ; attempt += 1) {\n    try {\n      await db.query(DDL)\n      return\n    } catch (error) {\n      if (attempt >= attempts || !isContention(error)) throw error\n      await wait(50 * attempt)\n    }\n  }\n}\n"]}

package/dist/store/errors.d.ts

@@ -0,0 +1,18 @@
+import type { StandardSchemaV1 } from '@standard-schema/spec';
+import { AffordanceError } from '../errors.js';
+/**
+ * A Case State document failed validation against the provided state schema —
+ * either an invalid initial state on `createCase`, or a stored state that no
+ * longer satisfies the schema on `loadCase` (loud by design: cases float to
+ * the latest definitions, so a load-time mismatch is an app bug,
+ * never something to paper over).
+ */
+export declare class CaseStateValidationError extends AffordanceError {
+    readonly issues: readonly StandardSchemaV1.Issue[];
+    constructor(context: string, issues: readonly StandardSchemaV1.Issue[]);
+}
+/** No case row exists for the given case id. */
+export declare class CaseNotFoundError extends AffordanceError {
+    readonly caseId: string;
+    constructor(caseId: string);
+}

package/dist/store/errors.js

@@ -0,0 +1,26 @@
+import { AffordanceError } from '../errors.js';
+/**
+ * A Case State document failed validation against the provided state schema —
+ * either an invalid initial state on `createCase`, or a stored state that no
+ * longer satisfies the schema on `loadCase` (loud by design: cases float to
+ * the latest definitions, so a load-time mismatch is an app bug,
+ * never something to paper over).
+ */
+export class CaseStateValidationError extends AffordanceError {
+    issues;
+    constructor(context, issues) {
+        super('invalid-state', `invalid ${context}: ${issues.map((issue) => issue.message).join('; ')}`);
+        this.name = 'CaseStateValidationError';
+        this.issues = issues;
+    }
+}
+/** No case row exists for the given case id. */
+export class CaseNotFoundError extends AffordanceError {
+    caseId;
+    constructor(caseId) {
+        super('not-found', `case not found: ${caseId}`);
+        this.name = 'CaseNotFoundError';
+        this.caseId = caseId;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/store/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/store/errors.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAA;AAE9C;;;;;;GAMG;AACH,MAAM,OAAO,wBAAyB,SAAQ,eAAe;IAClD,MAAM,CAAmC;IAElD,YAAY,OAAe,EAAE,MAAyC;QACpE,KAAK,CACH,eAAe,EACf,WAAW,OAAO,KAAK,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CACzE,CAAA;QACD,IAAI,CAAC,IAAI,GAAG,0BAA0B,CAAA;QACtC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAA;IACtB,CAAC;CACF;AAED,gDAAgD;AAChD,MAAM,OAAO,iBAAkB,SAAQ,eAAe;IAC3C,MAAM,CAAQ;IAEvB,YAAY,MAAc;QACxB,KAAK,CAAC,WAAW,EAAE,mBAAmB,MAAM,EAAE,CAAC,CAAA;QAC/C,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAA;QAC/B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAA;IACtB,CAAC;CACF","sourcesContent":["import type { StandardSchemaV1 } from '@standard-schema/spec'\nimport { AffordanceError } from '../errors.js'\n\n/**\n * A Case State document failed validation against the provided state schema —\n * either an invalid initial state on `createCase`, or a stored state that no\n * longer satisfies the schema on `loadCase` (loud by design: cases float to\n * the latest definitions, so a load-time mismatch is an app bug,\n * never something to paper over).\n */\nexport class CaseStateValidationError extends AffordanceError {\n  readonly issues: readonly StandardSchemaV1.Issue[]\n\n  constructor(context: string, issues: readonly StandardSchemaV1.Issue[]) {\n    super(\n      'invalid-state',\n      `invalid ${context}: ${issues.map((issue) => issue.message).join('; ')}`,\n    )\n    this.name = 'CaseStateValidationError'\n    this.issues = issues\n  }\n}\n\n/** No case row exists for the given case id. */\nexport class CaseNotFoundError extends AffordanceError {\n  readonly caseId: string\n\n  constructor(caseId: string) {\n    super('not-found', `case not found: ${caseId}`)\n    this.name = 'CaseNotFoundError'\n    this.caseId = caseId\n  }\n}\n"]}

package/dist/store/ids.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The kinds of id the framework mints. One entry per entity that gets an
+ * id at runtime.
+ */
+export type IdKind = 'case' | 'execution' | 'journal' | 'correlation' | 'event';
+/**
+ * Mint a typed id: `kind:uuid`.
+ *
+ * Every framework-generated id carries its kind, so an id is
+ * self-describing wherever it travels — a log line, a journal row's
+ * `cause`, a correlation, a support ticket. The columns holding them are
+ * `text`; nothing anywhere parses the id back apart — the prefix is for
+ * humans, and equality is the only operation ids support.
+ */
+export declare const mintId: (kind: IdKind) => string;

package/dist/store/ids.js

@@ -0,0 +1,12 @@
+import { randomUUID } from 'node:crypto';
+/**
+ * Mint a typed id: `kind:uuid`.
+ *
+ * Every framework-generated id carries its kind, so an id is
+ * self-describing wherever it travels — a log line, a journal row's
+ * `cause`, a correlation, a support ticket. The columns holding them are
+ * `text`; nothing anywhere parses the id back apart — the prefix is for
+ * humans, and equality is the only operation ids support.
+ */
+export const mintId = (kind) => `${kind}:${randomUUID()}`;
+//# sourceMappingURL=ids.js.map

package/dist/store/ids.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ids.js","sourceRoot":"","sources":["../../src/store/ids.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAQxC;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,MAAM,GAAG,CAAC,IAAY,EAAU,EAAE,CAAC,GAAG,IAAI,IAAI,UAAU,EAAE,EAAE,CAAA","sourcesContent":["import { randomUUID } from 'node:crypto'\n\n/**\n * The kinds of id the framework mints. One entry per entity that gets an\n * id at runtime.\n */\nexport type IdKind = 'case' | 'execution' | 'journal' | 'correlation' | 'event'\n\n/**\n * Mint a typed id: `kind:uuid`.\n *\n * Every framework-generated id carries its kind, so an id is\n * self-describing wherever it travels — a log line, a journal row's\n * `cause`, a correlation, a support ticket. The columns holding them are\n * `text`; nothing anywhere parses the id back apart — the prefix is for\n * humans, and equality is the only operation ids support.\n */\nexport const mintId = (kind: IdKind): string => `${kind}:${randomUUID()}`\n"]}

package/dist/store/index.d.ts

@@ -0,0 +1,12 @@
+export { bootstrap, CASE_TABLES, FRAMEWORK_SCHEMA } from './bootstrap.js';
+export { CaseNotFoundError, CaseStateValidationError } from './errors.js';
+export type { IdKind } from './ids.js';
+export { mintId } from './ids.js';
+export type { DatabaseAccess, PoolLike, Queryable, Transaction, } from './queryable.js';
+export { queryableOf } from './queryable.js';
+export type { CaseTypeLookup, ResolvedCase } from './resolve.js';
+export { resolveCase, resolveCaseForUpdate, resolveStoredState, validateCaseState, } from './resolve.js';
+export type { SqlWhere } from './sql.js';
+export { sqlWhere } from './sql.js';
+export type { CaseHandle, Dormancy } from './store.js';
+export { insertCase, selectCase, selectCaseForUpdate, selectCaseUntyped, updateCaseState, validateAgainstSchema, } from './store.js';

package/dist/store/index.js

@@ -0,0 +1,9 @@
+// Postgres persistence + case store.
+export { bootstrap, CASE_TABLES, FRAMEWORK_SCHEMA } from './bootstrap.js';
+export { CaseNotFoundError, CaseStateValidationError } from './errors.js';
+export { mintId } from './ids.js';
+export { queryableOf } from './queryable.js';
+export { resolveCase, resolveCaseForUpdate, resolveStoredState, validateCaseState, } from './resolve.js';
+export { sqlWhere } from './sql.js';
+export { insertCase, selectCase, selectCaseForUpdate, selectCaseUntyped, updateCaseState, validateAgainstSchema, } from './store.js';
+//# sourceMappingURL=index.js.map

package/dist/store/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/store/index.ts"],"names":[],"mappings":"AAAA,qCAAqC;AACrC,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAA;AACzE,OAAO,EAAE,iBAAiB,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAA;AAEzE,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAA;AAOjC,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAA;AAE5C,OAAO,EACL,WAAW,EACX,oBAAoB,EACpB,kBAAkB,EAClB,iBAAiB,GAClB,MAAM,cAAc,CAAA;AAErB,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAA;AAEnC,OAAO,EACL,UAAU,EACV,UAAU,EACV,mBAAmB,EACnB,iBAAiB,EACjB,eAAe,EACf,qBAAqB,GACtB,MAAM,YAAY,CAAA","sourcesContent":["// Postgres persistence + case store.\nexport { bootstrap, CASE_TABLES, FRAMEWORK_SCHEMA } from './bootstrap.js'\nexport { CaseNotFoundError, CaseStateValidationError } from './errors.js'\nexport type { IdKind } from './ids.js'\nexport { mintId } from './ids.js'\nexport type {\n  DatabaseAccess,\n  PoolLike,\n  Queryable,\n  Transaction,\n} from './queryable.js'\nexport { queryableOf } from './queryable.js'\nexport type { CaseTypeLookup, ResolvedCase } from './resolve.js'\nexport {\n  resolveCase,\n  resolveCaseForUpdate,\n  resolveStoredState,\n  validateCaseState,\n} from './resolve.js'\nexport type { SqlWhere } from './sql.js'\nexport { sqlWhere } from './sql.js'\nexport type { CaseHandle, Dormancy } from './store.js'\nexport {\n  insertCase,\n  selectCase,\n  selectCaseForUpdate,\n  selectCaseUntyped,\n  updateCaseState,\n  validateAgainstSchema,\n} from './store.js'\n"]}

package/dist/store/queryable.d.ts

@@ -0,0 +1,60 @@
+import type { QueryResult, QueryResultRow } from 'pg';
+/**
+ * Minimal query surface satisfied by pg.Pool, pg.Client, and pg.PoolClient.
+ *
+ * Every store internal takes a Queryable rather than a Pool so a future
+ * caller can run case-store queries on an existing client/transaction —
+ * the shared-transaction seam (spec §Mechanics/Persistence: handlers may
+ * join the framework transaction so app-table writes commit atomically
+ * with case state).
+ */
+export interface Queryable {
+    query<R extends QueryResultRow = QueryResultRow>(text: string, values?: unknown[]): Promise<QueryResult<R>>;
+}
+/**
+ * A pooled connection source: `connect()` checks out a client that must be
+ * released. `pg.Pool` satisfies this structurally, and so does any
+ * multiplexing wrapper (an instrumented pool, a proxy) that declares
+ * checkout the same way.
+ */
+export interface PoolLike extends Queryable {
+    connect(): Promise<Queryable & {
+        release(): void;
+    }>;
+}
+/**
+ * The database as the engine's caller supplies it. The union states, in the
+ * type, the one fact a transaction must know: whether `begin` needs a
+ * checked-out connection first. A pool multiplexes — issuing `begin` on it
+ * would put each statement on a different connection — so `pool` promises
+ * checkout via `connect()`, and `client` asserts a connection dedicated to
+ * the engine, safe to run a transaction on directly. The caller declares
+ * which they have; nothing downstream sniffs the object to guess.
+ */
+export type DatabaseAccess = {
+    readonly pool: PoolLike;
+} | {
+    readonly client: Queryable;
+};
+/**
+ * The plain query surface of either arm — what a single self-contained
+ * statement (a journal read, a heartbeat) runs against, where pool vs.
+ * client makes no difference.
+ */
+export declare const queryableOf: (db: DatabaseAccess) => Queryable;
+declare const transactionBrand: unique symbol;
+/**
+ * A {@link Queryable} known to be inside an open transaction — the handle
+ * `withTransaction` passes to its callback, and the only place the brand is
+ * ever applied.
+ *
+ * Some operations are meaningless (or silently wrong) against a pool: a
+ * `select … for update` whose lock vanishes with the statement, a write
+ * that must commit in the same transaction as the state it accompanies.
+ * Those take a `Transaction`, so "pass the transaction handle, not a pool"
+ * is a compile error rather than a sentence a caller has to have read.
+ */
+export interface Transaction extends Queryable {
+    readonly [transactionBrand]: true;
+}
+export {};

package/dist/store/queryable.js

@@ -0,0 +1,7 @@
+/**
+ * The plain query surface of either arm — what a single self-contained
+ * statement (a journal read, a heartbeat) runs against, where pool vs.
+ * client makes no difference.
+ */
+export const queryableOf = (db) => 'pool' in db ? db.pool : db.client;
+//# sourceMappingURL=queryable.js.map

package/dist/store/queryable.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"queryable.js","sourceRoot":"","sources":["../../src/store/queryable.ts"],"names":[],"mappings":"AAyCA;;;;GAIG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,EAAkB,EAAa,EAAE,CAC3D,MAAM,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,MAAM,CAAA","sourcesContent":["import type { QueryResult, QueryResultRow } from 'pg'\n\n/**\n * Minimal query surface satisfied by pg.Pool, pg.Client, and pg.PoolClient.\n *\n * Every store internal takes a Queryable rather than a Pool so a future\n * caller can run case-store queries on an existing client/transaction —\n * the shared-transaction seam (spec §Mechanics/Persistence: handlers may\n * join the framework transaction so app-table writes commit atomically\n * with case state).\n */\nexport interface Queryable {\n  query<R extends QueryResultRow = QueryResultRow>(\n    text: string,\n    values?: unknown[],\n  ): Promise<QueryResult<R>>\n}\n\n/**\n * A pooled connection source: `connect()` checks out a client that must be\n * released. `pg.Pool` satisfies this structurally, and so does any\n * multiplexing wrapper (an instrumented pool, a proxy) that declares\n * checkout the same way.\n */\nexport interface PoolLike extends Queryable {\n  connect(): Promise<Queryable & { release(): void }>\n}\n\n/**\n * The database as the engine's caller supplies it. The union states, in the\n * type, the one fact a transaction must know: whether `begin` needs a\n * checked-out connection first. A pool multiplexes — issuing `begin` on it\n * would put each statement on a different connection — so `pool` promises\n * checkout via `connect()`, and `client` asserts a connection dedicated to\n * the engine, safe to run a transaction on directly. The caller declares\n * which they have; nothing downstream sniffs the object to guess.\n */\nexport type DatabaseAccess =\n  | { readonly pool: PoolLike }\n  | { readonly client: Queryable }\n\n/**\n * The plain query surface of either arm — what a single self-contained\n * statement (a journal read, a heartbeat) runs against, where pool vs.\n * client makes no difference.\n */\nexport const queryableOf = (db: DatabaseAccess): Queryable =>\n  'pool' in db ? db.pool : db.client\n\ndeclare const transactionBrand: unique symbol\n\n/**\n * A {@link Queryable} known to be inside an open transaction — the handle\n * `withTransaction` passes to its callback, and the only place the brand is\n * ever applied.\n *\n * Some operations are meaningless (or silently wrong) against a pool: a\n * `select … for update` whose lock vanishes with the statement, a write\n * that must commit in the same transaction as the state it accompanies.\n * Those take a `Transaction`, so \"pass the transaction handle, not a pool\"\n * is a compile error rather than a sentence a caller has to have read.\n */\nexport interface Transaction extends Queryable {\n  readonly [transactionBrand]: true\n}\n"]}

package/dist/store/resolve.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Where the registry and the store meet: turning a case row into a Case Type
+ * definition and a Case State that can be trusted.
+ *
+ * Every read path needs the same three moves, in the same order — load the
+ * row, resolve `case_type` against the registered definitions, validate the
+ * stored document against that definition's schema — because the schema to
+ * validate against is only knowable *from* the row. What to do with a
+ * document that fails validation is a real decision, so it is expressed
+ * here as the interface rather than left to each caller:
+ *
+ * - {@link resolveCase} / {@link resolveCaseForUpdate} are **loud**. Their
+ *   callers were handed a case id by somebody and owe them an answer about
+ *   *that* case; a document that no longer validates is an app bug and says
+ *   so ({@link CaseStateValidationError}).
+ * - {@link resolveStoredState} is **lenient**. Its callers sweep — a
+ *   migration scanning a case type — and one
+ *   unreadable case must not take the sweep down.
+ *
+ * The same lenient/loud pair the model draws around scope selection
+ * (`addressTarget`'s value vs `resolveTarget`'s throw), for the same reason.
+ */
+import type { AnyCaseType } from '../model/index.js';
+import type { Queryable, Transaction } from './queryable.js';
+import type { CaseHandle } from './store.js';
+/** Resolve a persisted `case_type` name to its registered definition; throws if unknown. */
+export type CaseTypeLookup = (caseTypeName: string) => AnyCaseType;
+/** A case row, its Case Type definition, and its validated Case State. */
+export interface ResolvedCase {
+    readonly definition: AnyCaseType;
+    /** The row as persisted. Its `state` is the raw document; prefer {@link ResolvedCase.state}. */
+    readonly handle: CaseHandle<unknown>;
+    /** The stored Case State, validated against the definition's schema (defaults applied). */
+    readonly state: unknown;
+}
+/**
+ * Validate a Case State document against a Case Type's schema, loudly.
+ *
+ * `context` names what is being validated, and lands in the error message:
+ * `'stored state'` for a document read back, `"state returned by step 'x'"`
+ * for a handler's return. One function, because "does this document satisfy
+ * the case type" is one question however the document was obtained.
+ */
+export declare const validateCaseState: (definition: AnyCaseType, value: unknown, context?: string) => Promise<unknown>;
+/**
+ * Validate a Case State document already in hand, leniently: `null` when it
+ * no longer satisfies its Case Type's schema.
+ *
+ * The lenient twin of {@link validateCaseState} — literally: the same single
+ * Standard-Schema invocation (`validateAgainstSchema`), with the loud
+ * verdict absorbed. Only the validation verdict is absorbed; a schema whose
+ * `validate` itself throws is a definition bug and stays loud.
+ *
+ * Wrapped in an object rather than returned bare, because a valid Case State
+ * may legitimately *be* `null` and a sweep must not confuse the two.
+ */
+export declare const resolveStoredState: (definition: AnyCaseType, value: unknown) => Promise<{
+    readonly state: unknown;
+} | null>;
+/** Load a case and resolve it against the registered definitions. Loud — see this module's note. */
+export declare const resolveCase: (db: Queryable, caseTypeFor: CaseTypeLookup, caseId: string) => Promise<ResolvedCase>;
+/**
+ * {@link resolveCase} taking the case row's lock — the execution lifecycle's
+ * serialization point.
+ */
+export declare const resolveCaseForUpdate: (tx: Transaction, caseTypeFor: CaseTypeLookup, caseId: string) => Promise<ResolvedCase>;

package/dist/store/resolve.js

@@ -0,0 +1,71 @@
+/**
+ * Where the registry and the store meet: turning a case row into a Case Type
+ * definition and a Case State that can be trusted.
+ *
+ * Every read path needs the same three moves, in the same order — load the
+ * row, resolve `case_type` against the registered definitions, validate the
+ * stored document against that definition's schema — because the schema to
+ * validate against is only knowable *from* the row. What to do with a
+ * document that fails validation is a real decision, so it is expressed
+ * here as the interface rather than left to each caller:
+ *
+ * - {@link resolveCase} / {@link resolveCaseForUpdate} are **loud**. Their
+ *   callers were handed a case id by somebody and owe them an answer about
+ *   *that* case; a document that no longer validates is an app bug and says
+ *   so ({@link CaseStateValidationError}).
+ * - {@link resolveStoredState} is **lenient**. Its callers sweep — a
+ *   migration scanning a case type — and one
+ *   unreadable case must not take the sweep down.
+ *
+ * The same lenient/loud pair the model draws around scope selection
+ * (`addressTarget`'s value vs `resolveTarget`'s throw), for the same reason.
+ */
+import { CaseStateValidationError } from './errors.js';
+import { selectCaseForUpdate, selectCaseUntyped, validateAgainstSchema, } from './store.js';
+/**
+ * Validate a Case State document against a Case Type's schema, loudly.
+ *
+ * `context` names what is being validated, and lands in the error message:
+ * `'stored state'` for a document read back, `"state returned by step 'x'"`
+ * for a handler's return. One function, because "does this document satisfy
+ * the case type" is one question however the document was obtained.
+ */
+export const validateCaseState = async (definition, value, context = 'stored state') => validateAgainstSchema(definition.state, value, context);
+/**
+ * Validate a Case State document already in hand, leniently: `null` when it
+ * no longer satisfies its Case Type's schema.
+ *
+ * The lenient twin of {@link validateCaseState} — literally: the same single
+ * Standard-Schema invocation (`validateAgainstSchema`), with the loud
+ * verdict absorbed. Only the validation verdict is absorbed; a schema whose
+ * `validate` itself throws is a definition bug and stays loud.
+ *
+ * Wrapped in an object rather than returned bare, because a valid Case State
+ * may legitimately *be* `null` and a sweep must not confuse the two.
+ */
+export const resolveStoredState = async (definition, value) => {
+    try {
+        return { state: await validateCaseState(definition, value) };
+    }
+    catch (error) {
+        if (error instanceof CaseStateValidationError)
+            return null;
+        throw error;
+    }
+};
+const resolved = async (handle, caseTypeFor) => {
+    const definition = caseTypeFor(handle.caseTypeName);
+    return {
+        definition,
+        handle,
+        state: await validateCaseState(definition, handle.state),
+    };
+};
+/** Load a case and resolve it against the registered definitions. Loud — see this module's note. */
+export const resolveCase = async (db, caseTypeFor, caseId) => resolved(await selectCaseUntyped(db, caseId), caseTypeFor);
+/**
+ * {@link resolveCase} taking the case row's lock — the execution lifecycle's
+ * serialization point.
+ */
+export const resolveCaseForUpdate = async (tx, caseTypeFor, caseId) => resolved(await selectCaseForUpdate(tx, caseId), caseTypeFor);
+//# sourceMappingURL=resolve.js.map