@dsh-enhanced/assistant-verifier 0.1.65 → 0.1.66

package/lib/creation-review-store.js

@@ -1,9 +1,24 @@
-import { closeSync, constants, lstatSync, mkdirSync, openSync, realpathSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { closeSync, constants, fstatSync, lstatSync, mkdirSync, openSync, realpathSync } from 'node:fs';
 import { dirname, isAbsolute, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
 import { DatabaseSync } from 'node:sqlite';
 import { canonicalGrowthJson } from '@dsh-enhanced/assistant-growth-contract';
+import { lineageFail, validateScope, validateRequest, same } from './review-authority-lineage.js';
 const SHA = /^[a-f0-9]{64}$/u;
 const ID = /^[A-Za-z0-9][A-Za-z0-9._:/-]{0,199}$/u;
+const maintenance = Symbol('offline review grant maintenance');
+const readOnlyMaintenance = Symbol('readonly offline review history');
+const auditTable = 'creation_review_grant_handoffs';
+const auditSchema = `CREATE TABLE ${auditTable}(transaction_id TEXT PRIMARY KEY,proof TEXT NOT NULL) STRICT`;
+const auditTriggers = ['UPDATE', 'DELETE'].map(action => `CREATE TRIGGER creation_review_handoff_no_${action.toLowerCase()} BEFORE ${action} ON ${auditTable} BEGIN SELECT RAISE(ABORT,'immutable review handoff'); END`);
+const hash = (value) => createHash('sha256').update(canonicalGrowthJson(value)).digest('hex');
+function validScope(scope) {
+    return [scope.transactionId, scope.installationId, scope.profileId, scope.authority].every(value => typeof value === 'string' && ID.test(value))
+        && ['creation-reviews', 'revision-reviews', 'revision-regressions'].includes(scope.lane)
+        && typeof scope.configurationDigest === 'string' && SHA.test(scope.configurationDigest)
+        && typeof scope.toDigest === 'string' && SHA.test(scope.toDigest);
+}
 function fail(message) { throw new Error(`creation review store: ${message}`); }
 function check(idValue, digestValue) {
     if (!ID.test(idValue) || !SHA.test(digestValue))
@@ -18,22 +33,30 @@ function privateFile(path) {
 /** Every dispatch is claimed durably first. A claimed or unknown stage is never replayed. */
 export class CreationReviewStore {
     #db;
+    #maintenance;
+    #path;
+    #identity;
     #closed = false;
-    constructor(path) {
+    constructor(path, mode) {
+        this.#maintenance = mode === maintenance || mode === readOnlyMaintenance;
+        this.#path = path;
         if (!isAbsolute(path) || resolve(path) !== path)
             fail('invalid path');
         const parent = dirname(path);
-        mkdirSync(parent, { recursive: true, mode: 0o700 });
+        if (!this.#maintenance)
+            mkdirSync(parent, { recursive: true, mode: 0o700 });
         const directory = lstatSync(parent);
         if (!directory.isDirectory() || directory.isSymbolicLink() || directory.mode & 0o077
             || process.getuid && directory.uid !== process.getuid() || realpathSync(parent) !== parent)
             fail('directory must be private');
-        try {
-            closeSync(openSync(path, constants.O_CREAT | constants.O_EXCL | constants.O_RDWR | constants.O_NOFOLLOW, 0o600));
-        }
-        catch (error) {
-            if (error.code !== 'EEXIST')
-                throw error;
+        if (!this.#maintenance) {
+            try {
+                closeSync(openSync(path, constants.O_CREAT | constants.O_EXCL | constants.O_RDWR | constants.O_NOFOLLOW, 0o600));
+            }
+            catch (error) {
+                if (error.code !== 'EEXIST')
+                    throw error;
+            }
         }
         privateFile(path);
         for (const suffix of ['-wal', '-shm', '-journal']) {
@@ -45,9 +68,28 @@ export class CreationReviewStore {
                     throw error;
             }
         }
-        this.#db = new DatabaseSync(path);
+        const fd = openSync(path, (mode === readOnlyMaintenance ? constants.O_RDONLY : constants.O_RDWR) | constants.O_NOFOLLOW);
+        try {
+            const stat = fstatSync(fd);
+            this.#identity = { dev: stat.dev, ino: stat.ino };
+            if (this.#maintenance && stat.size < 100)
+                fail('maintenance database empty');
+            this.#db = mode === readOnlyMaintenance
+                ? new DatabaseSync(`${pathToFileURL(path).href}?mode=ro&immutable=1`, { readOnly: true })
+                : new DatabaseSync(this.#maintenance ? `${pathToFileURL(path).href}?mode=rw` : path);
+        }
+        finally {
+            closeSync(fd);
+        }
         try {
-            this.#db.exec(`PRAGMA busy_timeout=5000; PRAGMA journal_mode=WAL; PRAGMA synchronous=FULL;
+            this.#checkFile();
+            if (this.#maintenance) {
+                if (mode !== readOnlyMaintenance)
+                    this.#db.exec('PRAGMA busy_timeout=5000; PRAGMA synchronous=FULL;');
+                this.#maintenanceSchema();
+            }
+            else
+                this.#db.exec(`PRAGMA busy_timeout=5000; PRAGMA journal_mode=WAL; PRAGMA synchronous=FULL;
         CREATE TABLE IF NOT EXISTS grants(authority TEXT PRIMARY KEY,digest TEXT NOT NULL,maximum INTEGER NOT NULL,used INTEGER NOT NULL);
         CREATE TABLE IF NOT EXISTS verifications(plan TEXT PRIMARY KEY,binding TEXT NOT NULL,authority TEXT NOT NULL,
           state TEXT NOT NULL,data TEXT NOT NULL);`);
@@ -57,6 +99,471 @@ export class CreationReviewStore {
             throw error;
         }
     }
+    /** Offline private stage only. Caller must stop writers and authorize frozen configuration. */
+    static openExistingForMaintenance(path) {
+        return new CreationReviewStore(path, maintenance);
+    }
+    #checkFile() {
+        const parent = dirname(this.#path), directory = lstatSync(parent);
+        if (!directory.isDirectory() || directory.isSymbolicLink() || directory.mode & 0o077
+            || process.getuid && directory.uid !== process.getuid() || realpathSync(parent) !== parent)
+            fail('directory must be private');
+        privateFile(this.#path);
+        const stat = lstatSync(this.#path);
+        if (stat.dev !== this.#identity.dev || stat.ino !== this.#identity.ino)
+            fail('database identity changed');
+        for (const suffix of ['-wal', '-shm', '-journal']) {
+            try {
+                privateFile(this.#path + suffix);
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT')
+                    throw error;
+            }
+        }
+    }
+    #textIntegrity() {
+        // SQLite TEXT bindings can contain NUL/invalid UTF-8. Node 24's TEXT
+        // projection truncates at NUL, so never let that projection attest its own
+        // bytes. Check the independently returned BLOB before hashing/parsing/IDs.
+        const decoder = new TextDecoder('utf-8', { fatal: true });
+        const columns = {
+            sqlite_schema: ['type', 'name', 'tbl_name', 'sql'],
+            grants: ['authority', 'digest'], verifications: ['plan', 'binding', 'authority', 'state', 'data'],
+        };
+        if (this.#db.prepare("SELECT 1 FROM sqlite_schema WHERE name=?").get(auditTable))
+            columns[auditTable] = ['transaction_id', 'proof'];
+        for (const [table, names] of Object.entries(columns))
+            for (const column of names) {
+                const rows = this.#db.prepare(`SELECT ${column} AS text,CAST(${column} AS BLOB) AS bytes FROM ${table}`).iterate();
+                for (const row of rows) {
+                    if (row.text === null && table === 'sqlite_schema' && column === 'sql')
+                        continue;
+                    if (typeof row.text !== 'string' || !(row.bytes instanceof Uint8Array) || row.bytes.includes(0))
+                        lineageFail('unsafe SQLite TEXT bytes');
+                    let decoded;
+                    try {
+                        decoded = decoder.decode(row.bytes);
+                    }
+                    catch {
+                        lineageFail('invalid SQLite UTF-8 bytes');
+                    }
+                    if (decoded !== row.text || !Buffer.from(decoded, 'utf8').equals(Buffer.from(row.bytes)))
+                        lineageFail('SQLite TEXT projection changed bytes');
+                }
+            }
+    }
+    #maintenanceSchema(allowRuntime = false) {
+        if (!allowRuntime && !this.#maintenance || this.#closed)
+            fail('requires existing-only maintenance');
+        this.#checkFile();
+        this.#textIntegrity();
+        if (this.#db.prepare('PRAGMA user_version').get()?.user_version !== 0
+            || this.#db.prepare('PRAGMA application_id').get()?.application_id !== 0)
+            fail('maintenance metadata changed');
+        const objects = this.#db.prepare("SELECT type,name,sql FROM sqlite_schema WHERE name NOT GLOB 'sqlite_*' ORDER BY name").all();
+        const audit = objects.some(row => row.name === auditTable);
+        const allowed = new Map([['grants', 'table'], ['verifications', 'table']]);
+        if (audit) {
+            allowed.set(auditTable, 'table');
+            allowed.set('creation_review_handoff_no_update', 'trigger');
+            allowed.set('creation_review_handoff_no_delete', 'trigger');
+        }
+        if (objects.length !== allowed.size || objects.some(row => allowed.get(String(row.name)) !== row.type))
+            fail('maintenance schema changed');
+        const normalize = (sql) => sql.replace(/\s+/gu, '').toLowerCase();
+        for (const sql of [
+            'CREATE TABLE grants(authority TEXT PRIMARY KEY,digest TEXT NOT NULL,maximum INTEGER NOT NULL,used INTEGER NOT NULL)',
+            'CREATE TABLE verifications(plan TEXT PRIMARY KEY,binding TEXT NOT NULL,authority TEXT NOT NULL,state TEXT NOT NULL,data TEXT NOT NULL)',
+        ]) {
+            if (!objects.some(row => typeof row.sql === 'string' && normalize(row.sql) === normalize(sql)))
+                fail('maintenance schema changed');
+        }
+        const columns = {
+            grants: ['authority:TEXT:0:1', 'digest:TEXT:1:0', 'maximum:INTEGER:1:0', 'used:INTEGER:1:0'],
+            verifications: ['plan:TEXT:0:1', 'binding:TEXT:1:0', 'authority:TEXT:1:0', 'state:TEXT:1:0', 'data:TEXT:1:0'],
+        };
+        if (audit)
+            columns[auditTable] = ['transaction_id:TEXT:1:1', 'proof:TEXT:1:0'];
+        for (const [table, expected] of Object.entries(columns)) {
+            const actual = this.#db.prepare(`PRAGMA table_xinfo(${table})`).all();
+            if (actual.some(row => row.hidden !== 0) || actual.map(row => `${row.name}:${row.type}:${row.notnull}:${row.pk}`).join() !== expected.join())
+                fail('maintenance columns changed');
+        }
+        if (audit && [auditSchema, ...auditTriggers].some(sql => !objects.some(row => row.sql === sql)))
+            fail('handoff audit schema changed');
+        const integrity = this.#db.prepare('PRAGMA quick_check').all();
+        if (integrity.length !== 1 || integrity[0]?.quick_check !== 'ok')
+            fail('maintenance integrity failed');
+    }
+    #snapshot(authority, overrideDigest) {
+        this.#maintenanceSchema();
+        const grants = this.#db.prepare('SELECT * FROM grants ORDER BY authority COLLATE BINARY').all();
+        const counts = new Map();
+        for (const row of grants) {
+            if (typeof row.authority !== 'string' || !ID.test(row.authority) || typeof row.digest !== 'string' || !SHA.test(row.digest)
+                || !Number.isSafeInteger(row.maximum) || row.maximum < 1 || row.maximum > 1000
+                || !Number.isSafeInteger(row.used) || row.used < 1 || row.used > row.maximum)
+                fail('grant corrupt or has no claimed history');
+            counts.set(row.authority, 0);
+        }
+        const grant = grants.find(row => row.authority === authority);
+        if (!grant)
+            fail('existing grant missing');
+        const rows = this.#db.prepare('SELECT * FROM verifications ORDER BY plan COLLATE BINARY').all();
+        // Hash rows independently: the whole history can exceed the canonical JSON
+        // helper's per-payload node limit even though every stored row is bounded.
+        const history = createHash('sha256').update('dsh-creation-review-history/v1\n');
+        for (const row of rows) {
+            const terminal = row.state === 'rejected' || row.state === 'unknown';
+            if (typeof row.plan !== 'string' || !ID.test(row.plan) || typeof row.binding !== 'string' || !SHA.test(row.binding)
+                || !counts.has(row.authority) || typeof row.data !== 'string' || Buffer.byteLength(row.data) > (terminal ? 300_000 : 262_144)
+                || !['discover-claimed', 'contract-claimed', 'contract-ready', 'case-claimed', 'cases-ready', 'review-claimed',
+                    'certificate', 'rejected', 'unknown'].includes(row.state))
+                fail('verification corrupt');
+            let data;
+            try {
+                data = JSON.parse(row.data);
+            }
+            catch {
+                fail('verification data corrupt');
+            }
+            if (!data || typeof data !== 'object' || Array.isArray(data) || canonicalGrowthJson(data) !== row.data)
+                fail('verification data corrupt');
+            const fields = data;
+            const keys = Object.keys(data);
+            if (keys.some(key => !['discovery', 'contract', 'cases', 'activeCase', 'certificate', 'reason'].includes(key))
+                || fields.cases !== undefined && (!fields.cases || typeof fields.cases !== 'object' || Array.isArray(fields.cases))
+                || fields.activeCase !== undefined && (Object.keys(fields.activeCase).sort().join(',') !== 'caseId,operationDigest'
+                    || typeof fields.activeCase.caseId !== 'string' || !ID.test(fields.activeCase.caseId)
+                    || typeof fields.activeCase.operationDigest !== 'string' || !SHA.test(fields.activeCase.operationDigest))
+                || ['rejected', 'unknown'].includes(row.state) && (typeof fields.reason !== 'string' || !fields.reason.trim() || fields.reason.length > 4096)
+                || !['rejected', 'unknown'].includes(row.state) && fields.reason !== undefined
+                || row.state !== 'certificate' && fields.certificate !== undefined
+                || row.state === 'certificate' && fields.certificate === undefined)
+                fail('verification fields corrupt');
+            const stageKeys = keys.filter(key => key !== 'reason').sort().join(',');
+            const prefixes = ['', 'discovery', 'cases,contract,discovery', 'activeCase,cases,contract,discovery'];
+            const expectedKeys = row.state === 'discover-claimed' ? prefixes[0]
+                : row.state === 'contract-claimed' ? prefixes[1]
+                    : row.state === 'case-claimed' ? prefixes[3]
+                        : row.state === 'certificate' ? 'cases,certificate,contract,discovery' : prefixes[2];
+            if (terminal ? !prefixes.includes(stageKeys) : stageKeys !== expectedKeys)
+                fail('verification stage corrupt');
+            counts.set(row.authority, counts.get(row.authority) + 1);
+            history.update(canonicalGrowthJson(row)).update('\n');
+        }
+        if (grants.some(row => counts.get(row.authority) !== row.used))
+            fail('used/history mismatch');
+        return { digest: overrideDigest ?? grant.digest, maximum: grant.maximum, used: grant.used,
+            grantsDigest: hash(grants.map(row => row.authority === authority && overrideDigest ? { ...row, digest: overrideDigest } : row)),
+            historyDigest: history.digest('hex'), historyCount: rows.length };
+    }
+    #auditSnapshot(excludeTransaction) {
+        const exists = this.#db.prepare("SELECT name FROM sqlite_schema WHERE name=?").get(auditTable);
+        const rows = exists ? this.#db.prepare(`SELECT transaction_id,proof FROM ${auditTable} ORDER BY transaction_id COLLATE BINARY`).all() : [];
+        const retained = rows.filter(row => row.transaction_id !== excludeTransaction);
+        return { count: retained.length, digest: hash(retained) };
+    }
+    /** Snapshot only; no schema, grant, audit or journal-mode changes. */
+    planGrantHandoff(scope) {
+        if (!validScope(scope))
+            fail('invalid handoff scope');
+        return this.#transaction(() => {
+            const before = this.#snapshot(scope.authority);
+            if (before.digest === scope.toDigest)
+                fail('handoff digest unchanged');
+            const body = { ...scope, protocol: 'dsh-review-grant-handoff/v1',
+                file: { path: this.#path, ...this.#identity }, before, auditBefore: this.#auditSnapshot() };
+            return Object.freeze({ ...body, file: Object.freeze(body.file), before: Object.freeze(before), auditBefore: Object.freeze(body.auditBefore), planDigest: hash(body) });
+        });
+    }
+    /** CAS and immutable audit commit together. Reuse only before any writer resumes. */
+    applyGrantHandoff(plan) {
+        if (!plan || !validScope(plan) || plan.protocol !== 'dsh-review-grant-handoff/v1')
+            fail('invalid handoff plan');
+        const { planDigest, ...body } = plan;
+        if (hash(body) !== planDigest || !SHA.test(planDigest) || plan.file.path !== this.#path
+            || plan.file.dev !== this.#identity.dev || plan.file.ino !== this.#identity.ino
+            || !SHA.test(plan.before.digest) || plan.before.digest === plan.toDigest
+            || !plan.auditBefore || !Number.isSafeInteger(plan.auditBefore.count) || plan.auditBefore.count < 0
+            || !SHA.test(plan.auditBefore.digest))
+            fail('invalid handoff plan');
+        return this.#transaction(() => {
+            const current = this.#snapshot(plan.authority);
+            const audit = this.#db.prepare("SELECT name FROM sqlite_schema WHERE name=?").get(auditTable);
+            if (audit) {
+                const prior = this.#db.prepare(`SELECT proof FROM ${auditTable} WHERE transaction_id=?`).get(plan.transactionId);
+                if (prior) {
+                    const proof = JSON.parse(String(prior.proof));
+                    if (prior.proof !== canonicalGrowthJson({ plan, after: current })
+                        || canonicalGrowthJson(proof.plan) !== canonicalGrowthJson(plan)
+                        || canonicalGrowthJson(proof.after) !== canonicalGrowthJson(current)
+                        || canonicalGrowthJson(this.#auditSnapshot(plan.transactionId)) !== canonicalGrowthJson(plan.auditBefore)
+                        || this.#auditSnapshot().count !== plan.auditBefore.count + 1)
+                        fail('handoff retry conflict or drift');
+                    return proof;
+                }
+                if (Number(this.#db.prepare(`SELECT COUNT(*) AS n FROM ${auditTable}`).get()?.n) >= 64)
+                    fail('handoff audit limit');
+            }
+            if (canonicalGrowthJson(current) !== canonicalGrowthJson(plan.before)
+                || canonicalGrowthJson(this.#auditSnapshot()) !== canonicalGrowthJson(plan.auditBefore))
+                fail('handoff snapshot changed');
+            if (!audit)
+                this.#db.exec([auditSchema, ...auditTriggers].join(';'));
+            const after = this.#snapshot(plan.authority, plan.toDigest);
+            const result = this.#db.prepare('UPDATE grants SET digest=? WHERE authority=? AND digest=? AND maximum=? AND used=?')
+                .run(plan.toDigest, plan.authority, current.digest, current.maximum, current.used);
+            if (result.changes !== 1)
+                fail('handoff compare-and-swap failed');
+            const proof = { plan, after };
+            this.#db.prepare(`INSERT INTO ${auditTable}(transaction_id,proof) VALUES(?,?)`).run(plan.transactionId, canonicalGrowthJson(proof));
+            if (canonicalGrowthJson(this.#snapshot(plan.authority)) !== canonicalGrowthJson(after))
+                fail('handoff changed history');
+            return Object.freeze(proof);
+        });
+    }
+    #lineageAudits() {
+        const exists = this.#db.prepare('SELECT name FROM sqlite_schema WHERE name=?').get(auditTable);
+        if (!exists)
+            return [];
+        const rows = this.#db.prepare(`SELECT proof FROM ${auditTable} LIMIT 65`).all();
+        if (rows.length > 64)
+            lineageFail('chain limit');
+        return rows.map(row => {
+            if (typeof row.proof !== 'string' || Buffer.byteLength(row.proof) > 1_048_576)
+                lineageFail('proof bound');
+            const proof = JSON.parse(row.proof);
+            if (canonicalGrowthJson(proof) !== row.proof)
+                lineageFail('noncanonical audit proof');
+            this.#validateLineageProof(proof);
+            return proof;
+        });
+    }
+    #validateLineageProof(proof) {
+        if (!proof || Object.keys(proof).sort().join() !== 'after,plan' || !proof.plan
+            || proof.plan.protocol !== 'dsh-review-grant-handoff/v2')
+            lineageFail('v1 is not a history root');
+        const p = proof.plan, { planDigest, ...body } = p;
+        validateScope(p.scope);
+        if (Object.keys(p).sort().join() !== 'auditBefore,before,file,members,planDigest,protocol,scope,seals'
+            || hash(body) !== planDigest || !SHA.test(planDigest) || !p.file || !isAbsolute(p.file.path)
+            || !Number.isSafeInteger(p.file.dev) || !Number.isSafeInteger(p.file.ino)
+            || !p.auditBefore || !Number.isSafeInteger(p.auditBefore.count) || p.auditBefore.count < 0 || p.auditBefore.count >= 64 || !SHA.test(p.auditBefore.digest)
+            || !Array.isArray(p.members) || p.members.length > p.scope.oldIdentity.maximum
+            || p.members.some((id, i) => typeof id !== 'string' || !ID.test(id) || i > 0 && id <= p.members[i - 1])
+            || Buffer.byteLength(canonicalGrowthJson(p.members)) > 262_144
+            || !Array.isArray(p.seals) || p.seals.length > p.scope.oldIdentity.maximum || Buffer.byteLength(canonicalGrowthJson(p.seals)) > 262_144
+            || p.before.digest !== p.scope.oldIdentity.authority.authorityDigest || proof.after.digest !== p.scope.newIdentity.authority.authorityDigest
+            || p.before.maximum !== p.scope.oldIdentity.maximum || !Number.isSafeInteger(p.before.used) || p.before.used < 1 || p.before.used > p.before.maximum
+            || p.members.length !== p.before.used || p.seals.some(seal => !p.members.includes(seal.planId))
+            || p.seals.length > p.before.used || !SHA.test(p.before.historyDigest) || !SHA.test(p.before.grantsDigest)
+            || !SHA.test(proof.after.grantsDigest)
+            || !same({ ...p.before, digest: proof.after.digest, grantsDigest: proof.after.grantsDigest }, proof.after))
+            lineageFail('invalid v2 proof');
+        let previous = '';
+        for (const seal of p.seals) {
+            if (!seal || Object.keys(seal).sort().join() !== 'certificateDigest,planId,rowDigest' || !ID.test(seal.planId)
+                || seal.planId <= previous || !SHA.test(seal.rowDigest) || !SHA.test(seal.certificateDigest))
+                lineageFail('invalid seal');
+            previous = seal.planId;
+        }
+    }
+    #lineageChain(audits, headDigest, identity, scope) {
+        const byDigest = new Map(audits.map(proof => [hash(proof), proof]));
+        const chain = [], seen = new Set(), identities = new Set();
+        let next = headDigest, current = identity;
+        while (next !== null) {
+            if (chain.length >= 64 || seen.has(next))
+                lineageFail('chain cycle or bound');
+            const proof = byDigest.get(next);
+            if (!proof)
+                lineageFail('broken chain');
+            const s = proof.plan.scope;
+            if (!same(s.newIdentity, current) || ['installationId', 'profileId', 'lane', 'logicalDatabaseScope'].some(k => s[k] !== scope[k]))
+                lineageFail('chain identity or scope');
+            if (identities.has(s.newIdentity.authority.authorityDigest))
+                lineageFail('authority ABA');
+            identities.add(s.newIdentity.authority.authorityDigest);
+            seen.add(next);
+            chain.push(proof);
+            current = s.oldIdentity;
+            next = s.previousHeadDigest;
+        }
+        if (identities.has(current.authority.authorityDigest))
+            lineageFail('authority ABA');
+        const earlierMembers = new Set();
+        for (const proof of [...chain].reverse()) {
+            const members = new Set(proof.plan.members);
+            if ([...earlierMembers].some(member => !members.has(member))
+                || proof.plan.seals.some(seal => earlierMembers.has(seal.planId)))
+                lineageFail('historical member eligibility changed');
+            for (const member of members)
+                earlierMembers.add(member);
+        }
+        return chain;
+    }
+    #terminalSeals(identity, excludedMembers = new Set()) {
+        const rows = this.#db.prepare("SELECT * FROM verifications WHERE authority=? AND state='certificate' ORDER BY plan COLLATE BINARY LIMIT 1001")
+            .all(identity.authority.authorityId);
+        if (rows.length > identity.maximum)
+            lineageFail('terminal bound');
+        const seals = [];
+        for (const row of rows) {
+            if (excludedMembers.has(row.plan))
+                continue;
+            const data = JSON.parse(row.data);
+            // Previous identities remain eligible only through their earlier seals.
+            if (!same(data.certificate?.authority, identity.authority))
+                continue;
+            if (data.certificate?.plan?.id !== row.plan)
+                lineageFail('certificate plan mismatch');
+            seals.push({ planId: row.plan, rowDigest: hash(row), certificateDigest: hash(data.certificate) });
+        }
+        if (Buffer.byteLength(canonicalGrowthJson(seals)) > 262_144)
+            lineageFail('seal bytes bound');
+        return seals;
+    }
+    #members(authority) {
+        const rows = this.#db.prepare('SELECT plan FROM verifications WHERE authority=? ORDER BY plan COLLATE BINARY LIMIT 1001').all(authority);
+        if (rows.length > 1000)
+            lineageFail('membership limit');
+        return rows.map(row => String(row.plan));
+    }
+    #priorMembers(audits) { return new Set(audits.flatMap(proof => proof.plan.members)); }
+    #checkPrevious(scope, audits) {
+        if (scope.previousHeadDigest === null) {
+            if (audits.length)
+                lineageFail('existing history requires previous head');
+            return;
+        }
+        const chain = this.#lineageChain(audits, scope.previousHeadDigest, scope.oldIdentity, scope);
+        const currentMembers = new Set(this.#members(scope.oldIdentity.authority.authorityId));
+        if (chain.some(proof => proof.plan.members.some(member => !currentMembers.has(member))))
+            lineageFail('historical membership removed');
+        if (chain.length !== audits.length || chain.some(p => p.plan.scope.oldIdentity.authority.authorityDigest === scope.newIdentity.authority.authorityDigest
+            || p.plan.scope.newIdentity.authority.authorityDigest === scope.newIdentity.authority.authorityDigest))
+            lineageFail('branch or authority ABA');
+        for (const proof of chain)
+            for (const seal of proof.plan.seals) {
+                const row = this.#db.prepare('SELECT * FROM verifications WHERE plan=?').get(seal.planId);
+                if (!row || row.state !== 'certificate' || hash(row) !== seal.rowDigest
+                    || hash(JSON.parse(row.data).certificate) !== seal.certificateDigest)
+                    lineageFail('inherited seal changed');
+            }
+    }
+    planGrantHandoffV2(scope) {
+        validateScope(scope);
+        return this.#transaction(() => {
+            const before = this.#snapshot(scope.oldIdentity.authority.authorityId);
+            if (before.digest !== scope.oldIdentity.authority.authorityDigest || before.maximum !== scope.oldIdentity.maximum)
+                lineageFail('old grant identity');
+            const audits = this.#lineageAudits();
+            this.#checkPrevious(scope, audits);
+            const body = { protocol: 'dsh-review-grant-handoff/v2', scope: structuredClone(scope),
+                file: { path: this.#path, ...this.#identity }, before, auditBefore: this.#auditSnapshot(), members: this.#members(scope.oldIdentity.authority.authorityId), seals: this.#terminalSeals(scope.oldIdentity, this.#priorMembers(audits)) };
+            return structuredClone({ ...body, planDigest: hash(body) });
+        });
+    }
+    applyGrantHandoffV2(plan) {
+        // Validate via a synthetic after snapshot before any database mutation.
+        const { planDigest: _, ...body } = plan;
+        validateScope(plan.scope);
+        if (hash(body) !== plan.planDigest || !same(plan.file, { path: this.#path, ...this.#identity }))
+            lineageFail('plan or file changed');
+        return this.#transaction(() => {
+            const current = this.#snapshot(plan.scope.oldIdentity.authority.authorityId), audits = this.#lineageAudits();
+            const prior = audits.find(p => p.plan.scope.transactionId === plan.scope.transactionId);
+            if (prior) {
+                if (!same(prior.plan, plan) || !same(prior.after, current) || !same(this.#auditSnapshot(plan.scope.transactionId), plan.auditBefore)
+                    || this.#auditSnapshot().count !== plan.auditBefore.count + 1 || !same(this.#members(plan.scope.oldIdentity.authority.authorityId), plan.members)
+                    || !same(this.#terminalSeals(plan.scope.oldIdentity, this.#priorMembers(audits.filter(p => p !== prior))), plan.seals))
+                    lineageFail('retry drift');
+                return prior;
+            }
+            this.#checkPrevious(plan.scope, audits);
+            if (audits.length >= 64 || !same(current, plan.before) || !same(this.#auditSnapshot(), plan.auditBefore)
+                || !same(this.#members(plan.scope.oldIdentity.authority.authorityId), plan.members)
+                || !same(this.#terminalSeals(plan.scope.oldIdentity, this.#priorMembers(audits)), plan.seals))
+                lineageFail('snapshot or seals changed');
+            const after = this.#snapshot(plan.scope.oldIdentity.authority.authorityId, plan.scope.newIdentity.authority.authorityDigest);
+            const proof = { plan, after };
+            this.#validateLineageProof(proof);
+            if (!this.#db.prepare('SELECT name FROM sqlite_schema WHERE name=?').get(auditTable))
+                this.#db.exec([auditSchema, ...auditTriggers].join(';'));
+            const changed = this.#db.prepare('UPDATE grants SET digest=? WHERE authority=? AND digest=? AND maximum=? AND used=?')
+                .run(after.digest, plan.scope.oldIdentity.authority.authorityId, current.digest, current.maximum, current.used);
+            if (changed.changes !== 1)
+                lineageFail('CAS failed');
+            this.#db.prepare(`INSERT INTO ${auditTable}(transaction_id,proof) VALUES(?,?)`).run(plan.scope.transactionId, canonicalGrowthJson(proof));
+            if (!same(this.#snapshot(plan.scope.oldIdentity.authority.authorityId), after))
+                lineageFail('history changed');
+            return structuredClone(proof);
+        });
+    }
+    /** Same existing connection, one read transaction. Does not claim, migrate, or change quota. */
+    resolveHistoricalCertificate(request) {
+        validateRequest(request);
+        this.#checkFile();
+        if (!same(request.currentFileIdentity, this.#identity))
+            lineageFail('current file identity');
+        if (this.#closed)
+            lineageFail('closed');
+        this.#db.exec('BEGIN');
+        try {
+            this.#maintenanceSchema(true);
+            const audits = this.#lineageAudits(), chain = this.#lineageChain(audits, request.headDigest, request.currentIdentity, request);
+            if (chain.length !== audits.length || !same(chain[0]?.plan.file, { path: chain[0]?.plan.file.path, ...request.currentFileIdentity }))
+                lineageFail('current head file or branch');
+            const currentMembers = new Set(this.#members(request.currentIdentity.authority.authorityId));
+            if (chain.some(proof => proof.plan.members.some(member => !currentMembers.has(member))))
+                lineageFail('historical membership removed');
+            const grant = this.#db.prepare('SELECT * FROM grants WHERE authority=?').get(request.currentIdentity.authority.authorityId);
+            const count = Number(this.#db.prepare('SELECT COUNT(*) AS n FROM verifications WHERE authority=?').get(request.currentIdentity.authority.authorityId)?.n);
+            if (!grant || grant.digest !== request.currentIdentity.authority.authorityDigest || grant.maximum !== request.currentIdentity.maximum
+                || !Number.isSafeInteger(grant.used) || grant.used !== count || grant.used < chain[0].after.used || grant.used > grant.maximum)
+                lineageFail('current grant changed');
+            const row = this.#db.prepare('SELECT * FROM verifications WHERE plan=?').get(request.planId);
+            if (!row || row.state !== 'certificate' || row.authority !== grant.authority || Buffer.byteLength(row.data) > 262_144)
+                lineageFail('exact terminal row required');
+            const data = JSON.parse(row.data);
+            if (canonicalGrowthJson(data) !== row.data || !data.certificate || data.certificate.plan?.id !== row.plan)
+                lineageFail('terminal data');
+            const rowDigest = hash(row), certificateDigest = hash(data.certificate);
+            const sealed = chain.find(proof => proof.plan.seals.some(seal => seal.planId === row.plan && seal.rowDigest === rowDigest && seal.certificateDigest === certificateDigest));
+            if (!sealed || !same(data.certificate.authority, sealed.plan.scope.oldIdentity.authority))
+                lineageFail('unsealed terminal row');
+            this.#checkFile();
+            this.#db.exec('COMMIT');
+            return structuredClone({ certificate: data.certificate, identity: sealed.plan.scope.oldIdentity });
+        }
+        catch (error) {
+            this.#db.exec('ROLLBACK');
+            throw error;
+        }
+    }
+    /** Offline checkpointed adapter only. Live runtime should use its already-open store method above. */
+    static resolveHistoricalCertificate(path, request) {
+        validateRequest(request);
+        for (const suffix of ['-wal', '-journal']) {
+            try {
+                if (lstatSync(path + suffix).size)
+                    lineageFail('offline checkpoint required');
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT')
+                    throw error;
+            }
+        }
+        const store = new CreationReviewStore(path, readOnlyMaintenance);
+        try {
+            return store.resolveHistoricalCertificate(request);
+        }
+        finally {
+            store.close();
+        }
+    }
     close() { if (!this.#closed) {
         this.#closed = true;
         this.#db.close();
@@ -64,6 +571,8 @@ export class CreationReviewStore {
     #transaction(callback) {
         if (this.#closed)
             fail('closed');
+        if (this.#maintenance)
+            this.#checkFile();
         this.#db.exec('BEGIN IMMEDIATE');
         try {
             const result = callback();