@astrosheep/square 0.3.71 → 0.3.73

package/dist/host-ledger-file-adapter.js

@@ -1,16 +1,16 @@
 import { promises as fs } from 'node:fs';
 import path from 'node:path';
 import { randomUUID } from 'node:crypto';
-import { setTimeout as sleep } from 'node:timers/promises';
+import { isDeepStrictEqual } from 'node:util';
 import { withFileLock as acquireFileLock } from './file-lock.js';
 import { nameKey } from './model.js';
 import { formatActivityId } from './square-core.js';
 import { hostLedgerRoot } from './host-ledger-root.js';
-import { observeFileMetadata } from './file-changes.js';
+import { observeFileMetadata, observeFileVersion } from './file-changes.js';
 import { canonicalPath, canonicalPathSync } from './canonical-path.js';
+import { LEDGER_FILENAME, LEDGER_RETENTION, withLedger, readLedgerRevisions } from './host-ledger-sqlite.js';
 const LOCK = { retryMs: 10 };
-const RETENTION = 7 * 86400000;
-// Prepare before locking: lock databases and their journals are local runtime data too.
+// The claim fence deliberately spans asynchronous artifact/native work, never a ledger transaction.
 async function withFileLock(file, options, fn) {
     if (options.signal?.aborted)
         throw options.signal.reason ?? new Error('File lock acquisition aborted');
@@ -23,75 +23,100 @@ async function withFileLock(file, options, fn) {
         if (error.code !== 'EEXIST')
             throw error;
     }
-    return acquireFileLock(file, options, fn);
-}
-async function read(file, now, includeFuture = false) { try {
-    return (await fs.readFile(file, 'utf8')).split('\n').flatMap(line => { try {
-        const parsed = JSON.parse(line);
-        const row = decodeWakeRecord(parsed);
-        const at = row.at ?? row.updatedAt;
-        return row.v === 1 && typeof at === 'number' && (durableWake(row) || at >= now - RETENTION) && (includeFuture || at <= now) ? [row] : [];
-    }
-    catch {
-        return [];
-    } });
-}
-catch (e) {
-    if (e.code === 'ENOENT')
-        return [];
-    throw e;
-} }
-/** Keep the old ledger intact while Windows readers briefly deny replacement.
- * The owning file lock stays held throughout; never unlink the destination. */
-async function write(file, rows, signal) {
-    await fs.mkdir(path.dirname(file), { recursive: true });
-    const tmp = `${file}.${process.pid}.${randomUUID()}.tmp`;
     try {
-        if (signal?.aborted)
-            throw signal.reason ?? new Error('Ledger write aborted');
-        await fs.writeFile(tmp, rows.length ? rows.map((row) => JSON.stringify(row)).join('\n') + '\n' : '', { mode: 0o600, flag: 'wx' });
-        for (let attempt = 0;; attempt += 1) {
-            if (signal?.aborted)
-                throw signal.reason ?? new Error('Ledger write aborted');
-            try {
-                await fs.rename(tmp, file);
-                return;
-            }
-            catch (error) {
-                const code = error.code;
-                if (attempt >= 5 || (code !== 'EPERM' && code !== 'EACCES' && code !== 'EBUSY'))
-                    throw error;
-                await sleep(10 * 2 ** attempt, undefined, { signal });
-            }
-        }
+        return await acquireFileLock(file, options, fn);
     }
-    finally {
-        await fs.rm(tmp, { force: true }).catch(() => undefined);
+    catch (error) {
+        if (options.signal?.aborted)
+            throw options.signal.reason ?? error;
+        throw error;
     }
 }
-function k(v) { return JSON.stringify([v.location, nameKey(v.participant), v.session, v.channel, v.activity, v.kind]); }
+function identity(v) {
+    return JSON.stringify([v.location, nameKey(v.participant), v.session, v.channel, v.activity, v.kind]);
+}
 function durableWake(record) {
     const row = record;
-    return row.kind === 'wake' && (row.outcome === 'accepted' || row.outcome === 'unknown' || row.outcome === 'dispatching');
+    return row.kind === 'wake' && (['accepted', 'unknown', 'dispatching'].includes(row.outcome ?? '') || row.nativeDelivery?.harness === 'claude');
 }
-function decodeWakeRecord(row) {
-    return row.kind === 'wake' && row.outcome === 'unknown' && row.unknownSource === undefined
-        ? { ...row, unknownSource: row.signature === 'worker_interrupted_during_dispatch' ? 'interrupted' : 'transport' } : row;
-}
-/** Keep identity and native receipt, never a completed attempt's lease. */
 function finishWake(current, outcome, details = {}) {
     const { expiresAt: _expiresAt, ownerPid: _ownerPid, unknownSource: _unknownSource, ...rest } = current;
-    return { ...rest, ...details, kind: 'wake', outcome,
-        ...(outcome === 'unknown' ? { unknownSource: details.unknownSource ?? 'transport' } : {}) };
+    return { ...rest, ...details, kind: 'wake', outcome, ...(outcome === 'unknown' ? { unknownSource: details.unknownSource ?? 'transport' } : {}) };
 }
-function processAlive(pid) { if (pid === undefined)
-    return undefined; try {
-    process.kill(pid, 0);
-    return true;
+function processAlive(pid) {
+    if (pid === undefined)
+        return undefined;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === 'ESRCH' ? false : true;
+    }
 }
-catch (error) {
-    return error.code === 'ESRCH' ? false : true;
-} }
+const revisionReaders = new Map();
+async function revisions(root, entry, signal) {
+    for (;;) {
+        const metadata = await entry.metadata.read(signal);
+        if (entry.cached?.metadata === metadata)
+            return entry.cached.revisions;
+        if (entry.pending) {
+            await entry.pending;
+            continue;
+        }
+        entry.pending = readLedgerRevisions(root, entry.controller.signal).then((value) => {
+            // Never associate a snapshot with metadata obtained after the read.
+            entry.cached = { metadata, revisions: value };
+        }).finally(() => { entry.pending = undefined; });
+        await entry.pending;
+    }
+}
+async function observeLedger(root) {
+    let shared = revisionReaders.get(root);
+    if (!shared) {
+        shared = observeFileMetadata(path.join(root, LEDGER_FILENAME)).then((metadata) => ({ metadata, refs: 0, controller: new AbortController() }));
+        revisionReaders.set(root, shared);
+        void shared.catch(() => { if (revisionReaders.get(root) === shared)
+            revisionReaders.delete(root); });
+    }
+    const entry = await shared;
+    // A previous last subscriber may have closed while this acquisition awaited metadata.
+    if (revisionReaders.get(root) !== shared)
+        return observeLedger(root);
+    entry.refs += 2;
+    const release = () => { if (--entry.refs === 0) {
+        entry.controller.abort(new Error('Host ledger monitor closed'));
+        entry.metadata.close();
+        revisionReaders.delete(root);
+    } };
+    async function category(kind) {
+        const observer = await observeFileVersion(path.join(root, LEDGER_FILENAME), `host-ledger-${kind}`, async (_file, signal) => {
+            const pair = await revisions(root, entry, signal);
+            return pair === undefined ? 'missing' : String(pair[kind]);
+        });
+        let closed = false;
+        return { get generation() { return observer.generation; }, hinted: observer.hinted, read: observer.read, changed: observer.changed,
+            close() { if (!closed) {
+                closed = true;
+                observer.close();
+                release();
+            } } };
+    }
+    let presence;
+    try {
+        presence = await category('presence');
+        return { presence, evidence: await category('evidence') };
+    }
+    catch (error) {
+        if (presence)
+            presence.close();
+        else
+            release();
+        release();
+        throw error;
+    }
+}
+/** Existing port surface; each operation owns a short-lived SQLite connection. */
 export class FileHostLedgerPort {
     root;
     clock;
@@ -99,38 +124,26 @@ export class FileHostLedgerPort {
         this.root = canonicalPathSync(o.rootPath ?? hostLedgerRoot());
         this.clock = o.now ?? Date.now;
     }
-    file(kind) { return path.join(this.root, `${kind}.ndjsonl`); }
-    /** Invalidation only: callers still use the ledger projections as their authority. */
-    async observeChanges() {
-        const presence = await observeFileMetadata(this.file('presence'));
-        try {
-            return { presence, evidence: await observeFileMetadata(this.file('evidence')) };
-        }
-        catch (error) {
-            presence.close();
-            throw error;
-        }
-    }
-    /** Time can expire bindings/evidence even when their files do not change. */
+    observeChanges() { return observeLedger(this.root); }
     async nextExpiry(session) {
         const now = this.clock();
-        const rows = [...await read(this.file('presence'), now, true),
-            ...await read(this.file('evidence'), now, true)].filter((row) => row.session === session);
-        let next = Infinity;
-        for (const row of rows) {
-            const at = 'updatedAt' in row ? row.updatedAt : 'at' in row ? row.at : undefined;
-            if (typeof at === 'number') {
-                if (at > now)
-                    next = Math.min(next, at);
-                if (at + RETENTION + 1 > now && !durableWake(row))
-                    next = Math.min(next, at + RETENTION + 1);
+        return withLedger(this.root, false, (tx) => {
+            const records = [...tx.presence({ session }, now, true), ...tx.evidence({ session, includeReleased: true }, now, true)];
+            let next = Infinity;
+            for (const { record } of records) {
+                const at = 'updatedAt' in record ? record.updatedAt : 'at' in record ? record.at : undefined;
+                if (typeof at === 'number') {
+                    if (at > now)
+                        next = Math.min(next, at);
+                    if (at + LEDGER_RETENTION + 1 > now && !durableWake(record))
+                        next = Math.min(next, at + LEDGER_RETENTION + 1);
+                }
+                if ('expiresAt' in record && typeof record.expiresAt === 'number' && record.expiresAt > now)
+                    next = Math.min(next, record.expiresAt);
             }
-            if ('expiresAt' in row && typeof row.expiresAt === 'number' && row.expiresAt > now)
-                next = Math.min(next, row.expiresAt);
-        }
-        return next;
+            return next;
+        }, Infinity);
     }
-    /** The ownership claim critical section: the same lock as claimPresence and finalize. */
     withClaimLock(fn, signal) {
         return withFileLock(path.join(this.root, 'presence-claim.lock'), { ...LOCK, signal }, fn);
     }
@@ -138,20 +151,15 @@ export class FileHostLedgerPort {
         const location = await canonicalPath(i.location);
         const record = { ...i, location, updatedAt: i.updatedAt ?? this.clock(), v: 1 };
         try {
-            return await this.withClaimLock(async () => {
-                const file = this.file('presence');
-                // The authoritative read, ownership check, and write share the presence file lock:
-                // a concurrent ensurePresence/removePresence between them must never be overwritten
-                // by a stale snapshot.
-                return withFileLock(file + '.lock', { ...LOCK, signal }, async () => {
-                    const rows = await read(file, this.clock(), true);
-                    const existing = rows.filter((row) => row.location === location && nameKey(row.participant) === nameKey(record.participant)).sort((a, b) => (b.updatedAt ?? 0) - (a.updatedAt ?? 0))[0];
-                    if (existing !== undefined)
-                        return existing.session === record.session ? { status: 'owned', record: existing } : { status: 'busy', record: existing };
-                    await write(file, [...rows, record], signal);
-                    return { status: 'acquired', record };
-                });
-            }, signal);
+            return await this.withClaimLock(() => withLedger(this.root, true, (tx) => {
+                const existing = tx.presence({ location, participant: record.participant }, this.clock(), true)
+                    .map(({ record }) => record).sort((a, b) => (b.updatedAt ?? 0) - (a.updatedAt ?? 0))[0];
+                if (existing !== undefined)
+                    return { status: existing.session === record.session ? 'owned' : 'busy', record: existing };
+                tx.publish('presence', this.clock());
+                tx.insert('presence', record);
+                return { status: 'acquired', record };
+            }, { status: 'degraded', record, error: new Error('Missing writable host ledger') }, signal), signal);
         }
         catch (error) {
             return { status: 'degraded', record, error };
@@ -160,116 +168,109 @@ export class FileHostLedgerPort {
     async ensurePresence(i) {
         const record = { ...i, location: await canonicalPath(i.location), updatedAt: i.updatedAt ?? this.clock(), v: 1 };
         try {
-            await withFileLock(this.file('presence') + '.lock', LOCK, async () => {
-                const rows = await read(this.file('presence'), this.clock(), true);
-                const current = rows.findLast((row) => k(row) === k(record));
-                const sameEpoch = current?.epoch === record.epoch;
-                const cancelledThrough = sameEpoch ? Math.max(current?.cancelledThrough ?? -1, record.cancelledThrough ?? -1) : record.cancelledThrough ?? -1;
-                await write(this.file('presence'), [...rows.filter((row) => k(row) !== k(record)), { ...record, ...(cancelledThrough < 0 ? {} : { cancelledThrough }) }]);
-            });
+            await withLedger(this.root, true, (tx) => {
+                const rows = tx.presence({ location: record.location, participant: record.participant, session: record.session, channel: record.channel }, this.clock(), true).filter((row) => identity(row.record) === identity(record));
+                const current = rows.at(-1)?.record;
+                const cancelledThrough = current?.epoch === record.epoch ? Math.max(current?.cancelledThrough ?? -1, record.cancelledThrough ?? -1) : record.cancelledThrough ?? -1;
+                tx.publish('presence', this.clock());
+                tx.remove('presence', rows);
+                tx.insert('presence', { ...record, ...(cancelledThrough < 0 ? {} : { cancelledThrough }) });
+            }, undefined);
             return { status: 'ensured', record };
         }
         catch (error) {
             return { status: 'degraded', record, error };
         }
     }
-    /** Local batch suppression is monotonic only for the captured host generation. */
     async suppressPresence(i, through) {
         const record = { ...i, location: await canonicalPath(i.location) };
-        const file = this.file('presence');
-        return withFileLock(file + '.lock', LOCK, async () => {
-            const rows = await read(file, this.clock(), true);
-            const current = rows.findLast((row) => k(row) === k(record) && row.epoch === record.epoch);
+        return withLedger(this.root, true, (tx) => {
+            const current = tx.presence({ location: record.location, participant: record.participant, session: record.session, channel: record.channel }, this.clock(), true).findLast((row) => identity(row.record) === identity(record) && row.record.epoch === record.epoch);
             if (!current)
                 return false;
-            await write(file, rows.map((row) => row === current ? { ...row, cancelledThrough: Math.max(row.cancelledThrough ?? -1, through) } : row));
+            tx.publish('presence', this.clock());
+            tx.replace('presence', current.seq, { ...current.record, cancelledThrough: Math.max(current.record.cancelledThrough ?? -1, through) });
             return true;
-        });
+        }, false);
     }
     async removePresence(i) {
         const record = { ...i, location: await canonicalPath(i.location) };
-        await withFileLock(this.file('presence') + '.lock', LOCK, async () => write(this.file('presence'), (await read(this.file('presence'), this.clock(), true)).filter((row) => k(row) !== k(record))));
+        await withLedger(this.root, true, (tx) => {
+            const rows = tx.presence({ location: record.location, participant: record.participant, session: record.session, channel: record.channel }, this.clock(), true).filter((row) => identity(row.record) === identity(record));
+            tx.publish('presence', this.clock());
+            tx.remove('presence', rows);
+        }, undefined);
     }
     async removePresenceIfUnchanged(i) {
         const record = { ...i, location: await canonicalPath(i.location) };
-        return withFileLock(this.file('presence') + '.lock', LOCK, async () => {
-            const file = this.file('presence');
-            const rows = await read(file, this.clock(), true);
-            const matches = (row) => k(row) === k(record)
-                && (row.epoch ?? undefined) === (record.epoch ?? undefined)
-                && (row.updatedAt ?? undefined) === (record.updatedAt ?? undefined);
-            const current = rows.findLast(matches);
-            if (current === undefined)
+        return withLedger(this.root, true, (tx) => {
+            const current = tx.presence({ location: record.location, participant: record.participant, session: record.session, channel: record.channel }, this.clock(), true).findLast(({ record: row }) => identity(row) === identity(record) && (row.epoch ?? undefined) === (record.epoch ?? undefined) && (row.updatedAt ?? undefined) === (record.updatedAt ?? undefined));
+            if (!current)
                 return false;
-            await write(file, rows.filter((row) => row !== current));
+            tx.publish('presence', this.clock());
+            tx.remove('presence', [current]);
             return true;
-        });
+        }, false);
     }
     async listPresence(i = {}) {
         const location = i.location === undefined ? undefined : await canonicalPath(i.location);
-        return (await read(this.file('presence'), i.now ?? this.clock())).filter((row) => (!location || row.location === location) && (!i.participant || nameKey(row.participant) === nameKey(i.participant)) && (!i.session || row.session === i.session)).map(({ scope: _scope, ...row }) => row);
+        return withLedger(this.root, false, (tx) => tx.presence({ ...i, location, participant: i.participant || undefined, session: i.session || undefined }, i.now ?? this.clock()).map(({ record }) => {
+            const { scope: _scope, ...row } = record;
+            return row;
+        }), []);
     }
-    /** One attempt row owns attention-wide exclusion and session-scoped history for a wake. */
     async claimWakeAttempt(i) {
-        const location = await canonicalPath(i.attention.squarePath);
-        const activity = formatActivityId(i.attention.actIndex);
-        const at = i.now ?? this.clock();
-        const file = this.file('evidence');
+        const location = await canonicalPath(i.attention.squarePath), activity = formatActivityId(i.attention.actIndex), at = i.now ?? this.clock();
         try {
-            return await withFileLock(file + '.lock', LOCK, async () => {
-                const all = await read(file, at, true);
-                const attention = all.filter((row) => row.kind === 'wake' && row.location === location && nameKey(row.participant) === nameKey(i.attention.recipient) && row.activity === activity);
-                const terminal = attention.findLast((row) => row.outcome === 'accepted') ?? attention.findLast((row) => row.outcome === 'unknown');
+            return await withLedger(this.root, true, (tx) => {
+                const attention = tx.evidence({ location, participant: i.attention.recipient, activity, kind: 'wake', includeReleased: true }, at, true);
+                const terminal = attention.findLast(({ record }) => record.outcome === 'accepted') ?? attention.findLast(({ record }) => record.outcome === 'unknown');
                 if (terminal)
-                    return { status: 'terminal', record: terminal };
-                const interrupted = attention.filter((row) => row.outcome === 'dispatching');
-                const busy = interrupted.find((row) => (row.expiresAt ?? 0) > at && processAlive(row.ownerPid) !== false);
+                    return { status: 'terminal', record: terminal.record };
+                const interrupted = attention.filter(({ record }) => record.outcome === 'dispatching');
+                const busy = interrupted.find(({ record }) => (record.expiresAt ?? 0) > at && processAlive(record.ownerPid) !== false);
                 if (busy)
-                    return { status: 'busy', record: busy };
-                const nextNumber = (session) => attention.filter((row) => row.session === session).reduce((highest, row) => Math.max(highest, row.attemptN ?? 0), 0) + 1;
-                // An abandoned attempt may already have been sent, so it blocks every route.
+                    return { status: 'busy', record: busy.record };
+                const nextNumber = (session) => attention.filter(({ record }) => record.session === session).reduce((highest, { record }) => Math.max(highest, record.attemptN ?? 0), 0) + 1;
+                tx.publish('evidence', at);
                 if (interrupted.length) {
-                    const recovered = interrupted.map((row) => ({ ...finishWake(row, 'unknown', {
-                            unknownSource: 'interrupted', signature: 'worker_interrupted_during_dispatch',
-                            message: 'The notification worker ended after dispatch began; transport acceptance is unknown.',
-                        }), routeKind: row.routeKind ?? i.routeKind, attemptN: row.attemptN ?? nextNumber(row.session), v: 1 }));
-                    const replacements = new Map(interrupted.map((row, index) => [row, recovered[index]]));
-                    await write(file, all.map((row) => replacements.get(row) ?? row));
+                    const recovered = interrupted.map(({ record }) => ({ ...finishWake(record, 'unknown', {
+                            unknownSource: 'interrupted', signature: 'worker_interrupted_during_dispatch', message: 'The notification worker ended after dispatch began; transport acceptance is unknown.',
+                        }), routeKind: record.routeKind ?? i.routeKind, attemptN: record.attemptN ?? nextNumber(record.session), v: 1 }));
+                    interrupted.forEach((row, index) => tx.replace('evidence', row.seq, recovered[index]));
                     return { status: 'terminal', record: recovered[0] };
                 }
                 const attemptN = nextNumber(i.session), claimToken = `${process.pid}-${at}-${randomUUID()}`;
-                await write(file, [...all, { v: 1, at, location, participant: i.attention.recipient, session: i.session, activity,
-                        kind: 'wake', outcome: 'dispatching', routeKind: i.routeKind, attemptN, claimToken, ownerPid: process.pid, expiresAt: at + i.leaseMs }]);
+                tx.insert('evidence', { v: 1, at, location, participant: i.attention.recipient, session: i.session, activity, kind: 'wake', outcome: 'dispatching', routeKind: i.routeKind, attemptN, claimToken, ownerPid: process.pid, expiresAt: at + i.leaseMs });
                 return { status: 'acquired', claimToken, attemptN };
-            });
+            }, { status: 'degraded', error: new Error('Missing writable host ledger') });
         }
         catch (error) {
             return { status: 'degraded', error };
         }
     }
-    /** One locked, token-fenced replacement; each operation owns its state condition. */
     async updateWake(input, update, at = this.clock()) {
         if (!input.claimToken)
             return false;
-        const location = await canonicalPath(input.location), file = this.file('evidence');
-        return withFileLock(file + '.lock', LOCK, async () => {
-            const all = await read(file, at, true);
-            const current = all.findLast((row) => row.kind === 'wake' && row.location === location && nameKey(row.participant) === nameKey(input.participant) && row.activity === input.activity && row.session === input.session && row.claimToken === input.claimToken);
-            const next = current && update(current);
-            if (!next)
+        const location = await canonicalPath(input.location);
+        return withLedger(this.root, true, (tx) => {
+            const current = tx.evidence({ location, participant: input.participant, activity: input.activity, session: input.session, kind: 'wake', claimToken: input.claimToken, includeReleased: true }, at, true).at(-1);
+            const next = current && update(current.record);
+            if (!next || !current)
                 return false;
-            if (next !== current)
-                await write(file, all.map((row) => row === current ? { ...next, v: 1 } : row));
+            if (next !== current.record) {
+                tx.publish('evidence', at);
+                tx.replace('evidence', current.seq, { ...next, v: 1 });
+            }
             return true;
-        });
+        }, false);
     }
     async listWakeAttempts(i = {}) {
         const attention = i.attention;
         return this.listEvidence({ kind: 'wake', ...(attention === undefined ? {} : { location: await canonicalPath(attention.squarePath), participant: attention.recipient, activity: formatActivityId(attention.actIndex) }), session: i.session, now: i.now });
     }
     async prepareNativeWake(i) {
-        return this.updateWake(i, (current) => current.outcome === 'dispatching'
-            ? { ...current, nativeDelivery: i.nativeDelivery, routeKind: i.routeKind, attemptN: i.attemptN } : undefined);
+        return this.updateWake(i, (current) => current.outcome === 'dispatching' ? { ...current, nativeDelivery: i.nativeDelivery, routeKind: i.routeKind, attemptN: i.attemptN } : undefined);
     }
     async confirmWakeAdmission(i) {
         return this.updateWake(i, (current) => {
@@ -278,55 +279,94 @@ export class FileHostLedgerPort {
             return current.outcome === 'accepted' ? current : finishWake(current, 'accepted', { signature: 'native_queue_confirmed', message: undefined, diagnostic: undefined });
         });
     }
-    async claimEvidence(i) { if (i.kind === 'wake')
-        return { status: 'degraded', error: new Error('wake attempts are claimed with claimWakeAttempt') }; const f = this.file('evidence'), at = i.now ?? this.clock(), { leaseMs, ...claim } = i, r = { ...claim, location: await canonicalPath(i.location), outcome: 'dispatching', at, expiresAt: at + leaseMs, v: 1 }; try {
-        return await withFileLock(f + '.lock', LOCK, async () => { const all = await read(f, at, true), matching = all.filter(x => x.kind === r.kind && x.location === r.location && nameKey(x.participant) === nameKey(r.participant) && x.activity === r.activity && x.session === r.session), old = matching.findLast(x => x.outcome === 'dispatching'); if (old !== undefined && typeof old.expiresAt === 'number' && old.expiresAt > at)
-            return { status: 'busy', record: old }; if (r.kind === 'presentation' && matching.some(x => x.outcome === 'presented'))
-            return { status: 'delivered', record: matching.findLast(x => x.outcome === 'presented') }; const claimToken = `${process.pid}-${at}-${Math.random().toString(36).slice(2)}`, row = { ...r, claimToken }; await write(f, [...all.filter(x => !(x.kind === r.kind && x.location === r.location && nameKey(x.participant) === nameKey(r.participant) && x.activity === r.activity && x.session === r.session && (x.outcome === 'dispatching' || x.outcome === 'released'))), row]); return { status: 'acquired', claimToken }; });
+    async claimEvidence(i) {
+        if (i.kind === 'wake')
+            return { status: 'degraded', error: new Error('wake attempts are claimed with claimWakeAttempt') };
+        const at = i.now ?? this.clock(), { leaseMs, ...claim } = i;
+        const record = { ...claim, location: await canonicalPath(i.location), outcome: 'dispatching', at, expiresAt: at + leaseMs, v: 1 };
+        try {
+            return await withLedger(this.root, true, (tx) => {
+                const matching = tx.evidence({ ...record, includeReleased: true }, at, true);
+                const old = matching.findLast(({ record }) => record.outcome === 'dispatching');
+                if (old && typeof old.record.expiresAt === 'number' && old.record.expiresAt > at)
+                    return { status: 'busy', record: old.record };
+                const presented = matching.findLast(({ record }) => record.outcome === 'presented');
+                if (record.kind === 'presentation' && presented)
+                    return { status: 'delivered', record: presented.record };
+                const claimToken = `${process.pid}-${at}-${Math.random().toString(36).slice(2)}`;
+                tx.publish('evidence', at);
+                tx.remove('evidence', matching.filter(({ record }) => record.outcome === 'dispatching' || record.outcome === 'released'));
+                tx.insert('evidence', { ...record, claimToken });
+                return { status: 'acquired', claimToken };
+            }, { status: 'degraded', error: new Error('Missing writable host ledger') });
+        }
+        catch (error) {
+            return { status: 'degraded', error };
+        }
     }
-    catch (error) {
-        return { status: 'degraded', error };
-    } }
     async releaseEvidence(i) {
         if (i.kind === 'wake') {
             const { signature, message, diagnostic, routeKind, attemptN } = i;
             const details = Object.fromEntries(Object.entries({ signature, message, diagnostic, routeKind, attemptN }).filter(([, value]) => value !== undefined));
-            await this.updateWake(i, (current) => current.outcome === 'dispatching'
-                ? finishWake(current, 'released', { ...details, at: i.now ?? this.clock() }) : undefined, i.now);
+            await this.updateWake(i, (current) => current.outcome === 'dispatching' ? finishWake(current, 'released', { ...details, at: i.now ?? this.clock() }) : undefined, i.now);
             return;
         }
-        const f = this.file('evidence'), location = await canonicalPath(i.location), at = i.now ?? this.clock();
-        await withFileLock(f + '.lock', LOCK, async () => { const all = await read(f, at, true), same = (x) => x.kind === i.kind && x.location === location && nameKey(x.participant) === nameKey(i.participant) && x.activity === i.activity && x.session === i.session, current = all.findLast(x => same(x) && x.outcome === 'dispatching'); if (current === undefined || current.claimToken !== i.claimToken)
-            return; const tombstone = { ...current, outcome: 'released', at, ...(i.routeKind === undefined ? {} : { routeKind: i.routeKind }), ...(i.attemptN === undefined ? {} : { attemptN: i.attemptN }), ...(i.signature === undefined ? {} : { signature: i.signature }), ...(i.message === undefined ? {} : { message: i.message }), ...(i.diagnostic === undefined ? {} : { diagnostic: i.diagnostic }), expiresAt: undefined }; delete tombstone.expiresAt; delete tombstone.ownerPid; await write(f, [...all.filter(x => x !== current), tombstone]); });
+        const location = await canonicalPath(i.location), at = i.now ?? this.clock();
+        await withLedger(this.root, true, (tx) => {
+            const current = tx.evidence({ ...i, location, includeReleased: true, claimToken: undefined }, at, true).findLast(({ record }) => record.outcome === 'dispatching');
+            if (!current || current.record.claimToken !== i.claimToken)
+                return;
+            const { expiresAt: _expiry, ownerPid: _owner, ...rest } = current.record;
+            const details = Object.fromEntries(['routeKind', 'attemptN', 'signature', 'message', 'diagnostic'].filter((field) => i[field] !== undefined).map((field) => [field, i[field]]));
+            tx.publish('evidence', at);
+            tx.remove('evidence', [current]);
+            tx.insert('evidence', { ...rest, outcome: 'released', at, ...details });
+        }, undefined);
     }
-    /** Token-fenced terminal write. A token may only finish the attempt it claimed. */
     async appendEvidence(i) {
-        const f = this.file('evidence'), r = { ...i, location: await canonicalPath(i.location), at: i.at ?? this.clock(), v: 1 };
-        const token = i.claimToken;
-        if (typeof token !== 'string' || token.length === 0)
+        const record = { ...i, location: await canonicalPath(i.location), at: i.at ?? this.clock(), v: 1 };
+        if (typeof i.claimToken !== 'string' || !i.claimToken.length)
             return;
         if (i.kind === 'wake') {
-            if (r.outcome !== 'accepted' && r.outcome !== 'failed' && r.outcome !== 'unknown')
+            if (!['accepted', 'failed', 'unknown'].includes(record.outcome))
                 return;
-            const outcome = r.outcome;
-            await this.updateWake(r, (current) => {
+            const outcome = record.outcome;
+            await this.updateWake(record, (current) => {
                 if (current.outcome !== 'dispatching' && !(current.outcome === 'unknown' && current.unknownSource === 'interrupted' && outcome === 'accepted'))
                     return undefined;
-                return finishWake(current, outcome, { at: r.at, routeKind: r.routeKind, attemptN: r.attemptN, signature: r.signature, message: r.message, diagnostic: r.diagnostic });
-            }, r.at);
+                return finishWake(current, outcome, { at: record.at, routeKind: record.routeKind, attemptN: record.attemptN, signature: record.signature, message: record.message, diagnostic: record.diagnostic });
+            }, record.at);
             return;
         }
-        await withFileLock(f + '.lock', LOCK, async () => {
-            const all = await read(f, r.at, true);
-            const same = (x) => x.kind === r.kind && x.location === r.location && nameKey(x.participant) === nameKey(r.participant) && x.activity === r.activity && x.session === r.session;
-            const dispatching = all.findLast((x) => same(x) && x.outcome === 'dispatching');
-            const source = dispatching?.claimToken === token ? dispatching : undefined;
-            if (source === undefined)
+        await withLedger(this.root, true, (tx) => {
+            const matching = tx.evidence({ ...record, claimToken: undefined, includeReleased: true }, record.at, true);
+            const source = matching.findLast(({ record }) => record.outcome === 'dispatching');
+            if (!source || source.record.claimToken !== record.claimToken)
                 return;
-            await write(f, [...all.filter((x) => x !== source && !(same(x) && x.attemptN === r.attemptN && x.outcome !== 'dispatching' && x.outcome !== 'released')), { ...r, ...(source.nativeDelivery === undefined ? {} : { nativeDelivery: source.nativeDelivery }) }]);
-        });
+            tx.publish('evidence', record.at);
+            tx.remove('evidence', matching.filter((row) => row === source || row.record.attemptN === record.attemptN && row.record.outcome !== 'dispatching' && row.record.outcome !== 'released'));
+            tx.insert('evidence', { ...record, ...(source.record.nativeDelivery === undefined ? {} : { nativeDelivery: source.record.nativeDelivery }) });
+        }, undefined);
+    }
+    async listEvidence(i = {}) {
+        const location = i.location === undefined ? undefined : await canonicalPath(i.location);
+        return withLedger(this.root, false, (tx) => tx.evidence({ ...i, location, participant: i.participant || undefined, session: i.session || undefined, activity: i.activity || undefined, kind: i.kind || undefined }, i.now ?? this.clock()).map(({ record }) => record), []);
+    }
+    async retireEvidenceIfUnchanged(expected) {
+        if (expected.outcome === 'dispatching')
+            return false;
+        // Compare the persisted coordinate verbatim; maintenance canonicalizes only its artifact proof.
+        return withLedger(this.root, true, (tx) => {
+            const current = tx.evidence({ location: expected.location, participant: expected.participant, session: expected.session, activity: expected.activity, kind: expected.kind,
+                claimToken: expected.claimToken, includeExpired: true, includeReleased: true }, this.clock(), true)
+                .find(({ record }) => isDeepStrictEqual(record, expected));
+            return current !== undefined && tx.retireEvidence(current);
+        }, false);
+    }
+    lookupNativeTokens(input) {
+        if (!input.tokens.length)
+            return Promise.resolve({ deliveries: [], retired: [] });
+        return withLedger(this.root, false, tx => tx.nativeTokens(input), { deliveries: [], retired: [] });
     }
-    async listEvidence(i = {}) { const loc = i.location === undefined ? undefined : await canonicalPath(i.location); return (await read(this.file('evidence'), i.now ?? this.clock())).filter(r => (i.includeReleased === true || r.outcome !== 'released') && (!loc || r.location === loc) && (!i.participant || nameKey(r.participant) === nameKey(i.participant)) && (!i.session || r.session === i.session) && (!i.activity || r.activity === i.activity) && (!i.kind || r.kind === i.kind)); }
-    async gcEvidence(i) { const f = this.file('evidence'), pending = new Set(i.pendingWakeActivities ?? []); await withFileLock(f + '.lock', LOCK, async () => write(f, (await read(f, this.clock(), true)).filter(r => r.at >= i.before || durableWake(r) && pending.has(r.activity)))); }
 }
 export function createHostLedgerPort(o = {}) { return new FileHostLedgerPort(o); }

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

@@ -0,0 +1,26 @@
+type Kind = 'presence' | 'evidence';
+export interface LedgerSourceReport {
+    records: number;
+    ignored: number;
+    rejected: number;
+    sha256: string | null;
+}
+export interface HostLedgerReport {
+    status: 'empty' | 'legacy' | 'sqlite' | 'migrated' | 'upgraded';
+    presence: number;
+    evidence: number;
+    presenceRevision?: number;
+    evidenceRevision?: number;
+    sources?: Record<Kind, LedgerSourceReport>;
+    ready?: boolean;
+}
+export interface HostLedgerMaintenanceOptions {
+    rootPath?: string;
+    env?: NodeJS.ProcessEnv;
+    signal?: AbortSignal;
+}
+/** Read-only readiness/integrity check. Never creates a root, lock, or database. */
+export declare function verifyHostLedger(options?: HostLedgerMaintenanceOptions): Promise<HostLedgerReport>;
+/** Offline only: locks fence compatible writers, but do not prove hosts have stopped. */
+export declare function migrateHostLedger(options?: HostLedgerMaintenanceOptions): Promise<HostLedgerReport>;
+export {};