@sqdr2/dsh-fusion 0.0.0-stage → 0.3.2

package/src/task/sqlite-store.ts

@@ -0,0 +1,386 @@
+import { setImmediate as yieldToLoop } from 'node:timers/promises'
+import { StatusIndex, StatusDataError, StatusPending } from './status-index.js'
+import { taskSummary } from '../host/history.js'
+import { DatabaseSync } from 'node:sqlite'
+import { mkdirSync } from 'node:fs'
+import { dirname } from 'node:path'
+import type { ArtifactRef, FusionEvent, OutboxRow, OutboxState, TaskId } from '../contracts.js'
+import { ArtifactId } from '../contracts.js'
+import { digestOf, sha256Hex } from '../digest.js'
+import { CHECKSUM_MISMATCH, EVENT_CONFLICT, FusionError, REVISION_CONFLICT, STORE_MIGRATION_REQUIRED, TASK_BUSY, TASK_NOT_FOUND } from '../errors.js'
+import { reduce, reduceAll } from './reducer.js'
+import type { PersistedTask, TaskState } from './state.js'
+import { decodeStoreSnapshot, STORE_PROJECTION_VERSION } from './store.js'
+import type { ArtifactRecord, DiskSnapshot, FusionStore } from './store.js'
+import { deletionVerdict, DeletionBlocked, recordedProcessId, unfinishedDocument } from './deletion.js'
+import type { DeletionBlocker } from './deletion.js'
+
+/** Durable families whose open row pins a task to a still-living process. */
+const FOREIGN_WRITER_FAMILIES = ['native-effect', 'native-approval', 'check-invocation'] as const
+
+/** `kill(pid, 0)` probes existence without signalling; EPERM still means the process exists. */
+function processAlive(pid: number): boolean {
+  try { process.kill(pid, 0); return true }
+  catch (error) { return (error as NodeJS.ErrnoException).code === 'EPERM' }
+}
+
+/**
+ * Every document family whose id embeds the owning task as its second segment
+ * (`family:<taskId>:...`). Deleting a task sweeps exactly these plus the documents
+ * that name it in `taskId`, and never touches the session-scoped families
+ * (`binding:`, `model-control:`, `sandbox-intent:`), which outlive any one task.
+ * Keep this list in step with the `writeDocument` call sites in src/host/.
+ */
+const TASK_DOCUMENT_FAMILIES = [
+  'acceptance-amendment', 'activity', 'activity-link', 'brief', 'check', 'check-invocation',
+  'context-recovery', 'context-request', 'effects', 'effects-receipt', 'keepalive',
+  'lead-direct', 'lead-takeover', 'native-approval', 'native-effect', 'native-usage', 'progress',
+  'restore-index', 'runtime', 'scope-expansion', 'task-activity', 'task-checkpoint', 'task-compaction',
+  'task-context', 'task-index', 'task-origin', 'text', 'worker-delivery', 'worker-notice', 'worker-request',
+  'workflow-check-repair', 'workflow-effect-denied', 'workflow-progress', 'workflow-replan', 'workflow-stop',
+  'workflow-worker-resume', 'usage', 'usage-index',
+] as const
+
+/** Durable Host backend. Every read is fresh; CAS and outbox writes share one transaction. */
+export interface DeletionAuthority {
+  /**
+   * Why this task still owns live work in this process, or `undefined` when it
+   * owns none. Only the Host can answer this: it holds the Agent, tool call,
+   * lease and stop registries. A caller without a Host passes nothing live.
+   */
+  liveReason(taskId: TaskId): DeletionBlocker | undefined
+}
+
+export class SqliteFusionStore implements FusionStore {
+  readonly #db: DatabaseSync
+  readonly #status: StatusIndex
+
+  constructor(readonly filename: string) {
+    if (filename !== ':memory:') mkdirSync(dirname(filename), { recursive: true })
+    this.#db = new DatabaseSync(filename)
+    try {
+      this.#db.exec('PRAGMA busy_timeout = 5000; PRAGMA foreign_keys = ON;')
+      const version = this.#db.prepare('PRAGMA user_version').get()?.user_version
+      if (version !== 0 && version !== 1) throw new FusionError(STORE_MIGRATION_REQUIRED, 'unknown Fusion database version')
+      if (version === 0) {
+        const count = this.#db.prepare("SELECT count(*) AS n FROM sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite_%'").get()?.n
+        if (count !== 0) throw new FusionError(STORE_MIGRATION_REQUIRED, 'unversioned nonempty Fusion database')
+        this.#db.exec(`BEGIN IMMEDIATE;
+          CREATE TABLE tasks (id TEXT PRIMARY KEY, snapshot TEXT NOT NULL);
+          CREATE TABLE artifacts (task_id TEXT NOT NULL REFERENCES tasks(id), digest TEXT NOT NULL, bytes BLOB NOT NULL, PRIMARY KEY(task_id, digest));
+          CREATE TABLE documents (id TEXT PRIMARY KEY, revision INTEGER NOT NULL, json TEXT NOT NULL, checksum TEXT NOT NULL);
+          PRAGMA user_version = 1;
+          COMMIT;`)
+      }
+      this.#db.exec('PRAGMA journal_mode = WAL; PRAGMA synchronous = FULL;')
+      this.#status = new StatusIndex(this.#db)
+    } catch (error) { this.#db.close(); throw error }
+  }
+
+  statusSnapshot<T>(read: (index: StatusIndex) => T, backfill = true): T {
+    for (;;) {
+      try {
+        const result = this.#transaction(() => {
+          try { return { value: read(this.#status) } } catch (error) {
+            // Keep invalid-row markers durable rather than retrying their backfill on every poll.
+            if (error instanceof StatusDataError) return { error }
+            throw error
+          }
+        })
+        if ('error' in result) throw result.error
+        return result.value
+      } catch (error) {
+        if (!(error instanceof StatusPending) || !backfill) throw error
+        while (this.#transaction(() => this.#status.flushBatch(error.task))) { /* release the writer lock between batches */ }
+      }
+    }
+  }
+
+  /** HTTP reads yield between committed batches; cancellation retains resumable progress. */
+  async statusSnapshotAsync<T>(read: (index: StatusIndex) => T, signal?: AbortSignal): Promise<T> {
+    for (;;) {
+      signal?.throwIfAborted()
+      try { return this.statusSnapshot(read, false) } catch (error) {
+        if (!(error instanceof StatusPending)) throw error
+        this.#transaction(() => this.#status.flushBatch(error.task))
+        await yieldToLoop(undefined, { signal })
+      }
+    }
+  }
+
+  close(): void { this.#db.close() }
+
+  listTaskIds(): readonly TaskId[] {
+    return this.#db.prepare('SELECT id FROM tasks ORDER BY id').all().map(row => {
+      if (typeof row.id !== 'string') throw new FusionError(STORE_MIGRATION_REQUIRED, 'invalid task identity')
+      return row.id as TaskId
+    })
+  }
+
+  listDocumentIds(prefix: string): readonly string[] {
+    return this.#db.prepare('SELECT id FROM documents WHERE substr(id, 1, ?) = ? ORDER BY id').all(prefix.length, prefix).map(row => {
+      if (typeof row.id !== 'string') throw new FusionError(STORE_MIGRATION_REQUIRED, 'invalid document identity')
+      return row.id
+    })
+  }
+
+  load(taskId: TaskId): TaskState | undefined { return this.#read(taskId)?.persisted.state }
+
+  /**
+   * Remove one task record and everything that belongs to it.
+   *
+   * Liveness comes from `authority`, the in-process Host that owns the Agents,
+   * tool calls, leases and stops, plus durable rows a *different living* process
+   * left open. The persisted phase is deliberately not consulted: it describes
+   * where an interrupted process stopped, not whether anything still runs. See
+   * `deletion.ts` for why that distinction decides this bug.
+   */
+  deleteTask(taskId: string, authority: DeletionAuthority): void {
+    this.#transaction(() => {
+      const current = this.load(taskId as TaskId)
+      if (!current) throw new FusionError(TASK_NOT_FOUND, 'task not found')
+      const verdict = deletionVerdict({
+        live: authority.liveReason(current.taskId),
+        foreign: this.#foreignWriters(current.taskId),
+      })
+      if (!verdict.allowed) throw new DeletionBlocked(verdict.blocker, verdict.detail)
+      this.#db.prepare('DELETE FROM artifacts WHERE task_id = ?').run(taskId)
+      this.#db.prepare('DELETE FROM tasks WHERE id = ?').run(taskId)
+
+      // Documents that belong to this task either carry it as the second id segment
+      // (`family:<taskId>:...`) or hold it in a documented field. Both are swept, so a
+      // deleted task cannot leave a report, evidence row or progress window behind to
+      // be re-read by a later task that reuses nothing but the same id shape.
+      // Session-scoped documents (binding:, model-control:, sandbox-intent:) are never
+      // deleted here: they belong to the conversation, not to the task.
+      for (const prefix of TASK_DOCUMENT_FAMILIES) {
+        // Both the two-segment form (`task-index:<taskId>`) and the rest (`usage:<taskId>:<id>`).
+        this.#db.prepare("DELETE FROM documents WHERE id = ? || ':' || ? OR id LIKE ? || ':' || ? || ':%'")
+          .run(prefix, taskId, prefix, taskId)
+      }
+      this.#db.prepare('DELETE FROM documents WHERE id = ?').run(taskId)
+      this.#db.prepare(`
+        DELETE FROM documents
+        WHERE id NOT LIKE 'binding:%' AND id NOT LIKE 'model-control:%' AND id NOT LIKE 'sandbox-intent:%'
+          AND (json_extract(json, '$.taskId') = ? OR json_extract(json, '$.ticket.subject.taskId') = ?)
+      `).run(taskId, taskId)
+
+      this.#db.prepare('DELETE FROM fusion_status_facts_v1 WHERE task = ?').run(taskId)
+      this.#db.prepare('DELETE FROM fusion_status_totals_v1 WHERE task = ?').run(taskId)
+      for (const kind of TASK_DOCUMENT_FAMILIES) {
+        this.#db.prepare("DELETE FROM fusion_status_dirty_v1 WHERE id LIKE ? || ':' || ? || ':%'").run(kind, taskId)
+      }
+
+      const bindingDocs = this.#db.prepare("SELECT id, json, revision FROM documents WHERE id LIKE 'binding:%'").all()
+      for (const row of bindingDocs) {
+        if (typeof row.json === 'string' && typeof row.revision === 'number') {
+          try {
+            const data = JSON.parse(row.json) as { taskId?: unknown; selected?: boolean }
+            if (data.taskId === taskId && data.selected) {
+              const updated = { ...data, selected: false }
+              const json = JSON.stringify(updated)
+              const revision = row.revision + 1
+              this.#db.prepare('UPDATE documents SET revision = ?, json = ?, checksum = ? WHERE id = ?')
+                .run(revision, json, sha256Hex(Buffer.from(json)), row.id as string)
+            }
+          } catch { /* ignore */ }
+        }
+      }
+    })
+  }
+
+  /**
+   * Durable rows this task left unfinished under a *different* process that is
+   * still alive. A row owned by this process is not evidence: the in-process
+   * authority has already reported whether anything here is live, so such a row
+   * is residue from a call that was interrupted, not a running one.
+   */
+  #foreignWriters(taskId: TaskId): readonly string[] {
+    const found: string[] = []
+    for (const family of FOREIGN_WRITER_FAMILIES) {
+      for (const id of this.listDocumentIds(`${family}:${taskId}:`)) {
+        const value = this.readDocument(id)?.value
+        if (!unfinishedDocument(family, value)) continue
+        const pid = recordedProcessId(value)
+        // No recorded owner, or this process: the in-process authority decided.
+        if (pid === undefined || pid === process.pid) continue
+        if (!processAlive(pid)) continue
+        found.push(`${family} owned by pid ${pid}`)
+      }
+    }
+    return found
+  }
+
+  events(taskId: TaskId): readonly FusionEvent[] { return this.#require(taskId).persisted.events }
+
+  replay(taskId: TaskId): TaskState { return reduceAll(this.#require(taskId).persisted.events) }
+
+  create(event: Extract<FusionEvent, { type: 'task/created' }>): TaskState {
+    return this.#transaction(() => {
+      if (this.#read(event.taskId)) throw new FusionError(EVENT_CONFLICT, 'task exists')
+      const state = reduce(undefined, event)
+      this.#write(event.taskId, { state, events: [event], outbox: [] }, [])
+      return state
+    })
+  }
+
+  transact(taskId: TaskId, expectedSeq: number, mutate: (current: PersistedTask) => {
+    events?: readonly FusionEvent[]; outbox?: readonly OutboxRow[]
+  }): TaskState {
+    return this.#transaction(() => {
+      const current = this.#require(taskId)
+      if (current.persisted.state.seq !== expectedSeq) throw new FusionError(EVENT_CONFLICT, 'task sequence changed')
+      const patch = mutate(structuredClone(current.persisted))
+      return this.#apply(taskId, current, patch.events ?? [], patch.outbox ?? current.persisted.outbox)
+    })
+  }
+
+  append(taskId: TaskId, expectedRevision: number, events: readonly FusionEvent[]): TaskState {
+    return this.#transaction(() => {
+      const current = this.#require(taskId)
+      if (current.persisted.state.revision !== expectedRevision) throw new FusionError(REVISION_CONFLICT, 'task revision changed')
+      return this.#apply(taskId, current, events, current.persisted.outbox)
+    })
+  }
+
+  putArtifact(taskId: TaskId, bytes: Uint8Array, mediaType: string): ArtifactRef {
+    return this.putArtifacts(taskId, [{ bytes, mediaType }])[0]
+  }
+
+  /** One atomic metadata update for a bounded workspace evidence batch. */
+  putArtifacts(taskId: TaskId, inputs: readonly { bytes: Uint8Array; mediaType: string }[]): ArtifactRef[] {
+    return this.#transaction(() => {
+      const current = this.#require(taskId)
+      const records = new Map(current.artifacts.map(record => [record.digest, record]))
+      const insert = this.#db.prepare('INSERT OR IGNORE INTO artifacts(task_id, digest, bytes) VALUES (?, ?, ?)')
+      const result = inputs.map(({ bytes, mediaType }) => {
+        const digest = sha256Hex(bytes)
+        const record: ArtifactRecord = {
+          id: ArtifactId(digest), digest, ownerTaskId: taskId, mediaType, bytes: bytes.byteLength,
+          storageRef: `sqlite:${taskId}:${digest}`,
+        }
+        insert.run(taskId, digest, bytes)
+        records.set(digest, record)
+        return record
+      })
+      this.#write(taskId, current.persisted, [...records.values()])
+      return result
+    })
+  }
+
+  /** Load owned evidence bytes and verify content before trusting the reference. */
+  readArtifact(taskId: TaskId, digest: string): Uint8Array {
+    return this.readArtifacts(taskId, [digest])[0]
+  }
+
+  readArtifacts(taskId: TaskId, digests: readonly string[]): Uint8Array[] {
+    const records = new Map<string, ArtifactRecord>(this.artifacts(taskId).map(record => [record.digest, record]))
+    const select = this.#db.prepare('SELECT bytes FROM artifacts WHERE task_id = ? AND digest = ?')
+    return digests.map(digest => {
+      const record = records.get(digest), row = select.get(taskId, digest)
+      if (!record || !(row?.bytes instanceof Uint8Array)) throw new FusionError(EVENT_CONFLICT, 'artifact not owned by task')
+      if (sha256Hex(row.bytes) !== digest || row.bytes.byteLength !== record.bytes) throw new FusionError(CHECKSUM_MISMATCH, 'corrupt artifact')
+      return row.bytes
+    })
+  }
+
+  prepareOutbox(row: OutboxRow): OutboxRow {
+    return this.#transaction(() => {
+      const current = this.#require(row.taskId)
+      const existing = current.persisted.outbox.find(item => item.operationId === row.operationId)
+      if (existing) return existing
+      const prepared: OutboxRow = { ...row, state: 'prepared' }
+      this.#write(row.taskId, { ...current.persisted, outbox: [...current.persisted.outbox, prepared] }, current.artifacts)
+      return prepared
+    })
+  }
+
+  advanceOutbox(taskId: TaskId, operationId: string, from: OutboxState, to: OutboxState, patch: Partial<OutboxRow> = {}): OutboxRow {
+    return this.#transaction(() => {
+      const current = this.#require(taskId)
+      const prior = current.persisted.outbox.find(item => item.operationId === operationId)
+      if (!prior || prior.state !== from) throw new FusionError(EVENT_CONFLICT, 'outbox state changed or missing')
+      if ((patch.operationId !== undefined && patch.operationId !== prior.operationId)
+        || (patch.taskId !== undefined && patch.taskId !== prior.taskId)) throw new FusionError(EVENT_CONFLICT, 'outbox identity is immutable')
+      const next: OutboxRow = { ...prior, ...patch, state: to }
+      this.#write(taskId, { ...current.persisted, outbox: current.persisted.outbox.map(item => item.operationId === operationId ? next : item) }, current.artifacts)
+      return next
+    })
+  }
+
+  outbox(taskId: TaskId): readonly OutboxRow[] { return this.#require(taskId).persisted.outbox }
+  artifacts(taskId: TaskId): readonly ArtifactRecord[] { return this.#require(taskId).artifacts }
+
+  /** Host binding / usage documents require caller-side schema validation after loading. */
+  readDocument(id: string): { revision: number; value: unknown } | undefined {
+    const row = this.#db.prepare('SELECT revision, json, checksum FROM documents WHERE id = ?').get(id)
+    if (!row) return undefined
+    if (typeof row.json !== 'string' || typeof row.revision !== 'number') throw new FusionError(STORE_MIGRATION_REQUIRED, 'invalid Host document')
+    if (sha256Hex(Buffer.from(row.json)) !== row.checksum) throw new FusionError(CHECKSUM_MISMATCH, 'corrupt Host document')
+    return { revision: row.revision, value: JSON.parse(row.json) as unknown }
+  }
+
+  /** Compare-and-swap prevents an old Host instance overwriting a newer selection or bill. */
+  writeDocument(id: string, expectedRevision: number, value: unknown): number {
+    return this.#transaction(() => this.#writeDocument(id, expectedRevision, value))
+  }
+
+  writeDocuments(rows: readonly { id: string; expectedRevision: number; value: unknown }[]): number[] {
+    return this.#transaction(() => rows.map(row => this.#writeDocument(row.id, row.expectedRevision, row.value)))
+  }
+
+  #writeDocument(id: string, expectedRevision: number, value: unknown): number {
+    const current = this.readDocument(id)
+    if ((current?.revision ?? 0) !== expectedRevision) throw new FusionError(REVISION_CONFLICT, 'Host document revision changed')
+    const json = JSON.stringify(value)
+    if (json === undefined) throw new Error('Host document must be JSON serializable')
+    const revision = expectedRevision + 1
+    this.#db.prepare('INSERT INTO documents VALUES (?, ?, ?, ?) ON CONFLICT(id) DO UPDATE SET revision=excluded.revision, json=excluded.json, checksum=excluded.checksum')
+      .run(id, revision, json, sha256Hex(Buffer.from(json)))
+    this.#status.sync(id)
+    return revision
+  }
+
+  #apply(taskId: TaskId, current: DiskSnapshot, events: readonly FusionEvent[], outbox: readonly OutboxRow[]): TaskState {
+    let state = current.persisted.state
+    const nextEvents = [...current.persisted.events]
+    for (const event of events) {
+      if (state.appliedEventIds.includes(event.id)) continue
+      state = reduce(state, event)
+      nextEvents.push(event)
+    }
+    this.#write(taskId, { state, events: nextEvents, outbox }, current.artifacts)
+    return state
+  }
+
+  #read(taskId: TaskId): DiskSnapshot | undefined {
+    const row = this.#db.prepare('SELECT snapshot FROM tasks WHERE id = ?').get(taskId)
+    if (!row) return undefined
+    if (typeof row.snapshot !== 'string') throw new FusionError(STORE_MIGRATION_REQUIRED, 'invalid task snapshot')
+    return decodeStoreSnapshot(row.snapshot, taskId)
+  }
+
+  #require(taskId: TaskId): DiskSnapshot {
+    const current = this.#read(taskId)
+    if (!current) throw new FusionError(EVENT_CONFLICT, `unknown task ${taskId}`)
+    return current
+  }
+
+  #write(taskId: TaskId, persisted: PersistedTask, artifacts: readonly ArtifactRecord[]): void {
+    const snapshot: DiskSnapshot = { projectionVersion: STORE_PROJECTION_VERSION, persisted, artifacts, checksum: digestOf({ persisted, artifacts }) }
+    this.#db.prepare('INSERT INTO tasks VALUES (?, ?) ON CONFLICT(id) DO UPDATE SET snapshot=excluded.snapshot').run(taskId, JSON.stringify(snapshot))
+    const indexId = `task-index:${taskId}`
+    const prior = this.readDocument(indexId), summary = taskSummary(persisted.state, persisted.events[0]!.createdAt, persisted.events.at(-1)!.createdAt)
+    const priorTitle = (prior?.value as { title?: unknown } | undefined)?.title
+    if (!persisted.state.currentWorkOrder && typeof priorTitle === 'string') summary.title = priorTitle
+    this.#writeDocument(indexId, prior?.revision ?? 0, summary)
+  }
+
+  #transaction<T>(body: () => T): T {
+    this.#db.exec('BEGIN IMMEDIATE')
+    try { const result = body(); this.#db.exec('COMMIT'); return result } catch (error) {
+      this.#db.exec('ROLLBACK')
+      throw error
+    }
+  }
+}

package/src/task/state.ts

@@ -0,0 +1,72 @@
+import type {
+  ControlState,
+  Digest,
+  ExecutionIntent,
+  ExplorationReport,
+  FusionEvent,
+  LogicalApproval,
+  OutboxRow,
+  Phase,
+  ReviewGate,
+  ReviewReadinessReceipt,
+  ReviewResultV2,
+  ReviewTicket,
+  RunSelection,
+  SessionId,
+  SnapshotId,
+  TaskId,
+  VerificationLevel,
+  WorkOrder,
+  WorkerReport,
+  WriteLease,
+} from '../contracts.js'
+
+export interface AcceptedReview {
+  readonly ticket: ReviewTicket
+  readonly resultDigest: Digest
+}
+
+export interface TaskState {
+  readonly schemaVersion: 1
+  readonly taskId: TaskId
+  readonly revision: number
+  readonly seq: number
+  readonly phase: Phase
+  readonly parent: SessionId
+  readonly selection: RunSelection
+  readonly profileDigest?: Digest
+  readonly intent?: ExecutionIntent
+  readonly reservedChild?: SessionId
+  readonly acceptedChild?: SessionId
+  readonly acceptedMessageId?: string
+  readonly currentWorkOrder?: WorkOrder
+  readonly exploration?: ExplorationReport
+  readonly candidateReport?: WorkerReport
+  readonly validatedReport?: WorkerReport
+  readonly validatedReceipt?: ReviewReadinessReceipt
+  readonly activeReviewTicket?: ReviewTicket
+  readonly reviewResult?: ReviewResultV2
+  readonly reviewResultDigest?: Digest
+  readonly acceptedReview?: AcceptedReview
+  readonly reviewGeneration: number
+  readonly ignoredReviewResults: readonly ReviewResultV2[]
+  readonly staleValidations: readonly { readonly reportDigest: Digest; readonly reason: string }[]
+  /** Candidate if unvalidated, otherwise the validated report. Compatibility projection. */
+  readonly lastReport?: WorkerReport
+  readonly reviewGate?: ReviewGate
+  readonly verification: VerificationLevel
+  readonly pendingApprovalIds: readonly string[]
+  readonly pendingApprovals: Readonly<Record<string, LogicalApproval>>
+  readonly control: ControlState
+  readonly outcomeUnknown: boolean
+  readonly resumePhase?: Phase
+  readonly lease?: WriteLease
+  readonly lastSnapshot?: SnapshotId
+  readonly appliedEventIds: readonly string[]
+}
+
+export interface PersistedTask {
+  readonly state: TaskState
+  readonly events: readonly FusionEvent[]
+  readonly outbox: readonly OutboxRow[]
+}

package/src/task/status-index.ts

@@ -0,0 +1,198 @@
+import type { DatabaseSync, StatementSync } from 'node:sqlite'
+import { sha256Hex } from '../digest.js'
+import { projectLedger, restoreLedger } from '../usage/ledger.js'
+import type { NativeUsageRecord } from '../host/native-usage.js'
+import type { FusionStatus, RoleUsage } from '../status.js'
+
+type TaskStatus = NonNullable<FusionStatus['task']>
+const metrics = ['calls', 'finalCalls', 'provisionalCalls', 'unreportedCalls', 'compactionCalls', 'keepaliveCalls',
+  'inputTokens', 'inputReported', 'cacheReadTokens', 'cacheReadReported', 'outputTokens', 'outputReported', 'unsettled', 'checking', 'workerConversations'] as const
+type Metric = typeof metrics[number]
+type Totals = Record<Metric, number>
+const empty = (): Totals => Object.fromEntries(metrics.map(key => [key, 0])) as Totals
+const kinds = ['usage', 'native-effect', 'context-request', 'check-invocation'] as const
+const relevant = (id: string) => kinds.some(kind => id.startsWith(`${kind}:`))
+const condition = (ref: string) => kinds.map(kind => `${ref}.id GLOB '${kind}:*'`).join(' OR ')
+
+export class StatusDataError extends Error {}
+export class StatusPending extends Error {
+  constructor(readonly task: string) { super('Status projection needs backfill') }
+}
+
+/** Rebuildable read model. Triggers also track writes/deletes by older plugin processes. */
+export class StatusIndex {
+  readonly #statements = new Map<string, StatementSync>()
+  constructor(readonly db: DatabaseSync) {
+    db.exec('BEGIN IMMEDIATE')
+    try {
+      const tablesExist = db.prepare("SELECT count(*) AS n FROM sqlite_master WHERE type='table' AND name IN ('fusion_status_dirty_v1','fusion_status_facts_v1','fusion_status_totals_v1')").get()?.n === 3
+      const triggersExist = db.prepare("SELECT count(*) AS n FROM sqlite_master WHERE type='trigger' AND name IN ('fusion_status_insert_v1','fusion_status_update_v1','fusion_status_delete_v1')").get()?.n === 3
+      const exists = tablesExist && triggersExist
+      if (!exists) db.exec('DROP TABLE IF EXISTS fusion_status_dirty_v1; DROP TABLE IF EXISTS fusion_status_facts_v1; DROP TABLE IF EXISTS fusion_status_totals_v1;')
+      db.exec(`
+        CREATE TABLE IF NOT EXISTS fusion_status_dirty_v1 (id TEXT PRIMARY KEY);
+        CREATE TABLE IF NOT EXISTS fusion_status_facts_v1 (
+          id TEXT PRIMARY KEY, task TEXT NOT NULL, kind TEXT NOT NULL, role TEXT NOT NULL,
+          stamp TEXT NOT NULL, session TEXT NOT NULL, active INTEGER NOT NULL, error TEXT,
+          preview TEXT NOT NULL, ${metrics.map(key => `${key} INTEGER NOT NULL`).join(',')});
+        CREATE INDEX IF NOT EXISTS fusion_status_recent_v1 ON fusion_status_facts_v1(task,kind,stamp DESC,id);
+        CREATE INDEX IF NOT EXISTS fusion_status_context_v1 ON fusion_status_facts_v1(task,role,stamp DESC,id) WHERE kind='context-request';
+        CREATE INDEX IF NOT EXISTS fusion_status_active_v1 ON fusion_status_facts_v1(task,session) WHERE active=1;
+        CREATE INDEX IF NOT EXISTS fusion_status_errors_v1 ON fusion_status_facts_v1(id) WHERE error IS NOT NULL;
+        CREATE TABLE IF NOT EXISTS fusion_status_totals_v1 (
+          task TEXT NOT NULL, role TEXT NOT NULL, ${metrics.map(key => `${key} INTEGER NOT NULL`).join(',')}, PRIMARY KEY(task,role));
+        CREATE TRIGGER IF NOT EXISTS fusion_status_insert_v1 AFTER INSERT ON documents WHEN ${condition('NEW')}
+          BEGIN INSERT INTO fusion_status_dirty_v1 VALUES (NEW.id) ON CONFLICT(id) DO NOTHING; END;
+        CREATE TRIGGER IF NOT EXISTS fusion_status_update_v1 AFTER UPDATE ON documents WHEN ${condition('NEW')} OR ${condition('OLD')}
+          BEGIN INSERT INTO fusion_status_dirty_v1 VALUES (OLD.id) ON CONFLICT(id) DO NOTHING; INSERT INTO fusion_status_dirty_v1 VALUES (NEW.id) ON CONFLICT(id) DO NOTHING; END;
+        CREATE TRIGGER IF NOT EXISTS fusion_status_delete_v1 AFTER DELETE ON documents WHEN ${condition('OLD')}
+          BEGIN INSERT INTO fusion_status_dirty_v1 VALUES (OLD.id) ON CONFLICT(id) DO NOTHING; END;
+      `)
+      if (!exists) db.exec(`INSERT OR IGNORE INTO fusion_status_dirty_v1 SELECT id FROM documents WHERE ${condition('documents')}`)
+      db.exec('COMMIT')
+    } catch (error) { db.exec('ROLLBACK'); throw error }
+  }
+
+  #sql(sql: string): StatementSync {
+    let statement = this.#statements.get(sql)
+    if (!statement) { statement = this.db.prepare(sql); this.#statements.set(sql, statement) }
+    return statement
+  }
+
+  /** Call inside the document transaction, after the source row is written. */
+  sync(id: string): void {
+    if (!relevant(id)) { this.#sql('DELETE FROM fusion_status_dirty_v1 WHERE id=?').run(id); return }
+    const prior = this.#sql('SELECT * FROM fusion_status_facts_v1 WHERE id=?').get(id)
+    if (prior) this.#add(String(prior.task), String(prior.role), prior as Totals, -1)
+    this.#sql('DELETE FROM fusion_status_facts_v1 WHERE id=?').run(id)
+    const source = this.#sql('SELECT json,checksum FROM documents WHERE id=?').get(id)
+    if (source) {
+      let task = '', role = 'other', stamp = '', session = '', active = 0, error: string | null = null, preview: unknown = {}
+      const kind = id.slice(0, id.indexOf(':')), counts = empty()
+      try {
+        if (typeof source.json !== 'string' || sha256Hex(Buffer.from(source.json)) !== source.checksum) throw new Error('corrupt Host document')
+        const row = JSON.parse(source.json)
+        task = kind === 'check-invocation' ? row.evidence?.taskId : row.taskId
+        if (typeof task !== 'string' || !id.startsWith(`${kind}:${task}:`) || (kind !== 'check-invocation' && row.schemaVersion !== 1)) throw new Error('Fusion 状态记录需要检查')
+        role = row.role === 'lead' || row.role === 'worker' ? row.role : 'other'
+        if (kind === 'usage') {
+          const value = row as NativeUsageRecord, projection = projectLedger(restoreLedger(value.ledger))
+          counts.calls = 1
+          counts.workerConversations = Number(value.role === 'worker' && (value.purpose === undefined || value.purpose === 'conversation'))
+          counts[projection.authority === 'final' ? 'finalCalls' : projection.authority === 'provisional' ? 'provisionalCalls' : 'unreportedCalls'] = 1
+          counts.compactionCalls = Number(value.purpose === 'compaction'); counts.keepaliveCalls = Number(value.purpose === 'cache-keepalive')
+          for (const [field, count] of [['input', projection.bill?.uncachedInput], ['cacheRead', projection.bill?.cacheRead], ['output', projection.bill?.output]] as const) {
+            if (count?.state === 'known') { counts[`${field}Tokens`] = count.tokens; counts[`${field}Reported`] = 1 }
+          }
+          stamp = value.startedAt; session = value.sessionId
+          active = Number(value.purpose === 'conversation' && value.endedAt === null)
+          if (!active) session = ''
+          preview = { role: value.role, purpose: value.purpose, provider: value.ledger.key.provider, model: value.ledger.key.model,
+            outcome: value.outcome, authority: projection.authority }
+        } else if (kind === 'native-effect') {
+          stamp = row.startedAt; counts.unsettled = Number(row.state === 'dispatch-started' || row.state === 'outcome-unknown')
+          preview = { role: row.role, name: row.toolName, state: row.state, failed: row.nativeIsError === true }
+        } else if (kind === 'context-request') {
+          stamp = row.checkedAt
+          preview = { role: row.role, purpose: row.purpose, inputTokens: row.measurement.inputTokens, budget: row.budget,
+            quality: row.measurement.quality, admitted: row.admitted, checkedAt: row.checkedAt }
+        } else counts.checking = Number(row.evidence.state === 'started')
+        if (typeof stamp !== 'string' || typeof session !== 'string') throw new Error('Fusion 状态记录需要检查')
+      } catch (failure) {
+        error = failure instanceof Error ? failure.message : String(failure)
+        task = ''; role = 'other'; stamp = ''; session = ''; active = 0; preview = {}; Object.assign(counts, empty())
+      }
+      this.#sql(`INSERT INTO fusion_status_facts_v1 VALUES (${Array(9 + metrics.length).fill('?').join(',')})`)
+        .run(id, task, kind, role, stamp, session, active, error, JSON.stringify(preview), ...metrics.map(key => counts[key]))
+      this.#add(task, role, counts, 1)
+    }
+    this.#sql('DELETE FROM fusion_status_dirty_v1 WHERE id=?').run(id)
+  }
+
+  #add(task: string, role: string, value: Totals, sign: number): void {
+    this.#sql(`INSERT INTO fusion_status_totals_v1 VALUES (${Array(2 + metrics.length).fill('?').join(',')})
+      ON CONFLICT(task,role) DO UPDATE SET ${metrics.map(key => `${key}=${key}+excluded.${key}`).join(',')}`)
+      .run(task, role, ...metrics.map(key => sign * Number(value[key])))
+  }
+
+  /** Each batch is its own transaction, so a legacy backfill does not monopolize the writer lock. */
+  flushBatch(task: string): boolean {
+    let changed = false
+    for (const kind of kinds) {
+      const batch = this.#sql('SELECT id FROM fusion_status_dirty_v1 WHERE id>=? AND id<? ORDER BY id LIMIT 256')
+        .all(`${kind}:${task}:`, `${kind}:${task};`)
+      for (const row of batch) { this.sync(String(row.id)); changed = true }
+    }
+    return changed
+  }
+
+  #ready(task: string): void {
+    for (const kind of kinds) {
+      if (this.#sql('SELECT id FROM fusion_status_dirty_v1 WHERE id>=? AND id<? LIMIT 1').get(`${kind}:${task}:`, `${kind}:${task};`)) {
+        throw new StatusPending(task)
+      }
+    }
+  }
+
+  /** Bounded memory even for a legacy database; the surrounding transaction is atomic. */
+  flush(task?: string): void {
+    const ranges = task === undefined ? [undefined] : kinds.map(kind => [`${kind}:${task}:`, `${kind}:${task};`])
+    for (const range of ranges) for (;;) {
+      const batch = range
+        ? this.#sql('SELECT id FROM fusion_status_dirty_v1 WHERE id>=? AND id<? ORDER BY id LIMIT 256').all(...range)
+        : this.#sql('SELECT id FROM fusion_status_dirty_v1 ORDER BY id LIMIT 256').all()
+      if (!batch.length) break
+      for (const row of batch) this.sync(String(row.id))
+    }
+  }
+
+  rebuild(): void {
+    this.db.exec(`DELETE FROM fusion_status_facts_v1; DELETE FROM fusion_status_totals_v1;
+      INSERT OR IGNORE INTO fusion_status_dirty_v1 SELECT id FROM documents WHERE ${condition('documents')}`)
+    this.flush()
+  }
+
+  #validate(task: string): void {
+    for (const kind of kinds) {
+      const prefix = `${kind}:${task}:`
+      const error = this.#sql('SELECT error FROM fusion_status_facts_v1 WHERE error IS NOT NULL AND id>=? AND id<? LIMIT 1').get(prefix, `${kind}:${task};`)
+      if (error) throw new StatusDataError(String(error.error))
+    }
+  }
+
+  read(task: string): Pick<TaskStatus, 'usage' | 'requests' | 'tools' | 'contexts' | 'unsettledTools'> & { checking: boolean } {
+    this.#ready(task)
+    this.#validate(task)
+    const total = empty(), roles = { lead: empty(), worker: empty() }
+    for (const row of this.#sql('SELECT * FROM fusion_status_totals_v1 WHERE task=?').all(task)) {
+      for (const key of metrics) total[key] += Number(row[key])
+      if (row.role === 'lead' || row.role === 'worker') roles[row.role] = row as Totals
+    }
+    const own = (value: Totals): RoleUsage => ({ calls: value.calls,
+      input: { knownTokens: value.inputTokens, reportedRequests: value.inputReported, totalRequests: value.calls },
+      cacheRead: { knownTokens: value.cacheReadTokens, reportedRequests: value.cacheReadReported, totalRequests: value.calls },
+      output: { knownTokens: value.outputTokens, reportedRequests: value.outputReported, totalRequests: value.calls } })
+    const recent = (kind: string, limit: number) => this.#sql('SELECT id,stamp,preview FROM fusion_status_facts_v1 WHERE task=? AND kind=? ORDER BY stamp DESC,id LIMIT ?')
+      .all(task, kind, limit).map(row => ({ ...JSON.parse(String(row.preview)), id: String(row.id), startedAt: String(row.stamp) }))
+    return { usage: { ...own(total), finalCalls: total.finalCalls, provisionalCalls: total.provisionalCalls,
+      unreportedCalls: total.unreportedCalls, compactionCalls: total.compactionCalls, keepaliveCalls: total.keepaliveCalls,
+      actualBilledUsd: null, upstreamHttpCalls: null, byRole: { lead: own(roles.lead), worker: own(roles.worker) } },
+      requests: recent('usage', 12), tools: recent('native-effect', 8),
+      contexts: (['lead', 'worker'] as const).flatMap(role => {
+        const row = this.#sql("SELECT preview FROM fusion_status_facts_v1 WHERE task=? AND kind='context-request' AND role=? ORDER BY stamp DESC,id LIMIT 1").get(task, role)
+        return row ? [JSON.parse(String(row.preview))] : []
+      }), unsettledTools: total.unsettled, checking: total.checking > 0 }
+  }
+
+  workerConversations(task: string): number {
+    this.#ready(task)
+    this.#validate(task)
+    return Number(this.#sql("SELECT workerConversations FROM fusion_status_totals_v1 WHERE task=? AND role='worker'").get(task)?.workerConversations ?? 0)
+  }
+
+  hasConversation(task: string, session: string): boolean {
+    this.#ready(task)
+    this.#validate(task)
+    return Boolean(this.#sql('SELECT 1 FROM fusion_status_facts_v1 WHERE task=? AND session=? AND active=1 LIMIT 1').get(task, session))
+  }
+}