@affordance/pg 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mochicode LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,35 @@
+# @affordance/pg
+
+Postgres storage for `@affordance/core`: cases, execution claims, journals,
+correlations, delivery deduplication, migrations, and atomic commit effects.
+
+```sh
+npm install @affordance/core @affordance/pg pg
+```
+
+```ts
+import { createEngine } from '@affordance/core'
+import { bootstrap, createPgStorage } from '@affordance/pg'
+import { Pool } from 'pg'
+
+const pool = new Pool({ connectionString: process.env.DATABASE_URL })
+await bootstrap(pool)
+const storage = createPgStorage({ db: { pool } })
+const engine = createEngine({ storage, caseTypes: [purchase] })
+const page = await engine.listCases({ limit: 100 })
+```
+
+The app owns connection lifetime. Supply `{ pool }` for a connection source or
+`{ client }` for a dedicated connection. Schema bootstrap is explicit and
+idempotent; the engine does not run DDL when constructed.
+
+`ctx.onCommit` receives the commit transaction by default. Supply
+`commitContext: tx => ({ payments: createPaymentRepository(tx) })` to expose
+application repositories bound to that transaction instead. Declare the context
+with core's `stepsOf(schema, actor<Actor>(), commitContext<Repositories>())`.
+
+`deleteCase(db, caseId)` is destructive administrative cleanup for disposable
+cases. It deletes the case and its framework records in one transaction.
+
+See [storage adapters](https://github.com/mochicodecom/affordance/blob/main/docs/storage.md)
+for the interface and migration from `createEngine({ db })`.

package/dist/admin.d.ts

@@ -0,0 +1,5 @@
+import type { DatabaseAccess } from './queryable.js';
+/** Destructive administrative cleanup, intended for disposable demo/test cases.
+ * Locks the case before removing related records; all deletions commit together.
+ */
+export declare const deleteCase: (db: DatabaseAccess, caseId: string) => Promise<void>;

package/dist/admin.js

@@ -0,0 +1,12 @@
+import { CASE_TABLES, FRAMEWORK_SCHEMA } from './bootstrap.js';
+import { withTransaction } from './transaction.js';
+/** Destructive administrative cleanup, intended for disposable demo/test cases.
+ * Locks the case before removing related records; all deletions commit together.
+ */
+export const deleteCase = (db, caseId) => withTransaction(db, async (tx) => {
+    await tx.query(`select id from ${FRAMEWORK_SCHEMA}.cases where id = $1 for update`, [caseId]);
+    for (const { table, caseColumn } of CASE_TABLES) {
+        await tx.query(`delete from ${FRAMEWORK_SCHEMA}.${table} where ${caseColumn} = $1`, [caseId]);
+    }
+});
+//# sourceMappingURL=admin.js.map

package/dist/admin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"admin.js","sourceRoot":"","sources":["../src/admin.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAA;AAE9D,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAA;AAElD;;GAEG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,EAAkB,EAAE,MAAc,EAAiB,EAAE,CAC9E,eAAe,CAAC,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,EAAE;IAC/B,MAAM,EAAE,CAAC,KAAK,CACZ,kBAAkB,gBAAgB,iCAAiC,EACnE,CAAC,MAAM,CAAC,CACT,CAAA;IACD,KAAK,MAAM,EAAE,KAAK,EAAE,UAAU,EAAE,IAAI,WAAW,EAAE,CAAC;QAChD,MAAM,EAAE,CAAC,KAAK,CACZ,eAAe,gBAAgB,IAAI,KAAK,UAAU,UAAU,OAAO,EACnE,CAAC,MAAM,CAAC,CACT,CAAA;IACH,CAAC;AACH,CAAC,CAAC,CAAA","sourcesContent":["import { CASE_TABLES, FRAMEWORK_SCHEMA } from './bootstrap.js'\nimport type { DatabaseAccess } from './queryable.js'\nimport { withTransaction } from './transaction.js'\n\n/** Destructive administrative cleanup, intended for disposable demo/test cases.\n * Locks the case before removing related records; all deletions commit together.\n */\nexport const deleteCase = (db: DatabaseAccess, caseId: string): Promise<void> =>\n  withTransaction(db, async (tx) => {\n    await tx.query(\n      `select id from ${FRAMEWORK_SCHEMA}.cases where id = $1 for update`,\n      [caseId],\n    )\n    for (const { table, caseColumn } of CASE_TABLES) {\n      await tx.query(\n        `delete from ${FRAMEWORK_SCHEMA}.${table} where ${caseColumn} = $1`,\n        [caseId],\n      )\n    }\n  })\n"]}

package/dist/bootstrap.d.ts

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

package/dist/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/bootstrap.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bootstrap.js","sourceRoot":"","sources":["../src/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/correlation.d.ts

@@ -0,0 +1,16 @@
+import type { Correlation, CorrelationRegistration } from '@affordance/core';
+import type { Queryable } from './queryable.js';
+/**
+ * Register (or re-register) an external identifier against a case.
+ *
+ * Upserts on `(system, externalId)` — insert, or update the row already
+ * there: a retried handler attempt registering the same envelope again is
+ * not an error, it is the same fact. Pass any
+ * {@link Queryable} — from a handler this is the commit transaction, via
+ * `ctx.correlate` or `ctx.onCommit`.
+ */
+export declare const registerCorrelation: (db: Queryable, registration: CorrelationRegistration) => Promise<Correlation>;
+/** Look up where an external identifier routes; `null` when nothing has claimed it. */
+export declare const lookupCorrelation: (db: Queryable, system: string, externalId: string) => Promise<Correlation | null>;
+/** Every identifier registered against a case — the "what is this case waiting on" view. */
+export declare const correlationsFor: (db: Queryable, caseId: string, scopeKey?: string) => Promise<readonly Correlation[]>;

package/dist/correlation.js

@@ -0,0 +1,62 @@
+import { mintId } from '@affordance/core/storage';
+import { FRAMEWORK_SCHEMA } from './bootstrap.js';
+const CORRELATIONS = `${FRAMEWORK_SCHEMA}.correlations`;
+const toCorrelation = (row) => ({
+    id: row.id,
+    system: row.system,
+    externalId: row.external_id,
+    caseId: row.case_id,
+    scopeKey: row.scope_key,
+    step: row.step,
+    metadata: row.metadata,
+    createdAt: row.created_at.toISOString(),
+});
+/**
+ * Register (or re-register) an external identifier against a case.
+ *
+ * Upserts on `(system, externalId)` — insert, or update the row already
+ * there: a retried handler attempt registering the same envelope again is
+ * not an error, it is the same fact. Pass any
+ * {@link Queryable} — from a handler this is the commit transaction, via
+ * `ctx.correlate` or `ctx.onCommit`.
+ */
+export const registerCorrelation = async (db, registration) => {
+    const { rows } = await db.query(`insert into ${CORRELATIONS} (id, system, external_id, case_id, scope_key, step, metadata)
+     values ($1, $2, $3, $4, $5, $6, $7::jsonb)
+     on conflict (system, external_id) do update
+       set case_id = excluded.case_id,
+           scope_key = excluded.scope_key,
+           step = excluded.step,
+           metadata = excluded.metadata
+     returning id, system, external_id, case_id, scope_key, step, metadata, created_at`, [
+        mintId('correlation'),
+        registration.system,
+        registration.externalId,
+        registration.caseId,
+        registration.scopeKey ?? null,
+        registration.step ?? null,
+        registration.metadata === undefined
+            ? null
+            : JSON.stringify(registration.metadata),
+    ]);
+    const row = rows[0];
+    if (!row)
+        throw new Error(`insert into ${CORRELATIONS} returned no row`);
+    return toCorrelation(row);
+};
+/** Look up where an external identifier routes; `null` when nothing has claimed it. */
+export const lookupCorrelation = async (db, system, externalId) => {
+    const { rows } = await db.query(`select id, system, external_id, case_id, scope_key, step, metadata, created_at
+     from ${CORRELATIONS} where system = $1 and external_id = $2`, [system, externalId]);
+    const row = rows[0];
+    return row === undefined ? null : toCorrelation(row);
+};
+/** Every identifier registered against a case — the "what is this case waiting on" view. */
+export const correlationsFor = async (db, caseId, scopeKey) => {
+    const { rows } = await db.query(`select id, system, external_id, case_id, scope_key, step, metadata, created_at
+     from ${CORRELATIONS}
+     where case_id = $1 ${scopeKey === undefined ? '' : 'and scope_key = $2'}
+     order by created_at asc`, scopeKey === undefined ? [caseId] : [caseId, scopeKey]);
+    return rows.map(toCorrelation);
+};
+//# sourceMappingURL=correlation.js.map

package/dist/correlation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"correlation.js","sourceRoot":"","sources":["../src/correlation.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,EAAE,MAAM,0BAA0B,CAAA;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAA;AAGjD,MAAM,YAAY,GAAG,GAAG,gBAAgB,eAAe,CAAA;AAavD,MAAM,aAAa,GAAG,CAAC,GAAmB,EAAe,EAAE,CAAC,CAAC;IAC3D,EAAE,EAAE,GAAG,CAAC,EAAE;IACV,MAAM,EAAE,GAAG,CAAC,MAAM;IAClB,UAAU,EAAE,GAAG,CAAC,WAAW;IAC3B,MAAM,EAAE,GAAG,CAAC,OAAO;IACnB,QAAQ,EAAE,GAAG,CAAC,SAAS;IACvB,IAAI,EAAE,GAAG,CAAC,IAAI;IACd,QAAQ,EAAE,GAAG,CAAC,QAAQ;IACtB,SAAS,EAAE,GAAG,CAAC,UAAU,CAAC,WAAW,EAAE;CACxC,CAAC,CAAA;AAEF;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,KAAK,EACtC,EAAa,EACb,YAAqC,EACf,EAAE;IACxB,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,EAAE,CAAC,KAAK,CAC7B,eAAe,YAAY;;;;;;;uFAOwD,EACnF;QACE,MAAM,CAAC,aAAa,CAAC;QACrB,YAAY,CAAC,MAAM;QACnB,YAAY,CAAC,UAAU;QACvB,YAAY,CAAC,MAAM;QACnB,YAAY,CAAC,QAAQ,IAAI,IAAI;QAC7B,YAAY,CAAC,IAAI,IAAI,IAAI;QACzB,YAAY,CAAC,QAAQ,KAAK,SAAS;YACjC,CAAC,CAAC,IAAI;YACN,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,YAAY,CAAC,QAAQ,CAAC;KAC1C,CACF,CAAA;IACD,MAAM,GAAG,GAAG,IAAI,CAAC,CAAC,CAAC,CAAA;IACnB,IAAI,CAAC,GAAG;QAAE,MAAM,IAAI,KAAK,CAAC,eAAe,YAAY,kBAAkB,CAAC,CAAA;IACxE,OAAO,aAAa,CAAC,GAAG,CAAC,CAAA;AAC3B,CAAC,CAAA;AAED,uFAAuF;AACvF,MAAM,CAAC,MAAM,iBAAiB,GAAG,KAAK,EACpC,EAAa,EACb,MAAc,EACd,UAAkB,EACW,EAAE;IAC/B,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,EAAE,CAAC,KAAK,CAC7B;YACQ,YAAY,yCAAyC,EAC7D,CAAC,MAAM,EAAE,UAAU,CAAC,CACrB,CAAA;IACD,MAAM,GAAG,GAAG,IAAI,CAAC,CAAC,CAAC,CAAA;IACnB,OAAO,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,aAAa,CAAC,GAAG,CAAC,CAAA;AACtD,CAAC,CAAA;AAED,4FAA4F;AAC5F,MAAM,CAAC,MAAM,eAAe,GAAG,KAAK,EAClC,EAAa,EACb,MAAc,EACd,QAAiB,EACgB,EAAE;IACnC,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,EAAE,CAAC,KAAK,CAC7B;YACQ,YAAY;0BACE,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,oBAAoB;6BAC/C,EACzB,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,QAAQ,CAAC,CACvD,CAAA;IACD,OAAO,IAAI,CAAC,GAAG,CAAC,aAAa,CAAC,CAAA;AAChC,CAAC,CAAA","sourcesContent":["import type { Correlation, CorrelationRegistration } from '@affordance/core'\nimport { mintId } from '@affordance/core/storage'\nimport { FRAMEWORK_SCHEMA } from './bootstrap.js'\nimport type { Queryable } from './queryable.js'\n\nconst CORRELATIONS = `${FRAMEWORK_SCHEMA}.correlations`\n\ntype CorrelationRow = {\n  id: string\n  system: string\n  external_id: string\n  case_id: string\n  scope_key: string | null\n  step: string | null\n  metadata: unknown\n  created_at: Date\n}\n\nconst toCorrelation = (row: CorrelationRow): Correlation => ({\n  id: row.id,\n  system: row.system,\n  externalId: row.external_id,\n  caseId: row.case_id,\n  scopeKey: row.scope_key,\n  step: row.step,\n  metadata: row.metadata,\n  createdAt: row.created_at.toISOString(),\n})\n\n/**\n * Register (or re-register) an external identifier against a case.\n *\n * Upserts on `(system, externalId)` — insert, or update the row already\n * there: a retried handler attempt registering the same envelope again is\n * not an error, it is the same fact. Pass any\n * {@link Queryable} — from a handler this is the commit transaction, via\n * `ctx.correlate` or `ctx.onCommit`.\n */\nexport const registerCorrelation = async (\n  db: Queryable,\n  registration: CorrelationRegistration,\n): Promise<Correlation> => {\n  const { rows } = await db.query<CorrelationRow>(\n    `insert into ${CORRELATIONS} (id, system, external_id, case_id, scope_key, step, metadata)\n     values ($1, $2, $3, $4, $5, $6, $7::jsonb)\n     on conflict (system, external_id) do update\n       set case_id = excluded.case_id,\n           scope_key = excluded.scope_key,\n           step = excluded.step,\n           metadata = excluded.metadata\n     returning id, system, external_id, case_id, scope_key, step, metadata, created_at`,\n    [\n      mintId('correlation'),\n      registration.system,\n      registration.externalId,\n      registration.caseId,\n      registration.scopeKey ?? null,\n      registration.step ?? null,\n      registration.metadata === undefined\n        ? null\n        : JSON.stringify(registration.metadata),\n    ],\n  )\n  const row = rows[0]\n  if (!row) throw new Error(`insert into ${CORRELATIONS} returned no row`)\n  return toCorrelation(row)\n}\n\n/** Look up where an external identifier routes; `null` when nothing has claimed it. */\nexport const lookupCorrelation = async (\n  db: Queryable,\n  system: string,\n  externalId: string,\n): Promise<Correlation | null> => {\n  const { rows } = await db.query<CorrelationRow>(\n    `select id, system, external_id, case_id, scope_key, step, metadata, created_at\n     from ${CORRELATIONS} where system = $1 and external_id = $2`,\n    [system, externalId],\n  )\n  const row = rows[0]\n  return row === undefined ? null : toCorrelation(row)\n}\n\n/** Every identifier registered against a case — the \"what is this case waiting on\" view. */\nexport const correlationsFor = async (\n  db: Queryable,\n  caseId: string,\n  scopeKey?: string,\n): Promise<readonly Correlation[]> => {\n  const { rows } = await db.query<CorrelationRow>(\n    `select id, system, external_id, case_id, scope_key, step, metadata, created_at\n     from ${CORRELATIONS}\n     where case_id = $1 ${scopeKey === undefined ? '' : 'and scope_key = $2'}\n     order by created_at asc`,\n    scopeKey === undefined ? [caseId] : [caseId, scopeKey],\n  )\n  return rows.map(toCorrelation)\n}\n"]}

package/dist/delivery.d.ts

@@ -0,0 +1,30 @@
+import type { DeadLetter, DeadLetterFilter, DeadLetterReason, ExternalEvent } from '@affordance/core';
+import type { DeliveryRecord } from '@affordance/core/storage';
+import type { Queryable } from './queryable.js';
+/**
+ * The dedup gate. Inserts the event's row and reports whether this delivery
+ * is the one that got it.
+ *
+ * `on conflict do nothing` is the whole mechanism: exactly one of N
+ * concurrent deliveries inserts, and the losers read what the winner wrote.
+ * A previous delivery that ended `dead-lettered` for a *transient* reason is
+ * reopened rather than deduplicated — a provider retry after "the case was
+ * busy" should get its chance, which is precisely what provider retries are
+ * for.
+ */
+export declare const claimDelivery: (db: Queryable, event: ExternalEvent, idempotencyKey: string, reopenable: readonly DeadLetterReason[]) => Promise<{
+    row: DeliveryRecord;
+    fresh: boolean;
+}>;
+/** Record how a delivery ended. The row is the dead-letter surface, so this is the only settle path. */
+export declare const settle: (db: Queryable, id: string, fields: {
+    status: "executed" | "dead-lettered";
+    caseId?: string | null;
+    scopeKey?: string | null;
+    step?: string | null;
+    reason?: DeadLetterReason | null;
+    detail?: string | null;
+    executionId?: string | null;
+}) => Promise<void>;
+/** Read the dead-letter surface, newest first — the ops view of "arrived, did nothing". */
+export declare const readDeadLetters: (db: Queryable, filter?: DeadLetterFilter) => Promise<readonly DeadLetter[]>;