@aetheros/kernel-runtime 0.1.1 → 0.1.2

package/src/budgets.js

@@ -0,0 +1,226 @@
+import {createHash} from 'node:crypto';
+import {TransactionalStateStore} from './transactions.js';
+import {canonicalJson} from './canonical-json.js';
+
+const clone = value => structuredClone(value);
+const id = value => {if (typeof value !== 'string' || !value.trim() || value.length > 256) throw new TypeError('Invalid budget identifier'); return value;};
+const amount = (value, positive = false) => {
+  if (typeof value !== 'string' || !/^(0|[1-9][0-9]{0,77})$/.test(value) || (positive && value === '0')) throw new TypeError('Canonical integer amount required');
+  return BigInt(value);
+};
+const time = value => {if (!Number.isSafeInteger(value) || value < 0) throw new TypeError('Invalid budget time'); return value;};
+const slot = (...parts) => createHash('sha256').update(JSON.stringify(parts)).digest('hex');
+const policySnapshot = p => {
+  const {tenantId, subjectId, period, unit, scale, limit, startsAt, endsAt} = p ?? {};
+  [tenantId, subjectId, period, unit].forEach(id); amount(limit);
+  if (!Number.isInteger(scale) || scale < 0 || scale > 18 || time(startsAt) >= time(endsAt)) throw new TypeError('Invalid budget policy');
+  return {tenantId, subjectId, period, unit, scale, limit, startsAt, endsAt};
+};
+
+const receiptSnapshot = value => {
+  canonicalJson(value);
+  const {source, receiptId, evidenceId, kind, final} = value ?? {};
+  [source, receiptId, evidenceId].forEach(id);
+  if (final !== true || !['billed', 'no_spend'].includes(kind)) throw new TypeError('Final usage provenance required');
+  const receipt = {source, receiptId, evidenceId, kind, final};
+  if (canonicalJson(receipt) !== canonicalJson(value)) throw new TypeError('Invalid usage receipt');
+  return receipt;
+};
+const estimateReceiptSnapshot = value => {
+  canonicalJson(value);
+  const {source,receiptId,evidenceId,kind,final} = value ?? {};
+  [source,receiptId,evidenceId].forEach(id);
+  const receipt = {source,receiptId,evidenceId,kind,final};
+  if (kind !== 'estimate' || final !== false || canonicalJson(receipt) !== canonicalJson(value)) throw new TypeError('Explicit non-billed estimate receipt required');
+  return receipt;
+};
+const terminal = r => r.status === 'settled' || r.status === 'released';
+const totals = bucket => {
+  let reserved = 0n, spent = 0n, estimatedSpent = 0n;
+  for (const r of bucket.reservations) {
+    if (r.status === 'settled') spent += amount(r.actualAmount);
+    else if (r.status === 'estimated') estimatedSpent += amount(r.estimatedAmount);
+    else if (r.status !== 'released') reserved += amount(r.amount, true);
+  }
+  const remaining = amount(bucket.policy.limit) - reserved - spent - estimatedSpent;
+  return {reserved:reserved.toString(), spent:spent.toString(), estimatedSpent:estimatedSpent.toString(), available:(remaining < 0n ? 0n : remaining).toString(), deficit:(remaining < 0n ? -remaining : 0n).toString()};
+};
+
+/** Trusted-host primitive, not an authentication facade. Hosts authenticate and
+ * authorize tenant/subject policy and reservation access before calling it.
+ * Cooperating local processes must share one canonical dedicated file path.
+ * Busy/abandoned locks fail closed; no dispatch or lock recovery.
+ */
+export class FileBudgetStore {
+  #store;
+  #clock;
+  #verifyUsage;
+  #verifyEstimate;
+  constructor(path, {clock = Date.now, codec, verifyUsage, verifyEstimate} = {}) {
+    if (typeof clock !== 'function') throw new TypeError('Budget clock required');
+    if (verifyUsage !== undefined && typeof verifyUsage !== 'function') throw new TypeError('Usage verifier must be a function');
+    if (verifyEstimate !== undefined && typeof verifyEstimate !== 'function') throw new TypeError('Estimate verifier must be a function');
+    this.#verifyEstimate = verifyEstimate;
+    this.#verifyUsage = verifyUsage;
+    this.#clock = clock; this.#store = new TransactionalStateStore(path, {codec});
+  }
+  #validate(state) {
+    const receipts = new Set();
+    for (const [key, bucket] of Object.entries(state.tenants)) {
+      if (bucket?.kind !== 'budget-v1' || !Array.isArray(bucket.reservations)) throw new Error('Invalid budget state');
+      const p = policySnapshot(bucket.policy);
+      if (key !== slot(p.tenantId, p.subjectId, p.period) || canonicalJson(p) !== canonicalJson(bucket.policy)) throw new Error('Invalid budget policy state');
+      const keys = new Set();
+      for (const r of bucket.reservations) {
+        id(r.runId);
+        if (r.tenantId !== p.tenantId || r.subjectId !== p.subjectId || r.period !== p.period || r.unit !== p.unit || r.scale !== p.scale || keys.has(r.runId) || r.reservationId !== slot(p.tenantId, r.runId) || !['reserved','uncertain','settled','released','estimated'].includes(r.status) || time(r.reservedAt) < p.startsAt || r.reservedAt >= p.endsAt) throw new Error('Invalid budget reservation state');
+        keys.add(r.runId); amount(r.amount, true);
+        const baseKeys = ['tenantId','subjectId','period','unit','scale','reservationId','runId','amount','status','reservedAt'];
+        if (Object.hasOwn(r, 'interruptedAt')) {
+          if (time(r.interruptedAt) < r.reservedAt || r.status === 'reserved') throw new Error('Invalid interruption');
+          baseKeys.push('interruptedAt');
+        }
+        if (r.status === 'uncertain' && !Object.hasOwn(r, 'interruptedAt')) throw new Error('Missing interruption');
+        if (r.status === 'estimated' || Object.hasOwn(r, 'estimatedAmount')) {
+          const receipt = estimateReceiptSnapshot(r.estimateReceipt);
+          amount(r.estimatedAmount);
+          if (!['estimated','settled','released'].includes(r.status) || time(r.estimatedAt) < (r.interruptedAt ?? r.reservedAt)) throw new Error('Invalid estimate state');
+          const receiptKey = slot(r.tenantId,receipt.source,receipt.receiptId);
+          if (receipts.has(receiptKey)) throw new Error('Duplicate estimate receipt');
+          receipts.add(receiptKey);
+          baseKeys.push('estimatedAmount','estimateReceipt','estimatedAt');
+        }
+        if (terminal(r)) {
+          const receipt = receiptSnapshot(r.receipt);
+          amount(r.actualAmount);
+          if (time(r.finalizedAt) < Math.max(r.estimatedAt ?? 0, r.interruptedAt ?? r.reservedAt) || (r.status === 'settled' ? receipt.kind !== 'billed' : receipt.kind !== 'no_spend' || r.actualAmount !== '0')) throw new Error('Invalid final usage');
+          const receiptKey = slot(r.tenantId, receipt.source, receipt.receiptId);
+          if (receipts.has(receiptKey)) throw new Error('Duplicate usage receipt');
+          receipts.add(receiptKey);
+          baseKeys.push('receipt','actualAmount','finalizedAt');
+        }
+        if (Object.keys(r).length !== baseKeys.length || baseKeys.some(k => !Object.hasOwn(r,k))) throw new Error('Invalid reservation fields');
+      }
+      // A final verified bill may exceed the limit. Never discard real spend.
+      if (BigInt(totals(bucket).reserved) > amount(p.limit)) throw new Error('Invalid held budget total');
+    }
+    // Stable keys are unique across all subjects and periods within a tenant.
+    const keys = new Set(); const policies = [];
+    for (const b of Object.values(state.tenants)) {
+      const p = b.policy;
+      for (const prior of policies) if (prior.tenantId === p.tenantId && prior.subjectId === p.subjectId && prior.startsAt < p.endsAt && p.startsAt < prior.endsAt) throw new Error('Overlapping budget periods');
+      policies.push(p);
+      for (const r of b.reservations) {if (keys.has(r.reservationId)) throw new Error('Duplicate reservation key'); keys.add(r.reservationId);}
+    }
+  }
+  async #mutate(update) {
+    let result;
+    await this.#store.exclusive(() => this.#store.transaction(async state => {
+      this.#validate(state); result = await update(state); this.#validate(state); return state;
+    }));
+    return clone(result);
+  }
+  async setPolicy(input) {
+    const p = policySnapshot(input);
+    return this.#mutate(state => {
+      const key = slot(p.tenantId, p.subjectId, p.period), prior = state.tenants[key];
+      if (prior && canonicalJson(prior.policy) !== canonicalJson(p)) throw new Error('BUDGET_POLICY_CONFLICT');
+      if (!prior) state.tenants[key] = {kind:'budget-v1', policy:p, reservations:[]};
+      return p;
+    });
+  }
+  async getBudget({tenantId, subjectId, period} = {}) {
+    [tenantId, subjectId, period].forEach(id);
+    const state = await this.#store.load(); this.#validate(state);
+    const bucket = state.tenants[slot(tenantId, subjectId, period)];
+    if (!bucket) return null;
+    return {...clone(bucket.policy), ...totals(bucket), reservations:clone(bucket.reservations)};
+  }
+  async reserveBudget({tenantId, subjectId, period, amount: requested, runId} = {}) {
+    [tenantId, subjectId, period, runId].forEach(id); const value = amount(requested, true);
+    // Snapshot all caller values before waiting for the transaction queue.
+    return this.#mutate(state => {
+      const bucket = state.tenants[slot(tenantId, subjectId, period)];
+      if (!bucket) throw new Error('BUDGET_POLICY_REQUIRED');
+      for (const b of Object.values(state.tenants)) {
+        if (b.policy.tenantId !== tenantId) continue;
+        const prior = b.reservations.find(r => r.runId === runId);
+        if (prior) {
+          if (b !== bucket || prior.amount !== requested) throw new Error('BUDGET_KEY_CONFLICT');
+          return prior; // Old-period replay returns history, never new capacity.
+        }
+      }
+      const now = time(this.#clock()), p = bucket.policy;
+      if (now < p.startsAt || now >= p.endsAt) throw new Error('BUDGET_PERIOD_INACTIVE');
+      const usage = totals(bucket);
+      if (BigInt(usage.deficit) > 0n || value > BigInt(usage.available)) throw new Error('BUDGET_LIMIT_EXCEEDED');
+      const r = {tenantId, subjectId, period, unit:p.unit, scale:p.scale, reservationId:slot(tenantId, runId), runId, amount:requested, status:'reserved', reservedAt:now};
+      bucket.reservations.push(r); return r;
+    });
+  }
+  #find(state, {tenantId, subjectId, period, reservationId}) {
+    const bucket = state.tenants[slot(tenantId, subjectId, period)];
+    const r = bucket?.reservations.find(r => r.reservationId === reservationId);
+    if (!r) throw new Error('BUDGET_RESERVATION_NOT_FOUND');
+    return r;
+  }
+  /** Retire an interrupted run to uncertainty. Never frees capacity or dispatches. */
+  async recoverBudget({tenantId, subjectId, period, reservationId} = {}) {
+    const binding = {tenantId, subjectId, period, reservationId};
+    Object.values(binding).forEach(id);
+    return this.#mutate(state => {
+      const r = this.#find(state, binding);
+      if (r.status === 'reserved') {
+        const now = time(this.#clock());
+        if (now < r.reservedAt) throw new Error('BUDGET_CLOCK_REGRESSED');
+        r.status = 'uncertain'; r.interruptedAt = now;
+      }
+      return r;
+    });
+  }
+  /** Opt-in host estimate accounting. Never final bills or definitive no-spend. */
+  async estimateBudget({tenantId,subjectId,period,reservationId,estimatedAmount,receipt:supplied} = {}) {
+    const binding = {tenantId,subjectId,period,reservationId};Object.values(binding).forEach(id);
+    amount(estimatedAmount);const receipt = estimateReceiptSnapshot(supplied);
+    return this.#mutate(async state => {
+      const r = this.#find(state,binding);
+      if (Object.hasOwn(r,'estimatedAmount')) {
+        if (r.estimatedAmount !== estimatedAmount || canonicalJson(r.estimateReceipt) !== canonicalJson(receipt)) throw new Error('BUDGET_ESTIMATE_CONFLICT');
+        return r;
+      }
+      if (terminal(r)) throw new Error('BUDGET_FINALIZATION_CONFLICT');
+      for (const b of Object.values(state.tenants)) if (b.policy.tenantId === tenantId && b.reservations.some(other => [other.receipt,other.estimateReceipt].some(value => value?.source === receipt.source && value.receiptId === receipt.receiptId))) throw new Error('BUDGET_RECEIPT_CONFLICT');
+      if (!this.#verifyEstimate || await this.#verifyEstimate(clone({reservation:r,estimatedAmount,receipt})) !== true) throw new Error('BUDGET_ESTIMATE_UNVERIFIED');
+      const now = time(this.#clock());if (now < (r.interruptedAt ?? r.reservedAt)) throw new Error('BUDGET_CLOCK_REGRESSED');
+      Object.assign(r,{status:'estimated',estimatedAmount,estimateReceipt:receipt,estimatedAt:now});return r;
+    });
+  }
+  async settleBudget(input) {return this.#finalize(input, 'settled');}
+  async releaseBudget(input) {return this.#finalize(input, 'released');}
+  async #finalize({tenantId, subjectId, period, reservationId, actualAmount, receipt: supplied} = {}, status) {
+    const binding = {tenantId, subjectId, period, reservationId};
+    Object.values(binding).forEach(id);
+    amount(actualAmount);
+    const receipt = receiptSnapshot(supplied);
+    if (status === 'settled' ? receipt.kind !== 'billed' : receipt.kind !== 'no_spend' || actualAmount !== '0') throw new Error('BUDGET_PROVENANCE_REQUIRED');
+    return this.#mutate(async state => {
+      const r = this.#find(state, binding);
+      if (terminal(r)) {
+        if (r.status !== status || r.actualAmount !== actualAmount || canonicalJson(r.receipt) !== canonicalJson(receipt)) throw new Error('BUDGET_FINALIZATION_CONFLICT');
+        return r; // Durable replay needs no remote lookup and never changes capacity.
+      }
+      for (const b of Object.values(state.tenants)) {
+        if (b.policy.tenantId !== tenantId) continue;
+        if (b.reservations.some(other => [other.receipt,other.estimateReceipt].some(value => value?.source === receipt.source && value.receiptId === receipt.receiptId))) throw new Error('BUDGET_RECEIPT_CONFLICT');
+      }
+      // The host must prove complete final usage and fence every potential spender.
+      // A caller-supplied declaration/estimate is insufficient. No verifier = hold.
+      if (!this.#verifyUsage || await this.#verifyUsage(clone({action:status === 'settled' ? 'settle' : 'release', reservation:r, actualAmount, receipt})) !== true) throw new Error('BUDGET_USAGE_UNVERIFIED');
+      const now = time(this.#clock());
+      if (now < Math.max(r.estimatedAt ?? 0, r.interruptedAt ?? r.reservedAt)) throw new Error('BUDGET_CLOCK_REGRESSED');
+      Object.assign(r, {status, actualAmount, receipt, finalizedAt:now});
+      return r;
+    });
+  }
+
+}

package/src/claims-conformance.js

@@ -0,0 +1,83 @@
+import {strict as assert} from 'node:assert';
+
+/**
+ * Conformance cases for any claim backend. `make()` returns {backend, advance(ms)}: a fresh backend and a way to move ITS clock
+ * forward (a real backend adapter can sleep, or drive a fake clock on the server side).
+ * Use: for (const c of claimConformanceCases(make)) test(c.name, c.run);
+ */
+export function claimConformanceCases(make) {
+  const ttl = 1000;
+  return [
+    {name: 'acquire gives a fencing token; a second worker is refused while the claim is live', run: async () => {
+      const {backend} = make();
+      const a = await backend.acquire({key: 'k', owner: 'a', ttlMs: ttl});
+      assert.equal(a.ok, true); assert.ok(Number.isSafeInteger(a.token) && a.token >= 1);
+      const b = await backend.acquire({key: 'k', owner: 'b', ttlMs: ttl});
+      assert.deepEqual([b.ok, b.reason, b.heldBy], [false, 'held', 'a']);
+      assert.equal((await backend.acquire({key: 'other', owner: 'b', ttlMs: ttl})).ok, true, 'keys are independent');
+      assert.equal((await backend.get('k')).owner, 'a');
+    }},
+    {name: 'a claim that expires can be taken, and the new token is larger', run: async () => {
+      const {backend, advance} = make();
+      const a = await backend.acquire({key: 'k', owner: 'a', ttlMs: ttl});
+      advance(ttl + 1);
+      assert.equal(await backend.get('k'), null);
+      const b = await backend.acquire({key: 'k', owner: 'b', ttlMs: ttl});
+      assert.equal(b.ok, true); assert.ok(b.token > a.token);
+    }},
+    {name: 'a stale worker (its claim expired and was taken over) can neither renew, release nor pass validation', run: async () => {
+      const {backend, advance} = make();
+      const a = await backend.acquire({key: 'k', owner: 'a', ttlMs: ttl});
+      advance(ttl + 1);
+      const b = await backend.acquire({key: 'k', owner: 'b', ttlMs: ttl});
+      assert.deepEqual(await backend.renew({key: 'k', owner: 'a', token: a.token, ttlMs: ttl}), {ok: false, reason: 'stale'});
+      assert.deepEqual(await backend.release({key: 'k', owner: 'a', token: a.token}), {ok: false, reason: 'stale'});
+      assert.equal((await backend.validate({key: 'k', token: a.token})).ok, false);
+      assert.equal((await backend.validate({key: 'k', token: b.token})).ok, true);
+      assert.equal((await backend.get('k')).owner, 'b', 'the new holder is untouched');
+    }},
+    {name: 'a partitioned worker that comes back late cannot renew an expired claim even if nobody took it', run: async () => {
+      const {backend, advance} = make();
+      const a = await backend.acquire({key: 'k', owner: 'a', ttlMs: ttl});
+      advance(ttl + 1);
+      const late = await backend.renew({key: 'k', owner: 'a', token: a.token, ttlMs: ttl});
+      assert.equal(late.ok, false); assert.ok(['expired', 'stale', 'not-held'].includes(late.reason));
+      assert.equal((await backend.validate({key: 'k', token: a.token})).ok, false);
+    }},
+    {name: 'renew extends the claim; release frees it; tokens keep growing across releases', run: async () => {
+      const {backend, advance} = make();
+      const a = await backend.acquire({key: 'k', owner: 'a', ttlMs: ttl});
+      advance(ttl - 100);
+      assert.equal((await backend.renew({key: 'k', owner: 'a', token: a.token, ttlMs: ttl})).ok, true);
+      advance(ttl - 100);
+      assert.equal((await backend.get('k')).owner, 'a', 'still held thanks to the renewal');
+      assert.equal((await backend.release({key: 'k', owner: 'a', token: a.token})).ok, true);
+      assert.equal(await backend.get('k'), null);
+      const again = await backend.acquire({key: 'k', owner: 'a', ttlMs: ttl});
+      assert.ok(again.token > a.token, 'a token is never reused');
+      assert.equal((await backend.release({key: 'k', owner: 'a', token: a.token})).ok, false, 'the old token cannot release the new claim');
+      assert.equal((await backend.get('k')).token, again.token);
+    }},
+    {name: 'only the holder with the right token can renew or release; nothing held is not-held', run: async () => {
+      const {backend} = make();
+      assert.deepEqual(await backend.release({key: 'k', owner: 'a', token: 1}), {ok: false, reason: 'not-held'});
+      assert.deepEqual(await backend.renew({key: 'k', owner: 'a', token: 1, ttlMs: ttl}), {ok: false, reason: 'not-held'});
+      const a = await backend.acquire({key: 'k', owner: 'a', ttlMs: ttl});
+      assert.equal((await backend.renew({key: 'k', owner: 'b', token: a.token, ttlMs: ttl})).reason, 'stale');
+      assert.equal((await backend.renew({key: 'k', owner: 'a', token: a.token + 1, ttlMs: ttl})).reason, 'stale');
+      assert.equal((await backend.release({key: 'k', owner: 'b', token: a.token})).reason, 'stale');
+      assert.equal((await backend.get('k')).owner, 'a');
+    }},
+    {name: 'concurrent acquires: exactly one wins', run: async () => {
+      const {backend} = make();
+      const results = await Promise.all(Array.from({length: 8}, (_, i) => backend.acquire({key: 'k', owner: 'w' + i, ttlMs: ttl})));
+      assert.equal(results.filter(r => r.ok).length, 1);
+    }},
+    {name: 'bad input is a programming error, not a refusal', run: async () => {
+      const {backend} = make();
+      await assert.rejects(backend.acquire({key: '', owner: 'a', ttlMs: ttl}), TypeError);
+      await assert.rejects(backend.acquire({key: 'k', owner: '', ttlMs: ttl}), TypeError);
+      await assert.rejects(backend.acquire({key: 'k', owner: 'a', ttlMs: 0}), TypeError);
+    }}
+  ];
+}

package/src/claims.js

@@ -0,0 +1,64 @@
+/**
+ * Claim backend contract (A5): a lease on a named resource that several workers, possibly on several machines, compete for.
+ * The contract is what a shared backend (a database, a lock service) must provide; this file defines it, ships an in-memory
+ * reference and a conformance suite (claims-conformance.js). Which shared backend is used is a deployment decision.
+ *
+ * Rules every backend must keep:
+ *  - acquire succeeds only when nobody holds a live (unexpired) claim on the key; it returns a fencing token.
+ *  - fencing tokens only grow, per key, across releases and expiries. A token is never reused.
+ *  - renew and release only work for the current holder with the current token; a worker whose claim expired and was taken
+ *    over is "stale" and is refused. Expiry is judged by the backend's own clock, never by the worker's.
+ *  - validate(key, token) tells a protected resource whether a token is still the current one (use it before every write).
+ * Methods are async so a network backend can implement them; they never throw for refusals, they return {ok: false, reason}.
+ */
+export const CLAIM_REASONS = Object.freeze(['held', 'not-held', 'stale', 'expired']);
+
+const check = ({key, owner, ttlMs}) => {
+  if (typeof key !== 'string' || !key) throw new TypeError('Claim key required');
+  if (typeof owner !== 'string' || !owner) throw new TypeError('Claim owner required');
+  if (!Number.isFinite(ttlMs) || ttlMs <= 0) throw new TypeError('Claim ttlMs must be a positive number');
+};
+
+/** In-memory reference backend. `now` is the backend's clock (injectable for tests). */
+export function createMemoryClaimBackend({now = () => Date.now()} = {}) {
+  const claims = new Map(); // key -> {owner, token, expiresAt} (live or expired)
+  const tokens = new Map(); // key -> highest token ever issued
+  const live = key => { const c = claims.get(key); return c && c.expiresAt > now() ? c : null; };
+  return {
+    async acquire({key, owner, ttlMs}) {
+      check({key, owner, ttlMs});
+      const current = live(key);
+      if (current) return {ok: false, reason: 'held', heldBy: current.owner, expiresAt: current.expiresAt};
+      const token = (tokens.get(key) ?? 0) + 1;
+      tokens.set(key, token);
+      const claim = {owner, token, expiresAt: now() + ttlMs};
+      claims.set(key, claim);
+      return {ok: true, token, expiresAt: claim.expiresAt};
+    },
+    async renew({key, owner, token, ttlMs}) {
+      check({key, owner, ttlMs});
+      const claim = claims.get(key);
+      if (!claim) return {ok: false, reason: 'not-held'};
+      if (claim.owner !== owner || claim.token !== token) return {ok: false, reason: 'stale'};
+      if (claim.expiresAt <= now()) return {ok: false, reason: 'expired'}; // it ran out: renewing late is not allowed
+      claim.expiresAt = now() + ttlMs;
+      return {ok: true, token, expiresAt: claim.expiresAt};
+    },
+    async release({key, owner, token}) {
+      const claim = claims.get(key);
+      if (!claim) return {ok: false, reason: 'not-held'};
+      if (claim.owner !== owner || claim.token !== token) return {ok: false, reason: 'stale'};
+      claims.delete(key);
+      return {ok: true};
+    },
+    /** Is this token the current, live claim on the key? For a protected resource to check before it accepts a write. */
+    async validate({key, token}) {
+      const claim = live(key);
+      return claim && claim.token === token ? {ok: true, owner: claim.owner} : {ok: false, reason: claim ? 'stale' : 'expired'};
+    },
+    async get(key) {
+      const claim = live(key);
+      return claim ? {owner: claim.owner, token: claim.token, expiresAt: claim.expiresAt} : null;
+    }
+  };
+}

package/src/effect-journal.js

@@ -1,6 +1,8 @@
 import {createHash} from 'node:crypto';
 import {TransactionalStateStore} from './transactions.js';
+import {TokenAuthority} from './index.js';
 import {canonicalJson} from './canonical-json.js';
+import {snapshotRetryCapability, assertRetryCapabilityTime} from './retry-capability.js';
 import {snapshotEffectBinding, assertEffectBinding} from './effect-binding.js';
 
 const required = (value, label) => {
@@ -55,6 +57,26 @@ export class FileEffectJournal {
     const state = await this.#store.load();
     return clone(state.tenants[slot(tenantId, effectKey)] ?? null);
   }
+  // Trusted-host raw snapshot; never expose directly to clients.
+  async snapshot() { return clone((await this.#store.load()).tenants); }
+  // Logical tombstone only: preserve the complete replay record indefinitely.
+  async retain({expectedEntry, reviewId, decisionId, subject, beforeCommit} = {}) {
+    const expected = JSON.parse(canonical(expectedEntry));
+    if (!expected || expected.status !== 'confirmed' || expected.receipt === undefined ||
+        (expected.retry && expected.retry.status !== 'confirmed')) throw new TypeError('Confirmed effect required');
+    for (const [name, value] of Object.entries({tenantId:expected.tenantId, effectKey:expected.effectKey, reviewId, decisionId, subject})) required(value, name);
+    if (typeof beforeCommit !== 'function') throw new TypeError('Retention guard required');
+    const references = [expected.binding, expected.reconciliation, expected.claimRecovery,
+      expected.retry?.authorization, expected.retry?.execution, expected.retry?.recovery].filter(Boolean);
+    if (references.some(reference => reference.reviewId === reviewId || reference.decisionId === decisionId)) throw new Error('Fresh retention Review required');
+    return this.#mutate(async state => {
+      const key = slot(expected.tenantId, expected.effectKey), prior = state.tenants[key];
+      if (!prior || canonical(prior) !== canonical(expected)) throw new Error('EFFECT_REVIEW_CONFLICT');
+      if (await beforeCommit() !== true) throw new Error('EFFECT_RETENTION_DENIED');
+      if (!prior.retention) state.tenants[key] = {...prior, retention:{version:1, reviewId, decisionId, subject, reviewedDigest:digest(expected), retainedAt:Date.now()}};
+      return clone(state.tenants[key]);
+    });
+  }
   async markDispatched({tenantId, effectKey, binding} = {}) {
     return this.#transition(tenantId, effectKey, 'dispatched', undefined, binding);
   }
@@ -82,7 +104,85 @@ export class FileEffectJournal {
       if (!prior || canonical(prior) !== canonical(expected)) throw new Error('EFFECT_REVIEW_CONFLICT');
       if (await beforeCommit() !== true) throw new Error('EFFECT_RECONCILIATION_DENIED');
       const next = {...prior, status:'confirmed', receipt:safeReceipt,
-        reconciliation:{decisionId, subject}};
+        reconciliation:{decisionId, subject},
+        ...(prior.retry && {retry:{...prior.retry, status:'confirmed', completedAt:Date.now()}})};
+      state.tenants[key] = next;
+      return clone(next);
+    });
+  }
+  // Trusted-host reservation primitive. The authenticated facade supplies policy/Review guards.
+  // Reservation alone never dispatches; a reserved effect remains uncertain.
+  async reserveRetryAttempt({expectedEntry, input, capability, reviewId, decisionId, subject, attemptId, beforeCommit} = {}) {
+    const expected = JSON.parse(canonical(expectedEntry));
+    if (!expected || expected.kind !== 'idempotent-write' ||
+        !['dispatched', 'reconciliation_required'].includes(expected.status) ||
+        !snapshotEffectBinding(expected.binding) || Object.hasOwn(expected, 'retry')) throw new TypeError('Unreserved bound uncertain idempotent effect required');
+    for (const [name, value] of Object.entries({tenantId:expected.tenantId, effectKey:expected.effectKey, reviewId, decisionId, subject, attemptId})) required(value, name);
+    if (reviewId === expected.binding.reviewId || decisionId === expected.binding.decisionId || typeof beforeCommit !== 'function') throw new TypeError('Fresh retry Review and commit guard required');
+    const contract = snapshotRetryCapability(capability, expected, input);
+    return this.#mutate(async state => {
+      const key = slot(expected.tenantId, expected.effectKey), prior = state.tenants[key];
+      if (!prior || canonical(prior) !== canonical(expected)) throw new Error('EFFECT_REVIEW_CONFLICT');
+      if (await beforeCommit() !== true) throw new Error('EFFECT_RETRY_DENIED');
+      assertRetryCapabilityTime(contract);
+      const next = {...prior, retry:{version:1, id:attemptId, number:1, status:'reserved',
+        authorization:{action:'reserve-retry', reviewId, decisionId, subject,
+          expectedEntryDigest:digest(expected), capability:contract}, reservedAt:Date.now()}};
+      state.tenants[key] = next;
+      return clone(next);
+    });
+  }
+  // Trusted-host one-shot transitions. No resume, release, reuse or second attempt.
+  async transitionRetryAttempt({expectedEntry, target, input, reviewId, decisionId, subject, receipt, beforeCommit} = {}) {
+    const expected = JSON.parse(canonical(expectedEntry));
+    if (!expected || expected.kind !== 'idempotent-write' ||
+        !['dispatched', 'reconciliation_required'].includes(expected.status) ||
+        !snapshotEffectBinding(expected.binding) || expected.retry?.version !== 1 || expected.retry.number !== 1 ||
+        !['dispatched', 'confirmed', 'reconciliation_required'].includes(target) || typeof beforeCommit !== 'function') throw new TypeError('Bound retry transition required');
+    const retry = expected.retry;
+    required(retry.id, 'attemptId');
+    if (target === 'dispatched') {
+      if (retry.status !== 'reserved') throw new Error('EFFECT_REPLAY_BLOCKED');
+      for (const [name, value] of Object.entries({reviewId, decisionId, subject})) required(value, name);
+      if ([expected.binding.reviewId, retry.authorization.reviewId].includes(reviewId) ||
+          [expected.binding.decisionId, retry.authorization.decisionId].includes(decisionId)) throw new Error('Fresh execution Review required');
+    } else if (retry.status !== 'dispatched') throw new Error('EFFECT_REPLAY_BLOCKED');
+    const contract = target === 'dispatched' ? snapshotRetryCapability(retry.authorization.capability, expected, input) : undefined;
+    const safeReceipt = target === 'confirmed' ? JSON.parse(canonical(receipt)) : undefined;
+    return this.#mutate(async state => {
+      const key = slot(expected.tenantId, expected.effectKey), prior = state.tenants[key];
+      if (!prior || canonical(prior) !== canonical(expected)) throw new Error('EFFECT_REVIEW_CONFLICT');
+      if (await beforeCommit() !== true) throw new Error('EFFECT_RETRY_DENIED');
+      if (contract) assertRetryCapabilityTime(contract);
+      const next = {...prior, status:target === 'confirmed' ? 'confirmed' : prior.status,
+        ...(target === 'confirmed' && {receipt:safeReceipt}),
+        retry:{...prior.retry, status:target,
+          ...(target === 'dispatched' ? {dispatchedAt:Date.now(), execution:{action:'execute-retry', reviewId, decisionId, subject}} : {completedAt:Date.now()})}};
+      state.tenants[key] = next;
+      return clone(next);
+    });
+  }
+  // Retire an interrupted attempt, never reset it. Whole-record CAS fences old
+  // reservations and late completions; it cannot cancel already admitted remote work.
+  async recoverRetryAttempt({expectedEntry, reviewId, decisionId, subject, beforeCommit} = {}) {
+    const expected = JSON.parse(canonical(expectedEntry));
+    if (!expected || expected.kind !== 'idempotent-write' ||
+        !['dispatched', 'reconciliation_required'].includes(expected.status) ||
+        !snapshotEffectBinding(expected.binding) || expected.retry?.version !== 1 || expected.retry.number !== 1 ||
+        !['reserved', 'dispatched', 'reconciliation_required'].includes(expected.retry.status) ||
+        Object.hasOwn(expected.retry, 'recovery') || typeof beforeCommit !== 'function') throw new TypeError('Interrupted bound retry required');
+    const retry = expected.retry;
+    for (const [name, value] of Object.entries({tenantId:expected.tenantId, effectKey:expected.effectKey, attemptId:retry.id, reviewId, decisionId, subject})) required(value, name);
+    if ([expected.binding.reviewId, retry.authorization?.reviewId, retry.execution?.reviewId].includes(reviewId) ||
+        [expected.binding.decisionId, retry.authorization?.decisionId, retry.execution?.decisionId].includes(decisionId)) throw new Error('Fresh recovery Review required');
+    return this.#mutate(async state => {
+      const key = slot(expected.tenantId, expected.effectKey), prior = state.tenants[key];
+      if (!prior || canonical(prior) !== canonical(expected)) throw new Error('EFFECT_REVIEW_CONFLICT');
+      if (await beforeCommit() !== true) throw new Error('EFFECT_RETRY_RECOVERY_DENIED');
+      const next = {...prior, status:'reconciliation_required', retry:{...prior.retry,
+        status:'reconciliation_required', completedAt:Date.now(),
+        recovery:{action:'recover-retry', previousStatus:retry.status, reviewId, decisionId, subject,
+          expectedEntryDigest:digest(expected)}}};
       state.tenants[key] = next;
       return clone(next);
     });
@@ -140,3 +240,55 @@ export class FileEffectJournal {
   }
 }
 
+/** Authenticated, redacted operator facade; raw journal access stays trusted-host only. */
+export class AuthenticatedEffectJournal {
+  #journal; #authority; #tenantId; #authorizeRetention;
+  constructor(journal, authority, {tenantId, authorizeRetention} = {}) {
+    if (!(journal instanceof FileEffectJournal) || !(authority instanceof TokenAuthority)) throw new TypeError('Journal and authority required');
+    required(tenantId, 'tenantId');
+    if (authorizeRetention !== undefined && typeof authorizeRetention !== 'function') throw new TypeError('Invalid retention policy');
+    this.#journal = journal; this.#authority = authority; this.#tenantId = tenantId; this.#authorizeRetention = authorizeRetention;
+  }
+  #auth(token, permission = 'read') { return this.#authority.authenticate(token, {tenantId:this.#tenantId, permission}); }
+  #visible(entry, identity) { return entry.tenantId === identity.tenantId && (identity.permissions.includes('admin') || entry.subject === identity.subject); }
+  #view(entry) {
+    if (!['prepared', 'dispatched', 'confirmed', 'reconciliation_required'].includes(entry.status)) throw new Error('Invalid effect status');
+    return {id:slot(entry.tenantId, entry.effectKey), status:entry.status, retained:!!entry.retention,
+      bound:!!entry.binding, retryPresent:!!entry.retry, reconciliationRecorded:!!entry.reconciliation,
+      claimRecoveryRecorded:!!entry.claimRecovery, expectedDigest:digest(entry), remoteAbsenceProven:false};
+  }
+  async list({token, limit = 25, cursor, includeRetained = false} = {}) {
+    const identity = this.#auth(token);
+    if (!Number.isInteger(limit) || limit < 1 || limit > 100 || typeof includeRetained !== 'boolean') throw new TypeError('Invalid page options');
+    if (cursor !== undefined && (!cursor || Object.keys(cursor).sort().join() !== 'after,snapshotDigest' || !/^[a-f0-9]{64}$/.test(cursor.after) || !/^[a-f0-9]{64}$/.test(cursor.snapshotDigest))) throw new TypeError('Invalid cursor');
+    const snapshot = await this.#journal.snapshot(); this.#auth(token);
+    const entries = Object.values(snapshot).filter(e => this.#visible(e, identity));
+    const snapshotDigest = digest({identity, includeRetained, entries});
+    if (cursor && cursor.snapshotDigest !== snapshotDigest) throw new Error('Journal snapshot changed');
+    const views = entries.filter(e => includeRetained || !e.retention).map(e => this.#view(e)).sort((a,b) => a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
+    if (cursor && !views.some(e => e.id === cursor.after)) throw new Error('Invalid cursor');
+    const remaining = views.filter(e => !cursor || e.id > cursor.after), page = remaining.slice(0, limit);
+    return {entries:page, snapshotDigest, next:remaining.length > limit ? {after:page.at(-1).id, snapshotDigest} : null, remoteAbsenceProven:false};
+  }
+  async inspect(effectKey, {token} = {}) {
+    const identity = this.#auth(token);
+    const entry = await this.#journal.get({tenantId:this.#tenantId, effectKey}); this.#auth(token);
+    if (!entry || !this.#visible(entry, identity)) throw new Error('Effect unavailable');
+    return this.#view(entry);
+  }
+  async retain(effectKey, {token, expectedDigest, reviewId, decisionId} = {}) {
+    const identity = this.#auth(token, 'admin');
+    required(expectedDigest, 'expectedDigest'); required(reviewId, 'reviewId'); required(decisionId, 'decisionId');
+    if (!this.#authorizeRetention) throw new Error('Retention policy required');
+    const entry = await this.#journal.get({tenantId:this.#tenantId, effectKey}); this.#auth(token, 'admin');
+    if (!entry || !this.#visible(entry, identity) || digest(entry) !== expectedDigest) throw new Error('EFFECT_REVIEW_CONFLICT');
+    const guard = async () => {
+      this.#auth(token, 'admin');
+      const allowed = await this.#authorizeRetention({action:'retain-effect', identity:clone(identity), entry:clone(entry), reviewId, decisionId, expectedDigest});
+      this.#auth(token, 'admin'); return allowed === true;
+    };
+    if (await guard() !== true) throw new Error('EFFECT_RETENTION_DENIED');
+    const retained = await this.#journal.retain({expectedEntry:entry, reviewId, decisionId, subject:identity.subject, beforeCommit:guard});
+    this.#auth(token, 'admin'); return this.#view(retained);
+  }
+}

package/src/encrypted-state.js

@@ -12,7 +12,12 @@ const keyCopy = key => {
 };
 
 /** Encrypt live snapshots and temporary files while retaining local transaction semantics. */
-export function createEncryptedStateStore(path, {key, keyId, tenantId, readKeys = []} = {}) {
+export function createEncryptedStateStore(path, options = {}) {
+  const {key, keyId, tenantId, readKeys = [], keyProvider} = options;
+  if (keyProvider !== undefined) {
+    if (['key', 'keyId', 'readKeys'].some(field => Object.hasOwn(options, field))) throw new TypeError('Select static keys or a host key provider');
+    return new TransactionalStateStore(path, {codec: createProviderEncryptedStateCodec({keyProvider, tenantId})});
+  }
   id(keyId, 'state key id', 128); id(tenantId, 'state storage context', 256);
   if (!Array.isArray(readKeys) || readKeys.length > 32) throw new Error('Invalid state read-key ring');
   const keys = new Map([[keyId, keyCopy(key)]]);
@@ -33,3 +38,60 @@ export function createEncryptedStateStore(path, {key, keyId, tenantId, readKeys
   });
   return new TransactionalStateStore(path, {codec});
 }
+
+/** Host callback is trusted, asynchronous and consulted anew for every codec operation. */
+export function createProviderEncryptedStateCodec({keyProvider, tenantId} = {}) {
+  id(tenantId, 'state storage context', 256);
+  if (!keyProvider || typeof keyProvider.getKeyRing !== 'function') throw new TypeError('Host key provider required');
+  return Object.freeze({
+    async encode(state) {
+      const backup = await createStateBackup({load: async () => state});
+      return encryptStateBackupWithProvider(backup, {keyProvider, tenantId});
+    },
+    async decode(envelope) {
+      return (await decryptStateBackupWithProvider(envelope, {keyProvider, tenantId})).state;
+    }
+  });
+}
+
+// No raw callback error/cause escapes: a credential adapter may include secrets in it.
+async function withProviderKey({keyProvider, tenantId}, operation, selected, use) {
+  id(tenantId, 'state storage context', 256);
+  if (!keyProvider || typeof keyProvider.getKeyRing !== 'function') throw new TypeError('Host key provider required');
+  // Reject foreign metadata before asking the host to resolve any key.
+  if (operation === 'read') id(selected, 'state key id', 128);
+  const copies = [];
+  let chosen;
+  try {
+    const ring = await keyProvider.getKeyRing(Object.freeze({tenantId, operation}));
+    id(ring?.currentKeyId, 'current key id', 128);
+    if (!Array.isArray(ring.keys) || ring.keys.length < 1 || ring.keys.length > 33) throw new Error();
+    const keys = new Map();
+    for (const entry of ring.keys) {
+      id(entry?.keyId, 'read key id', 128);
+      if (keys.has(entry.keyId) || !['active', 'read-only', 'revoked'].includes(entry.status)) throw new Error();
+      if (entry.status === 'active' && entry.keyId !== ring.currentKeyId) throw new Error();
+      const secret = entry.status === 'revoked' ? null : keyCopy(entry.key);
+      if (secret) copies.push(secret);
+      keys.set(entry.keyId, {secret, status: entry.status});
+    }
+    const keyId = operation === 'write' ? ring.currentKeyId : selected;
+    const entry = keys.get(keyId);
+    if (!entry?.secret || (operation === 'write' && entry.status !== 'active')) throw new Error();
+    chosen = {key: entry.secret, keyId, tenantId};
+  } catch {
+    for (const key of copies) key.fill(0);
+    throw new Error('Encryption key provider unavailable or key denied');
+  }
+  try { return await use(chosen); }
+  finally { for (const key of copies) key.fill(0); }
+}
+
+/** Same v1 envelope as the static-key API; policy/key material never enters it. */
+export async function encryptStateBackupWithProvider(backup, options = {}) {
+  return withProviderKey(options, 'write', undefined, key => encryptStateBackup(backup, key));
+}
+export async function decryptStateBackupWithProvider(envelope, options = {}) {
+  if (envelope?.tenantId !== options.tenantId) throw new Error('Encrypted backup context mismatch');
+  return withProviderKey(options, 'read', envelope?.keyId, key => decryptStateBackup(envelope, key));
+}