mlx-bun 0.0.7 → 0.0.9

package/src/memory/db.ts

@@ -1,19 +1,29 @@
-// mlx-bun memory — synthesis bookkeeping store (bun:sqlite).
+// mlx-bun memory — "The Dreaming" synthesis store (bun:sqlite).
 //
-// ⚠️ M1 STUB schema-wise the tables are real, but no stage writes them yet.
-// The read path (vault.ts / tools.ts) does NOT touch this — it's only used by
-// the synthesis pipeline (pipeline.ts), which is itself stubbed.
+// Two kinds of tables live here:
 //
-// Reuses mlx-bun's existing per-domain sqlite pattern (cf. JobStore in
-// src/jobs/db.ts, EvalDB in src/evaldb.ts): a small class over bun:sqlite with
-// WAL + schema-in-constructor + an additive migrate() hook, living under
-// ~/.cache/mlx-bun/ alongside jobs.sqlite / evals.sqlite / registry.sqlite. It's
-// derived state — rebuildable from the pi transcripts + the vault articles — so
-// it belongs in the rebuildable cache, NOT in the (precious, git-tracked) vault.
+//   • DERIVED CACHE — entities, entity_aliases, categories, article_categories,
+//     infobox_facts, links. These are a *cache of the markdown vault*: every row
+//     can be regenerated by reindexing the articles. reindex makes them match the
+//     vault, NEVER the reverse — if a row disagrees with the markdown, the
+//     markdown wins and the row is rebuilt.
 //
-// The schema mirrors lucien's incremental design: per-source watermarks (don't
-// re-ingest), chunked_at > updated_at (re-chunk only changed convs), and a
-// synthesized-chunk ledger (never fold the same chunk into an article twice).
+//   • SYNTHESIS LEDGER — messages, chunks, chunk_entities, chunk_sections,
+//     synthesized_chunk_sections, watermarks (+ buckets/chunk_buckets +
+//     subject_redirects, the fold/capture sub-concept→home-article edges that the
+//     reindex projects into entity_aliases). These are
+//     the pipeline's bookkeeping: what we ingested, how we cut it, and what has
+//     already been folded into the vault. This is the authoritative record of
+//     pipeline progress and is not reconstructable from the vault alone.
+//
+// Storage is pointer-based: chunks do NOT copy conversation text. A chunk is a
+// [start,end] position range into its conversation's messages; chunkText()
+// reassembles the slice on demand. Total stored text == the messages, once.
+//
+// Reuses mlx-bun's per-domain sqlite pattern (cf. JobStore in src/jobs/db.ts,
+// EvalDB in src/evaldb.ts): a small class over bun:sqlite with WAL +
+// schema-in-constructor + a migrate() hook, living under ~/.cache/mlx-bun/.
+// It's rebuildable derived state, so it belongs in the cache, NOT the vault.
 
 import { Database } from "bun:sqlite";
 import { mkdirSync } from "node:fs";
@@ -25,68 +35,156 @@ export interface ConversationRow {
   conv: string;
   source: string; // "pi-web" | "pi-terminal"
   title: string;
-  /** Full normalized transcript JSON ({role, content}[]). */
-  transcript: string;
   updated_at: number;
   chunked_at: number | null;
 }
 
 export interface ChunkRow {
+  /** Deterministic id `${conv}:${start}-${end}` — idempotent re-chunking. */
   id: string;
   conv: string;
-  ordinal: number;
-  text: string;
-  bucket: string | null;
+  start: number;
+  end: number;
+  label: string | null;
+}
+
+export interface EntityRow {
+  name: string;
+  article_stem: string | null;
+  kind: string | null;
+  notable: number;
 }
 
 export interface BucketRow {
   name: string;
-  article: string; // target article stem
+  article_stem: string;
   description: string;
 }
 
+/** Deterministic chunk id from its conversation + position range. */
+export function chunkId(conv: string, start: number, end: number): string {
+  return `${conv}:${start}-${end}`;
+}
+
 const SCHEMA = `
 CREATE TABLE IF NOT EXISTS conversations (
   conv       TEXT PRIMARY KEY,
-  source     TEXT NOT NULL,
-  title      TEXT NOT NULL DEFAULT '',
-  transcript TEXT NOT NULL,
-  updated_at INTEGER NOT NULL,
+  source     TEXT,
+  title      TEXT DEFAULT '',
+  updated_at INTEGER,
   chunked_at INTEGER
 );
+CREATE TABLE IF NOT EXISTS messages (
+  conv     TEXT REFERENCES conversations(conv) ON DELETE CASCADE,
+  position INTEGER,
+  role     TEXT,
+  uuid     TEXT,
+  text     TEXT,
+  PRIMARY KEY (conv, position)
+);
 CREATE TABLE IF NOT EXISTS chunks (
-  id      TEXT PRIMARY KEY,
-  conv    TEXT NOT NULL REFERENCES conversations(conv),
-  ordinal INTEGER NOT NULL,
-  text    TEXT NOT NULL,
-  bucket  TEXT
+  id    TEXT PRIMARY KEY,
+  conv  TEXT REFERENCES conversations(conv) ON DELETE CASCADE,
+  start INTEGER,
+  end   INTEGER,
+  label TEXT
 );
 CREATE INDEX IF NOT EXISTS idx_chunks_conv ON chunks(conv);
-CREATE TABLE IF NOT EXISTS buckets (
-  name        TEXT PRIMARY KEY,
-  article     TEXT NOT NULL,
-  description TEXT NOT NULL DEFAULT ''
+CREATE TABLE IF NOT EXISTS entities (
+  name         TEXT PRIMARY KEY,
+  article_stem TEXT,
+  kind         TEXT,
+  notable      INTEGER DEFAULT 0
+);
+CREATE TABLE IF NOT EXISTS entity_aliases (
+  alias       TEXT,
+  entity_name TEXT REFERENCES entities(name) ON DELETE CASCADE,
+  PRIMARY KEY (alias, entity_name)
+);
+CREATE INDEX IF NOT EXISTS idx_aliases_alias ON entity_aliases(alias);
+CREATE TABLE IF NOT EXISTS chunk_entities (
+  chunk_id     TEXT REFERENCES chunks(id) ON DELETE CASCADE,
+  entity_name  TEXT REFERENCES entities(name) ON DELETE CASCADE,
+  surface_form TEXT,
+  PRIMARY KEY (chunk_id, entity_name)
+);
+CREATE TABLE IF NOT EXISTS categories (
+  name       TEXT PRIMARY KEY,
+  definition TEXT DEFAULT '',
+  parent     TEXT REFERENCES categories(name) ON DELETE SET NULL
+);
+CREATE TABLE IF NOT EXISTS article_categories (
+  article_stem TEXT,
+  category     TEXT REFERENCES categories(name) ON DELETE CASCADE,
+  source       TEXT,
+  PRIMARY KEY (article_stem, category)
+);
+CREATE INDEX IF NOT EXISTS idx_artcat_category ON article_categories(category);
+CREATE TABLE IF NOT EXISTS infobox_facts (
+  article_stem TEXT,
+  key          TEXT,
+  value        TEXT,
+  kind         TEXT,
+  entity_link  TEXT,
+  PRIMARY KEY (article_stem, key, value)
+);
+CREATE INDEX IF NOT EXISTS idx_infobox_key ON infobox_facts(key);
+CREATE INDEX IF NOT EXISTS idx_infobox_link ON infobox_facts(entity_link);
+CREATE TABLE IF NOT EXISTS links (
+  src_stem TEXT,
+  dst_stem TEXT,
+  via      TEXT,
+  PRIMARY KEY (src_stem, dst_stem, via)
+);
+CREATE INDEX IF NOT EXISTS idx_links_dst ON links(dst_stem);
+CREATE TABLE IF NOT EXISTS chunk_sections (
+  chunk_id       TEXT REFERENCES chunks(id) ON DELETE CASCADE,
+  article_stem   TEXT,
+  section_anchor TEXT,
+  PRIMARY KEY (chunk_id, article_stem, section_anchor)
+);
+CREATE TABLE IF NOT EXISTS synthesized_chunk_sections (
+  chunk_id       TEXT REFERENCES chunks(id) ON DELETE CASCADE,
+  article_stem   TEXT,
+  section_anchor TEXT,
+  synthesized_at INTEGER,
+  PRIMARY KEY (chunk_id, article_stem, section_anchor)
+);
+CREATE TABLE IF NOT EXISTS reconciled_articles (
+  article_stem  TEXT,
+  reconciled_at INTEGER,
+  refreshed     TEXT,
+  rewritten     TEXT,
+  PRIMARY KEY (article_stem, reconciled_at)
 );
--- Per-source ingest watermark: only process what's new since last run.
 CREATE TABLE IF NOT EXISTS watermarks (
   source     TEXT PRIMARY KEY,
-  cursor     TEXT NOT NULL,
-  updated_at INTEGER NOT NULL
+  cursor     TEXT,
+  updated_at INTEGER
+);
+CREATE TABLE IF NOT EXISTS buckets (
+  name         TEXT PRIMARY KEY,
+  article_stem TEXT,
+  description  TEXT DEFAULT ''
+);
+CREATE TABLE IF NOT EXISTS chunk_buckets (
+  chunk_id TEXT REFERENCES chunks(id) ON DELETE CASCADE,
+  bucket   TEXT REFERENCES buckets(name) ON DELETE CASCADE,
+  PRIMARY KEY (chunk_id, bucket)
 );
--- Idempotency ledger: a (bucket, chunk) pair is folded into an article once.
-CREATE TABLE IF NOT EXISTS synthesized_bucket_chunks (
-  bucket   TEXT NOT NULL,
-  chunk_id TEXT NOT NULL,
-  PRIMARY KEY (bucket, chunk_id)
+CREATE TABLE IF NOT EXISTS subject_redirects (
+  surface     TEXT,
+  target_stem TEXT,
+  kind        TEXT,
+  PRIMARY KEY (surface, target_stem)
 );
+CREATE INDEX IF NOT EXISTS idx_redirect_target ON subject_redirects(target_stem);
 `;
 
 /**
- * Synthesis bookkeeping DB. Same shape as JobStore/EvalDB: open in the
- * constructor (WAL on, schema ensured, additive migrate), expose `db`, and a
- * `close()`. Only the synthesis pipeline constructs one — opening it is what
- * *creates* memory.sqlite, so the read path never does. Stage queries land in
- * M1; the tables they expect already exist here.
+ * "The Dreaming" synthesis store. Same shape as JobStore/EvalDB: open in the
+ * constructor (WAL on, foreign keys on, schema ensured, additive migrate),
+ * expose `db`, and a `close()`.
  */
 export class MemoryStore {
   readonly db: Database;
@@ -99,15 +197,56 @@ export class MemoryStore {
     this.dbPath = dbPath;
     this.db = new Database(dbPath);
     this.db.exec("PRAGMA journal_mode = WAL");
+    if (this.hasLegacySchema()) this.dropAllTables();
+    this.db.exec("PRAGMA foreign_keys = ON");
     this.db.exec(SCHEMA);
     this.migrate();
   }
 
+  /**
+   * A DB written by the pre-rewrite (bucket/transcript) schema. There is no
+   * production data to preserve, so detecting either marker means: nuke and
+   * recreate from scratch. Markers: chunks.text column, or the dropped
+   * synthesized_bucket_chunks table.
+   */
+  private hasLegacySchema(): boolean {
+    const cols = this.db.query("PRAGMA table_info(chunks)").all() as { name: string }[];
+    if (cols.some((c) => c.name === "text")) return true;
+    const legacy = this.db
+      .query("SELECT name FROM sqlite_master WHERE type='table' AND name='synthesized_bucket_chunks'")
+      .get();
+    return legacy != null;
+  }
+
+  /** Drop every user table (FK checks off during the teardown). */
+  private dropAllTables(): void {
+    this.db.exec("PRAGMA foreign_keys = OFF");
+    const tables = this.db
+      .query("SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%'")
+      .all() as { name: string }[];
+    for (const { name } of tables) this.db.exec(`DROP TABLE IF EXISTS "${name}"`);
+  }
+
   /** Additive-only migrations (mirrors JobStore.migrate). Re-opening is a no-op. */
   private migrate(): void {
     // No columns to add today; the hook stays so future fields are additive.
   }
 
+  /**
+   * Reassemble a chunk's text from its messages by position range — chunks are
+   * pointers, not copies. Returns "" for an unknown chunk id.
+   */
+  chunkText(id: string): string {
+    const chunk = this.db
+      .query("SELECT conv, start, end FROM chunks WHERE id = ?")
+      .get(id) as { conv: string; start: number; end: number } | null;
+    if (!chunk) return "";
+    const rows = this.db
+      .query("SELECT text FROM messages WHERE conv = ? AND position BETWEEN ? AND ? ORDER BY position")
+      .all(chunk.conv, chunk.start, chunk.end) as { text: string }[];
+    return rows.map((r) => r.text).join("\n");
+  }
+
   close(): void {
     this.db.close();
   }

package/src/memory/entity.ts

@@ -0,0 +1,203 @@
+// mlx-bun memory — ENTITY-EXTRACT (P5-T3).
+//
+// Reads ONE chunk's reassembled TEXT and asks the local model "what things is
+// this chunk about?", returning canonical wiki-title entity names — the specific
+// things AND the broad domain. This is the REAL routing-thesis test: unlike the
+// P4 label-proxy (which routed on the 4–10-word episodic chunk label), this
+// stage reads the full conversation text, so it sees the entities the label
+// merely gestures at.
+//
+// Design (P5-T3):
+//   - ONE chunk per call (NO multi-item JSON, NO batch indices — that
+//     batch-index drift is what sank Lucien's batched assign). Output is a plain
+//     newline list parsed by parseLines.
+//   - `Entities.md` policy (the five kinds, notability checklist, naming rules,
+//     emit-both-granularities) is inlined into the prompt via loadMetaPolicy, so
+//     editing the vault page re-tunes extraction with no code change.
+//   - Deterministic canonicalization (casefold, ws-collapse, strip leading
+//     articles/possessives) so a name's spacing/short-form/brand-only variants
+//     collapse to one stem. The canonical stem feeds dedup + the entity_aliases index.
+//   - Persists chunk_entities(chunk_id, entity_name, surface_form) and upserts a
+//     candidate entities row (article_stem NULL — no article exists yet) so the
+//     FK on chunk_entities.entity_name is satisfied; the raw model surface is
+//     stored as an alias of the canonical name.
+//
+// The base model + policy runs until a `memory-entity` LoRA is trained (P10-T3),
+// which only happens on a measured recall miss here.
+
+import type { MemoryStore } from "./db";
+import { callLocal } from "./model";
+import { parseLines } from "./parse";
+import { loadMetaPolicy } from "./prompts";
+import { EntityResolver, goldSeeds } from "./resolve";
+
+/** Model-call seam for extraction (defaults to the local `entity` stage). Injected
+ *  by the pipeline + tests so the deterministic scaffolding runs with no GPU. */
+export type ExtractCall = (prompt: string, opts?: { maxTokens?: number }) => Promise<string>;
+
+/** One extracted entity: the canonical wiki-title name + the raw model surface. */
+export interface ExtractedEntity {
+  /** Canonical wiki-title name (the model's line, cleaned of markup/trailing
+   *  punctuation) — the value written to chunk_entities.entity_name. */
+  name: string;
+  /** The raw surface the model emitted (chunk_entities.surface_form). */
+  surface: string;
+  /** Deterministic canonical stem (casefold/ws-collapse/strip articles+
+   *  possessives) used for dedup and alias keying. */
+  stem: string;
+}
+
+const QUESTION =
+  "What things is this chunk about? List canonical wiki-title names, one per " +
+  "line; include specific things AND the broad domain. Output NONE if nothing " +
+  "nameable or substantive.";
+
+/**
+ * Deterministic canonical stem of an entity surface: casefold, collapse
+ * whitespace/underscores, strip surrounding markdown/quotes, drop a trailing
+ * period, then strip ONE leading article (the/a/an) and ONE leading possessive
+ * determiner (my/your/his/her/its/our/their), plus a trailing possessive `'s`.
+ *
+ * This is the dedup key: a name's spacing variants, short forms, brand-only
+ * surfaces, and possessive surfaces all collapse toward one stem so variants of
+ * the same thing unify.
+ */
+export function canonicalize(surface: string): string {
+  let t = surface
+    .toLowerCase()
+    .replace(/[*_`"'“”]+/g, " ") // strip md emphasis / quotes
+    .replace(/[_\s]+/g, " ")
+    .trim()
+    .replace(/[.,;:]+$/, "")
+    .trim();
+  // strip a leading list marker / numbering the model may emit ("- ", "1. ")
+  t = t.replace(/^(?:[-*•]\s+|\d+[.)]\s+)/, "").trim();
+  // strip ONE leading article, then ONE leading possessive determiner
+  t = t.replace(/^(?:the|a|an)\s+/, "").trim();
+  t = t.replace(/^(?:my|your|his|her|its|our|their)\s+/, "").trim();
+  // strip a trailing saxon-genitive
+  t = t.replace(/['’]s$/, "").trim();
+  return t;
+}
+
+/** Clean a raw model line into a stored canonical NAME (preserve casing/words,
+ *  just strip surrounding markup, list markers, and trailing punctuation). */
+function cleanName(line: string): string {
+  return line
+    .replace(/^(?:[-*•]\s+|\d+[.)]\s+)/, "")
+    .replace(/^[*_`"“]+|[*_`"”]+$/g, "")
+    .replace(/[.,;:]+$/, "")
+    .trim();
+}
+
+/**
+ * Build the entity-extraction prompt: inlined `Entities.md` policy + the chunk
+ * text + the fixed question. The policy block is passed in so callers can cache
+ * it across many chunks (loadMetaPolicy does disk IO).
+ */
+export function buildEntityPrompt(text: string, policy: string): string {
+  return (
+    `${policy}\n\n` +
+    `--- Conversation chunk ---\n${text}\n--- end chunk ---\n\n` +
+    QUESTION
+  );
+}
+
+/**
+ * Core extraction: render the prompt, call the base model (maxTokens 128), parse
+ * the newline list, clean + canonicalize each surface, and de-duplicate by stem.
+ * Pure w.r.t. the DB. Returns the extracted entities AND the raw newline-line
+ * count (pre-dedup) so instruments can report the canonicalizer's parse health.
+ */
+export async function extractEntityNamesRaw(
+  text: string,
+  policy?: string,
+  opts?: { maxTokens?: number; call?: ExtractCall },
+): Promise<{ entities: ExtractedEntity[]; rawLines: number }> {
+  if (!text.trim()) return { entities: [], rawLines: 0 };
+  const pol = policy ?? loadMetaPolicy(["Entities"]);
+  const prompt = buildEntityPrompt(text, pol);
+  const call: ExtractCall = opts?.call ?? ((p, o) => callLocal("entity", { user: p }, o));
+  const out = await call(prompt, { maxTokens: opts?.maxTokens ?? 128 });
+  const lines = parseLines(out);
+  const seen = new Set<string>();
+  const entities: ExtractedEntity[] = [];
+  for (const raw of lines) {
+    const surface = cleanName(raw);
+    const stem = canonicalize(surface);
+    if (!stem || !surface) continue;
+    if (seen.has(stem)) continue; // collapse variants of one thing
+    seen.add(stem);
+    entities.push({ name: surface, surface: raw.trim(), stem });
+  }
+  return { entities, rawLines: lines.length };
+}
+
+/** Convenience wrapper: just the extracted entities (no raw-line count). */
+export async function extractEntityNames(
+  text: string,
+  policy?: string,
+  opts?: { maxTokens?: number; call?: ExtractCall },
+): Promise<ExtractedEntity[]> {
+  return (await extractEntityNamesRaw(text, policy, opts)).entities;
+}
+
+/**
+ * Full stage: extract the entities a chunk is about and PERSIST them.
+ *
+ * Each extracted surface is RESOLVED to a canonical entity through the variant
+ * resolver (squeeze/alias/token-subset; see resolve.ts) so casing/spacing/brand
+ * variants collapse onto ONE entity instead of minting a fresh row each — the
+ * dedup fix. The resolver is seeded from the store's existing entities/aliases
+ * AND the curated gold (so notable brand-only nicknames fold), and accumulates
+ * minted canonicals across chunks when the caller threads one in via `opts`.
+ *
+ * Upserts the resolved canonical `entities` row (article_stem NULL — no article
+ * exists yet; ROUTE/CREATE promote it later) so the chunk_entities FK is
+ * satisfied, records the raw surface as an alias of the canonical, and writes one
+ * chunk_entities row per distinct resolved entity. Idempotent: re-running on the
+ * same chunk INSERT-OR-IGNOREs the same rows.
+ *
+ * Returns the extracted list (also useful to callers that route immediately).
+ */
+export async function extractEntities(
+  store: MemoryStore,
+  chunkId: string,
+  opts?: { maxTokens?: number; policy?: string; resolver?: EntityResolver; call?: ExtractCall },
+): Promise<ExtractedEntity[]> {
+  const text = store.chunkText(chunkId);
+  const extracted = await extractEntityNames(text, opts?.policy, opts);
+
+  // Seed once from the store + gold unless the caller threads a shared resolver
+  // (which lets minted canonicals carry across chunks in a single run).
+  const resolver = opts?.resolver ?? EntityResolver.fromStore(store);
+  if (!opts?.resolver) for (const s of goldSeeds()) resolver.register(s.canonical, s.aliases);
+
+  const insEntity = store.db.query(
+    "INSERT OR IGNORE INTO entities (name, article_stem, kind, notable) VALUES (?, NULL, NULL, 0)",
+  );
+  const insAlias = store.db.query(
+    "INSERT OR IGNORE INTO entity_aliases (alias, entity_name) VALUES (?, ?)",
+  );
+  const insChunkEntity = store.db.query(
+    "INSERT OR IGNORE INTO chunk_entities (chunk_id, entity_name, surface_form) VALUES (?, ?, ?)",
+  );
+
+  // Resolve OUTSIDE the write tx (the resolver index is in-memory, no DB writes),
+  // collapsing within-chunk variants onto one canonical before persisting.
+  const resolved = new Map<string, string>(); // canonical → first raw surface seen
+  for (const e of extracted) {
+    const canonical = resolver.resolve(e.name).name;
+    if (!resolved.has(canonical)) resolved.set(canonical, e.surface);
+  }
+
+  const tx = store.db.transaction(() => {
+    for (const [canonical, surface] of resolved) {
+      insEntity.run(canonical);
+      insAlias.run(canonicalize(surface), canonical);
+      insChunkEntity.run(chunkId, canonical, surface);
+    }
+  });
+  tx();
+  return extracted;
+}

package/src/memory/gate.ts

@@ -0,0 +1,187 @@
+// mlx-bun memory — the conservative write gate.
+//
+// The Dreaming write pipeline patches articles section-by-section. Before any
+// synthesized edit is committed to the vault, it passes through this gate: a
+// deterministic, GPU-free check that the edit PRESERVED the existing article
+// rather than degrading it. A weak pass is a NO-OP — the caller discards the
+// model's output and leaves the vault byte-for-byte unchanged.
+//
+// This is a faithful port of Lucien's editorial gate (scripts/wikify.ts:
+// verifyEditorialResult / checkFootnoteIntegrity / extractConvHashes). It
+// catches citation loss, structural loss, footnote-bijection breaks, and gross
+// prose deletion. It does NOT catch nuance loss — that is the cloud judge's job.
+// The gate is mechanism, not policy: it can only reject, never rewrite.
+
+// ---- citation hashes --------------------------------------------------
+
+// Illustrative placeholder hashes the synthesis prompt warns against; never
+// real citations, so excluded from the preservation set.
+const SPEC_HASHES = new Set(["00000000", "00000001"]);
+
+/** All real `conv:HASH` citation hashes in `text`, lowercased, minus the
+ *  documented spec placeholders. A `conv:` hash is exactly 8 lowercase
+ *  hex-ish chars `[0-9a-z]` (matched case-insensitively, then lowered). */
+export function extractConvHashes(text: string): Set<string> {
+  const out = new Set<string>();
+  for (const m of text.matchAll(/conv:([0-9a-z]{8})/gi)) {
+    const h = m[1]!.toLowerCase();
+    if (!SPEC_HASHES.has(h)) out.add(h);
+  }
+  return out;
+}
+
+// ---- footnote integrity ----------------------------------------------
+
+export interface CheckResult {
+  ok: boolean;
+  /** Human-readable violations; empty when `ok`. */
+  errors: string[];
+}
+
+/**
+ * Verify footnote markers and definitions form a clean bijection:
+ * - every `[^N]` body marker has a matching `[^N]:` definition and vice versa;
+ * - marker/definition numbers are contiguous from 1;
+ * - every definition line carries exactly one backticked `conv:HASH`.
+ *
+ * Only a line-START `[^N]:` is a definition. A body marker glued to a
+ * list-introducing colon (`...two types[^2]:`) is still a marker, so we strip
+ * definition lines before scanning for markers rather than excluding any
+ * `[^N]` followed by `:`.
+ */
+export function checkFootnoteIntegrity(text: string): CheckResult {
+  const errors: string[] = [];
+
+  // Definition lines: `[^N]: ...` at line start.
+  const defNums = new Set<number>();
+  const defLineByNum = new Map<number, string>();
+  const defSeen = new Set<number>();
+  for (const m of text.matchAll(/^\[\^(\d+)\]:(.*)$/gm)) {
+    const n = parseInt(m[1]!, 10);
+    if (defSeen.has(n)) errors.push(`definition [^${n}] is duplicated`);
+    defSeen.add(n);
+    defNums.add(n);
+    defLineByNum.set(n, m[2]!);
+  }
+
+  // Body markers: every `[^N]` outside a definition line.
+  const bodyText = text
+    .split("\n")
+    .filter((l) => !/^\[\^\d+\]:/.test(l))
+    .join("\n");
+  const markerNums = new Set<number>();
+  for (const m of bodyText.matchAll(/\[\^(\d+)\]/g)) {
+    markerNums.add(parseInt(m[1]!, 10));
+  }
+
+  for (const n of markerNums) {
+    if (!defNums.has(n)) errors.push(`marker [^${n}] has no definition`);
+  }
+  for (const n of defNums) {
+    if (!markerNums.has(n)) errors.push(`definition [^${n}] has no marker`);
+  }
+
+  const all = [...new Set([...markerNums, ...defNums])].sort((a, b) => a - b);
+  for (let i = 0; i < all.length; i++) {
+    if (all[i] !== i + 1) {
+      errors.push(`footnote numbers not contiguous from 1 (saw ${all.join(",")})`);
+      break;
+    }
+  }
+
+  for (const [n, line] of defLineByNum) {
+    const backticked = line.match(/`conv:[0-9a-z]{8}`/gi) ?? [];
+    if (backticked.length !== 1) {
+      errors.push(`[^${n}] definition lacks a backticked \`conv:HASH\` (found ${backticked.length})`);
+    }
+  }
+
+  return { ok: errors.length === 0, errors };
+}
+
+// ---- the gate ---------------------------------------------------------
+
+export interface GateOptions {
+  /** Edited word count must be >= floor * before's word count. Default 0.7. */
+  floor?: number;
+  /** Citation hashes the caller has DELIBERATELY pruned (a factual-error fix that
+   *  removes a wrong value as if it had never been there). Their loss is permitted
+   *  rather than vetoed as accidental citation loss. Empty by default. */
+  allowDroppedHashes?: Set<string>;
+}
+
+export interface GateVerdict {
+  /** True when the edit is safe to commit. */
+  ok: boolean;
+  /** Null when `ok`; otherwise the joined failing reasons, so the caller can
+   *  log WHY the edit was discarded. */
+  reason: string | null;
+}
+
+function wordCount(s: string): number {
+  const t = s.trim();
+  return t ? t.split(/\s+/).length : 0;
+}
+
+/** True when `text` contains an H1 title line (`# Title`). */
+function hasH1(text: string): boolean {
+  return text.split("\n").some((l) => /^#\s+\S/.test(l.trim()));
+}
+
+/** True when `text` contains a `## References` section heading. */
+function hasReferences(text: string): boolean {
+  return /^##\s+References\s*$/m.test(text);
+}
+
+/**
+ * The conservative write gate. Given the (before, after) text of a section or
+ * article, decide whether the edit preserved it. On `ok: false` the caller
+ * MUST discard `after` and keep `before` — the vault stays unchanged.
+ *
+ * Enforces (deterministically, no GPU):
+ * 1. Citation preservation — every pre-existing `conv:HASH` survives.
+ * 2. Footnote bijection — every `[^N]` marker ⇔ one `[^N]:` definition.
+ * 3. Prose preservation — the edited word count stays at/above the floor.
+ * 4. Structural survival — an H1 and `## References` present before survive.
+ *
+ * Catches citation/structure/bulk-prose loss; does NOT catch nuance loss.
+ */
+export function gateEdit(before: string, after: string, opts: GateOptions = {}): GateVerdict {
+  const floor = opts.floor ?? 0.7;
+  const reasons: string[] = [];
+
+  // 1. Citation preservation: every pre-existing hash must still be cited —
+  //    UNLESS the caller deliberately pruned it (a factual-error fix).
+  const beforeHashes = extractConvHashes(before);
+  const afterHashes = extractConvHashes(after);
+  const allowed = opts.allowDroppedHashes ?? new Set<string>();
+  for (const h of beforeHashes) {
+    if (!afterHashes.has(h) && !allowed.has(h)) reasons.push(`dropped citation conv:${h}`);
+  }
+
+  // 2. Footnote bijection on the edited text.
+  const fn = checkFootnoteIntegrity(after);
+  if (!fn.ok) reasons.push(...fn.errors);
+
+  // 3. Prose preservation: word floor on the touched text.
+  const bw = wordCount(before);
+  const aw = wordCount(after);
+  if (bw > 0 && aw < floor * bw) {
+    reasons.push(`word count ${aw} below floor ${Math.ceil(floor * bw)} (before ${bw})`);
+  }
+
+  // 4. Structural survival: an H1 / ## References present before must survive.
+  if (hasH1(before) && !hasH1(after)) reasons.push("edit dropped the H1 title");
+  if (hasReferences(before) && !hasReferences(after)) {
+    reasons.push("edit dropped the ## References section");
+  }
+
+  // 5. See-also singularity: a fence-confused rebuild that buried one ## See also
+  //    and appended another would grow the section unboundedly. Reject (NO-OP) any
+  //    result carrying more than ONE ## See also heading, so the section can never
+  //    grow regardless of how pathological the input was.
+  const seeAlsoCount = (after.match(/^##\s+See also\s*$/gim) ?? []).length;
+  if (seeAlsoCount > 1) reasons.push(`multiple ## See also sections (${seeAlsoCount})`);
+
+  return reasons.length ? { ok: false, reason: reasons.join("; ") } : { ok: true, reason: null };
+}