mlx-bun 0.5.0 → 1.0.0

package/src/memory/db.ts

@@ -1,253 +0,0 @@
-// mlx-bun memory — "The Dreaming" synthesis store (bun:sqlite).
-//
-// Two kinds of tables live here:
-//
-//   • 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.
-//
-//   • 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";
-
-export const DEFAULT_MEMORY_DB = `${process.env.HOME}/.cache/mlx-bun/memory.sqlite`;
-
-export interface ConversationRow {
-  /** Stable conv id: first 8 hex of the session UUID (the conv:HASH citation). */
-  conv: string;
-  source: string; // "pi-web" | "pi-terminal"
-  title: string;
-  updated_at: number;
-  chunked_at: number | null;
-}
-
-export interface ChunkRow {
-  /** Deterministic id `${conv}:${start}-${end}` — idempotent re-chunking. */
-  id: string;
-  conv: string;
-  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_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,
-  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 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 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)
-);
-CREATE TABLE IF NOT EXISTS watermarks (
-  source     TEXT PRIMARY KEY,
-  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)
-);
-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);
-`;
-
-/**
- * "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;
-  readonly dbPath: string;
-
-  constructor(dbPath: string = DEFAULT_MEMORY_DB) {
-    if (dbPath !== ":memory:") {
-      try { mkdirSync(dbPath.slice(0, dbPath.lastIndexOf("/")), { recursive: true }); } catch {}
-    }
-    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

@@ -1,203 +0,0 @@
-// 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

@@ -1,187 +0,0 @@
-// 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 };
-}