@astrosheep/square 0.3.72 → 0.3.73

package/dist/host-ledger-migration.js

@@ -0,0 +1,227 @@
+import { createHash } from 'node:crypto';
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { DatabaseSync } from 'node:sqlite';
+import { canonicalPathSync } from './canonical-path.js';
+import { withFileLock } from './file-lock.js';
+import { hostLedgerRoot } from './host-ledger-root.js';
+import { LEDGER_FILENAME, initializeLedger, insertLedgerRecord, ledgerRecordColumns, setLedgerRevisions, upgradeLedger, validateLedger, verifyLedger, } from './host-ledger-sqlite.js';
+import { inSqliteTransaction } from './sqlite-transaction.js';
+function rootFor(options) {
+    return canonicalPathSync(options.rootPath ?? hostLedgerRoot(options.env));
+}
+function abort(signal) {
+    if (signal?.aborted)
+        throw signal.reason ?? new Error('Host ledger migration aborted');
+}
+async function exists(file) {
+    try {
+        await fs.lstat(file);
+        return true;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return false;
+        throw error;
+    }
+}
+/** Generic and payload-free: the only supported remedy is offline conversion under stopped hosts. */
+function verificationFailure() {
+    return new Error('Host ledger database verification failed; destination left untouched.\nStop all Square hosts, then run: square ledger migrate');
+}
+async function verifyDatabase(file, signal) {
+    abort(signal);
+    let db;
+    try {
+        db = new DatabaseSync(file, { readOnly: true });
+        const counts = await inSqliteTransaction(db, false, () => validateLedger(db), () => verifyLedger(db), signal);
+        return { status: 'sqlite', ...counts };
+    }
+    catch {
+        abort(signal);
+        throw verificationFailure();
+    }
+    finally {
+        db?.close();
+    }
+}
+async function readLegacy(root, kind, signal) {
+    let bytes;
+    try {
+        bytes = await fs.readFile(path.join(root, `${kind}.ndjsonl`));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return { rows: [], report: { records: 0, ignored: 0, rejected: 0, sha256: null } };
+        throw new Error(`Cannot read legacy ${kind} source.`);
+    }
+    const rows = [];
+    let ignored = 0, rejected = 0;
+    let firstRejectedLine;
+    const lines = bytes.toString('utf8').split('\n');
+    for (let index = 0; index < lines.length; index++) {
+        abort(signal);
+        if (lines[index].trim() === '')
+            continue;
+        let row;
+        try {
+            row = JSON.parse(lines[index]);
+        }
+        catch {
+            ignored++;
+            continue;
+        }
+        if (row === null || typeof row !== 'object' || row.v !== 1 || typeof (row.at ?? row.updatedAt) !== 'number') {
+            ignored++;
+            continue;
+        }
+        // This compatibility normalization belongs only to the explicit importer.
+        if (row.kind === 'wake' && row.outcome === 'unknown' && row.unknownSource === undefined) {
+            row = { ...row, unknownSource: row.signature === 'worker_interrupted_during_dispatch' ? 'interrupted' : 'transport' };
+        }
+        try {
+            ledgerRecordColumns(kind, row);
+        }
+        catch {
+            rejected++;
+            firstRejectedLine ??= index + 1;
+            continue;
+        }
+        rows.push(row);
+    }
+    return { rows, firstRejectedLine, report: { records: rows.length, ignored, rejected, sha256: createHash('sha256').update(bytes).digest('hex') } };
+}
+async function readSources(root, signal) {
+    return { presence: await readLegacy(root, 'presence', signal), evidence: await readLegacy(root, 'evidence', signal) };
+}
+function sourceReport(sources) {
+    return {
+        status: sources.presence.report.sha256 === null && sources.evidence.report.sha256 === null ? 'empty' : 'legacy',
+        presence: sources.presence.rows.length, evidence: sources.evidence.rows.length,
+        sources: { presence: sources.presence.report, evidence: sources.evidence.report },
+        ready: sources.presence.report.rejected === 0 && sources.evidence.report.rejected === 0,
+    };
+}
+/** Read-only readiness/integrity check. Never creates a root, lock, or database. */
+export async function verifyHostLedger(options = {}) {
+    const root = rootFor(options);
+    abort(options.signal);
+    const destination = path.join(root, LEDGER_FILENAME);
+    if (await exists(destination))
+        return verifyDatabase(destination, options.signal);
+    return sourceReport(await readSources(root, options.signal));
+}
+/** The fixed offline fence: ownership claim, then both legacy source locks, in that order. */
+function withOfflineLocks(root, signal, body) {
+    const lockOptions = { retryMs: 10, signal };
+    return withFileLock(path.join(root, 'presence-claim.lock'), lockOptions, () => withFileLock(path.join(root, 'presence.ndjsonl.lock'), lockOptions, () => withFileLock(path.join(root, 'evidence.ndjsonl.lock'), lockOptions, body)))
+        .catch((error) => { abort(signal); throw error; });
+}
+/**
+ * Under the offline fence: a current ledger verifies read-only, an older SQLite format is upgraded in
+ * place through the explicit transaction owner, and anything else is refused without repair.
+ */
+async function currentFormat(root, signal) {
+    const destination = path.join(root, LEDGER_FILENAME);
+    try {
+        return await verifyDatabase(destination, signal);
+    }
+    catch {
+        abort(signal);
+    }
+    if (!await exists(destination))
+        throw verificationFailure();
+    let db;
+    try {
+        db = new DatabaseSync(destination);
+        const upgraded = await inSqliteTransaction(db, true, () => { }, () => upgradeLedger(db), signal);
+        db.close();
+        db = undefined;
+        return { ...await verifyDatabase(destination, signal), status: upgraded ? 'upgraded' : 'sqlite' };
+    }
+    catch {
+        abort(signal);
+        throw verificationFailure();
+    }
+    finally {
+        db?.close();
+    }
+}
+/** Offline only: locks fence compatible writers, but do not prove hosts have stopped. */
+export async function migrateHostLedger(options = {}) {
+    const root = rootFor(options), signal = options.signal;
+    abort(signal);
+    const destination = path.join(root, LEDGER_FILENAME);
+    if (await exists(destination)) {
+        try {
+            return await verifyDatabase(destination, signal);
+        }
+        catch {
+            abort(signal);
+        }
+        // An older SQLite format is upgraded offline; a current ledger stays a read-only no-op.
+        return withOfflineLocks(root, signal, () => currentFormat(root, signal));
+    }
+    if (!await exists(path.join(root, 'presence.ndjsonl')) && !await exists(path.join(root, 'evidence.ndjsonl'))) {
+        return { status: 'empty', presence: 0, evidence: 0 };
+    }
+    return withOfflineLocks(root, signal, () => convertLegacy(root, destination, signal));
+}
+/** The offline NDJSON import: build, verify and publish a new database without touching sources. */
+async function convertLegacy(root, destination, signal) {
+    if (await exists(destination))
+        return currentFormat(root, signal);
+    const sources = await readSources(root, signal);
+    const report = sourceReport(sources);
+    if (!report.ready) {
+        const rejected = ['presence', 'evidence'].filter((kind) => sources[kind].report.rejected > 0)
+            .map((kind) => `${kind}: ${sources[kind].report.rejected} rejected (first line ${sources[kind].firstRejectedLine})`);
+        throw new Error(`Unsafe legacy records; conversion refused. ${rejected.join('; ')}.`);
+    }
+    const temporary = await fs.mkdtemp(path.join(root, '.host-ledger-migrate-'));
+    const file = path.join(temporary, LEDGER_FILENAME);
+    let db;
+    try {
+        abort(signal);
+        // The temporary connection remains under the ledger root, including journals.
+        await fs.writeFile(file, '', { flag: 'wx', mode: 0o600 });
+        db = new DatabaseSync(file);
+        initializeLedger(db);
+        await inSqliteTransaction(db, true, () => { }, () => {
+            for (const kind of ['presence', 'evidence']) {
+                for (const row of sources[kind].rows) {
+                    abort(signal);
+                    insertLedgerRecord(db, kind, row);
+                }
+            }
+            setLedgerRevisions(db, { presence: report.presence ? 1 : 0, evidence: report.evidence ? 1 : 0 });
+        }, signal);
+        db.close();
+        db = undefined;
+        const verified = await verifyDatabase(file, signal);
+        if (verified.presence !== report.presence || verified.evidence !== report.evidence) {
+            throw new Error('Host ledger import counts do not match; conversion refused.');
+        }
+        abort(signal);
+        try {
+            await fs.link(file, destination);
+        }
+        catch (error) {
+            if (error.code === 'EEXIST')
+                return await verifyDatabase(destination, signal);
+            throw error;
+        }
+        const directory = await fs.open(root, 'r');
+        try {
+            await directory.sync();
+        }
+        finally {
+            await directory.close();
+        }
+        return { ...verified, status: 'migrated', sources: report.sources };
+    }
+    finally {
+        db?.close();
+        await fs.rm(temporary, { recursive: true, force: true });
+    }
+}

package/dist/host-ledger-sqlite.d.ts

@@ -0,0 +1,62 @@
+import { DatabaseSync, type SQLInputValue } from 'node:sqlite';
+import type { PresenceRecord, PresenceLookup, EvidenceRecord, EvidenceLookup, NativeTokenLookup, NativeTokenResult } from './host-ledger.js';
+export declare const LEDGER_FILENAME = "host-ledger.sqlite";
+export declare const LEDGER_APPLICATION_ID = 1397835852;
+export declare const LEDGER_VERSION = 2;
+export declare const LEDGER_RETENTION: number;
+type Kind = 'presence' | 'evidence';
+export interface Stored<T> {
+    readonly seq: number;
+    readonly record: T;
+}
+/** The complete record remains authority; these are only reproducible lookup projections. */
+export declare function ledgerRecordColumns(kind: Kind, input: object): Record<string, SQLInputValue>;
+export declare function initializeLedger(db: DatabaseSync): void;
+export declare function setLedgerRevisions(db: DatabaseSync, revisions: {
+    presence: number;
+    evidence: number;
+}): void;
+export declare function insertLedgerRecord(db: DatabaseSync, kind: Kind, row: object): void;
+export declare function ledgerRevisions(db: DatabaseSync): {
+    presence: number;
+    evidence: number;
+};
+export declare function validateLedger(db: DatabaseSync): void;
+export declare function verifyLedger(db: DatabaseSync): {
+    presence: number;
+    evidence: number;
+    presenceRevision: number;
+    evidenceRevision: number;
+};
+/** Explicit offline migration only; the caller owns the write transaction. Preserve all records and revisions. */
+export declare function upgradeLedger(db: DatabaseSync): boolean;
+export declare function migrationRequired(): Error;
+/** Transaction-local storage rows; sequence coordinates never cross HostLedgerPort. */
+export declare class LedgerTransaction {
+    private readonly db;
+    private readonly changed;
+    constructor(db: DatabaseSync);
+    presence(input: PresenceLookup & {
+        channel?: string;
+    }, now: number, includeFuture?: boolean): Stored<PresenceRecord>[];
+    evidence(input: EvidenceLookup & {
+        claimToken?: string;
+    }, now: number, includeFuture?: boolean): Stored<EvidenceRecord>[];
+    private select;
+    /** Both halves of recognition are read in the enclosing SQLite snapshot, with indexed session/token predicates. */
+    nativeTokens(input: NativeTokenLookup): NativeTokenResult;
+    /** Called only after exact-record CAS. No housekeeping of unrelated rows belongs here. */
+    retireEvidence(row: Stored<EvidenceRecord>): boolean;
+    insert(kind: Kind, row: object): void;
+    replace(kind: Kind, seq: number, row: object): void;
+    remove(kind: Kind, rows: readonly Stored<unknown>[]): void;
+    /** Only invoke at the point where the former implementation published a mutation. */
+    publish(kind: Kind, now: number): void;
+    commitRevisions(): void;
+}
+export declare function withLedger<T>(root: string, write: boolean, select: (rows: LedgerTransaction) => T, absent: T, signal?: AbortSignal): Promise<T>;
+export declare function readLedgerRevisions(root: string, signal?: AbortSignal): Promise<{
+    presence: number;
+    evidence: number;
+} | undefined>;
+export {};

package/dist/host-ledger-sqlite.js

@@ -0,0 +1,341 @@
+import { DatabaseSync } from 'node:sqlite';
+import { randomUUID } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { nameKey } from './model.js';
+import { inSqliteTransaction, retrySqliteBusy } from './sqlite-transaction.js';
+export const LEDGER_FILENAME = 'host-ledger.sqlite';
+export const LEDGER_APPLICATION_ID = 0x5351484c;
+export const LEDGER_VERSION = 2;
+export const LEDGER_RETENTION = 7 * 86400000;
+const tables = { presence: 'host_presence', evidence: 'host_evidence' };
+const columns = {
+    presence: ['location_key', 'participant_key', 'session_key', 'channel_key', 'effective_at'],
+    evidence: ['location_key', 'participant_key', 'session_key', 'activity_key', 'kind', 'outcome', 'claim_token_key', 'effective_at'],
+};
+const indexes = {
+    host_presence_identity: ['host_presence', 'location_key', 'participant_key', 'seq'],
+    host_presence_session: ['host_presence', 'session_key', 'seq'],
+    host_presence_time: ['host_presence', 'effective_at'],
+    host_evidence_attention: ['host_evidence', 'location_key', 'participant_key', 'activity_key', 'kind', 'session_key', 'seq'],
+    host_evidence_kind_session: ['host_evidence', 'kind', 'session_key', 'seq'],
+    host_evidence_session: ['host_evidence', 'session_key', 'seq'],
+    host_evidence_token: ['host_evidence', 'location_key', 'participant_key', 'activity_key', 'session_key', 'claim_token_key', 'seq'],
+    host_evidence_outcome_time: ['host_evidence', 'outcome', 'effective_at'],
+    host_evidence_time: ['host_evidence', 'effective_at'],
+    host_evidence_native_token: ['host_evidence', 'session_key', 'claim_token_key', 'seq'],
+};
+const tableSchema = {
+    host_meta: 'CREATE TABLE host_meta (id INTEGER PRIMARY KEY CHECK(id=1), presence_revision INTEGER NOT NULL, evidence_revision INTEGER NOT NULL)',
+    host_presence: 'CREATE TABLE host_presence (seq INTEGER PRIMARY KEY AUTOINCREMENT, location_key TEXT NOT NULL, participant_key TEXT NOT NULL, session_key TEXT NOT NULL, channel_key TEXT NOT NULL, effective_at REAL NOT NULL, row_json TEXT NOT NULL)',
+    host_evidence: 'CREATE TABLE host_evidence (seq INTEGER PRIMARY KEY AUTOINCREMENT, location_key TEXT NOT NULL, participant_key TEXT NOT NULL, session_key TEXT NOT NULL, activity_key TEXT NOT NULL, kind TEXT NOT NULL, outcome TEXT NOT NULL, claim_token_key TEXT, effective_at REAL NOT NULL, row_json TEXT NOT NULL)',
+    host_native_tokens: "CREATE TABLE host_native_tokens (harness TEXT NOT NULL CHECK(harness='claude'), session_key TEXT NOT NULL, token_key TEXT NOT NULL, PRIMARY KEY(harness,session_key,token_key)) WITHOUT ROWID",
+};
+const versionTwoNames = new Set(['host_native_tokens', 'host_evidence_native_token']);
+const retainedEvidence = "(kind='wake' AND (outcome IN ('accepted','unknown','dispatching') OR COALESCE(json_extract(row_json,'$.nativeDelivery.harness'),'')='claude'))";
+function validToken(token) { return typeof token === 'string' && /^[a-zA-Z0-9-]+$/.test(token); }
+function indexSql(name, [table, ...fields]) {
+    return `CREATE INDEX ${name} ON ${table} (${fields.join(',')})`;
+}
+function invalid(message) { return new Error(`Invalid host ledger: ${message}`); }
+function key(value) { return JSON.stringify(value); }
+/** The complete record remains authority; these are only reproducible lookup projections. */
+export function ledgerRecordColumns(kind, input) {
+    const row = input;
+    if (!row || Array.isArray(row) || row.v !== 1)
+        throw invalid('record version');
+    for (const field of ['location', 'participant', 'session', ...(kind === 'presence' ? ['channel'] : ['activity', 'kind', 'outcome'])]) {
+        if (typeof row[field] !== 'string')
+            throw invalid(`record ${field}`);
+    }
+    if (kind === 'evidence' && row.claimToken !== undefined && typeof row.claimToken !== 'string')
+        throw invalid('record claimToken');
+    const at = row.at ?? row.updatedAt;
+    if (typeof at !== 'number' || !Number.isFinite(at))
+        throw invalid('record time');
+    return {
+        location_key: key(row.location), participant_key: key(nameKey(row.participant)), session_key: key(row.session),
+        ...(kind === 'presence' ? { channel_key: key(row.channel) } : {
+            activity_key: key(row.activity), kind: row.kind, outcome: row.outcome,
+            claim_token_key: row.claimToken === undefined ? null : key(row.claimToken),
+        }), effective_at: at,
+    };
+}
+export function initializeLedger(db) {
+    db.exec(`PRAGMA journal_mode=DELETE; PRAGMA synchronous=FULL;
+    PRAGMA application_id=${LEDGER_APPLICATION_ID}; PRAGMA user_version=${LEDGER_VERSION};`);
+    initializeLedgerSchema(db);
+}
+export function setLedgerRevisions(db, revisions) {
+    if (![revisions.presence, revisions.evidence].every((n) => Number.isSafeInteger(n) && n >= 0))
+        throw invalid('revisions');
+    db.prepare('UPDATE host_meta SET presence_revision=?,evidence_revision=? WHERE id=1').run(revisions.presence, revisions.evidence);
+}
+export function insertLedgerRecord(db, kind, row) {
+    const derived = ledgerRecordColumns(kind, row);
+    db.prepare(`INSERT INTO ${tables[kind]} (${columns[kind].join(',')},row_json) VALUES (${columns[kind].map(() => '?').join(',')},?)`)
+        .run(...columns[kind].map((column) => derived[column]), JSON.stringify(row));
+}
+export function ledgerRevisions(db) {
+    const rows = db.prepare('SELECT id,presence_revision,evidence_revision FROM host_meta').all();
+    if (rows.length !== 1 || rows[0].id !== 1 || ![rows[0].presence_revision, rows[0].evidence_revision].every((n) => typeof n === 'number' && Number.isSafeInteger(n) && n >= 0))
+        throw invalid('revisions');
+    return { presence: rows[0].presence_revision, evidence: rows[0].evidence_revision };
+}
+export function validateLedger(db) { validateLedgerAtVersion(db, LEDGER_VERSION); }
+function validateLedgerAtVersion(db, version) {
+    validateLedgerHeader(db, version);
+    if (db.prepare('PRAGMA journal_mode').get()?.journal_mode !== 'delete')
+        throw invalid('journal mode');
+    const expected = new Map([...Object.entries(tableSchema), ...Object.entries(indexes).map(([name, fields]) => [name, indexSql(name, fields)])].filter(([name]) => version >= 2 || !versionTwoNames.has(name)));
+    const schema = db.prepare("SELECT name,sql FROM sqlite_schema WHERE name NOT LIKE 'sqlite_%'").all();
+    const normalize = (sql) => sql.replace(/\s+/g, '').replace(/;$/, '');
+    if (schema.length !== expected.size || schema.some((row) => typeof row.sql !== 'string' || !expected.has(row.name) || normalize(row.sql) !== normalize(expected.get(row.name))))
+        throw invalid('schema or indexes');
+    ledgerRevisions(db);
+}
+export function verifyLedger(db) {
+    return verifyLedgerAtVersion(db, LEDGER_VERSION);
+}
+function verifyLedgerAtVersion(db, version) {
+    validateLedgerAtVersion(db, version);
+    const integrity = db.prepare('PRAGMA integrity_check').all();
+    if (integrity.length !== 1 || integrity[0].integrity_check !== 'ok')
+        throw invalid('integrity check failed');
+    const counts = { presence: 0, evidence: 0 };
+    for (const kind of ['presence', 'evidence']) {
+        for (const stored of db.prepare(`SELECT * FROM ${tables[kind]} ORDER BY seq ASC`).iterate()) {
+            let row;
+            try {
+                row = JSON.parse(stored.row_json);
+            }
+            catch {
+                throw invalid('record JSON');
+            }
+            const derived = ledgerRecordColumns(kind, row);
+            if (!Number.isSafeInteger(stored.seq) || stored.seq < 1 || columns[kind].some((column) => stored[column] !== derived[column]))
+                throw invalid('record projections');
+            counts[kind] += 1;
+        }
+    }
+    if (version >= 2) {
+        for (const row of db.prepare('SELECT harness,session_key,token_key FROM host_native_tokens').iterate()) {
+            try {
+                const session = JSON.parse(row.session_key), token = JSON.parse(row.token_key);
+                if (row.harness !== 'claude' || typeof session !== 'string' || !session.length || !validToken(token)
+                    || key(session) !== row.session_key || key(token) !== row.token_key)
+                    throw invalid('native token codec');
+            }
+            catch {
+                throw invalid('native token codec');
+            }
+        }
+    }
+    const revision = ledgerRevisions(db);
+    if ((counts.presence && !revision.presence) || (counts.evidence && !revision.evidence))
+        throw invalid('records without revision');
+    return { ...counts, presenceRevision: revision.presence, evidenceRevision: revision.evidence };
+}
+/** Explicit offline migration only; the caller owns the write transaction. Preserve all records and revisions. */
+export function upgradeLedger(db) {
+    if (db.prepare('PRAGMA user_version').get()?.user_version === LEDGER_VERSION) {
+        verifyLedger(db);
+        return false;
+    }
+    verifyLedgerAtVersion(db, 1);
+    db.exec(tableSchema.host_native_tokens);
+    db.exec(indexSql('host_evidence_native_token', indexes.host_evidence_native_token));
+    db.exec(`PRAGMA user_version=${LEDGER_VERSION}`);
+    verifyLedger(db);
+    return true;
+}
+function exists(file) { try {
+    fs.statSync(file);
+    return true;
+}
+catch (error) {
+    if (error.code === 'ENOENT')
+        return false;
+    throw error;
+} }
+export function migrationRequired() {
+    return new Error('Host ledger conversion required. Stop all ledger users before running:\nsquare ledger migrate');
+}
+/** Compact runtime framing. Full schema, projections and integrity belong to explicit verify. */
+function validateLedgerHeader(db, version = LEDGER_VERSION) {
+    if (db.prepare('PRAGMA application_id').get()?.application_id !== LEDGER_APPLICATION_ID
+        || db.prepare('PRAGMA user_version').get()?.user_version !== version)
+        throw invalid('unsupported identity or version. Stop all ledger users before running:\nsquare ledger migrate');
+}
+/** Publish new empty authority only. Never initialize or replace an existing destination. */
+function createEmptyLedger(root) {
+    fs.mkdirSync(root, { recursive: true });
+    try {
+        fs.writeFileSync(path.join(root, '.gitignore'), '*\n', { flag: 'wx' });
+    }
+    catch (error) {
+        if (error.code !== 'EEXIST')
+            throw error;
+    }
+    const temporary = path.join(root, `.host-ledger.${process.pid}.${randomUUID()}.tmp`);
+    let db;
+    try {
+        fs.closeSync(fs.openSync(temporary, 'wx', 0o600));
+        db = new DatabaseSync(temporary);
+        initializeLedger(db);
+        db.close();
+        db = undefined;
+        try {
+            fs.linkSync(temporary, path.join(root, LEDGER_FILENAME));
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST')
+                throw error;
+        }
+    }
+    finally {
+        db?.close();
+        fs.rmSync(temporary, { force: true });
+    }
+}
+/** Never create authority on a read, or silently replace legacy authority on a write. */
+async function openLedger(root, write, signal) {
+    const file = path.join(root, LEDGER_FILENAME);
+    if (!exists(file)) {
+        if (exists(path.join(root, 'presence.ndjsonl')) || exists(path.join(root, 'evidence.ndjsonl')))
+            throw migrationRequired();
+        if (!write)
+            return undefined;
+        if (signal?.aborted)
+            throw signal.reason;
+        createEmptyLedger(root);
+    }
+    const uri = pathToFileURL(file);
+    uri.searchParams.set('mode', write ? 'rw' : 'ro');
+    const db = new DatabaseSync(uri.href);
+    try {
+        await retrySqliteBusy(() => db.exec('PRAGMA busy_timeout=0; PRAGMA synchronous=FULL'), signal);
+        return db;
+    }
+    catch (error) {
+        db.close();
+        throw error;
+    }
+}
+function initializeLedgerSchema(db) {
+    for (const sql of Object.values(tableSchema))
+        db.exec(sql);
+    db.exec('INSERT INTO host_meta VALUES(1,0,0)');
+    for (const [name, fields] of Object.entries(indexes))
+        db.exec(indexSql(name, fields));
+}
+function visibility(kind, now, includeFuture, includeExpired) {
+    const durable = kind === 'evidence' ? ` OR ${retainedEvidence}` : '';
+    const sql = includeExpired ? '1' : `(effective_at>=?${durable})`;
+    const args = includeExpired ? [] : [now - LEDGER_RETENTION];
+    if (!includeFuture)
+        args.push(now);
+    return { sql: `${sql}${includeFuture ? '' : ' AND effective_at<=?'}`, args };
+}
+/** Transaction-local storage rows; sequence coordinates never cross HostLedgerPort. */
+export class LedgerTransaction {
+    db;
+    changed = new Set();
+    constructor(db) {
+        this.db = db;
+    }
+    presence(input, now, includeFuture = false) {
+        return this.select('presence', input, now, includeFuture);
+    }
+    evidence(input, now, includeFuture = false) {
+        return this.select('evidence', input, now, includeFuture);
+    }
+    select(kind, input, now, includeFuture) {
+        const visible = visibility(kind, now, includeFuture, kind === 'evidence' && input.includeExpired === true), where = [visible.sql], args = visible.args;
+        for (const [field, column] of Object.entries({ location: 'location_key', participant: 'participant_key', session: 'session_key', ...(kind === 'evidence' ? { activity: 'activity_key', kind: 'kind', claimToken: 'claim_token_key' } : { channel: 'channel_key' }) })) {
+            const value = input[field];
+            if (value !== undefined) {
+                where.push(`${column}=?`);
+                args.push(column === 'kind' ? value : key(field === 'participant' ? nameKey(value) : value));
+            }
+        }
+        if (kind === 'evidence' && input.includeReleased !== true)
+            where.push("outcome<>'released'");
+        return this.db.prepare(`SELECT seq,row_json FROM ${tables[kind]} WHERE ${where.join(' AND ')} ORDER BY seq ASC`).all(...args).map((stored) => ({ seq: stored.seq, record: JSON.parse(stored.row_json) }));
+    }
+    /** Both halves of recognition are read in the enclosing SQLite snapshot, with indexed session/token predicates. */
+    nativeTokens(input) {
+        const tokens = [...new Set(input.tokens)], encoded = JSON.stringify(tokens.map(key));
+        const deliveries = this.db.prepare("SELECT row_json FROM host_evidence WHERE session_key=? AND claim_token_key IN (SELECT value FROM json_each(?)) AND kind='wake' AND json_extract(row_json,'$.nativeDelivery.harness')='claude' ORDER BY seq ASC")
+            .all(key(input.session), encoded).map(row => JSON.parse(row.row_json));
+        const retired = new Set(this.db.prepare('SELECT token_key FROM host_native_tokens WHERE harness=? AND session_key=? AND token_key IN (SELECT value FROM json_each(?))')
+            .all(input.harness, key(input.session), encoded).map(row => row.token_key));
+        return { deliveries, retired: tokens.filter(token => retired.has(key(token))) };
+    }
+    /** Called only after exact-record CAS. No housekeeping of unrelated rows belongs here. */
+    retireEvidence(row) {
+        const record = row.record;
+        if (record.outcome === 'dispatching')
+            return false;
+        if (record.nativeDelivery?.harness === 'claude') {
+            const native = record.nativeDelivery;
+            if (!record.session || !validToken(record.claimToken) || typeof native.payload !== 'string' || !native.payload.length
+                || typeof native.endpoint !== 'string' || !native.endpoint.length || !Number.isSafeInteger(native.epoch) || native.epoch < 0)
+                return false;
+            this.db.prepare("INSERT OR IGNORE INTO host_native_tokens(harness,session_key,token_key) VALUES('claude',?,?)")
+                .run(key(record.session), key(record.claimToken));
+        }
+        this.remove('evidence', [row]);
+        return true;
+    }
+    insert(kind, row) { insertLedgerRecord(this.db, kind, row); this.changed.add(kind); }
+    replace(kind, seq, row) {
+        const derived = ledgerRecordColumns(kind, row);
+        const result = this.db.prepare(`UPDATE ${tables[kind]} SET ${columns[kind].map((column) => `${column}=?`).join(',')},row_json=? WHERE seq=?`).run(...columns[kind].map((column) => derived[column]), JSON.stringify(row), seq);
+        if (result.changes)
+            this.changed.add(kind);
+    }
+    remove(kind, rows) {
+        const statement = this.db.prepare(`DELETE FROM ${tables[kind]} WHERE seq=?`);
+        for (const row of rows)
+            if (statement.run(row.seq).changes)
+                this.changed.add(kind);
+    }
+    /** Only invoke at the point where the former implementation published a mutation. */
+    publish(kind, now) {
+        const durable = kind === 'evidence' ? ` AND NOT ${retainedEvidence}` : '';
+        if (this.db.prepare(`DELETE FROM ${tables[kind]} WHERE effective_at<?${durable}`).run(now - LEDGER_RETENTION).changes)
+            this.changed.add(kind);
+    }
+    commitRevisions() {
+        for (const kind of this.changed)
+            this.db.exec(`UPDATE host_meta SET ${kind}_revision=${kind}_revision+1 WHERE id=1`);
+    }
+}
+export async function withLedger(root, write, select, absent, signal) {
+    const db = await openLedger(root, write, signal);
+    if (!db)
+        return absent;
+    try {
+        return await inSqliteTransaction(db, write, () => validateLedgerHeader(db), () => {
+            const rows = new LedgerTransaction(db), result = select(rows);
+            rows.commitRevisions();
+            return result;
+        }, signal);
+    }
+    finally {
+        db.close();
+    }
+}
+export async function readLedgerRevisions(root, signal) {
+    const db = await openLedger(root, false, signal);
+    if (!db)
+        return undefined;
+    try {
+        return await inSqliteTransaction(db, false, () => validateLedgerHeader(db), () => ledgerRevisions(db), signal);
+    }
+    finally {
+        db.close();
+    }
+}

package/dist/host-ledger.d.ts

@@ -91,6 +91,7 @@ export interface EvidenceRelease {
     readonly diagnostic?: unknown;
     readonly now?: number;
 }
+/** includeExpired is maintenance-only: bypass age retention, never future filtering. */
 export interface EvidenceLookup {
     readonly location?: string;
     readonly participant?: string;
@@ -99,10 +100,17 @@ export interface EvidenceLookup {
     readonly kind?: EvidenceRecord['kind'];
     readonly now?: number;
     readonly includeReleased?: boolean;
+    readonly includeExpired?: boolean;
 }
-export interface EvidenceGc {
-    readonly before: number;
-    readonly pendingWakeActivities?: readonly string[];
+export interface NativeTokenLookup {
+    readonly harness: 'claude';
+    readonly session: string;
+    readonly tokens: readonly string[];
+}
+/** One snapshot of live correlations and recognition-only retired tokens. Neither tokens nor lookup confer authority. */
+export interface NativeTokenResult {
+    readonly deliveries: readonly EvidenceRecord[];
+    readonly retired: readonly string[];
 }
 export interface WakeAttention {
     readonly squarePath: string;
@@ -160,6 +168,8 @@ export interface HostLedgerPort {
         readonly claimToken: string;
     }): Promise<void>;
     listEvidence(input: EvidenceLookup): Promise<readonly EvidenceRecord[]>;
+    retireEvidenceIfUnchanged(expected: EvidenceRecord): Promise<boolean>;
+    lookupNativeTokens(input: NativeTokenLookup): Promise<NativeTokenResult>;
     listWakeAttempts(input?: WakeAttemptLookup): Promise<readonly EvidenceRecord[]>;
     prepareNativeWake(input: EvidenceRecord & {
         readonly claimToken: string;
@@ -170,5 +180,4 @@ export interface HostLedgerPort {
         readonly claimToken: string;
     }): Promise<boolean>;
     claimWakeAttempt(input: WakeAttemptClaimInput): Promise<WakeAttemptClaim>;
-    gcEvidence(input: EvidenceGc): Promise<void>;
 }