@affordance/core 0.1.0 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@affordance/core",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "author": "Mochicode LLC (https://mochicode.com)",
   "license": "MIT",
   "type": "module",
@@ -8,22 +8,23 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./storage": {
+      "types": "./dist/storage.d.ts",
+      "import": "./dist/storage.js"
     }
   },
   "dependencies": {
-    "@standard-schema/spec": "^1.1.0",
-    "@types/pg": "^8.11.10",
-    "@affordance/contract": "0.1.0"
+    "@standard-schema/spec": "^1.1.0"
   },
   "devDependencies": {
     "@types/node": "^24.0.0",
     "typescript": "^5.7.2",
     "vitest": "^3.2.0",
-    "pg": "^8.13.1",
     "zod": "^4.4.3",
     "@affordance/testkit": "0.0.0"
   },
-  "description": "Adaptive case management with guarded steps, async execution, and a Postgres journal.",
+  "description": "Adaptive case management with guarded steps, async execution, and pluggable storage.",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "files": [
@@ -46,8 +47,7 @@
   "keywords": [
     "affordance",
     "case-management",
-    "typescript",
-    "postgres"
+    "typescript"
   ],
   "publishConfig": {
     "access": "public",

package/dist/execution/transaction.d.ts

@@ -1,24 +0,0 @@
-/**
- * The transaction seam.
- *
- * The claim and the commit are each one short transaction; the handler runs
- * between them, outside both — so no transaction is ever held open
- * across a handler's external calls. `withTransaction` is how the execution
- * lifecycle gets one, and it is also what a handler's `ctx.onCommit` writes
- * ride along inside.
- */
-import type { DatabaseAccess, Transaction } from '../store/index.js';
-/**
- * Run `fn` inside a transaction and hand it the handle to use — a checked-out
- * client when the caller brought a pool, the client itself when they brought
- * one (issuing `begin` on a *pool* would put each statement on a different
- * connection, so the distinction is not cosmetic). Which case applies is the
- * caller's declaration — {@link DatabaseAccess} — never sniffed from the
- * object.
- *
- * Commits on return, rolls back on throw, and always releases what it
- * checked out. A rollback that itself fails is swallowed: the original error
- * is what the caller needs, and a connection too broken to roll back is
- * discarded by the pool anyway.
- */
-export declare const withTransaction: <T>(db: DatabaseAccess, fn: (tx: Transaction) => Promise<T>) => Promise<T>;

package/dist/execution/transaction.js

@@ -1,49 +0,0 @@
-/**
- * The transaction seam.
- *
- * The claim and the commit are each one short transaction; the handler runs
- * between them, outside both — so no transaction is ever held open
- * across a handler's external calls. `withTransaction` is how the execution
- * lifecycle gets one, and it is also what a handler's `ctx.onCommit` writes
- * ride along inside.
- */
-/**
- * Run `fn` inside a transaction and hand it the handle to use — a checked-out
- * client when the caller brought a pool, the client itself when they brought
- * one (issuing `begin` on a *pool* would put each statement on a different
- * connection, so the distinction is not cosmetic). Which case applies is the
- * caller's declaration — {@link DatabaseAccess} — never sniffed from the
- * object.
- *
- * Commits on return, rolls back on throw, and always releases what it
- * checked out. A rollback that itself fails is swallowed: the original error
- * is what the caller needs, and a connection too broken to roll back is
- * discarded by the pool anyway.
- */
-export const withTransaction = async (db, fn) => {
-    if (!('pool' in db))
-        return runTransaction(db.client, fn);
-    const client = await db.pool.connect();
-    try {
-        return await runTransaction(client, fn);
-    }
-    finally {
-        client.release();
-    }
-};
-const runTransaction = async (handle, fn) => {
-    // The one place the brand is applied: past the `begin` below, this handle
-    // really is inside a transaction.
-    const tx = handle;
-    await tx.query('begin');
-    try {
-        const result = await fn(tx);
-        await tx.query('commit');
-        return result;
-    }
-    catch (error) {
-        await tx.query('rollback').catch(() => undefined);
-        throw error;
-    }
-};
-//# sourceMappingURL=transaction.js.map

package/dist/execution/transaction.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"transaction.js","sourceRoot":"","sources":["../../src/execution/transaction.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,KAAK,EAClC,EAAkB,EAClB,EAAmC,EACvB,EAAE;IACd,IAAI,CAAC,CAAC,MAAM,IAAI,EAAE,CAAC;QAAE,OAAO,cAAc,CAAC,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,CAAA;IACzD,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC,IAAI,CAAC,OAAO,EAAE,CAAA;IACtC,IAAI,CAAC;QACH,OAAO,MAAM,cAAc,CAAC,MAAM,EAAE,EAAE,CAAC,CAAA;IACzC,CAAC;YAAS,CAAC;QACT,MAAM,CAAC,OAAO,EAAE,CAAA;IAClB,CAAC;AACH,CAAC,CAAA;AAED,MAAM,cAAc,GAAG,KAAK,EAC1B,MAAiB,EACjB,EAAmC,EACvB,EAAE;IACd,0EAA0E;IAC1E,kCAAkC;IAClC,MAAM,EAAE,GAAG,MAAqB,CAAA;IAChC,MAAM,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,CAAA;IACvB,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC,EAAE,CAAC,CAAA;QAC3B,MAAM,EAAE,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAA;QACxB,OAAO,MAAM,CAAA;IACf,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,EAAE,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAA;QACjD,MAAM,KAAK,CAAA;IACb,CAAC;AACH,CAAC,CAAA","sourcesContent":["/**\n * The transaction seam.\n *\n * The claim and the commit are each one short transaction; the handler runs\n * between them, outside both — so no transaction is ever held open\n * across a handler's external calls. `withTransaction` is how the execution\n * lifecycle gets one, and it is also what a handler's `ctx.onCommit` writes\n * ride along inside.\n */\n\nimport type { DatabaseAccess, Queryable, Transaction } from '../store/index.js'\n\n/**\n * Run `fn` inside a transaction and hand it the handle to use — a checked-out\n * client when the caller brought a pool, the client itself when they brought\n * one (issuing `begin` on a *pool* would put each statement on a different\n * connection, so the distinction is not cosmetic). Which case applies is the\n * caller's declaration — {@link DatabaseAccess} — never sniffed from the\n * object.\n *\n * Commits on return, rolls back on throw, and always releases what it\n * checked out. A rollback that itself fails is swallowed: the original error\n * is what the caller needs, and a connection too broken to roll back is\n * discarded by the pool anyway.\n */\nexport const withTransaction = async <T>(\n  db: DatabaseAccess,\n  fn: (tx: Transaction) => Promise<T>,\n): Promise<T> => {\n  if (!('pool' in db)) return runTransaction(db.client, fn)\n  const client = await db.pool.connect()\n  try {\n    return await runTransaction(client, fn)\n  } finally {\n    client.release()\n  }\n}\n\nconst runTransaction = async <T>(\n  handle: Queryable,\n  fn: (tx: Transaction) => Promise<T>,\n): Promise<T> => {\n  // The one place the brand is applied: past the `begin` below, this handle\n  // really is inside a transaction.\n  const tx = handle as Transaction\n  await tx.query('begin')\n  try {\n    const result = await fn(tx)\n    await tx.query('commit')\n    return result\n  } catch (error) {\n    await tx.query('rollback').catch(() => undefined)\n    throw error\n  }\n}\n"]}

package/dist/store/bootstrap.d.ts

@@ -1,57 +0,0 @@
-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/store/bootstrap.js

@@ -1,268 +0,0 @@
-/**
- * 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

@@ -1 +0,0 @@
-{"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/queryable.d.ts

@@ -1,60 +0,0 @@
-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

@@ -1,7 +0,0 @@
-/**
- * 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

@@ -1 +0,0 @@
-{"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/sql.d.ts

@@ -1,26 +0,0 @@
-/**
- * The one idiom behind every filtered read in the package: a `where` clause
- * assembled from a list of AND-ed conditions and a positional values array.
- * The journal, the dead-letter surface, and the migration candidate query
- * each read a different table, but they all number their placeholders and
- * join their conditions the same way — stated once here, so a new filter
- * cannot number a placeholder wrong.
- */
-/** A `where` clause under assembly. */
-export interface SqlWhere {
-    /** The AND-ed conditions; push to add one. */
-    readonly conditions: string[];
-    /** The bound values, positionally matching the `$n` placeholders. */
-    readonly values: unknown[];
-    /** Append a value and return its `$n` placeholder. */
-    readonly bind: (value: unknown) => string;
-    /** The conditions joined with ` and ` — the body of the `where` clause. */
-    readonly where: () => string;
-}
-/**
- * Start a `where` clause. Fixed conditions and their values are the seed —
- * a seeded condition may spell its own `$n` as long as it matches the
- * value's position — and optional conditions are pushed with placeholders
- * from `bind`.
- */
-export declare const sqlWhere: (conditions?: string[], values?: unknown[]) => SqlWhere;

package/dist/store/sql.js

@@ -1,21 +0,0 @@
-/**
- * The one idiom behind every filtered read in the package: a `where` clause
- * assembled from a list of AND-ed conditions and a positional values array.
- * The journal, the dead-letter surface, and the migration candidate query
- * each read a different table, but they all number their placeholders and
- * join their conditions the same way — stated once here, so a new filter
- * cannot number a placeholder wrong.
- */
-/**
- * Start a `where` clause. Fixed conditions and their values are the seed —
- * a seeded condition may spell its own `$n` as long as it matches the
- * value's position — and optional conditions are pushed with placeholders
- * from `bind`.
- */
-export const sqlWhere = (conditions = [], values = []) => ({
-    conditions,
-    values,
-    bind: (value) => `$${values.push(value)}`,
-    where: () => conditions.join(' and '),
-});
-//# sourceMappingURL=sql.js.map

package/dist/store/sql.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"sql.js","sourceRoot":"","sources":["../../src/store/sql.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAcH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG,CACtB,aAAuB,EAAE,EACzB,SAAoB,EAAE,EACZ,EAAE,CAAC,CAAC;IACd,UAAU;IACV,MAAM;IACN,IAAI,EAAE,CAAC,KAAc,EAAU,EAAE,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE;IAC1D,KAAK,EAAE,GAAG,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC;CACtC,CAAC,CAAA","sourcesContent":["/**\n * The one idiom behind every filtered read in the package: a `where` clause\n * assembled from a list of AND-ed conditions and a positional values array.\n * The journal, the dead-letter surface, and the migration candidate query\n * each read a different table, but they all number their placeholders and\n * join their conditions the same way — stated once here, so a new filter\n * cannot number a placeholder wrong.\n */\n\n/** A `where` clause under assembly. */\nexport interface SqlWhere {\n  /** The AND-ed conditions; push to add one. */\n  readonly conditions: string[]\n  /** The bound values, positionally matching the `$n` placeholders. */\n  readonly values: unknown[]\n  /** Append a value and return its `$n` placeholder. */\n  readonly bind: (value: unknown) => string\n  /** The conditions joined with ` and ` — the body of the `where` clause. */\n  readonly where: () => string\n}\n\n/**\n * Start a `where` clause. Fixed conditions and their values are the seed —\n * a seeded condition may spell its own `$n` as long as it matches the\n * value's position — and optional conditions are pushed with placeholders\n * from `bind`.\n */\nexport const sqlWhere = (\n  conditions: string[] = [],\n  values: unknown[] = [],\n): SqlWhere => ({\n  conditions,\n  values,\n  bind: (value: unknown): string => `$${values.push(value)}`,\n  where: () => conditions.join(' and '),\n})\n"]}