@affordance/core 0.1.0

package/dist/store/resolve.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.js","sourceRoot":"","sources":["../../src/store/resolve.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAGH,OAAO,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAA;AAGtD,OAAO,EACL,mBAAmB,EACnB,iBAAiB,EACjB,qBAAqB,GACtB,MAAM,YAAY,CAAA;AAcnB;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,KAAK,EACpC,UAAuB,EACvB,KAAc,EACd,OAAO,GAAG,cAAc,EACN,EAAE,CAAC,qBAAqB,CAAC,UAAU,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,CAAC,CAAA;AAE9E;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,KAAK,EACrC,UAAuB,EACvB,KAAc,EAC+B,EAAE;IAC/C,IAAI,CAAC;QACH,OAAO,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAC,UAAU,EAAE,KAAK,CAAC,EAAE,CAAA;IAC9D,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,KAAK,YAAY,wBAAwB;YAAE,OAAO,IAAI,CAAA;QAC1D,MAAM,KAAK,CAAA;IACb,CAAC;AACH,CAAC,CAAA;AAED,MAAM,QAAQ,GAAG,KAAK,EACpB,MAA2B,EAC3B,WAA2B,EACJ,EAAE;IACzB,MAAM,UAAU,GAAG,WAAW,CAAC,MAAM,CAAC,YAAY,CAAC,CAAA;IACnD,OAAO;QACL,UAAU;QACV,MAAM;QACN,KAAK,EAAE,MAAM,iBAAiB,CAAC,UAAU,EAAE,MAAM,CAAC,KAAK,CAAC;KACzD,CAAA;AACH,CAAC,CAAA;AAED,oGAAoG;AACpG,MAAM,CAAC,MAAM,WAAW,GAAG,KAAK,EAC9B,EAAa,EACb,WAA2B,EAC3B,MAAc,EACS,EAAE,CACzB,QAAQ,CAAC,MAAM,iBAAiB,CAAC,EAAE,EAAE,MAAM,CAAC,EAAE,WAAW,CAAC,CAAA;AAE5D;;;GAGG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,KAAK,EACvC,EAAe,EACf,WAA2B,EAC3B,MAAc,EACS,EAAE,CACzB,QAAQ,CAAC,MAAM,mBAAmB,CAAC,EAAE,EAAE,MAAM,CAAC,EAAE,WAAW,CAAC,CAAA","sourcesContent":["/**\n * Where the registry and the store meet: turning a case row into a Case Type\n * definition and a Case State that can be trusted.\n *\n * Every read path needs the same three moves, in the same order — load the\n * row, resolve `case_type` against the registered definitions, validate the\n * stored document against that definition's schema — because the schema to\n * validate against is only knowable *from* the row. What to do with a\n * document that fails validation is a real decision, so it is expressed\n * here as the interface rather than left to each caller:\n *\n * - {@link resolveCase} / {@link resolveCaseForUpdate} are **loud**. Their\n *   callers were handed a case id by somebody and owe them an answer about\n *   *that* case; a document that no longer validates is an app bug and says\n *   so ({@link CaseStateValidationError}).\n * - {@link resolveStoredState} is **lenient**. Its callers sweep — a\n *   migration scanning a case type — and one\n *   unreadable case must not take the sweep down.\n *\n * The same lenient/loud pair the model draws around scope selection\n * (`addressTarget`'s value vs `resolveTarget`'s throw), for the same reason.\n */\n\nimport type { AnyCaseType } from '../model/index.js'\nimport { CaseStateValidationError } from './errors.js'\nimport type { Queryable, Transaction } from './queryable.js'\nimport type { CaseHandle } from './store.js'\nimport {\n  selectCaseForUpdate,\n  selectCaseUntyped,\n  validateAgainstSchema,\n} from './store.js'\n\n/** Resolve a persisted `case_type` name to its registered definition; throws if unknown. */\nexport type CaseTypeLookup = (caseTypeName: string) => AnyCaseType\n\n/** A case row, its Case Type definition, and its validated Case State. */\nexport interface ResolvedCase {\n  readonly definition: AnyCaseType\n  /** The row as persisted. Its `state` is the raw document; prefer {@link ResolvedCase.state}. */\n  readonly handle: CaseHandle<unknown>\n  /** The stored Case State, validated against the definition's schema (defaults applied). */\n  readonly state: unknown\n}\n\n/**\n * Validate a Case State document against a Case Type's schema, loudly.\n *\n * `context` names what is being validated, and lands in the error message:\n * `'stored state'` for a document read back, `\"state returned by step 'x'\"`\n * for a handler's return. One function, because \"does this document satisfy\n * the case type\" is one question however the document was obtained.\n */\nexport const validateCaseState = async (\n  definition: AnyCaseType,\n  value: unknown,\n  context = 'stored state',\n): Promise<unknown> => validateAgainstSchema(definition.state, value, context)\n\n/**\n * Validate a Case State document already in hand, leniently: `null` when it\n * no longer satisfies its Case Type's schema.\n *\n * The lenient twin of {@link validateCaseState} — literally: the same single\n * Standard-Schema invocation (`validateAgainstSchema`), with the loud\n * verdict absorbed. Only the validation verdict is absorbed; a schema whose\n * `validate` itself throws is a definition bug and stays loud.\n *\n * Wrapped in an object rather than returned bare, because a valid Case State\n * may legitimately *be* `null` and a sweep must not confuse the two.\n */\nexport const resolveStoredState = async (\n  definition: AnyCaseType,\n  value: unknown,\n): Promise<{ readonly state: unknown } | null> => {\n  try {\n    return { state: await validateCaseState(definition, value) }\n  } catch (error) {\n    if (error instanceof CaseStateValidationError) return null\n    throw error\n  }\n}\n\nconst resolved = async (\n  handle: CaseHandle<unknown>,\n  caseTypeFor: CaseTypeLookup,\n): Promise<ResolvedCase> => {\n  const definition = caseTypeFor(handle.caseTypeName)\n  return {\n    definition,\n    handle,\n    state: await validateCaseState(definition, handle.state),\n  }\n}\n\n/** Load a case and resolve it against the registered definitions. Loud — see this module's note. */\nexport const resolveCase = async (\n  db: Queryable,\n  caseTypeFor: CaseTypeLookup,\n  caseId: string,\n): Promise<ResolvedCase> =>\n  resolved(await selectCaseUntyped(db, caseId), caseTypeFor)\n\n/**\n * {@link resolveCase} taking the case row's lock — the execution lifecycle's\n * serialization point.\n */\nexport const resolveCaseForUpdate = async (\n  tx: Transaction,\n  caseTypeFor: CaseTypeLookup,\n  caseId: string,\n): Promise<ResolvedCase> =>\n  resolved(await selectCaseForUpdate(tx, caseId), caseTypeFor)\n"]}

package/dist/store/sql.d.ts

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

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

@@ -0,0 +1 @@
+{"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"]}

package/dist/store/store.d.ts

@@ -0,0 +1,66 @@
+import type { StandardSchemaV1 } from '@standard-schema/spec';
+import type { Queryable, Transaction } from './queryable.js';
+/**
+ * A typed handle to one Case as persisted: the materialized Case State plus
+ * the row-level bookkeeping the engine builds on.
+ */
+export interface CaseHandle<State> {
+    /** Case id — a UUID generated by the store on creation. */
+    id: string;
+    /** Name of the Case Type this case is an instance of. */
+    caseTypeName: string;
+    /** The materialized Case State document, validated against the schema. */
+    state: State;
+    /** Per-case monotonic sequence counter, 0 at creation, bumped by every committed Execution. */
+    seq: number;
+    /** Dormancy marker set by `end()`; null while the case is active. */
+    endedAt: Date | null;
+    createdAt: Date;
+    updatedAt: Date;
+}
+/**
+ * Validate a document against a state schema, loudly. The one implementation
+ * of "this document must satisfy this schema or the caller hears about it" —
+ * `resolve.ts` layers the case-type registry on top of it, and everything
+ * that validates a Case State goes through one of the two.
+ */
+export declare const validateAgainstSchema: <S extends StandardSchemaV1>(schema: S, value: unknown, context: string) => Promise<StandardSchemaV1.InferOutput<S>>;
+/**
+ * `createCase` against an explicit {@link Queryable} — the shared-transaction
+ * seam. State is stringified explicitly so array-rooted documents are stored
+ * as jsonb rather than misread as Postgres arrays.
+ */
+export declare const insertCase: <S extends StandardSchemaV1>(db: Queryable, caseTypeName: string, stateSchema: S, initialState: StandardSchemaV1.InferInput<S>) => Promise<CaseHandle<StandardSchemaV1.InferOutput<S>>>;
+/** `loadCase` against an explicit {@link Queryable} — the shared-transaction seam. */
+export declare const selectCase: <S extends StandardSchemaV1>(db: Queryable, id: string, stateSchema: S) => Promise<CaseHandle<StandardSchemaV1.InferOutput<S>>>;
+/**
+ * Load a Case by id with the stored state **unvalidated** (`unknown`).
+ *
+ * Additive export for the engine: the engine learns which state
+ * schema applies only *from* the loaded row — `case_type` names the
+ * registered case type — so it must read the row before it can validate.
+ * Every other caller should prefer {@link selectCase} / `loadCase`, which
+ * validate; whoever consumes this handle owns validating `state` against the
+ * type's schema before trusting it.
+ */
+export declare const selectCaseUntyped: (db: Queryable, id: string) => Promise<CaseHandle<unknown>>;
+/**
+ * Load a Case by id **for update** — `select … for update`, so the row lock is
+ * held until the calling transaction ends.
+ *
+ * This is the execution lifecycle's serialization point: the claim and the
+ * commit both take the case row's lock first, which is what makes the
+ * one-in-flight-execution check (and an expired claim's takeover) a decision
+ * no two transactions can make concurrently.
+ */
+export declare const selectCaseForUpdate: (tx: Transaction, id: string) => Promise<CaseHandle<unknown>>;
+/** The dormancy transition a committing Execution applies to the case row (`end()` / `reopen()`). */
+export type Dormancy = 'ended' | 'reopened';
+/**
+ * Write the next Case State, bump `seq`, and apply the Execution's dormancy
+ * transition, if any: `'ended'` stamps `ended_at`, `'reopened'` clears it,
+ * `null` leaves it exactly as it was. The state document is **not** validated
+ * here — the execution lifecycle validates the handler's return against the
+ * case type's schema before calling this, and reports a failure there.
+ */
+export declare const updateCaseState: (tx: Transaction, id: string, state: unknown, dormancy?: Dormancy | null) => Promise<CaseHandle<unknown>>;

package/dist/store/store.js

@@ -0,0 +1,108 @@
+import { FRAMEWORK_SCHEMA } from './bootstrap.js';
+import { CaseNotFoundError, CaseStateValidationError } from './errors.js';
+import { mintId } from './ids.js';
+const CASES = `${FRAMEWORK_SCHEMA}.cases`;
+const CASE_COLUMNS = 'id, case_type, state, seq, ended_at, created_at, updated_at';
+const toHandle = (row, state) => ({
+    id: row.id,
+    caseTypeName: row.case_type,
+    state,
+    // Number() is safe: seq counts executions of one human-paced case and will
+    // never approach 2^53.
+    seq: Number(row.seq),
+    endedAt: row.ended_at,
+    createdAt: row.created_at,
+    updatedAt: row.updated_at,
+});
+/**
+ * Validate a document against a state schema, loudly. The one implementation
+ * of "this document must satisfy this schema or the caller hears about it" —
+ * `resolve.ts` layers the case-type registry on top of it, and everything
+ * that validates a Case State goes through one of the two.
+ */
+export const validateAgainstSchema = async (schema, value, context) => {
+    const result = await schema['~standard'].validate(value);
+    if (result.issues)
+        throw new CaseStateValidationError(context, result.issues);
+    return result.value;
+};
+/**
+ * `createCase` against an explicit {@link Queryable} — the shared-transaction
+ * seam. State is stringified explicitly so array-rooted documents are stored
+ * as jsonb rather than misread as Postgres arrays.
+ */
+export const insertCase = async (db, caseTypeName, stateSchema, initialState) => {
+    const state = await validateAgainstSchema(stateSchema, initialState, 'initial state');
+    const id = mintId('case');
+    const { rows } = await db.query(`insert into ${CASES} (id, case_type, state)
+     values ($1, $2, $3::jsonb)
+     returning ${CASE_COLUMNS}`, [id, caseTypeName, JSON.stringify(state)]);
+    const row = rows[0];
+    if (!row)
+        throw new Error(`insert into ${CASES} returned no row`);
+    return toHandle(row, state);
+};
+/** `loadCase` against an explicit {@link Queryable} — the shared-transaction seam. */
+export const selectCase = async (db, id, stateSchema) => {
+    const handle = await selectCaseUntyped(db, id);
+    const state = await validateAgainstSchema(stateSchema, handle.state, 'stored state');
+    return { ...handle, state };
+};
+/**
+ * Load a Case by id with the stored state **unvalidated** (`unknown`).
+ *
+ * Additive export for the engine: the engine learns which state
+ * schema applies only *from* the loaded row — `case_type` names the
+ * registered case type — so it must read the row before it can validate.
+ * Every other caller should prefer {@link selectCase} / `loadCase`, which
+ * validate; whoever consumes this handle owns validating `state` against the
+ * type's schema before trusting it.
+ */
+export const selectCaseUntyped = async (db, id) => {
+    const { rows } = await db.query(`select ${CASE_COLUMNS} from ${CASES} where id = $1`, [id]);
+    const row = rows[0];
+    if (!row)
+        throw new CaseNotFoundError(id);
+    return toHandle(row, row.state);
+};
+/**
+ * Load a Case by id **for update** — `select … for update`, so the row lock is
+ * held until the calling transaction ends.
+ *
+ * This is the execution lifecycle's serialization point: the claim and the
+ * commit both take the case row's lock first, which is what makes the
+ * one-in-flight-execution check (and an expired claim's takeover) a decision
+ * no two transactions can make concurrently.
+ */
+export const selectCaseForUpdate = async (tx, id) => {
+    const { rows } = await tx.query(`select ${CASE_COLUMNS} from ${CASES} where id = $1 for update`, [id]);
+    const row = rows[0];
+    if (!row)
+        throw new CaseNotFoundError(id);
+    return toHandle(row, row.state);
+};
+/**
+ * Write the next Case State, bump `seq`, and apply the Execution's dormancy
+ * transition, if any: `'ended'` stamps `ended_at`, `'reopened'` clears it,
+ * `null` leaves it exactly as it was. The state document is **not** validated
+ * here — the execution lifecycle validates the handler's return against the
+ * case type's schema before calling this, and reports a failure there.
+ */
+export const updateCaseState = async (tx, id, state, dormancy = null) => {
+    const { rows } = await tx.query(`update ${CASES}
+     set state = $2::jsonb,
+         seq = seq + 1,
+         ended_at = case
+           when $3::text = 'ended' then now()
+           when $3::text = 'reopened' then null
+           else ended_at
+         end,
+         updated_at = now()
+     where id = $1
+     returning ${CASE_COLUMNS}`, [id, JSON.stringify(state), dormancy]);
+    const row = rows[0];
+    if (!row)
+        throw new CaseNotFoundError(id);
+    return toHandle(row, row.state);
+};
+//# sourceMappingURL=store.js.map

package/dist/store/store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../../src/store/store.ts"],"names":[],"mappings":"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","sourcesContent":["import type { StandardSchemaV1 } from '@standard-schema/spec'\nimport { FRAMEWORK_SCHEMA } from './bootstrap.js'\nimport { CaseNotFoundError, CaseStateValidationError } from './errors.js'\nimport { mintId } from './ids.js'\nimport type { Queryable, Transaction } from './queryable.js'\n\nconst CASES = `${FRAMEWORK_SCHEMA}.cases`\nconst CASE_COLUMNS =\n  'id, case_type, state, seq, ended_at, created_at, updated_at'\n\n/**\n * A typed handle to one Case as persisted: the materialized Case State plus\n * the row-level bookkeeping the engine builds on.\n */\nexport interface CaseHandle<State> {\n  /** Case id — a UUID generated by the store on creation. */\n  id: string\n  /** Name of the Case Type this case is an instance of. */\n  caseTypeName: string\n  /** The materialized Case State document, validated against the schema. */\n  state: State\n  /** Per-case monotonic sequence counter, 0 at creation, bumped by every committed Execution. */\n  seq: number\n  /** Dormancy marker set by `end()`; null while the case is active. */\n  endedAt: Date | null\n  createdAt: Date\n  updatedAt: Date\n}\n\n/** Row shape of `affordance.cases` (int8 arrives as text from the pg driver). */\ntype CaseRow = {\n  id: string\n  case_type: string\n  state: unknown\n  seq: string | number\n  ended_at: Date | null\n  created_at: Date\n  updated_at: Date\n}\n\nconst toHandle = <State>(row: CaseRow, state: State): CaseHandle<State> => ({\n  id: row.id,\n  caseTypeName: row.case_type,\n  state,\n  // Number() is safe: seq counts executions of one human-paced case and will\n  // never approach 2^53.\n  seq: Number(row.seq),\n  endedAt: row.ended_at,\n  createdAt: row.created_at,\n  updatedAt: row.updated_at,\n})\n\n/**\n * Validate a document against a state schema, loudly. The one implementation\n * of \"this document must satisfy this schema or the caller hears about it\" —\n * `resolve.ts` layers the case-type registry on top of it, and everything\n * that validates a Case State goes through one of the two.\n */\nexport const validateAgainstSchema = async <S extends StandardSchemaV1>(\n  schema: S,\n  value: unknown,\n  context: string,\n): Promise<StandardSchemaV1.InferOutput<S>> => {\n  const result = await schema['~standard'].validate(value)\n  if (result.issues) throw new CaseStateValidationError(context, result.issues)\n  return result.value as StandardSchemaV1.InferOutput<S>\n}\n\n/**\n * `createCase` against an explicit {@link Queryable} — the shared-transaction\n * seam. State is stringified explicitly so array-rooted documents are stored\n * as jsonb rather than misread as Postgres arrays.\n */\nexport const insertCase = async <S extends StandardSchemaV1>(\n  db: Queryable,\n  caseTypeName: string,\n  stateSchema: S,\n  initialState: StandardSchemaV1.InferInput<S>,\n): Promise<CaseHandle<StandardSchemaV1.InferOutput<S>>> => {\n  const state = await validateAgainstSchema(\n    stateSchema,\n    initialState,\n    'initial state',\n  )\n  const id = mintId('case')\n  const { rows } = await db.query<CaseRow>(\n    `insert into ${CASES} (id, case_type, state)\n     values ($1, $2, $3::jsonb)\n     returning ${CASE_COLUMNS}`,\n    [id, caseTypeName, JSON.stringify(state)],\n  )\n  const row = rows[0]\n  if (!row) throw new Error(`insert into ${CASES} returned no row`)\n  return toHandle(row, state)\n}\n\n/** `loadCase` against an explicit {@link Queryable} — the shared-transaction seam. */\nexport const selectCase = async <S extends StandardSchemaV1>(\n  db: Queryable,\n  id: string,\n  stateSchema: S,\n): Promise<CaseHandle<StandardSchemaV1.InferOutput<S>>> => {\n  const handle = await selectCaseUntyped(db, id)\n  const state = await validateAgainstSchema(\n    stateSchema,\n    handle.state,\n    'stored state',\n  )\n  return { ...handle, state }\n}\n\n/**\n * Load a Case by id with the stored state **unvalidated** (`unknown`).\n *\n * Additive export for the engine: the engine learns which state\n * schema applies only *from* the loaded row — `case_type` names the\n * registered case type — so it must read the row before it can validate.\n * Every other caller should prefer {@link selectCase} / `loadCase`, which\n * validate; whoever consumes this handle owns validating `state` against the\n * type's schema before trusting it.\n */\nexport const selectCaseUntyped = async (\n  db: Queryable,\n  id: string,\n): Promise<CaseHandle<unknown>> => {\n  const { rows } = await db.query<CaseRow>(\n    `select ${CASE_COLUMNS} from ${CASES} where id = $1`,\n    [id],\n  )\n  const row = rows[0]\n  if (!row) throw new CaseNotFoundError(id)\n  return toHandle(row, row.state)\n}\n\n/**\n * Load a Case by id **for update** — `select … for update`, so the row lock is\n * held until the calling transaction ends.\n *\n * This is the execution lifecycle's serialization point: the claim and the\n * commit both take the case row's lock first, which is what makes the\n * one-in-flight-execution check (and an expired claim's takeover) a decision\n * no two transactions can make concurrently.\n */\nexport const selectCaseForUpdate = async (\n  tx: Transaction,\n  id: string,\n): Promise<CaseHandle<unknown>> => {\n  const { rows } = await tx.query<CaseRow>(\n    `select ${CASE_COLUMNS} from ${CASES} where id = $1 for update`,\n    [id],\n  )\n  const row = rows[0]\n  if (!row) throw new CaseNotFoundError(id)\n  return toHandle(row, row.state)\n}\n\n/** The dormancy transition a committing Execution applies to the case row (`end()` / `reopen()`). */\nexport type Dormancy = 'ended' | 'reopened'\n\n/**\n * Write the next Case State, bump `seq`, and apply the Execution's dormancy\n * transition, if any: `'ended'` stamps `ended_at`, `'reopened'` clears it,\n * `null` leaves it exactly as it was. The state document is **not** validated\n * here — the execution lifecycle validates the handler's return against the\n * case type's schema before calling this, and reports a failure there.\n */\nexport const updateCaseState = async (\n  tx: Transaction,\n  id: string,\n  state: unknown,\n  dormancy: Dormancy | null = null,\n): Promise<CaseHandle<unknown>> => {\n  const { rows } = await tx.query<CaseRow>(\n    `update ${CASES}\n     set state = $2::jsonb,\n         seq = seq + 1,\n         ended_at = case\n           when $3::text = 'ended' then now()\n           when $3::text = 'reopened' then null\n           else ended_at\n         end,\n         updated_at = now()\n     where id = $1\n     returning ${CASE_COLUMNS}`,\n    [id, JSON.stringify(state), dormancy],\n  )\n  const row = rows[0]\n  if (!row) throw new CaseNotFoundError(id)\n  return toHandle(row, row.state)\n}\n"]}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@affordance/core",
+  "version": "0.1.0",
+  "author": "Mochicode LLC (https://mochicode.com)",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@standard-schema/spec": "^1.1.0",
+    "@types/pg": "^8.11.10",
+    "@affordance/contract": "0.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.",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22.12"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mochicodecom/affordance.git",
+    "directory": "packages/core"
+  },
+  "homepage": "https://github.com/mochicodecom/affordance#readme",
+  "bugs": {
+    "url": "https://github.com/mochicodecom/affordance/issues"
+  },
+  "keywords": [
+    "affordance",
+    "case-management",
+    "typescript",
+    "postgres"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "build": "node ../../scripts/build-package.mjs"
+  }
+}