@omgbase/core 0.1.0

package/dist/src/core/store/schema.js

@@ -0,0 +1,386 @@
+// Full DDL — data-model §3 (durable) + §4 (derived). SQLite dialect.
+// Kept as one string so migrations and rebuild-index can apply it verbatim.
+// No dialect-specific SQL leaks above the store module (02 §8).
+export const SCHEMA_VERSION = 13;
+// file_stats (02 §4; derived, rebuildable by a full re-stat) backs the CLI
+// freshness sweep (11 §3.3): (mtime_ns, size) cheap-change detection so a
+// one-shot command re-ingests only files that changed on disk since last ingest.
+export const FILE_STATS_DDL = /* sql */ `
+CREATE TABLE IF NOT EXISTS file_stats (
+  repo_id  TEXT NOT NULL,
+  path     TEXT NOT NULL,
+  mtime_ns INTEGER NOT NULL,
+  size     INTEGER NOT NULL,
+  hash     BLOB NOT NULL,
+  PRIMARY KEY (repo_id, path)
+);
+`;
+// properties (properties-table). One indexed row per property value: the
+// unified query surface for frontmatter, inline (key:: value), and computed
+// ($title/$tags) document properties, superseding the docs.metadata JSON
+// blob. `card` records the authored shape (scalar vs list) so scalar ==/!=/<
+// match only scalar-authored rows while list() sees all — reproducing the
+// json_extract scalar-vs-array distinction. Current-state, maintained
+// transactionally at ingest alongside blocks (repopulated by re-ingest, not by
+// rebuild-index — see docs/properties-table.md §6).
+export const PROPERTIES_DDL = /* sql */ `
+CREATE TABLE IF NOT EXISTS properties (
+  prop_id        TEXT PRIMARY KEY,
+  repo_id        TEXT NOT NULL,
+  doc_id         TEXT NOT NULL,
+  block_id       TEXT,                    -- NULL = document-scoped (frontmatter, computed)
+  source         TEXT NOT NULL CHECK (source IN ('frontmatter','inline','computed')),
+  key            TEXT NOT NULL,           -- dotted, flattened: "layer","meta.owner"; computed carry $: "$title"
+  card           TEXT NOT NULL CHECK (card IN ('scalar','list')),
+  ord            INTEGER NOT NULL DEFAULT 0,
+  val_text       TEXT,
+  val_num        REAL,
+  val_bool       INTEGER,
+  val_json       TEXT,
+  type           TEXT NOT NULL CHECK (type IN ('string','number','bool','null','json')),
+  created_commit TEXT NOT NULL,
+  deleted_commit TEXT
+);
+CREATE INDEX IF NOT EXISTS idx_props_doc      ON properties(doc_id)                 WHERE deleted_commit IS NULL;
+CREATE INDEX IF NOT EXISTS idx_props_key_text ON properties(repo_id, key, val_text) WHERE deleted_commit IS NULL;
+CREATE INDEX IF NOT EXISTS idx_props_key_num  ON properties(repo_id, key, val_num)  WHERE deleted_commit IS NULL;
+CREATE INDEX IF NOT EXISTS idx_props_src_key  ON properties(repo_id, source, key)   WHERE deleted_commit IS NULL;
+`;
+// Sync adapters/sources/attachments (sync-plugins §2). A workspace-level
+// registry: adapters map a name → external command; sources name an adapter +
+// config (rendered to flags at spawn); attachments join repo ⇄ source (m:n).
+// sync_state holds engine-owned per-attachment change-tracking (revision per
+// path, cursor) so a stateless adapter can be spawned fresh each run (§6).
+export const SYNC_DDL = /* sql */ `
+CREATE TABLE IF NOT EXISTS adapters (
+  name     TEXT PRIMARY KEY,        -- workspace-unique adapter name (e.g. "fs")
+  command  TEXT NOT NULL,           -- argv[0] to spawn (e.g. "omgbase-fs-adapter")
+  args     TEXT NOT NULL DEFAULT '[]'  -- fixed leading args (JSON string[])
+);
+
+CREATE TABLE IF NOT EXISTS sources (
+  source_id TEXT PRIMARY KEY,
+  name      TEXT NOT NULL UNIQUE,   -- workspace-unique source name
+  adapter   TEXT NOT NULL REFERENCES adapters(name),
+  config    TEXT NOT NULL DEFAULT '{}',  -- JSON object → rendered to flags (13 §3.1)
+  env       TEXT NOT NULL DEFAULT '{}'   -- JSON object → spawn env (secrets; 13 §3.2)
+);
+
+CREATE TABLE IF NOT EXISTS attachments (
+  repo_id   TEXT NOT NULL REFERENCES repos(repo_id),
+  source_id TEXT NOT NULL REFERENCES sources(source_id),
+  PRIMARY KEY (repo_id, source_id)
+);
+
+CREATE TABLE IF NOT EXISTS sync_state (
+  repo_id   TEXT NOT NULL,
+  source_id TEXT NOT NULL,
+  path      TEXT NOT NULL,          -- '' reserved for the attachment-level cursor row
+  revision  TEXT,                   -- last-observed source revision for this path
+  cursor    TEXT,                   -- last poll/webhook cursor (attachment-level row)
+  PRIMARY KEY (repo_id, source_id, path)
+);
+`;
+// Workspace-default settings (config-scope). A singleton row (id = 0) holding a
+// JSON blob with the SAME shape as repos.settings. It is the default layer: a
+// repo's own settings deep-merge on top (repo overrides workspace at the leaf).
+// There is no separate "global config" namespace — top-level concepts are the
+// tables (repos/adapters/sources); omg config speaks only this settings shape,
+// at the workspace (default) layer or a specific repo layer.
+export const WORKSPACE_SETTINGS_DDL = /* sql */ `
+CREATE TABLE IF NOT EXISTS workspace_settings (
+  id       INTEGER PRIMARY KEY CHECK (id = 0),
+  settings TEXT NOT NULL DEFAULT '{}'
+);
+INSERT OR IGNORE INTO workspace_settings (id, settings) VALUES (0, '{}');
+`;
+export const NODES_DDL = /* sql */ `
+CREATE TABLE IF NOT EXISTS nodes (
+  node_id    TEXT PRIMARY KEY,
+  repo_id    TEXT NOT NULL,
+  doc_id     TEXT NOT NULL,
+  block_id   TEXT,
+  kind       TEXT NOT NULL,
+  name       TEXT,
+  value      TEXT,
+  span_start INTEGER,
+  span_end   INTEGER,
+  attrs      TEXT NOT NULL DEFAULT '{}'
+);
+CREATE INDEX IF NOT EXISTS idx_nodes_doc  ON nodes(doc_id);
+CREATE INDEX IF NOT EXISTS idx_nodes_kind ON nodes(kind);
+CREATE INDEX IF NOT EXISTS idx_nodes_name ON nodes(name) WHERE name IS NOT NULL;
+CREATE VIRTUAL TABLE IF NOT EXISTS nodes_fts USING fts5(
+  name, value, content='nodes', content_rowid='rowid', tokenize='porter unicode61'
+);
+`;
+// doc_embeddings (doc-grain semantic retrieval). One vector per (doc_id, model)
+// so `from=docs semantic` ranks whole documents by topical relevance rather than
+// re-labelling block hits. `input_hash` is the freshness key: the sha256 of the
+// exact bytes that produced the vector (whole-doc embed input, or the pooled
+// fallback's composite of block hashes) — a stored row whose input_hash no
+// longer matches the current document's is stale and re-embedded. `method`
+// records which strategy produced it ('whole' = whole-document embedding;
+// 'pooled' = token-weighted mean of block vectors, used only when the doc's
+// embed input exceeds the provider's max input length). Derived/rebuildable
+// like the block `embeddings` cache; keyed by doc_id (not content_hash) because
+// a document has no single stable content hash across block edits.
+export const DOC_EMBEDDINGS_DDL = /* sql */ `
+CREATE TABLE IF NOT EXISTS doc_embeddings (
+  doc_id     TEXT NOT NULL,
+  model      TEXT NOT NULL,
+  input_hash BLOB NOT NULL,
+  method     TEXT NOT NULL CHECK (method IN ('whole','pooled')),
+  dim        INTEGER NOT NULL,
+  vec        BLOB NOT NULL,
+  PRIMARY KEY (doc_id, model)
+);
+`;
+// Additive migrations keyed by the version they upgrade TO. Each runs inside a
+// transaction. Only forward, idempotent DDL (CREATE ... IF NOT EXISTS) — no
+// destructive changes. store.ts applies these in order for an older db.
+// Migrations 3, 4, 6, 7, 9, 11 are programmatic — see store.ts.
+export const MIGRATIONS = {
+    2: FILE_STATS_DDL,
+    3: "", // handled programmatically in store.ts
+    4: "", // handled programmatically in store.ts
+    5: NODES_DDL,
+    6: "", // handled programmatically in store.ts
+    7: "", // handled programmatically in store.ts
+    8: PROPERTIES_DDL,
+    9: "", // SYNC_DDL + repos.root_path→nullable, handled programmatically in store.ts
+    10: WORKSPACE_SETTINGS_DDL,
+    11: "", // ALTER TABLE documents RENAME TO docs, handled programmatically in store.ts
+    12: DOC_EMBEDDINGS_DDL, // doc-grain semantic vectors
+    13: "", // drop repos.root_path (migrate → fs sources), handled programmatically in store.ts
+};
+export const DDL = /* sql */ `
+-- ---- durable tables (02 §3) --------------------------------------------------
+CREATE TABLE IF NOT EXISTS repos (
+  repo_id   TEXT PRIMARY KEY,
+  slug      TEXT NOT NULL UNIQUE,
+  settings  TEXT NOT NULL DEFAULT '{}'
+);
+-- A repo owns identity + history, NOT a filesystem (ADR-014). Where its bytes
+-- come from is a sources row (adapter=fs, config.root) joined via attachments;
+-- the former repos.root_path column was removed in schema v13.
+
+CREATE TABLE IF NOT EXISTS docs (
+  doc_id         TEXT PRIMARY KEY,
+  repo_id        TEXT NOT NULL REFERENCES repos(repo_id),
+  path           TEXT NOT NULL,
+  format         TEXT NOT NULL DEFAULT 'markdown',
+  current_rev    TEXT,
+  file_hash      BLOB,
+  conflicted     INTEGER NOT NULL DEFAULT 0,
+  leading_trivia TEXT NOT NULL DEFAULT '',
+  frontmatter_trivia TEXT,                  -- separator between frontmatter and first body block (NULL = no frontmatter)
+  deleted_commit TEXT,
+  UNIQUE (repo_id, path)
+);
+
+CREATE TABLE IF NOT EXISTS blocks (
+  block_id       TEXT PRIMARY KEY,
+  repo_id        TEXT NOT NULL REFERENCES repos(repo_id),
+  doc_id         TEXT NOT NULL REFERENCES docs(doc_id),
+  parent_block   TEXT,
+  order_key      TEXT NOT NULL,
+  ordinal        INTEGER NOT NULL,
+  depth          INTEGER NOT NULL,
+  ancestor_path  TEXT NOT NULL,
+  type           TEXT NOT NULL,
+  attrs          TEXT NOT NULL DEFAULT '{}',
+  text           TEXT NOT NULL,
+  raw_hash       BLOB NOT NULL,
+  norm_hash      BLOB NOT NULL,
+  trivia_hash    BLOB,                     -- trailing trivia blob hash (NULL = no trivia)
+  created_commit TEXT NOT NULL,
+  deleted_commit TEXT
+);
+CREATE INDEX IF NOT EXISTS idx_blocks_doc      ON blocks(doc_id, parent_block, order_key) WHERE deleted_commit IS NULL;
+CREATE INDEX IF NOT EXISTS idx_blocks_type     ON blocks(repo_id, type)                   WHERE deleted_commit IS NULL;
+CREATE INDEX IF NOT EXISTS idx_blocks_rawhash  ON blocks(raw_hash);
+CREATE INDEX IF NOT EXISTS idx_blocks_ancestor ON blocks(doc_id, ancestor_path);
+
+CREATE TABLE IF NOT EXISTS blobs (
+  hash  BLOB PRIMARY KEY,
+  bytes BLOB NOT NULL,
+  size  INTEGER NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS tree_nodes (
+  hash    BLOB PRIMARY KEY,
+  entries TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS revisions (
+  rev_id           TEXT PRIMARY KEY,
+  doc_id           TEXT NOT NULL REFERENCES docs(doc_id),
+  seq              INTEGER NOT NULL,
+  root_tree        BLOB NOT NULL REFERENCES tree_nodes(hash),
+  frontmatter_blob BLOB REFERENCES blobs(hash),
+  rendered_hash    BLOB NOT NULL,
+  path             TEXT NOT NULL,
+  commit_id        TEXT NOT NULL REFERENCES commits(commit_id),
+  UNIQUE (doc_id, seq)
+);
+
+CREATE TABLE IF NOT EXISTS commits (
+  commit_id     TEXT PRIMARY KEY,
+  repo_id       TEXT NOT NULL REFERENCES repos(repo_id),
+  seq           INTEGER NOT NULL,
+  ts            TEXT NOT NULL,
+  origin        TEXT NOT NULL CHECK (origin IN ('api','observed','import','projection')),
+  actor         TEXT,
+  reason        TEXT,
+  checkpoint_id TEXT,
+  ops           TEXT,
+  UNIQUE (repo_id, seq)
+);
+
+CREATE TABLE IF NOT EXISTS dispositions (
+  commit_id  TEXT NOT NULL REFERENCES commits(commit_id),
+  block_id   TEXT NOT NULL,
+  kind       TEXT NOT NULL CHECK (kind IN
+             ('same','edited','moved','edited_moved','inserted','deleted',
+              'split_from','merged_into','copied_from','resurrected','bulk_rewrite')),
+  confidence REAL,
+  reason     TEXT,
+  matcher_v  TEXT,
+  detail     TEXT NOT NULL DEFAULT '{}',
+  PRIMARY KEY (commit_id, block_id, kind)
+);
+
+CREATE TABLE IF NOT EXISTS edges (
+  edge_id     TEXT PRIMARY KEY,
+  repo_id     TEXT NOT NULL,
+  src_doc     TEXT NOT NULL,
+  src_block   TEXT,
+  src_field   TEXT,
+  predicate   TEXT NOT NULL,
+  dst_kind    TEXT NOT NULL CHECK (dst_kind IN ('document','block','external','collection')),
+  dst_node    TEXT NOT NULL,
+  anchor      TEXT,
+  provenance  TEXT NOT NULL CHECK (provenance IN ('link','frontmatter','inline_field','projected',
+               'yaml_ref','yaml_schema','yaml_extends','json_ref','json_schema')),
+  via_node    TEXT,
+  from_commit TEXT NOT NULL,
+  to_commit   TEXT
+);
+CREATE INDEX IF NOT EXISTS idx_edges_src      ON edges(src_doc, predicate) WHERE to_commit IS NULL;
+CREATE INDEX IF NOT EXISTS idx_edges_dst      ON edges(dst_node, predicate) WHERE to_commit IS NULL;
+CREATE INDEX IF NOT EXISTS idx_edges_temporal ON edges(from_commit, to_commit);
+
+CREATE TABLE IF NOT EXISTS external_nodes (
+  node_id TEXT PRIMARY KEY,
+  repo_id TEXT NOT NULL,
+  uri     TEXT NOT NULL,
+  title   TEXT,
+  UNIQUE (repo_id, uri)
+);
+
+CREATE TABLE IF NOT EXISTS collections (
+  node_id TEXT PRIMARY KEY,
+  repo_id TEXT NOT NULL,
+  name    TEXT NOT NULL,
+  spec    TEXT NOT NULL DEFAULT '{}'
+);
+
+CREATE TABLE IF NOT EXISTS checkpoints (
+  id       TEXT PRIMARY KEY,
+  repo_id  TEXT NOT NULL,
+  ts       TEXT NOT NULL,
+  files    TEXT NOT NULL,
+  git_head TEXT
+);
+
+CREATE TABLE IF NOT EXISTS resurrection_pool (
+  block_id       TEXT PRIMARY KEY,
+  repo_id        TEXT NOT NULL,
+  doc_id         TEXT NOT NULL,
+  raw_hash       BLOB NOT NULL,
+  norm_hash      BLOB NOT NULL,
+  type           TEXT NOT NULL,
+  deleted_commit TEXT NOT NULL,
+  expires_ts     TEXT NOT NULL
+);
+
+-- ---- derived tables (02 §4; rebuildable) ------------------------------------
+CREATE TABLE IF NOT EXISTS sections (
+  heading_block TEXT NOT NULL,
+  doc_id        TEXT NOT NULL,
+  level         INTEGER NOT NULL,
+  first_ordinal INTEGER NOT NULL,
+  last_ordinal  INTEGER NOT NULL,
+  PRIMARY KEY (doc_id, heading_block)
+);
+
+CREATE TABLE IF NOT EXISTS doc_edges (
+  src_doc   TEXT NOT NULL,
+  predicate TEXT NOT NULL,
+  dst_node  TEXT NOT NULL,
+  dst_kind  TEXT NOT NULL,
+  count     INTEGER NOT NULL,
+  samples   TEXT NOT NULL,
+  PRIMARY KEY (src_doc, predicate, dst_node)
+);
+
+CREATE TABLE IF NOT EXISTS block_changes (
+  block_id  TEXT NOT NULL,
+  commit_id TEXT NOT NULL,
+  kind      TEXT NOT NULL,
+  PRIMARY KEY (block_id, commit_id, kind)
+);
+
+CREATE TABLE IF NOT EXISTS inferred_edges (
+  src_node    TEXT NOT NULL,
+  dst_node    TEXT NOT NULL,
+  predicate   TEXT NOT NULL,
+  method      TEXT NOT NULL,
+  score       REAL NOT NULL,
+  model_v     TEXT NOT NULL,
+  computed_at TEXT NOT NULL,
+  PRIMARY KEY (src_node, dst_node, predicate, method)
+);
+
+CREATE TABLE IF NOT EXISTS embeddings (
+  content_hash BLOB NOT NULL,
+  ctx_hash     BLOB NOT NULL,
+  model        TEXT NOT NULL,
+  dim          INTEGER NOT NULL,
+  vec          BLOB NOT NULL,
+  PRIMARY KEY (content_hash, ctx_hash, model)
+);
+
+${DOC_EMBEDDINGS_DDL}
+
+CREATE VIRTUAL TABLE IF NOT EXISTS blocks_fts USING fts5(
+  text, content='blocks', content_rowid='rowid', tokenize='porter unicode61'
+);
+
+CREATE TABLE IF NOT EXISTS nodes (
+  node_id    TEXT PRIMARY KEY,
+  repo_id    TEXT NOT NULL,
+  doc_id     TEXT NOT NULL,
+  block_id   TEXT,
+  kind       TEXT NOT NULL,
+  name       TEXT,
+  value      TEXT,
+  span_start INTEGER,
+  span_end   INTEGER,
+  attrs      TEXT NOT NULL DEFAULT '{}'
+);
+CREATE INDEX IF NOT EXISTS idx_nodes_doc  ON nodes(doc_id);
+CREATE INDEX IF NOT EXISTS idx_nodes_kind ON nodes(kind);
+CREATE INDEX IF NOT EXISTS idx_nodes_name ON nodes(name) WHERE name IS NOT NULL;
+
+CREATE VIRTUAL TABLE IF NOT EXISTS nodes_fts USING fts5(
+  name, value, content='nodes', content_rowid='rowid', tokenize='porter unicode61'
+);
+
+${FILE_STATS_DDL}
+${PROPERTIES_DDL}
+${SYNC_DDL}
+${WORKSPACE_SETTINGS_DDL}
+`;
+//# sourceMappingURL=schema.js.map

package/dist/src/core/store/sections.d.ts

@@ -0,0 +1,2 @@
+import type { Database } from "better-sqlite3";
+export declare function rebuildSections(db: Database, docId: string): void;

package/dist/src/core/store/sections.js

@@ -0,0 +1,29 @@
+export function rebuildSections(db, docId) {
+    db.prepare("DELETE FROM sections WHERE doc_id = ?").run(docId);
+    const tops = db
+        .prepare(`SELECT block_id, ordinal, type,
+              json_extract(attrs, '$.level') AS level
+       FROM blocks
+       WHERE doc_id = ? AND parent_block IS NULL AND deleted_commit IS NULL
+       ORDER BY ordinal`)
+        .all(docId);
+    const maxOrdinal = tops.length > 0 ? tops[tops.length - 1].ordinal : -1;
+    const headings = tops.filter((t) => t.type === "heading");
+    const insert = db.prepare(`INSERT INTO sections (heading_block, doc_id, level, first_ordinal, last_ordinal)
+     VALUES (?, ?, ?, ?, ?)`);
+    for (let i = 0; i < headings.length; i++) {
+        const h = headings[i];
+        const level = h.level ?? 1;
+        // last_ordinal = one before the next heading with level <= this one.
+        let last = maxOrdinal;
+        for (let j = i + 1; j < headings.length; j++) {
+            const next = headings[j];
+            if ((next.level ?? 1) <= level) {
+                last = next.ordinal - 1;
+                break;
+            }
+        }
+        insert.run(h.block_id, docId, level, h.ordinal, last);
+    }
+}
+//# sourceMappingURL=sections.js.map

package/dist/src/core/store/store.d.ts

@@ -0,0 +1,24 @@
+import Database from "better-sqlite3";
+export interface StoreOptions {
+    /** ':memory:' for tests, or a filesystem path (parent dirs created). */
+    path: string;
+}
+export declare class Store {
+    readonly db: Database.Database;
+    constructor(opts: StoreOptions);
+    private migrate;
+    private migrateV3;
+    private migrateV4;
+    private migrateV6;
+    private migrateV7;
+    private migrateV9;
+    private migrateV11;
+    private migrateV13;
+    /**
+     * Run fn inside a single write transaction (02 §2: one transaction per
+     * commit). better-sqlite3 transactions are synchronous and serialized.
+     */
+    write<T>(fn: (db: Database.Database) => T): T;
+    pragma(name: string): unknown;
+    close(): void;
+}

package/dist/src/core/store/store.js

@@ -0,0 +1,164 @@
+import Database from "better-sqlite3";
+import { mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+import { DDL, SCHEMA_VERSION, MIGRATIONS, SYNC_DDL } from "./schema.js";
+import { cosineBytes } from "../vec.js";
+import { mintId } from "../ids.js";
+export class Store {
+    db;
+    constructor(opts) {
+        if (opts.path !== ":memory:")
+            mkdirSync(dirname(opts.path), { recursive: true });
+        this.db = new Database(opts.path);
+        this.db.pragma("journal_mode = WAL");
+        this.db.pragma("synchronous = NORMAL");
+        this.db.pragma("foreign_keys = ON");
+        // cosine(vecBlob, queryBlob) → REAL: the similarity used by OQX's semantic()
+        // scalar. Deterministic (same inputs → same score) so SQLite may cache it.
+        this.db.function("cosine", { deterministic: true }, (a, b) => cosineBytes(a, b));
+        this.migrate();
+    }
+    migrate() {
+        const current = this.db.pragma("user_version", { simple: true });
+        if (current === 0) {
+            this.db.exec(DDL);
+            this.db.pragma(`user_version = ${SCHEMA_VERSION}`);
+            return;
+        }
+        if (current === SCHEMA_VERSION)
+            return;
+        if (current > SCHEMA_VERSION) {
+            throw new Error(`database schema (v${current}) is newer than this build (v${SCHEMA_VERSION}); upgrade omgbase`);
+        }
+        // Apply forward additive migrations in order (each idempotent DDL).
+        for (let v = current + 1; v <= SCHEMA_VERSION; v++) {
+            if (v === 3) {
+                this.migrateV3();
+                continue;
+            }
+            if (v === 4) {
+                this.migrateV4();
+                continue;
+            }
+            if (v === 6) {
+                this.migrateV6();
+                continue;
+            }
+            if (v === 7) {
+                this.migrateV7();
+                continue;
+            }
+            if (v === 9) {
+                this.migrateV9();
+                continue;
+            }
+            if (v === 11) {
+                this.migrateV11();
+                continue;
+            }
+            if (v === 13) {
+                this.migrateV13();
+                continue;
+            }
+            const ddl = MIGRATIONS[v];
+            if (!ddl)
+                throw new Error(`no migration to schema v${v}`);
+            this.db.exec(ddl);
+        }
+        this.db.pragma(`user_version = ${SCHEMA_VERSION}`);
+    }
+    migrateV3() {
+        const cols = this.db.pragma("table_info(documents)");
+        if (cols.length > 0 && !cols.some((c) => c.name === "format")) {
+            this.db.exec("ALTER TABLE documents ADD COLUMN format TEXT NOT NULL DEFAULT 'markdown'");
+        }
+    }
+    migrateV4() {
+        const cols = this.db.pragma("table_info(documents)");
+        if (cols.length > 0 && cols.some((c) => c.name === "frontmatter") && !cols.some((c) => c.name === "metadata")) {
+            this.db.exec("ALTER TABLE documents RENAME COLUMN frontmatter TO metadata");
+        }
+    }
+    migrateV6() {
+        const docCols = this.db.pragma("table_info(documents)");
+        if (docCols.length > 0 && !docCols.some((c) => c.name === "leading_trivia")) {
+            this.db.exec("ALTER TABLE documents ADD COLUMN leading_trivia TEXT NOT NULL DEFAULT ''");
+        }
+        const blockCols = this.db.pragma("table_info(blocks)");
+        if (blockCols.length > 0 && !blockCols.some((c) => c.name === "trivia_hash")) {
+            this.db.exec("ALTER TABLE blocks ADD COLUMN trivia_hash BLOB");
+        }
+    }
+    migrateV7() {
+        const docCols = this.db.pragma("table_info(documents)");
+        if (docCols.length > 0 && !docCols.some((c) => c.name === "frontmatter_trivia")) {
+            this.db.exec("ALTER TABLE documents ADD COLUMN frontmatter_trivia TEXT");
+        }
+    }
+    // v9 (sync-plugins): add the adapters/sources/attachments/sync_state tables.
+    // repos.root_path is relaxed to nullable in the base DDL for fresh dbs; an
+    // existing NOT NULL column still accepts all prior (non-null) rows, so no table
+    // rebuild is needed to migrate — new nullable inserts only happen on fresh dbs.
+    migrateV9() {
+        this.db.exec(SYNC_DDL);
+    }
+    // v11: rename the `documents` table to `docs`. SQLite (>= 3.25, legacy_alter_table
+    // off by default) rewrites the FK references in blocks/revisions automatically,
+    // so no child-table rebuild is needed. Idempotent: skip if `docs` already exists
+    // (fresh dbs get `docs` straight from the DDL and never run this).
+    migrateV11() {
+        const tableExists = (name) => !!this.db.prepare("SELECT 1 FROM sqlite_master WHERE type='table' AND name=?").get(name);
+        // Fresh dbs already have `docs` from the DDL; a `documents` table only exists
+        // on real pre-v11 dbs. Rename only when the old table is present and the new
+        // one is not — otherwise there's nothing to do.
+        if (tableExists("docs") || !tableExists("documents"))
+            return;
+        this.db.exec("ALTER TABLE documents RENAME TO docs");
+    }
+    // v13 (ADR-014): a repo owns identity, not a filesystem. Drop repos.root_path,
+    // migrating each repo's former root_path into an `fs` source + attachment (the
+    // durable "where its bytes come from"). Idempotent: skip if the column is gone
+    // (fresh dbs get the columnless repos table straight from the DDL). Runs in one
+    // transaction; DROP COLUMN needs modern SQLite (>= 3.35, bundled by
+    // better-sqlite3), and root_path is a plain unindexed column so it drops cleanly.
+    migrateV13() {
+        const cols = this.db.pragma("table_info(repos)");
+        if (cols.length === 0 || !cols.some((c) => c.name === "root_path"))
+            return;
+        this.db.transaction(() => {
+            // The fs adapter row backs the migrated sources (sources.adapter FK).
+            this.db.exec("INSERT OR IGNORE INTO adapters (name, command, args) VALUES ('fs', 'omgbase-fs-adapter', '[]')");
+            const repos = this.db
+                .prepare("SELECT repo_id, slug, root_path FROM repos WHERE root_path IS NOT NULL AND root_path != ''")
+                .all();
+            const findByName = this.db.prepare("SELECT source_id FROM sources WHERE name = ?");
+            const insSource = this.db.prepare("INSERT INTO sources (source_id, name, adapter, config, env) VALUES (?, ?, 'fs', ?, '{}')");
+            const insAttach = this.db.prepare("INSERT OR IGNORE INTO attachments (repo_id, source_id) VALUES (?, ?)");
+            for (const r of repos) {
+                const name = `${r.slug}-fs`;
+                const existing = findByName.get(name);
+                let sourceId = existing?.source_id;
+                if (!sourceId) {
+                    sourceId = mintId("src");
+                    insSource.run(sourceId, name, JSON.stringify({ root: r.root_path }));
+                }
+                insAttach.run(r.repo_id, sourceId);
+            }
+            this.db.exec("ALTER TABLE repos DROP COLUMN root_path");
+        })();
+    }
+    /**
+     * Run fn inside a single write transaction (02 §2: one transaction per
+     * commit). better-sqlite3 transactions are synchronous and serialized.
+     */
+    write(fn) {
+        return this.db.transaction(fn)(this.db);
+    }
+    pragma(name) {
+        return this.db.pragma(name, { simple: true });
+    }
+    close() {
+        this.db.close();
+    }
+}
+//# sourceMappingURL=store.js.map

package/dist/src/core/store/writers.d.ts

@@ -0,0 +1,52 @@
+import type { Database } from "better-sqlite3";
+import { type TreeEntry } from "../hash.js";
+import type { RawBlock } from "../parse/types.js";
+/** A block with a minted/assigned id, ready to encode into the tree. */
+export interface TreeInputBlock {
+    blockId: string;
+    type: string;
+    raw: string;
+    trivia: string;
+    attrs: Record<string, unknown>;
+    children: TreeInputBlock[];
+}
+/** Assign fresh minted ids to a parsed block tree (Stage-1 re-mint path). */
+export declare function assignIds(blocks: RawBlock[]): TreeInputBlock[];
+/** Content-address raw text into blobs; returns hex hash. Dedups. */
+export declare function putBlob(db: Database, text: string): string;
+/** Content-address a tree node's entries; returns hex hash. Dedups. */
+export declare function putTreeNode(db: Database, entries: TreeEntry[]): string;
+/**
+ * Encode a list of sibling blocks into a Merkle tree node bottom-up, writing
+ * blobs (raw + trivia) and child tree nodes. Returns the node's hex hash.
+ * Structural sharing: unchanged subtrees produce identical hashes and are not
+ * re-inserted.
+ */
+export declare function writeBlockTree(db: Database, blocks: TreeInputBlock[]): string;
+export interface NewCommitInput {
+    repoId: string;
+    ts: string;
+    origin: "api" | "observed" | "import" | "projection";
+    actor?: string | null;
+    reason?: string | null;
+    checkpointId?: string | null;
+    ops?: string | null;
+}
+/** Append a commit; assigns the per-repo total-order seq. */
+export declare function newCommit(db: Database, input: NewCommitInput): {
+    commitId: string;
+    seq: number;
+};
+export interface NewRevisionInput {
+    docId: string;
+    rootTreeHex: string;
+    frontmatterBlobHex: string | null;
+    renderedHash: Buffer;
+    path: string;
+    commitId: string;
+}
+/** Append a revision; assigns the per-document monotonic seq. */
+export declare function writeRevision(db: Database, input: NewRevisionInput): {
+    revId: string;
+    seq: number;
+};