@omgbase/core 0.11.1 → 0.19.0

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

@@ -1,9 +1,10 @@
-export declare const SCHEMA_VERSION = 13;
+export declare const SCHEMA_VERSION = 14;
 export declare const FILE_STATS_DDL = "\nCREATE TABLE IF NOT EXISTS file_stats (\n  repo_id  TEXT NOT NULL,\n  path     TEXT NOT NULL,\n  mtime_ns INTEGER NOT NULL,\n  size     INTEGER NOT NULL,\n  hash     BLOB NOT NULL,\n  PRIMARY KEY (repo_id, path)\n);\n";
 export declare const PROPERTIES_DDL = "\nCREATE TABLE IF NOT EXISTS properties (\n  prop_id        TEXT PRIMARY KEY,\n  repo_id        TEXT NOT NULL,\n  doc_id         TEXT NOT NULL,\n  block_id       TEXT,                    -- NULL = document-scoped (frontmatter, computed)\n  source         TEXT NOT NULL CHECK (source IN ('frontmatter','inline','computed')),\n  key            TEXT NOT NULL,           -- dotted, flattened: \"layer\",\"meta.owner\"; computed carry $: \"$title\"\n  card           TEXT NOT NULL CHECK (card IN ('scalar','list')),\n  ord            INTEGER NOT NULL DEFAULT 0,\n  val_text       TEXT,\n  val_num        REAL,\n  val_bool       INTEGER,\n  val_json       TEXT,\n  type           TEXT NOT NULL CHECK (type IN ('string','number','bool','null','json')),\n  created_commit TEXT NOT NULL,\n  deleted_commit TEXT\n);\nCREATE INDEX IF NOT EXISTS idx_props_doc      ON properties(doc_id)                 WHERE deleted_commit IS NULL;\nCREATE INDEX IF NOT EXISTS idx_props_key_text ON properties(repo_id, key, val_text) WHERE deleted_commit IS NULL;\nCREATE INDEX IF NOT EXISTS idx_props_key_num  ON properties(repo_id, key, val_num)  WHERE deleted_commit IS NULL;\nCREATE INDEX IF NOT EXISTS idx_props_src_key  ON properties(repo_id, source, key)   WHERE deleted_commit IS NULL;\n";
 export declare const SYNC_DDL = "\nCREATE TABLE IF NOT EXISTS adapters (\n  name     TEXT PRIMARY KEY,        -- workspace-unique adapter name (e.g. \"fs\")\n  command  TEXT NOT NULL,           -- argv[0] to spawn (e.g. \"omgbase-fs-adapter\")\n  args     TEXT NOT NULL DEFAULT '[]'  -- fixed leading args (JSON string[])\n);\n\nCREATE TABLE IF NOT EXISTS sources (\n  source_id TEXT PRIMARY KEY,\n  name      TEXT NOT NULL UNIQUE,   -- workspace-unique source name\n  adapter   TEXT NOT NULL REFERENCES adapters(name),\n  config    TEXT NOT NULL DEFAULT '{}',  -- JSON object \u2192 rendered to flags (13 \u00A73.1)\n  env       TEXT NOT NULL DEFAULT '{}'   -- JSON object \u2192 spawn env (secrets; 13 \u00A73.2)\n);\n\nCREATE TABLE IF NOT EXISTS attachments (\n  repo_id   TEXT NOT NULL REFERENCES repos(repo_id),\n  source_id TEXT NOT NULL REFERENCES sources(source_id),\n  PRIMARY KEY (repo_id, source_id)\n);\n\nCREATE TABLE IF NOT EXISTS sync_state (\n  repo_id   TEXT NOT NULL,\n  source_id TEXT NOT NULL,\n  path      TEXT NOT NULL,          -- '' reserved for the attachment-level cursor row\n  revision  TEXT,                   -- last-observed source revision for this path\n  cursor    TEXT,                   -- last poll/webhook cursor (attachment-level row)\n  PRIMARY KEY (repo_id, source_id, path)\n);\n";
 export declare const WORKSPACE_SETTINGS_DDL = "\nCREATE TABLE IF NOT EXISTS workspace_settings (\n  id       INTEGER PRIMARY KEY CHECK (id = 0),\n  settings TEXT NOT NULL DEFAULT '{}'\n);\nINSERT OR IGNORE INTO workspace_settings (id, settings) VALUES (0, '{}');\n";
 export declare const NODES_DDL = "\nCREATE TABLE IF NOT EXISTS nodes (\n  node_id    TEXT PRIMARY KEY,\n  repo_id    TEXT NOT NULL,\n  doc_id     TEXT NOT NULL,\n  block_id   TEXT,\n  kind       TEXT NOT NULL,\n  name       TEXT,\n  value      TEXT,\n  span_start INTEGER,\n  span_end   INTEGER,\n  attrs      TEXT NOT NULL DEFAULT '{}'\n);\nCREATE INDEX IF NOT EXISTS idx_nodes_doc  ON nodes(doc_id);\nCREATE INDEX IF NOT EXISTS idx_nodes_kind ON nodes(kind);\nCREATE INDEX IF NOT EXISTS idx_nodes_name ON nodes(name) WHERE name IS NOT NULL;\nCREATE VIRTUAL TABLE IF NOT EXISTS nodes_fts USING fts5(\n  name, value, content='nodes', content_rowid='rowid', tokenize='porter unicode61'\n);\n";
 export declare const DOC_EMBEDDINGS_DDL = "\nCREATE TABLE IF NOT EXISTS doc_embeddings (\n  doc_id     TEXT NOT NULL,\n  model      TEXT NOT NULL,\n  input_hash BLOB NOT NULL,\n  method     TEXT NOT NULL CHECK (method IN ('whole','pooled')),\n  dim        INTEGER NOT NULL,\n  vec        BLOB NOT NULL,\n  PRIMARY KEY (doc_id, model)\n);\n";
+export declare const PENDING_MATERIALIZATIONS_DDL = "\nCREATE TABLE IF NOT EXISTS pending_materializations (\n  repo_id       TEXT NOT NULL REFERENCES repos(repo_id),\n  path          TEXT NOT NULL,                 -- where the file must end up\n  kind          TEXT NOT NULL CHECK (kind IN ('write','rename','remove')),\n  from_path     TEXT,                          -- rename: the old path\n  doc_id        TEXT NOT NULL REFERENCES docs(doc_id),\n  rev_id        TEXT REFERENCES revisions(rev_id),   -- write/rename: the revision the bytes render (NULL for remove)\n  rendered_hash BLOB NOT NULL,                 -- the bytes expected at path (remove: the bytes it is safe to unlink)\n  commit_id     TEXT NOT NULL REFERENCES commits(commit_id),\n  PRIMARY KEY (repo_id, path)\n);\n";
 export declare const MIGRATIONS: Record<number, string>;
-export declare const DDL = "\n-- ---- durable tables (02 \u00A73) --------------------------------------------------\nCREATE TABLE IF NOT EXISTS repos (\n  repo_id   TEXT PRIMARY KEY,\n  slug      TEXT NOT NULL UNIQUE,\n  settings  TEXT NOT NULL DEFAULT '{}'\n);\n-- A repo owns identity + history, NOT a filesystem (ADR-014). Where its bytes\n-- come from is a sources row (adapter=fs, config.root) joined via attachments;\n-- the former repos.root_path column was removed in schema v13.\n\nCREATE TABLE IF NOT EXISTS docs (\n  doc_id         TEXT PRIMARY KEY,\n  repo_id        TEXT NOT NULL REFERENCES repos(repo_id),\n  path           TEXT NOT NULL,\n  format         TEXT NOT NULL DEFAULT 'markdown',\n  current_rev    TEXT,\n  file_hash      BLOB,\n  conflicted     INTEGER NOT NULL DEFAULT 0,\n  leading_trivia TEXT NOT NULL DEFAULT '',\n  frontmatter_trivia TEXT,                  -- separator between frontmatter and first body block (NULL = no frontmatter)\n  deleted_commit TEXT,\n  UNIQUE (repo_id, path)\n);\n\nCREATE TABLE IF NOT EXISTS blocks (\n  block_id       TEXT PRIMARY KEY,\n  repo_id        TEXT NOT NULL REFERENCES repos(repo_id),\n  doc_id         TEXT NOT NULL REFERENCES docs(doc_id),\n  parent_block   TEXT,\n  order_key      TEXT NOT NULL,\n  ordinal        INTEGER NOT NULL,\n  depth          INTEGER NOT NULL,\n  ancestor_path  TEXT NOT NULL,\n  type           TEXT NOT NULL,\n  attrs          TEXT NOT NULL DEFAULT '{}',\n  text           TEXT NOT NULL,\n  raw_hash       BLOB NOT NULL,\n  norm_hash      BLOB NOT NULL,\n  trivia_hash    BLOB,                     -- trailing trivia blob hash (NULL = no trivia)\n  created_commit TEXT NOT NULL,\n  deleted_commit TEXT\n);\nCREATE INDEX IF NOT EXISTS idx_blocks_doc      ON blocks(doc_id, parent_block, order_key) WHERE deleted_commit IS NULL;\nCREATE INDEX IF NOT EXISTS idx_blocks_type     ON blocks(repo_id, type)                   WHERE deleted_commit IS NULL;\nCREATE INDEX IF NOT EXISTS idx_blocks_rawhash  ON blocks(raw_hash);\nCREATE INDEX IF NOT EXISTS idx_blocks_ancestor ON blocks(doc_id, ancestor_path);\n\nCREATE TABLE IF NOT EXISTS blobs (\n  hash  BLOB PRIMARY KEY,\n  bytes BLOB NOT NULL,\n  size  INTEGER NOT NULL\n);\n\nCREATE TABLE IF NOT EXISTS tree_nodes (\n  hash    BLOB PRIMARY KEY,\n  entries TEXT NOT NULL\n);\n\nCREATE TABLE IF NOT EXISTS revisions (\n  rev_id           TEXT PRIMARY KEY,\n  doc_id           TEXT NOT NULL REFERENCES docs(doc_id),\n  seq              INTEGER NOT NULL,\n  root_tree        BLOB NOT NULL REFERENCES tree_nodes(hash),\n  frontmatter_blob BLOB REFERENCES blobs(hash),\n  rendered_hash    BLOB NOT NULL,\n  path             TEXT NOT NULL,\n  commit_id        TEXT NOT NULL REFERENCES commits(commit_id),\n  UNIQUE (doc_id, seq)\n);\n\nCREATE TABLE IF NOT EXISTS commits (\n  commit_id     TEXT PRIMARY KEY,\n  repo_id       TEXT NOT NULL REFERENCES repos(repo_id),\n  seq           INTEGER NOT NULL,\n  ts            TEXT NOT NULL,\n  origin        TEXT NOT NULL CHECK (origin IN ('api','observed','import','projection')),\n  actor         TEXT,\n  reason        TEXT,\n  checkpoint_id TEXT,\n  ops           TEXT,\n  UNIQUE (repo_id, seq)\n);\n\nCREATE TABLE IF NOT EXISTS dispositions (\n  commit_id  TEXT NOT NULL REFERENCES commits(commit_id),\n  block_id   TEXT NOT NULL,\n  kind       TEXT NOT NULL CHECK (kind IN\n             ('same','edited','moved','edited_moved','inserted','deleted',\n              'split_from','merged_into','copied_from','resurrected','bulk_rewrite')),\n  confidence REAL,\n  reason     TEXT,\n  matcher_v  TEXT,\n  detail     TEXT NOT NULL DEFAULT '{}',\n  PRIMARY KEY (commit_id, block_id, kind)\n);\n\nCREATE TABLE IF NOT EXISTS edges (\n  edge_id     TEXT PRIMARY KEY,\n  repo_id     TEXT NOT NULL,\n  src_doc     TEXT NOT NULL,\n  src_block   TEXT,\n  src_field   TEXT,\n  predicate   TEXT NOT NULL,\n  dst_kind    TEXT NOT NULL CHECK (dst_kind IN ('document','block','external','collection')),\n  dst_node    TEXT NOT NULL,\n  anchor      TEXT,\n  provenance  TEXT NOT NULL CHECK (provenance IN ('link','frontmatter','inline_field','projected',\n               'yaml_ref','yaml_schema','yaml_extends','json_ref','json_schema')),\n  via_node    TEXT,\n  from_commit TEXT NOT NULL,\n  to_commit   TEXT\n);\nCREATE INDEX IF NOT EXISTS idx_edges_src      ON edges(src_doc, predicate) WHERE to_commit IS NULL;\nCREATE INDEX IF NOT EXISTS idx_edges_dst      ON edges(dst_node, predicate) WHERE to_commit IS NULL;\nCREATE INDEX IF NOT EXISTS idx_edges_temporal ON edges(from_commit, to_commit);\n\nCREATE TABLE IF NOT EXISTS external_nodes (\n  node_id TEXT PRIMARY KEY,\n  repo_id TEXT NOT NULL,\n  uri     TEXT NOT NULL,\n  title   TEXT,\n  UNIQUE (repo_id, uri)\n);\n\nCREATE TABLE IF NOT EXISTS collections (\n  node_id TEXT PRIMARY KEY,\n  repo_id TEXT NOT NULL,\n  name    TEXT NOT NULL,\n  spec    TEXT NOT NULL DEFAULT '{}'\n);\n\nCREATE TABLE IF NOT EXISTS checkpoints (\n  id       TEXT PRIMARY KEY,\n  repo_id  TEXT NOT NULL,\n  ts       TEXT NOT NULL,\n  files    TEXT NOT NULL,\n  git_head TEXT\n);\n\nCREATE TABLE IF NOT EXISTS resurrection_pool (\n  block_id       TEXT PRIMARY KEY,\n  repo_id        TEXT NOT NULL,\n  doc_id         TEXT NOT NULL,\n  raw_hash       BLOB NOT NULL,\n  norm_hash      BLOB NOT NULL,\n  type           TEXT NOT NULL,\n  deleted_commit TEXT NOT NULL,\n  expires_ts     TEXT NOT NULL\n);\n\n-- ---- derived tables (02 \u00A74; rebuildable) ------------------------------------\nCREATE TABLE IF NOT EXISTS sections (\n  heading_block TEXT NOT NULL,\n  doc_id        TEXT NOT NULL,\n  level         INTEGER NOT NULL,\n  first_ordinal INTEGER NOT NULL,\n  last_ordinal  INTEGER NOT NULL,\n  PRIMARY KEY (doc_id, heading_block)\n);\n\nCREATE TABLE IF NOT EXISTS doc_edges (\n  src_doc   TEXT NOT NULL,\n  predicate TEXT NOT NULL,\n  dst_node  TEXT NOT NULL,\n  dst_kind  TEXT NOT NULL,\n  count     INTEGER NOT NULL,\n  samples   TEXT NOT NULL,\n  PRIMARY KEY (src_doc, predicate, dst_node)\n);\n\nCREATE TABLE IF NOT EXISTS block_changes (\n  block_id  TEXT NOT NULL,\n  commit_id TEXT NOT NULL,\n  kind      TEXT NOT NULL,\n  PRIMARY KEY (block_id, commit_id, kind)\n);\n\nCREATE TABLE IF NOT EXISTS inferred_edges (\n  src_node    TEXT NOT NULL,\n  dst_node    TEXT NOT NULL,\n  predicate   TEXT NOT NULL,\n  method      TEXT NOT NULL,\n  score       REAL NOT NULL,\n  model_v     TEXT NOT NULL,\n  computed_at TEXT NOT NULL,\n  PRIMARY KEY (src_node, dst_node, predicate, method)\n);\n\nCREATE TABLE IF NOT EXISTS embeddings (\n  content_hash BLOB NOT NULL,\n  ctx_hash     BLOB NOT NULL,\n  model        TEXT NOT NULL,\n  dim          INTEGER NOT NULL,\n  vec          BLOB NOT NULL,\n  PRIMARY KEY (content_hash, ctx_hash, model)\n);\n\n\nCREATE TABLE IF NOT EXISTS doc_embeddings (\n  doc_id     TEXT NOT NULL,\n  model      TEXT NOT NULL,\n  input_hash BLOB NOT NULL,\n  method     TEXT NOT NULL CHECK (method IN ('whole','pooled')),\n  dim        INTEGER NOT NULL,\n  vec        BLOB NOT NULL,\n  PRIMARY KEY (doc_id, model)\n);\n\n\nCREATE VIRTUAL TABLE IF NOT EXISTS blocks_fts USING fts5(\n  text, content='blocks', content_rowid='rowid', tokenize='porter unicode61'\n);\n\nCREATE TABLE IF NOT EXISTS nodes (\n  node_id    TEXT PRIMARY KEY,\n  repo_id    TEXT NOT NULL,\n  doc_id     TEXT NOT NULL,\n  block_id   TEXT,\n  kind       TEXT NOT NULL,\n  name       TEXT,\n  value      TEXT,\n  span_start INTEGER,\n  span_end   INTEGER,\n  attrs      TEXT NOT NULL DEFAULT '{}'\n);\nCREATE INDEX IF NOT EXISTS idx_nodes_doc  ON nodes(doc_id);\nCREATE INDEX IF NOT EXISTS idx_nodes_kind ON nodes(kind);\nCREATE INDEX IF NOT EXISTS idx_nodes_name ON nodes(name) WHERE name IS NOT NULL;\n\nCREATE VIRTUAL TABLE IF NOT EXISTS nodes_fts USING fts5(\n  name, value, content='nodes', content_rowid='rowid', tokenize='porter unicode61'\n);\n\n\nCREATE TABLE IF NOT EXISTS file_stats (\n  repo_id  TEXT NOT NULL,\n  path     TEXT NOT NULL,\n  mtime_ns INTEGER NOT NULL,\n  size     INTEGER NOT NULL,\n  hash     BLOB NOT NULL,\n  PRIMARY KEY (repo_id, path)\n);\n\n\nCREATE TABLE IF NOT EXISTS properties (\n  prop_id        TEXT PRIMARY KEY,\n  repo_id        TEXT NOT NULL,\n  doc_id         TEXT NOT NULL,\n  block_id       TEXT,                    -- NULL = document-scoped (frontmatter, computed)\n  source         TEXT NOT NULL CHECK (source IN ('frontmatter','inline','computed')),\n  key            TEXT NOT NULL,           -- dotted, flattened: \"layer\",\"meta.owner\"; computed carry $: \"$title\"\n  card           TEXT NOT NULL CHECK (card IN ('scalar','list')),\n  ord            INTEGER NOT NULL DEFAULT 0,\n  val_text       TEXT,\n  val_num        REAL,\n  val_bool       INTEGER,\n  val_json       TEXT,\n  type           TEXT NOT NULL CHECK (type IN ('string','number','bool','null','json')),\n  created_commit TEXT NOT NULL,\n  deleted_commit TEXT\n);\nCREATE INDEX IF NOT EXISTS idx_props_doc      ON properties(doc_id)                 WHERE deleted_commit IS NULL;\nCREATE INDEX IF NOT EXISTS idx_props_key_text ON properties(repo_id, key, val_text) WHERE deleted_commit IS NULL;\nCREATE INDEX IF NOT EXISTS idx_props_key_num  ON properties(repo_id, key, val_num)  WHERE deleted_commit IS NULL;\nCREATE INDEX IF NOT EXISTS idx_props_src_key  ON properties(repo_id, source, key)   WHERE deleted_commit IS NULL;\n\n\nCREATE TABLE IF NOT EXISTS adapters (\n  name     TEXT PRIMARY KEY,        -- workspace-unique adapter name (e.g. \"fs\")\n  command  TEXT NOT NULL,           -- argv[0] to spawn (e.g. \"omgbase-fs-adapter\")\n  args     TEXT NOT NULL DEFAULT '[]'  -- fixed leading args (JSON string[])\n);\n\nCREATE TABLE IF NOT EXISTS sources (\n  source_id TEXT PRIMARY KEY,\n  name      TEXT NOT NULL UNIQUE,   -- workspace-unique source name\n  adapter   TEXT NOT NULL REFERENCES adapters(name),\n  config    TEXT NOT NULL DEFAULT '{}',  -- JSON object \u2192 rendered to flags (13 \u00A73.1)\n  env       TEXT NOT NULL DEFAULT '{}'   -- JSON object \u2192 spawn env (secrets; 13 \u00A73.2)\n);\n\nCREATE TABLE IF NOT EXISTS attachments (\n  repo_id   TEXT NOT NULL REFERENCES repos(repo_id),\n  source_id TEXT NOT NULL REFERENCES sources(source_id),\n  PRIMARY KEY (repo_id, source_id)\n);\n\nCREATE TABLE IF NOT EXISTS sync_state (\n  repo_id   TEXT NOT NULL,\n  source_id TEXT NOT NULL,\n  path      TEXT NOT NULL,          -- '' reserved for the attachment-level cursor row\n  revision  TEXT,                   -- last-observed source revision for this path\n  cursor    TEXT,                   -- last poll/webhook cursor (attachment-level row)\n  PRIMARY KEY (repo_id, source_id, path)\n);\n\n\nCREATE TABLE IF NOT EXISTS workspace_settings (\n  id       INTEGER PRIMARY KEY CHECK (id = 0),\n  settings TEXT NOT NULL DEFAULT '{}'\n);\nINSERT OR IGNORE INTO workspace_settings (id, settings) VALUES (0, '{}');\n\n";
+export declare const DDL = "\n-- ---- durable tables (02 \u00A73) --------------------------------------------------\nCREATE TABLE IF NOT EXISTS repos (\n  repo_id   TEXT PRIMARY KEY,\n  slug      TEXT NOT NULL UNIQUE,\n  settings  TEXT NOT NULL DEFAULT '{}'\n);\n-- A repo owns identity + history, NOT a filesystem (ADR-014). Where its bytes\n-- come from is a sources row (adapter=fs, config.root) joined via attachments;\n-- the former repos.root_path column was removed in schema v13.\n\nCREATE TABLE IF NOT EXISTS docs (\n  doc_id         TEXT PRIMARY KEY,\n  repo_id        TEXT NOT NULL REFERENCES repos(repo_id),\n  path           TEXT NOT NULL,\n  format         TEXT NOT NULL DEFAULT 'markdown',\n  current_rev    TEXT,\n  file_hash      BLOB,\n  conflicted     INTEGER NOT NULL DEFAULT 0,\n  leading_trivia TEXT NOT NULL DEFAULT '',\n  frontmatter_trivia TEXT,                  -- separator between frontmatter and first body block (NULL = no frontmatter)\n  deleted_commit TEXT,\n  UNIQUE (repo_id, path)\n);\n\nCREATE TABLE IF NOT EXISTS blocks (\n  block_id       TEXT PRIMARY KEY,\n  repo_id        TEXT NOT NULL REFERENCES repos(repo_id),\n  doc_id         TEXT NOT NULL REFERENCES docs(doc_id),\n  parent_block   TEXT,\n  order_key      TEXT NOT NULL,\n  ordinal        INTEGER NOT NULL,\n  depth          INTEGER NOT NULL,\n  ancestor_path  TEXT NOT NULL,\n  type           TEXT NOT NULL,\n  attrs          TEXT NOT NULL DEFAULT '{}',\n  text           TEXT NOT NULL,\n  raw_hash       BLOB NOT NULL,\n  norm_hash      BLOB NOT NULL,\n  trivia_hash    BLOB,                     -- trailing trivia blob hash (NULL = no trivia)\n  created_commit TEXT NOT NULL,\n  deleted_commit TEXT\n);\nCREATE INDEX IF NOT EXISTS idx_blocks_doc      ON blocks(doc_id, parent_block, order_key) WHERE deleted_commit IS NULL;\nCREATE INDEX IF NOT EXISTS idx_blocks_type     ON blocks(repo_id, type)                   WHERE deleted_commit IS NULL;\nCREATE INDEX IF NOT EXISTS idx_blocks_rawhash  ON blocks(raw_hash);\nCREATE INDEX IF NOT EXISTS idx_blocks_ancestor ON blocks(doc_id, ancestor_path);\n\nCREATE TABLE IF NOT EXISTS blobs (\n  hash  BLOB PRIMARY KEY,\n  bytes BLOB NOT NULL,\n  size  INTEGER NOT NULL\n);\n\nCREATE TABLE IF NOT EXISTS tree_nodes (\n  hash    BLOB PRIMARY KEY,\n  entries TEXT NOT NULL\n);\n\nCREATE TABLE IF NOT EXISTS revisions (\n  rev_id           TEXT PRIMARY KEY,\n  doc_id           TEXT NOT NULL REFERENCES docs(doc_id),\n  seq              INTEGER NOT NULL,\n  root_tree        BLOB NOT NULL REFERENCES tree_nodes(hash),\n  frontmatter_blob BLOB REFERENCES blobs(hash),\n  rendered_hash    BLOB NOT NULL,\n  path             TEXT NOT NULL,\n  commit_id        TEXT NOT NULL REFERENCES commits(commit_id),\n  UNIQUE (doc_id, seq)\n);\n\nCREATE TABLE IF NOT EXISTS commits (\n  commit_id     TEXT PRIMARY KEY,\n  repo_id       TEXT NOT NULL REFERENCES repos(repo_id),\n  seq           INTEGER NOT NULL,\n  ts            TEXT NOT NULL,\n  origin        TEXT NOT NULL CHECK (origin IN ('api','observed','import','projection')),\n  actor         TEXT,\n  reason        TEXT,\n  checkpoint_id TEXT,\n  ops           TEXT,\n  UNIQUE (repo_id, seq)\n);\n\nCREATE TABLE IF NOT EXISTS dispositions (\n  commit_id  TEXT NOT NULL REFERENCES commits(commit_id),\n  block_id   TEXT NOT NULL,\n  kind       TEXT NOT NULL CHECK (kind IN\n             ('same','edited','moved','edited_moved','inserted','deleted',\n              'split_from','merged_into','copied_from','resurrected','bulk_rewrite')),\n  confidence REAL,\n  reason     TEXT,\n  matcher_v  TEXT,\n  detail     TEXT NOT NULL DEFAULT '{}',\n  PRIMARY KEY (commit_id, block_id, kind)\n);\n\nCREATE TABLE IF NOT EXISTS edges (\n  edge_id     TEXT PRIMARY KEY,\n  repo_id     TEXT NOT NULL,\n  src_doc     TEXT NOT NULL,\n  src_block   TEXT,\n  src_field   TEXT,\n  predicate   TEXT NOT NULL,\n  dst_kind    TEXT NOT NULL CHECK (dst_kind IN ('document','block','external','collection')),\n  dst_node    TEXT NOT NULL,\n  anchor      TEXT,\n  provenance  TEXT NOT NULL CHECK (provenance IN ('link','frontmatter','inline_field','projected',\n               'yaml_ref','yaml_schema','yaml_extends','json_ref','json_schema')),\n  via_node    TEXT,\n  from_commit TEXT NOT NULL,\n  to_commit   TEXT\n);\nCREATE INDEX IF NOT EXISTS idx_edges_src      ON edges(src_doc, predicate) WHERE to_commit IS NULL;\nCREATE INDEX IF NOT EXISTS idx_edges_dst      ON edges(dst_node, predicate) WHERE to_commit IS NULL;\nCREATE INDEX IF NOT EXISTS idx_edges_temporal ON edges(from_commit, to_commit);\n\nCREATE TABLE IF NOT EXISTS external_nodes (\n  node_id TEXT PRIMARY KEY,\n  repo_id TEXT NOT NULL,\n  uri     TEXT NOT NULL,\n  title   TEXT,\n  UNIQUE (repo_id, uri)\n);\n\nCREATE TABLE IF NOT EXISTS collections (\n  node_id TEXT PRIMARY KEY,\n  repo_id TEXT NOT NULL,\n  name    TEXT NOT NULL,\n  spec    TEXT NOT NULL DEFAULT '{}'\n);\n\nCREATE TABLE IF NOT EXISTS checkpoints (\n  id       TEXT PRIMARY KEY,\n  repo_id  TEXT NOT NULL,\n  ts       TEXT NOT NULL,\n  files    TEXT NOT NULL,\n  git_head TEXT\n);\n\nCREATE TABLE IF NOT EXISTS resurrection_pool (\n  block_id       TEXT PRIMARY KEY,\n  repo_id        TEXT NOT NULL,\n  doc_id         TEXT NOT NULL,\n  raw_hash       BLOB NOT NULL,\n  norm_hash      BLOB NOT NULL,\n  type           TEXT NOT NULL,\n  deleted_commit TEXT NOT NULL,\n  expires_ts     TEXT NOT NULL\n);\n\nCREATE TABLE IF NOT EXISTS pending_materializations (\n  repo_id       TEXT NOT NULL REFERENCES repos(repo_id),\n  path          TEXT NOT NULL,                 -- where the file must end up\n  kind          TEXT NOT NULL CHECK (kind IN ('write','rename','remove')),\n  from_path     TEXT,                          -- rename: the old path\n  doc_id        TEXT NOT NULL REFERENCES docs(doc_id),\n  rev_id        TEXT REFERENCES revisions(rev_id),   -- write/rename: the revision the bytes render (NULL for remove)\n  rendered_hash BLOB NOT NULL,                 -- the bytes expected at path (remove: the bytes it is safe to unlink)\n  commit_id     TEXT NOT NULL REFERENCES commits(commit_id),\n  PRIMARY KEY (repo_id, path)\n);\n\n-- ---- derived tables (02 \u00A74; rebuildable) ------------------------------------\nCREATE TABLE IF NOT EXISTS sections (\n  heading_block TEXT NOT NULL,\n  doc_id        TEXT NOT NULL,\n  level         INTEGER NOT NULL,\n  first_ordinal INTEGER NOT NULL,\n  last_ordinal  INTEGER NOT NULL,\n  PRIMARY KEY (doc_id, heading_block)\n);\n\nCREATE TABLE IF NOT EXISTS doc_edges (\n  src_doc   TEXT NOT NULL,\n  predicate TEXT NOT NULL,\n  dst_node  TEXT NOT NULL,\n  dst_kind  TEXT NOT NULL,\n  count     INTEGER NOT NULL,\n  samples   TEXT NOT NULL,\n  PRIMARY KEY (src_doc, predicate, dst_node)\n);\n\nCREATE TABLE IF NOT EXISTS block_changes (\n  block_id  TEXT NOT NULL,\n  commit_id TEXT NOT NULL,\n  kind      TEXT NOT NULL,\n  PRIMARY KEY (block_id, commit_id, kind)\n);\n\nCREATE TABLE IF NOT EXISTS inferred_edges (\n  src_node    TEXT NOT NULL,\n  dst_node    TEXT NOT NULL,\n  predicate   TEXT NOT NULL,\n  method      TEXT NOT NULL,\n  score       REAL NOT NULL,\n  model_v     TEXT NOT NULL,\n  computed_at TEXT NOT NULL,\n  PRIMARY KEY (src_node, dst_node, predicate, method)\n);\n\nCREATE TABLE IF NOT EXISTS embeddings (\n  content_hash BLOB NOT NULL,\n  ctx_hash     BLOB NOT NULL,\n  model        TEXT NOT NULL,\n  dim          INTEGER NOT NULL,\n  vec          BLOB NOT NULL,\n  PRIMARY KEY (content_hash, ctx_hash, model)\n);\n\n\nCREATE TABLE IF NOT EXISTS doc_embeddings (\n  doc_id     TEXT NOT NULL,\n  model      TEXT NOT NULL,\n  input_hash BLOB NOT NULL,\n  method     TEXT NOT NULL CHECK (method IN ('whole','pooled')),\n  dim        INTEGER NOT NULL,\n  vec        BLOB NOT NULL,\n  PRIMARY KEY (doc_id, model)\n);\n\n\nCREATE VIRTUAL TABLE IF NOT EXISTS blocks_fts USING fts5(\n  text, content='blocks', content_rowid='rowid', tokenize='porter unicode61'\n);\n\nCREATE TABLE IF NOT EXISTS nodes (\n  node_id    TEXT PRIMARY KEY,\n  repo_id    TEXT NOT NULL,\n  doc_id     TEXT NOT NULL,\n  block_id   TEXT,\n  kind       TEXT NOT NULL,\n  name       TEXT,\n  value      TEXT,\n  span_start INTEGER,\n  span_end   INTEGER,\n  attrs      TEXT NOT NULL DEFAULT '{}'\n);\nCREATE INDEX IF NOT EXISTS idx_nodes_doc  ON nodes(doc_id);\nCREATE INDEX IF NOT EXISTS idx_nodes_kind ON nodes(kind);\nCREATE INDEX IF NOT EXISTS idx_nodes_name ON nodes(name) WHERE name IS NOT NULL;\n\nCREATE VIRTUAL TABLE IF NOT EXISTS nodes_fts USING fts5(\n  name, value, content='nodes', content_rowid='rowid', tokenize='porter unicode61'\n);\n\n\nCREATE TABLE IF NOT EXISTS file_stats (\n  repo_id  TEXT NOT NULL,\n  path     TEXT NOT NULL,\n  mtime_ns INTEGER NOT NULL,\n  size     INTEGER NOT NULL,\n  hash     BLOB NOT NULL,\n  PRIMARY KEY (repo_id, path)\n);\n\n\nCREATE TABLE IF NOT EXISTS properties (\n  prop_id        TEXT PRIMARY KEY,\n  repo_id        TEXT NOT NULL,\n  doc_id         TEXT NOT NULL,\n  block_id       TEXT,                    -- NULL = document-scoped (frontmatter, computed)\n  source         TEXT NOT NULL CHECK (source IN ('frontmatter','inline','computed')),\n  key            TEXT NOT NULL,           -- dotted, flattened: \"layer\",\"meta.owner\"; computed carry $: \"$title\"\n  card           TEXT NOT NULL CHECK (card IN ('scalar','list')),\n  ord            INTEGER NOT NULL DEFAULT 0,\n  val_text       TEXT,\n  val_num        REAL,\n  val_bool       INTEGER,\n  val_json       TEXT,\n  type           TEXT NOT NULL CHECK (type IN ('string','number','bool','null','json')),\n  created_commit TEXT NOT NULL,\n  deleted_commit TEXT\n);\nCREATE INDEX IF NOT EXISTS idx_props_doc      ON properties(doc_id)                 WHERE deleted_commit IS NULL;\nCREATE INDEX IF NOT EXISTS idx_props_key_text ON properties(repo_id, key, val_text) WHERE deleted_commit IS NULL;\nCREATE INDEX IF NOT EXISTS idx_props_key_num  ON properties(repo_id, key, val_num)  WHERE deleted_commit IS NULL;\nCREATE INDEX IF NOT EXISTS idx_props_src_key  ON properties(repo_id, source, key)   WHERE deleted_commit IS NULL;\n\n\nCREATE TABLE IF NOT EXISTS adapters (\n  name     TEXT PRIMARY KEY,        -- workspace-unique adapter name (e.g. \"fs\")\n  command  TEXT NOT NULL,           -- argv[0] to spawn (e.g. \"omgbase-fs-adapter\")\n  args     TEXT NOT NULL DEFAULT '[]'  -- fixed leading args (JSON string[])\n);\n\nCREATE TABLE IF NOT EXISTS sources (\n  source_id TEXT PRIMARY KEY,\n  name      TEXT NOT NULL UNIQUE,   -- workspace-unique source name\n  adapter   TEXT NOT NULL REFERENCES adapters(name),\n  config    TEXT NOT NULL DEFAULT '{}',  -- JSON object \u2192 rendered to flags (13 \u00A73.1)\n  env       TEXT NOT NULL DEFAULT '{}'   -- JSON object \u2192 spawn env (secrets; 13 \u00A73.2)\n);\n\nCREATE TABLE IF NOT EXISTS attachments (\n  repo_id   TEXT NOT NULL REFERENCES repos(repo_id),\n  source_id TEXT NOT NULL REFERENCES sources(source_id),\n  PRIMARY KEY (repo_id, source_id)\n);\n\nCREATE TABLE IF NOT EXISTS sync_state (\n  repo_id   TEXT NOT NULL,\n  source_id TEXT NOT NULL,\n  path      TEXT NOT NULL,          -- '' reserved for the attachment-level cursor row\n  revision  TEXT,                   -- last-observed source revision for this path\n  cursor    TEXT,                   -- last poll/webhook cursor (attachment-level row)\n  PRIMARY KEY (repo_id, source_id, path)\n);\n\n\nCREATE TABLE IF NOT EXISTS workspace_settings (\n  id       INTEGER PRIMARY KEY CHECK (id = 0),\n  settings TEXT NOT NULL DEFAULT '{}'\n);\nINSERT OR IGNORE INTO workspace_settings (id, settings) VALUES (0, '{}');\n\n";

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

@@ -1,7 +1,7 @@
 // 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;
+export const SCHEMA_VERSION = 14;
 // 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.
@@ -136,10 +136,34 @@ CREATE TABLE IF NOT EXISTS doc_embeddings (
   PRIMARY KEY (doc_id, model)
 );
 `;
+// pending_materializations (spec/store §5.7, store 14.0). The recorded intent
+// of the api path's file half: the commit transaction inserts one row per file
+// the request must leave on disk — `write` the revision's bytes at `path`,
+// `rename` the file from `from_path` to `path`, `remove` the file at `path` —
+// and the materializer deletes each row once the file is there (after COMMIT,
+// per file, autocommit). A row that survives a crash is replayed by the next
+// materializer (B', the freshness sweep's step 0, recovery) from
+// `reconstruct at rev_id`; `rendered_hash` names the bytes expected at `path`
+// (for `remove`: the bytes it is safe to unlink). No bytes column: the
+// revision already holds them. One row per path: a later request for the same
+// path supersedes the earlier intent (`INSERT OR REPLACE`).
+export const PENDING_MATERIALIZATIONS_DDL = /* sql */ `
+CREATE TABLE IF NOT EXISTS pending_materializations (
+  repo_id       TEXT NOT NULL REFERENCES repos(repo_id),
+  path          TEXT NOT NULL,                 -- where the file must end up
+  kind          TEXT NOT NULL CHECK (kind IN ('write','rename','remove')),
+  from_path     TEXT,                          -- rename: the old path
+  doc_id        TEXT NOT NULL REFERENCES docs(doc_id),
+  rev_id        TEXT REFERENCES revisions(rev_id),   -- write/rename: the revision the bytes render (NULL for remove)
+  rendered_hash BLOB NOT NULL,                 -- the bytes expected at path (remove: the bytes it is safe to unlink)
+  commit_id     TEXT NOT NULL REFERENCES commits(commit_id),
+  PRIMARY KEY (repo_id, path)
+);
+`;
 // 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.
+// Migrations 3, 4, 6, 7, 9, 11, 13 are programmatic — see store.ts.
 export const MIGRATIONS = {
     2: FILE_STATS_DDL,
     3: "", // handled programmatically in store.ts
@@ -153,6 +177,7 @@ export const MIGRATIONS = {
     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
+    14: PENDING_MATERIALIZATIONS_DDL, // the api path's recorded file intent (spec/store §5.7)
 };
 export const DDL = /* sql */ `
 -- ---- durable tables (02 §3) --------------------------------------------------
@@ -304,7 +329,7 @@ CREATE TABLE IF NOT EXISTS resurrection_pool (
   deleted_commit TEXT NOT NULL,
   expires_ts     TEXT NOT NULL
 );
-
+${PENDING_MATERIALIZATIONS_DDL}
 -- ---- derived tables (02 §4; rebuildable) ------------------------------------
 CREATE TABLE IF NOT EXISTS sections (
   heading_block TEXT NOT NULL,

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

@@ -0,0 +1,76 @@
+import type { Store } from "./store.js";
+export declare const SIZE_CATEGORIES: readonly ["content", "history", "search", "sync"];
+export type SizeCategory = (typeof SIZE_CATEGORIES)[number];
+/** spec/store §7: the category of every table `schema.sql` creates. */
+export declare const TABLE_CATEGORY: Readonly<Record<string, SizeCategory>>;
+/** The category of a table: the spec's assignment, `sync` for anything else. */
+export declare function categoryOf(table: string): SizeCategory;
+export interface SizeTable {
+    name: string;
+    /** Pages of the table and its indexes (and shadow tables), in bytes; null without dbstat. */
+    bytes: number | null;
+    /** `bytes` over the total, one decimal; null without dbstat. */
+    share: number | null;
+    rows: number;
+    /** The bytes of the table's indexes alone (included in `bytes`); null without dbstat. */
+    indexes: number | null;
+}
+export interface SizeCategoryReport {
+    name: SizeCategory;
+    bytes: number | null;
+    share: number | null;
+    rows: number;
+    /** By bytes desc then name (rows desc then name without dbstat). */
+    tables: SizeTable[];
+}
+export interface SizeFile {
+    path: string;
+    /** The main file's bytes on disk (`page_count * page_size` for an in-memory database). */
+    bytes: number;
+    /** The `-wal` file's bytes on disk, 0 when absent. */
+    wal_bytes: number;
+    page_size: number;
+    page_count: number;
+    freelist_count: number;
+    /** `freelist_count * page_size`: what `VACUUM` returns to the filesystem. */
+    reclaimable: number;
+}
+export interface SizeReport {
+    file: SizeFile;
+    /** Always the four categories, in the fixed order content, history, search, sync. */
+    categories: SizeCategoryReport[];
+    advice: string[];
+    /** Present only when the SQLite build lacks `dbstat` (row counts only). */
+    detail?: "dbstat unavailable";
+}
+/** The advice thresholds (spec/store §7). */
+export declare const VACUUM_ADVICE_MIN_BYTES: number;
+export declare const VACUUM_ADVICE_MIN_SHARE = 10;
+export declare const HISTORY_ADVICE_MIN_SHARE = 50;
+export declare const EMBEDDINGS_ADVICE_MIN_SHARE = 25;
+/**
+ * `<n> B` under 1024, else one decimal of KB/MB/GB/TB (1024-based), the tenths
+ * rounded half up — `4096` → `4.0 KB`, `13734297` → `13.1 MB`. Both engines
+ * format from the integer tenths so the bytes never differ by a rounding mode.
+ */
+export declare function humanBytes(n: number): string;
+/** A share as `<n>.<d>%` from its one-decimal value (`48.2` → `48.2%`, `50` → `50.0%`). */
+export declare function formatShare(share: number): string;
+/** `bytes / total` in percent, one decimal, rounded half up; 0 when the total is 0. */
+export declare function shareOf(bytes: number, total: number): number;
+/** spec/store §7: the advice lines, in this order; `nothing to reclaim` when none applies. */
+export declare function sizeAdvice(file: SizeFile, categories: SizeCategoryReport[]): string[];
+/** The size report of an open store (spec/store §7 "Size"). */
+export declare function sizeReport(store: Store): SizeReport;
+export interface VacuumResult {
+    /** `freelist_count * page_size` before the `VACUUM`: the bytes it returned. */
+    reclaimable: number;
+}
+/**
+ * `VACUUM` the database (spec/store §7). Not a transaction's work — SQLite
+ * refuses a VACUUM inside one — so it runs on the bare connection; returns the
+ * free-page bytes measured before, which is what the file shrinks by.
+ */
+export declare function vacuum(store: Store): VacuumResult;
+/** `freelist_count * page_size`: the bytes a `VACUUM` would return now. */
+export declare function reclaimableBytes(store: Store): number;

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

@@ -0,0 +1,223 @@
+import { statSync } from "node:fs";
+// The size report (spec/store §7 "Size", 14.1): what the database is made of,
+// table by table through SQLite's `dbstat` virtual table, grouped into the four
+// categories a reader reasons about — the live state (`content`), the
+// append-only record (`history`), the derived indexes (`search`) and the
+// workspace bookkeeping (`sync`) — plus the file's page accounting and the
+// deterministic advice `omg doctor --size` prints. The categorization is the
+// spec's: every table of `schema.sql` is assigned, an index counts toward its
+// table, an FTS5 virtual table's shadow tables fold into it, and anything the
+// spec does not name (`sqlite_schema`, `sqlite_stat1`, a table from a newer
+// schema) is `sync`.
+export const SIZE_CATEGORIES = ["content", "history", "search", "sync"];
+/** spec/store §7: the category of every table `schema.sql` creates. */
+export const TABLE_CATEGORY = {
+    docs: "content",
+    blocks: "content",
+    sections: "content",
+    nodes: "content",
+    edges: "content",
+    doc_edges: "content",
+    inferred_edges: "content",
+    external_nodes: "content",
+    properties: "content",
+    collections: "content",
+    blobs: "history",
+    tree_nodes: "history",
+    revisions: "history",
+    commits: "history",
+    dispositions: "history",
+    block_changes: "history",
+    resurrection_pool: "history",
+    pending_materializations: "history",
+    blocks_fts: "search",
+    nodes_fts: "search",
+    embeddings: "search",
+    doc_embeddings: "search",
+    repos: "sync",
+    sources: "sync",
+    adapters: "sync",
+    attachments: "sync",
+    checkpoints: "sync",
+    file_stats: "sync",
+    sync_state: "sync",
+    workspace_settings: "sync",
+};
+/** The category of a table: the spec's assignment, `sync` for anything else. */
+export function categoryOf(table) {
+    return TABLE_CATEGORY[table] ?? "sync";
+}
+/** The advice thresholds (spec/store §7). */
+export const VACUUM_ADVICE_MIN_BYTES = 1024 * 1024;
+export const VACUUM_ADVICE_MIN_SHARE = 10;
+export const HISTORY_ADVICE_MIN_SHARE = 50;
+export const EMBEDDINGS_ADVICE_MIN_SHARE = 25;
+/**
+ * `<n> B` under 1024, else one decimal of KB/MB/GB/TB (1024-based), the tenths
+ * rounded half up — `4096` → `4.0 KB`, `13734297` → `13.1 MB`. Both engines
+ * format from the integer tenths so the bytes never differ by a rounding mode.
+ */
+export function humanBytes(n) {
+    if (n < 1024)
+        return `${n} B`;
+    const units = ["KB", "MB", "GB", "TB"];
+    let v = n / 1024;
+    let u = 0;
+    while (v >= 1024 && u < units.length - 1) {
+        v /= 1024;
+        u++;
+    }
+    const tenths = Math.round(v * 10);
+    return `${Math.floor(tenths / 10)}.${tenths % 10} ${units[u]}`;
+}
+/** A share as `<n>.<d>%` from its one-decimal value (`48.2` → `48.2%`, `50` → `50.0%`). */
+export function formatShare(share) {
+    const tenths = Math.round(share * 10);
+    return `${Math.floor(tenths / 10)}.${tenths % 10}%`;
+}
+/** `bytes / total` in percent, one decimal, rounded half up; 0 when the total is 0. */
+export function shareOf(bytes, total) {
+    if (total <= 0)
+        return 0;
+    return Math.round((bytes * 1000) / total) / 10;
+}
+/** spec/store §7: the advice lines, in this order; `nothing to reclaim` when none applies. */
+export function sizeAdvice(file, categories) {
+    const advice = [];
+    const logical = file.page_count * file.page_size;
+    if (file.reclaimable > VACUUM_ADVICE_MIN_BYTES && file.reclaimable * 100 > logical * VACUUM_ADVICE_MIN_SHARE) {
+        advice.push(`run \`omg gc --vacuum\` to return ${humanBytes(file.reclaimable)} of free pages to the filesystem`);
+    }
+    const history = categories.find((c) => c.name === "history");
+    if (history && history.share !== null && history.share > HISTORY_ADVICE_MIN_SHARE) {
+        advice.push(`history dominates (${formatShare(history.share)}): blobs, tree nodes and dispositions grow with every commit — enable gc (\`omg config set gc.enabled true\`) and run \`omg gc --vacuum\``);
+    }
+    const search = categories.find((c) => c.name === "search");
+    if (search && search.bytes !== null) {
+        const total = categories.reduce((n, c) => n + (c.bytes ?? 0), 0);
+        const embBytes = search.tables.filter((t) => t.name === "embeddings" || t.name === "doc_embeddings").reduce((n, t) => n + (t.bytes ?? 0), 0);
+        const embShare = shareOf(embBytes, total);
+        if (embShare > EMBEDDINGS_ADVICE_MIN_SHARE) {
+            advice.push(`embeddings are ${formatShare(embShare)} of the database: a smaller model (\`embedding.model\` / \`embedding.dim\`) or \`omg embed drain --prune\` after a model switch shrinks them`);
+        }
+    }
+    if (advice.length === 0)
+        advice.push("nothing to reclaim");
+    return advice;
+}
+/** The `dbstat` bytes per b-tree name, or null when the build lacks the virtual table. */
+function dbstatBytes(store) {
+    try {
+        const rows = store.db.prepare("SELECT name, sum(pgsize) AS bytes FROM dbstat GROUP BY name").all();
+        return new Map(rows.map((r) => [r.name, Number(r.bytes)]));
+    }
+    catch {
+        return null;
+    }
+}
+/** The size report of an open store (spec/store §7 "Size"). */
+export function sizeReport(store) {
+    const db = store.db;
+    const path = db.name === "" ? ":memory:" : db.name;
+    const page_size = db.pragma("page_size", { simple: true });
+    const page_count = db.pragma("page_count", { simple: true });
+    const freelist_count = db.pragma("freelist_count", { simple: true });
+    const onDisk = path !== ":memory:";
+    const fileBytes = (p) => {
+        try {
+            return statSync(p).size;
+        }
+        catch {
+            return 0;
+        }
+    };
+    const file = {
+        path,
+        bytes: onDisk ? fileBytes(path) : page_count * page_size,
+        wal_bytes: onDisk ? fileBytes(`${path}-wal`) : 0,
+        page_size,
+        page_count,
+        freelist_count,
+        reclaimable: freelist_count * page_size,
+    };
+    const master = db.prepare("SELECT type, name, tbl_name, sql FROM sqlite_master").all();
+    const virtuals = master.filter((r) => r.type === "table" && /^CREATE VIRTUAL TABLE/i.test(r.sql ?? "")).map((r) => r.name);
+    // A shadow table (`blocks_fts_data`, …) folds into its virtual table.
+    const ownerOf = (name) => virtuals.find((v) => name.startsWith(`${v}_`)) ?? name;
+    const stat = dbstatBytes(store);
+    // Every table: sqlite_master's (shadow tables folded into their owner), plus
+    // the schema table itself, which sqlite_master does not list but dbstat does.
+    const tableNames = new Set(["sqlite_schema"]);
+    for (const r of master)
+        if (r.type === "table")
+            tableNames.add(ownerOf(r.name));
+    if (stat)
+        for (const name of stat.keys())
+            if (!master.some((r) => r.name === name && r.type === "index"))
+                tableNames.add(ownerOf(name));
+    const indexBytes = new Map();
+    const tableBytes = new Map();
+    if (stat) {
+        for (const [name, bytes] of stat) {
+            const idx = master.find((r) => r.type === "index" && r.name === name);
+            if (idx) {
+                indexBytes.set(idx.tbl_name, (indexBytes.get(idx.tbl_name) ?? 0) + bytes);
+                tableBytes.set(idx.tbl_name, (tableBytes.get(idx.tbl_name) ?? 0) + bytes);
+            }
+            else {
+                const owner = ownerOf(name);
+                tableBytes.set(owner, (tableBytes.get(owner) ?? 0) + bytes);
+            }
+        }
+    }
+    const total = stat ? [...stat.values()].reduce((n, b) => n + b, 0) : 0;
+    const countRows = (name) => {
+        // An external-content FTS5 table answers `count(*)` from its content table;
+        // the rows it indexes are its `_docsize` shadow's.
+        const from = virtuals.includes(name) ? `${name}_docsize` : name;
+        try {
+            return db.prepare(`SELECT count(*) AS c FROM "${from.replace(/"/g, '""')}"`).get().c;
+        }
+        catch {
+            return 0;
+        }
+    };
+    const byCategory = new Map(SIZE_CATEGORIES.map((c) => [c, []]));
+    for (const name of tableNames) {
+        const bytes = stat ? (tableBytes.get(name) ?? 0) : null;
+        byCategory.get(categoryOf(name)).push({
+            name,
+            bytes,
+            share: bytes === null ? null : shareOf(bytes, total),
+            rows: countRows(name),
+            indexes: stat ? (indexBytes.get(name) ?? 0) : null,
+        });
+    }
+    const byBytesThenName = (a, b) => (b.bytes ?? b.rows) - (a.bytes ?? a.rows) || (a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
+    const categories = SIZE_CATEGORIES.map((name) => {
+        const tables = byCategory.get(name).sort(byBytesThenName);
+        const bytes = stat ? tables.reduce((n, t) => n + (t.bytes ?? 0), 0) : null;
+        return { name, bytes, share: bytes === null ? null : shareOf(bytes, total), rows: tables.reduce((n, t) => n + t.rows, 0), tables };
+    });
+    const report = { file, categories, advice: sizeAdvice(file, categories) };
+    if (!stat)
+        report.detail = "dbstat unavailable";
+    return report;
+}
+/**
+ * `VACUUM` the database (spec/store §7). Not a transaction's work — SQLite
+ * refuses a VACUUM inside one — so it runs on the bare connection; returns the
+ * free-page bytes measured before, which is what the file shrinks by.
+ */
+export function vacuum(store) {
+    const reclaimable = reclaimableBytes(store);
+    store.db.exec("VACUUM");
+    return { reclaimable };
+}
+/** `freelist_count * page_size`: the bytes a `VACUUM` would return now. */
+export function reclaimableBytes(store) {
+    const page_size = store.db.pragma("page_size", { simple: true });
+    const freelist_count = store.db.pragma("freelist_count", { simple: true });
+    return freelist_count * page_size;
+}
+//# sourceMappingURL=size.js.map

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

@@ -23,6 +23,15 @@ export declare class Store {
      * commit). better-sqlite3 transactions are synchronous and serialized.
      */
     write<T>(fn: (db: Database.Database) => T): T;
+    /**
+     * Run fn inside a `BEGIN IMMEDIATE` transaction: the write lock is taken at
+     * BEGIN, so every read fn makes is already protected from another writer and
+     * a concurrent `BEGIN IMMEDIATE` waits (SQLITE_BUSY after the busy timeout).
+     * The commit phase of a request uses it (spec/mutate §4 step 5(c), 2.2) so
+     * the preconditions it re-validates cannot move before it writes. Nested
+     * inside an open transaction it is a savepoint, like `write`.
+     */
+    writeImmediate<T>(fn: (db: Database.Database) => T): T;
     pragma(name: string): unknown;
     close(): void;
 }

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

@@ -191,6 +191,17 @@ export class Store {
     write(fn) {
         return this.db.transaction(fn)(this.db);
     }
+    /**
+     * Run fn inside a `BEGIN IMMEDIATE` transaction: the write lock is taken at
+     * BEGIN, so every read fn makes is already protected from another writer and
+     * a concurrent `BEGIN IMMEDIATE` waits (SQLITE_BUSY after the busy timeout).
+     * The commit phase of a request uses it (spec/mutate §4 step 5(c), 2.2) so
+     * the preconditions it re-validates cannot move before it writes. Nested
+     * inside an open transaction it is a savepoint, like `write`.
+     */
+    writeImmediate(fn) {
+        return this.db.transaction(fn).immediate(this.db);
+    }
     pragma(name) {
         return this.db.pragma(name, { simple: true });
     }

package/dist/src/graph/history.js

@@ -278,12 +278,15 @@ export function changesSince(store, repoId, opts = {}) {
     const digests = page.map((c) => {
         const revs = store.db.prepare("SELECT r.doc_id AS doc, r.path AS path, r.rendered_hash AS rendered_hash FROM revisions r WHERE r.commit_id = ?").all(c.commit_id).map((r) => ({ id: r.doc, path: referencePath(r.path), hash: r.rendered_hash.toString("hex") }));
         const dispCounts = store.db.prepare("SELECT kind, count(*) n FROM dispositions WHERE commit_id = ? GROUP BY kind").all(c.commit_id);
-        // A deletion or a move writes no revision: the tombstone names the commit
-        // (`docs.deleted_commit`), a move only its reason (`move <from> -> <to>`).
+        // A deletion writes no revision: the tombstone names the commit
+        // (`docs.deleted_commit`). A move names itself by its reason (`move <from>
+        // -> <to>`) and, since spec/mutate 2.1, carries the inbound retarget's
+        // revisions under the same commit — so the move is read off the reason
+        // whether or not the commit has revisions.
         const deleted = revs.length === 0
             ? store.db.prepare("SELECT path FROM docs WHERE deleted_commit = ? ORDER BY path").all(c.commit_id).map((r) => referencePath(r.path))
             : [];
-        const moved = revs.length === 0 ? parseMove(c.reason) : null;
+        const moved = parseMove(c.reason);
         const summary = renderSummary(c.origin, c.actor, revs, dispCounts, { deleted, moved: moved ? { from: referencePath(moved.from), to: referencePath(moved.to) } : null });
         return { commit: c.commit_id, seq: c.seq, ts: c.ts, origin: c.origin, actor: c.actor, summary, revisions: revs };
     });
@@ -387,18 +390,18 @@ function parseMove(reason) {
 }
 /**
  * One line per commit: `<origin>[(<actor>)]: <paths> — <n> <kind>, …`. A
- * commit that touched no revision — a document deletion (observed or api) or a
- * move — says so instead: `deleted <path>` / `moved <from> → <to>`
- * (spec/cli §6 `log`; the summary is unpinned by spec/surface).
+ * commit that touched no revision — a document deletion (observed or api) —
+ * says so instead: `deleted <path>`. A move says `moved <from> → <to>`, and
+ * when it also rewrote the inbound sources (spec/mutate §6, 2.1) their paths
+ * follow: `moved a → b; /index.md — 31 edited` (spec/cli §6 `log`; the summary
+ * is unpinned by spec/surface).
  */
 function renderSummary(origin, actor, revs, disp, extra = { deleted: [], moved: null }) {
     let subject = revs.map((r) => r.path).join(", ");
-    if (revs.length === 0) {
-        if (extra.deleted.length > 0)
-            subject = `deleted ${extra.deleted.join(", ")}`;
-        else if (extra.moved)
-            subject = `moved ${extra.moved.from} → ${extra.moved.to}`;
-    }
+    if (extra.moved)
+        subject = `moved ${extra.moved.from} → ${extra.moved.to}${revs.length > 0 ? `; ${subject}` : ""}`;
+    else if (revs.length === 0 && extra.deleted.length > 0)
+        subject = `deleted ${extra.deleted.join(", ")}`;
     const parts = disp.filter((d) => d.kind !== "same").map((d) => `${d.n} ${d.kind}`);
     const detail = parts.length > 0 ? ` — ${parts.join(", ")}` : "";
     if (origin === "api" || origin === "import")

package/dist/src/index.d.ts

@@ -16,7 +16,7 @@ export { Workspace, RepoSelectionError, selectRepo, type RepoRow } from "./sync/
 export { resolveSettings, workspaceSettings, repoOwnSettings, writeWorkspaceSettings, writeRepoSettings, deepMerge, type Settings, } from "./sync/settings.js";
 export { freshnessSweep, rebuildFileStats, recordFileStat, recordStat, detectDiskDrift, sweepPlan, sweepCandidates, loadStatCache, snapshotOf, type SweepResult, type DiskDrift, type SweepPlan, type StatCacheRow, type SnapshotEntry, } from "./sync/freshness.js";
 export { recoverRepo, type RecoveryResult } from "./sync/recovery.js";
-export { withWriterLock, writerLockFree, WriterLockTimeout } from "./sync/writer-lock.js";
+export { withWriterLock, withWriterLockAsync, writerLockFree, writerLockHeld, setWriterLockDefaults, writerLockDefaults, WriterLockTimeout, type WriterLockOptions } from "./sync/writer-lock.js";
 export { WatchLease, watchLeaseLive } from "./sync/watch-lease.js";
 export { ingestDirectory, type IngestDirResult } from "./sync/attach.js";
 export { ensureRepo } from "./core/attach.js";
@@ -28,7 +28,7 @@ export { createExternalSource, type ExternalSourceSpec } from "./sync/external-s
 export { ensureAdapter, listAdapters, createSource, deleteSource, listSources, getSourceByName, attachSourceToRepo, detachSourceFromRepo, sourcesForRepo, renderConfigFlags, type AdapterRow, type SourceRow, } from "./sync/sources.js";
 export { reconcileChanges, attachSource } from "./sync/driver.js";
 export { observeFile, observeMany, observeOne, observeDelete, observeBatch, type ObserveResult, type ObserveOneResult, type ObserveDeleteResult, type BatchItem, type BatchOutcome } from "./sync/observe.js";
-export { buildServer, type ServerContext } from "./mcp/server.js";
+export { buildServer, toolDescriptions, toolNames, unknownTool, UNKNOWN_TOOL_CODE, WRITE_TOOLS, MINIMAL_TOOLS, PROFILES, TOOLS_PROFILES, parseToolsProfile, type ServerContext, type ToolsProfile } from "./mcp/server.js";
 export { serveStdio, type ServeStdioHandle } from "./mcp/stdio.js";
 export { processCheckpoint, type CheckpointResult } from "./sync/checkpoint.js";
 export { reposStatus, syncStatus, reposList, type RepoStatus, type SyncStatus, type DiskStatus, type ReposList } from "./sync/admin.js";
@@ -60,12 +60,19 @@ export { sha256 } from "./core/hash.js";
 export { ingestFile, type IngestResult } from "./core/ingest.js";
 export { apply, type ApplyRequest, type ApplyResult, type Op } from "./mutate/apply.js";
 export { type DocStore, FsDocStore, NullDocStore, resolveDocStore } from "./mutate/doc-store.js";
+export { materializePending, materializeRow, listPending, readPending, type PendingRow, type PendingKind } from "./mutate/materialize.js";
 export { type To, type At, type Expect } from "./mutate/ops.js";
 export { tasksComplete, sectionsAppend, sectionsRename, sectionsMove, listsInsertItem, linksRetarget, nodeSet, editablePropsFor, type RetargetHit, } from "./mutate/macros.js";
-export { docsCreate, docsMove, docsDelete, docsSetMeta, type DocOpContext, type DocOpResult, type DocMoveOptions, type DocMoveResult, } from "./mutate/docs.js";
+export { canonicalDocPath, composeFile, splitFrontmatter, planInboundRetarget } from "./mutate/docs.js";
+export { createEffects, moveDocEffects, deleteDocEffects, setMetaEffects, updateContentEffects, insertEffects, updateBlockEffects, moveBlocksEffects, removeBlocksEffects, splitEffects, mergeEffects, checkEffects, nodeSetEffects, appendEffects, docsAppendEffects, retargetEffects, guardOf, requireAbsentPath, applySugar, createdDoc, docOutcome, moveLinks, type Sugar, type SugarDoc, type SugarRequest, type DocOpOutcome, type MoveLinks, } from "./mutate/sugar.js";
+export { planEffects, executePlan, executeByDigest, applyEffects, applyEffectsDetailed, substituteSymbols, admitPlan, canonicalJson, planDigest, PLAN_VERSION, PLANNER_V, type Plan, type PlanCore, type PlanOpset, type PlanPreconditions, type PlanPreview, type Receipt, type PlanEffectsRequest, type ExecuteRequest, } from "./mutate/plan.js";
+export { validateEffects, EFFECT_OPS, type Effect, type EffectTarget, type EffectExpect, type ResolvedEffect, type CreateEntry, type RetargetPreview } from "./mutate/effects.js";
+export { compileSelection, selectionQuery, SELECTION_CEILING, type Selection, type SelectionExpect, type CompiledSelection } from "./mutate/select.js";
+export { oqxRunQuery, reservedAlias } from "./oqx-js/run.js";
 export { inboundLinksTo, retargetLinksInRaw, type InboundLink } from "./graph/inbound-links.js";
-export { planUpdate, applyOpset, docsUpdate, type PlanUpdateOptions, type ApplyOpsetRequest, type DocsUpdateContext, type DocsUpdateResult, } from "./mutate/plan-update.js";
-export { opsetKernelOps, renderOpsetPlan, serializeOpset, parseOpset, type Opset, type PlanOp, type OpsetSummary, type OpsetPrecondition, type PlanDisposition, } from "./mutate/opset.js";
+export { planUpdate, type PlanUpdateOptions } from "./mutate/plan-update.js";
+export { opsetKernelOps, renderOpsetPlan, renderIdentityPlan, type IdentityPreview, serializeOpset, parseOpset, type Opset, type PlanOp, type OpsetSummary, type OpsetPrecondition, type PlanDisposition, } from "./mutate/opset.js";
 export { rebuildIndex, type RebuildTarget } from "./core/store/rebuild.js";
 export { runGc, type GcResult } from "./core/store/gc.js";
+export { sizeReport, sizeAdvice, vacuum, reclaimableBytes, humanBytes, formatShare, shareOf, categoryOf, TABLE_CATEGORY, SIZE_CATEGORIES, type SizeReport, type SizeCategory, type SizeCategoryReport, type SizeTable, type SizeFile, type VacuumResult, } from "./core/store/size.js";
 export { LIVE_LEAF_SQL, ftsIndexedRowCount, liveLeafCount } from "./core/store/fts.js";

package/dist/src/index.js

@@ -17,7 +17,7 @@ export { Workspace, RepoSelectionError, selectRepo } from "./sync/workspace.js";
 export { resolveSettings, workspaceSettings, repoOwnSettings, writeWorkspaceSettings, writeRepoSettings, deepMerge, } from "./sync/settings.js";
 export { freshnessSweep, rebuildFileStats, recordFileStat, recordStat, detectDiskDrift, sweepPlan, sweepCandidates, loadStatCache, snapshotOf, } from "./sync/freshness.js";
 export { recoverRepo } from "./sync/recovery.js";
-export { withWriterLock, writerLockFree, WriterLockTimeout } from "./sync/writer-lock.js";
+export { withWriterLock, withWriterLockAsync, writerLockFree, writerLockHeld, setWriterLockDefaults, writerLockDefaults, WriterLockTimeout } from "./sync/writer-lock.js";
 export { WatchLease, watchLeaseLive } from "./sync/watch-lease.js";
 export { ingestDirectory } from "./sync/attach.js";
 export { ensureRepo } from "./core/attach.js";
@@ -28,7 +28,7 @@ export { createExternalSource } from "./sync/external-source.js";
 export { ensureAdapter, listAdapters, createSource, deleteSource, listSources, getSourceByName, attachSourceToRepo, detachSourceFromRepo, sourcesForRepo, renderConfigFlags, } from "./sync/sources.js";
 export { reconcileChanges, attachSource } from "./sync/driver.js";
 export { observeFile, observeMany, observeOne, observeDelete, observeBatch } from "./sync/observe.js";
-export { buildServer } from "./mcp/server.js";
+export { buildServer, toolDescriptions, toolNames, unknownTool, UNKNOWN_TOOL_CODE, WRITE_TOOLS, MINIMAL_TOOLS, PROFILES, TOOLS_PROFILES, parseToolsProfile } from "./mcp/server.js";
 export { serveStdio } from "./mcp/stdio.js";
 export { processCheckpoint } from "./sync/checkpoint.js";
 export { reposStatus, syncStatus, reposList } from "./sync/admin.js";
@@ -67,16 +67,27 @@ export { ingestFile } from "./core/ingest.js";
 // Mutation surface consumed by CLI write commands (11 §5.6).
 export { apply } from "./mutate/apply.js";
 export { FsDocStore, NullDocStore, resolveDocStore } from "./mutate/doc-store.js";
+export { materializePending, materializeRow, listPending, readPending } from "./mutate/materialize.js";
 export {} from "./mutate/ops.js";
 export { tasksComplete, sectionsAppend, sectionsRename, sectionsMove, listsInsertItem, linksRetarget, nodeSet, editablePropsFor, } from "./mutate/macros.js";
-// Admin/maintenance (11 §5.9). Graph traversal is OQX `follow` now (see oqx/).
-export { docsCreate, docsMove, docsDelete, docsSetMeta, } from "./mutate/docs.js";
+// The document operations' shared pieces (spec/mutate §6); the operations themselves are the effect builders below.
+export { canonicalDocPath, composeFile, splitFrontmatter, planInboundRetarget } from "./mutate/docs.js";
+// The effect builders (spec/mutate §6/§10, 3.0; spec/surface §4 "Sugar over effects", 4.0): one per operation,
+// shared by the MCP server, the `omg` verbs and the fixture runner, plus `applySugar` and the Receipt adapters.
+export { createEffects, moveDocEffects, deleteDocEffects, setMetaEffects, updateContentEffects, insertEffects, updateBlockEffects, moveBlocksEffects, removeBlocksEffects, splitEffects, mergeEffects, checkEffects, nodeSetEffects, appendEffects, docsAppendEffects, retargetEffects, guardOf, requireAbsentPath, applySugar, createdDoc, docOutcome, moveLinks, } from "./mutate/sugar.js";
+// The Effect layer (ADR-021, spec/mutate §11): plan / execute / apply { effects } and the plan's shapes.
+export { planEffects, executePlan, executeByDigest, applyEffects, applyEffectsDetailed, substituteSymbols, admitPlan, canonicalJson, planDigest, PLAN_VERSION, PLANNER_V, } from "./mutate/plan.js";
+export { validateEffects, EFFECT_OPS } from "./mutate/effects.js";
+// Query-directed planning (spec/mutate §11.8, 3.1): the selector binding behind `plan`/`apply`/`execute { select }`.
+export { compileSelection, selectionQuery, SELECTION_CEILING } from "./mutate/select.js";
+export { oqxRunQuery, reservedAlias } from "./oqx-js/run.js";
 // Inbound-link discovery + destination-aware rewrite (docs_move's dangling report / retarget_inbound).
 export { inboundLinksTo, retargetLinksInRaw } from "./graph/inbound-links.js";
-// Whole-document update: reconcile → opset → inspect/apply.
-export { planUpdate, applyOpset, docsUpdate, } from "./mutate/plan-update.js";
-export { opsetKernelOps, renderOpsetPlan, serializeOpset, parseOpset, } from "./mutate/opset.js";
+// Whole-document update: reconcile → opset (the `set content` effect's internal planner since 3.0; `preview.identity` surfaces it).
+export { planUpdate } from "./mutate/plan-update.js";
+export { opsetKernelOps, renderOpsetPlan, renderIdentityPlan, serializeOpset, parseOpset, } from "./mutate/opset.js";
 export { rebuildIndex } from "./core/store/rebuild.js";
 export { runGc } from "./core/store/gc.js";
+export { sizeReport, sizeAdvice, vacuum, reclaimableBytes, humanBytes, formatShare, shareOf, categoryOf, TABLE_CATEGORY, SIZE_CATEGORIES, } from "./core/store/size.js";
 export { LIVE_LEAF_SQL, ftsIndexedRowCount, liveLeafCount } from "./core/store/fts.js";
 //# sourceMappingURL=index.js.map