common-memory-core 0.2.0

package/docs/v2-ablation.md

@@ -0,0 +1,117 @@
+# V2 调度机制消融实验
+
+## 结论范围
+
+本次是**真实 RuntimeStore 的调度层单因素消融**，不是完整 Writer 或真实模型的语义消融。
+未修改生产实现、未移除生产安全机制、未调用远程模型、未读取实际用户 dataRoot。
+Prompt、context-only、Section patch、语义 admission 等组件的质量贡献**尚未测量**；不能从脚本 oracle 推断它们无效。
+
+## 方法与控制变量
+
+- 40 个场景 × 6 个组 × 3 次重复 = **720 次隔离 SQLite 实验**；重复必须得到完全相同的去 ID 轨迹，否则脚本失败。
+- 组别：完整 Hybrid、分别移除数量／体积／空闲／最长等待／生命周期触发；一次仅移除一项。
+- 默认基线：6 Turn、16 KiB、120 秒 idle、600 秒 oldest wait。
+- **独立固定批容量为 6**，调用实际 `claim({maxTurns:6})`。生产默认批容量取 turnThreshold；直接调大该阈值而不固定容量会混入批大小效应。
+- 移除阈值用安全最大整数实现；所有实验轮数、字节数和虚拟时间远小于此值。
+- 同场景各组共享输入、Scope、busy/stable、关闭/重启时间与观察截止点。
+- 每秒检查一次、每次最多领取一批；同刻顺序固定为 **enqueue → lifecycle → 稳定检查**。新输入与 idle deadline 同刻时先重置 idle。
+- 领取后立即 no-op 完成，不模拟模型耗时、失败、重试和内容写入。
+- 生命周期用持久 `requestFlush()`，不是 `force:true`；关闭仅排队，重开数据库后才检查。
+- **截止时不额外强制 flush**，否则会掩盖尾批差异。pending 是窗口内未处理，不是永久丢失。
+- 均值按 Turn 加权，不将三次确定性重复视为三倍独立统计样本，不提供虚假的显著性或置信区间。
+
+原始 30 条轨迹来自已有 fixture，但末轮后 1 秒的 lifecycle flush 是本实验合成的宿主事件，
+不是实际采集证据；统一观察到末轮后 60 秒。截止选择影响 pending 数，不能外推生产发生率。
+另有 9 个默认参数诊断场景，以及 1 个单独分层的高数量阈值敏感性场景。
+
+## 指标
+
+- **维护批次**：实际成功领取并消费的队列批次，不是真实模型调用或 Token 成本。
+- **已处理延迟**：消费时刻减投递时刻；JSON 记录均值、P95 与逐轮值。
+- **截尾平均等待**：每轮取 `min(消费时刻, 观察截止)-投递时刻` 后求均值，避免忽略 pending 产生幸存者偏差。
+- pending 另报数量和年龄；截尾平均等待是有限窗口指标，不是未完成轮次的最终延迟估计。
+- 模型调用数为 0，Token 未测量。原始时序、分层汇总与代码/fixture 摘要在 [JSON](v2-ablation-results.json)。
+
+## 结果 A：已有 30 条轨迹（210 Turn）
+
+| 消融组 | 已处理 / 总轮数 | 截尾待处理 | 维护批次 | 截尾平均等待（秒） | 相对基线（秒） |
+|---|---:|---:|---:|---:|---:|
+| 完整 Hybrid | 210 / 210 | 0 | 60 | 47.89 | 0.00 |
+| 移除数量触发 | 210 / 210 | 0 | 60 | 56.20 | 8.31 |
+| 移除体积触发 | 210 / 210 | 0 | 60 | 47.89 | 0.00 |
+| 移除空闲触发 | 210 / 210 | 0 | 60 | 58.00 | 10.11 |
+| 移除最长等待 | 210 / 210 | 0 | 60 | 47.89 | 0.00 |
+| 移除生命周期 flush | 144 / 210 | 66 | 30 | 66.43 | 18.54 |
+
+数量与空闲触发影响等待，即使总批次数仍为 60。移除生命周期后有 66 条在截止前尚未处理；
+这不表示正文丢失。体积和最长等待在此样本无边际效应，不能据此判断为冗余。
+
+## 结果 B：默认参数诊断场景（9 场景、39 Turn）
+
+| 消融组 | 已处理 / 总轮数 | 截尾待处理 | 维护批次 | 截尾平均等待（秒） | 相对基线（秒） |
+|---|---:|---:|---:|---:|---:|
+| 完整 Hybrid | 39 / 39 | 0 | 15 | 153.85 | 0.00 |
+| 移除数量触发 | 33 / 39 | 6 | 14 | 197.05 | 43.21 |
+| 移除体积触发 | 38 / 39 | 1 | 14 | 155.38 | 1.54 |
+| 移除空闲触发 | 32 / 39 | 7 | 9 | 161.79 | 7.95 |
+| 移除最长等待 | 37 / 39 | 2 | 14 | 155.90 | 2.05 |
+| 移除生命周期 flush | 35 / 39 | 4 | 13 | 156.92 | 3.08 |
+
+每个机制都有能被独立识别的场景：
+
+| 机制 | 场景与证据 |
+|---|---|
+| 数量 | 6 条短消息在 50 秒内抵达：基线第 50 秒消费；去数量组第 110 秒仍待处理 6 条。 |
+| 体积 | 单条完整 20 KiB Turn：基线立即消费；去体积组第 60 秒仍待处理。 |
+| 空闲 | 两条短消息后不结束 Session：基线第 150 秒消费；去 idle 组第 210 秒仍待处理 2 条。 |
+| 生命周期 | 第 20 秒请求 flush；或第 20 秒关闭、第 40 秒重开，持久 flush 才触发。去生命周期组到第 60 秒均未消费。 |
+| 最长等待 | 第 0 秒与第 650 秒投递两条，宿主 busy 到第 660 秒。稳定后只有 oldest wait 满足；基线消费两条，去 maxWait 组第 700 秒仍未处理。 |
+
+**最长等待不是严格的墙钟完成 SLA。** 模型工作仍须等稳定边界；上例首轮实际等了 660 秒。
+跨 Scope 交错和 busy 边界也在 fixture 中，避免把全 global、始终空闲的结果误推到全部宿主。
+
+## 结果 C：高阈值敏感性（单独分层）
+
+数量阈值 100、字节阈值 1 GB；连续每 100 秒输入，共 12 条，观察到第 1150 秒。
+
+| 消融组 | 已处理 / 总轮数 | 截尾待处理 | 维护批次 | 截尾平均等待（秒） | 相对基线（秒） |
+|---|---:|---:|---:|---:|---:|
+| 完整 Hybrid | 6 / 12 | 6 | 1 | 325.00 | 0.00 |
+| 移除数量触发 | 6 / 12 | 6 | 1 | 325.00 | 0.00 |
+| 移除体积触发 | 6 / 12 | 6 | 1 | 325.00 | 0.00 |
+| 移除空闲触发 | 6 / 12 | 6 | 1 | 325.00 | 0.00 |
+| 移除最长等待 | 0 / 12 | 12 | 0 | 600.00 | 275.00 |
+| 移除生命周期 flush | 6 / 12 | 6 | 1 | 325.00 | 0.00 |
+
+去掉 maxWait 后一直被新输入重置 idle，窗口内零维护。基线处理 6 条、余下 6 条被截尾；
+这是窗口与固定批容量的结果，不是失败或永久积压证明。
+
+## 判断与下一步
+
+1. 在这些受控场景中，五种触发都有窗口内及时性贡献，**没有依据直接删除某一机制**。
+2. original-30 零效应属于覆盖不足；busy-aged-backlog 使默认 maxWait 的独立作用可见。
+3. 结果支持保留多触发设计，但不证明参数成本最优、语义更好或线上用户收益。
+4. 后续真实模型消融应固定模型、调用预算和对话集，分别测 current-state/context/维护指令，评审保留、更新、遗忘、过度泛化和 Scope 错误；本轮未执行该付费实验。
+
+## 复现与验证
+
+```sh
+npm run ablate:v2
+npm test -- --run tests/v2/ablation.test.ts
+npm run lint
+npm test
+```
+
+仅新增实验脚本、fixture、测试、npm 命令与文档，生产 Writer/Runtime/Pi 行为不变。
+独立实验设计审查记录见本文件末尾。
+
+### 验证记录
+
+- `npm run ablate:v2`：build 与 720 次隔离执行通过；三次重复逐场景轨迹完全一致。
+- `npm run lint`：typecheck 与静态边界检查通过。
+- `npm test`：13 个测试文件，104 项测试通过（包含 3 项新增实验回归）。
+- `git diff --check`：通过。
+- 独立 `critic` 实验设计审查：**OKAY，无阻断项**；核对脚本、场景、结果与报告，并独立运行新增 3 项测试通过。
+
+实验文件：`scripts/ablate-v2.mjs`、`fixtures/v2-ablation-scenarios.json`、
+`tests/v2/ablation.test.ts`、`docs/v2-ablation-results.json`。

package/docs/v2-evaluation-repeat-results.json

@@ -0,0 +1,7 @@
+{
+  "runs": 10,
+  "policyRuns": 30,
+  "trajectoryRuns": 900,
+  "failures": [],
+  "semanticQualityVerified": false
+}

package/docs/v2-evaluation-scripted-results.json

@@ -0,0 +1,67 @@
+{
+  "mode": "scripted-executor",
+  "semanticQualityVerified": false,
+  "trajectories": 30,
+  "results": [
+    {
+      "policy": "every-turn",
+      "cases": 30,
+      "correctFinalState": 30,
+      "scopeErrors": 0,
+      "calls": 210,
+      "inputBytes": 1455570,
+      "inputTokens": 0,
+      "outputTokens": 0,
+      "tokensMeasured": false,
+      "retries": 0,
+      "failureCodes": {},
+      "maxLatencyMs": 0,
+      "meanLatencyMs": 0,
+      "outcomes": {
+        "committed": 35,
+        "ignored": 175,
+        "idle": 30
+      }
+    },
+    {
+      "policy": "fixed-six",
+      "cases": 30,
+      "correctFinalState": 30,
+      "scopeErrors": 0,
+      "calls": 60,
+      "inputBytes": 430525,
+      "inputTokens": 0,
+      "outputTokens": 0,
+      "tokensMeasured": false,
+      "retries": 0,
+      "failureCodes": {},
+      "maxLatencyMs": 225000,
+      "meanLatencyMs": 58000,
+      "outcomes": {
+        "idle": 210,
+        "committed": 35,
+        "ignored": 25
+      }
+    },
+    {
+      "policy": "hybrid",
+      "cases": 30,
+      "correctFinalState": 30,
+      "scopeErrors": 0,
+      "calls": 60,
+      "inputBytes": 430525,
+      "inputTokens": 0,
+      "outputTokens": 0,
+      "tokensMeasured": false,
+      "retries": 0,
+      "failureCodes": {},
+      "maxLatencyMs": 165000,
+      "meanLatencyMs": 85286,
+      "outcomes": {
+        "idle": 222,
+        "committed": 35,
+        "ignored": 25
+      }
+    }
+  ]
+}

package/docs/v2-evaluation.md

@@ -0,0 +1,35 @@
+# V2 bounded evaluation
+
+`npm run build && node scripts/evaluate-v2.mjs` runs all 30 synthetic trajectories
+through the actual Writer, runtime queue, protocol validator and Markdown commit path
+under every-turn, fixed-six and hybrid scheduling. All policies flush their tail batch.
+There are five retain, update, forget, ignore, conditional preference and project-scope
+cases each. Variable pauses exercise idle maintenance. Fixtures contain explicit oracle
+actions used only by the scripted model, never by production semantic admission.
+
+The JSON report records final-state correctness, project-to-global scope errors, model
+calls, serialized input bytes, real token usage when available, failed/retry outcomes,
+and capture-to-model latency. Scripted token counts are zero (unknown/not measured),
+not estimates. These comparisons measure execution and scheduling; they do not show
+that any real model correctly interprets natural-language evidence. In particular,
+conditional wording and ignore correctness are supplied by the oracle.
+
+Real-model quality is separate, paid and opt-in:
+
+```sh
+COMMON_MEMORY_EVAL_CONFIRM=paid-remote-disclosure node scripts/evaluate-v2.mjs --real --limit=3
+```
+
+This uses configured credentials but creates isolated temporary runtime/canonical
+roots, never writes production memory, and discloses synthetic fixture text only.
+`--limit` is 1–30; total model calls have a hard cap of 630. No automatic provider
+fallback is used. Final-state exact-match is deliberately strict and can count a
+semantically correct paraphrase as a failure: inspect outputs before drawing quality
+conclusions. Broader human-reviewed over-memory/generalization precision/recall and
+real provider token/cost results remain unverified until this opt-in run is performed.
+
+The final scripted evaluation is repeated ten times with freshly generated host IDs.
+`v2-evaluation-repeat-results.json` records all 900 trajectory-policy executions.
+Failure codes are retained in metrics rather than hiding failed calls behind a final
+state match. A prior UUID/card-scanner false positive was reproduced and fixed; see
+`v2-verification.md` for the regression record.

package/docs/v2-optimization-plan.md

@@ -0,0 +1,23 @@
+# V2 本轮性能优化计划
+
+## 目标与不变项
+
+仅降低 Runtime SQLite 空闲轮询与积压领取开销。保留消融验证过的五种触发、默认阈值、完整 Turn、跨 Scope FIFO、持久 flush、lease fencing、隐私清理与文件回执恢复。无新依赖、无新增数据库字段、无模型调用。不以删功能或调大延迟换取速度。
+
+## 基线与执行顺序
+
+1. 先冻结本轮修改前的 dist，并保存 `v2-performance-baseline.json`；脚本在独立临时 dataRoot 测量，造数和 warmup 不计入耗时。
+2. 编辑实现前新增行为回归：Unicode/NUL 字节计数、跨 Scope 阈值及 FIFO、时钟回拨时按 ID 而非时间极值取首尾、flush 跨 Scope 尾批、maxTurns 极值、已清空正文不重复更新。
+3. 仅加查询索引和局部读取：空闲/待处理 state 索引、jobId 索引、活跃 job 部分索引、可清理 processed 正文部分索引；清理排除已 NULL 正文。
+4. claim 仅读取当前批容量的队首，count 在全队列判断，必要时 SQL UTF-8 BLOB 字节聚合；idle/maxWait 仍用末/首 ID 的入队时间。更新后查询剩余 pending 来决定是否清除 flush。
+5. 跑全量回归与 720 次消融；调度记录必须与优化前完全相同。最后进行新旧配对性能测试与独立复审。
+
+## 不做的优化
+
+不缓存队列总量，不迁移正文 schema，不跳过 lease/CAS/来源检查，不缓存或跳过永久回执验证。回执恢复虽然也是测量项，但本轮保持其安全行为，避免用弱化恢复校验换性能。
+
+## 验收
+
+新旧相同固定数据、相同批次与余量；至少 9 个实测样本并报告 median/P95 和小样本开销，不在 CI 对墙钟设脆弱阈值。大积压和大量历史的主要路径应有明确提升；若没有则撤回无收益改动。机器、Node、代码摘要及噪声边界写入结果，不把本机微基准当线上 SLA 或语义质量证据。
+
+本计划由主代理撰写，独立 critic lane 在实施前审查约束，实施后复核行为和证据。

package/docs/v2-performance-baseline-runtime.js.txt

@@ -0,0 +1,231 @@
+import { failureCode } from './errors.js';
+import { DatabaseSync } from "node:sqlite";
+import { lstatSync } from "node:fs";
+import { join } from "node:path";
+import { randomUUID, createHash } from "node:crypto";
+import { safeDirectory } from "./lock.js";
+/** Durable queue, not a reconstructible index. All mutating operations are synchronous. */
+export class RuntimeStore {
+    db;
+    #now;
+    #options;
+    #depth = 0;
+    constructor(dataRoot, options = {}) {
+        safeDirectory(dataRoot);
+        const path = join(dataRoot, "runtime.sqlite");
+        for (const suffix of ["", "-journal", "-wal", "-shm"]) {
+            try {
+                const stat = lstatSync(path + suffix);
+                if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1)
+                    throw new Error("Unsafe runtime path");
+            }
+            catch (error) {
+                if (error.code !== "ENOENT")
+                    throw error;
+            }
+        }
+        this.#now = options.now ?? Date.now;
+        this.#options = { turnThreshold: options.turnThreshold ?? 6, byteThreshold: options.byteThreshold ?? 16384, idleMs: options.idleMs ?? 120000, maxWaitMs: options.maxWaitMs ?? 600000, leaseMs: options.leaseMs ?? 120000, maxAttempts: options.maxAttempts ?? 5 };
+        for (const value of Object.values(this.#options))
+            if (!Number.isSafeInteger(value) || value <= 0)
+                throw new Error("Invalid runtime limit");
+        this.db = new DatabaseSync(path);
+        this.db.exec(`PRAGMA busy_timeout=5000; PRAGMA journal_mode=WAL; PRAGMA synchronous=FULL;
+      CREATE TABLE IF NOT EXISTS observations(id INTEGER PRIMARY KEY AUTOINCREMENT, sessionId TEXT NOT NULL, entryId TEXT NOT NULL, text TEXT, digest TEXT NOT NULL, scope TEXT NOT NULL, observedAt TEXT NOT NULL, source TEXT NOT NULL, state TEXT NOT NULL, enqueuedAt INTEGER NOT NULL, processedAt INTEGER, jobId TEXT, issue TEXT, UNIQUE(sessionId,entryId));
+      CREATE TABLE IF NOT EXISTS jobs(id TEXT PRIMARY KEY, token TEXT NOT NULL, generation INTEGER NOT NULL, state TEXT NOT NULL, expires INTEGER NOT NULL, attempts INTEGER NOT NULL, available INTEGER NOT NULL, issue TEXT);
+      CREATE TABLE IF NOT EXISTS document_versions(target TEXT PRIMARY KEY, hash TEXT NOT NULL);
+      CREATE TABLE IF NOT EXISTS associations(target TEXT NOT NULL, sourceId INTEGER NOT NULL, PRIMARY KEY(target,sourceId));
+      CREATE TABLE IF NOT EXISTS receipts(id TEXT PRIMARY KEY);
+      CREATE TABLE IF NOT EXISTS inputs(id TEXT PRIMARY KEY, sessionId TEXT NOT NULL, text TEXT NOT NULL, source TEXT NOT NULL, scope TEXT NOT NULL, queueKind TEXT NOT NULL, parentEntryId TEXT, used INTEGER NOT NULL DEFAULT 0);
+      CREATE TABLE IF NOT EXISTS deliveries(id INTEGER PRIMARY KEY AUTOINCREMENT, sessionId TEXT NOT NULL, text TEXT NOT NULL, digest TEXT NOT NULL, timestamp INTEGER NOT NULL, scope TEXT NOT NULL, source TEXT NOT NULL, state TEXT NOT NULL, UNIQUE(sessionId,digest,timestamp));
+      CREATE TABLE IF NOT EXISTS settings(key TEXT PRIMARY KEY,value INTEGER NOT NULL);`);
+    }
+    transaction(fn) {
+        if (this.#depth > 0)
+            return fn();
+        this.db.exec("BEGIN IMMEDIATE");
+        this.#depth++;
+        try {
+            const result = fn();
+            if (result instanceof Promise)
+                throw new Error("Runtime transaction must be synchronous");
+            this.db.exec("COMMIT");
+            return result;
+        }
+        catch (error) {
+            this.db.exec("ROLLBACK");
+            throw error;
+        }
+        finally {
+            this.#depth--;
+        }
+    }
+    enqueue(input) {
+        const digest = createHash("sha256").update(input.text).digest("hex");
+        return this.transaction(() => {
+            const existing = this.db.prepare("SELECT * FROM observations WHERE sessionId=? AND entryId=?").get(input.sessionId, input.entryId);
+            if (existing) {
+                if (existing.digest !== digest || existing.scope !== input.scope || existing.source !== input.source)
+                    throw new Error("Conflicting observation identity");
+                return existing;
+            }
+            const state = ["interactive", "rpc"].includes(input.source) ? "pending" : "quarantined";
+            const result = this.db.prepare("INSERT INTO observations(sessionId,entryId,text,digest,scope,observedAt,source,state,enqueuedAt) VALUES(?,?,?,?,?,?,?,?,?)").run(input.sessionId, input.entryId, input.text, digest, input.scope, input.observedAt, input.source, state, this.#now());
+            return this.db.prepare("SELECT * FROM observations WHERE id=?").get(result.lastInsertRowid);
+        });
+    }
+    hasWork() { return Boolean(this.db.prepare("SELECT 1 FROM observations WHERE state IN ('pending','claimed') LIMIT 1").get()); }
+    pending() { return this.db.prepare("SELECT * FROM observations WHERE state='pending' ORDER BY id").all(); }
+    context(observation) {
+        return this.db.prepare("SELECT * FROM observations WHERE id<? AND sessionId=? AND scope=? AND state='processed' AND text IS NOT NULL ORDER BY id DESC LIMIT 2").all(observation.id, observation.sessionId, observation.scope).reverse();
+    }
+    requestFlush() { this.db.prepare("INSERT INTO settings VALUES('flush',1) ON CONFLICT(key) DO UPDATE SET value=1").run(); }
+    claim(options = {}) {
+        if (options.maxTurns !== undefined && (!Number.isSafeInteger(options.maxTurns) || options.maxTurns < 1))
+            throw new Error("Invalid batch size");
+        return this.transaction(() => {
+            const now = this.#now();
+            const active = this.db.prepare("SELECT * FROM jobs WHERE state IN ('running','retry') ORDER BY rowid LIMIT 1").get();
+            if (active) {
+                if (active.state === "running" && Number(active.expires) > now || Number(active.available) > now)
+                    return null;
+                if (Number(active.attempts) >= this.#options.maxAttempts) {
+                    this.db.prepare("UPDATE jobs SET state='dead' WHERE id=?").run(active.id);
+                    this.db.prepare("UPDATE observations SET state='dead' WHERE jobId=?").run(active.id);
+                }
+                else {
+                    const token = randomUUID(), generation = Number(active.generation) + 1;
+                    this.db.prepare("UPDATE jobs SET token=?,generation=?,state='running',expires=?,attempts=attempts+1 WHERE id=?").run(token, generation, now + this.#options.leaseMs, active.id);
+                    return { id: String(active.id), token, generation, observations: this.db.prepare("SELECT * FROM observations WHERE jobId=? ORDER BY id").all(active.id) };
+                }
+            }
+            const pending = this.pending();
+            if (!pending.length) {
+                this.db.prepare("DELETE FROM settings WHERE key='flush'").run();
+                return null;
+            }
+            const flush = this.db.prepare("SELECT value FROM settings WHERE key='flush'").get();
+            if (!options.force && !flush?.value && pending.length < this.#options.turnThreshold && pending.reduce((n, o) => n + Buffer.byteLength(o.text ?? ""), 0) < this.#options.byteThreshold && now - pending[pending.length - 1].enqueuedAt < this.#options.idleMs && now - pending[0].enqueuedAt < this.#options.maxWaitMs)
+                return null;
+            const firstScope = pending[0].scope;
+            const observations = [];
+            for (const observation of pending) {
+                if (observation.scope !== firstScope || observations.length >= (options.maxTurns ?? this.#options.turnThreshold))
+                    break;
+                observations.push(observation);
+            }
+            const id = randomUUID(), token = randomUUID();
+            this.db.prepare("INSERT INTO jobs VALUES(?,?,1,'running',?,1,0,NULL)").run(id, token, now + this.#options.leaseMs);
+            for (const o of observations)
+                this.db.prepare("UPDATE observations SET state='claimed',jobId=? WHERE id=?").run(id, o.id);
+            if (observations.length === pending.length)
+                this.db.prepare("DELETE FROM settings WHERE key='flush'").run();
+            return { id, token, generation: 1, observations };
+        });
+    }
+    assertLease(job) {
+        const row = this.db.prepare("SELECT * FROM jobs WHERE id=? AND token=? AND generation=? AND state='running' AND expires>?").get(job.id, job.token, job.generation, this.#now());
+        if (!row)
+            throw new Error("STALE_LEASE");
+    }
+    trim(job, count) {
+        return this.transaction(() => { this.assertLease(job); if (!Number.isSafeInteger(count) || count < 1 || count > job.observations.length)
+            throw new Error("Invalid batch size"); for (const o of job.observations.slice(count))
+            this.db.prepare("UPDATE observations SET state='pending',jobId=NULL WHERE id=? AND jobId=?").run(o.id, job.id); return { ...job, observations: job.observations.slice(0, count) }; });
+    }
+    renew(job) { this.transaction(() => { this.assertLease(job); this.db.prepare("UPDATE jobs SET expires=? WHERE id=?").run(this.#now() + this.#options.leaseMs, job.id); }); }
+    finish(job, receipt) { this.transaction(() => { this.assertLease(job); if (receipt) {
+        if (receipt.jobId !== job.id || JSON.stringify([...receipt.observationIds].sort()) !== JSON.stringify(job.observations.map(o => o.id).sort()))
+            throw new Error("Receipt batch mismatch");
+        this.recoverReceipt(receipt);
+    }
+    else
+        this.#consume(job.id); }); }
+    #consume(id) { this.db.prepare("UPDATE observations SET state='processed',processedAt=? WHERE jobId=?").run(this.#now(), id); this.db.prepare("UPDATE jobs SET state='done' WHERE id=?").run(id); }
+    recoverReceipt(receipt) {
+        this.transaction(() => {
+            if (this.db.prepare("SELECT id FROM receipts WHERE id=?").get(receipt.jobId))
+                return;
+            const actual = this.db.prepare("SELECT id FROM observations WHERE jobId=? ORDER BY id").all(receipt.jobId).map(row => Number(row.id));
+            if (!actual.length || JSON.stringify(actual) !== JSON.stringify([...receipt.observationIds].sort((a, b) => a - b)))
+                throw new Error("Receipt batch mismatch");
+            for (const link of receipt.associations ?? [])
+                for (const sourceId of link.sourceIds)
+                    if (!this.db.prepare("SELECT id FROM observations WHERE id=?").get(sourceId))
+                        throw new Error("Receipt source unknown");
+            for (const id of receipt.observationIds) {
+                const row = this.db.prepare("SELECT jobId FROM observations WHERE id=?").get(id);
+                if (!row || row.jobId !== receipt.jobId)
+                    throw new Error("Receipt references unknown batch");
+            }
+            this.#consume(receipt.jobId);
+            for (const doc of receipt.documents ?? [])
+                this.db.prepare("INSERT INTO document_versions VALUES(?,?) ON CONFLICT(target) DO UPDATE SET hash=excluded.hash").run(doc.target, doc.after);
+            for (const target of receipt.removeTargets ?? [])
+                this.db.prepare("DELETE FROM associations WHERE target=?").run(target);
+            for (const link of receipt.associations ?? [])
+                for (const id of link.sourceIds)
+                    this.db.prepare("INSERT OR IGNORE INTO associations VALUES(?,?)").run(link.target, id);
+            for (const id of receipt.forgetSourceIds ?? []) {
+                this.db.prepare("UPDATE observations SET text=NULL WHERE id=? AND state='processed'").run(id);
+            }
+            this.db.prepare("INSERT INTO receipts VALUES(?)").run(receipt.jobId);
+        });
+    }
+    documentVersion(target) { const row = this.db.prepare("SELECT hash FROM document_versions WHERE target=?").get(target); return row ? String(row.hash) : null; }
+    documentSourceKeys(target) { return this.db.prepare("SELECT DISTINCT target FROM associations WHERE substr(target,1,?)=?").all(target.length + 1, target + ':').map(row => String(row.target)); }
+    sources(target) { return this.db.prepare("SELECT sourceId FROM associations WHERE target=? ORDER BY sourceId").all(target).map(row => Number(row.sourceId)); }
+    fail(job, error) { this.transaction(() => { this.assertLease(job); const row = this.db.prepare("SELECT attempts FROM jobs WHERE id=?").get(job.id); const dead = Number(row.attempts) >= this.#options.maxAttempts; this.db.prepare("UPDATE jobs SET state=?,available=?,issue=? WHERE id=?").run(dead ? "dead" : "retry", this.#now() + Math.min(600000, 1000 * 2 ** (Number(row.attempts) - 1)), failureCode(error), job.id); if (dead)
+        this.db.prepare("UPDATE observations SET state='dead' WHERE jobId=?").run(job.id); }); }
+    quarantine(job, observationId, issue) { this.transaction(() => { this.assertLease(job); if (!job.observations.some(o => o.id === observationId))
+        throw new Error("Unknown observation"); this.db.prepare("UPDATE observations SET state='quarantined',jobId=NULL,issue=? WHERE id=?").run(issue, observationId); this.db.prepare("UPDATE observations SET state='pending',jobId=NULL WHERE jobId=?").run(job.id); this.db.prepare("UPDATE jobs SET state='done' WHERE id=?").run(job.id); }); }
+    retry(jobId) { this.transaction(() => { this.db.prepare("UPDATE observations SET state='pending',jobId=NULL WHERE jobId=? AND state='dead'").run(jobId); this.db.prepare("UPDATE jobs SET state='done' WHERE id=? AND state='dead'").run(jobId); }); }
+    pruneProcessed(retentionMs = 7 * 86400000) { this.db.prepare("UPDATE observations SET text=NULL WHERE state='processed' AND processedAt<?").run(this.#now() - retentionMs); }
+    cancelInputs(sessionId) { this.db.prepare("DELETE FROM inputs WHERE sessionId=?").run(sessionId); }
+    stageInput(input) {
+        return this.transaction(() => {
+            const id = randomUUID(), kind = input.streamingBehavior ?? "direct";
+            const prior = kind === "direct" ? this.db.prepare("SELECT text FROM inputs WHERE sessionId=? AND queueKind='direct'").get(input.sessionId) : undefined;
+            // Direct preflight may be cancelled; queued steer/followUp are legal FIFO lists.
+            if (kind === "direct")
+                this.db.prepare("DELETE FROM inputs WHERE sessionId=? AND queueKind='direct'").run(input.sessionId);
+            let source = input.hasUnsupportedContent ? "unsupported_content" : prior?.text === input.text ? "ambiguous" : input.source;
+            const competing = this.db.prepare("SELECT source,scope FROM inputs WHERE sessionId=?").all(input.sessionId);
+            if (competing.some(row => row.source !== source || row.scope !== input.scope)) {
+                source = "ambiguous";
+                this.db.prepare("UPDATE inputs SET source='ambiguous' WHERE sessionId=?").run(input.sessionId);
+            }
+            this.db.prepare("INSERT INTO inputs(id,sessionId,text,source,scope,queueKind,parentEntryId) VALUES(?,?,?,?,?,?,?)").run(id, input.sessionId, input.text, source, input.scope, kind, input.parentEntryId ?? null);
+            return id;
+        });
+    }
+    delivered(sessionId, text, timestamp, hasUnsupportedContent = false) {
+        const digest = createHash("sha256").update(text).digest("hex");
+        this.transaction(() => {
+            if (this.db.prepare("SELECT id FROM deliveries WHERE sessionId=? AND digest=? AND timestamp=?").get(sessionId, digest, timestamp))
+                return;
+            // Pi drains direct delivery, steering, then follow-up queues. Never search old
+            // inputs by text: a cancelled global input must not authenticate project text.
+            const expected = this.db.prepare("SELECT * FROM inputs WHERE sessionId=? ORDER BY CASE queueKind WHEN 'direct' THEN 0 WHEN 'steer' THEN 1 ELSE 2 END, rowid LIMIT 1").get(sessionId);
+            const matches = expected?.text === text;
+            const source = hasUnsupportedContent ? "unsupported_content" : matches ? String(expected.source) : "ambiguous";
+            this.db.prepare("INSERT OR IGNORE INTO deliveries(sessionId,text,digest,timestamp,scope,source,state) VALUES(?,?,?,?,?,?,'unbound')").run(sessionId, text, digest, timestamp, expected?.scope ?? "global", source);
+            if (expected)
+                this.db.prepare("DELETE FROM inputs WHERE id=?").run(expected.id);
+        });
+    }
+    bind(sessionId, entries) { this.transaction(() => { const deliveries = this.db.prepare("SELECT * FROM deliveries WHERE sessionId=? AND state='unbound' ORDER BY id").all(sessionId); for (const delivery of deliveries) {
+        const matches = entries.filter(e => e.text === delivery.text && e.timestamp === delivery.timestamp);
+        if (matches.length > 1) {
+            this.db.prepare("UPDATE deliveries SET state='quarantined' WHERE id=?").run(delivery.id);
+            continue;
+        }
+        if (matches.length === 0)
+            continue;
+        this.enqueue({ sessionId, entryId: matches[0].id, text: String(delivery.text), scope: String(delivery.scope), source: String(delivery.source), observedAt: new Date(Number(delivery.timestamp)).toISOString() });
+        this.db.prepare("UPDATE deliveries SET state='bound',text='' WHERE id=?").run(delivery.id);
+    } }); }
+    status() { return { observations: this.db.prepare("SELECT state,COUNT(*) AS count FROM observations GROUP BY state").all(), jobs: this.db.prepare("SELECT id,state,attempts,issue FROM jobs ORDER BY rowid").all(), quarantinedDeliveries: Number(this.db.prepare("SELECT COUNT(*) AS n FROM deliveries WHERE state='quarantined'").get().n), unbound: Number(this.db.prepare("SELECT COUNT(*) AS n FROM deliveries WHERE state='unbound'").get().n) }; }
+    close() { this.db.close(); }
+}
+//# sourceMappingURL=runtime.js.map