@maolon/pi-watcher 0.0.0-stage → 0.1.0

package/dist/storage/store.js

@@ -0,0 +1,555 @@
+/**
+ * WatchStore: local truth store (design 07).
+ * - SQLite WAL / synchronous=FULL / foreign_keys=ON
+ * - Each process holds the root flock (fixed inode); runtimeEpoch increments on every open
+ * - transaction(): synchronous, bounded transaction body (external I/O is forbidden inside)
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import Database from 'better-sqlite3';
+import { RootLock } from './lock.js';
+import { WatcherError } from '../util/result.js';
+const SCHEMA_SQL_PATH = fileURLToPath(new URL('./schema.sql', import.meta.url));
+export function emptySnapshot() {
+    return {
+        taskState: 'unknown',
+        stage: null,
+        exitCode: null,
+        summary: null,
+        checks: [],
+        artifactIds: [],
+        coverage: { truncated: false, sourceGap: false },
+        scopeRevision: 0,
+        backoffMs: 0
+    };
+}
+export class WatchStore {
+    rootDir;
+    dbPath;
+    evidenceDir;
+    resultsDir;
+    runtimeEpoch;
+    db;
+    lock;
+    closed = false;
+    constructor(rootDir, db, lock, epoch) {
+        this.rootDir = rootDir;
+        this.dbPath = path.join(rootDir, 'watcher.db');
+        this.evidenceDir = path.join(rootDir, 'evidence');
+        this.resultsDir = path.join(rootDir, 'results');
+        this.db = db;
+        this.lock = lock;
+        this.runtimeEpoch = epoch;
+    }
+    static async open(rootDir, options = {}) {
+        fs.mkdirSync(rootDir, { recursive: true });
+        const lock = new RootLock(rootDir);
+        if (!options.noLock) {
+            await lock.requireAcquire();
+        }
+        const dbPath = path.join(rootDir, 'watcher.db');
+        const db = new Database(dbPath);
+        db.pragma('journal_mode = WAL');
+        db.pragma('synchronous = FULL');
+        db.pragma('foreign_keys = ON');
+        const hasMeta = db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='runtime_meta'").get() !== undefined;
+        if (!hasMeta) {
+            const sql = fs.readFileSync(SCHEMA_SQL_PATH, 'utf8');
+            db.exec(sql);
+        }
+        // runtime_meta singleton row: created on first open (CHECK requires epoch>0, initialized to 1), then incremented on every process open (design 7.2 fencing)
+        db.prepare(`INSERT OR IGNORE INTO runtime_meta (singleton,schema_version,runtime_epoch,mode,recovery_attention_hold)
+      VALUES (1,1,1,?,1)`).run(options.mode ?? 'embedded');
+        // Bump runtime epoch for this process; every commit is fenced by it.
+        const bump = db.transaction(() => {
+            db.prepare("UPDATE runtime_meta SET runtime_epoch = runtime_epoch + 1, mode = ? WHERE singleton = 1")
+                .run(options.mode ?? 'embedded');
+            const row = db.prepare('SELECT runtime_epoch FROM runtime_meta WHERE singleton = 1').get();
+            return row.runtime_epoch;
+        });
+        const epoch = bump();
+        return new WatchStore(rootDir, db, options.noLock ? null : lock, epoch);
+    }
+    transaction(body) {
+        if (this.closed)
+            throw new WatcherError('STORE_UNAVAILABLE', 'store is closed');
+        const fence = this.db.prepare('SELECT runtime_epoch FROM runtime_meta WHERE singleton = 1').get();
+        if (fence.runtime_epoch !== this.runtimeEpoch) {
+            throw new WatcherError('STORE_UNAVAILABLE', 'stale runtime epoch: this store handle is fenced out');
+        }
+        this.db.exec('BEGIN IMMEDIATE');
+        let tx;
+        try {
+            tx = this.makeTx();
+            const out = body(tx);
+            this.db.exec('COMMIT');
+            return out;
+        }
+        catch (e) {
+            try {
+                this.db.exec('ROLLBACK');
+            }
+            catch {
+                /* already rolled back */
+            }
+            throw e;
+        }
+    }
+    get isClosed() {
+        return this.closed;
+    }
+    /** Connection-level pragma diagnostics (WAL persists; synchronous/foreign_keys are connection-level). */
+    pragmaReport() {
+        return {
+            journalMode: this.db.pragma('journal_mode', { simple: true }),
+            synchronous: this.db.pragma('synchronous', { simple: true }),
+            foreignKeys: this.db.pragma('foreign_keys', { simple: true })
+        };
+    }
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        this.db.close();
+        if (this.lock) {
+            void this.lock.release();
+        }
+    }
+    // --- evidence blocks: content-addressed files under root/evidence ---
+    writeEvidenceBlock(content) {
+        const { createHash } = require('node:crypto');
+        const sha = createHash('sha256').update(content, 'utf8').digest('hex');
+        fs.mkdirSync(this.evidenceDir, { recursive: true });
+        const locator = path.join('evidence', `${sha}.txt`);
+        const abs = path.join(this.rootDir, locator);
+        if (!fs.existsSync(abs)) {
+            fs.writeFileSync(abs, content, { encoding: 'utf8' });
+        }
+        return { sha256: sha, relativeLocator: locator, bytes: Buffer.byteLength(content, 'utf8') };
+    }
+    writeResultCard(watchId, resultId, card) {
+        const dir = path.join(this.resultsDir, watchId);
+        fs.mkdirSync(dir, { recursive: true });
+        const abs = path.join(dir, `${resultId}.json`);
+        fs.writeFileSync(abs, JSON.stringify(card, null, 2), 'encoding' in { encoding: 'utf8' } ? 'utf8' : undefined);
+        return path.relative(this.rootDir, abs);
+    }
+    listResultCards(watchId) {
+        const dir = path.join(this.resultsDir, watchId);
+        if (!fs.existsSync(dir))
+            return [];
+        return fs.readdirSync(dir)
+            .filter(f => f.endsWith('.json'))
+            .sort()
+            .map(f => JSON.parse(fs.readFileSync(path.join(dir, f), 'utf8')));
+    }
+    // --- transaction body ---
+    makeTx() {
+        const db = this.db;
+        const selWatch = db.prepare('SELECT * FROM watches WHERE watch_id = ?');
+        const insWatch = db.prepare(`INSERT INTO watches
+      (watch_id,generation,mission_revision,control_revision,lifecycle,health,owner_session,owner_binding_epoch,
+       spec_json,snapshot_json,observation_seq,next_due_at,updated_at)
+      VALUES (?,?,?,?,?,?,?,?,?,?,0,?,?)`);
+        const updWatch = db.prepare(`UPDATE watches SET
+      lifecycle=COALESCE(?,lifecycle), health=COALESCE(?,health), control_revision=COALESCE(?,control_revision),
+      mission_revision=COALESCE(?,mission_revision), snapshot_json=COALESCE(?,snapshot_json),
+      observation_seq=COALESCE(?,observation_seq), next_due_at=COALESCE(?,next_due_at), updated_at=?
+      WHERE watch_id=?`);
+        const insObs = db.prepare(`INSERT OR IGNORE INTO observations
+      (observation_id,watch_id,generation,source_id,attempt_id,source_seq,local_seq,observed_at,digest,payload_json)
+      VALUES (?,?,?,?,?,?,?,?,?,?)`);
+        const tx = {
+            meta: () => {
+                const r = db.prepare('SELECT schema_version,runtime_epoch,mode,recovery_attention_hold FROM runtime_meta WHERE singleton=1')
+                    .get();
+                return {
+                    schemaVersion: r.schema_version,
+                    runtimeEpoch: r.runtime_epoch,
+                    mode: r.mode,
+                    recoveryAttentionHold: r.recovery_attention_hold === 1
+                };
+            },
+            clearRecoveryHold: () => {
+                db.prepare('UPDATE runtime_meta SET recovery_attention_hold = 0 WHERE singleton = 1').run();
+            },
+            getWatchRow: (watchId) => {
+                const r = selWatch.get(watchId);
+                return r ? rowToWatchRow(r) : undefined;
+            },
+            getWatch: (watchId) => tx.getWatchRow(watchId)?.spec,
+            compareRevision: (basis) => {
+                const r = selWatch.get(basis.watchId);
+                if (!r)
+                    return false;
+                return (r.generation === basis.generation &&
+                    r.mission_revision === basis.missionRevision &&
+                    r.control_revision === basis.controlRevision &&
+                    basis.observationSeq <= r.observation_seq);
+            },
+            persistCommandResult: (actorId, requestId, digest, result) => {
+                const existing = db.prepare('SELECT digest,response_json FROM commands WHERE actor_id=? AND request_id=?')
+                    .get(actorId, requestId);
+                if (existing) {
+                    if (existing.digest === digest) {
+                        return { duplicate: true, previous: JSON.parse(existing.response_json) };
+                    }
+                    throw new WatcherError('REQUEST_CONFLICT', `requestId ${requestId} replayed with different digest`);
+                }
+                db.prepare('INSERT INTO commands (request_id,actor_id,digest,response_json,committed_at) VALUES (?,?,?,?,?)')
+                    .run(requestId, actorId, digest, JSON.stringify(result), Date.now());
+                return { duplicate: false };
+            },
+            getCommand: (actorId, requestId) => {
+                const r = db.prepare('SELECT digest,response_json FROM commands WHERE actor_id=? AND request_id=?')
+                    .get(actorId, requestId);
+                return r ? { digest: r.digest, response: JSON.parse(r.response_json) } : undefined;
+            },
+            insertWatch: (row) => {
+                insWatch.run(row.watchId, row.generation, row.missionRevision, row.controlRevision, row.lifecycle, row.health, row.ownerSession, row.ownerBindingEpoch, JSON.stringify(row.spec), JSON.stringify(row.snapshot), row.nextDueAt, row.now);
+            },
+            updateWatch: (watchId, patch, now) => {
+                const cur = selWatch.get(watchId);
+                if (!cur)
+                    throw new WatcherError('UNKNOWN_TARGET', `watch ${watchId} not found`);
+                updWatch.run(patch.lifecycle ?? null, patch.health ?? null, patch.controlRevision ?? null, patch.missionRevision ?? null, patch.snapshot ? JSON.stringify(patch.snapshot) : null, patch.observationSeq ?? null, patch.nextDueAt === undefined ? null : patch.nextDueAt, now, watchId);
+            },
+            bumpObservationSeq: (watchId) => {
+                db.prepare('UPDATE watches SET observation_seq = observation_seq + 1 WHERE watch_id = ?').run(watchId);
+                const r = selWatch.get(watchId);
+                return r.observation_seq;
+            },
+            insertObservation: (input) => {
+                const info = insObs.run(input.observationId, input.watchId, input.generation, input.sourceId, input.attemptId, input.sourceSeq, input.localSeq, input.observedAt, input.digest, JSON.stringify(input.payload));
+                return info.changes === 1;
+            },
+            getCursor: (watchId, sourceId, generation) => {
+                const r = db.prepare('SELECT cursor_json FROM cursors WHERE watch_id=? AND source_id=? AND generation=?')
+                    .get(watchId, sourceId, generation);
+                return r ? JSON.parse(r.cursor_json) : undefined;
+            },
+            putCursor: (watchId, sourceId, generation, cursor) => {
+                db.prepare(`INSERT INTO cursors (watch_id,source_id,generation,cursor_json) VALUES (?,?,?,?)
+          ON CONFLICT(watch_id,source_id,generation) DO UPDATE SET cursor_json=excluded.cursor_json`)
+                    .run(watchId, sourceId, generation, JSON.stringify(cursor));
+            },
+            nextEpisodeOrdinal: (watchId, generation, kind, checkpointId) => {
+                const r = db.prepare('SELECT COALESCE(MAX(ordinal),0)+1 AS n FROM episodes WHERE watch_id=? AND generation=? AND kind=? AND checkpoint_id=?').get(watchId, generation, kind, checkpointId);
+                return r.n;
+            },
+            insertEpisode: (input) => {
+                db.prepare(`INSERT INTO episodes
+          (episode_id,watch_id,generation,kind,checkpoint_id,ordinal,revision,state,body_json,snooze_until,updated_at)
+          VALUES (?,?,?,?,?,?,1,'open',?,NULL,?)`)
+                    .run(input.episodeId, input.watchId, input.generation, input.kind, input.checkpointId, input.ordinal, JSON.stringify(input.body), input.now);
+            },
+            getEpisode: (episodeId) => {
+                const r = db.prepare('SELECT * FROM episodes WHERE episode_id=?').get(episodeId);
+                return r ? rowToEpisodeRow(r) : undefined;
+            },
+            getActiveEpisodeBySlot: (watchId, generation, kind, checkpointId) => {
+                const r = db.prepare(`SELECT * FROM episodes
+          WHERE watch_id=? AND generation=? AND kind=? AND checkpoint_id=? AND state IN ('open','snoozed','acknowledged')
+          ORDER BY ordinal DESC LIMIT 1`)
+                    .get(watchId, generation, kind, checkpointId);
+                return r ? rowToEpisodeRow(r) : undefined;
+            },
+            updateEpisode: (episodeId, expectedRevision, patch, now) => {
+                const info = db.prepare(`UPDATE episodes SET
+          state=COALESCE(?,state), body_json=COALESCE(?,body_json), snooze_until=COALESCE(?,snooze_until),
+          revision=revision+1, updated_at=?
+          WHERE episode_id=? AND revision=?`)
+                    .run(patch.state ?? null, patch.body ? JSON.stringify(patch.body) : null, patch.snoozeUntil === undefined ? null : patch.snoozeUntil, now, episodeId, expectedRevision);
+                if (info.changes !== 1)
+                    return null;
+                const r = db.prepare('SELECT revision FROM episodes WHERE episode_id=?').get(episodeId);
+                return r.revision;
+            },
+            listEpisodes: (watchId, limit) => {
+                const rows = db.prepare('SELECT * FROM episodes WHERE watch_id=? ORDER BY updated_at DESC LIMIT ?')
+                    .all(watchId, limit);
+                return rows.map(rowToEpisodeRow);
+            },
+            insertOutbox: (input) => {
+                db.prepare(`INSERT INTO outbox
+          (event_id,watch_id,episode_id,generation,event_type,event_bytes,event_digest,valid_until,admission,admission_json,created_at,updated_at)
+          VALUES (?,?,?,?,?,?,?,?, ?, ?, ?, ?)`)
+                    .run(input.eventId, input.watchId, input.episodeId, input.generation, input.eventType, input.eventBytes, input.eventDigest, input.validUntil, input.admission ?? 'pending', JSON.stringify(input.admissionJson ?? {}), input.now, input.now);
+            },
+            setOutboxAdmission: (eventId, admission, admissionJson, now) => {
+                db.prepare('UPDATE outbox SET admission=?, admission_json=?, updated_at=? WHERE event_id=?')
+                    .run(admission, JSON.stringify(admissionJson), now, eventId);
+            },
+            getOutbox: (eventId) => {
+                const r = db.prepare('SELECT * FROM outbox WHERE event_id=?').get(eventId);
+                return r ? rowToOutboxRow(r) : undefined;
+            },
+            listOutboxByWatch: (watchId, limit) => {
+                const rows = db.prepare('SELECT * FROM outbox WHERE watch_id=? ORDER BY created_at DESC LIMIT ?')
+                    .all(watchId, limit);
+                return rows.map(rowToOutboxRow);
+            },
+            insertControlOutbox: (input) => {
+                db.prepare(`INSERT INTO control_outbox
+          (operation_id,watch_id,scope_id,expected_revision,next_revision,requested_state,status,result_json,created_at)
+          VALUES (?,?,?,?,?,?, 'pending', '{}', ?)`)
+                    .run(input.operationId, input.watchId, input.scopeId, input.expectedRevision, input.nextRevision, input.requestedState, input.now);
+            },
+            completeControlOutbox: (operationId, status, result) => {
+                if (result) {
+                    db.prepare('UPDATE control_outbox SET status=?, result_json=? WHERE operation_id=?')
+                        .run(status, JSON.stringify(result), operationId);
+                }
+                else {
+                    db.prepare('UPDATE control_outbox SET status=? WHERE operation_id=?')
+                        .run(status, operationId);
+                }
+            },
+            getControlOutboxStatus: (operationId) => {
+                const r = db.prepare('SELECT status FROM control_outbox WHERE operation_id=?').get(operationId);
+                return r?.status ?? null;
+            },
+            listOpenControlOutbox: (watchId) => {
+                const rows = (watchId
+                    ? db.prepare(`SELECT * FROM control_outbox WHERE watch_id=? AND status IN ('pending','sending','unknown')
+              ORDER BY created_at, rowid`).all(watchId)
+                    : db.prepare(`SELECT * FROM control_outbox WHERE status IN ('pending','sending','unknown')
+              ORDER BY created_at, rowid`).all());
+                return rows.map(r => ({
+                    operationId: r.operation_id,
+                    watchId: r.watch_id,
+                    scopeId: r.scope_id,
+                    expectedRevision: r.expected_revision,
+                    nextRevision: r.next_revision,
+                    requestedState: r.requested_state,
+                    status: r.status,
+                    createdAt: r.created_at
+                }));
+            },
+            mergeOutboxAdmissionJson: (eventId, patch, now) => {
+                const r = db.prepare('SELECT admission_json FROM outbox WHERE event_id=?').get(eventId);
+                if (!r)
+                    return;
+                const merged = { ...JSON.parse(r.admission_json), ...patch };
+                db.prepare('UPDATE outbox SET admission_json=?, updated_at=? WHERE event_id=?')
+                    .run(JSON.stringify(merged), now, eventId);
+            },
+            listOutboxAwaitingWithdraw: (limit) => {
+                const rows = db.prepare(`SELECT * FROM outbox WHERE event_type='watcher.attention.v1'
+          AND json_extract(admission_json,'$.withdraw.operationId') IS NOT NULL
+          AND json_extract(admission_json,'$.withdraw.result') IS NULL
+          ORDER BY created_at LIMIT ?`).all(limit);
+                return rows.map(rowToOutboxRow);
+            },
+            insertAppliedResponse: (input) => {
+                db.prepare(`INSERT INTO applied_responses
+          (response_id,watch_id,episode_id,delivery_ref,digest,result_json,applied_at)
+          VALUES (?,?,?,?,?,?,?)`)
+                    .run(input.responseId, input.watchId, input.episodeId, input.deliveryRef, input.digest, JSON.stringify(input.result), input.now);
+            },
+            getAppliedResponse: (responseId) => {
+                const r = db.prepare('SELECT response_id,result_json FROM applied_responses WHERE response_id=?')
+                    .get(responseId);
+                return r ? { responseId: r.response_id, result: JSON.parse(r.result_json) } : undefined;
+            },
+            insertAppliedConfirmOutbox: (operationId, responseId) => {
+                db.prepare(`INSERT INTO applied_confirmation_outbox (operation_id,response_id,status,result_json)
+          VALUES (?,?,'pending','{}')`).run(operationId, responseId);
+            },
+            listObservations: (watchId, limit) => {
+                const rows = db.prepare('SELECT observation_id,source_seq,local_seq,observed_at,digest,payload_json FROM observations WHERE watch_id=? ORDER BY local_seq DESC LIMIT ?')
+                    .all(watchId, limit);
+                return rows.map(r => ({
+                    observationId: r.observation_id,
+                    sourceSeq: r.source_seq,
+                    localSeq: r.local_seq,
+                    observedAt: r.observed_at,
+                    digest: r.digest,
+                    payload: JSON.parse(r.payload_json)
+                }));
+            },
+            listWatches: (ownerSession, cursor, limit, lifecycles) => {
+                const lc = lifecycles && lifecycles.length > 0 ? ` AND lifecycle IN (${lifecycles.map(() => '?').join(',')})` : '';
+                const rows = (cursor
+                    ? db.prepare(`SELECT * FROM watches WHERE owner_session=? AND watch_id > ?${lc} ORDER BY watch_id LIMIT ?`)
+                        .all(ownerSession, cursor, ...lifecycles ?? [], limit)
+                    : db.prepare(`SELECT * FROM watches WHERE owner_session=?${lc} ORDER BY watch_id LIMIT ?`)
+                        .all(ownerSession, ...lifecycles ?? [], limit));
+                return rows.map(rowToWatchRow);
+            },
+            countWatches: (ownerSession, lifecycles) => {
+                const lc = lifecycles && lifecycles.length > 0 ? ` AND lifecycle IN (${lifecycles.map(() => '?').join(',')})` : '';
+                const r = db.prepare(`SELECT COUNT(*) AS n FROM watches WHERE owner_session=?${lc}`)
+                    .get(ownerSession, ...lifecycles ?? []);
+                return r.n;
+            },
+            listAllWatches: (limit) => {
+                const rows = db.prepare('SELECT * FROM watches ORDER BY watch_id LIMIT ?')
+                    .all(limit);
+                return rows.map(rowToWatchRow);
+            },
+            countOpenEpisodes: (watchId) => {
+                const r = db.prepare(`SELECT COUNT(*) AS n FROM episodes WHERE watch_id=? AND state IN ('open','snoozed','acknowledged')`)
+                    .get(watchId);
+                return r.n;
+            },
+            countUnresolvedEpisodes: (ownerSession) => {
+                if (ownerSession) {
+                    const r = db.prepare(`SELECT COUNT(*) AS n FROM episodes e
+            JOIN watches w ON w.watch_id = e.watch_id
+            WHERE e.state IN ('open','snoozed','acknowledged') AND w.owner_session=?`)
+                        .get(ownerSession);
+                    return r.n;
+                }
+                const r = db.prepare(`SELECT COUNT(*) AS n FROM episodes WHERE state IN ('open','snoozed','acknowledged')`)
+                    .get();
+                return r.n;
+            },
+            countPendingAttentions: (now, ownerSession) => {
+                if (ownerSession) {
+                    const r = db.prepare(`SELECT COUNT(*) AS n FROM outbox o
+            JOIN episodes e ON e.episode_id = o.episode_id
+            JOIN watches w ON w.watch_id = e.watch_id
+            WHERE o.event_type='watcher.attention.v1' AND e.state IN ('open','snoozed')
+              AND o.admission != 'expired' AND o.valid_until > ? AND w.owner_session=?`)
+                        .get(now, ownerSession);
+                    return r.n;
+                }
+                const r = db.prepare(`SELECT COUNT(*) AS n FROM outbox o JOIN episodes e ON e.episode_id = o.episode_id
+          WHERE o.event_type='watcher.attention.v1' AND e.state IN ('open','snoozed')
+            AND o.admission != 'expired' AND o.valid_until > ?`)
+                    .get(now);
+                return r.n;
+            },
+            supersedeEpisodesOfWatch: (watchId, now) => {
+                const info = db.prepare(`UPDATE episodes SET state='superseded', revision=revision+1, updated_at=?
+          WHERE watch_id=? AND state IN ('open','snoozed','acknowledged')`).run(now, watchId);
+                return info.changes;
+            },
+            supersedeEpisodesOfInactiveWatches: (now) => {
+                const info = db.prepare(`UPDATE episodes SET state='superseded', revision=revision+1, updated_at=?
+          WHERE state IN ('open','snoozed','acknowledged')
+            AND watch_id IN (SELECT watch_id FROM watches WHERE lifecycle IN ('closed','expired'))`).run(now);
+                return info.changes;
+            },
+            expireStaleAttentions: (now) => {
+                const info = db.prepare(`UPDATE outbox SET admission='expired',
+          admission_json=json_set(admission_json, '$.note', 'attention ttl elapsed before delivery; no longer deliverable'),
+          updated_at=?
+          WHERE event_type='watcher.attention.v1' AND admission IN ('pending','publishing') AND valid_until < ?`).run(now, now);
+                return info.changes;
+            },
+            insertJudgment: (input) => {
+                db.prepare(`INSERT INTO judgments (judgment_id,watch_id,generation,mission_revision,control_revision,window_digest,model,question_set,status,data_json,created_at)
+          VALUES (?,?,?,?,?,?,?,?,?,?,?)`)
+                    .run(input.judgmentId, input.watchId, input.generation, input.missionRevision, input.controlRevision, input.windowDigest, input.model, input.questionSet, input.status, JSON.stringify(input.data), input.createdAt);
+            },
+            getJudgmentByWindow: (watchId, generation, windowDigest, model, questionSet) => {
+                const r = db.prepare(`SELECT judgment_id,status,data_json FROM judgments
+          WHERE watch_id=? AND generation=? AND window_digest=? AND model=? AND question_set=?
+          ORDER BY created_at DESC LIMIT 1`)
+                    .get(watchId, generation, windowDigest, model, questionSet);
+                if (!r)
+                    return undefined;
+                return { judgmentId: r.judgment_id, status: r.status, data: JSON.parse(r.data_json) };
+            },
+            listJudgments: (watchId, limit) => {
+                const rows = db.prepare(`SELECT judgment_id,window_digest,model,question_set,status,data_json,created_at FROM judgments WHERE watch_id=? ORDER BY created_at DESC LIMIT ?`)
+                    .all(watchId, limit);
+                return rows.map(r => ({
+                    judgmentId: r.judgment_id,
+                    windowDigest: r.window_digest,
+                    model: r.model,
+                    questionSet: r.question_set,
+                    status: r.status,
+                    data: JSON.parse(r.data_json),
+                    createdAt: r.created_at
+                }));
+            },
+            insertProbeRun: (input) => {
+                db.prepare(`INSERT INTO probe_runs (probe_run_id,watch_id,episode_id,generation,control_revision,probe_id,status,data_json,created_at)
+          VALUES (?,?,?,?,?,?,?,?,?)`)
+                    .run(input.probeRunId, input.watchId, input.episodeId, input.generation, input.controlRevision, input.probeId, input.status, JSON.stringify(input.data), input.createdAt);
+            },
+            setProbeRunStatus: (probeRunId, status, data) => {
+                db.prepare('UPDATE probe_runs SET status=?, data_json=? WHERE probe_run_id=?')
+                    .run(status, JSON.stringify(data), probeRunId);
+            },
+            countBudgetReservations: (category, periodKey, watchId) => {
+                const r = (watchId
+                    ? db.prepare(`SELECT COUNT(*) AS n FROM budget_reservations WHERE category=? AND period_key=? AND watch_id=? AND state IN ('reserved','spent','unknown-cost')`)
+                        .get(category, periodKey, watchId)
+                    : db.prepare(`SELECT COUNT(*) AS n FROM budget_reservations WHERE category=? AND period_key=? AND state IN ('reserved','spent','unknown-cost')`)
+                        .get(category, periodKey));
+                return r.n;
+            },
+            insertBudgetReservation: (input) => {
+                db.prepare(`INSERT INTO budget_reservations (reservation_id,watch_id,category,period_key,units,state,created_at)
+          VALUES (?,?,?,?,?,?,?)`)
+                    .run(input.reservationId, input.watchId, input.category, input.periodKey, input.units, input.state, input.createdAt);
+            },
+            setBudgetReservationState: (reservationId, state) => {
+                db.prepare('UPDATE budget_reservations SET state=? WHERE reservation_id=?').run(state, reservationId);
+            },
+            getRelayCursor: (streamId) => {
+                const r = db.prepare('SELECT cursor FROM relay_cursors WHERE stream_id=?').get(streamId);
+                return r?.cursor;
+            },
+            putRelayCursor: (streamId, cursor) => {
+                db.prepare('INSERT INTO relay_cursors (stream_id,cursor) VALUES (?,?) ON CONFLICT(stream_id) DO UPDATE SET cursor=excluded.cursor')
+                    .run(streamId, cursor);
+            }
+        };
+        return tx;
+    }
+}
+/** Actor scoping removed: actorId is passed explicitly to persistCommandResult. */
+function rowToWatchRow(r) {
+    return {
+        watchId: r.watch_id,
+        generation: r.generation,
+        missionRevision: r.mission_revision,
+        controlRevision: r.control_revision,
+        lifecycle: r.lifecycle,
+        health: r.health,
+        ownerSession: r.owner_session,
+        ownerBindingEpoch: r.owner_binding_epoch,
+        spec: JSON.parse(r.spec_json),
+        snapshot: { ...emptySnapshot(), ...JSON.parse(r.snapshot_json) },
+        observationSeq: r.observation_seq,
+        nextDueAt: r.next_due_at ?? null,
+        updatedAt: r.updated_at
+    };
+}
+function rowToEpisodeRow(r) {
+    return {
+        episodeId: r.episode_id,
+        watchId: r.watch_id,
+        generation: r.generation,
+        kind: r.kind,
+        checkpointId: r.checkpoint_id,
+        ordinal: r.ordinal,
+        revision: r.revision,
+        state: r.state,
+        body: JSON.parse(r.body_json),
+        snoozeUntil: r.snooze_until ?? null,
+        updatedAt: r.updated_at
+    };
+}
+function rowToOutboxRow(r) {
+    return {
+        eventId: r.event_id,
+        watchId: r.watch_id,
+        episodeId: r.episode_id ?? null,
+        generation: r.generation,
+        eventType: r.event_type,
+        eventBytes: r.event_bytes,
+        eventDigest: r.event_digest,
+        validUntil: r.valid_until,
+        admission: r.admission,
+        admissionJson: JSON.parse(r.admission_json),
+        createdAt: r.created_at,
+        updatedAt: r.updated_at
+    };
+}

package/dist/util/clock.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Clock port per contracts/interfaces.ts.
+ * wallNow: persisted wall-clock ms (basis across restarts).
+ * monotonicNow: same-process monotonic ms (same-process elapsed).
+ */
+export interface Clock {
+    wallNow(): number;
+    monotonicNow(): number;
+}
+export declare class SystemClock implements Clock {
+    wallNow(): number;
+    monotonicNow(): number;
+}
+/** Injectable fake clock for tests. */
+export declare class ManualClock implements Clock {
+    private _wall;
+    private _mono;
+    constructor(wall?: number, mono?: number);
+    wallNow(): number;
+    monotonicNow(): number;
+    advanceWall(ms: number): void;
+    advanceMono(ms: number): void;
+}

package/dist/util/clock.js

@@ -0,0 +1,34 @@
+/**
+ * Clock port per contracts/interfaces.ts.
+ * wallNow: persisted wall-clock ms (basis across restarts).
+ * monotonicNow: same-process monotonic ms (same-process elapsed).
+ */
+export class SystemClock {
+    wallNow() {
+        return Date.now();
+    }
+    monotonicNow() {
+        return performance.now();
+    }
+}
+/** Injectable fake clock for tests. */
+export class ManualClock {
+    _wall;
+    _mono;
+    constructor(wall = Date.now(), mono = 0) {
+        this._wall = wall;
+        this._mono = mono;
+    }
+    wallNow() {
+        return this._wall;
+    }
+    monotonicNow() {
+        return this._mono;
+    }
+    advanceWall(ms) {
+        this._wall += ms;
+    }
+    advanceMono(ms) {
+        this._mono += ms;
+    }
+}

package/dist/util/ids.d.ts

@@ -0,0 +1,8 @@
+/**
+ * IDs and digests. watchId is globally random; digest is sha256 hex.
+ */
+export declare function newId(prefix: string): string;
+export declare function sha256Hex(data: string | Uint8Array): string;
+export declare function digestJson(value: unknown): string;
+/** Command digest for idempotency: requestId + digest is unique. */
+export declare function stableStringify(value: unknown): string;

package/dist/util/ids.js

@@ -0,0 +1,29 @@
+/**
+ * IDs and digests. watchId is globally random; digest is sha256 hex.
+ */
+import { createHash, randomUUID } from 'node:crypto';
+export function newId(prefix) {
+    return `${prefix}-${randomUUID().replace(/-/g, '').slice(0, 20)}`;
+}
+export function sha256Hex(data) {
+    return createHash('sha256').update(data).digest('hex');
+}
+export function digestJson(value) {
+    return sha256Hex(JSON.stringify(value));
+}
+/** Command digest for idempotency: requestId + digest is unique. */
+export function stableStringify(value) {
+    return JSON.stringify(sortValue(value));
+}
+function sortValue(value) {
+    if (Array.isArray(value))
+        return value.map(sortValue);
+    if (value && typeof value === 'object') {
+        const out = {};
+        for (const k of Object.keys(value).sort()) {
+            out[k] = sortValue(value[k]);
+        }
+        return out;
+    }
+    return value;
+}