@emilia-protocol/gate 0.11.0 → 0.13.0

package/src/reliance-kernel.ts

@@ -0,0 +1,119 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * EP-RELIANCE-KERNEL-v1 — runtime enforcement wrapper.
+ *
+ * The pure verdict lives in @emilia-protocol/verify/reliance (evaluateReliance).
+ * This is the deny-by-default RUNTIME point a relying party puts in front of a
+ * consequential action: it evaluates the evidence packet against the relying
+ * party's pinned EP-RELIANCE-PROFILE-v1, appends the decision to a tamper-evident
+ * evidence log, and — on anything other than `rely` — returns a machine-readable
+ * refusal (HTTP 428, the same Receipt-Required status the Gate uses) naming the
+ * closed verdict and what evidence was required.
+ *
+ * ALLOW iff verdict === 'rely'. Every other closed verdict, a thrown verifier,
+ * or a strict evidence-log failure denies. The kernel never re-derives a verdict
+ * of its own — it enforces the one the pure offline verifier computed.
+ */
+import { createEvidenceLog } from './evidence.js';
+import {
+  evaluateReliance,
+  RELIANCE_PROFILE_VERSION,
+  RELIANCE_VERDICTS,
+} from '@emilia-protocol/verify/reliance';
+
+type Obj = Record<string, any>;
+
+const RECEIPT_REQUIRED_STATUS = 428;
+
+export { RELIANCE_VERDICTS, RELIANCE_PROFILE_VERSION };
+
+/** Build the 428 refusal for a non-`rely` verdict. */
+function relianceChallenge(verdict, reasons, profile) {
+  return {
+    status: RECEIPT_REQUIRED_STATUS,
+    error: 'do_not_rely',
+    verdict,
+    reasons: Array.isArray(reasons) ? reasons : [],
+    required_assurance: profile?.required_assurance ?? null,
+    required_authority: profile?.required_authority === true,
+    required_evidence: Array.isArray(profile?.required_evidence) ? profile.required_evidence : [],
+    header: { name: 'Reliance-Refused', value: verdict },
+  };
+}
+
+/**
+ * Create a reliance kernel bound to one relying-party profile.
+ *
+ * @param {object} [cfg]
+ * @param {object} [cfg.profile]      the pinned EP-RELIANCE-PROFILE-v1
+ * @param {object} [cfg.log]          an evidence log (createEvidenceLog); one is created if absent
+ * @param {boolean} [cfg.strictEvidence=true]  fail closed if the evidence log sink fails
+ * @returns {{ check: Function, evidence: object }}
+ */
+export function createRelianceKernel({
+  profile,
+  log,
+  strictEvidence = true,
+}: { profile?: Obj; log?: Obj; strictEvidence?: boolean } = {}) {
+  const evidence = log || createEvidenceLog({ strict: strictEvidence });
+
+  /**
+   * Evaluate + enforce one evidence packet.
+   * @param {object} input  the evaluateReliance input MINUS relying_party_profile (bound here)
+   * @param {object} [opts] verifier options { approverKeys, logPublicKey, rpId, revokerKeys }
+   * @returns {Promise<{ allow:boolean, status:number, verdict:string, reasons:string[], checks:object, challenge:(object|null), decision:object }>}
+   */
+  async function check(input: Obj = {}, opts: Obj = {}) {
+    let result;
+    try {
+      result = evaluateReliance({ ...input, relying_party_profile: profile }, opts);
+    } catch (err) {
+      // A thrown verifier is not a maybe — it is a refusal.
+      result = { verdict: 'do_not_rely_unsigned', rely: false, reasons: [`verifier_error:${(err as { message?: string })?.message || 'threw'}`], checks: {} };
+    }
+
+    const allow = result.verdict === 'rely';
+    const actionHash = input?.action?.action_hash ?? input?.receipt?.action_hash ?? null;
+
+    // Deny-by-default: record the decision to the tamper-evident log first. In
+    // strict mode a log-sink failure THROWS, which we convert to a refusal — an
+    // action whose decision cannot be durably recorded must not proceed.
+    let decision;
+    try {
+      decision = await evidence.record({
+        type: 'reliance.decision',
+        verdict: result.verdict,
+        allow,
+        action_hash: actionHash,
+        reasons: result.reasons,
+        checks: result.checks,
+        profile: result.profile ?? null,
+      });
+    } catch (err) {
+      return {
+        allow: false,
+        status: RECEIPT_REQUIRED_STATUS,
+        verdict: 'do_not_rely_unsigned',
+        reasons: [`evidence_log_failed:${(err as { message?: string })?.message || 'sink'}`],
+        checks: result.checks || {},
+        challenge: relianceChallenge('do_not_rely_unsigned', ['evidence_log_failed'], profile),
+        decision: null,
+      };
+    }
+
+    return {
+      allow,
+      status: allow ? 200 : RECEIPT_REQUIRED_STATUS,
+      verdict: result.verdict,
+      reasons: result.reasons,
+      checks: result.checks,
+      challenge: allow ? null : relianceChallenge(result.verdict, result.reasons, profile),
+      decision,
+    };
+  }
+
+  return { check, evidence };
+}
+
+const relianceKernelApi = { createRelianceKernel };
+export default relianceKernelApi;

package/src/reliance-packet.ts

@@ -0,0 +1,206 @@
+// SPDX-License-Identifier: Apache-2.0
+// Auditor / insurer-facing reliance packet for an EMILIA Gate decision.
+
+export const RELIANCE_PACKET_VERSION = 'EP-GATE-RELIANCE-PACKET-v1';
+
+// The CLOSED admissibility verdict set (mirror of lib/evidence/admissibility.js
+// ADMISSIBILITY_VERDICTS). The gate does NOT import that app module — it stays a
+// dependency-light published package — so the closed set is restated here as a
+// value contract. 'admissible' is the ONLY verdict that reads as success; every
+// other member, and anything not in this set, fails closed. Precedence lives in
+// the evaluator; the gate never re-derives a verdict, it only checks the one the
+// relying party's offline evaluator already computed.
+export const ADMISSIBILITY_VERDICTS = Object.freeze([
+  'admissible', 'missing_evidence', 'stale', 'conflicted', 'unverifiable',
+]);
+
+type Obj = Record<string, any>;
+
+/**
+ * Normalize an admissibility block onto the packet. FAIL CLOSED: a missing block,
+ * a missing/unrecognized verdict, or a non-'admissible' verdict all produce
+ * admissible:false. The block is only carried when the caller supplies one; when
+ * absent, `admissibility` is null and no admissibility gating applies (backwards
+ * compatible with pre-profile packets).
+ *
+ * @param {object|null} adm  the relying-party evaluator's result, carrying
+ *   { admissibility_profile:{id,version}, profile_hash, verdict, replay_digest, challenge_id?, challenge_digest? }
+ */
+function normalizeAdmissibility(adm: Obj | null) {
+  if (!adm || typeof adm !== 'object') return null;
+  const verdict = typeof adm.verdict === 'string' ? adm.verdict : null;
+  const recognized = verdict !== null && ADMISSIBILITY_VERDICTS.includes(verdict);
+  // Only a recognized 'admissible' verdict reads as success. Missing, malformed,
+  // or any other closed-set member (missing_evidence/stale/conflicted/unverifiable)
+  // is non-admissible.
+  const admissible = recognized && verdict === 'admissible';
+  const profile = adm.admissibility_profile && typeof adm.admissibility_profile === 'object'
+    ? { id: adm.admissibility_profile.id ?? null, version: adm.admissibility_profile.version ?? null }
+    : null;
+  return {
+    admissibility_profile: profile,
+    profile_hash: typeof adm.profile_hash === 'string' ? adm.profile_hash : null,
+    verdict: verdict, // preserved verbatim (including null / unrecognized) for the auditor
+    verdict_recognized: recognized,
+    admissible,
+    replay_digest: typeof adm.replay_digest === 'string' ? adm.replay_digest : null,
+    // The evidence-challenge loop (lib/negotiate/evidence-challenge.js) keys each
+    // round by challenge_id; challenge_digest is carried through when the caller
+    // hashes the challenge. Either identifies which challenge round this verdict
+    // answers. Both null-safe.
+    challenge_id: adm.challenge_id ?? null,
+    challenge_digest: typeof adm.challenge_digest === 'string' ? adm.challenge_digest : null,
+  };
+}
+
+async function evidenceStatus(evidence) {
+  if (!evidence) {
+    return { ok: false, length: null, head: null, reason: 'evidence_verification_unavailable' };
+  }
+  try {
+    const status = typeof evidence.verify === 'function'
+      ? await evidence.verify()
+      : await evidence;
+    if (!status || typeof status !== 'object' || Array.isArray(status)) {
+      return { ok: false, length: null, head: null, reason: 'evidence_verification_malformed' };
+    }
+    if (status.ok !== true) {
+      return {
+        ok: false,
+        length: Number.isSafeInteger(status.length) ? status.length : null,
+        head: typeof status.head === 'string' ? status.head : null,
+        reason: status.reason || 'evidence_verification_rejected',
+      };
+    }
+    return {
+      ...status,
+      ok: true,
+      length: Number.isSafeInteger(status.length) ? status.length : null,
+      head: typeof status.head === 'string' ? status.head : null,
+    };
+  } catch {
+    return { ok: false, length: null, head: null, reason: 'evidence_verification_failed' };
+  }
+}
+
+/**
+ * Generic check-result builder. `detail` is an opaque payload — sometimes a
+ * plain string reason, sometimes a structured object — carried through
+ * verbatim for the auditor. Its real type varies per call site; annotate it
+ * as `*` rather than over-constraining it to the `null` the default value
+ * would otherwise narrow it to.
+ * @param {string} id
+ * @param {boolean|null} ok
+ * @param {*} [detail]
+ */
+function check(id, ok, detail: string | Obj | null = null) {
+  return { id, ok, ...(detail ? { detail } : {}) };
+}
+
+/**
+ * @param {{ decision?: any, execution?: any, evidence?: any, manifest?: any, binding?: any, admissibility?: any, verifier?: string }} [o]
+ */
+export async function buildReliancePacket({
+  decision,
+  execution = null,
+  evidence = null,
+  manifest = null,
+  binding = null,
+  admissibility = null,
+  verifier = '@emilia-protocol/gate',
+}: {
+  decision?: Obj | null;
+  execution?: Obj | null;
+  evidence?: Obj | null;
+  manifest?: Obj | null;
+  binding?: Obj | null;
+  admissibility?: Obj | null;
+  verifier?: string;
+} = {}) {
+  const evidenceCheck = await evidenceStatus(evidence);
+  const decisionHash = decision?.evidence?.hash || decision?.hash || null;
+  const executionBound = Boolean(
+    execution
+    && execution.kind === 'execution'
+    && decisionHash
+    && execution.authorizes_decision === decisionHash,
+  );
+  // Prefer the binding carried by the execution proof. Authorization-time
+  // binding alone is not enough: an executor could otherwise attest a
+  // different mutation and still receive a rely verdict.
+  const bindingCheck = execution?.execution_binding
+    || binding
+    || decision?.evidence?.execution_binding
+    || decision?.execution_binding
+    || null;
+  const allowed = decision?.allow === true;
+  const evidenceOk = evidenceCheck.ok === true;
+  const bindingOk = bindingCheck ? bindingCheck.ok === true : true;
+
+  // Admissibility block (relying-party evaluator output, computed OFFLINE against
+  // its PINNED profile — never re-derived here). When present it is an additional
+  // gate on 'rely': a non-'admissible' verdict (or a missing/unrecognized one)
+  // fails closed. When absent, admissibility does not affect the verdict.
+  const adm = normalizeAdmissibility(admissibility);
+  const admissibilityOk = adm === null ? true : adm.admissible === true;
+
+  const verdict = allowed && executionBound && evidenceOk && bindingOk && admissibilityOk ? 'rely' : 'do_not_rely';
+
+  return {
+    '@version': RELIANCE_PACKET_VERSION,
+    product: 'EMILIA Gate',
+    verifier,
+    verdict,
+    summary: {
+      action: decision?.action || null,
+      receipt_id: decision?.evidence?.receipt_id || decision?.receipt_id || null,
+      subject: decision?.evidence?.subject || null,
+      policy_id: decision?.evidence?.evaluated_policy_id || null,
+      policy_hash: decision?.evidence?.evaluated_policy_hash || null,
+      tenant_id: decision?.evidence?.evaluated_tenant_id || null,
+      approvers: decision?.evidence?.evaluated_approvers || [],
+      required_tier: decision?.evidence?.required_tier || decision?.required_tier || null,
+      observed_tier: decision?.evidence?.have_tier || decision?.have_tier || null,
+      decision_hash: decisionHash,
+      execution_hash: execution?.hash || null,
+      evidence_head: evidenceCheck.head || null,
+      // Surface the admissibility verdict + pinned profile in the summary so an
+      // auditor sees WHICH bar was cleared without digging into checks. Null when
+      // no admissibility block was supplied.
+      admissibility_verdict: adm ? adm.verdict : null,
+      admissibility_profile: adm ? adm.admissibility_profile : null,
+      admissibility_profile_hash: adm ? adm.profile_hash : null,
+    },
+    // Full admissibility block (or null). The auditor / gate can re-check
+    // {profile_hash, verdict, replay_digest} against the profile the relying party
+    // pinned. Carried verbatim, fail-closed by construction (see normalizeAdmissibility).
+    admissibility: adm,
+    checks: [
+      check('receipt_present_and_valid', allowed && !String(decision?.reason || '').startsWith('receipt_rejected'), decision?.reason || null),
+      check('assurance_sufficient', allowed || decision?.reason !== 'assurance_too_low', decision?.reason === 'assurance_too_low' ? 'receipt tier below action requirement' : null),
+      check('receipt_one_time_consumed', allowed || decision?.reason === 'replay_refused' ? decision?.reason !== 'replay_refused' : null),
+      check('execution_fields_bound', bindingCheck ? bindingCheck.ok === true : null, bindingCheck ? { missing_observed_fields: bindingCheck.missing_observed_fields || [], mismatched_fields: bindingCheck.mismatched_fields || [] } : 'no material execution-field binding required by this action'),
+      check('execution_attests_decision', executionBound, execution ? null : 'no execution record supplied'),
+      check('evidence_log_intact', evidenceCheck.ok === true, evidenceCheck.reason || null),
+      // Admissibility verdict against the relying party's PINNED profile. null when
+      // no profile/verdict was supplied (this reliance did not gate on admissibility);
+      // true only for a recognized 'admissible' verdict; false otherwise (fail closed).
+      check(
+        'admissibility_verdict_admissible',
+        adm === null ? null : adm.admissible === true,
+        adm === null
+          ? 'no admissibility profile / verdict supplied for this reliance'
+          : { verdict: adm.verdict, verdict_recognized: adm.verdict_recognized, profile: adm.admissibility_profile, profile_hash: adm.profile_hash, replay_digest: adm.replay_digest },
+      ),
+    ],
+    manifest_version: manifest?.['@version'] || null,
+    limitations: [
+      'The packet proves the gate verified a receipt and enforced its configured policy; it does not prove the human made a wise decision.',
+      'Identity, authority enrollment, and key custody remain external trust roots that must be operated correctly.',
+      'For execution-field binding, observedAction must come from the system of record, not from attacker-controlled request input.',
+      'An admissible verdict means the evidence bundle cleared the bar THIS relying party pinned; it does not establish the action is correct, safe, or currently valid beyond the freshness bounds evaluated. The verdict is computed OFFLINE by the relying party against its own pinned profile — EMILIA neither hosts the authoritative registry nor adjudicates.',
+    ],
+  };
+}
+
+export default { RELIANCE_PACKET_VERSION, ADMISSIBILITY_VERDICTS, buildReliancePacket };

package/src/remedy-program-postgres.ts

@@ -0,0 +1,367 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Durable, tenant-aware PostgreSQL CAS store for the Remedy Program kernel.
+ *
+ * Tables are never addressed directly. Each operation calls one service-role
+ * RPC on one pinned pg client inside an explicit transaction. Logical refusals
+ * have stable reasons; malformed rows, connection failures, and uncertain
+ * commit outcomes throw so callers cannot mistake ambiguity for success.
+ */
+import { createHash } from 'node:crypto';
+import { canonicalize } from '../execution-binding.js';
+import type {
+  RemedyProgramResult,
+  RemedyProgramState,
+  RemedyProgramStore,
+} from './remedy-program.js';
+
+export const REMEDY_PROGRAM_PG_STORE_VERSION = 'EP-GATE-REMEDY-PROGRAM-PG-STORE-v1';
+export const REMEDY_PROGRAM_MAX_STATE_BYTES = 4 * 1024 * 1024;
+export const REMEDY_PROGRAM_MAX_FORWARD_SKEW_MINUTES = 5;
+
+const INSTANCE_ID = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,255}$/;
+const DIGEST = /^sha256:[0-9a-f]{64}$/;
+const STRICT_INSTANT = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,9})?Z$/;
+const ENVELOPE_KEYS = new Set([
+  'ok', 'reason', 'tenant_id', 'instance_id', 'revision',
+  'state_json', 'state_digest', 'recorded_at',
+]);
+
+type RecordLike = Record<string, any>;
+type QueryResult = { rowCount: number | null; rows?: any[] };
+type PgClient = {
+  query: (text: string, params?: any[]) => Promise<QueryResult>;
+  release: () => void;
+};
+type PgPool = { connect: () => Promise<PgClient> };
+
+export const REMEDY_PROGRAM_POSTGRES_SQL = Object.freeze({
+  create: `SELECT ok, reason, tenant_id, instance_id, revision, state_json, state_digest, recorded_at
+FROM remedy_program_private.remedy_program_create(
+  $1::text, $2::text, $3::text, $4::text, $5::text
+)`,
+  get: `SELECT ok, reason, tenant_id, instance_id, revision, state_json, state_digest, recorded_at
+FROM remedy_program_private.remedy_program_get($1::text, $2::text)`,
+  compareAndSwap: `SELECT ok, reason, tenant_id, instance_id, revision, state_json, state_digest, recorded_at
+FROM remedy_program_private.remedy_program_compare_and_swap(
+  $1::text, $2::text, $3::bigint, $4::bigint, $5::text, $6::text, $7::text
+)`,
+});
+
+function isRecord(value: unknown): value is RecordLike {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+
+function exactKeys(value: RecordLike, expected: ReadonlySet<string>) {
+  const keys = Reflect.ownKeys(value);
+  return keys.length === expected.size
+    && keys.every((key) => typeof key === 'string' && expected.has(key));
+}
+
+function fail(reason: string): RemedyProgramResult {
+  return { ok: false, reason };
+}
+
+function assertTenantId(value: unknown): asserts value is string {
+  if (typeof value !== 'string'
+      || Buffer.byteLength(value, 'utf8') < 1
+      || Buffer.byteLength(value, 'utf8') > 512
+      || /[\u0000-\u001f\u007f]/.test(value)) {
+    throw new TypeError('remedy-program tenantId is invalid');
+  }
+}
+
+function assertInstanceId(value: unknown): asserts value is string {
+  if (typeof value !== 'string' || !INSTANCE_ID.test(value)) {
+    throw new TypeError('remedy-program instanceId is invalid');
+  }
+}
+
+function assertRevision(value: unknown, label: string): asserts value is number {
+  if (!Number.isSafeInteger(value) || (value as number) < 0) {
+    throw new TypeError(`remedy-program ${label} revision is invalid`);
+  }
+}
+
+function stateDigest(stateJson: string) {
+  return `sha256:${createHash('sha256').update(stateJson, 'utf8').digest('hex')}`;
+}
+
+function stateEventAt(state: RecordLike) {
+  const value = state.updated_at;
+  if (typeof value !== 'string'
+      || !STRICT_INSTANT.test(value)
+      || !Number.isFinite(Date.parse(value))) {
+    throw new TypeError('remedy-program state updated_at is invalid');
+  }
+  return value;
+}
+
+function encodeState(
+  state: unknown,
+  tenantId: string,
+  instanceId: string,
+  revision: number,
+) {
+  if (!isRecord(state)
+      || state.tenant_id !== tenantId
+      || state.instance_id !== instanceId
+      || state.revision !== revision) {
+    throw new TypeError('remedy-program state binding does not match the store operation');
+  }
+  let stateJson: string;
+  try {
+    stateJson = canonicalize(state);
+  } catch {
+    throw new TypeError('remedy-program state must be canonical JSON');
+  }
+  if (Buffer.byteLength(stateJson, 'utf8') > REMEDY_PROGRAM_MAX_STATE_BYTES) {
+    throw new TypeError('remedy-program state exceeds the durable store limit');
+  }
+  return {
+    stateJson,
+    stateDigest: stateDigest(stateJson),
+    eventAt: stateEventAt(state),
+  };
+}
+
+function safeRevision(value: unknown) {
+  const revision = typeof value === 'string' && /^(?:0|[1-9]\d*)$/.test(value)
+    ? Number(value)
+    : value;
+  if (!Number.isSafeInteger(revision) || (revision as number) < 0) {
+    throw new Error('remedy-program Postgres returned an invalid revision');
+  }
+  return revision as number;
+}
+
+function assertRecordedAt(value: unknown) {
+  if (typeof value !== 'string'
+      || !STRICT_INSTANT.test(value)
+      || !Number.isFinite(Date.parse(value))) {
+    throw new Error('remedy-program Postgres returned an invalid recorded_at');
+  }
+}
+
+function decodeState(
+  row: RecordLike,
+  expectedTenantId: string,
+  expectedInstanceId: string,
+  expectedRevision?: number,
+) {
+  if (row.tenant_id !== expectedTenantId
+      || row.instance_id !== expectedInstanceId
+      || typeof row.state_json !== 'string'
+      || typeof row.state_digest !== 'string'
+      || !DIGEST.test(row.state_digest)
+      || Buffer.byteLength(row.state_json, 'utf8') > REMEDY_PROGRAM_MAX_STATE_BYTES
+      || row.state_digest !== stateDigest(row.state_json)) {
+    throw new Error('remedy-program Postgres returned an invalid state envelope');
+  }
+  assertRecordedAt(row.recorded_at);
+  const revision = safeRevision(row.revision);
+  if (expectedRevision !== undefined && revision !== expectedRevision) {
+    throw new Error('remedy-program Postgres returned an unexpected revision');
+  }
+
+  let state: unknown;
+  try {
+    state = JSON.parse(row.state_json);
+    if (!isRecord(state)
+        || canonicalize(state) !== row.state_json
+        || state.tenant_id !== expectedTenantId
+        || state.instance_id !== expectedInstanceId
+        || state.revision !== revision) {
+      throw new Error('state binding mismatch');
+    }
+    stateEventAt(state);
+  } catch {
+    throw new Error('remedy-program Postgres returned non-canonical state');
+  }
+  return state as RemedyProgramState;
+}
+
+function definitiveRow(
+  result: QueryResult,
+  operation: string,
+  tenantId: string,
+  instanceId: string,
+  allowedReasons: ReadonlySet<string>,
+  expectedRevision?: number,
+): RemedyProgramResult {
+  if (!result || result.rowCount !== 1 || !Array.isArray(result.rows) || result.rows.length !== 1) {
+    throw new Error(`remedy-program ${operation} outcome is ambiguous`);
+  }
+  const row = result.rows[0];
+  if (!isRecord(row) || !exactKeys(row, ENVELOPE_KEYS) || typeof row.ok !== 'boolean') {
+    throw new Error(`remedy-program ${operation} outcome is malformed`);
+  }
+  if (row.tenant_id !== tenantId || row.instance_id !== instanceId) {
+    throw new Error(`remedy-program ${operation} Postgres returned a mismatched identity`);
+  }
+  if (!row.ok) {
+    if (typeof row.reason !== 'string'
+        || !allowedReasons.has(row.reason)
+        || row.revision !== null
+        || row.state_json !== null
+        || row.state_digest !== null
+        || row.recorded_at !== null) {
+      throw new Error(`remedy-program ${operation} refusal is unrecognized`);
+    }
+    return fail(row.reason);
+  }
+  if (row.reason !== null) {
+    throw new Error(`remedy-program ${operation} success carried a refusal reason`);
+  }
+  return {
+    ok: true,
+    state: decodeState(row, tenantId, instanceId, expectedRevision),
+  };
+}
+
+function lookupInput(value: unknown) {
+  if (!isRecord(value)
+      || Reflect.ownKeys(value).length !== 2
+      || !Object.hasOwn(value, 'tenantId')
+      || !Object.hasOwn(value, 'instanceId')) {
+    throw new TypeError('remedy-program lookup input is invalid');
+  }
+  assertTenantId(value.tenantId);
+  assertInstanceId(value.instanceId);
+  return { tenantId: value.tenantId, instanceId: value.instanceId };
+}
+
+/** Build the exact durable store consumed by createRemedyProgramKernel(). */
+export function createRemedyProgramPostgresStore(
+  { pool }: { pool?: PgPool } = {},
+): RemedyProgramStore {
+  if (!pool || typeof pool.connect !== 'function') {
+    throw new TypeError(
+      'createRemedyProgramPostgresStore requires a transaction-capable pg pool',
+    );
+  }
+
+  async function transaction<T>(readOnly: boolean, work: (client: PgClient) => Promise<T>) {
+    const client = await pool!.connect();
+    if (!client || typeof client.query !== 'function' || typeof client.release !== 'function') {
+      throw new TypeError('remedy-program pg pool returned an invalid client');
+    }
+    let began = false;
+    try {
+      await client.query(readOnly
+        ? 'BEGIN ISOLATION LEVEL REPEATABLE READ READ ONLY'
+        : 'BEGIN ISOLATION LEVEL READ COMMITTED READ WRITE');
+      began = true;
+      const value = await work(client);
+      await client.query('COMMIT');
+      began = false;
+      return value;
+    } catch (error) {
+      if (began) {
+        try {
+          await client.query('ROLLBACK');
+        } catch (rollbackError) {
+          throw new AggregateError(
+            [error, rollbackError],
+            'remedy-program transaction and rollback both failed',
+          );
+        }
+      }
+      throw error;
+    } finally {
+      client.release();
+    }
+  }
+
+  return Object.freeze({
+    durable: true,
+    async create(state: RemedyProgramState) {
+      const tenantId = (state as RecordLike)?.tenant_id;
+      const instanceId = (state as RecordLike)?.instance_id;
+      assertTenantId(tenantId);
+      assertInstanceId(instanceId);
+      const encoded = encodeState(state, tenantId, instanceId, 0);
+      return transaction(false, async (client) => definitiveRow(
+        await client.query(REMEDY_PROGRAM_POSTGRES_SQL.create, [
+          tenantId,
+          instanceId,
+          encoded.stateJson,
+          encoded.stateDigest,
+          encoded.eventAt,
+        ]),
+        'create',
+        tenantId,
+        instanceId,
+        new Set([
+          'instance_exists', 'clock_forward_skew',
+          'evidence_replayed', 'remedy_operation_replayed',
+        ]),
+        0,
+      ));
+    },
+    async get(input: { tenantId: string; instanceId: string }) {
+      const { tenantId, instanceId } = lookupInput(input);
+      return transaction(true, async (client) => definitiveRow(
+        await client.query(REMEDY_PROGRAM_POSTGRES_SQL.get, [tenantId, instanceId]),
+        'get',
+        tenantId,
+        instanceId,
+        new Set(['instance_not_found']),
+      ));
+    },
+    async compareAndSwap(input: {
+      tenantId: string;
+      instanceId: string;
+      expectedRevision: number;
+      state: RemedyProgramState;
+    }) {
+      if (!isRecord(input)
+          || Reflect.ownKeys(input).length !== 4
+          || !Object.hasOwn(input, 'tenantId')
+          || !Object.hasOwn(input, 'instanceId')
+          || !Object.hasOwn(input, 'expectedRevision')
+          || !Object.hasOwn(input, 'state')) {
+        throw new TypeError('remedy-program compareAndSwap input is invalid');
+      }
+      const { tenantId, instanceId, expectedRevision, state } = input;
+      assertTenantId(tenantId);
+      assertInstanceId(instanceId);
+      assertRevision(expectedRevision, 'expected');
+      const nextRevision = expectedRevision + 1;
+      if (!Number.isSafeInteger(nextRevision)) {
+        throw new TypeError('remedy-program next revision is invalid');
+      }
+      const encoded = encodeState(state, tenantId, instanceId, nextRevision);
+      return transaction(false, async (client) => definitiveRow(
+        await client.query(REMEDY_PROGRAM_POSTGRES_SQL.compareAndSwap, [
+          tenantId,
+          instanceId,
+          expectedRevision,
+          nextRevision,
+          encoded.stateJson,
+          encoded.stateDigest,
+          encoded.eventAt,
+        ]),
+        'compareAndSwap',
+        tenantId,
+        instanceId,
+        new Set([
+          'instance_not_found', 'revision_conflict',
+          'clock_regression', 'clock_forward_skew',
+          'evidence_replayed', 'remedy_operation_replayed',
+        ]),
+        nextRevision,
+      ));
+    },
+  });
+}
+
+export default {
+  REMEDY_PROGRAM_PG_STORE_VERSION,
+  REMEDY_PROGRAM_MAX_STATE_BYTES,
+  REMEDY_PROGRAM_MAX_FORWARD_SKEW_MINUTES,
+  REMEDY_PROGRAM_POSTGRES_SQL,
+  createRemedyProgramPostgresStore,
+};