@emilia-protocol/gate 0.1.0 → 0.6.0

package/eg1-conformance.js

@@ -0,0 +1,206 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * EG-1 Conformance — the binary artifact that turns "we adopted EMILIA Gate"
+ * from a claim into a test result.
+ *
+ * The question EG-1 answers: *does your integration actually ENFORCE the gate,
+ * or are you only claiming it?* An integration earns EG-1 only if it
+ * demonstrably:
+ *   1. refuses a high-risk action with NO receipt (428);
+ *   2. refuses a software-tier receipt on a Class-A action;
+ *   3. refuses when the observed execution drifts from the authorized fields;
+ *   4. RUNS the action for a valid Class-A/quorum receipt;
+ *   5. refuses a replay of the same receipt;
+ *   6. refuses a tampered receipt;
+ *   7. emits an execution proof bound to the authorization decision;
+ *   8. produces a reliance packet whose verdict is "rely".
+ *
+ * This module is pure (no dependency on index.js, so no import cycle): it owns a
+ * throwaway issuer keypair, mints the scenario receipts, and drives any
+ * "subject" through the eight checks. A subject is an async `invoke` function
+ * representing one attempt at the guarded dangerous action:
+ *
+ *   invoke({ receipt, observedAction }) -> {
+ *     allowed: boolean, status: number, reason: string,
+ *     // present only on an allowed run:
+ *     decisionHash?: string, execution?: { authorizes_decision }, packet?: { verdict }
+ *   }
+ *
+ * For integrations built on @emilia-protocol/gate, `makeGateInvoke(gate, ...)`
+ * produces a conformant `invoke` from `gate.run()`. Custom integrations (an HTTP
+ * service, a different language) implement `invoke` themselves and configure
+ * their gate to trust `harness.publicKey` for the run.
+ */
+import crypto from 'node:crypto';
+
+export const EG1_VERSION = 'EG-1';
+
+// Same sorted-key canonical JSON the receipt signature is computed over.
+const canon = (v) => (v == null ? JSON.stringify(v)
+  : Array.isArray(v) ? `[${v.map(canon).join(',')}]`
+    : typeof v === 'object' ? `{${Object.keys(v).sort().map((k) => JSON.stringify(k) + ':' + canon(v[k])).join(',')}}`
+      : JSON.stringify(v));
+
+// The default high-risk action EG-1 exercises: a Class-A money movement, which
+// the default gate manifest guards (selector { protocol:'mcp', tool:'release_payment' }).
+export const EG1_DEFAULT_SELECTOR = Object.freeze({ protocol: 'mcp', tool: 'release_payment' });
+export const EG1_DEFAULT_ACTION = Object.freeze({
+  action_type: 'payment.release',
+  amount_usd: 40000,
+  currency: 'USD',
+  payment_instruction_id: 'pi_eg1_40000',
+  beneficiary_account_hash: 'sha256:eg1-beneficiary',
+});
+
+export const EG1_CHECKS = Object.freeze([
+  { id: 'missing_receipt_refused', title: 'missing receipt → 428' },
+  { id: 'software_on_classA_refused', title: 'software receipt on Class-A action → refused' },
+  { id: 'execution_drift_refused', title: 'observed execution drift → refused' },
+  { id: 'valid_classA_runs', title: 'valid Class-A/quorum receipt → runs' },
+  { id: 'replay_refused', title: 'same receipt replay → refused' },
+  { id: 'tampered_refused', title: 'tampered receipt → refused' },
+  { id: 'execution_proof_binds', title: 'execution proof binds to authorization decision' },
+  { id: 'reliance_packet_rely', title: 'reliance packet returns verdict "rely"' },
+]);
+
+/**
+ * Create an EG-1 harness: a throwaway issuer key + a receipt minter for the
+ * scenarios. Configure the subject's gate to trust `publicKey` for the run.
+ */
+export function createEg1Harness({ now = Date.now, action = EG1_DEFAULT_ACTION, idPrefix = 'eg1' } = {}) {
+  const { publicKey, privateKey } = crypto.generateKeyPairSync('ed25519');
+  const pub = publicKey.export({ type: 'spki', format: 'der' }).toString('base64url');
+  let counter = 0;
+  const nowMs = () => (typeof now === 'function' ? now() : now);
+
+  /**
+   * Mint a scenario receipt.
+   * @param {object} o
+   * @param {'allow'|'allow_with_signoff'} [o.outcome] 'allow'=software, 'allow_with_signoff'=Class-A
+   * @param {object} [o.quorum] a quorum block (signers/threshold) -> quorum tier
+   * @param {object} [o.tamper] fields assigned to the claim AFTER signing (breaks the signature)
+   */
+  function mint({ outcome = 'allow_with_signoff', quorum = null, tamper = null, extra = {} } = {}) {
+    const payload = {
+      receipt_id: `${idPrefix}_${++counter}`,
+      subject: 'agent:eg1-conformance',
+      issuer: 'ep:org:eg1',
+      created_at: new Date(nowMs()).toISOString(),
+      claim: {
+        ...action,
+        outcome,
+        approver: 'ep:approver:eg1',
+        ...(quorum ? { quorum } : {}),
+        ...extra,
+      },
+    };
+    const value = crypto.sign(null, Buffer.from(canon(payload), 'utf8'), privateKey).toString('base64url');
+    const receipt = { '@version': 'EP-RECEIPT-v1', payload, signature: { algorithm: 'Ed25519', value } };
+    if (tamper) Object.assign(receipt.payload.claim, tamper); // tamper AFTER signing -> signature no longer binds
+    return receipt;
+  }
+
+  return { publicKey: pub, mint, action, now: nowMs };
+}
+
+/**
+ * Adapt an @emilia-protocol/gate instance into an EG-1 `invoke`. The gate must
+ * have been built trusting the harness public key. Uses gate.run() so the
+ * execution proof + reliance packet are produced on the allowed path.
+ */
+export function makeGateInvoke(gate, { selector = EG1_DEFAULT_SELECTOR, action = EG1_DEFAULT_ACTION } = {}) {
+  if (!gate || typeof gate.run !== 'function') {
+    throw new Error('makeGateInvoke requires an EMILIA Gate instance (with .run)');
+  }
+  return async ({ receipt, observedAction }) => {
+    const out = await gate.run(
+      { selector, receipt, observedAction: observedAction ?? action },
+      async () => ({ eg1: 'side-effect-ran' }),
+    );
+    if (!out.ok) {
+      return { allowed: false, status: out.status, reason: out.authorization?.reason ?? 'refused' };
+    }
+    return {
+      allowed: true,
+      status: 200,
+      reason: out.authorization?.reason ?? 'allow',
+      decisionHash: out.authorization?.evidence?.hash ?? null,
+      execution: out.execution ?? null,
+      packet: out.packet ?? null,
+    };
+  };
+}
+
+const pick = (r) => ({ allowed: !!r.allowed, status: r.status ?? null, reason: r.reason ?? null });
+
+/**
+ * Drive a subject through the eight EG-1 checks and return a JSON report.
+ * @param {object} o
+ * @param {(scenario:object)=>Promise<object>} o.invoke the integration under test
+ * @param {object} o.harness from createEg1Harness()
+ * @param {object} [o.action] the high-risk action (defaults to the harness action)
+ */
+export async function runEg1({ invoke, harness, action } = {}) {
+  if (typeof invoke !== 'function') throw new Error('runEg1 requires an invoke(scenario) function');
+  if (!harness || typeof harness.mint !== 'function') throw new Error('runEg1 requires a harness from createEg1Harness()');
+  const act = action || harness.action || EG1_DEFAULT_ACTION;
+  const observed = act;
+  const drift = { ...act, amount_usd: Number(act.amount_usd ?? 0) + 1 };
+
+  const results = {};
+  const set = (id, pass, observed_) => { results[id] = { pass: !!pass, observed: observed_ }; };
+
+  // 1. missing receipt → 428
+  let r = await invoke({ receipt: null, observedAction: observed });
+  set('missing_receipt_refused', !r.allowed && r.status === 428, pick(r));
+
+  // 2. software receipt on a Class-A action → refused
+  r = await invoke({ receipt: harness.mint({ outcome: 'allow' }), observedAction: observed });
+  set('software_on_classA_refused', !r.allowed && /assurance/i.test(r.reason || ''), pick(r));
+
+  // 3. observed execution drift → refused
+  r = await invoke({ receipt: harness.mint({ outcome: 'allow_with_signoff' }), observedAction: drift });
+  set('execution_drift_refused', !r.allowed && /binding/i.test(r.reason || ''), pick(r));
+
+  // 4. valid Class-A receipt → runs (capture for 5/7/8)
+  const valid = harness.mint({ outcome: 'allow_with_signoff' });
+  r = await invoke({ receipt: valid, observedAction: observed });
+  const validAllowed = r.allowed === true;
+  set('valid_classA_runs', validAllowed, pick(r));
+
+  // 7. execution proof binds to the authorization decision
+  const boundOk = validAllowed
+    && !!r.execution && !!r.execution.authorizes_decision
+    && !!r.decisionHash && r.execution.authorizes_decision === r.decisionHash;
+  set('execution_proof_binds', boundOk, {
+    authorizes_decision: r.execution?.authorizes_decision ?? null,
+    decision_hash: r.decisionHash ?? null,
+  });
+
+  // 8. reliance packet verdict "rely"
+  set('reliance_packet_rely', validAllowed && String(r.packet?.verdict || '').toLowerCase() === 'rely', {
+    verdict: r.packet?.verdict ?? null,
+  });
+
+  // 5. same receipt replay → refused
+  r = await invoke({ receipt: valid, observedAction: observed });
+  set('replay_refused', !r.allowed && /replay/i.test(r.reason || ''), pick(r));
+
+  // 6. tampered receipt → refused
+  r = await invoke({ receipt: harness.mint({ outcome: 'allow_with_signoff', tamper: { amount_usd: 9_999_999 } }), observedAction: observed });
+  set('tampered_refused', !r.allowed && r.status === 428, pick(r));
+
+  const checks = EG1_CHECKS.map((c) => ({ id: c.id, title: c.title, ...results[c.id] }));
+  const passedCount = checks.filter((c) => c.pass).length;
+  const passed = passedCount === checks.length;
+  return {
+    standard: EG1_VERSION,
+    passed,
+    badge: passed ? 'EG-1 Enforced' : 'EG-1 not earned',
+    summary: { passed: passedCount, total: checks.length },
+    checks,
+    generated_at: new Date(harness.now ? harness.now() : Date.now()).toISOString(),
+  };
+}
+
+export default { EG1_VERSION, EG1_CHECKS, EG1_DEFAULT_ACTION, EG1_DEFAULT_SELECTOR, createEg1Harness, makeGateInvoke, runEg1 };

package/eg1.mjs

@@ -0,0 +1,40 @@
+/**
+ * EG-1 Conformance — runnable proof. Run: node eg1.mjs [--json]
+ *
+ * Self-certifies the reference EMILIA Gate against the eight EG-1 checks. An
+ * adopter earns EG-1 by pointing this harness at THEIR integration: build your
+ * gate trusting `harness.publicKey`, pass it to gateConformance(), and ship the
+ * JSON report + the "EG-1 Enforced" badge.
+ *
+ *   import { createEg1Harness, gateConformance } from '@emilia-protocol/gate';
+ *   const harness = createEg1Harness();
+ *   const gate = createTrustedActionFirewall({ trustedKeys: [harness.publicKey] });
+ *   const report = await gateConformance({ gate, harness });
+ *
+ * Exit code is 0 only if all eight checks pass — CI-friendly.
+ * @license Apache-2.0
+ */
+import { gateConformanceSelfTest } from './index.js';
+
+const report = await gateConformanceSelfTest();
+
+if (process.argv.includes('--json')) {
+  // eslint-disable-next-line no-console
+  console.log(JSON.stringify(report, null, 2));
+  process.exit(report.passed ? 0 : 1);
+}
+
+const G = (s) => `\x1b[32m${s}\x1b[0m`;
+const R = (s) => `\x1b[31m${s}\x1b[0m`;
+const line = (s) => console.log(s);
+
+line('='.repeat(64));
+line('  EG-1 Conformance — does this integration ENFORCE EMILIA Gate?');
+line('='.repeat(64));
+for (const c of report.checks) {
+  line(`  ${c.pass ? G('PASS') : R('FAIL')}  ${c.title}`);
+}
+line('  ' + '-'.repeat(60));
+line(`  ${report.passed ? G(`✓ ${report.badge}`) : R(`✗ ${report.badge}`)}  (${report.summary.passed}/${report.summary.total})`);
+line('='.repeat(64));
+process.exit(report.passed ? 0 : 1);

package/execution-binding.js

@@ -0,0 +1,98 @@
+// SPDX-License-Identifier: Apache-2.0
+// Execution-field binding for EMILIA Gate. This is the executor-side control
+// that prevents "the signed claim said X, the system mutated Y".
+
+import crypto from 'node:crypto';
+
+export const EXECUTION_BINDING_VERSION = 'EP-GATE-EXECUTION-BINDING-v1';
+
+export function canonicalize(v) {
+  if (v === null || v === undefined) return JSON.stringify(v);
+  if (Array.isArray(v)) return `[${v.map(canonicalize).join(',')}]`;
+  if (typeof v === 'object') {
+    return `{${Object.keys(v).sort().map((k) => JSON.stringify(k) + ':' + canonicalize(v[k])).join(',')}}`;
+  }
+  return JSON.stringify(v);
+}
+
+export function hashCanonical(v) {
+  return crypto.createHash('sha256').update(canonicalize(v)).digest('hex');
+}
+
+function hasValue(v) {
+  return v !== undefined && v !== null;
+}
+
+function normalize(v) {
+  if (Array.isArray(v)) return [...new Set(v.map((x) => String(x)))].sort();
+  if (v && typeof v === 'object') {
+    return Object.fromEntries(Object.keys(v).sort().map((k) => [k, normalize(v[k])]));
+  }
+  return v;
+}
+
+function equalValue(a, b) {
+  return hashCanonical(normalize(a)) === hashCanonical(normalize(b));
+}
+
+export function materialFieldsFor(requirement) {
+  const fields = requirement?.execution_binding?.required_fields;
+  return Array.isArray(fields) ? [...new Set(fields.filter(Boolean))] : [];
+}
+
+/**
+ * Verifies that the signed claim and the executor-observed mutation fields
+ * match for the action pack. The executor must pass `observedAction` from the
+ * system of record, not from the agent request body.
+ */
+export function verifyExecutionBinding({ requirement, receipt, observedAction } = {}) {
+  const requiredFields = materialFieldsFor(requirement);
+  if (requiredFields.length === 0) {
+    return { ok: true, required: false, required_fields: [], signed_hash: null, observed_hash: null };
+  }
+
+  const signed = receipt?.payload?.claim || {};
+  const observed = observedAction || {};
+  const missingSigned = [];
+  const missingObserved = [];
+  const mismatched = [];
+  const signedValues = {};
+  const observedValues = {};
+
+  for (const field of requiredFields) {
+    const expected = signed[field];
+    const actual = observed[field];
+    if (!hasValue(expected)) {
+      missingSigned.push(field);
+      continue;
+    }
+    signedValues[field] = normalize(expected);
+    if (!hasValue(actual)) {
+      missingObserved.push(field);
+      continue;
+    }
+    observedValues[field] = normalize(actual);
+    if (!equalValue(expected, actual)) mismatched.push(field);
+  }
+
+  return {
+    '@version': EXECUTION_BINDING_VERSION,
+    ok: missingSigned.length === 0 && missingObserved.length === 0 && mismatched.length === 0,
+    required: true,
+    required_fields: requiredFields,
+    missing_signed_fields: missingSigned,
+    missing_observed_fields: missingObserved,
+    mismatched_fields: mismatched,
+    signed_hash: hashCanonical(signedValues),
+    observed_hash: hashCanonical(observedValues),
+    note: 'Executor MUST provide observedAction from the system of record; request-body fields are not a trust source.',
+  };
+}
+
+export default {
+  EXECUTION_BINDING_VERSION,
+  canonicalize,
+  hashCanonical,
+  materialFieldsFor,
+  verifyExecutionBinding,
+};

package/index.js

@@ -21,7 +21,7 @@
  * adds the three things a firewall needs over a bare verifier: assurance-tier
  * enforcement, replay defense, and the evidence log. Fails closed.
  */
-import {
+const {
   verifyEmiliaReceipt,
   receiptChallenge,
   receiptRequiredHeader,
@@ -29,11 +29,27 @@ import {
   findActionRequirement,
   RECEIPT_REQUIRED_STATUS,
   RECEIPT_REQUIRED_HEADER,
-} from '../require-receipt/index.js';
+} = await import('@emilia-protocol/require-receipt').catch(() => import('../require-receipt/index.js'));
 import { MemoryConsumptionStore } from './store.js';
 import { createEvidenceLog } from './evidence.js';
+import { DEFAULT_GATE_MANIFEST, HIGH_RISK_ACTION_PACKS, createDefaultActionRiskManifest } from './action-packs.js';
+import { hashCanonical, verifyExecutionBinding } from './execution-binding.js';
+import { buildReliancePacket } from './reliance-packet.js';
+import { createEg1Harness, makeGateInvoke, runEg1, EG1_DEFAULT_SELECTOR } from './eg1-conformance.js';
+import { createKeyRegistry, asKeyRegistry } from './key-registry.js';
+import { classifyRetention, buildRetentionExport } from './retention.js';
 
 export { MemoryConsumptionStore, createEvidenceLog };
+export { createDurableConsumptionStore, createMemoryBackend } from './store.js';
+export { createKeyRegistry, asKeyRegistry } from './key-registry.js';
+export { classifyRetention, buildRetentionExport, RETENTION_EXPORT_VERSION } from './retention.js';
+export { DEFAULT_GATE_MANIFEST, HIGH_RISK_ACTION_PACKS, createDefaultActionRiskManifest };
+export { EXECUTION_BINDING_VERSION, canonicalize, hashCanonical, materialFieldsFor, verifyExecutionBinding } from './execution-binding.js';
+export { RELIANCE_PACKET_VERSION, buildReliancePacket } from './reliance-packet.js';
+export {
+  EG1_VERSION, EG1_CHECKS, EG1_DEFAULT_ACTION, EG1_DEFAULT_SELECTOR,
+  createEg1Harness, makeGateInvoke, runEg1,
+} from './eg1-conformance.js';
 export const ASSURANCE_TIERS = ['software', 'class_a', 'quorum'];
 const TIER_RANK = { software: 0, class_a: 1, quorum: 2 };
 
@@ -64,8 +80,15 @@ export function receiptAssuranceTier(doc) {
  * @param {object} [opts.store]         consumption store (default in-memory)
  * @param {object} [opts.log]           evidence log (default in-memory, hash-chained)
  * @param {boolean} [opts.allowInlineKey=false] accept the receipt's own key (integrity, NOT trust)
+ * @param {object} [opts.keyRegistry] a key registry (createKeyRegistry) for rotation + revocation;
+ *   if given it supersedes trustedKeys — a receipt is verified only against keys valid (and not
+ *   revoked) at its issuance time.
  */
-export function createGate({ manifest = null, trustedKeys = [], maxAgeSec = 900, store, log, allowInlineKey = false, allowEphemeralStore = false, strictEvidence = true, now = Date.now } = {}) {
+export function createGate({ manifest = null, trustedKeys = [], maxAgeSec = 900, store, log, allowInlineKey = false, allowEphemeralStore = false, strictEvidence = true, now = Date.now, keyRegistry = null } = {}) {
+  // Production key custody: a registry (rotation + revocation) supersedes a flat
+  // trustedKeys list. A flat list is coerced to an always-valid registry, so
+  // existing callers are unchanged.
+  const registry = keyRegistry ? asKeyRegistry(keyRegistry) : (trustedKeys.length ? asKeyRegistry(trustedKeys) : null);
   if (manifest) {
     const m = validateActionRiskManifest(manifest);
     if (!m.ok) throw new Error('EMILIA Gate: invalid action-risk manifest: ' + m.errors.join('; '));
@@ -88,10 +111,11 @@ export function createGate({ manifest = null, trustedKeys = [], maxAgeSec = 900,
   }
   const evidence = log || createEvidenceLog({ strict: strictEvidence });
 
-  async function check({ selector = {}, receipt = null } = {}) {
+  async function check({ selector = {}, receipt = null, observedAction = null, consumptionMode = 'consume' } = {}) {
     const requirement = manifest ? findActionRequirement(manifest, selector) : null;
     const action = requirement?.action_type || selector.action_type || selector.action || null;
     const requiredTier = requirement?.assurance_class || selector.assurance_class || 'software';
+    const observed = observedAction || selector.observedAction || selector.actionDetails || null;
 
     async function decide(allow, status, reason, extra = {}) {
       const entry = {
@@ -105,6 +129,7 @@ export function createGate({ manifest = null, trustedKeys = [], maxAgeSec = 900,
         required_tier: requiredTier,
         receipt_id: receipt?.payload?.receipt_id ?? null,
         subject: receipt?.payload?.subject ?? null,
+        observed_action_hash: observed ? hashCanonical(observed) : null,
         ...extra,
       };
       let record;
@@ -144,8 +169,14 @@ export function createGate({ manifest = null, trustedKeys = [], maxAgeSec = 900,
     if (!receipt) {
       return decide(false, RECEIPT_REQUIRED_STATUS, 'receipt_required');
     }
-    // Signature / freshness / action-binding / outcome.
-    const v = verifyEmiliaReceipt(receipt, { trustedKeys, allowInlineKey, action, maxAgeSec });
+    // Signature / freshness / action-binding / outcome. Production key custody:
+    // resolve the issuer keys valid (and not revoked) at THIS receipt's issuance
+    // time. A revoked or out-of-window key is excluded, so its signature does not
+    // verify and the action is refused (fail closed).
+    const effectiveKeys = registry
+      ? registry.keysValidAt(receipt?.payload?.created_at)
+      : trustedKeys;
+    const v = verifyEmiliaReceipt(receipt, { trustedKeys: effectiveKeys, allowInlineKey, action, maxAgeSec });
     if (!v.ok) {
       return decide(false, RECEIPT_REQUIRED_STATUS, `receipt_rejected:${v.reason}`, { rejected: v });
     }
@@ -154,6 +185,13 @@ export function createGate({ manifest = null, trustedKeys = [], maxAgeSec = 900,
     if ((TIER_RANK[have] ?? 0) < (TIER_RANK[requiredTier] ?? 0)) {
       return decide(false, RECEIPT_REQUIRED_STATUS, 'assurance_too_low', { have_tier: have, need_tier: requiredTier });
     }
+    // The high-risk action packs define material fields that must be observed
+    // by the executor from the system of record. A signed, harmless-looking
+    // claim cannot authorize a different real mutation.
+    const executionBinding = verifyExecutionBinding({ requirement, receipt, observedAction: observed });
+    if (!executionBinding.ok) {
+      return decide(false, RECEIPT_REQUIRED_STATUS, 'execution_binding_failed', { execution_binding: executionBinding, have_tier: have });
+    }
     // One-time consumption (replay defense). Require a stable, issuer-generated
     // receipt_id — never fall back to a content hash, whose canonicalization can
     // differ across language implementations and silently break replay detection
@@ -162,11 +200,21 @@ export function createGate({ manifest = null, trustedKeys = [], maxAgeSec = 900,
     if (!receiptId) {
       return decide(false, RECEIPT_REQUIRED_STATUS, 'receipt_rejected:missing_receipt_id');
     }
-    const fresh = await consumption.consume(receiptId);
+    let fresh;
+    if (consumptionMode === 'reserve') {
+      if (typeof consumption.reserve !== 'function') {
+        return decide(false, RECEIPT_REQUIRED_STATUS, 'consumption_store_lacks_reserve', { consumption_key: receiptId });
+      }
+      fresh = await consumption.reserve(receiptId);
+    } else if (consumptionMode === 'none') {
+      fresh = true;
+    } else {
+      fresh = await consumption.consume(receiptId);
+    }
     if (!fresh) {
       return decide(false, RECEIPT_REQUIRED_STATUS, 'replay_refused', { consumption_key: receiptId });
     }
-    return decide(true, 200, 'allow', { signer: v.signer, outcome: v.outcome, have_tier: have });
+    return decide(true, 200, 'allow', { signer: v.signer, outcome: v.outcome, have_tier: have, execution_binding: executionBinding, consumption_mode: consumptionMode });
   }
 
   /** Express/Connect middleware: refuse the route unless a sufficient receipt is present. */
@@ -180,7 +228,10 @@ export function createGate({ manifest = null, trustedKeys = [], maxAgeSec = 900,
       const hdr = req.headers?.['x-emilia-receipt'];
       if (hdr) { try { doc = JSON.parse(Buffer.from(hdr, 'base64').toString('utf8')); } catch { /* fallthrough */ } }
       if (!doc && req.body?.emilia_receipt) doc = req.body.emilia_receipt;
-      const out = await check({ selector, receipt: doc });
+      const observedAction = typeof opts.observedAction === 'function'
+        ? opts.observedAction(req)
+        : (opts.observedAction || req.emiliaObservedAction || null);
+      const out = await check({ selector, receipt: doc, observedAction });
       if (!out.allow) {
         res.setHeader(RECEIPT_REQUIRED_HEADER, out.header);
         return res.status(out.status).json(out.challenge);
@@ -196,7 +247,7 @@ export function createGate({ manifest = null, trustedKeys = [], maxAgeSec = 900,
    * commits to the exact authorization decision (`authorizes_decision` = that
    * decision's evidence hash), so authorization and execution are one chain.
    */
-  async function recordExecution({ authorization, outcome = 'executed', detail } = {}) {
+  async function recordExecution({ authorization, outcome = 'executed', detail, observedAction = null, executionBinding = null } = {}) {
     const auth = authorization?.evidence || authorization || {};
     return evidence.record({
       kind: 'execution',
@@ -205,10 +256,47 @@ export function createGate({ manifest = null, trustedKeys = [], maxAgeSec = 900,
       action: authorization?.action ?? auth.action ?? null,
       receipt_id: auth.receipt_id ?? null,
       outcome, // 'executed' | 'failed'
+      observed_action_hash: observedAction ? hashCanonical(observedAction) : null,
+      execution_binding: executionBinding || authorization?.evidence?.execution_binding || authorization?.execution_binding || null,
       ...(detail !== undefined ? { detail } : {}),
     });
   }
 
+  /**
+   * Recommended end-to-end path. Reserves the receipt, runs the side effect,
+   * commits one-time consumption only after success, and records execution.
+   * If the side effect throws, the reservation is released so the approval can
+   * be retried safely.
+   */
+  async function run({ selector = {}, receipt = null, observedAction = null } = {}, fn, opts = {}) {
+    if (typeof fn !== 'function') throw new Error('EMILIA Gate run(): fn is required');
+    const authorization = await check({ selector, receipt, observedAction, consumptionMode: 'reserve' });
+    if (!authorization.allow) {
+      return { ok: false, status: authorization.status, body: authorization.challenge, authorization };
+    }
+    const receiptId = authorization.evidence?.receipt_id;
+    let actionRan = false;
+    try {
+      const result = await fn(authorization);
+      actionRan = true;
+      if (typeof consumption.commit === 'function') await consumption.commit(receiptId);
+      if (opts.recordExecution === false) return { ok: true, result, authorization, execution: null, packet: null };
+      const execution = await recordExecution({ authorization, outcome: 'executed', observedAction });
+      return { ok: true, result, authorization, execution, packet: reliancePacket({ authorization, execution }) };
+    } catch (e) {
+      if (!actionRan && typeof consumption.release === 'function') await consumption.release(receiptId);
+      if (opts.recordExecution !== false) {
+        await recordExecution({
+          authorization,
+          outcome: 'failed',
+          detail: actionRan ? `post_execution_failure:${String(e?.message ?? e)}` : String(e?.message ?? e),
+          observedAction,
+        });
+      }
+      throw e;
+    }
+  }
+
   /**
    * Wrap any function so it runs only behind a passing gate check, and (unless
    * disabled) emits an execution receipt after it runs — the full firewall loop:
@@ -218,26 +306,97 @@ export function createGate({ manifest = null, trustedKeys = [], maxAgeSec = 900,
     return async function guarded(...args) {
       const selector = typeof opts.selector === 'function' ? opts.selector(...args) : (opts.selector || {});
       const receipt = typeof opts.receipt === 'function' ? opts.receipt(...args) : (opts.receipt ?? null);
-      const out = await check({ selector, receipt });
-      if (!out.allow) {
-        const e = new Error(`EMILIA Gate refused (${out.reason})`);
+      const observedAction = typeof opts.observedAction === 'function'
+        ? opts.observedAction(...args)
+        : (opts.observedAction || selector.observedAction || null);
+      const out = await run({ selector, receipt, observedAction }, () => fn(...args), { recordExecution: opts.recordExecution });
+      if (!out.ok) {
+        const e = new Error(`EMILIA Gate refused (${out.authorization.reason})`);
         e.code = 'EMILIA_RECEIPT_REQUIRED';
-        e.gate = out;
-        throw e;
-      }
-      if (opts.recordExecution === false) return fn(...args);
-      try {
-        const result = await fn(...args);
-        await recordExecution({ authorization: out, outcome: 'executed' });
-        return result;
-      } catch (e) {
-        await recordExecution({ authorization: out, outcome: 'failed', detail: String(e?.message ?? e) });
+        e.gate = out.authorization;
         throw e;
       }
+      return out.result;
     };
   }
 
-  return { check, recordExecution, middleware, guard, evidence, store: consumption };
+  function reliancePacket({ authorization, execution = null, binding = null } = {}) {
+    return buildReliancePacket({
+      decision: authorization,
+      execution,
+      evidence,
+      manifest,
+      binding,
+    });
+  }
+
+  /** Retention classification over this gate's evidence log (hot/cold/expired/legal-hold). */
+  function retention(opts = {}) {
+    return classifyRetention(evidence.all(), opts);
+  }
+  /** The auditor/SIEM export manifest for this gate's evidence log. */
+  function retentionExport(opts = {}) {
+    return buildRetentionExport(evidence.all(), opts);
+  }
+
+  return {
+    check, run, recordExecution, middleware, guard, reliancePacket, evidence,
+    store: consumption, keyRegistry: registry, retention, retentionExport,
+  };
+}
+
+export function createTrustedActionFirewall(opts = {}) {
+  const { manifest = createDefaultActionRiskManifest(), ...rest } = opts;
+  return createGate({ ...rest, manifest });
+}
+
+/**
+ * EG-1 conformance for an existing gate. The gate MUST have been built trusting
+ * `harness.publicKey` (otherwise every valid receipt is rejected and the gate
+ * cannot earn EG-1). Returns the EG-1 JSON report.
+ * @param {object} o
+ * @param {object} o.gate     an EMILIA Gate (createGate/createTrustedActionFirewall)
+ * @param {object} o.harness  the harness whose key the gate trusts (createEg1Harness)
+ * @param {object} [o.action] the high-risk action to exercise
+ * @param {object} [o.selector] the manifest selector for that action
+ */
+export async function gateConformance({ gate, harness, action, selector = EG1_DEFAULT_SELECTOR } = {}) {
+  if (!gate || typeof gate.run !== 'function') {
+    throw new Error('gateConformance requires a gate built trusting harness.publicKey');
+  }
+  if (!harness) throw new Error('gateConformance requires the harness whose key the gate trusts');
+  const act = action || harness.action;
+  const invoke = makeGateInvoke(gate, { selector, action: act });
+  return runEg1({ invoke, harness, action: act });
+}
+
+/**
+ * Self-certify the reference gate: build a default Trusted Action Firewall that
+ * trusts a fresh EG-1 harness key, then run all eight checks. This is the
+ * canonical "EMILIA Gate earns EG-1" proof — runnable as a CLI (`eg1.mjs`),
+ * shown on /gate, and the template an adopter copies for their integration.
+ */
+export async function gateConformanceSelfTest({ now } = {}) {
+  const harness = createEg1Harness({ now });
+  const gate = createTrustedActionFirewall({ trustedKeys: [harness.publicKey], now });
+  return gateConformance({ gate, harness });
 }
 
-export default { createGate, receiptAssuranceTier, MemoryConsumptionStore, createEvidenceLog, ASSURANCE_TIERS };
+export default {
+  createGate,
+  createTrustedActionFirewall,
+  receiptAssuranceTier,
+  MemoryConsumptionStore,
+  createEvidenceLog,
+  ASSURANCE_TIERS,
+  DEFAULT_GATE_MANIFEST,
+  HIGH_RISK_ACTION_PACKS,
+  gateConformance,
+  gateConformanceSelfTest,
+  createEg1Harness,
+  runEg1,
+  createKeyRegistry,
+  asKeyRegistry,
+  classifyRetention,
+  buildRetentionExport,
+};