@godspeedai/cognate-store-sqlite 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,40 @@
-# Temporary Holding Version
+# @godspeedai/cognate-store-sqlite
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Authoritative `DurableStore` on `bun:sqlite` (spec §13).
+
+## Tables (spec §13.2)
+
+`schema_versions` (migrations), `event_streams` (per-stream version), `events` (envelope only —
+position, event_id, stream_id/sequence, type, timing, causality, semantic ref, metadata),
+`payloads` (event_id → JSON payload, separate from the envelope so `erasePayload` can delete
+content without touching causality), `idempotency` (scope+key → fingerprint/result/event_ids),
+`records` (collection+id → version/JSON value, CAS), `outbox` (id, topic, payload, status,
+attempts, `claimed_until` lease), `projection_checkpoints`, `projection_state`, `blobs`
+(sha256-addressed bytes).
+
+## Transaction boundary
+
+`commit()` runs the entire decision — envelope validation, idempotency lookup, stream/record CAS,
+event/record/outbox writes, idempotency recording — inside one `BEGIN IMMEDIATE` transaction.
+Any failure throws and rolls back everything; `onCommitted` listeners fire only after `COMMIT`
+returns. `commitProjection` and `erasePayload` are each their own single transaction. bun:sqlite
+is synchronous and the store performs no `await` before entering a transaction, so concurrent
+`commit()` calls in one process serialize naturally through the JS event loop — exactly one wins
+a stream-version race, the rest see `ConcurrencyError`.
+
+## Durability settings
+
+`journal_mode=WAL`, `synchronous=FULL` (fsync on every commit — durability over speed, per spec
+§31.2 "fail closed": a decision must never be reported committed before SQLite confirms it),
+`foreign_keys=ON`, `busy_timeout=5000`. `secure_delete=ON` so `erasePayload` overwrites freed
+pages instead of merely unlinking them; it also runs `PRAGMA wal_checkpoint(TRUNCATE)` so no
+plaintext lingers in the WAL either.
+
+## Limits
+
+Single-process writer: correctness relies on one Node/Bun process holding the connection and on
+bun:sqlite's synchronous API for in-process serialization, not on SQLite's file locking for
+cross-process write concurrency. Multiple processes writing the same file concurrently will hit
+`SQLITE_BUSY` after `busy_timeout` rather than being serialized by this store. Back up by copying
+the `.sqlite` file plus its `-wal`/`-shm` siblings only after a checkpoint (or use the SQLite
+backup API); a bare copy of the main file while WAL is active can miss committed data.

package/package.json

@@ -1,6 +1,27 @@
 {
   "name": "@godspeedai/cognate-store-sqlite",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Authoritative DurableStore on bun:sqlite (spec §13).",
+  "type": "module",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/GodSpeedAI/Cognate.git",
+    "directory": "packages/store-sqlite"
+  },
+  "engines": {
+    "bun": ">=1.4.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src"
+  ],
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "dependencies": {
+    "@godspeedai/cognate-events": "^0.1.1"
+  }
+}

package/src/index.ts

@@ -0,0 +1,519 @@
+// Authoritative DurableStore on bun:sqlite (spec §13). Single-process writer; see README.md.
+import { Database } from "bun:sqlite";
+import { createHash } from "node:crypto";
+import { ConcurrencyError, RecordConflictError, IdempotencyMismatchError, CheckpointConflictError, NotFoundError, validateNewEvent } from "@godspeedai/cognate-events";
+import type {
+  DurableStore,
+  NewEvent,
+  StoredEvent,
+  RecordWrite,
+  StoredRecord,
+  CommitRequest,
+  CommitOutcome,
+  OutboxItem,
+  OutboxStatus,
+  OutboxSettlement,
+  ProjectionCheckpoint,
+  ProjectionCommit,
+  Json,
+} from "@godspeedai/cognate-events";
+import { migrate } from "./schema.ts";
+
+export interface SqliteStoreOptions {
+  /** Database file path, or ":memory:". */
+  readonly path: string;
+}
+
+// A row shape as returned by bun:sqlite; kept loosely typed at the boundary and mapped
+// into the exact DurableStore shapes below.
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type Row = any;
+
+const EVENT_SELECT = "SELECT e.*, p.payload AS payload FROM events e LEFT JOIN payloads p ON p.event_id = e.event_id";
+
+function mapEventRow(row: Row): StoredEvent {
+  const event: Row = {
+    eventId: row.event_id,
+    streamId: row.stream_id,
+    streamSequence: row.stream_sequence,
+    position: row.position,
+    eventType: row.event_type,
+    schemaVersion: row.schema_version,
+    occurredAt: row.occurred_at,
+    recordedAt: row.recorded_at,
+    tenant: row.tenant,
+    correlationId: row.correlation_id,
+    causationId: row.causation_id,
+    runId: row.run_id,
+    scopeId: row.scope_id,
+    payload: row.payload != null ? JSON.parse(row.payload as string) : null,
+  };
+  if (row.component_id != null) event.componentId = row.component_id;
+  if (row.fiber_id != null) event.fiberId = row.fiber_id;
+  if (row.semantic_ref != null) event.semanticRef = JSON.parse(row.semantic_ref as string);
+  if (row.metadata != null) event.metadata = JSON.parse(row.metadata as string);
+  if (row.erasure_reason != null) event.erasure = { reason: row.erasure_reason, erasedAt: row.erasure_at };
+  return event as StoredEvent;
+}
+
+function mapRecordRow(row: Row): StoredRecord {
+  return { collection: row.collection, id: row.id, version: row.version, value: JSON.parse(row.value as string) };
+}
+
+// Priority order, most to least selective: a correlationId (one thread/session) or agent narrows to a small
+// slice of the tenant's runs; tenant alone is the least selective (every run of that tenant), so it is only
+// picked when nothing more selective was asked for. Field iteration order in `where` must not decide this —
+// runtime-bun always builds `{ tenant, correlationId?, agent? }` with tenant first.
+const RUNS_INDEX_PRIORITY: readonly (readonly [string, string])[] = [
+  ["correlationId", "records_runs_correlation_idx"],
+  ["agent", "records_runs_agent_idx"],
+  ["tenant", "records_runs_tenant_idx"],
+];
+
+/**
+ * Builds the exact SQL `listRecords` executes (exported so tests can prove, via `EXPLAIN QUERY PLAN` on this
+ * same text, which index the real code path chooses — not a hand-written approximation of it).
+ *
+ * Equality filters push down as `json_extract(value, '$.<field>')` so a matching field can be served by an
+ * expression index (schema.ts migration 3) instead of loading every row in the collection and filtering in
+ * JS. The partial indexes are conditioned on a literal `collection = 'runs'`, which SQLite only matches
+ * against a literal in the query (a bound `?` parameter defeats partial-index selection even when its value
+ * happens to be "runs"), so a collection name safe to embed literally is inlined. Without an `INDEXED BY`
+ * hint, SQLite's planner may still favor the always-present `(collection, id)` primary key over a selective
+ * partial index on a small table (no `ANALYZE` statistics); the hint keeps the lookup scoped to the matching
+ * slice of runs regardless of table size, which is the DEBT-019 concern.
+ */
+export function buildListRecordsQuery(collection: string, where?: { readonly [field: string]: string | number | boolean | null }): { readonly sql: string; readonly params: readonly unknown[] } {
+  if (!/^[A-Za-z_][A-Za-z0-9_-]*$/.test(collection)) throw new Error(`listRecords: invalid collection name "${collection}"`);
+  const indexHint = collection === "runs" && where ? RUNS_INDEX_PRIORITY.find(([f]) => f in where)?.[1] : undefined;
+  let sql = `SELECT * FROM records${indexHint ? ` INDEXED BY ${indexHint}` : ""} WHERE collection = '${collection}'`;
+  const params: unknown[] = [];
+  for (const [field, value] of Object.entries(where ?? {})) {
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(field)) throw new Error(`listRecords: invalid field name "${field}"`);
+    sql += value === null ? ` AND json_extract(value, '$.${field}') IS NULL` : ` AND json_extract(value, '$.${field}') = ?`;
+    if (value !== null) params.push(value);
+  }
+  sql += " ORDER BY id";
+  return { sql, params };
+}
+
+function mapOutboxRow(row: Row): OutboxItem {
+  return {
+    id: row.id,
+    topic: row.topic,
+    payload: JSON.parse(row.payload as string),
+    status: row.status as OutboxStatus,
+    attempts: row.attempts,
+    availableAt: row.claimed_until,
+    lastError: row.last_error ?? null,
+    receipt: row.receipt != null ? JSON.parse(row.receipt as string) : null,
+    createdAt: row.created_at,
+  };
+}
+
+function mapCheckpointRow(row: Row): ProjectionCheckpoint {
+  return {
+    name: row.name,
+    version: row.version,
+    position: row.position,
+    status: row.status,
+    error: row.error_event_id != null ? { position: row.error_position, eventId: row.error_event_id, message: row.error_message } : null,
+  };
+}
+
+export function openSqliteStore(options: SqliteStoreOptions): DurableStore {
+  const db = new Database(options.path, { create: true });
+  db.exec("PRAGMA journal_mode = WAL");
+  // Durability over speed: fsync on every commit (spec §31.2 "fail closed" — a decision must
+  // never be reported committed before SQLite has actually persisted it). WAL + synchronous=FULL
+  // fsyncs the WAL on every transaction commit, so a crash cannot lose or reorder a committed decision.
+  db.exec("PRAGMA synchronous = FULL");
+  db.exec("PRAGMA foreign_keys = ON");
+  db.exec("PRAGMA busy_timeout = 5000");
+  // Erased payload bytes are overwritten in place rather than merely unlinked, so `erasePayload`
+  // (spec §32) leaves nothing recoverable from freed pages once the WAL is checkpointed.
+  db.exec("PRAGMA secure_delete = ON");
+  migrate(db);
+
+  let closed = false;
+  const listeners = new Set<(events: readonly StoredEvent[]) => void>();
+
+  function assertOpen(): void {
+    if (closed) throw new Error("store-sqlite: store is closed");
+  }
+
+  function ensureStream(streamId: string): void {
+    db.query("INSERT OR IGNORE INTO event_streams (stream_id, version) VALUES (?, 0)").run(streamId);
+  }
+
+  function streamVersionRow(streamId: string): number {
+    const row = db.query("SELECT version FROM event_streams WHERE stream_id = ?").get(streamId) as { version: number } | null;
+    return row?.version ?? 0;
+  }
+
+  function insertEventRow(streamId: string, sequence: number, event: NewEvent, recordedAt: string): StoredEvent {
+    const eventId = event.eventId ?? crypto.randomUUID();
+    db.query(
+      `INSERT INTO events (event_id, stream_id, stream_sequence, event_type, schema_version, occurred_at, recorded_at, tenant, correlation_id, causation_id, run_id, scope_id, component_id, fiber_id, semantic_ref, metadata)
+       VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)`,
+    ).run(
+      eventId,
+      streamId,
+      sequence,
+      event.eventType,
+      event.schemaVersion,
+      event.occurredAt,
+      recordedAt,
+      event.tenant,
+      event.correlationId,
+      event.causationId,
+      event.runId,
+      event.scopeId,
+      event.componentId ?? null,
+      event.fiberId ?? null,
+      event.semanticRef ? JSON.stringify(event.semanticRef) : null,
+      event.metadata ? JSON.stringify(event.metadata) : null,
+    );
+    db.query("INSERT INTO payloads (event_id, payload) VALUES (?, ?)").run(eventId, JSON.stringify(event.payload));
+    const row = db.query(`${EVENT_SELECT} WHERE e.event_id = ?`).get(eventId) as Row;
+    return mapEventRow(row);
+  }
+
+  function applyRecordWrite(write: RecordWrite): StoredRecord {
+    const row = db.query("SELECT version FROM records WHERE collection = ? AND id = ?").get(write.collection, write.id) as { version: number } | null;
+    const current = row?.version ?? 0;
+    if (current !== write.expectedVersion) throw new RecordConflictError(write.collection, write.id, write.expectedVersion, current);
+    const version = current + 1;
+    db.query(
+      `INSERT INTO records (collection, id, version, value) VALUES (?, ?, ?, ?)
+       ON CONFLICT (collection, id) DO UPDATE SET version = excluded.version, value = excluded.value`,
+    ).run(write.collection, write.id, version, JSON.stringify(write.value));
+    return { collection: write.collection, id: write.id, version, value: write.value };
+  }
+
+  const commitTxn = db.transaction((request: CommitRequest): CommitOutcome => {
+    // Phase A — validate every envelope before anything is written (spec §10).
+    for (const append of request.appends) for (const event of append.events) validateNewEvent(event);
+
+    // Phase B — idempotency: duplicate replays the recorded result; a fingerprint mismatch is an error.
+    if (request.idempotency) {
+      const existing = db
+        .query("SELECT fingerprint, result, event_ids FROM idempotency WHERE scope = ? AND key = ?")
+        .get(request.idempotency.scope, request.idempotency.key) as { fingerprint: string; result: string; event_ids: string } | null;
+      if (existing) {
+        if (existing.fingerprint !== request.idempotency.fingerprint) {
+          throw new IdempotencyMismatchError(request.idempotency.scope, request.idempotency.key);
+        }
+        const ids = JSON.parse(existing.event_ids) as string[];
+        const events = ids.map((id) => mapEventRow(db.query(`${EVENT_SELECT} WHERE e.event_id = ?`).get(id) as Row));
+        return { kind: "duplicate", events, result: JSON.parse(existing.result) as Json };
+      }
+    }
+
+    // Phase C — CAS every stream's expected version before writing any event.
+    const streamVersions = new Map<string, number>();
+    for (const append of request.appends) {
+      ensureStream(append.streamId);
+      const current = streamVersionRow(append.streamId);
+      if (current !== append.expectedVersion) throw new ConcurrencyError(append.streamId, append.expectedVersion, current);
+      streamVersions.set(append.streamId, current);
+    }
+
+    // Phase D — CAS every record write before applying any of them.
+    for (const write of request.records ?? []) {
+      const row = db.query("SELECT version FROM records WHERE collection = ? AND id = ?").get(write.collection, write.id) as { version: number } | null;
+      const current = row?.version ?? 0;
+      if (current !== write.expectedVersion) throw new RecordConflictError(write.collection, write.id, write.expectedVersion, current);
+    }
+
+    // Phase E — insert events; the store assigns sequence/position/id/recordedAt.
+    const recordedAt = new Date().toISOString();
+    const storedEvents: StoredEvent[] = [];
+    for (const append of request.appends) {
+      let sequence = streamVersions.get(append.streamId) ?? 0;
+      for (const event of append.events) {
+        sequence += 1;
+        storedEvents.push(insertEventRow(append.streamId, sequence, event, recordedAt));
+      }
+      db.query("UPDATE event_streams SET version = ? WHERE stream_id = ?").run(sequence, append.streamId);
+    }
+
+    // Phase F — apply record writes (already validated above).
+    const storedRecords = (request.records ?? []).map((write) => applyRecordWrite(write));
+
+    // Phase G — outbox intents; a reused id fails the whole decision (unique constraint).
+    for (const item of request.outbox ?? []) {
+      db.query("INSERT INTO outbox (id, topic, payload, created_at) VALUES (?, ?, ?, ?)").run(item.id, item.topic, JSON.stringify(item.payload), recordedAt);
+    }
+
+    // Phase H — record the idempotency key against the result and the events it produced.
+    const result: Json = request.result ?? null;
+    if (request.idempotency) {
+      db.query("INSERT INTO idempotency (scope, key, fingerprint, result, event_ids, created_at) VALUES (?, ?, ?, ?, ?, ?)").run(
+        request.idempotency.scope,
+        request.idempotency.key,
+        request.idempotency.fingerprint,
+        JSON.stringify(result),
+        JSON.stringify(storedEvents.map((e) => e.eventId)),
+        recordedAt,
+      );
+    }
+
+    return { kind: "committed", events: storedEvents, records: storedRecords, result };
+  });
+
+  const claimOutboxTxn = db.transaction((topic: string, now: number, limit: number, leaseMs: number): OutboxItem[] => {
+    const rows = db.query("SELECT * FROM outbox WHERE topic = ? AND status = 'pending' AND claimed_until <= ? ORDER BY rowid LIMIT ?").all(topic, now, limit) as Row[];
+    const claimedUntil = now + leaseMs;
+    const items: OutboxItem[] = [];
+    for (const row of rows) {
+      db.query("UPDATE outbox SET attempts = attempts + 1, claimed_until = ? WHERE id = ?").run(claimedUntil, row.id);
+      items.push(mapOutboxRow({ ...row, attempts: row.attempts + 1, claimed_until: claimedUntil }));
+    }
+    return items;
+  });
+
+  const settleOutboxTxn = db.transaction((id: string, settlement: OutboxSettlement): void => {
+    if (settlement.kind === "delivered") {
+      db.query("UPDATE outbox SET status = 'delivered', receipt = ? WHERE id = ?").run(JSON.stringify(settlement.receipt), id);
+    } else if (settlement.kind === "retry") {
+      db.query("UPDATE outbox SET last_error = ?, claimed_until = ? WHERE id = ?").run(settlement.error, settlement.retryAt, id);
+    } else {
+      db.query("UPDATE outbox SET status = 'poisoned', last_error = ? WHERE id = ?").run(settlement.error, id);
+    }
+  });
+
+  const commitProjectionTxn = db.transaction((commitReq: ProjectionCommit): void => {
+    const row = db.query("SELECT position FROM projection_checkpoints WHERE name = ?").get(commitReq.name) as { position: number } | null;
+    const current = row?.position ?? 0;
+    if (current !== commitReq.fromPosition) {
+      throw new CheckpointConflictError(`Projection ${commitReq.name} checkpoint is at ${current}, expected ${commitReq.fromPosition}`);
+    }
+    for (const write of commitReq.writes) {
+      if (write.value === null) {
+        db.query("DELETE FROM projection_state WHERE name = ? AND key = ?").run(commitReq.name, write.key);
+      } else {
+        db.query(
+          `INSERT INTO projection_state (name, key, value) VALUES (?, ?, ?)
+           ON CONFLICT (name, key) DO UPDATE SET value = excluded.value`,
+        ).run(commitReq.name, write.key, JSON.stringify(write.value));
+      }
+    }
+    db.query(
+      `INSERT INTO projection_checkpoints (name, version, position, status, error_position, error_event_id, error_message)
+       VALUES (?, ?, ?, 'ok', NULL, NULL, NULL)
+       ON CONFLICT (name) DO UPDATE SET version = excluded.version, position = excluded.position, status = 'ok', error_position = NULL, error_event_id = NULL, error_message = NULL`,
+    ).run(commitReq.name, commitReq.version, commitReq.toPosition);
+  });
+
+  const erasePayloadTxn = db.transaction((eventId: string, reason: string, actorId: string): StoredEvent => {
+    const original = db.query(`${EVENT_SELECT} WHERE e.event_id = ?`).get(eventId) as Row;
+    if (!original) throw new NotFoundError(`event ${eventId} not found`);
+    const erasedAt = new Date().toISOString();
+    db.query("DELETE FROM payloads WHERE event_id = ?").run(eventId);
+    db.query("UPDATE events SET erasure_reason = ?, erasure_at = ? WHERE event_id = ?").run(reason, erasedAt, eventId);
+
+    ensureStream("$erasures");
+    const sequence = streamVersionRow("$erasures") + 1;
+    const tombstone = insertEventRow(
+      "$erasures",
+      sequence,
+      {
+        eventType: "erasure.recorded",
+        schemaVersion: 1,
+        occurredAt: erasedAt,
+        tenant: original.tenant,
+        correlationId: original.correlation_id,
+        causationId: original.event_id,
+        runId: original.run_id,
+        scopeId: original.scope_id,
+        payload: { eventId, reason, actorId },
+      },
+      erasedAt,
+    );
+    db.query("UPDATE event_streams SET version = ? WHERE stream_id = ?").run(sequence, "$erasures");
+    return tombstone;
+  });
+
+  const store: DurableStore = {
+    async commit(request: CommitRequest): Promise<CommitOutcome> {
+      assertOpen();
+      const outcome = commitTxn.immediate(request);
+      if (outcome.kind === "committed" && outcome.events.length > 0) {
+        for (const listener of listeners) listener(outcome.events);
+      }
+      return outcome;
+    },
+
+    async streamVersion(streamId: string): Promise<number> {
+      assertOpen();
+      return streamVersionRow(streamId);
+    },
+
+    async readStream(streamId: string, options?: { readonly afterSequence?: number; readonly limit?: number }): Promise<StoredEvent[]> {
+      assertOpen();
+      let sql = `${EVENT_SELECT} WHERE e.stream_id = ?`;
+      const params: unknown[] = [streamId];
+      if (options?.afterSequence != null) {
+        sql += " AND e.stream_sequence > ?";
+        params.push(options.afterSequence);
+      }
+      sql += " ORDER BY e.stream_sequence";
+      if (options?.limit != null) {
+        sql += " LIMIT ?";
+        params.push(options.limit);
+      }
+      const rows = db.query(sql).all(...(params as [])) as Row[];
+      return rows.map(mapEventRow);
+    },
+
+    async readAll(options?: { readonly afterPosition?: number; readonly limit?: number }): Promise<StoredEvent[]> {
+      assertOpen();
+      let sql = `${EVENT_SELECT} WHERE 1 = 1`;
+      const params: unknown[] = [];
+      if (options?.afterPosition != null) {
+        sql += " AND e.position > ?";
+        params.push(options.afterPosition);
+      }
+      sql += " ORDER BY e.position";
+      if (options?.limit != null) {
+        sql += " LIMIT ?";
+        params.push(options.limit);
+      }
+      const rows = db.query(sql).all(...(params as [])) as Row[];
+      return rows.map(mapEventRow);
+    },
+
+    async getEvent(eventId: string): Promise<StoredEvent | undefined> {
+      assertOpen();
+      const row = db.query(`${EVENT_SELECT} WHERE e.event_id = ?`).get(eventId) as Row;
+      return row ? mapEventRow(row) : undefined;
+    },
+
+    onCommitted(listener: (events: readonly StoredEvent[]) => void): () => void {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+
+    async getRecord(collection: string, id: string): Promise<StoredRecord | undefined> {
+      assertOpen();
+      const row = db.query("SELECT * FROM records WHERE collection = ? AND id = ?").get(collection, id) as Row;
+      return row ? mapRecordRow(row) : undefined;
+    },
+
+    async listRecords(collection: string, where?: { readonly [field: string]: string | number | boolean | null }): Promise<StoredRecord[]> {
+      assertOpen();
+      const { sql, params } = buildListRecordsQuery(collection, where);
+      const rows = db.query(sql).all(...(params as [])) as Row[];
+      return rows.map(mapRecordRow);
+    },
+
+    async claimOutbox(options: { readonly topic: string; readonly now: number; readonly limit: number; readonly leaseMs: number }): Promise<OutboxItem[]> {
+      assertOpen();
+      return claimOutboxTxn.immediate(options.topic, options.now, options.limit, options.leaseMs);
+    },
+
+    async settleOutbox(id: string, settlement: OutboxSettlement): Promise<void> {
+      assertOpen();
+      settleOutboxTxn.immediate(id, settlement);
+    },
+
+    async requeueOutbox(id: string, now: number): Promise<void> {
+      assertOpen();
+      db.query("UPDATE outbox SET status = 'pending', claimed_until = ? WHERE id = ?").run(now, id);
+    },
+
+    async listOutbox(options?: { readonly topic?: string; readonly status?: OutboxStatus }): Promise<OutboxItem[]> {
+      assertOpen();
+      let sql = "SELECT * FROM outbox WHERE 1 = 1";
+      const params: unknown[] = [];
+      if (options?.topic != null) {
+        sql += " AND topic = ?";
+        params.push(options.topic);
+      }
+      if (options?.status != null) {
+        sql += " AND status = ?";
+        params.push(options.status);
+      }
+      sql += " ORDER BY rowid";
+      const rows = db.query(sql).all(...(params as [])) as Row[];
+      return rows.map(mapOutboxRow);
+    },
+
+    async getProjection(name: string): Promise<ProjectionCheckpoint | undefined> {
+      assertOpen();
+      const row = db.query("SELECT * FROM projection_checkpoints WHERE name = ?").get(name) as Row;
+      return row ? mapCheckpointRow(row) : undefined;
+    },
+
+    async commitProjection(commitReq: ProjectionCommit): Promise<void> {
+      assertOpen();
+      commitProjectionTxn.immediate(commitReq);
+    },
+
+    async failProjection(name: string, error: { readonly position: number; readonly eventId: string; readonly message: string }): Promise<void> {
+      assertOpen();
+      db.query(
+        `INSERT INTO projection_checkpoints (name, version, position, status, error_position, error_event_id, error_message)
+         VALUES (?, '', 0, 'error', ?, ?, ?)
+         ON CONFLICT (name) DO UPDATE SET status = 'error', error_position = excluded.error_position, error_event_id = excluded.error_event_id, error_message = excluded.error_message`,
+      ).run(name, error.position, error.eventId, error.message);
+    },
+
+    async readProjection(name: string, key: string): Promise<Json | undefined> {
+      assertOpen();
+      const row = db.query("SELECT value FROM projection_state WHERE name = ? AND key = ?").get(name, key) as { value: string } | null;
+      return row ? (JSON.parse(row.value) as Json) : undefined;
+    },
+
+    async listProjection(name: string): Promise<{ readonly key: string; readonly value: Json }[]> {
+      assertOpen();
+      const rows = db.query("SELECT key, value FROM projection_state WHERE name = ? ORDER BY key").all(name) as Row[];
+      return rows.map((row) => ({ key: row.key, value: JSON.parse(row.value) as Json }));
+    },
+
+    async resetProjection(name: string): Promise<void> {
+      assertOpen();
+      const txn = db.transaction((n: string): void => {
+        db.query("DELETE FROM projection_state WHERE name = ?").run(n);
+        db.query("DELETE FROM projection_checkpoints WHERE name = ?").run(n);
+      });
+      txn.immediate(name);
+    },
+
+    async putBlob(bytes: Uint8Array): Promise<string> {
+      assertOpen();
+      const hash = `sha256:${createHash("sha256").update(bytes).digest("hex")}`;
+      db.query("INSERT OR IGNORE INTO blobs (hash, bytes) VALUES (?, ?)").run(hash, bytes);
+      return hash;
+    },
+
+    async getBlob(hash: string): Promise<Uint8Array | undefined> {
+      assertOpen();
+      const row = db.query("SELECT bytes FROM blobs WHERE hash = ?").get(hash) as { bytes: Uint8Array } | null;
+      return row ? new Uint8Array(row.bytes) : undefined;
+    },
+
+    async deleteBlob(hash: string): Promise<void> {
+      assertOpen();
+      db.query("DELETE FROM blobs WHERE hash = ?").run(hash);
+    },
+
+    async erasePayload(eventId: string, reason: string, actorId: string): Promise<void> {
+      assertOpen();
+      const tombstone = erasePayloadTxn.immediate(eventId, reason, actorId);
+      // Flush and truncate the WAL so the secure-delete-zeroed pages (and the tombstone) are the
+      // only trace left on disk; the erased plaintext must not linger in either file (spec §32).
+      db.exec("PRAGMA wal_checkpoint(TRUNCATE)");
+      for (const listener of listeners) listener([tombstone]);
+    },
+
+    async close(): Promise<void> {
+      if (closed) return;
+      closed = true;
+      db.close();
+    },
+  };
+
+  return store;
+}

package/src/schema.ts

@@ -0,0 +1,142 @@
+// Numbered migrations recorded in `schema_versions`. Tables mirror spec §13.2 logical names.
+// Payloads are kept in a table separate from event envelopes so erasure (spec §32) can delete
+// content while the envelope (causality, ids, timing) survives untouched.
+import type { Database } from "bun:sqlite";
+
+export interface Migration {
+  readonly version: number;
+  readonly sql: string;
+}
+
+export const MIGRATIONS: readonly Migration[] = [
+  {
+    version: 1,
+    sql: `
+      CREATE TABLE event_streams (
+        stream_id TEXT PRIMARY KEY,
+        version INTEGER NOT NULL
+      );
+
+      CREATE TABLE events (
+        position INTEGER PRIMARY KEY,
+        event_id TEXT NOT NULL UNIQUE,
+        stream_id TEXT NOT NULL REFERENCES event_streams(stream_id),
+        stream_sequence INTEGER NOT NULL,
+        event_type TEXT NOT NULL,
+        schema_version INTEGER NOT NULL,
+        occurred_at TEXT NOT NULL,
+        recorded_at TEXT NOT NULL,
+        tenant TEXT NOT NULL,
+        correlation_id TEXT NOT NULL,
+        causation_id TEXT,
+        run_id TEXT,
+        scope_id TEXT NOT NULL,
+        component_id TEXT,
+        fiber_id TEXT,
+        semantic_ref TEXT,
+        metadata TEXT,
+        erasure_reason TEXT,
+        erasure_at TEXT,
+        UNIQUE (stream_id, stream_sequence)
+      );
+
+      -- Payload bytes live apart from the envelope so erasePayload can delete content
+      -- without touching causality-bearing columns above (spec sec32).
+      CREATE TABLE payloads (
+        event_id TEXT PRIMARY KEY REFERENCES events(event_id),
+        payload TEXT NOT NULL
+      );
+
+      CREATE TABLE idempotency (
+        scope TEXT NOT NULL,
+        key TEXT NOT NULL,
+        fingerprint TEXT NOT NULL,
+        result TEXT NOT NULL,
+        event_ids TEXT NOT NULL,
+        created_at TEXT NOT NULL,
+        PRIMARY KEY (scope, key)
+      );
+
+      CREATE TABLE records (
+        collection TEXT NOT NULL,
+        id TEXT NOT NULL,
+        version INTEGER NOT NULL,
+        value TEXT NOT NULL,
+        PRIMARY KEY (collection, id)
+      );
+
+      CREATE TABLE outbox (
+        id TEXT PRIMARY KEY,
+        topic TEXT NOT NULL,
+        payload TEXT NOT NULL,
+        status TEXT NOT NULL DEFAULT 'pending',
+        attempts INTEGER NOT NULL DEFAULT 0,
+        claimed_until INTEGER NOT NULL DEFAULT 0,
+        last_error TEXT,
+        receipt TEXT,
+        created_at TEXT NOT NULL
+      );
+      CREATE INDEX outbox_topic_idx ON outbox (topic, status, claimed_until);
+
+      CREATE TABLE projection_checkpoints (
+        name TEXT PRIMARY KEY,
+        version TEXT NOT NULL,
+        position INTEGER NOT NULL,
+        status TEXT NOT NULL,
+        error_position INTEGER,
+        error_event_id TEXT,
+        error_message TEXT
+      );
+
+      CREATE TABLE projection_state (
+        name TEXT NOT NULL,
+        key TEXT NOT NULL,
+        value TEXT NOT NULL,
+        PRIMARY KEY (name, key)
+      );
+
+      CREATE TABLE blobs (
+        hash TEXT PRIMARY KEY,
+        bytes BLOB NOT NULL
+      );
+    `,
+  },
+  {
+    // Spec §9.2: durable facts are never undone by deleting or rewriting history. Enforced in the file itself,
+    // so raw SQL cannot bypass the store API. Only a single erasure (§32) may set the erasure columns.
+    version: 2,
+    sql: `
+      CREATE TRIGGER events_append_only_delete BEFORE DELETE ON events
+      BEGIN SELECT RAISE(ABORT, 'events are append-only (spec §9.2)'); END;
+
+      CREATE TRIGGER events_append_only_update BEFORE UPDATE ON events
+      WHEN NEW.position IS NOT OLD.position OR NEW.event_id IS NOT OLD.event_id OR NEW.stream_id IS NOT OLD.stream_id OR NEW.stream_sequence IS NOT OLD.stream_sequence OR NEW.event_type IS NOT OLD.event_type OR NEW.schema_version IS NOT OLD.schema_version OR NEW.occurred_at IS NOT OLD.occurred_at OR NEW.recorded_at IS NOT OLD.recorded_at OR NEW.tenant IS NOT OLD.tenant OR NEW.correlation_id IS NOT OLD.correlation_id OR NEW.causation_id IS NOT OLD.causation_id OR NEW.run_id IS NOT OLD.run_id OR NEW.scope_id IS NOT OLD.scope_id OR NEW.component_id IS NOT OLD.component_id OR NEW.fiber_id IS NOT OLD.fiber_id OR NEW.semantic_ref IS NOT OLD.semantic_ref OR NEW.metadata IS NOT OLD.metadata OR OLD.erasure_reason IS NOT NULL
+      BEGIN SELECT RAISE(ABORT, 'events are append-only (spec §9.2)'); END;
+    `,
+  },
+  {
+    // DurableStore.listRecords (spec §22, DEBT-019) pushes equality filters down as json_extract expressions;
+    // these partial expression indexes let SQLite serve `runtime-bun`'s listRuns query (collection = 'runs',
+    // filtered by tenant/correlationId/agent) as an index search instead of scanning every run record.
+    version: 3,
+    sql: `
+      CREATE INDEX records_runs_tenant_idx ON records (json_extract(value, '$.tenant')) WHERE collection = 'runs';
+      CREATE INDEX records_runs_correlation_idx ON records (json_extract(value, '$.correlationId')) WHERE collection = 'runs';
+      CREATE INDEX records_runs_agent_idx ON records (json_extract(value, '$.agent')) WHERE collection = 'runs';
+    `,
+  },
+];
+
+/** Apply any migration not yet recorded in `schema_versions`, inside one transaction. */
+export function migrate(db: Database): void {
+  db.exec("CREATE TABLE IF NOT EXISTS schema_versions (version INTEGER PRIMARY KEY, applied_at TEXT NOT NULL)");
+  const applied = new Set((db.query("SELECT version FROM schema_versions").all() as { version: number }[]).map((r) => r.version));
+  const run = db.transaction((): void => {
+    for (const migration of MIGRATIONS) {
+      if (applied.has(migration.version)) continue;
+      db.exec(migration.sql);
+      db.query("INSERT INTO schema_versions (version, applied_at) VALUES (?, ?)").run(migration.version, new Date().toISOString());
+    }
+  });
+  run.immediate();
+}