@synoi/gateway-lite 0.1.0

package/dist/gap/store.js

@@ -0,0 +1,1063 @@
+"use strict";
+/**
+ * gap/store.ts - SQLite persistence for GAP objects.
+ *
+ * Shares the synoi.db file with the rest of the gateway. Indexed for
+ * sub-ms lookup on hot paths (grant evaluation, workflow runner).
+ *
+ * Tables:
+ *   gap_declarations          — capability declarations (long-lived)
+ *   gap_grants                — capability grants (long-lived, revocable)
+ *   gap_invocations           — capability invocations (short-lived audit)
+ *   gap_workflow_definitions  — workflow templates
+ *   gap_workflow_instances    — workflow runs
+ *   gap_stage_transitions     — workflow state transitions
+ *   gap_channel_events        — channel adapter events
+ *   gap_receipts              — Decision Receipts (also persisted to evidence journal)
+ *   gap_revocations           — revocation events
+ *
+ * V1 scope: L1 revocation only. L2/L3 are tracked in the schema but not
+ * enforced yet (separate ticket).
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CrossTenantRevocationError = void 0;
+exports.saveDeclaration = saveDeclaration;
+exports.getDeclaration = getDeclaration;
+exports.findActiveDeclarationByActor = findActiveDeclarationByActor;
+exports.listActiveDeclarationsMatching = listActiveDeclarationsMatching;
+exports.saveGrant = saveGrant;
+exports.findActiveGrantsForCaller = findActiveGrantsForCaller;
+exports.capabilityMatches = capabilityMatches;
+exports.getGrant = getGrant;
+exports.listActiveGrantsForTenant = listActiveGrantsForTenant;
+exports.revokeGrant = revokeGrant;
+exports.incrementGrantUse = incrementGrantUse;
+exports.saveInvocation = saveInvocation;
+exports.findInvocationByIdempotency = findInvocationByIdempotency;
+exports.findInvocationByKeyAnyCapability = findInvocationByKeyAnyCapability;
+exports.countGrantInvocationsInWindow = countGrantInvocationsInWindow;
+exports.getInvocationReceiptOid = getInvocationReceiptOid;
+exports.saveWorkflowDefinition = saveWorkflowDefinition;
+exports.getWorkflowDefinition = getWorkflowDefinition;
+exports.findActiveWorkflowDefinitions = findActiveWorkflowDefinitions;
+exports.saveWorkflowInstance = saveWorkflowInstance;
+exports.getWorkflowInstance = getWorkflowInstance;
+exports.listWorkflowDefinitions = listWorkflowDefinitions;
+exports.listWorkflowInstances = listWorkflowInstances;
+exports.saveStageTransition = saveStageTransition;
+exports.listStageTransitions = listStageTransitions;
+exports.saveChannelEvent = saveChannelEvent;
+exports.saveReceipt = saveReceipt;
+exports.getReceipt = getReceipt;
+exports.listReceipts = listReceipts;
+exports.queryLedgerReceipts = queryLedgerReceipts;
+exports.getReceiptsByOids = getReceiptsByOids;
+exports.findDenialReceiptForPrincipal = findDenialReceiptForPrincipal;
+exports.saveRevocation = saveRevocation;
+exports.ownerTenantOf = ownerTenantOf;
+exports.assertTenantOwnsTarget = assertTenantOwnsTarget;
+exports.isOidRevoked = isOidRevoked;
+exports.listRevocations = listRevocations;
+exports.listAllTenants = listAllTenants;
+exports.saveBinding = saveBinding;
+exports.getBinding = getBinding;
+exports.findActiveBindingsForCapability = findActiveBindingsForCapability;
+exports.listBindingsForTenant = listBindingsForTenant;
+exports.deactivateBinding = deactivateBinding;
+exports._resetForTesting = _resetForTesting;
+exports._testRawUpdateReceiptBody = _testRawUpdateReceiptBody;
+exports._setQueryOnlyForTesting = _setQueryOnlyForTesting;
+exports.deleteDemoRowsByTenantPrefix = deleteDemoRowsByTenantPrefix;
+exports.saveDemoNdaAcceptance = saveDemoNdaAcceptance;
+exports.getDemoNdaAcceptance = getDemoNdaAcceptance;
+exports.migrateAgpTablesToGap = migrateAgpTablesToGap;
+const better_sqlite3_1 = __importDefault(require("better-sqlite3"));
+const fs = __importStar(require("node:fs"));
+const os = __importStar(require("node:os"));
+const path = __importStar(require("node:path"));
+function dataDir() {
+    return process.env['SYNOI_DATA_DIR'] ?? path.join(os.homedir(), '.synoi');
+}
+let _db = null;
+function db() {
+    if (_db)
+        return _db;
+    const dir = dataDir();
+    fs.mkdirSync(dir, { recursive: true });
+    _db = new better_sqlite3_1.default(path.join(dir, 'synoi.db'));
+    _db.pragma('journal_mode = WAL');
+    _db.exec(`
+    CREATE TABLE IF NOT EXISTS gap_declarations (
+      oid              TEXT PRIMARY KEY,
+      tenant_id        TEXT NOT NULL,
+      actor_type       TEXT NOT NULL,
+      actor_id         TEXT NOT NULL,
+      actor_version    TEXT NOT NULL,
+      capabilities     TEXT NOT NULL,    -- JSON array
+      body             TEXT NOT NULL,    -- full body as JSON
+      created_at_ms    INTEGER NOT NULL,
+      supersedes       TEXT,
+      revoked_at_ms    INTEGER
+    );
+    CREATE INDEX IF NOT EXISTS idx_gap_decl_actor
+      ON gap_declarations(tenant_id, actor_id, revoked_at_ms);
+
+    CREATE TABLE IF NOT EXISTS gap_grants (
+      oid                  TEXT PRIMARY KEY,
+      tenant_id            TEXT NOT NULL,
+      grantee_actor_oid    TEXT NOT NULL,
+      grantee_actor_type   TEXT NOT NULL,
+      capability_pattern   TEXT NOT NULL,   -- JSON array of capability strings
+      body                 TEXT NOT NULL,
+      granted_at_ms        INTEGER NOT NULL,
+      expires_at_ms        INTEGER,
+      revoked_at_ms        INTEGER,
+      uses_count           INTEGER NOT NULL DEFAULT 0,
+      last_used_at_ms      INTEGER
+    );
+    CREATE INDEX IF NOT EXISTS idx_gap_grants_lookup
+      ON gap_grants(tenant_id, grantee_actor_oid, revoked_at_ms, expires_at_ms);
+
+    CREATE TABLE IF NOT EXISTS gap_invocations (
+      oid                  TEXT PRIMARY KEY,
+      tenant_id            TEXT NOT NULL,
+      caller_actor_oid     TEXT NOT NULL,
+      capability           TEXT NOT NULL,
+      grant_oid            TEXT NOT NULL,
+      workflow_instance_oid TEXT,
+      workflow_stage_id    TEXT,
+      idempotency_key      TEXT,
+      body                 TEXT NOT NULL,
+      invoked_at_ms        INTEGER NOT NULL,
+      status               TEXT NOT NULL,   -- ok | denied | failed | pending_workflow
+      receipt_oid          TEXT
+    );
+    CREATE INDEX IF NOT EXISTS idx_gap_inv_tenant
+      ON gap_invocations(tenant_id, invoked_at_ms DESC);
+    CREATE INDEX IF NOT EXISTS idx_gap_inv_workflow
+      ON gap_invocations(workflow_instance_oid);
+    CREATE UNIQUE INDEX IF NOT EXISTS idx_gap_inv_idempotency
+      ON gap_invocations(tenant_id, caller_actor_oid, capability, idempotency_key)
+      WHERE idempotency_key IS NOT NULL;
+
+    CREATE TABLE IF NOT EXISTS gap_workflow_definitions (
+      oid                          TEXT PRIMARY KEY,
+      tenant_id                    TEXT NOT NULL,
+      workflow_id                  TEXT NOT NULL,
+      workflow_version             TEXT NOT NULL,
+      trigger_kind                 TEXT NOT NULL,
+      capability_pattern           TEXT,
+      action_type_pattern          TEXT,
+      body                         TEXT NOT NULL,
+      created_at_ms                INTEGER NOT NULL,
+      supersedes                   TEXT,
+      revoked_at_ms                INTEGER
+    );
+    CREATE INDEX IF NOT EXISTS idx_gap_wfdef_lookup
+      ON gap_workflow_definitions(tenant_id, workflow_id, revoked_at_ms);
+
+    CREATE TABLE IF NOT EXISTS gap_workflow_instances (
+      oid                       TEXT PRIMARY KEY,
+      tenant_id                 TEXT NOT NULL,
+      workflow_definition_oid   TEXT NOT NULL,
+      workflow_id               TEXT NOT NULL,
+      current_stage_id          TEXT NOT NULL,
+      scope_variables           TEXT NOT NULL,
+      started_at_ms             INTEGER NOT NULL,
+      last_transition_at_ms     INTEGER NOT NULL,
+      terminated_at_ms          INTEGER,
+      terminal_outcome          TEXT,
+      body                      TEXT NOT NULL
+    );
+    CREATE INDEX IF NOT EXISTS idx_gap_wfinst_tenant
+      ON gap_workflow_instances(tenant_id, started_at_ms DESC);
+    CREATE INDEX IF NOT EXISTS idx_gap_wfinst_active
+      ON gap_workflow_instances(tenant_id, terminated_at_ms);
+
+    CREATE TABLE IF NOT EXISTS gap_stage_transitions (
+      oid                           TEXT PRIMARY KEY,
+      tenant_id                     TEXT NOT NULL,
+      workflow_instance_oid         TEXT NOT NULL,
+      previous_transition_oid       TEXT,
+      from_stage_id                 TEXT NOT NULL,
+      to_stage_id                   TEXT NOT NULL,
+      trigger_reason                TEXT NOT NULL,
+      body                          TEXT NOT NULL,
+      transitioned_at_ms            INTEGER NOT NULL
+    );
+    CREATE INDEX IF NOT EXISTS idx_gap_trans_workflow
+      ON gap_stage_transitions(workflow_instance_oid, transitioned_at_ms);
+
+    CREATE TABLE IF NOT EXISTS gap_channel_events (
+      oid                           TEXT PRIMARY KEY,
+      tenant_id                     TEXT NOT NULL,
+      channel                       TEXT NOT NULL,
+      event_kind                    TEXT NOT NULL,
+      workflow_instance_oid         TEXT,
+      stage_id                      TEXT,
+      body                          TEXT NOT NULL,
+      observed_at_ms                INTEGER NOT NULL
+    );
+    CREATE INDEX IF NOT EXISTS idx_gap_chan_events
+      ON gap_channel_events(workflow_instance_oid, observed_at_ms);
+
+    CREATE TABLE IF NOT EXISTS gap_receipts (
+      oid                  TEXT PRIMARY KEY,
+      tenant_id            TEXT NOT NULL,
+      subject_kind         TEXT NOT NULL,
+      subject_oid          TEXT NOT NULL,
+      status               TEXT NOT NULL,
+      initiator_actor_oid  TEXT NOT NULL,
+      workflow_instance_oid TEXT,
+      workflow_stage_id    TEXT,
+      body                 TEXT NOT NULL,
+      initiated_at_ms      INTEGER NOT NULL,
+      resolved_at_ms       INTEGER NOT NULL
+    );
+    CREATE INDEX IF NOT EXISTS idx_gap_rcpt_tenant
+      ON gap_receipts(tenant_id, resolved_at_ms DESC);
+    CREATE INDEX IF NOT EXISTS idx_gap_rcpt_subject
+      ON gap_receipts(subject_oid);
+    CREATE INDEX IF NOT EXISTS idx_gap_rcpt_workflow
+      ON gap_receipts(workflow_instance_oid);
+
+    CREATE TABLE IF NOT EXISTS gap_revocations (
+      oid                       TEXT PRIMARY KEY,
+      tenant_id                 TEXT NOT NULL,
+      target_kind               TEXT NOT NULL,
+      target_oid                TEXT NOT NULL,
+      required_level            INTEGER NOT NULL,
+      provisional               INTEGER NOT NULL,    -- 0/1
+      effective_at_ms           INTEGER,
+      lifted_at_ms              INTEGER,
+      body                      TEXT NOT NULL
+    );
+    CREATE INDEX IF NOT EXISTS idx_gap_revoc_target
+      ON gap_revocations(target_oid, effective_at_ms);
+
+    -- Optional Capabilities sharing policy (Phase 2 of SYNOI_OPTIONAL_CAPABILITIES_SPEC.md).
+    -- Per-tenant rules controlling which capability classes a given digital
+    -- experience (game / app / SDK identified by actor OID) may invoke via
+    -- optional_effects. Phase 1 is unchanged when no row exists for an actor.
+    CREATE TABLE IF NOT EXISTS gap_optional_sharing_policies (
+      tenant_id              TEXT NOT NULL,
+      experience_actor_oid   TEXT NOT NULL,
+      allowed_classes_json   TEXT NOT NULL DEFAULT '[]',
+      denied_classes_json    TEXT NOT NULL DEFAULT '[]',
+      expires_at             INTEGER,
+      session_only           INTEGER NOT NULL DEFAULT 0,
+      notification_on_use    TEXT NOT NULL DEFAULT 'never',
+      created_at             INTEGER NOT NULL,
+      updated_at             INTEGER NOT NULL,
+      PRIMARY KEY (tenant_id, experience_actor_oid)
+    );
+    CREATE INDEX IF NOT EXISTS idx_gap_sharing_tenant
+      ON gap_optional_sharing_policies(tenant_id);
+
+    -- Instagration I1: capability -> provider binding records (signed CDROs).
+    -- Per-tenant. Multiple rows may exist for the same capability (fungible
+    -- brokering); resolution logic lives in capability-resolver.ts.
+    CREATE TABLE IF NOT EXISTS gap_capability_bindings (
+      oid              TEXT PRIMARY KEY,
+      tenant_id        TEXT NOT NULL,
+      capability       TEXT NOT NULL,
+      provider         TEXT NOT NULL,
+      fungible         INTEGER NOT NULL,   -- 0/1
+      active           INTEGER NOT NULL,   -- 0/1
+      body             TEXT NOT NULL,      -- full body as JSON
+      created_at_ms    INTEGER NOT NULL
+    );
+    CREATE INDEX IF NOT EXISTS idx_gap_binding_lookup
+      ON gap_capability_bindings(tenant_id, capability, active);
+
+    -- Durable NDA acceptance record for the public demo's entry gate. Keyed by
+    -- operator_oid so a returning visitor is recognized across sessions and
+    -- process restarts (the session object itself is ephemeral/in-memory and
+    -- must never be the source of truth for this). One row per operator; a
+    -- re-accept (e.g. a new nda_version) overwrites the prior row.
+    CREATE TABLE IF NOT EXISTS gap_demo_nda_acceptances (
+      operator_oid     TEXT PRIMARY KEY,
+      tenant_id        TEXT NOT NULL,
+      nda_version      TEXT NOT NULL,
+      accepted_at_ms   INTEGER NOT NULL
+    );
+    CREATE INDEX IF NOT EXISTS idx_gap_demo_nda_tenant
+      ON gap_demo_nda_acceptances(tenant_id);
+  `);
+    // Lazy-wire the sharing-policy module to this DB on first open. The
+    // import is dynamic so we avoid a hard module cycle (sharing-policy
+    // imports capabilityMatches from this file).
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const sp = require('./safety/sharing-policy');
+        sp._setDbProvider?.(() => db());
+    }
+    catch { /* sharing-policy module unavailable — non-fatal */ }
+    return _db;
+}
+// ── Helpers ──────────────────────────────────────────────────────────────────
+function exec() { return db(); }
+// ── Declarations ─────────────────────────────────────────────────────────────
+function saveDeclaration(d) {
+    exec().prepare(`
+    INSERT OR REPLACE INTO gap_declarations
+      (oid, tenant_id, actor_type, actor_id, actor_version, capabilities, body, created_at_ms, supersedes, revoked_at_ms)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, NULL)
+  `).run(d.oid, d.tenant_id, d.body.actor_type, d.body.actor_id, d.body.actor_version, JSON.stringify(d.body.capabilities.map((c) => c.capability)), JSON.stringify(d), d.created_at_ms, d.supersedes ?? null);
+}
+function getDeclaration(oid) {
+    const row = exec().prepare(`SELECT body FROM gap_declarations WHERE oid = ?`).get(oid);
+    return row ? JSON.parse(row.body) : null;
+}
+function findActiveDeclarationByActor(tenantId, actorId) {
+    const row = exec().prepare(`
+    SELECT body, revoked_at_ms FROM gap_declarations
+     WHERE tenant_id = ? AND actor_id = ? AND revoked_at_ms IS NULL
+     ORDER BY created_at_ms DESC LIMIT 1
+  `).get(tenantId, actorId);
+    return row ? JSON.parse(row.body) : null;
+}
+/**
+ * Enumerate all active (non-revoked) declarations for a tenant whose
+ * declared capabilities match the given pattern. Used by the optional-
+ * effects matcher in the engine: a workflow declares
+ * `requires_capability: 'home.lighting.*'` and this returns every smart-
+ * home device that declared a `home.lighting.*` capability.
+ *
+ * Pattern matching uses capabilityMatches() — exact OR prefix wildcard.
+ */
+function listActiveDeclarationsMatching(tenantId, capability_pattern) {
+    const rows = exec().prepare(`
+    SELECT body FROM gap_declarations
+     WHERE tenant_id = ? AND revoked_at_ms IS NULL
+     ORDER BY created_at_ms DESC
+  `).all(tenantId);
+    const out = [];
+    for (const r of rows) {
+        const decl = JSON.parse(r.body);
+        if (decl.body.capabilities.some(c => capabilityMatches(capability_pattern, c.capability))) {
+            out.push(decl);
+        }
+    }
+    return out;
+}
+// ── Grants ───────────────────────────────────────────────────────────────────
+function saveGrant(g) {
+    exec().prepare(`
+    INSERT OR REPLACE INTO gap_grants
+      (oid, tenant_id, grantee_actor_oid, grantee_actor_type, capability_pattern, body, granted_at_ms, expires_at_ms, revoked_at_ms, uses_count, last_used_at_ms)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, NULL, 0, NULL)
+  `).run(g.oid, g.tenant_id, g.body.grantee.actor_oid, g.body.grantee.actor_type, JSON.stringify(g.body.capability_scopes.map((s) => s.capability)), JSON.stringify(g), g.body.granted_at_ms, g.body.expires_at_ms ?? null);
+}
+function findActiveGrantsForCaller(tenantId, callerActorOid, capability) {
+    const now = Date.now();
+    const rows = exec().prepare(`
+    SELECT body FROM gap_grants
+     WHERE tenant_id = ?
+       AND grantee_actor_oid = ?
+       AND revoked_at_ms IS NULL
+       AND (expires_at_ms IS NULL OR expires_at_ms > ?)
+     ORDER BY granted_at_ms DESC
+  `).all(tenantId, callerActorOid, now);
+    const all = rows.map((r) => JSON.parse(r.body));
+    // Filter to grants that include this capability.
+    const matching = all.filter((g) => g.body.capability_scopes.some((s) => capabilityMatches(s.capability, capability)));
+    // Exclude superseded grants. A grant-predicate update (updateGrantPredicate)
+    // mints a NEW grant carrying supersedes=<prior oid> and leaves the prior in
+    // the table (it is not revoked). The prior is no longer the effective grant,
+    // so it must not be returned as active -- otherwise a stale predicate (e.g. an
+    // old threshold) would be evaluated even though the operator changed it. Keep
+    // only the leaves of the supersession chain; ORDER BY granted_at_ms DESC makes
+    // the newest leaf first so callers that take [0] get the current grant.
+    const supersededOids = new Set(matching.map((g) => g.supersedes).filter((x) => typeof x === 'string'));
+    return matching.filter((g) => !supersededOids.has(g.oid));
+}
+/** Match: exact, '*' match-all, or a SEGMENT-BOUNDARY wildcard ('skill.*').
+ *  A non-boundary wildcard like 'admin.us*' must NOT prefix-match
+ *  'admin.users.delete' (privilege-escalation footgun) — the '*' must follow '.'. */
+function capabilityMatches(pattern, target) {
+    if (pattern === target)
+        return true;
+    if (pattern === '*')
+        return true;
+    if (pattern.endsWith('.*')) {
+        const prefix = pattern.slice(0, -1); // keep trailing '.', e.g. 'skill.'
+        return target.startsWith(prefix);
+    }
+    return false;
+}
+function getGrant(oid) {
+    const row = exec().prepare(`SELECT body FROM gap_grants WHERE oid = ?`).get(oid);
+    return row ? JSON.parse(row.body) : null;
+}
+/**
+ * Enumerate active (non-revoked, non-expired) grants for a tenant.
+ * Optional grantee filter narrows to one actor. Used by the operator CLI
+ * and the portal grants list view.
+ */
+function listActiveGrantsForTenant(tenantId, granteeOid) {
+    const now = Date.now();
+    const rows = granteeOid !== undefined
+        ? exec().prepare(`
+        SELECT body FROM gap_grants
+         WHERE tenant_id = ? AND grantee_actor_oid = ?
+           AND revoked_at_ms IS NULL
+           AND (expires_at_ms IS NULL OR expires_at_ms > ?)
+         ORDER BY granted_at_ms DESC
+      `).all(tenantId, granteeOid, now)
+        : exec().prepare(`
+        SELECT body FROM gap_grants
+         WHERE tenant_id = ?
+           AND revoked_at_ms IS NULL
+           AND (expires_at_ms IS NULL OR expires_at_ms > ?)
+         ORDER BY granted_at_ms DESC
+      `).all(tenantId, now);
+    return rows.map(r => JSON.parse(r.body));
+}
+function revokeGrant(oid) {
+    const r = exec().prepare(`
+    UPDATE gap_grants SET revoked_at_ms = ?
+     WHERE oid = ? AND revoked_at_ms IS NULL
+  `).run(Date.now(), oid);
+    return r.changes > 0;
+}
+function incrementGrantUse(oid) {
+    exec().prepare(`
+    UPDATE gap_grants
+       SET uses_count = uses_count + 1, last_used_at_ms = ?
+     WHERE oid = ?
+  `).run(Date.now(), oid);
+}
+// ── Invocations ──────────────────────────────────────────────────────────────
+function saveInvocation(inv, status, receiptOid) {
+    exec().prepare(`
+    INSERT OR REPLACE INTO gap_invocations
+      (oid, tenant_id, caller_actor_oid, capability, grant_oid, workflow_instance_oid, workflow_stage_id, idempotency_key, body, invoked_at_ms, status, receipt_oid)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `).run(inv.oid, inv.tenant_id, inv.body.caller.actor_oid, inv.body.capability, inv.body.caller.grant_oid, inv.body.workflow_context?.workflow_instance_oid ?? null, inv.body.workflow_context?.stage_id ?? null, inv.body.idempotency_key ?? null, JSON.stringify(inv), inv.body.invoked_at_ms, status, receiptOid);
+}
+function findInvocationByIdempotency(tenantId, callerActorOid, capability, idempotencyKey) {
+    const row = exec().prepare(`
+    SELECT body FROM gap_invocations
+     WHERE tenant_id = ? AND caller_actor_oid = ? AND capability = ? AND idempotency_key = ?
+  `).get(tenantId, callerActorOid, capability, idempotencyKey);
+    return row ? JSON.parse(row.body) : null;
+}
+/**
+ * PC-22: find any invocation by (tenant, caller, idempotency_key) regardless of capability.
+ * Used to detect cross-capability idempotency key reuse.
+ */
+function findInvocationByKeyAnyCapability(tenantId, callerActorOid, idempotencyKey) {
+    const row = exec().prepare(`
+    SELECT body FROM gap_invocations
+     WHERE tenant_id = ? AND caller_actor_oid = ? AND idempotency_key = ?
+     LIMIT 1
+  `).get(tenantId, callerActorOid, idempotencyKey);
+    return row ? JSON.parse(row.body) : null;
+}
+/**
+ * PC-06: get the receipt OID for an invocation.
+ */
+/**
+ * PC-24: count successful invocations for a grant within a rolling window.
+ * Used by aggregate_limits enforcement in the invoke gate.
+ */
+function countGrantInvocationsInWindow(tenantId, grantOid, callerActorOid, windowStartMs) {
+    const row = exec().prepare(`
+    SELECT COUNT(*) as cnt FROM gap_invocations
+     WHERE tenant_id = ?
+       AND grant_oid = ?
+       AND caller_actor_oid = ?
+       AND status = 'ok'
+       AND invoked_at_ms >= ?
+  `).get(tenantId, grantOid, callerActorOid, windowStartMs);
+    return row.cnt;
+}
+function getInvocationReceiptOid(invocationOid) {
+    const row = exec().prepare(`
+    SELECT receipt_oid FROM gap_invocations WHERE oid = ?
+  `).get(invocationOid);
+    return row?.receipt_oid ?? null;
+}
+// ── Workflow definitions + instances + transitions ───────────────────────────
+function saveWorkflowDefinition(def) {
+    exec().prepare(`
+    INSERT OR REPLACE INTO gap_workflow_definitions
+      (oid, tenant_id, workflow_id, workflow_version, trigger_kind, capability_pattern, action_type_pattern, body, created_at_ms, supersedes, revoked_at_ms)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, NULL)
+  `).run(def.oid, def.tenant_id, def.body.workflow_id, def.body.workflow_version, def.body.trigger.kind, def.body.trigger.capability_pattern ?? null, def.body.trigger.action_type_pattern ?? null, JSON.stringify(def), def.created_at_ms, def.supersedes ?? null);
+}
+function getWorkflowDefinition(oid) {
+    const row = exec().prepare(`SELECT body FROM gap_workflow_definitions WHERE oid = ?`).get(oid);
+    return row ? JSON.parse(row.body) : null;
+}
+function findActiveWorkflowDefinitions(tenantId, workflowId) {
+    const row = exec().prepare(`
+    SELECT body FROM gap_workflow_definitions
+     WHERE tenant_id = ? AND workflow_id = ? AND revoked_at_ms IS NULL
+     ORDER BY created_at_ms DESC LIMIT 1
+  `).get(tenantId, workflowId);
+    return row ? JSON.parse(row.body) : null;
+}
+function saveWorkflowInstance(inst) {
+    exec().prepare(`
+    INSERT OR REPLACE INTO gap_workflow_instances
+      (oid, tenant_id, workflow_definition_oid, workflow_id, current_stage_id, scope_variables, started_at_ms, last_transition_at_ms, terminated_at_ms, terminal_outcome, body)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `).run(inst.oid, inst.tenant_id, inst.body.workflow_definition_oid, inst.body.workflow_id, inst.body.current_stage_id, JSON.stringify(inst.body.scope_variables), inst.body.started_at_ms, inst.body.last_transition_at_ms, inst.body.terminated_at_ms, inst.body.terminal_outcome, JSON.stringify(inst));
+}
+function getWorkflowInstance(oid) {
+    const row = exec().prepare(`SELECT body FROM gap_workflow_instances WHERE oid = ?`).get(oid);
+    return row ? JSON.parse(row.body) : null;
+}
+/** List a tenant's workflow definitions (newest first). Pure read. */
+function listWorkflowDefinitions(tenantId, opts = {}) {
+    const revokedClause = opts.includeRevoked ? '' : 'AND revoked_at_ms IS NULL';
+    const rows = exec().prepare(`
+    SELECT body FROM gap_workflow_definitions
+     WHERE tenant_id = ? ${revokedClause}
+     ORDER BY created_at_ms DESC
+  `).all(tenantId);
+    return rows.map(r => JSON.parse(r.body));
+}
+/** List a tenant's workflow instances (most-recently-active first). Pure read. */
+function listWorkflowInstances(tenantId, opts = {}) {
+    const activeClause = opts.activeOnly ? 'AND terminated_at_ms IS NULL' : '';
+    const limit = Math.min(Math.max(opts.limit ?? 200, 1), 500);
+    const rows = exec().prepare(`
+    SELECT body FROM gap_workflow_instances
+     WHERE tenant_id = ? ${activeClause}
+     ORDER BY last_transition_at_ms DESC
+     LIMIT ?
+  `).all(tenantId, limit);
+    return rows.map(r => JSON.parse(r.body));
+}
+function saveStageTransition(t) {
+    exec().prepare(`
+    INSERT OR REPLACE INTO gap_stage_transitions
+      (oid, tenant_id, workflow_instance_oid, previous_transition_oid, from_stage_id, to_stage_id, trigger_reason, body, transitioned_at_ms)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `).run(t.oid, t.tenant_id, t.body.workflow_instance_oid, t.body.previous_transition_oid, t.body.from_stage_id, t.body.to_stage_id, t.body.trigger_reason, JSON.stringify(t), t.body.transitioned_at_ms);
+}
+function listStageTransitions(workflowInstanceOid) {
+    const rows = exec().prepare(`
+    SELECT body FROM gap_stage_transitions
+     WHERE workflow_instance_oid = ?
+     ORDER BY transitioned_at_ms ASC
+  `).all(workflowInstanceOid);
+    return rows.map((r) => JSON.parse(r.body));
+}
+// ── Channel events ───────────────────────────────────────────────────────────
+function saveChannelEvent(e) {
+    exec().prepare(`
+    INSERT OR REPLACE INTO gap_channel_events
+      (oid, tenant_id, channel, event_kind, workflow_instance_oid, stage_id, body, observed_at_ms)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+  `).run(e.oid, e.tenant_id, e.body.channel, e.body.event_kind, e.body.workflow_instance_oid ?? null, e.body.stage_id ?? null, JSON.stringify(e), e.body.observed_at_ms);
+}
+// ── Receipts ─────────────────────────────────────────────────────────────────
+function saveReceipt(r) {
+    exec().prepare(`
+    INSERT OR REPLACE INTO gap_receipts
+      (oid, tenant_id, subject_kind, subject_oid, status, initiator_actor_oid, workflow_instance_oid, workflow_stage_id, body, initiated_at_ms, resolved_at_ms)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `).run(r.oid, r.tenant_id, r.body.subject_kind, r.body.subject_oid, r.body.status, r.body.initiator.actor_oid, r.body.workflow_instance_oid ?? null, r.body.workflow_stage_id ?? null, JSON.stringify(r), r.body.initiated_at_ms, r.body.resolved_at_ms);
+}
+function getReceipt(oid) {
+    const row = exec().prepare(`SELECT body FROM gap_receipts WHERE oid = ?`).get(oid);
+    return row ? JSON.parse(row.body) : null;
+}
+/**
+ * PC-17/PC-18: list receipts for a tenant with optional filters.
+ * When capability is provided, only returns receipts for capability_invocation
+ * subjects where the linked invocation has that capability string.
+ * Tenant isolation is enforced by WHERE tenant_id = tenantId.
+ * Returns newest first (by resolved_at_ms DESC).
+ */
+function listReceipts(tenantId, opts) {
+    const limit = opts?.limit ?? 50;
+    let sql;
+    const params = [tenantId];
+    if (opts?.capability !== undefined) {
+        // Join with invocations to filter by capability.
+        sql = `
+      SELECT r.body FROM gap_receipts r
+      JOIN gap_invocations i ON i.oid = r.subject_oid
+        AND r.subject_kind = 'capability_invocation'
+      WHERE r.tenant_id = ?
+        AND i.capability = ?
+    `;
+        params.push(opts.capability);
+        if (opts.status !== undefined) {
+            sql += ` AND r.status = ?`;
+            params.push(opts.status);
+        }
+        sql += ` ORDER BY r.resolved_at_ms DESC LIMIT ?`;
+    }
+    else {
+        sql = `SELECT body FROM gap_receipts WHERE tenant_id = ?`;
+        if (opts?.status !== undefined) {
+            sql += ` AND status = ?`;
+            params.push(opts.status);
+        }
+        if (opts?.subject_kind !== undefined) {
+            sql += ` AND subject_kind = ?`;
+            params.push(opts.subject_kind);
+        }
+        sql += ` ORDER BY resolved_at_ms DESC LIMIT ?`;
+    }
+    params.push(limit);
+    const rows = exec().prepare(sql).all(...params);
+    return rows.map((r) => JSON.parse(r.body));
+}
+/**
+ * Cycle 7 — Receipt Ledger query. A tenant-scoped, time-windowed, paginated read
+ * over the receipt store for the admin ledger surface (GET /admin/ledger). The
+ * column-backed filters (status, subject_kind, resolved_at_ms window) run in SQL;
+ * the JSON-body filters (capability, provider_ran) are applied by the caller on
+ * the projection layer, since they live inside the serialized body.
+ *
+ * TRUNCATION HONESTY (Cycle-6 [14] lesson): the ledger NEVER implies completeness
+ * it cannot back. `total` is a COUNT(*) over the SAME column-backed predicate, so
+ * a caller can compare `total` against `offset + rows.length` and report exactly
+ * whether the page is the tail of the result set or a truncated prefix. The COUNT
+ * covers only the column-backed predicate; any additional body-level filter the
+ * caller applies further reduces the returned rows below `total`, which the caller
+ * MUST surface (it does: see ledger.ts `filtered_by_body`).
+ *
+ * Tenant isolation is enforced by WHERE tenant_id = tenantId. Newest first.
+ */
+function queryLedgerReceipts(tenantId, opts) {
+    const limit = Math.max(1, Math.min(opts?.limit ?? 50, 1000));
+    const offset = Math.max(0, opts?.offset ?? 0);
+    const where = ['tenant_id = ?'];
+    const whereParams = [tenantId];
+    if (opts?.status !== undefined) {
+        where.push('status = ?');
+        whereParams.push(opts.status);
+    }
+    if (opts?.subject_kind !== undefined) {
+        where.push('subject_kind = ?');
+        whereParams.push(opts.subject_kind);
+    }
+    if (opts?.since_ms !== undefined) {
+        where.push('resolved_at_ms >= ?');
+        whereParams.push(opts.since_ms);
+    }
+    if (opts?.until_ms !== undefined) {
+        where.push('resolved_at_ms <= ?');
+        whereParams.push(opts.until_ms);
+    }
+    const whereSql = where.join(' AND ');
+    const totalRow = exec()
+        .prepare(`SELECT COUNT(*) AS n FROM gap_receipts WHERE ${whereSql}`)
+        .get(...whereParams);
+    const rows = exec()
+        .prepare(`SELECT body FROM gap_receipts WHERE ${whereSql} ` +
+        `ORDER BY resolved_at_ms DESC LIMIT ? OFFSET ?`)
+        .all(...whereParams, limit, offset);
+    return {
+        rows: rows.map((r) => JSON.parse(r.body)),
+        total: totalRow.n,
+    };
+}
+/**
+ * Cycle 7 — resolve a set of receipt OIDs to full receipts for a tenant, in the
+ * order requested. Used by the evidence-bundle export to gather the exact signed
+ * receipt objects a filter selected. Tenant-scoped: a receipt whose tenant_id
+ * does not match is skipped (never leaked across tenants). Missing OIDs are
+ * skipped; the caller reconciles requested-vs-returned counts.
+ */
+function getReceiptsByOids(tenantId, oids) {
+    const out = [];
+    const stmt = exec().prepare(`SELECT body FROM gap_receipts WHERE oid = ? AND tenant_id = ?`);
+    for (const oid of oids) {
+        const row = stmt.get(oid, tenantId);
+        if (row)
+            out.push(JSON.parse(row.body));
+    }
+    return out;
+}
+/**
+ * S2.3 — find the most-recent denial receipt for a (tenant, principal, subject_oid)
+ * triple within a look-back window. Used by the 2-receipt chain gate to locate D1
+ * before emitting E1 with `replayed_after = D1.oid`.
+ *
+ * The look-back window guards the provisional-block condition: we only allow
+ * replay if D1 is still within the provisional-block window (caller enforces this).
+ *
+ * Returns the most recent matching denial receipt, or null if none.
+ * Does NOT check whether the denial's auto-lift fired — caller must verify
+ * provisional state before acting on this result.
+ */
+function findDenialReceiptForPrincipal(tenantId, principalOid, subjectOid, windowMs) {
+    const since = Date.now() - windowMs;
+    const row = exec().prepare(`
+    SELECT body FROM gap_receipts
+     WHERE tenant_id           = ?
+       AND initiator_actor_oid = ?
+       AND subject_oid         = ?
+       AND status              = 'denied'
+       AND resolved_at_ms     >= ?
+     ORDER BY resolved_at_ms DESC
+     LIMIT 1
+  `).get(tenantId, principalOid, subjectOid, since);
+    return row ? JSON.parse(row.body) : null;
+}
+// ── Revocation ───────────────────────────────────────────────────────────────
+function saveRevocation(r) {
+    exec().prepare(`
+    INSERT OR REPLACE INTO gap_revocations
+      (oid, tenant_id, target_kind, target_oid, required_level, provisional, effective_at_ms, lifted_at_ms, body)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `).run(r.oid, r.tenant_id, r.body.target_kind, r.body.target_oid, r.body.required_level, r.body.provisional ? 1 : 0, r.body.effective_at_ms, r.body.lifted_at_ms ?? null, JSON.stringify(r));
+    // If effective immediately, mark the target as revoked.
+    if (r.body.effective_at_ms !== null && r.body.effective_at_ms <= Date.now()) {
+        applyRevocationToTarget(r.body.target_kind, r.body.target_oid, r.tenant_id);
+    }
+}
+/**
+ * Resolve the owning tenant of a revocation target, or null when ownership
+ * is not locally knowable. The tenant-owned GAP-native kinds carry a
+ * tenant_id column; 'skill' is Vault-homed + content-addressed (the same
+ * skill OID is shared across tenants) so it has no single local owner and
+ * returns null. Callers use null to mean "cannot verify ownership here".
+ *
+ * The table name is selected from a fixed internal allow-list, never from
+ * caller input, so the interpolation is not an injection surface.
+ */
+function ownerTenantOf(kind, oid) {
+    const table = kind === 'capability_grant' ? 'gap_grants' :
+        kind === 'capability_declaration' ? 'gap_declarations' :
+            kind === 'workflow_definition' ? 'gap_workflow_definitions' :
+                kind === 'workflow_instance' ? 'gap_workflow_instances' :
+                    null; // 'skill' has no local ownership row
+    if (table === null)
+        return null;
+    const row = exec()
+        .prepare(`SELECT tenant_id FROM ${table} WHERE oid = ?`)
+        .get(oid);
+    return row?.tenant_id ?? null;
+}
+/**
+ * Thrown when a tenant attempts to revoke a target owned by a different
+ * tenant. Mapped to HTTP 403 by the router. Closes the cross-tenant
+ * DoS-by-revocation hole (H1) across every revocation entry point: L1
+ * (revokeGapObject), L2/L3 initiation, and the emergency provisional block —
+ * each fed the gap_revocations table / provisional-block set with no
+ * per-target-tenant ownership check.
+ */
+class CrossTenantRevocationError extends Error {
+    target_oid;
+    owner_tenant;
+    caller_tenant;
+    constructor(target_oid, owner_tenant, caller_tenant) {
+        super(`tenant '${caller_tenant}' may not revoke ${target_oid} owned by tenant '${owner_tenant}'`);
+        this.target_oid = target_oid;
+        this.owner_tenant = owner_tenant;
+        this.caller_tenant = caller_tenant;
+        this.name = 'CrossTenantRevocationError';
+    }
+}
+exports.CrossTenantRevocationError = CrossTenantRevocationError;
+/**
+ * Ownership guard shared by every revocation entry point. For tenant-owned
+ * kinds (grant/declaration/workflow) the caller's tenant must own the target;
+ * 'skill' is content-addressed + Vault-homed (ownerTenantOf returns null), so
+ * it is not guarded here — a network-wide skill kill goes through the
+ * multi-party L2/L3 path. See CAPABILITY_NETWORK_HARDENING.md H1.
+ */
+function assertTenantOwnsTarget(tenant_id, target_kind, target_oid) {
+    const owner = ownerTenantOf(target_kind, target_oid);
+    if (owner !== null && owner !== tenant_id) {
+        throw new CrossTenantRevocationError(target_oid, owner, tenant_id);
+    }
+}
+function applyRevocationToTarget(kind, targetOid, tenantId) {
+    const now = Date.now();
+    // Defense in depth: the UPDATE is scoped to the revocation's own tenant, so
+    // a revocation row can only flip a target row that the same tenant owns even
+    // if the upstream ownership guard were ever bypassed.
+    if (kind === 'capability_grant') {
+        exec().prepare(`UPDATE gap_grants SET revoked_at_ms = ? WHERE oid = ? AND tenant_id = ? AND revoked_at_ms IS NULL`).run(now, targetOid, tenantId);
+    }
+    else if (kind === 'capability_declaration') {
+        exec().prepare(`UPDATE gap_declarations SET revoked_at_ms = ? WHERE oid = ? AND tenant_id = ? AND revoked_at_ms IS NULL`).run(now, targetOid, tenantId);
+    }
+    else if (kind === 'workflow_definition') {
+        exec().prepare(`UPDATE gap_workflow_definitions SET revoked_at_ms = ? WHERE oid = ? AND tenant_id = ? AND revoked_at_ms IS NULL`).run(now, targetOid, tenantId);
+    }
+    // workflow_instance + skill revocation are handled elsewhere (engine in-flight cancellation; skill registry).
+}
+function isOidRevoked(oid) {
+    // Check grants, declarations, and workflow defs (per-table revoked_at_ms columns).
+    const r1 = exec().prepare(`SELECT 1 FROM gap_grants WHERE oid = ? AND revoked_at_ms IS NOT NULL`).get(oid);
+    if (r1 !== undefined)
+        return true;
+    const r2 = exec().prepare(`SELECT 1 FROM gap_declarations WHERE oid = ? AND revoked_at_ms IS NOT NULL`).get(oid);
+    if (r2 !== undefined)
+        return true;
+    const r3 = exec().prepare(`SELECT 1 FROM gap_workflow_definitions WHERE oid = ? AND revoked_at_ms IS NOT NULL`).get(oid);
+    if (r3 !== undefined)
+        return true;
+    // Skills don't have a per-row revoked_at_ms because they live outside GAP's
+    // own tables (their canonical home is the Vault). Check gap_revocations
+    // directly for an effective, non-lifted revocation targeting this OID
+    // regardless of target_kind. Same check covers any future target_kind that
+    // gets added without needing a new per-table column.
+    const now = Date.now();
+    const r4 = exec().prepare(`
+    SELECT 1 FROM gap_revocations
+    WHERE target_oid = ?
+      AND effective_at_ms IS NOT NULL
+      AND effective_at_ms <= ?
+      AND (lifted_at_ms IS NULL OR lifted_at_ms > ?)
+    LIMIT 1
+  `).get(oid, now, now);
+    return r4 !== undefined;
+}
+/**
+ * List recent revocation events for the open OID Resolver / observability
+ * surface. Defaults to descending effective_at_ms (most recent first), with
+ * optional filters on target_kind + tenant.
+ */
+function listRevocations(opts = {}) {
+    const limit = Math.min(Math.max(opts.limit ?? 50, 1), 500);
+    const where = [];
+    const params = [];
+    if (opts.before_ms !== undefined) {
+        where.push(`effective_at_ms IS NOT NULL AND effective_at_ms < ?`);
+        params.push(opts.before_ms);
+    }
+    if (opts.target_kind !== undefined) {
+        where.push(`target_kind = ?`);
+        params.push(opts.target_kind);
+    }
+    if (opts.tenant_id !== undefined) {
+        where.push(`tenant_id = ?`);
+        params.push(opts.tenant_id);
+    }
+    const whereClause = where.length > 0 ? `WHERE ${where.join(' AND ')}` : '';
+    // ORDER BY effective_at_ms DESC NULLS LAST — SQLite sorts NULLs first in
+    // DESC order by default, so we explicitly push them to the end.
+    const rows = exec().prepare(`
+    SELECT oid, tenant_id, target_kind, target_oid, required_level,
+           provisional, effective_at_ms, lifted_at_ms, body
+    FROM gap_revocations
+    ${whereClause}
+    ORDER BY (effective_at_ms IS NULL), effective_at_ms DESC
+    LIMIT ?
+  `).all(...params, limit);
+    return rows.map(r => ({
+        oid: r.oid,
+        tenant_id: r.tenant_id,
+        target_kind: r.target_kind,
+        target_oid: r.target_oid,
+        required_level: r.required_level,
+        provisional: r.provisional === 1,
+        effective_at_ms: r.effective_at_ms,
+        lifted_at_ms: r.lifted_at_ms,
+        body: JSON.parse(r.body),
+    }));
+}
+/**
+ * Return one summary row per distinct tenant_id known to the grants table,
+ * including tenants whose grants have all been revoked (historical presence).
+ * Ordered by most-recent grant descending.
+ */
+function listAllTenants() {
+    const rows = exec().prepare(`
+    SELECT
+      tenant_id,
+      COUNT(*)        AS grant_count,
+      MIN(granted_at_ms) AS first_ms,
+      MAX(granted_at_ms) AS last_ms
+    FROM gap_grants
+    GROUP BY tenant_id
+    ORDER BY last_ms DESC
+  `).all();
+    return rows.map(r => ({
+        tenant_id: r.tenant_id,
+        grant_count: r.grant_count,
+        first_grant_at: new Date(r.first_ms).toISOString(),
+        last_grant_at: new Date(r.last_ms).toISOString(),
+    }));
+}
+// ── Capability bindings (Instagration I1) ───────────────────────────────────
+function saveBinding(b) {
+    exec().prepare(`
+    INSERT OR REPLACE INTO gap_capability_bindings
+      (oid, tenant_id, capability, provider, fungible, active, body, created_at_ms)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+  `).run(b.oid, b.tenant_id, b.body.capability, b.body.provider, b.body.fungible ? 1 : 0, b.body.active ? 1 : 0, JSON.stringify(b), b.created_at_ms);
+}
+function getBinding(oid) {
+    const row = exec().prepare(`SELECT body FROM gap_capability_bindings WHERE oid = ?`).get(oid);
+    return row ? JSON.parse(row.body) : null;
+}
+/**
+ * Active bindings for a capability, ordered by created_at_ms ascending
+ * (oldest first -- the resolver's "pick the first" seam, doc I1, relies on
+ * stable insertion order for the >1-fungible placeholder path).
+ */
+function findActiveBindingsForCapability(tenantId, capability) {
+    const rows = exec().prepare(`
+    SELECT body FROM gap_capability_bindings
+     WHERE tenant_id = ? AND capability = ? AND active = 1
+     ORDER BY created_at_ms ASC
+  `).all(tenantId, capability);
+    return rows.map((r) => JSON.parse(r.body));
+}
+function listBindingsForTenant(tenantId) {
+    const rows = exec().prepare(`
+    SELECT body FROM gap_capability_bindings
+     WHERE tenant_id = ?
+     ORDER BY created_at_ms DESC
+  `).all(tenantId);
+    return rows.map((r) => JSON.parse(r.body));
+}
+/** Deactivate a binding (soft-disable; preserves the signed CDRO history). */
+function deactivateBinding(oid) {
+    const r = exec().prepare(`
+    UPDATE gap_capability_bindings SET active = 0
+     WHERE oid = ? AND active = 1
+  `).run(oid);
+    return r.changes > 0;
+}
+// ── Test helpers ─────────────────────────────────────────────────────────────
+function _resetForTesting() {
+    if (_db !== null) {
+        _db.close();
+        _db = null;
+    }
+}
+/**
+ * Test-only: overwrite the persisted `body` column of a receipt row directly,
+ * WITHOUT re-signing. Models a DB-level tamper / corrupt row. Used to prove the
+ * authorized-axis read-time re-verify (D3 [5]): a mutated body no longer binds
+ * the signed attestation, so the receipt authorizes nothing. Not exported into
+ * any runtime path.
+ */
+function _testRawUpdateReceiptBody(oid, body) {
+    exec().prepare(`UPDATE gap_receipts SET body = ? WHERE oid = ?`).run(body, oid);
+}
+/**
+ * Test-only: force the shared connection into (or out of) SQLite `query_only`
+ * mode. When ON, every write (INSERT/UPDATE/DELETE) throws SQLITE_READONLY
+ * while reads still succeed. Used to prove the bindings rebind fail-safe:
+ * with writes failing, the new-binding INSERT throws BEFORE any deactivation
+ * runs, so the old binding must remain active (no zero-active-binding window).
+ */
+function _setQueryOnlyForTesting(on) {
+    exec().pragma(`query_only = ${on ? 'ON' : 'OFF'}`);
+}
+// ── Demo data bulk-delete (admin reset) ─────────────────────────────────────
+/**
+ * Delete all rows from gap_receipts and gap_grants whose tenant_id starts
+ * with the given prefix (e.g. 'tenant:demo-'). Covers both the gate tenant
+ * (tenant:demo-<oid>) and the memory tenant (tenant:demo-mem-<oid>).
+ * Returns the number of rows deleted across both tables.
+ *
+ * Scoped strictly to the prefix: the LIKE pattern uses the prefix followed by
+ * '%'. No rows outside that prefix are touched.
+ */
+function deleteDemoRowsByTenantPrefix(prefix) {
+    const pattern = prefix + '%';
+    const r1 = exec().prepare(`DELETE FROM gap_receipts             WHERE tenant_id LIKE ?`).run(pattern);
+    const r2 = exec().prepare(`DELETE FROM gap_grants               WHERE tenant_id LIKE ?`).run(pattern);
+    const r3 = exec().prepare(`DELETE FROM gap_demo_nda_acceptances WHERE tenant_id LIKE ?`).run(pattern);
+    return { receipts: r1.changes, grants: r2.changes, nda: r3.changes };
+}
+/**
+ * Record (or overwrite) the durable NDA acceptance for an operator. Called
+ * only after POST /v1/demo/nda/accept has verified the operator's signature.
+ * Survives process restart and is independent of any in-memory session.
+ */
+function saveDemoNdaAcceptance(operatorOid, tenantId, ndaVersion, acceptedAtMs) {
+    exec().prepare(`
+    INSERT INTO gap_demo_nda_acceptances (operator_oid, tenant_id, nda_version, accepted_at_ms)
+    VALUES (?, ?, ?, ?)
+    ON CONFLICT(operator_oid) DO UPDATE SET
+      tenant_id      = excluded.tenant_id,
+      nda_version    = excluded.nda_version,
+      accepted_at_ms = excluded.accepted_at_ms
+  `).run(operatorOid, tenantId, ndaVersion, acceptedAtMs);
+}
+/** Look up the durable NDA acceptance for an operator. Null when never accepted. */
+function getDemoNdaAcceptance(operatorOid) {
+    const row = exec().prepare(`
+    SELECT operator_oid, nda_version, accepted_at_ms
+      FROM gap_demo_nda_acceptances
+     WHERE operator_oid = ?
+  `).get(operatorOid);
+    return row ?? null;
+}
+// ── ADR_007 migration: rename agp_* tables to gap_* for existing databases ──
+/**
+ * Rename existing agp_* tables to gap_* for any database created before the
+ * ADR_007 signed-byte migration. Safe to call multiple times: each ALTER is
+ * wrapped in an existence check so it is a no-op when the gap_* table already
+ * exists (i.e. fresh post-migration databases).
+ *
+ * Call this once at gateway startup before any other store operations.
+ * The old agp_* table names no longer appear in any CREATE TABLE or SQL
+ * query in this codebase after ADR_007.
+ */
+function migrateAgpTablesToGap() {
+    const d = exec();
+    const tableRenames = [
+        ['agp_declarations', 'gap_declarations'],
+        ['agp_grants', 'gap_grants'],
+        ['agp_invocations', 'gap_invocations'],
+        ['agp_workflow_definitions', 'gap_workflow_definitions'],
+        ['agp_workflow_instances', 'gap_workflow_instances'],
+        ['agp_stage_transitions', 'gap_stage_transitions'],
+        ['agp_channel_events', 'gap_channel_events'],
+        ['agp_receipts', 'gap_receipts'],
+        ['agp_revocations', 'gap_revocations'],
+        ['agp_optional_sharing_policies', 'gap_optional_sharing_policies'],
+        ['agp_provisional_blocks', 'gap_provisional_blocks'],
+    ];
+    for (const [oldName, newName] of tableRenames) {
+        const exists = d.prepare(`SELECT 1 FROM sqlite_master WHERE type='table' AND name=?`).get(oldName);
+        if (exists) {
+            d.exec(`ALTER TABLE ${oldName} RENAME TO ${newName}`);
+        }
+    }
+}