@emilia-protocol/gate 0.9.3 → 0.9.5

package/reports/assurance-package.js

@@ -0,0 +1,287 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * EP-ASSURANCE-PACKAGE-v1 — the reliance assurance layer.
+ *
+ * The layer above the reliance kernel. The kernel answers "may this party rely on
+ * this action?" The assurance package answers the question an INDEPENDENT assurer
+ * (an audit firm, a regulator, an insurer) asks: "can I reproduce, test, and
+ * attest that an organization's automated actions were governed by admissible
+ * evidence under the organization's OWN pinned rule?"
+ *
+ * Two halves, mirroring the re-performance discipline of reperform.js:
+ *   buildAssurancePackage(decisions, ...)      the organization bundles its
+ *      automated decisions + the evidence each relied on into ONE portable,
+ *      content-addressed package (action, receipt, profile, authority proof,
+ *      revocation check, consumption, denial/exception history, policy hash).
+ *   reperformAssurancePackage(pkg, ...)         the assurer RE-PERFORMS every
+ *      reliance verdict offline from that evidence, TRUSTING NOTHING the package
+ *      asserts: it recomputes each verdict with evaluateReliance, compares to the
+ *      verdict the org's runtime CLAIMED (drift = a control failure the assurer
+ *      caught), maps every verdict to a control objective, and emits an
+ *      auditor-style workpaper. It does not conclude; the assurer concludes.
+ *
+ * PCAOB AS 1105 alignment (why this is audit evidence): the source is
+ * cryptographic, the decision trail is immutable and content-addressed, the rule
+ * is a pinned profile, and the verdict is re-performable directly. This module
+ * SUPPORTS a re-performance procedure; it never issues an opinion.
+ */
+import { hashCanonical } from '../execution-binding.js';
+
+export const ASSURANCE_PACKAGE_VERSION = 'EP-ASSURANCE-PACKAGE-v1';
+export const ASSURANCE_REPERFORMANCE_VERSION = 'EP-ASSURANCE-REPERFORMANCE-v1';
+
+// Cross-package resolution, same pattern the Gate uses: the pure offline reliance
+// verifier. No DB, no network.
+const { evaluateReliance, RELIANCE_VERDICTS } = await import('@emilia-protocol/verify/reliance')
+  .catch(() => import('../../verify/reliance.js'));
+
+export { RELIANCE_VERDICTS };
+
+/**
+ * The reliance control catalog: every reliance verdict maps to the control
+ * objective it exercises. A `rely` shows the control PASSING; every do_not_rely_*
+ * shows the control OPERATING (it refused a non-admissible action). Denials are
+ * the control working, not the control failing.
+ */
+export const RELIANCE_CONTROL_CATALOG = Object.freeze({
+  'RC-1': { objective: 'Only a human with valid organization-bound, scoped authority for THIS exact action may authorize it', verdicts: ['do_not_rely_authority_missing', 'do_not_rely_authority_subject_mismatch', 'do_not_rely_authority_organization_mismatch', 'do_not_rely_authority_revoked', 'do_not_rely_authority_expired', 'do_not_rely_scope_mismatch', 'do_not_rely_amount_exceeded', 'do_not_rely_registry_unavailable'] },
+  'RC-2': { objective: 'Authorization uses a device-bound named-human ceremony (Class-A or quorum)', verdicts: ['do_not_rely_no_class_a', 'do_not_rely_quorum_unsatisfied'] },
+  'RC-3': { objective: 'The action conforms to a pinned, accepted policy', verdicts: ['do_not_rely_policy_mismatch'] },
+  'RC-4': { objective: 'Authorization is consumed exactly once (no replay)', verdicts: ['do_not_rely_already_consumed'] },
+  'RC-5': { objective: 'Reliance is evaluated against fresh revocation state', verdicts: ['do_not_rely_stale_revocation'] },
+  'RC-6': { objective: 'Evidence is signed by a trusted issuer and evaluated under a pinned rule', verdicts: ['do_not_rely_unsigned', 'do_not_rely_untrusted_issuer', 'do_not_rely_no_profile'] },
+});
+
+const VERDICT_TO_CONTROL = Object.freeze(
+  Object.entries(RELIANCE_CONTROL_CATALOG).reduce((m, [cid, c]) => {
+    for (const v of c.verdicts) m[v] = cid;
+    return m;
+  }, {}),
+);
+
+/** Which control objective a verdict exercises (rely passes ALL, so returns null). */
+function controlForVerdict(verdict) {
+  if (verdict === 'rely') return null;
+  return VERDICT_TO_CONTROL[verdict] || null;
+}
+
+function toIso(now) {
+  const ms = typeof now === 'function' ? now() : now;
+  return new Date(ms == null ? 0 : ms).toISOString();
+}
+
+/**
+ * Bundle N automated reliance decisions + the evidence each relied on into one
+ * portable, content-addressed assurance package. Does NOT re-perform (that is the
+ * assurer's independent step); it packages faithfully, including the verdict the
+ * org's runtime CLAIMED, so drift is checkable later.
+ *
+ * @param {Array<object>} decisions  each: { decision_id, action, receipt, quorum?,
+ *   authority_proof?, revocation_state?, consumption?, stated_verdict? }
+ * @param {object} opts
+ * @param {object} opts.profile       the pinned EP-RELIANCE-PROFILE-v1 the org operated under
+ * @param {object} [opts.organization] { id, name } (no PHI)
+ * @param {number|function} [opts.now]
+ * @returns {object} EP-ASSURANCE-PACKAGE-v1
+ */
+export function buildAssurancePackage(decisions = [], { profile, organization = null, now = 0 } = {}) {
+  if (!Array.isArray(decisions)) throw new Error('assurance-package: decisions must be an array');
+  const items = decisions.map((d, i) => {
+    const decision_id = d?.decision_id ?? `decision-${i}`;
+    return {
+      decision_id,
+      action: d?.action ?? null,
+      policy_hash: d?.action?.policy_hash ?? null,
+      stated_verdict: typeof d?.stated_verdict === 'string' ? d.stated_verdict : null,
+      evidence: {
+        receipt: d?.receipt ?? null,
+        quorum: d?.quorum ?? null,
+        authority_proof: d?.authority_proof ?? null,
+        revocation_state: d?.revocation_state ?? null,
+        consumption: d?.consumption ?? null,
+      },
+    };
+  });
+  // Denial/exception history = the decisions the org itself recorded as refused.
+  const exceptions = items.filter((it) => it.stated_verdict && it.stated_verdict !== 'rely')
+    .map((it) => ({ decision_id: it.decision_id, stated_verdict: it.stated_verdict, control_id: controlForVerdict(it.stated_verdict) }));
+
+  const body = {
+    '@version': ASSURANCE_PACKAGE_VERSION,
+    organization,
+    reliance_profile: profile ?? null,
+    profile_hash: profile ? hashCanonical(profile) : null,
+    control_catalog: RELIANCE_CONTROL_CATALOG,
+    decisions: items,
+    exception_history: exceptions,
+    counts: {
+      decisions: items.length,
+      stated_admissible: items.filter((it) => it.stated_verdict === 'rely').length,
+      stated_refused: items.filter((it) => it.stated_verdict && it.stated_verdict !== 'rely').length,
+      stated_unknown: items.filter((it) => !it.stated_verdict).length,
+    },
+    assembled_at: toIso(now),
+  };
+  // Content address over everything EXCEPT the timestamp (so the same evidence
+  // yields the same digest regardless of when it was packaged).
+  const { assembled_at: _t, ...digestScope } = body;
+  return { ...body, package_digest: hashCanonical(digestScope) };
+}
+
+/**
+ * INDEPENDENT re-performance. Recompute every reliance verdict offline from the
+ * packaged evidence under the package's pinned profile and AUDITOR-supplied keys,
+ * trusting nothing the package asserts. Detect drift (recomputed ≠ stated), map
+ * to control objectives, and emit an auditor-style workpaper. Conclusion fields
+ * are ALWAYS null: the assurer concludes, not this tool.
+ *
+ * @param {object} pkg  an EP-ASSURANCE-PACKAGE-v1
+ * @param {object} opts
+ * @param {object} [opts.approverKeys]  auditor-pinned approver keys (out of band)
+ * @param {string} [opts.logPublicKey]  auditor-pinned transparency-log key
+ * @param {string} [opts.rpId]
+ * @param {object} [opts.revokerKeys]
+ * @param {(key:object)=>boolean} [opts.isConsumed] auditor-owned consumption lookup
+ * @param {number|string|Date} [opts.now]  reliance-evaluation clock (pin for determinism)
+ * @returns {object} EP-ASSURANCE-REPERFORMANCE-v1
+ */
+export function reperformAssurancePackage(pkg, { approverKeys = {}, logPublicKey = null, rpId = null, revokerKeys = {}, isConsumed, now = 0 } = {}) {
+  if (!pkg || pkg['@version'] !== ASSURANCE_PACKAGE_VERSION) throw new Error('assurance-reperform: not an EP-ASSURANCE-PACKAGE-v1');
+  const profile = pkg.reliance_profile;
+  const evalOpts = { approverKeys, logPublicKey, rpId, revokerKeys, ...(typeof isConsumed === 'function' ? { isConsumed } : {}) };
+  const relianceNow = typeof now === 'function' ? now() : now;
+
+  const results = (Array.isArray(pkg.decisions) ? pkg.decisions : []).map((it) => {
+    const ev = it.evidence || {};
+    const input = {
+      action: it.action || {},
+      receipt: ev.receipt,
+      quorum: ev.quorum || undefined,
+      authority_proof: ev.authority_proof || undefined,
+      revocation_state: ev.revocation_state || undefined,
+      consumption: ev.consumption || undefined,
+      relying_party_profile: profile,
+      now: relianceNow,
+    };
+    let recomputed;
+    try {
+      recomputed = evaluateReliance(input, evalOpts);
+    } catch (err) {
+      recomputed = { verdict: 'do_not_rely_unsigned', rely: false, reasons: [`reperform_error:${err?.message || 'threw'}`] };
+    }
+    const recomputed_verdict = recomputed.verdict;
+    const stated_verdict = it.stated_verdict ?? null;
+    // Drift: the org's runtime claimed one outcome, independent re-performance
+    // computed another. A claimed `rely` that recomputes to a refusal is the
+    // material finding — the org relied on evidence that does not support reliance.
+    const drift = stated_verdict !== null && stated_verdict !== recomputed_verdict;
+    return {
+      decision_id: it.decision_id,
+      action_type: it.action?.action_type ?? null,
+      stated_verdict,
+      recomputed_verdict,
+      admissible: recomputed_verdict === 'rely',
+      drift,
+      drift_severity: drift ? (stated_verdict === 'rely' ? 'relied_on_inadmissible_evidence' : 'refused_admissible_or_reclassified') : null,
+      control_id: controlForVerdict(recomputed_verdict),
+      reasons: recomputed.reasons || [],
+    };
+  });
+
+  const byVerdict = Object.create(null);
+  const byControl = Object.create(null);
+  let admissible = 0;
+  let refused = 0;
+  let drift = 0;
+  for (const r of results) {
+    byVerdict[r.recomputed_verdict] = (byVerdict[r.recomputed_verdict] || 0) + 1;
+    if (r.admissible) admissible += 1; else refused += 1;
+    if (r.drift) drift += 1;
+    if (r.control_id) byControl[r.control_id] = (byControl[r.control_id] || 0) + 1;
+  }
+
+  // Recompute the package digest from the package's OWN contents rather than
+  // trusting pkg.package_digest. "No value the package asserts is trusted" has to
+  // include the digest: copying the stated one verbatim would let a tampered
+  // package carry a lying content-address through re-performance unchecked. Mirror
+  // buildAssurancePackage's digestScope exactly (body minus assembled_at and the
+  // digest field itself), then compare.
+  const { assembled_at: _statedAt, package_digest: _statedDigest, ...digestScope } = pkg;
+  const recomputedPackageDigest = hashCanonical(digestScope);
+  const packageDigestVerified = pkg.package_digest != null && recomputedPackageDigest === pkg.package_digest;
+
+  const doc = {
+    '@version': ASSURANCE_REPERFORMANCE_VERSION,
+    product: 'EMILIA Reliance Assurance',
+    package_digest: recomputedPackageDigest,
+    stated_package_digest: pkg.package_digest ?? null,
+    package_digest_verified: packageDigestVerified,
+    profile_hash: pkg.profile_hash ?? null,
+    generated_at: toIso(now),
+    honesty: {
+      reperforms:
+        'Independent recomputation of every reliance verdict from the packaged evidence, under the package\'s pinned '
+        + 'EP-RELIANCE-PROFILE-v1 and auditor-supplied keys, using the offline reliance kernel. No value the package '
+        + 'asserts (including the stated verdict) is trusted; the stated verdict is compared, never relied on.',
+      does_not_establish: [
+        'Completeness of the decision population: decisions withheld before packaging are not detectable from the package alone. Bind the population to an externally anchored count to close this.',
+        'Runtime freshness or one-time consumption AT THE MOMENT OF DECISION: those were live properties; re-performance checks the evidence as packaged, not the runtime state that existed then.',
+        'Issuer, approver, and registrar key custody, enrollment, or identity proofing, which remain external trust roots the auditor supplies out of band.',
+        'The business correctness or wisdom of any authorized action.',
+      ],
+      status: 'Support for an audit re-performance procedure. This document does not conclude, opine, or certify; any conclusion is the auditor\'s.',
+    },
+    population: {
+      decisions: results.length,
+      admissible,
+      refused,
+      drift,
+      relied_on_inadmissible_evidence: results.filter((r) => r.drift_severity === 'relied_on_inadmissible_evidence').length,
+      by_recomputed_verdict: byVerdict,
+      by_control: byControl,
+    },
+    control_catalog: RELIANCE_CONTROL_CATALOG,
+    results,
+    reperformance_digest: null, // filled below
+    // Conclusion fields are ALWAYS null: a machine may support re-performance, it
+    // may never fill in the auditor's sign-off. A renderer must refuse to print a
+    // non-null conclusion here.
+    conclusion: { supportable: null, opinion: null, signed_off_by: null },
+  };
+  // Deterministic re-performance digest over the recomputed results + population
+  // (excludes timestamps), so a second assurer reproduces it byte-for-byte.
+  doc.reperformance_digest = hashCanonical({ package_digest: doc.package_digest, population: doc.population, results });
+  return doc;
+}
+
+/** Render a plain-text auditor workpaper. Refuses to print a filled conclusion. */
+export function renderAssuranceWorkpaper(doc) {
+  if (!doc || doc['@version'] !== ASSURANCE_REPERFORMANCE_VERSION) throw new Error('render: not an EP-ASSURANCE-REPERFORMANCE-v1');
+  if (doc.conclusion && (doc.conclusion.supportable !== null || doc.conclusion.opinion !== null || doc.conclusion.signed_off_by !== null)) {
+    throw new Error('render refused: conclusion fields must be null (the auditor concludes, not the tool)');
+  }
+  const p = doc.population;
+  const lines = [];
+  lines.push(`EMILIA Reliance Assurance — re-performance workpaper (${doc['@version']})`);
+  lines.push(`package_digest:       ${doc.package_digest} (recomputed)`);
+  lines.push(`package_digest match: ${doc.package_digest_verified ? 'YES — recomputed digest equals the package\'s stated digest' : 'NO — stated digest does NOT match recomputed contents (tamper or drift)'}`);
+  lines.push(`reperformance_digest: ${doc.reperformance_digest}`);
+  lines.push('');
+  lines.push(`Population: ${p.decisions} decisions | admissible(rely): ${p.admissible} | refused: ${p.refused} | drift: ${p.drift}`);
+  lines.push(`Relied on INADMISSIBLE evidence (claimed rely, recomputed refusal): ${p.relied_on_inadmissible_evidence}`);
+  lines.push('');
+  lines.push('By recomputed verdict:');
+  for (const [v, n] of Object.entries(p.by_recomputed_verdict)) lines.push(`  ${v}: ${n}`);
+  lines.push('');
+  lines.push('Control objectives exercised (denials are the control operating):');
+  for (const [cid, n] of Object.entries(p.by_control)) lines.push(`  ${cid} (${RELIANCE_CONTROL_CATALOG[cid].objective}): ${n}`);
+  lines.push('');
+  const drifts = doc.results.filter((r) => r.drift);
+  if (drifts.length) {
+    lines.push('DRIFT (independent re-performance disagrees with the runtime\'s stated verdict):');
+    for (const r of drifts) lines.push(`  ${r.decision_id}: stated=${r.stated_verdict} recomputed=${r.recomputed_verdict} [${r.drift_severity}]`);
+    lines.push('');
+  }
+  lines.push('Conclusion: NULL by construction. The auditor concludes; this workpaper only supports the procedure.');
+  return lines.join('\n');
+}

package/store-postgres.js

@@ -1,26 +1,24 @@
 // SPDX-License-Identifier: Apache-2.0
 /**
  * EMILIA Gate — reference DURABLE consumption backend: Postgres
- * (EP-GATE-PG-CONSUMPTION-v1).
+ * (EP-GATE-PG-CONSUMPTION-v2).
  *
  * Replay defense that survives restarts. This module implements the backend
  * contract consumed by `createDurableConsumptionStore` in ./store.js:
  *
  *   backend = {
  *     async addIfAbsent(key, value, { ttlSeconds }?) : boolean  // true iff inserted
- *     async set(key, value, { ttlSeconds }?)         : void     // overwrite
- *     async delete(key)                              : void
+ *     async compareAndSet(key, expected, replacement, { ttlSeconds }?) : boolean
+ *     async deleteIfValue(key, expected)             : boolean
  *     async has(key)                                 : boolean
  *   }
  *
  * plus a `cleanupExpired(now)` garbage-collection statement.
  *
- * THE ONE CORRECTNESS PRIMITIVE — atomic insert-if-absent. `addIfAbsent` is a
- * SINGLE statement: `INSERT ... ON CONFLICT (consumption_key) DO NOTHING`, and
- * the returned row count decides consumed-vs-replay. There is no read-then-
- * write, so there is no race: when two pods consume the same receipt id
- * concurrently, Postgres serializes the inserts on the primary key and exactly
- * one caller sees rowCount === 1. Everyone else is a replay.
+ * Each transition is one SQL statement. `addIfAbsent` decides first use;
+ * `compareAndSet` and `deleteIfValue` bind commit/release to the opaque owner of
+ * the current reservation. There is no read-then-write interval in which a
+ * delayed worker can overwrite or remove a newer worker's reservation.
  *
  * FAIL-CLOSED CONTRACT: if the injected `query` THROWS (connection down,
  * timeout, constraint other than the PK, ...) the error PROPAGATES to the
@@ -37,7 +35,7 @@
  * fake with real ON CONFLICT semantics — no network, no database.
  */
 
-export const PG_CONSUMPTION_VERSION = 'EP-GATE-PG-CONSUMPTION-v1';
+export const PG_CONSUMPTION_VERSION = 'EP-GATE-PG-CONSUMPTION-v2';
 
 /** Single consumption table. Timestamps are epoch milliseconds (BIGINT) so the
  * injected JS clock maps 1:1 onto column values with no timezone ambiguity. */
@@ -58,16 +56,16 @@ export const CONSUMPTION_SQL = {
   /** $1 key, $2 state, $3 consumed_at ms, $4 expires_at ms|null. rowCount 1 = consumed, 0 = replay. */
   addIfAbsent: `INSERT INTO ${CONSUMPTION_TABLE} (consumption_key, state, consumed_at, expires_at) `
     + 'VALUES ($1, $2, $3, $4) ON CONFLICT (consumption_key) DO NOTHING',
-  /** $1 key, $2 state, $3 consumed_at ms, $4 expires_at ms|null. Upsert (overwrite). */
-  set: `INSERT INTO ${CONSUMPTION_TABLE} (consumption_key, state, consumed_at, expires_at) `
-    + 'VALUES ($1, $2, $3, $4) ON CONFLICT (consumption_key) DO UPDATE '
-    + 'SET state = EXCLUDED.state, consumed_at = EXCLUDED.consumed_at, expires_at = EXCLUDED.expires_at',
-  /** $1 key. */
-  delete: `DELETE FROM ${CONSUMPTION_TABLE} WHERE consumption_key = $1`,
+  /** $1 key, $2 expected state, $3 replacement, $4 consumed_at ms, $5 expires_at ms|null. */
+  compareAndSet: `UPDATE ${CONSUMPTION_TABLE} SET state = $3, consumed_at = $4, expires_at = $5 `
+    + 'WHERE consumption_key = $1 AND state = $2',
+  /** $1 key, $2 expected state. */
+  deleteIfValue: `DELETE FROM ${CONSUMPTION_TABLE} WHERE consumption_key = $1 AND state = $2`,
   /** $1 key. Any row — even an expired one — counts as consumed until cleaned. */
   has: `SELECT 1 FROM ${CONSUMPTION_TABLE} WHERE consumption_key = $1`,
   /** $1 now ms. Removes ONLY rows whose TTL has elapsed; NULL expires_at never expires. */
-  cleanupExpired: `DELETE FROM ${CONSUMPTION_TABLE} WHERE expires_at IS NOT NULL AND expires_at <= $1`,
+  cleanupExpired: `DELETE FROM ${CONSUMPTION_TABLE} WHERE state LIKE 'committed:%' `
+    + 'AND expires_at IS NOT NULL AND expires_at <= $1',
 };
 
 /**
@@ -84,13 +82,25 @@ export function createPostgresBackend({ query, now = Date.now } = {}) {
     throw new Error('createPostgresBackend: query must be an async (text, params) => { rowCount } function '
       + '(e.g. pg pool.query). It must THROW on failure — a backend error must never look like a verdict.');
   }
-  const nowMs = () => (typeof now === 'function' ? now() : now);
+  let lastObservedNow = Number.NEGATIVE_INFINITY;
+  const checkedNow = (candidate) => {
+    if (!Number.isSafeInteger(candidate) || candidate < 0) {
+      throw new Error('consumption clock must return a non-negative safe-integer epoch millisecond');
+    }
+    if (candidate < lastObservedNow) {
+      throw new Error(`consumption clock regression refused: ${candidate} < ${lastObservedNow}`);
+    }
+    lastObservedNow = candidate;
+    return candidate;
+  };
+  const nowMs = () => checkedNow(typeof now === 'function' ? now() : now);
   const expiryFor = (opt) => {
     const ttl = Number(opt?.ttlSeconds);
     return Number.isFinite(ttl) && ttl > 0 ? nowMs() + ttl * 1000 : null;
   };
 
   return {
+    durable: true,
     /** True iff THIS call inserted the row — the atomic consumed-vs-replay decision. */
     async addIfAbsent(key, value, opt) {
       const res = await query(CONSUMPTION_SQL.addIfAbsent, [key, value, nowMs(), expiryFor(opt)]);
@@ -102,14 +112,22 @@ export function createPostgresBackend({ query, now = Date.now } = {}) {
       return res.rowCount === 1;
     },
 
-    /** Overwrite (used by commit(): 'reserved' -> 'committed'). */
-    async set(key, value, opt) {
-      await query(CONSUMPTION_SQL.set, [key, value, nowMs(), expiryFor(opt)]);
+    /** Ownership-fenced reserved -> committed transition. */
+    async compareAndSet(key, expected, replacement, opt) {
+      const res = await query(CONSUMPTION_SQL.compareAndSet, [key, expected, replacement, nowMs(), expiryFor(opt)]);
+      if (!res || typeof res.rowCount !== 'number') {
+        throw new Error('compareAndSet: query result has no numeric rowCount — cannot prove reservation ownership');
+      }
+      return res.rowCount === 1;
     },
 
-    /** Remove (used by release(): a failed action leaves the approval retryable). */
-    async delete(key) {
-      await query(CONSUMPTION_SQL.delete, [key]);
+    /** Remove only the reservation owned by the caller. */
+    async deleteIfValue(key, expected) {
+      const res = await query(CONSUMPTION_SQL.deleteIfValue, [key, expected]);
+      if (!res || typeof res.rowCount !== 'number') {
+        throw new Error('deleteIfValue: query result has no numeric rowCount — cannot prove reservation ownership');
+      }
+      return res.rowCount === 1;
     },
 
     /** Present = consumed. Expired-but-uncleaned rows still count (conservative). */
@@ -119,8 +137,9 @@ export function createPostgresBackend({ query, now = Date.now } = {}) {
     },
 
     /** Garbage-collect rows whose TTL elapsed. Returns the number removed. */
-    async cleanupExpired(at = nowMs()) {
-      const res = await query(CONSUMPTION_SQL.cleanupExpired, [at]);
+    async cleanupExpired(at) {
+      const cleanupAt = at === undefined ? nowMs() : checkedNow(at);
+      const res = await query(CONSUMPTION_SQL.cleanupExpired, [cleanupAt]);
       return res?.rowCount ?? 0;
     },
   };

package/store.js

@@ -4,11 +4,14 @@
  *
  * A receipt authorizes ONE action, once. The gate consumes a receipt's
  * identifier the first time it is used; any later presentation of the same
- * receipt is a replay and is refused. The default store is in-memory; swap in a
- * Redis/DB-backed store with the same `consume(key)` contract for a fleet.
+ * receipt is a replay and is refused. The default store is in-memory; fleets
+ * use the ownership-fenced durable contract below.
  */
 export class MemoryConsumptionStore {
   constructor() {
+    this.durable = false;
+    this.ownershipFenced = false;
+    this.permanentConsumption = false;
     this.seen = new Set();
     this.reserved = new Set();
   }
@@ -49,41 +52,103 @@ export class MemoryConsumptionStore {
   }
 }
 
+export const DURABLE_CONSUMPTION_VERSION = 'EP-GATE-DURABLE-CONSUMPTION-v2';
+
+const COMMITTED_VALUE = 'committed:v2';
+const RESERVED_PREFIX = 'reserved:v2:';
+
+function defaultReservationToken() {
+  if (typeof globalThis.crypto?.randomUUID !== 'function') {
+    throw new Error('secure crypto.randomUUID() is required for durable reservation fencing');
+  }
+  return globalThis.crypto.randomUUID();
+}
+
 /**
  * Production custody for replay defense: a durable consumption store backed by
  * any shared key-value backend (Redis, Postgres, DynamoDB, ...), so a receipt
  * consumed on one pod/lambda cannot be replayed on another.
  *
- * The backend MUST provide an ATOMIC insert-if-absent — this is the single
- * correctness primitive that makes replay defense sound under concurrency:
+ * The backend MUST provide atomic insert-if-absent plus atomic conditional
+ * transition and delete. Together they make replay defense and reservation
+ * ownership sound under concurrency:
  *
  *   backend = {
- *     async addIfAbsent(key, value): boolean  // true iff it inserted (Redis SET NX,
- *                                             // Postgres INSERT .. ON CONFLICT DO NOTHING)
- *     async set(key, value): void             // overwrite
- *     async delete(key): void
+ *     async addIfAbsent(key, value): boolean
+ *     async compareAndSet(key, expected, replacement): boolean
+ *     async deleteIfValue(key, expected): boolean
  *     async has(key): boolean
  *   }
  *
- * State per receipt id is a single key: 'reserved' while in flight, 'committed'
- * once the action succeeded. reserve() is the atomic gate; a second reserve()
- * (concurrent replay) loses the race and is refused. Optional `ttlSeconds` is
- * passed through to the backend so consumed ids can expire after the receipt's
- * own max age (the gate already rejects stale receipts on freshness).
+ * State per receipt id is a single ownership-fenced value. A reservation is
+ * `reserved:v2:<random token>` and only the store instance holding that token
+ * can commit or release it. This prevents a delayed worker from deleting or
+ * committing a newer worker's reservation after timeout/failover.
+ *
+ * Reservations deliberately receive NO TTL. A crash after an external effect
+ * has begun is an indeterminate outcome, and automatically reopening the key
+ * would permit a duplicate effect. Operators must reconcile abandoned
+ * reservations. `ttlSeconds` applies only after a value is committed, when the
+ * receipt's own freshness window independently prevents reuse.
  */
-export function createDurableConsumptionStore(backend, { ttlSeconds } = {}) {
-  for (const m of ['addIfAbsent', 'set', 'delete', 'has']) {
+export function createDurableConsumptionStore(backend, { ttlSeconds, reservationTokenFactory = defaultReservationToken } = {}) {
+  for (const m of ['addIfAbsent', 'compareAndSet', 'deleteIfValue', 'has']) {
     if (typeof backend?.[m] !== 'function') {
       throw new Error(`createDurableConsumptionStore: backend must implement async ${m}(). `
-        + 'addIfAbsent MUST be atomic (e.g. Redis SET NX) or replay defense is not fleet-safe.');
+        + 'addIfAbsent and conditional transitions MUST be atomic or replay defense is not fleet-safe.');
     }
   }
+  if (typeof reservationTokenFactory !== 'function') {
+    throw new Error('createDurableConsumptionStore: reservationTokenFactory must be a function');
+  }
+  if (ttlSeconds !== undefined && ttlSeconds !== null
+      && (!Number.isSafeInteger(ttlSeconds) || ttlSeconds <= 0)) {
+    throw new Error('createDurableConsumptionStore: ttlSeconds must be a positive safe integer when supplied');
+  }
   const opt = ttlSeconds ? { ttlSeconds } : undefined;
+  const ownedReservations = new Map();
+
+  function ownedValue(key) {
+    const token = ownedReservations.get(key);
+    if (!token) {
+      throw new Error(`durable consumption transition refused: this store does not own reservation ${key}`);
+    }
+    return `${RESERVED_PREFIX}${token}`;
+  }
+
   return {
-    async reserve(key) { return (await backend.addIfAbsent(key, 'reserved', opt)) === true; },
-    async commit(key) { await backend.set(key, 'committed', opt); return true; },
-    async release(key) { await backend.delete(key); return true; },
-    async consume(key) { return (await backend.addIfAbsent(key, 'committed', opt)) === true; },
+    durable: backend.durable === true,
+    ownershipFenced: true,
+    permanentConsumption: ttlSeconds === undefined || ttlSeconds === null,
+    retentionSeconds: ttlSeconds ?? null,
+    async reserve(key) {
+      const token = reservationTokenFactory();
+      if (typeof token !== 'string' || token.length < 16) {
+        throw new Error('reservationTokenFactory must return an unpredictable string of at least 16 characters');
+      }
+      const inserted = (await backend.addIfAbsent(key, `${RESERVED_PREFIX}${token}`)) === true;
+      if (inserted) ownedReservations.set(key, token);
+      return inserted;
+    },
+    async commit(key) {
+      const expected = ownedValue(key);
+      const changed = await backend.compareAndSet(key, expected, COMMITTED_VALUE, opt);
+      if (changed !== true) {
+        throw new Error(`durable consumption commit refused: reservation ownership was lost for ${key}`);
+      }
+      ownedReservations.delete(key);
+      return true;
+    },
+    async release(key) {
+      const expected = ownedValue(key);
+      const deleted = await backend.deleteIfValue(key, expected);
+      ownedReservations.delete(key);
+      if (deleted !== true) {
+        throw new Error(`durable consumption release refused: reservation ownership was lost for ${key}`);
+      }
+      return true;
+    },
+    async consume(key) { return (await backend.addIfAbsent(key, COMMITTED_VALUE, opt)) === true; },
     async has(key) { return (await backend.has(key)) === true; },
   };
 }
@@ -92,12 +157,21 @@ export function createDurableConsumptionStore(backend, { ttlSeconds } = {}) {
 export function createMemoryBackend() {
   const map = new Map();
   return {
+    durable: false,
     async addIfAbsent(key, value) { if (map.has(key)) return false; map.set(key, value); return true; },
-    async set(key, value) { map.set(key, value); },
-    async delete(key) { map.delete(key); },
+    async compareAndSet(key, expected, replacement) {
+      if (map.get(key) !== expected) return false;
+      map.set(key, replacement);
+      return true;
+    },
+    async deleteIfValue(key, expected) {
+      if (map.get(key) !== expected) return false;
+      return map.delete(key);
+    },
     async has(key) { return map.has(key); },
+    async get(key) { return map.get(key); },
     get size() { return map.size; },
   };
 }
 
-export default { MemoryConsumptionStore, createDurableConsumptionStore, createMemoryBackend };
+export default { MemoryConsumptionStore, createDurableConsumptionStore, createMemoryBackend, DURABLE_CONSUMPTION_VERSION };