@astrosheep/square 0.3.106 → 0.4.1

package/dist/delivery-ledger-sqlite.js

@@ -0,0 +1,496 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { DatabaseSync } from 'node:sqlite';
+import { inSqliteTransaction } from './sqlite-transaction.js';
+import { validateSchema } from './sqlite-framing.js';
+const FORMAT = 3;
+const APPLICATION_ID = 0x444c4752;
+const RETENTION_MS = 30 * 24 * 60 * 60 * 1000;
+const SCHEMA = `CREATE TABLE meta (format INTEGER NOT NULL, next_seq INTEGER NOT NULL);
+CREATE TABLE sessions (owner TEXT PRIMARY KEY, generation TEXT NOT NULL, state TEXT NOT NULL, routes_json TEXT NOT NULL, at REAL NOT NULL);
+CREATE TABLE cards (seq INTEGER PRIMARY KEY, owner TEXT NOT NULL, key TEXT NOT NULL, text TEXT NOT NULL, details TEXT, posted_at REAL NOT NULL, UNIQUE(owner,key));
+CREATE INDEX cards_owner ON cards(owner,seq);
+CREATE TABLE suppressions (id TEXT PRIMARY KEY, owner TEXT NOT NULL, key TEXT NOT NULL, scope TEXT NOT NULL CHECK(scope IN ('exact','prefix')), created_at REAL NOT NULL, expires_at REAL);
+CREATE INDEX suppressions_owner ON suppressions(owner);
+CREATE UNIQUE INDEX suppressions_permanent_exact ON suppressions(owner,key) WHERE scope='exact' AND expires_at IS NULL;
+CREATE TABLE attempts (token TEXT PRIMARY KEY, seq INTEGER NOT NULL, generation TEXT NOT NULL, track TEXT NOT NULL, route_kind TEXT, outcome TEXT NOT NULL, correlation_json TEXT NOT NULL, started_at REAL NOT NULL, expires_at REAL NOT NULL, settled_at REAL);
+CREATE INDEX attempts_seq ON attempts(seq);
+CREATE TABLE receipts (owner TEXT NOT NULL, key TEXT NOT NULL, at REAL NOT NULL, PRIMARY KEY(owner,key));
+CREATE INDEX receipts_time ON receipts(at);
+CREATE TABLE cancellations (owner TEXT PRIMARY KEY, generation TEXT NOT NULL, through_seq INTEGER NOT NULL);`;
+function validate(db, location) {
+    const header = db.prepare('SELECT application_id, user_version FROM pragma_application_id, pragma_user_version').get();
+    if (header?.application_id !== APPLICATION_ID || header.user_version !== FORMAT)
+        throw new Error('Unsupported delivery ledger format');
+    validateSchema(db, SCHEMA, location);
+    const meta = db.prepare('SELECT * FROM meta').all();
+    if (meta.length !== 1 || meta[0].format !== FORMAT || !Number.isSafeInteger(meta[0].next_seq) || Number(meta[0].next_seq) < 1)
+        throw new Error('Invalid delivery ledger header');
+}
+function session(row) {
+    return row ? { owner: row.owner, generation: row.generation, state: row.state,
+        routes: JSON.parse(row.routes_json), at: row.at } : undefined;
+}
+function card(row) {
+    return { seq: row.seq, owner: row.owner, key: row.key, text: row.text,
+        ...(row.details === null ? {} : { details: JSON.parse(row.details) }), postedAt: row.posted_at };
+}
+function attempt(row) {
+    return { token: row.token, seq: row.seq, generation: row.generation,
+        track: row.track, routeKind: row.route_kind, outcome: row.outcome,
+        correlation: JSON.parse(row.correlation_json), startedAt: row.started_at, expiresAt: row.expires_at,
+        ...(row.settled_at === null ? {} : { settledAt: row.settled_at }) };
+}
+function holds(row) { return !['failed', 'released'].includes(row.outcome); }
+/** All ledger file access and SQL are confined here. Transactions never span external effects. */
+export class LedgerStore {
+    location;
+    db;
+    clock;
+    pending = Promise.resolve();
+    closed = false;
+    constructor(location, db, clock) {
+        this.location = location;
+        this.db = db;
+        this.clock = clock;
+    }
+    static async open(location, clock) {
+        try {
+            await fs.access(location);
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+            await fs.mkdir(path.dirname(location), { recursive: true, mode: 0o700 });
+            const temporary = location + '.' + randomUUID() + '.tmp';
+            let initial;
+            try {
+                await (await fs.open(temporary, 'wx', 0o600)).close();
+                initial = new DatabaseSync(temporary);
+                await inSqliteTransaction(initial, true, () => undefined, () => {
+                    initial.exec(SCHEMA);
+                    initial.prepare('INSERT INTO meta VALUES(?,1)').run(FORMAT);
+                    initial.exec(`PRAGMA application_id=${APPLICATION_ID}; PRAGMA user_version=${FORMAT}`);
+                });
+                initial.close();
+                initial = undefined;
+                try {
+                    await fs.link(temporary, location);
+                }
+                catch (error) {
+                    if (error.code !== 'EEXIST')
+                        throw error;
+                }
+            }
+            finally {
+                initial?.close();
+                await fs.unlink(temporary).catch(() => undefined);
+            }
+        }
+        // Existing formats are inspected on a read-only connection before any writable open.
+        const probe = new DatabaseSync(location, { readOnly: true });
+        try {
+            validate(probe, location);
+        }
+        finally {
+            probe.close();
+        }
+        const db = new DatabaseSync(location);
+        try {
+            validate(db, location);
+            return new LedgerStore(location, db, clock);
+        }
+        catch (error) {
+            db.close();
+            throw error;
+        }
+    }
+    close() {
+        this.closed = true;
+        return this.pending.then(() => this.db.close());
+    }
+    transaction(write, change, signal) {
+        if (this.closed)
+            return Promise.reject(new Error('Delivery ledger is closed'));
+        const result = this.pending.then(() => inSqliteTransaction(this.db, write, () => validate(this.db, this.location), () => {
+            const now = this.clock();
+            if (!Number.isFinite(now))
+                throw new TypeError('Expected finite ledger time');
+            const changes = Number(this.db.prepare('SELECT total_changes() AS n').get().n);
+            const result = change(now);
+            if (write && Number(this.db.prepare('SELECT total_changes() AS n').get().n) > changes) {
+                this.normalize(now);
+                this.gc(now);
+            }
+            return result;
+        }, signal));
+        this.pending = result.catch(() => undefined);
+        return result;
+    }
+    getSession(owner) {
+        return session(this.db.prepare('SELECT * FROM sessions WHERE owner=?').get(owner));
+    }
+    attached(owner, generation) {
+        const s = this.getSession(owner);
+        return s?.state === 'attached' && s.generation === generation ? s : undefined;
+    }
+    listAttempts(seq) {
+        return this.db.prepare('SELECT * FROM attempts WHERE seq=? ORDER BY started_at,token').all(seq).map(attempt);
+    }
+    awaitingEffect(seq) {
+        const attempts = this.listAttempts(seq);
+        if (attempts.some(a => ['dispatching', 'unknown'].includes(a.outcome)))
+            return true;
+        return attempts.some(a => a.track === 'handoff' && a.outcome === 'accepted')
+            && !attempts.some(a => a.track === 'presentation' && a.outcome === 'presented');
+    }
+    getAttempt(token) {
+        const row = this.db.prepare('SELECT * FROM attempts WHERE token=?').get(token);
+        return row ? attempt(row) : undefined;
+    }
+    normalize(now) {
+        this.db.prepare(`UPDATE attempts SET outcome='unknown', settled_at=? WHERE outcome='dispatching' AND
+      (expires_at<=? OR NOT EXISTS(SELECT 1 FROM cards c JOIN sessions s ON s.owner=c.owner
+        WHERE c.seq=attempts.seq AND s.generation=attempts.generation AND s.state='attached'))`).run(now, now);
+        this.db.prepare(`UPDATE cards SET text='',details=NULL WHERE (text<>'' OR details IS NOT NULL)
+      AND EXISTS(SELECT 1 FROM attempts a WHERE a.seq=cards.seq AND a.outcome IN ('accepted','unknown','presented'))`).run();
+        const terminal = this.db.prepare(`SELECT seq FROM cards WHERE
+      EXISTS(SELECT 1 FROM attempts a WHERE a.seq=cards.seq AND a.track='presentation' AND a.outcome='presented')
+      AND NOT EXISTS(SELECT 1 FROM attempts a WHERE a.seq=cards.seq AND a.outcome='dispatching')`).all();
+        for (const row of terminal)
+            this.deleteCard(row.seq, now);
+    }
+    deleteCard(seq, tombstoneAt) {
+        if (tombstoneAt !== undefined)
+            this.db.prepare(`INSERT INTO suppressions
+      SELECT ?,owner,key,'exact',?,NULL FROM cards WHERE seq=?
+      ON CONFLICT(owner,key) WHERE scope='exact' AND expires_at IS NULL DO UPDATE SET created_at=excluded.created_at`)
+                .run(randomUUID(), tombstoneAt, seq);
+        this.db.prepare('DELETE FROM attempts WHERE seq=?').run(seq);
+        this.db.prepare('DELETE FROM cards WHERE seq=?').run(seq);
+    }
+    gc(now) {
+        const cutoff = now - RETENTION_MS;
+        this.db.prepare('DELETE FROM suppressions WHERE expires_at IS NOT NULL AND expires_at<=?').run(now);
+        const suppressed = this.db.prepare(`SELECT seq FROM cards WHERE EXISTS(SELECT 1 FROM suppressions s WHERE s.owner=cards.owner AND s.scope='exact' AND s.key=cards.key AND s.expires_at IS NULL)
+      AND NOT EXISTS(SELECT 1 FROM attempts a WHERE a.seq=cards.seq AND a.outcome IN ('dispatching','unknown'))`).all();
+        for (const row of suppressed) {
+            if (this.awaitingEffect(row.seq))
+                continue;
+            this.deleteCard(row.seq);
+        }
+        this.db.prepare(`DELETE FROM suppressions WHERE id IN (SELECT id FROM suppressions
+      WHERE expires_at IS NULL AND created_at<? ORDER BY created_at LIMIT 100)`).run(cutoff);
+        const expiredSessions = this.db.prepare(`SELECT c.seq FROM cards c JOIN sessions s ON s.owner=c.owner
+      WHERE s.state='deleted' OR (s.state='detached' AND s.at<?) ORDER BY c.seq`).all(cutoff);
+        for (const row of expiredSessions)
+            this.deleteCard(row.seq);
+        this.db.prepare("DELETE FROM suppressions WHERE owner IN (SELECT owner FROM sessions WHERE state='deleted')").run();
+        const old = this.db.prepare(`SELECT c.seq FROM cards c WHERE
+      EXISTS(SELECT 1 FROM attempts a WHERE a.seq=c.seq AND a.outcome IN ('accepted','unknown'))
+      AND (SELECT MAX(a.settled_at) FROM attempts a WHERE a.seq=c.seq)<?
+      AND NOT EXISTS(SELECT 1 FROM attempts a WHERE a.seq=c.seq AND a.outcome='dispatching') ORDER BY c.seq LIMIT 100`).all(cutoff);
+        for (const row of old)
+            this.deleteCard(row.seq, now);
+        this.db.prepare('DELETE FROM receipts WHERE rowid IN (SELECT rowid FROM receipts WHERE at<? ORDER BY at LIMIT 100)').run(cutoff);
+    }
+    session(owner) { return this.transaction(false, () => this.getSession(owner)); }
+    sessions() {
+        return this.transaction(false, () => this.db.prepare('SELECT * FROM sessions ORDER BY owner').all().map(row => session(row)));
+    }
+    pendingCards(owner, generation) {
+        return this.transaction(false, now => this.attached(owner, generation)
+            ? this.db.prepare('SELECT * FROM cards WHERE owner=? ORDER BY seq').all(owner).filter(row => this.eligible(row, now)).map(card) : []);
+    }
+    handoffs(owner, generation) {
+        return this.transaction(false, () => this.db.prepare(`SELECT a.* FROM attempts a JOIN cards c ON c.seq=a.seq
+      WHERE c.owner=? AND a.generation=? AND a.track='handoff' ORDER BY a.rowid`).all(owner, generation).map(attempt));
+    }
+    attach(input) {
+        const encoded = JSON.stringify(input.routes);
+        return this.transaction(true, now => {
+            const previous = this.getSession(input.owner);
+            if (previous?.state === 'deleted' || (previous ? previous.generation !== input.expectedGeneration : input.expectedGeneration !== null))
+                return false;
+            const generation = randomUUID();
+            this.db.prepare(`INSERT INTO sessions VALUES(?,?,'attached',?,?) ON CONFLICT(owner)
+        DO UPDATE SET generation=excluded.generation,state=excluded.state,routes_json=excluded.routes_json,at=excluded.at`).run(input.owner, generation, encoded, now);
+            return this.getSession(input.owner);
+        });
+    }
+    updateRoutes(input) {
+        const encoded = JSON.stringify(input.routes);
+        return this.transaction(true, now => {
+            if (!this.attached(input.owner, input.generation))
+                return false;
+            this.db.prepare('UPDATE sessions SET routes_json=?,at=? WHERE owner=?').run(encoded, now, input.owner);
+            return true;
+        });
+    }
+    lifecycle(input, state) {
+        return this.transaction(true, now => {
+            const s = this.getSession(input.owner);
+            if (!s || s.generation !== input.generation || s.state === 'deleted')
+                return false;
+            this.db.prepare('UPDATE sessions SET state=?,at=? WHERE owner=?').run(state, now, input.owner);
+            return true;
+        });
+    }
+    post(input) {
+        return this.transaction(true, now => {
+            const s = this.getSession(input.owner);
+            if (!s)
+                return { status: 'unknown-session' };
+            if (s.state === 'deleted')
+                return { status: 'deleted-session' };
+            const previous = this.db.prepare('SELECT * FROM cards WHERE owner=? AND key=?').get(input.owner, input.key);
+            if (previous) {
+                if (this.listAttempts(previous.seq).some(a => ['accepted', 'unknown', 'presented'].includes(a.outcome)))
+                    return { status: 'duplicate' };
+                return { status: previous.text !== input.text || previous.details !== input.details ? 'conflict' : this.isSuppressed(input.owner, input.key, now) ? 'suppressed' : 'duplicate' };
+            }
+            if (this.db.prepare("SELECT 1 FROM suppressions WHERE owner=? AND key=? AND scope='exact' AND expires_at IS NULL").get(input.owner, input.key))
+                return { status: 'suppressed' };
+            const suppressed = this.isSuppressed(input.owner, input.key, now);
+            const seq = Number(this.db.prepare('SELECT next_seq FROM meta').get().next_seq);
+            if (!Number.isSafeInteger(seq + 1))
+                throw new RangeError('Delivery sequence exhausted');
+            this.db.prepare('UPDATE meta SET next_seq=?').run(seq + 1);
+            this.db.prepare('INSERT INTO cards VALUES(?,?,?,?,?,?)').run(seq, input.owner, input.key, input.text, input.details, now);
+            return { status: suppressed ? 'suppressed' : 'posted' };
+        });
+    }
+    suppress(input) {
+        return this.transaction(true, now => {
+            const permanentId = input.scope === 'exact' && input.expiresAt === undefined
+                ? this.db.prepare("SELECT id FROM suppressions WHERE owner=? AND key=? AND scope='exact' AND expires_at IS NULL").get(input.owner, input.key)?.id
+                : undefined;
+            const id = permanentId ?? randomUUID();
+            const matching = this.db.prepare('SELECT * FROM cards WHERE owner=?').all(input.owner)
+                .filter(row => input.scope === 'exact' ? row.key === input.key : String(row.key).startsWith(input.key));
+            const inCustody = matching.some(row => this.awaitingEffect(row.seq));
+            if (permanentId === undefined)
+                this.db.prepare('INSERT INTO suppressions VALUES(?,?,?,?,?,?)').run(id, input.owner, input.key, input.scope, now, input.expiresAt ?? null);
+            if (input.scope === 'exact' && input.expiresAt === undefined)
+                for (const row of matching) {
+                    if (!this.awaitingEffect(row.seq))
+                        this.deleteCard(row.seq);
+                }
+            return { id, status: inCustody ? 'in-custody' : 'suppressed' };
+        });
+    }
+    renewSuppression(input) {
+        return this.transaction(true, now => this.db.prepare('UPDATE suppressions SET expires_at=? WHERE owner=? AND id=? AND (expires_at IS NULL OR expires_at>?)').run(input.expiresAt, input.owner, input.id, now).changes > 0);
+    }
+    releaseSuppression(input) {
+        return this.transaction(true, () => this.db.prepare('DELETE FROM suppressions WHERE owner=? AND id=?').run(input.owner, input.id).changes > 0);
+    }
+    cancel(input) {
+        return this.transaction(true, () => {
+            if (!this.attached(input.owner, input.generation))
+                return false;
+            this.db.prepare(`INSERT INTO cancellations VALUES(?,?,(SELECT next_seq-1 FROM meta))
+        ON CONFLICT(owner) DO UPDATE SET generation=excluded.generation,through_seq=MAX(through_seq,excluded.through_seq)`).run(input.owner, input.generation);
+            return true;
+        });
+    }
+    isSuppressed(owner, key, now) {
+        return !!this.db.prepare(`SELECT 1 FROM suppressions WHERE owner=? AND (expires_at IS NULL OR expires_at>?)
+      AND ((scope='exact' AND key=?) OR (scope='prefix' AND substr(?,1,length(key))=key)) LIMIT 1`).get(owner, now, key, key);
+    }
+    eligible(row, now) {
+        if (this.isSuppressed(String(row.owner), String(row.key), now))
+            return false;
+        if (this.db.prepare('SELECT 1 FROM receipts WHERE owner=? AND key=?').get(row.owner, row.key))
+            return false;
+        const cancellation = this.db.prepare('SELECT through_seq FROM cancellations WHERE owner=?').get(row.owner);
+        return !(cancellation && Number(cancellation.through_seq) >= Number(row.seq));
+    }
+    insertAttempt(seq, generation, track, routeKind, now, leaseMs) {
+        const token = randomUUID();
+        this.db.prepare("INSERT INTO attempts VALUES(?,?,?,?,?,'dispatching','{}',?,?,NULL)").run(token, seq, generation, track, routeKind, now, now + leaseMs);
+        return this.getAttempt(token);
+    }
+    claimPresentation(owner, generation, budgetChars, leaseMs, signal) {
+        return this.transaction(true, now => {
+            if (!this.attached(owner, generation))
+                return undefined;
+            this.normalize(now);
+            const cards = [], attempts = [];
+            let size = 0;
+            for (const row of this.db.prepare('SELECT * FROM cards WHERE owner=? ORDER BY seq').all(owner)) {
+                if (!this.eligible(row, now) || this.listAttempts(row.seq).some(holds))
+                    continue;
+                const next = card(row);
+                const nextSize = size + next.text.length + (cards.length ? 2 : 0);
+                if (nextSize > budgetChars && cards.length > 0)
+                    break;
+                size = nextSize;
+                cards.push(next);
+                attempts.push(this.insertAttempt(next.seq, generation, 'presentation', null, now, leaseMs));
+                if (size > budgetChars)
+                    break;
+            }
+            return cards.length ? { cards, attempts } : undefined;
+        }, signal);
+    }
+    claimHandoff(owner, key, generation, kind, leaseMs, signal) {
+        return this.transaction(true, now => {
+            const route = this.attached(owner, generation)?.routes.find(route => route.kind === kind);
+            if (!route)
+                return undefined;
+            this.normalize(now);
+            const row = this.db.prepare('SELECT * FROM cards WHERE owner=? AND key=?').get(owner, key);
+            if (!row || !this.eligible(row, now) || this.listAttempts(row.seq).some(holds))
+                return undefined;
+            return { card: card(row), route, attempt: this.insertAttempt(row.seq, generation, 'handoff', route.kind, now, leaseMs) };
+        }, signal);
+    }
+    current(tokens, signal, route) {
+        if (signal?.aborted)
+            return Promise.resolve(false);
+        return this.transaction(false, now => tokens.every(token => {
+            const a = this.getAttempt(token);
+            if (!a || a.outcome !== 'dispatching' || a.expiresAt <= now)
+                return false;
+            const row = this.db.prepare('SELECT * FROM cards WHERE seq=?').get(a.seq);
+            const s = row && this.attached(row.owner, a.generation);
+            const registered = s?.routes.find(candidate => candidate.kind === route?.kind);
+            return !!row && !!s && this.eligible(row, now) && (route === undefined || !!registered
+                && Object.keys(route.address).length === Object.keys(registered.address).length
+                && Object.entries(route.address).every(([key, value]) => Object.hasOwn(registered.address, key) && registered.address[key] === value));
+        }), signal);
+    }
+    prepare(token, value, signal) {
+        const encoded = JSON.stringify(value);
+        return this.transaction(true, now => {
+            const a = this.getAttempt(token);
+            if (!a || a.outcome !== 'dispatching' || a.expiresAt <= now)
+                return false;
+            if (a.correlation.payloadHash !== undefined && a.correlation.payloadHash !== value.payloadHash)
+                return false;
+            const row = this.db.prepare('SELECT owner FROM cards WHERE seq=?').get(a.seq);
+            if (!row || !this.attached(row.owner, a.generation))
+                return false;
+            this.db.prepare('UPDATE attempts SET correlation_json=? WHERE token=?').run(encoded, token);
+            return true;
+        }, signal);
+    }
+    receipt(seq, now) {
+        this.db.prepare('INSERT INTO receipts SELECT owner,key,? FROM cards WHERE seq=? ON CONFLICT(owner,key) DO NOTHING').run(now, seq);
+    }
+    confirm(handoff, now) {
+        if (handoff.track !== 'handoff' || !['dispatching', 'accepted', 'unknown'].includes(handoff.outcome))
+            return false;
+        const previous = this.listAttempts(handoff.seq).filter(a => a.track === 'presentation');
+        if (previous.some(a => a.outcome === 'presented'))
+            return true;
+        if (previous.some(holds))
+            return false;
+        const p = this.insertAttempt(handoff.seq, handoff.generation, 'presentation', handoff.routeKind, now, 1);
+        this.db.prepare("UPDATE attempts SET outcome='presented',correlation_json=?,settled_at=? WHERE token=?").run(JSON.stringify(handoff.correlation), now, p.token);
+        this.receipt(handoff.seq, now);
+        return true;
+    }
+    settle(tokens, outcome) {
+        return this.transaction(true, now => {
+            const attempts = tokens.map(token => this.getAttempt(token));
+            if (attempts.some(a => !a || a.track === 'presentation' && outcome === 'accepted'
+                || !['dispatching', 'unknown'].includes(a.outcome) && a.outcome !== outcome))
+                return false;
+            for (const a of attempts) {
+                if (a.outcome === outcome)
+                    continue;
+                if (a.outcome === 'unknown' && !['accepted', 'presented'].includes(outcome))
+                    return false;
+            }
+            for (const a of attempts) {
+                if (a.outcome === outcome)
+                    continue;
+                if (a.track === 'handoff' && outcome === 'presented') {
+                    if (!this.confirm(a, now))
+                        throw new Error('Cannot confirm handoff presentation');
+                    this.db.prepare("UPDATE attempts SET outcome='accepted',settled_at=? WHERE token=?").run(now, a.token);
+                }
+                else {
+                    this.db.prepare('UPDATE attempts SET outcome=?,settled_at=? WHERE token=?').run(outcome, now, a.token);
+                    if (outcome === 'presented')
+                        this.receipt(a.seq, now);
+                }
+            }
+            return true;
+        });
+    }
+    handoffFacts(token) {
+        const a = this.getAttempt(token);
+        if (!a || a.track !== 'handoff' || !a.routeKind || !a.correlation.payloadHash)
+            return undefined;
+        const row = this.db.prepare('SELECT * FROM cards WHERE seq=?').get(a.seq);
+        if (!row)
+            return undefined;
+        return { attempt: a, row, ref: { token: a.token, owner: row.owner, generation: a.generation,
+                payloadHash: a.correlation.payloadHash, routeKind: a.routeKind } };
+    }
+    matchingHandoff(ref) {
+        if (!ref || typeof ref !== 'object' || typeof ref.token !== 'string')
+            return undefined;
+        const facts = this.handoffFacts(ref.token);
+        return facts && facts.ref.owner === ref.owner && facts.ref.generation === ref.generation
+            && facts.ref.payloadHash === ref.payloadHash && ref.routeKind === facts.ref.routeKind ? facts : undefined;
+    }
+    currentHandoff(facts, now) {
+        const s = this.attached(facts.ref.owner, facts.ref.generation);
+        return facts.attempt.expiresAt > now && !!s && s.routes.some(route => route.kind === facts.ref.routeKind) && this.eligible(facts.row, now);
+    }
+    handoff(token) {
+        return this.transaction(false, () => this.handoffFacts(token)?.ref);
+    }
+    guardHandoff(ref) {
+        return this.transaction(false, now => {
+            const facts = this.matchingHandoff(ref);
+            return !!facts && ['dispatching', 'unknown'].includes(facts.attempt.outcome) && this.currentHandoff(facts, now);
+        });
+    }
+    acceptHandoff(ref) {
+        return this.transaction(true, now => {
+            const a = this.matchingHandoff(ref)?.attempt;
+            if (!a || !['dispatching', 'unknown', 'accepted'].includes(a.outcome))
+                return false;
+            if (a.outcome !== 'accepted')
+                this.db.prepare("UPDATE attempts SET outcome='accepted',settled_at=? WHERE token=?").run(now, a.token);
+            return true;
+        });
+    }
+    observePresentation(handoff, options) {
+        return this.transaction(true, now => {
+            const facts = typeof handoff === 'string' ? undefined : this.matchingHandoff(handoff);
+            if (options?.requireCurrent) {
+                const s = facts && this.attached(facts.ref.owner, facts.ref.generation);
+                if (!facts || !s || !s.routes.some(route => route.kind === facts.ref.routeKind) || !this.eligible(facts.row, now)
+                    || !!this.db.prepare(`SELECT 1 FROM attempts WHERE seq=? AND rowid>(SELECT rowid FROM attempts WHERE token=?) LIMIT 1`)
+                        .get(facts.attempt.seq, facts.attempt.token))
+                    return false;
+            }
+            const a = typeof handoff === 'string' ? this.getAttempt(handoff) : facts?.attempt;
+            return a ? this.confirm(a, now) : false;
+        });
+    }
+    receipts(owner, options) {
+        return this.transaction(false, () => this.db.prepare('SELECT * FROM receipts WHERE owner=? AND at>=? ORDER BY at,key').all(owner, options.since ?? -Number.MAX_VALUE)
+            .filter(row => options.keys === undefined || options.keys.includes(row.key))
+            .map(row => ({ owner: row.owner, key: row.key, at: row.at })));
+    }
+    health(owner) {
+        return this.transaction(false, now => {
+            const all = this.db.prepare('SELECT a.* FROM attempts a JOIN cards c ON c.seq=a.seq WHERE (? IS NULL OR c.owner=?) ORDER BY a.started_at,a.token').all(owner ?? null, owner ?? null).map(attempt);
+            const repeatedFailures = this.db.prepare(`SELECT c.owner,c.key,COUNT(*) AS count FROM attempts a JOIN cards c ON c.seq=a.seq
+        WHERE a.outcome='failed' AND (? IS NULL OR c.owner=?) GROUP BY c.owner,c.key HAVING COUNT(*)>=2 ORDER BY c.seq`).all(owner ?? null, owner ?? null)
+                .map(row => ({ owner: row.owner, key: row.key, count: row.count }));
+            const sessions = this.db.prepare("SELECT * FROM sessions WHERE state='attached' AND (? IS NULL OR owner=?) ORDER BY owner").all(owner ?? null, owner ?? null).map(row => session(row));
+            return { unknownAttempts: all.filter(a => a.outcome === 'unknown' || a.outcome === 'dispatching' && a.expiresAt <= now)
+                    .map(a => a.outcome === 'dispatching' ? { ...a, outcome: 'unknown' } : a), repeatedFailures,
+                sessionsWithoutRoute: sessions.filter(s => s.routes.length === 0).map(s => s.owner) };
+        });
+    }
+}