@hraness/oh 0.2.3

package/src/semantic.ts

@@ -0,0 +1,333 @@
+import { mkdir, readFile, readdir, rename, unlink, writeFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+
+import { canonicalJson, canonicalSha256, hasExactKeys, isPlainRecord, parseSha256Hex,
+  safeCode, sha256Hex, type Sha256Hex } from "./canonical";
+import { OH_GRAPH_LIMITS_V1, type KnowledgeGraphRecordV1 } from "./graph";
+import type { OhSqliteStore } from "./sqlite/store";
+
+export const OH_EMBEDDING_PROFILE_V1 = Object.freeze({
+  dimensions: 768,
+  distance: "cosine",
+  documentation: "https://ai.google.dev/gemma/docs/embeddinggemma",
+  documentFormat: "title: {title} | text: {content}",
+  engine: "@tobilu/qmd@2.5.3",
+  model: "hf:ggml-org/embeddinggemma-300M-GGUF/embeddinggemma-300M-Q8_0.gguf",
+  normalization: "l2",
+  queryFormat: "task: search result | query: {query}",
+  v: 1,
+} as const);
+
+export type OhEmbeddingProfileV1 = typeof OH_EMBEDDING_PROFILE_V1;
+
+export function formatOhEmbeddingQueryV1(query: string): string {
+  return `task: search result | query: ${query}`;
+}
+
+export function formatOhEmbeddingDocumentV1(title: string, content: string): string {
+  return `title: ${title} | text: ${content}`;
+}
+
+export function normalizeOhEmbeddingV1(vector: readonly number[]): readonly number[] {
+  if (vector.length !== OH_EMBEDDING_PROFILE_V1.dimensions
+    || vector.some((component) => !Number.isFinite(component))) {
+    throw new TypeError(`Embedding vectors must contain ${OH_EMBEDDING_PROFILE_V1.dimensions} finite values.`);
+  }
+  const magnitude = Math.sqrt(vector.reduce((sum, component) => sum + component * component, 0));
+  if (magnitude === 0) throw new TypeError("Embedding vectors must have nonzero magnitude.");
+  return vector.map((component) => component / magnitude);
+}
+
+export function cosineSimilarityV1(left: readonly number[], right: readonly number[]): number {
+  const normalizedLeft = normalizeOhEmbeddingV1(left);
+  const normalizedRight = normalizeOhEmbeddingV1(right);
+  return normalizedLeft.reduce((sum, component, index) => sum + component * (normalizedRight[index] as number), 0);
+}
+
+export type OhSemanticSearchResultV1 = Readonly<{
+  key: string;
+  recordSha256: Sha256Hex;
+  score: number;
+  v: 1;
+}>;
+
+export interface OhSemanticSearchBackendV1 {
+  readonly profile: OhEmbeddingProfileV1;
+  close(): Promise<void>;
+  index(records: readonly KnowledgeGraphRecordV1[]): Promise<Readonly<{ indexed: number; v: 1 }>>;
+  search(query: string, limit: number, authority: OhSqliteStore): Promise<readonly OhSemanticSearchResultV1[]>;
+}
+
+type QmdStore = {
+  close(): Promise<void>;
+  embed(options: Readonly<{ collection: string; model: string }>): Promise<unknown>;
+  searchVector(query: string, options: Readonly<{ collection: string; limit: number }>): Promise<unknown>;
+  update(options: Readonly<{ collections: readonly string[] }>): Promise<unknown>;
+};
+export type QmdStoreFactoryV1 = (options: Readonly<{
+  config: Readonly<Record<string, unknown>>;
+  dbPath: string;
+}>) => Promise<QmdStore>;
+
+const qmdModuleSpecifier: string = "@tobilu/qmd";
+async function defaultQmdStoreFactory(options: Parameters<QmdStoreFactoryV1>[0]): Promise<QmdStore> {
+  let module: unknown;
+  try { module = await import(qmdModuleSpecifier); } catch {
+    throw new Error("Semantic search needs the optional @tobilu/qmd@2.5.3 package.");
+  }
+  const createStore = (module as { createStore?: unknown }).createStore;
+  if (typeof createStore !== "function") throw new Error("The installed QMD package has no compatible createStore export.");
+  return await (createStore as QmdStoreFactoryV1)(options);
+}
+
+type SemanticManifestV1 = Readonly<{
+  entries: Readonly<Record<string, Readonly<{ key: string; recordSha256: Sha256Hex }>>>;
+  profileSha256: Sha256Hex;
+  v: 1;
+}>;
+
+function recordDocument(record: KnowledgeGraphRecordV1): string {
+  return `# ${record.key}\n\nkind: ${record.kind}\n\n${canonicalJson(record.value)}\n`;
+}
+
+const QMD_VECTOR_RESULT_KEYS = [
+  "body", "bodyLength", "chunkPos", "collectionName", "context", "displayPath", "docid",
+  "filepath", "hash", "modifiedAt", "score", "source", "title",
+] as const;
+type ParsedQmdVectorResult = Readonly<{
+  body: string;
+  filename: string;
+  hash: Sha256Hex;
+  score: number;
+  title: string;
+}>;
+
+function semanticManifest(entries: Record<string, { key: string; recordSha256: Sha256Hex }>): SemanticManifestV1 {
+  const immutableEntries: Record<string, Readonly<{ key: string; recordSha256: Sha256Hex }>> = {};
+  for (const [filename, entry] of Object.entries(entries)) {
+    immutableEntries[filename] = Object.freeze({ ...entry });
+  }
+  return Object.freeze({
+    entries: Object.freeze(immutableEntries),
+    profileSha256: canonicalSha256(OH_EMBEDDING_PROFILE_V1),
+    v: 1,
+  });
+}
+
+function parseQmdVectorResult(value: unknown): ParsedQmdVectorResult | null {
+  if (!isPlainRecord(value) || !hasExactKeys(value, QMD_VECTOR_RESULT_KEYS)) return null;
+  const pathMatch = typeof value.filepath === "string"
+    ? /^qmd:\/\/oh\/([a-f0-9]{64}\.md)$/u.exec(value.filepath)
+    : null;
+  const filename = pathMatch?.[1];
+  const hash = parseSha256Hex(value.hash);
+  const title = safeCode(value.title, 512);
+  if (filename === undefined || value.displayPath !== `oh/${filename}` || value.collectionName !== "oh"
+    || value.source !== "vec" || value.context !== null || value.modifiedAt !== ""
+    || hash === null || value.docid !== hash.slice(0, 6) || title === null
+    || typeof value.body !== "string" || typeof value.bodyLength !== "number" || !Number.isSafeInteger(value.bodyLength)
+    || value.bodyLength < 0 || value.bodyLength > OH_GRAPH_LIMITS_V1.recordBytes + 4096
+    || value.body.length !== value.bodyLength || hash !== sha256Hex(value.body) || typeof value.chunkPos !== "number"
+    || !Number.isSafeInteger(value.chunkPos) || value.chunkPos < 0
+    || typeof value.score !== "number" || !Number.isFinite(value.score) || value.score < 0 || value.score > 1) {
+    return null;
+  }
+  return { body: value.body, filename, hash, score: value.score, title };
+}
+
+function parseQmdVectorResults(value: unknown): readonly ParsedQmdVectorResult[] {
+  if (!Array.isArray(value) || value.length > 100) {
+    throw new Error("QMD returned an invalid vector result batch.");
+  }
+  return value.map(parseQmdVectorResult)
+    .filter((result): result is ParsedQmdVectorResult => result !== null);
+}
+
+/**
+ * Optional, rebuildable local QMD index. SQLite records remain authoritative;
+ * every returned hit is rejoined to its exact current record digest.
+ */
+export class OhQmdSemanticBackendV1 implements OhSemanticSearchBackendV1 {
+  readonly profile = OH_EMBEDDING_PROFILE_V1;
+  readonly #cacheDirectory: string;
+  readonly #databasePath: string;
+  readonly #factory: QmdStoreFactoryV1;
+  #manifest: SemanticManifestV1 = semanticManifest({});
+  #manifestLoad: Promise<void> | null = null;
+  #store: Promise<QmdStore> | null = null;
+  #storeClose: Promise<void> | null = null;
+  #closure: Promise<void> | null = null;
+  #indexQueue: Promise<void> = Promise.resolve();
+  readonly #activeSearches = new Set<Promise<unknown>>();
+  #closed = false;
+
+  constructor(options: Readonly<{ cacheDirectory: string; databasePath?: string; storeFactory?: QmdStoreFactoryV1 }>) {
+    this.#cacheDirectory = resolve(options.cacheDirectory);
+    this.#databasePath = resolve(options.databasePath ?? join(this.#cacheDirectory, "qmd.sqlite"));
+    this.#factory = options.storeFactory ?? defaultQmdStoreFactory;
+  }
+
+  async #open(): Promise<QmdStore> {
+    if (this.#closed) throw new Error("The semantic backend is closed.");
+    this.#store ??= this.#initializeStore();
+    const store = await this.#store;
+    if (this.#closed) {
+      await this.#closeStore(store);
+      throw new Error("The semantic backend is closed.");
+    }
+    return store;
+  }
+
+  async #initializeStore(): Promise<QmdStore> {
+    const documents = join(this.#cacheDirectory, "documents");
+    await mkdir(documents, { recursive: true });
+    await this.#loadManifest();
+    if (this.#closed) throw new Error("The semantic backend is closed.");
+    const store = await this.#factory({
+      dbPath: this.#databasePath,
+      config: {
+        collections: { oh: { path: documents, pattern: "*.md" } },
+        models: { embed: OH_EMBEDDING_PROFILE_V1.model },
+      },
+    });
+    if (this.#closed) {
+      await this.#closeStore(store);
+      throw new Error("The semantic backend is closed.");
+    }
+    return store;
+  }
+
+  #closeStore(store: QmdStore): Promise<void> {
+    this.#storeClose ??= Promise.resolve().then(() => store.close());
+    return this.#storeClose;
+  }
+
+  #loadManifest(): Promise<void> {
+    this.#manifestLoad ??= this.#readManifest();
+    return this.#manifestLoad;
+  }
+
+  async #readManifest(): Promise<void> {
+    let text: string;
+    try { text = await readFile(join(this.#cacheDirectory, "manifest.json"), "utf8"); }
+    catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ENOENT") return;
+      throw error;
+    }
+    let value: unknown;
+    try { value = JSON.parse(text); } catch { throw new Error("The semantic manifest is not JSON."); }
+    if (canonicalJson(value) !== text || !isPlainRecord(value)
+      || !hasExactKeys(value, ["entries", "profileSha256", "v"]) || value.v !== 1
+      || value.profileSha256 !== canonicalSha256(OH_EMBEDDING_PROFILE_V1) || !isPlainRecord(value.entries)
+      || Object.keys(value.entries).length > 65_536) throw new Error("The semantic manifest is incompatible or invalid.");
+    const entries: Record<string, { key: string; recordSha256: Sha256Hex }> = {};
+    for (const [filename, candidate] of Object.entries(value.entries)) {
+      if (!/^[a-f0-9]{64}\.md$/u.test(filename) || !isPlainRecord(candidate)
+        || !hasExactKeys(candidate, ["key", "recordSha256"])) throw new Error("The semantic manifest has an invalid entry.");
+      const key = safeCode(candidate.key, 512);
+      const recordSha256 = parseSha256Hex(candidate.recordSha256);
+      if (key === null || recordSha256 === null || filename !== `${sha256Hex(key)}.md`) {
+        throw new Error("The semantic manifest entry identity is invalid.");
+      }
+      entries[filename] = { key, recordSha256 };
+    }
+    this.#manifest = semanticManifest(entries);
+  }
+
+  index(records: readonly KnowledgeGraphRecordV1[]): Promise<Readonly<{ indexed: number; v: 1 }>> {
+    if (records.length > 65_536) {
+      return Promise.reject(new RangeError("A semantic snapshot may contain at most 65,536 records."));
+    }
+    if (this.#closed) return Promise.reject(new Error("The semantic backend is closed."));
+    const snapshot = [...records];
+    const operation = this.#indexQueue.then(() => this.#indexSnapshot(snapshot));
+    this.#indexQueue = operation.then(() => undefined, () => undefined);
+    return operation;
+  }
+
+  async #indexSnapshot(records: readonly KnowledgeGraphRecordV1[]): Promise<Readonly<{ indexed: number; v: 1 }>> {
+    if (this.#closed) throw new Error("The semantic backend is closed.");
+    const documents = join(this.#cacheDirectory, "documents");
+    await mkdir(documents, { recursive: true });
+    await this.#loadManifest();
+    const entries: Record<string, { key: string; recordSha256: Sha256Hex }> = {};
+    for (const record of records) {
+      const filename = `${sha256Hex(record.key)}.md`;
+      entries[filename] = { key: record.key, recordSha256: record.recordSha256 };
+      const path = join(documents, filename);
+      const temporary = `${path}.${process.pid}.tmp`;
+      await writeFile(temporary, recordDocument(record), { encoding: "utf8", mode: 0o600 });
+      await rename(temporary, path);
+    }
+    const retained = new Set(Object.keys(entries));
+    for (const filename of await readdir(documents)) {
+      if (/^[a-f0-9]{64}\.md$/u.test(filename) && !retained.has(filename)) await unlink(join(documents, filename));
+    }
+    const nextManifest = semanticManifest(entries);
+    const store = await this.#open();
+    await store.update({ collections: ["oh"] });
+    await store.embed({ collection: "oh", model: OH_EMBEDDING_PROFILE_V1.model });
+    const manifestPath = join(this.#cacheDirectory, "manifest.json");
+    const temporaryManifest = `${manifestPath}.${process.pid}.tmp`;
+    await writeFile(temporaryManifest, canonicalJson(nextManifest), { encoding: "utf8", mode: 0o600 });
+    await rename(temporaryManifest, manifestPath);
+    this.#manifest = nextManifest;
+    return { indexed: records.length, v: 1 };
+  }
+
+  search(query: string, limit: number, authority: OhSqliteStore): Promise<readonly OhSemanticSearchResultV1[]> {
+    if (!Number.isSafeInteger(limit) || limit < 1 || limit > 100) {
+      return Promise.reject(new RangeError("Semantic limit must be 1 through 100."));
+    }
+    if (this.#closed) return Promise.reject(new Error("The semantic backend is closed."));
+    const operation = this.#searchSnapshot(query, limit, authority);
+    this.#activeSearches.add(operation);
+    void operation.then(
+      () => { this.#activeSearches.delete(operation); },
+      () => { this.#activeSearches.delete(operation); },
+    );
+    return operation;
+  }
+
+  async #searchSnapshot(query: string, limit: number,
+    authority: OhSqliteStore): Promise<readonly OhSemanticSearchResultV1[]> {
+    const store = await this.#open();
+    const manifest = this.#manifest;
+    const results = parseQmdVectorResults(await store.searchVector(query,
+      { collection: "oh", limit: Math.min(100, limit * 3) }));
+    const output: OhSemanticSearchResultV1[] = [];
+    const seen = new Set<string>();
+    for (const result of results) {
+      const entry = manifest.entries[result.filename];
+      if (entry === undefined || result.title !== entry.key || seen.has(entry.key)) continue;
+      const current = authority.get(entry.key);
+      if (current === null || current.recordSha256 !== entry.recordSha256) continue;
+      const expectedDocument = recordDocument(current);
+      if (result.body !== expectedDocument || result.hash !== sha256Hex(expectedDocument)) continue;
+      seen.add(entry.key);
+      output.push({ key: entry.key, recordSha256: entry.recordSha256, score: result.score, v: 1 });
+      if (output.length === limit) break;
+    }
+    return output;
+  }
+
+  async #finishClose(): Promise<void> {
+    await this.#indexQueue;
+    await Promise.allSettled([...this.#activeSearches]);
+    if (this.#store === null) return;
+    try {
+      const store = await this.#store;
+      await this.#closeStore(store);
+    } catch {
+      // Initialization failures are not close failures. A close initiated by
+      // late initialization is shared separately and must still be observed.
+      if (this.#storeClose !== null) await this.#storeClose;
+    }
+  }
+
+  close(): Promise<void> {
+    this.#closed = true;
+    this.#closure ??= this.#finishClose();
+    return this.#closure;
+  }
+}

package/src/sqlite/driver.ts

@@ -0,0 +1,47 @@
+import { existsSync } from "node:fs";
+import { Database } from "bun:sqlite";
+
+import { createOhSqliteRuntime } from "./runtime";
+
+export type OhSqliteDatabase = Database;
+
+const SQLITE_RUNTIME = createOhSqliteRuntime({
+  exists: existsSync,
+  open: (path, options) => new Database(path, options),
+  platform: process.platform,
+  setCustomSQLite: (path) => Database.setCustomSQLite(path),
+});
+
+export function openOhSqliteDatabase(path: string): OhSqliteDatabase {
+  const database = SQLITE_RUNTIME.open(path);
+  database.exec("PRAGMA foreign_keys = ON");
+  database.exec("PRAGMA journal_mode = WAL");
+  database.exec("PRAGMA synchronous = NORMAL");
+  database.exec("PRAGMA busy_timeout = 5000");
+  database.exec("PRAGMA trusted_schema = OFF");
+  return database;
+}
+
+export function withImmediateTransaction<T>(database: OhSqliteDatabase, work: () => T): T {
+  database.exec("BEGIN IMMEDIATE");
+  try {
+    const result = work();
+    database.exec("COMMIT");
+    return result;
+  } catch (error) {
+    try { database.exec("ROLLBACK"); } catch { /* preserve the original failure */ }
+    throw error;
+  }
+}
+
+export function withReadTransaction<T>(database: OhSqliteDatabase, work: () => T): T {
+  database.exec("BEGIN");
+  try {
+    const result = work();
+    database.exec("COMMIT");
+    return result;
+  } catch (error) {
+    try { database.exec("ROLLBACK"); } catch { /* preserve the original failure */ }
+    throw error;
+  }
+}

package/src/sqlite/index.ts

@@ -0,0 +1,4 @@
+export * from "./driver";
+export * from "./migrations";
+export * from "./port";
+export * from "./store";

package/src/sqlite/migrations.test.ts

@@ -0,0 +1,44 @@
+import { describe, expect, test } from "bun:test";
+
+import { canonicalNow, sha256Hex } from "../canonical";
+import { openOhSqliteDatabase } from "./driver";
+import { OH_SQLITE_MIGRATIONS, OH_SQLITE_SCHEMA_VERSION } from "./migrations";
+import { OhSqliteStore } from "./store";
+
+describe("SQLite schema evolution", () => {
+  test("preserves the released 0001 bytes and appends store realms as version 2", () => {
+    expect(OH_SQLITE_SCHEMA_VERSION).toBe(2);
+    expect(OH_SQLITE_MIGRATIONS.map(({ name, version }) => ({ name, version }))).toEqual([
+      { name: "0001_oh_core", version: 1 },
+      { name: "0002_store_realms", version: 2 },
+    ]);
+    expect(String(sha256Hex(OH_SQLITE_MIGRATIONS[0]?.sql ?? ""))).toBe(
+      "f525fc4f521b544d8e00526f2993a3b6bf81ae936950765c51406566ea4b1b7c",
+    );
+  });
+
+  test("upgrades an applied version-1 authority without rewriting its migration evidence", () => {
+    const database = openOhSqliteDatabase(":memory:");
+    const first = OH_SQLITE_MIGRATIONS[0];
+    if (first === undefined) throw new Error("Missing first migration.");
+    database.exec(`CREATE TABLE oh_migrations (
+      version INTEGER PRIMARY KEY,
+      name TEXT NOT NULL UNIQUE,
+      migration_sha256 TEXT NOT NULL CHECK(length(migration_sha256) = 64),
+      applied_at TEXT NOT NULL
+    ) STRICT`);
+    database.exec(first.sql);
+    database.query(`INSERT INTO oh_migrations(version, name, migration_sha256, applied_at)
+      VALUES (?, ?, ?, ?)`).run(first.version, first.name, sha256Hex(first.sql), canonicalNow());
+
+    const store = new OhSqliteStore({ database, spaceId: "upgraded" });
+    expect(store.contract().sqliteSchemaVersion).toBe(2);
+    expect(database.query<{ count: number }, []>(
+      "SELECT count(*) AS count FROM oh_migrations",
+    ).get()?.count).toBe(2);
+    expect(database.query<{ count: number }, []>(
+      "SELECT count(*) AS count FROM sqlite_schema WHERE name IN ('oh_space_bindings', 'oh_space_purges')",
+    ).get()?.count).toBe(2);
+    store.close();
+  });
+});

package/src/sqlite/migrations.ts

@@ -0,0 +1,178 @@
+import { canonicalNow, sha256Hex } from "../canonical";
+import type { OhSqliteDatabase } from "./driver";
+
+export const OH_SQLITE_SCHEMA_VERSION = 2 as const;
+
+export type OhSqliteMigration = Readonly<{ name: string; sql: string; version: number }>;
+
+export const OH_SQLITE_MIGRATIONS: readonly OhSqliteMigration[] = Object.freeze([
+  Object.freeze({
+    name: "0001_oh_core",
+    version: 1,
+    sql: `
+CREATE TABLE oh_contracts (
+  contract_id TEXT PRIMARY KEY,
+  contract_sha256 TEXT NOT NULL CHECK(length(contract_sha256) = 64),
+  manifest_json TEXT NOT NULL CHECK(json_valid(manifest_json)),
+  created_at TEXT NOT NULL
+) STRICT;
+
+CREATE TABLE oh_spaces (
+  space_id TEXT PRIMARY KEY,
+  contract_id TEXT NOT NULL REFERENCES oh_contracts(contract_id),
+  generation INTEGER NOT NULL CHECK(generation >= 0),
+  head_operation_sha256 TEXT CHECK(head_operation_sha256 IS NULL OR length(head_operation_sha256) = 64),
+  graph_revision_sha256 TEXT CHECK(graph_revision_sha256 IS NULL OR length(graph_revision_sha256) = 64),
+  records_sha256 TEXT NOT NULL CHECK(length(records_sha256) = 64),
+  sequence INTEGER NOT NULL CHECK(sequence >= 0),
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL,
+  CHECK(generation = sequence),
+  CHECK((sequence = 0) = (head_operation_sha256 IS NULL)),
+  CHECK((sequence = 0) = (graph_revision_sha256 IS NULL))
+) STRICT;
+
+CREATE TABLE oh_operations (
+  operation_sha256 TEXT PRIMARY KEY CHECK(length(operation_sha256) = 64),
+  space_id TEXT NOT NULL REFERENCES oh_spaces(space_id),
+  sequence INTEGER NOT NULL CHECK(sequence > 0),
+  operation_id TEXT NOT NULL,
+  parent_operation_sha256 TEXT CHECK(parent_operation_sha256 IS NULL OR length(parent_operation_sha256) = 64),
+  graph_revision_sha256 TEXT NOT NULL CHECK(length(graph_revision_sha256) = 64),
+  records_sha256 TEXT NOT NULL CHECK(length(records_sha256) = 64),
+  operation_json TEXT NOT NULL CHECK(json_valid(operation_json)),
+  instant TEXT NOT NULL,
+  UNIQUE(space_id, sequence),
+  UNIQUE(space_id, operation_id)
+) STRICT;
+
+CREATE TABLE oh_operation_records (
+  operation_sha256 TEXT NOT NULL REFERENCES oh_operations(operation_sha256),
+  ordinal INTEGER NOT NULL CHECK(ordinal >= 0),
+  record_key TEXT NOT NULL,
+  change_kind TEXT NOT NULL CHECK(change_kind IN ('put', 'tombstone')),
+  record_sha256 TEXT CHECK(record_sha256 IS NULL OR length(record_sha256) = 64),
+  PRIMARY KEY(operation_sha256, ordinal),
+  UNIQUE(operation_sha256, record_key)
+) STRICT;
+
+CREATE TABLE oh_records (
+  space_id TEXT NOT NULL REFERENCES oh_spaces(space_id),
+  record_key TEXT NOT NULL,
+  kind TEXT NOT NULL,
+  record_sha256 TEXT NOT NULL CHECK(length(record_sha256) = 64),
+  record_json TEXT NOT NULL CHECK(json_valid(record_json)),
+  operation_sha256 TEXT NOT NULL REFERENCES oh_operations(operation_sha256),
+  sequence INTEGER NOT NULL CHECK(sequence > 0),
+  PRIMARY KEY(space_id, record_key)
+) STRICT;
+
+CREATE TABLE oh_dependencies (
+  space_id TEXT NOT NULL,
+  record_key TEXT NOT NULL,
+  dependency_key TEXT NOT NULL,
+  PRIMARY KEY(space_id, record_key, dependency_key),
+  FOREIGN KEY(space_id, record_key) REFERENCES oh_records(space_id, record_key) ON DELETE CASCADE,
+  FOREIGN KEY(space_id, dependency_key) REFERENCES oh_records(space_id, record_key)
+) STRICT;
+
+CREATE TABLE oh_sync_outbox (
+  space_id TEXT NOT NULL REFERENCES oh_spaces(space_id),
+  sequence INTEGER NOT NULL,
+  operation_sha256 TEXT NOT NULL REFERENCES oh_operations(operation_sha256),
+  PRIMARY KEY(space_id, sequence),
+  UNIQUE(operation_sha256)
+) STRICT;
+
+CREATE TABLE oh_sync_state (
+  remote_id TEXT NOT NULL,
+  space_id TEXT NOT NULL REFERENCES oh_spaces(space_id),
+  pulled_sequence INTEGER NOT NULL CHECK(pulled_sequence >= 0),
+  pushed_sequence INTEGER NOT NULL CHECK(pushed_sequence >= 0),
+  remote_head_sha256 TEXT CHECK(remote_head_sha256 IS NULL OR length(remote_head_sha256) = 64),
+  updated_at TEXT NOT NULL,
+  PRIMARY KEY(remote_id, space_id)
+) STRICT;
+
+CREATE TABLE oh_search_documents (
+  space_id TEXT NOT NULL,
+  record_key TEXT NOT NULL,
+  record_sha256 TEXT NOT NULL CHECK(length(record_sha256) = 64),
+  text TEXT NOT NULL,
+  PRIMARY KEY(space_id, record_key),
+  FOREIGN KEY(space_id, record_key) REFERENCES oh_records(space_id, record_key) ON DELETE CASCADE
+) STRICT;
+
+CREATE VIRTUAL TABLE oh_search_fts USING fts5(
+  space_id UNINDEXED,
+  record_key UNINDEXED,
+  text,
+  tokenize='unicode61 remove_diacritics 2'
+);
+
+CREATE INDEX oh_operations_space_sequence ON oh_operations(space_id, sequence);
+CREATE INDEX oh_records_space_kind ON oh_records(space_id, kind, record_key);
+CREATE INDEX oh_dependencies_dependency ON oh_dependencies(space_id, dependency_key);
+`,
+  }),
+  Object.freeze({
+    name: "0002_store_realms",
+    version: 2,
+    sql: `
+CREATE TABLE oh_space_bindings (
+  space_id TEXT PRIMARY KEY REFERENCES oh_spaces(space_id),
+  realm_id TEXT NOT NULL,
+  profile_id TEXT NOT NULL,
+  profile_kind TEXT NOT NULL CHECK(profile_kind IN ('canonical', 'working')),
+  profile_sha256 TEXT NOT NULL CHECK(length(profile_sha256) = 64),
+  binding_sha256 TEXT NOT NULL UNIQUE CHECK(length(binding_sha256) = 64),
+  binding_json TEXT NOT NULL CHECK(json_valid(binding_json)),
+  created_at TEXT NOT NULL
+) STRICT;
+
+CREATE TABLE oh_space_purges (
+  space_id TEXT PRIMARY KEY,
+  binding_sha256 TEXT NOT NULL CHECK(length(binding_sha256) = 64),
+  prior_operation_sha256 TEXT CHECK(prior_operation_sha256 IS NULL OR length(prior_operation_sha256) = 64),
+  prior_sequence INTEGER NOT NULL CHECK(prior_sequence >= 0),
+  purged_at TEXT NOT NULL,
+  receipt_sha256 TEXT NOT NULL UNIQUE CHECK(length(receipt_sha256) = 64),
+  receipt_json TEXT NOT NULL CHECK(json_valid(receipt_json))
+) STRICT;
+`,
+  }),
+]);
+
+export function applyOhSqliteMigrations(database: OhSqliteDatabase): void {
+  database.exec(`CREATE TABLE IF NOT EXISTS oh_migrations (
+    version INTEGER PRIMARY KEY,
+    name TEXT NOT NULL UNIQUE,
+    migration_sha256 TEXT NOT NULL CHECK(length(migration_sha256) = 64),
+    applied_at TEXT NOT NULL
+  ) STRICT`);
+  const select = database.query<{ migration_sha256: string; name: string }, [number]>(
+    "SELECT name, migration_sha256 FROM oh_migrations WHERE version = ?",
+  );
+  const insert = database.query(
+    "INSERT INTO oh_migrations(version, name, migration_sha256, applied_at) VALUES (?, ?, ?, ?)",
+  );
+  for (const migration of OH_SQLITE_MIGRATIONS) {
+    const digest = sha256Hex(migration.sql);
+    database.exec("BEGIN IMMEDIATE");
+    try {
+      const existing = select.get(migration.version);
+      if (existing !== null) {
+        if (existing.name !== migration.name || existing.migration_sha256 !== digest) {
+          throw new Error(`SQLite migration ${migration.version} does not match the applied migration.`);
+        }
+      } else {
+        database.exec(migration.sql);
+        insert.run(migration.version, migration.name, digest, canonicalNow());
+      }
+      database.exec("COMMIT");
+    } catch (error) {
+      try { database.exec("ROLLBACK"); } catch { /* preserve the migration error */ }
+      throw error;
+    }
+  }
+}