synabun 1.3.0 → 2.0.0

package/neural-interface/lib/rulesets/json-edit.js

@@ -0,0 +1,186 @@
+// ═══════════════════════════════════════════
+// SynaBun — one entry of a JSON list, edited as text (pure, no fs)
+// ═══════════════════════════════════════════
+//
+// OpenCode's config.json belongs to the user. Parsing it and writing it back
+// would re-indent it, re-space it and drop whatever JSON.stringify spells
+// differently, all to add one string to one list. These two functions change
+// only the characters of that entry (and of the key, when SynaBun adds or takes
+// away the whole list): every other byte, the BOM, the line endings and the
+// final newline stay as they were.
+//
+// Input must be strict JSON holding an object (the caller parsed it already).
+// Both throw on text they cannot follow, and on a key that is there more than
+// once (code DUPLICATE_KEY): JSON.parse keeps the last one, so an edit of
+// either would lose or strand an entry. The caller then refuses to write;
+// nothing here, and nothing in the installer, re-serialises the file.
+
+const WHITESPACE = new Set([' ', '\t', '\r', '\n']);
+
+function skipSpace(text, pos) {
+  while (pos < text.length && WHITESPACE.has(text[pos])) pos++;
+  return pos;
+}
+
+function skipString(text, pos) {
+  for (let i = pos + 1; i < text.length; i++) {
+    if (text[i] === '\\') { i++; continue; }
+    if (text[i] === '"') return i + 1;
+  }
+  throw new Error('JSON string without an end');
+}
+
+/** The offset just past the value that starts at `pos`. */
+function skipValue(text, pos) {
+  const first = text[pos];
+  if (first === '"') return skipString(text, pos);
+  if (first === '{' || first === '[') {
+    let depth = 0;
+    for (let i = pos; i < text.length; i++) {
+      const ch = text[i];
+      if (ch === '"') { i = skipString(text, i) - 1; continue; }
+      if (ch === '{' || ch === '[') depth++;
+      else if (ch === '}' || ch === ']') { depth--; if (depth === 0) return i + 1; }
+    }
+    throw new Error('JSON value without an end');
+  }
+  let end = pos;
+  while (end < text.length && !WHITESPACE.has(text[end]) && text[end] !== ',' && text[end] !== '}' && text[end] !== ']') end++;
+  if (end === pos) throw new Error('JSON value expected');
+  return end;
+}
+
+/** {open, close, members:[{key, keyStart, valueStart, valueEnd}]} for the object whose `{` is at `open`. */
+function scanObject(text, open) {
+  if (text[open] !== '{') throw new Error('JSON object expected');
+  const members = [];
+  let pos = skipSpace(text, open + 1);
+  if (text[pos] === '}') return { open, close: pos, members };
+  for (;;) {
+    if (text[pos] !== '"') throw new Error('JSON key expected');
+    const keyStart = pos;
+    const keyEnd = skipString(text, pos);
+    pos = skipSpace(text, keyEnd);
+    if (text[pos] !== ':') throw new Error('JSON colon expected');
+    const valueStart = skipSpace(text, pos + 1);
+    const valueEnd = skipValue(text, valueStart);
+    members.push({ key: JSON.parse(text.slice(keyStart, keyEnd)), keyStart, valueStart, valueEnd });
+    pos = skipSpace(text, valueEnd);
+    if (text[pos] === ',') { pos = skipSpace(text, pos + 1); continue; }
+    if (text[pos] === '}') return { open, close: pos, members };
+    throw new Error('JSON object without an end');
+  }
+}
+
+/** {open, close, items:[{start, end}]} for the list whose `[` is at `open`. */
+function scanList(text, open) {
+  if (text[open] !== '[') throw new Error('JSON list expected');
+  const items = [];
+  let pos = skipSpace(text, open + 1);
+  if (text[pos] === ']') return { open, close: pos, items };
+  for (;;) {
+    const end = skipValue(text, pos);
+    items.push({ start: pos, end });
+    pos = skipSpace(text, end);
+    if (text[pos] === ',') { pos = skipSpace(text, pos + 1); continue; }
+    if (text[pos] === ']') return { open, close: pos, items };
+    throw new Error('JSON list without an end');
+  }
+}
+
+function rootObject(text) {
+  return scanObject(text, skipSpace(text, text.startsWith('') ? 1 : 0));
+}
+
+/** The whitespace `pos` is indented by, or null when something else comes before it on its line. */
+function lineIndent(text, pos) {
+  let start = pos;
+  while (start > 0 && (text[start - 1] === ' ' || text[start - 1] === '\t')) start--;
+  return start === 0 || text[start - 1] === '\n' ? text.slice(start, pos) : null;
+}
+
+function styleOf(text, root) {
+  const first = root.members.length ? lineIndent(text, root.members[0].keyStart) : null;
+  return { eol: text.includes('\r\n') ? '\r\n' : '\n', unit: first || '  ' };
+}
+
+/** The index of the one member named `key`, or -1. Throws DUPLICATE_KEY when there are several. */
+function findMember(root, key) {
+  let at = -1;
+  root.members.forEach((member, index) => {
+    if (member.key !== key) return;
+    if (at !== -1) {
+      const error = new Error(`"${key}" is there more than once`);
+      error.code = 'DUPLICATE_KEY';
+      throw error;
+    }
+    at = index;
+  });
+  return at;
+}
+
+/** How many times `key` appears at the top level of the object in `text`. */
+export function countJsonKey(text, key) {
+  return rootObject(text).members.filter((member) => member.key === key).length;
+}
+
+/** Append the string `value` to the top-level list `key`, creating the list (as the last key) when there is none. */
+export function addToJsonList(text, key, value) {
+  const root = rootObject(text);
+  const { eol, unit } = styleOf(text, root);
+  const quoted = JSON.stringify(value);
+  const at = findMember(root, key);
+
+  if (at !== -1) {
+    const member = root.members[at];
+    const list = scanList(text, member.valueStart);
+    if (list.items.length) {
+      const last = list.items[list.items.length - 1];
+      const indent = lineIndent(text, last.start);
+      return text.slice(0, last.end) + (indent === null ? `, ${quoted}` : `,${eol}${indent}${quoted}`) + text.slice(last.end);
+    }
+    const outer = lineIndent(text, member.keyStart);
+    const filled = outer === null ? `[${quoted}]` : `[${eol}${outer}${unit}${quoted}${eol}${outer}]`;
+    return text.slice(0, list.open) + filled + text.slice(list.close + 1);
+  }
+
+  const name = JSON.stringify(key);
+  if (root.members.length) {
+    const last = root.members[root.members.length - 1];
+    const indent = lineIndent(text, last.keyStart);
+    const added = indent === null
+      ? `, ${name}: [${quoted}]`
+      : `,${eol}${indent}${name}: [${eol}${indent}${unit}${quoted}${eol}${indent}]`;
+    return text.slice(0, last.valueEnd) + added + text.slice(last.valueEnd);
+  }
+  return `${text.slice(0, root.open)}{${eol}${unit}${name}: [${eol}${unit}${unit}${quoted}${eol}${unit}]${eol}}${text.slice(root.close + 1)}`;
+}
+
+/**
+ * Take one occurrence of the string `value` (the last) out of the top-level
+ * list `key`. With `dropEmptyKey`, a list left empty goes too, key and all.
+ * Unchanged when the list or the string is not there.
+ */
+export function removeFromJsonList(text, key, value, { dropEmptyKey = false } = {}) {
+  const root = rootObject(text);
+  const at = findMember(root, key);
+  if (at === -1) return text;
+  const member = root.members[at];
+  if (text[member.valueStart] !== '[') return text;
+  const list = scanList(text, member.valueStart);
+  let found = -1;
+  list.items.forEach((item, index) => {
+    if (text[item.start] === '"' && JSON.parse(text.slice(item.start, item.end)) === value) found = index;
+  });
+  if (found === -1) return text;
+
+  if (list.items.length > 1) {
+    // With its comma: the one before it, or for the first item the one after.
+    if (found > 0) return text.slice(0, list.items[found - 1].end) + text.slice(list.items[found].end);
+    return text.slice(0, list.items[0].start) + text.slice(list.items[1].start);
+  }
+  if (!dropEmptyKey) return `${text.slice(0, list.open)}[]${text.slice(list.close + 1)}`;
+  if (root.members.length === 1) return `${text.slice(0, root.open)}{}${text.slice(root.close + 1)}`;
+  if (at > 0) return text.slice(0, root.members[at - 1].valueEnd) + text.slice(member.valueEnd);
+  return text.slice(0, member.keyStart) + text.slice(root.members[1].keyStart);
+}

package/neural-interface/lib/rulesets/lock.js

@@ -0,0 +1,170 @@
+// ═══════════════════════════════════════════
+// SynaBun — one rules writer per data home
+// ═══════════════════════════════════════════
+//
+// Two SynaBun servers can share one data home (two ports, a dev checkout next
+// to an installed release). Every change the rules installer makes runs inside
+// one critical section per data home, held by the operating system:
+//
+//   <dataHome>/data/rulesets-lock.db
+//
+// is an empty SQLite database, and a write transaction on it (BEGIN IMMEDIATE)
+// is the lock. Nothing is ever written to it: the transaction is rolled back to
+// leave. SQLite keeps that lock as an OS file lock, so it goes away with the
+// process that held it, however the process ended. There is no stale state to
+// clean up, and nothing here looks at pids or ages: a holder that is suspended
+// keeps the lock, and everyone else times out (BUSY).
+//
+// The binding is `node:sqlite`, the one the Neural Interface already loads for
+// the memory store (server.js, lib/db.js). The journal mode stays the default
+// (never WAL) and the locking mode stays normal (never EXCLUSIVE).
+//
+// NOTHING ELSE MAY EVER OPEN, READ, COPY OR BACK UP THAT FILE. On POSIX a
+// process loses every lock it holds on a file the moment it closes any
+// descriptor on that file, so a second look at it from inside the server (a
+// backup that streams it, a checksum, a copy) can silently drop the lock while
+// a writer is still inside. SQLite's own connections are safe from that; plain
+// file access is not. lib/backup-service.js skips the file by name, and a
+// restore never extracts it (lib/system-restore.js): both read LOCK_FILE_NAME
+// through LOCK_ONLY_DATA_FILES of backup-service.js.
+//
+// The file can still be deleted or replaced under a running server (a restore,
+// a cleanup tool, the user). A connection that stayed on the old, unlinked file
+// would lock something nobody else looks at, and two processes would each
+// believe they hold the lock. So the connection remembers which file it is on
+// (device and inode, by stat alone: never by opening the file a second time)
+// and checks the path against that before and after every BEGIN IMMEDIATE: a
+// path that leads to another file, or to none, means a new connection.
+
+import { mkdirSync, statSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { DatabaseSync } from 'node:sqlite';
+
+export const DEFAULT_LOCK_TIMEOUT_MS = 2000;
+/** The lock file's name inside <dataHome>/data. Spelled here and nowhere else. */
+export const LOCK_FILE_NAME = 'rulesets-lock.db';
+
+const SQLITE_BUSY = 5;
+
+function lockError(code, message, cause) {
+  const error = new Error(message);
+  error.code = code;
+  error.retryable = code === 'BUSY';
+  if (cause) error.cause = cause;
+  return error;
+}
+
+function isBusy(error) {
+  // The primary result code: extended codes (SQLITE_BUSY_SNAPSHOT, ...) keep it in the low byte.
+  return (Number(error?.errcode) & 0xff) === SQLITE_BUSY || /database is locked/i.test(String(error?.errstr || error?.message || ''));
+}
+
+/**
+ * The writer lock at `path`. `enter()` returns once this process holds it, or
+ * throws: BUSY when another holder kept it for `timeoutMs`, or when the lock
+ * file kept being replaced while it was taken (retryable), and
+ * LOCK_UNAVAILABLE when the lock file cannot be opened, is not an SQLite
+ * database (an empty file is one), or is one in WAL mode. A valid database
+ * that holds something is accepted: nothing is ever read from it or written
+ * to it. Either way the caller must change nothing. `leave()`
+ * gives it back. One connection, opened on the first `enter()` and kept for as
+ * long as `path` still leads to the file it is on. `afterBegin` runs right
+ * after the lock was taken, before the file is checked again (a seam for tests).
+ */
+export function createWriterLock(path, { timeoutMs = DEFAULT_LOCK_TIMEOUT_MS, afterBegin = null } = {}) {
+  const wait = Number.isFinite(timeoutMs) && timeoutMs >= 0 ? Math.floor(timeoutMs) : DEFAULT_LOCK_TIMEOUT_MS;
+  let db = null;
+  let file = null; // which file the connection is on: "<dev>:<ino>"
+  let held = false;
+
+  /** The file `path` leads to right now, as "<dev>:<ino>", or null when there is none. By stat alone. */
+  function identity() {
+    try {
+      const info = statSync(path, { bigint: true });
+      return `${info.dev}:${info.ino}`;
+    } catch (error) {
+      if (error?.code === 'ENOENT' || error?.code === 'ENOTDIR') return null;
+      throw error;
+    }
+  }
+  function close() {
+    const handle = db;
+    db = null;
+    file = null;
+    held = false;
+    try { handle?.close(); } catch { /* closed already */ }
+  }
+  function open() {
+    if (db) return db;
+    mkdirSync(dirname(path), { recursive: true });
+    const before = identity();
+    const handle = new DatabaseSync(path);
+    try {
+      handle.exec(`PRAGMA busy_timeout=${wait}`);
+      const mode = handle.prepare('PRAGMA journal_mode').get()?.journal_mode;
+      if (String(mode).toLowerCase() === 'wal') throw new Error('it is in WAL mode, which SynaBun never sets');
+      file = identity();
+      // A file that was there before the open and is another one after it was replaced in between: which of the
+      // two this connection is on cannot be told by stat, so it is not used.
+      if (file === null || (before !== null && before !== file)) throw Object.assign(new Error('the lock file was replaced while it was being opened'), { moved: true });
+    } catch (error) {
+      file = null;
+      try { handle.close(); } catch { /* nothing to close */ }
+      throw error;
+    }
+    db = handle;
+    return db;
+  }
+  function unavailable(cause) {
+    return lockError('LOCK_UNAVAILABLE', `SynaBun could not use its rules lock (${path}): ${cause?.message || cause}. Nothing was changed.`, cause);
+  }
+
+  function enter() {
+    if (held) throw lockError('LOCK_UNAVAILABLE', `The rules lock (${path}) is already held by this installer.`);
+    for (let attempt = 1; attempt <= 2; attempt++) {
+      let handle;
+      try {
+        // Deleted or replaced since this connection was opened: it is on a file nobody else locks. It holds no
+        // transaction here, so it is simply dropped and a new one is opened on the file that is there now.
+        if (db && identity() !== file) close();
+        handle = open();
+      } catch (cause) {
+        close();
+        if (cause?.moved) continue; // replaced under the open itself: once more, then BUSY
+        throw unavailable(cause);
+      }
+      try {
+        handle.exec('BEGIN IMMEDIATE');
+      } catch (cause) {
+        if (isBusy(cause)) throw lockError('BUSY', 'Another SynaBun process is working on the rules right now, so nothing was changed. Try again in a moment.', cause);
+        close(); // not a lock this connection can use: the next call opens it afresh
+        throw unavailable(cause);
+      }
+      let same = false;
+      try {
+        if (afterBegin) afterBegin(path);
+        // Replaced between the look above and the lock: what was just locked is the old file. Give it back.
+        same = identity() === file;
+      } catch (cause) {
+        try { handle.exec('ROLLBACK'); } catch { /* closed below either way */ }
+        close();
+        throw unavailable(cause);
+      }
+      if (same) {
+        held = true;
+        return;
+      }
+      try { handle.exec('ROLLBACK'); } catch { /* closed below either way */ }
+      close();
+    }
+    throw lockError('BUSY', 'The rules lock file was replaced while SynaBun was taking it, so nothing was changed. Try again in a moment.');
+  }
+  function leave() {
+    if (!held) return;
+    held = false;
+    // A rollback that fails leaves the connection in doubt: closing it gives the lock back for certain.
+    try { db.exec('ROLLBACK'); } catch { close(); }
+  }
+
+  return { path, timeoutMs: wait, enter, leave, close };
+}

package/neural-interface/lib/rulesets/managed-text.js

@@ -0,0 +1,314 @@
+// ═══════════════════════════════════════════
+// SynaBun — managed rule blocks (pure text, no fs)
+// ═══════════════════════════════════════════
+//
+// SynaBun's rules sit in a user's instruction file between two markers:
+//
+//   <!-- synabun:rules:begin v=2.0.0 host=codex sha=9f2c1a7b3e4d -->
+//   <!-- Managed by SynaBun. Edit this block and SynaBun stops updating it; … -->
+//   ...rendered rules...
+//   <!-- synabun:rules:end -->
+//
+// The sha covers everything between the begin and end lines, so a block says
+// by itself whether someone edited it. Every function here leaves each byte
+// outside the markers alone, keeps the file's line endings and BOM, and
+// refuses to guess when the markers are damaged.
+//
+// Fenced code (``` and ~~~) is somebody quoting text, never the live thing: a
+// marker or an old ruleset inside a fence is not seen by anything here.
+
+import { createHash } from 'node:crypto';
+import { normalise, sha12 } from './normalise.js';
+
+export const MANAGED_NOTE = '<!-- Managed by SynaBun. Edit this block and SynaBun stops updating it; remove it in SynaBun Settings > Setup. -->';
+export const END_MARKER = '<!-- synabun:rules:end -->';
+export const LEGACY_HEADINGS = Object.freeze(['## Memory Ruleset', '## Memory: SynaBun MCP', '## Persistent Memory']);
+
+const BEGIN_RE = /^<!-- synabun:rules:begin v=(\S+) host=([a-z0-9-]+) sha=([0-9a-f]{12}) -->$/;
+const BEGIN_HINT = 'synabun:rules:begin';
+const END_HINT = 'synabun:rules:end';
+const BOM = '';
+
+export class ManagedTextConflict extends Error {
+  constructor(code, message) {
+    super(message);
+    this.name = 'ManagedTextConflict';
+    this.code = code;
+  }
+}
+
+export function hasBom(text) {
+  return String(text ?? '').startsWith(BOM);
+}
+
+/** The file's own line ending: CRLF when most of its lines end that way, LF otherwise. */
+export function detectEol(text) {
+  const source = String(text ?? '');
+  const crlf = source.split('\r\n').length - 1;
+  const lf = source.split('\n').length - 1 - crlf;
+  return crlf > lf ? '\r\n' : '\n';
+}
+
+function toEol(text, eol) {
+  const lf = String(text).replace(/\r\n/g, '\n');
+  return eol === '\n' ? lf : lf.replace(/\n/g, eol);
+}
+
+/** [{start, end, eolEnd, text}]: `end` stops before the line break, `eolEnd` after it. */
+function scanLines(text) {
+  const lines = [];
+  let pos = hasBom(text) ? 1 : 0;
+  while (pos < text.length) {
+    const lf = text.indexOf('\n', pos);
+    if (lf === -1) {
+      lines.push({ start: pos, end: text.length, eolEnd: text.length, text: text.slice(pos) });
+      break;
+    }
+    const end = lf > pos && text[lf - 1] === '\r' ? lf - 1 : lf;
+    lines.push({ start: pos, end, eolEnd: lf + 1, text: text.slice(pos, end) });
+    pos = lf + 1;
+  }
+  return lines;
+}
+
+function endsWithEol(text) {
+  return text.endsWith('\n');
+}
+
+function stripOneEol(text) {
+  if (text.endsWith('\r\n')) return text.slice(0, -2);
+  if (text.endsWith('\n')) return text.slice(0, -1);
+  return text;
+}
+
+function startsWithEol(text) {
+  return text.startsWith('\r\n') || text.startsWith('\n');
+}
+
+function dropLeadingEol(text) {
+  if (text.startsWith('\r\n')) return text.slice(2);
+  if (text.startsWith('\n')) return text.slice(1);
+  return text;
+}
+
+/** wrap(text, {version, host}) → the stamped block, LF line endings, no trailing newline. */
+export function wrap(text, { version, host } = {}) {
+  if (!version || !host) throw new Error('wrap needs a version and a host');
+  const body = `${MANAGED_NOTE}\n${normalise(text)}`;
+  return `<!-- synabun:rules:begin v=${version} host=${host} sha=${sha12(body)} -->\n${body}\n${END_MARKER}`;
+}
+
+const FENCE_OPEN_RE = /^[ \t]*(?:>[ \t]*)*(`{3,}|~{3,})(.*)$/;
+
+/** {char, size} when the line opens a fenced code block, else null. Read generously: quoted text is left alone. */
+function fenceOpening(line) {
+  const match = line.match(FENCE_OPEN_RE);
+  if (!match) return null;
+  // A backtick fence cannot carry a backtick in its info string: that is inline code.
+  if (match[1][0] === '`' && match[2].includes('`')) return null;
+  return { char: match[1][0], size: match[1].length };
+}
+
+function fenceCloses(line, fence) {
+  const match = line.match(FENCE_OPEN_RE);
+  return !!match && match[1][0] === fence.char && match[1].length >= fence.size && match[2].trim() === '';
+}
+
+/**
+ * One pass over the file: the managed blocks, the marker conflict if any, and
+ * which lines sit inside a fenced code block. A block that is open is opaque
+ * (its own body may hold fences); a fence that is open hides every marker in
+ * it, and an unclosed fence runs to the end of the file as it does in Markdown.
+ */
+function analyse(text) {
+  const lines = scanLines(text);
+  const fenced = new Array(lines.length).fill(false);
+  const blocks = [];
+  let conflict = null;
+  let open = null;
+  let fence = null;
+  const flag = (code, message) => { if (!conflict) conflict = { code, message }; };
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i].text.replace(/\s+$/, '');
+    if (!open) {
+      if (fence) {
+        fenced[i] = true;
+        if (fenceCloses(line, fence)) fence = null;
+        continue;
+      }
+      fence = fenceOpening(line);
+      if (fence) { fenced[i] = true; continue; }
+    }
+    if (line.includes(BEGIN_HINT)) {
+      const match = line.match(BEGIN_RE);
+      if (!match) { flag('malformed-begin', 'A SynaBun begin marker is damaged'); continue; }
+      if (open) flag('begin-without-end', 'A SynaBun begin marker has no end marker');
+      open = { index: i, version: match[1], host: match[2], sha: match[3] };
+      continue;
+    }
+    if (line.includes(END_HINT)) {
+      if (line !== END_MARKER) { flag('malformed-end', 'A SynaBun end marker is damaged'); continue; }
+      if (!open) { flag('end-without-begin', 'A SynaBun end marker has no begin marker'); continue; }
+      const first = lines[open.index];
+      blocks.push({
+        start: first.start,
+        end: lines[i].end,
+        eolEnd: lines[i].eolEnd,
+        version: open.version,
+        host: open.host,
+        sha: open.sha,
+        body: lines.slice(open.index + 1, i).map((entry) => entry.text).join('\n'),
+        text: text.slice(first.start, lines[i].end),
+      });
+      open = null;
+    }
+  }
+  if (open) flag('begin-without-end', 'A SynaBun begin marker has no end marker');
+  if (blocks.length > 1) flag('duplicate-blocks', 'More than one SynaBun rules block');
+  return { lines, fenced, blocks, conflict };
+}
+
+/**
+ * findBlocks(fileText) → {blocks, conflict}.
+ * A block is {start, end, eolEnd, version, host, sha, body, text}; `text` runs
+ * from the begin marker to the end marker. `conflict` is null, or {code,
+ * message} when the markers cannot be trusted: two blocks, a begin without an
+ * end, an end without a begin, or a begin line that does not parse. Markers
+ * inside a fenced code block are quoted text and are not read at all.
+ */
+export function findBlocks(fileText) {
+  const { blocks, conflict } = analyse(String(fileText ?? ''));
+  return { blocks, conflict };
+}
+
+function singleBlock(fileText) {
+  const { blocks, conflict } = findBlocks(fileText);
+  if (conflict) throw new ManagedTextConflict(conflict.code, conflict.message);
+  return blocks[0] || null;
+}
+
+/** True while the body still hashes to its own stamp. Takes a block from findBlocks or a block's text. */
+export function isPristine(block) {
+  let parsed = block;
+  if (typeof block === 'string') {
+    const found = findBlocks(block);
+    if (found.conflict || found.blocks.length !== 1) return false;
+    parsed = found.blocks[0];
+  }
+  if (!parsed || typeof parsed.body !== 'string' || !parsed.sha) return false;
+  return sha12(parsed.body) === parsed.sha;
+}
+
+/**
+ * Replace the existing block in place, else append it with one blank line
+ * before it. Throws ManagedTextConflict when the markers are damaged.
+ */
+export function upsertBlock(fileText, block) {
+  const text = String(fileText ?? '');
+  const existing = singleBlock(text);
+  const eol = detectEol(text);
+  const inserted = toEol(block, eol);
+  if (existing) return text.slice(0, existing.start) + inserted + text.slice(existing.end);
+  const content = hasBom(text) ? text.slice(1) : text;
+  if (content === '') return text + inserted + eol;
+  // A file that ends without a line break keeps ending without one, so the
+  // removal below can give back exactly the bytes it started from.
+  if (endsWithEol(text)) return text + eol + inserted + eol;
+  return text + eol + eol + inserted;
+}
+
+/** Remove the block and the blank line the insert added. Unchanged when there is no block. */
+export function removeBlock(fileText) {
+  const text = String(fileText ?? '');
+  const existing = singleBlock(text);
+  if (!existing) return text;
+  let before = text.slice(0, existing.start);
+  const after = text.slice(existing.eolEnd);
+  const blockHadEol = existing.eolEnd > existing.end;
+  const floor = hasBom(before) ? 1 : 0;
+  const blankBefore = () => before.length > floor && endsWithEol(before) && (stripOneEol(before).length === floor || endsWithEol(stripOneEol(before)));
+  if (blockHadEol || after.length > 0) {
+    if (blankBefore()) before = stripOneEol(before);
+  } else if (blankBefore()) {
+    before = stripOneEol(stripOneEol(before));
+  }
+  return before + after;
+}
+
+/** Put `block` over the characters [start, end) in the file's own line endings. */
+export function replaceRange(fileText, start, end, block) {
+  const text = String(fileText ?? '');
+  return text.slice(0, start) + toEol(block, detectEol(text)) + text.slice(end);
+}
+
+/** Cut the lines [start, end) and one of the blank lines that surrounded them. */
+export function removeRange(fileText, start, end) {
+  const text = String(fileText ?? '');
+  let before = text.slice(0, start);
+  let after = dropLeadingEol(text.slice(end));
+  const floor = hasBom(before) ? 1 : 0;
+  const blankBefore = before.length === floor || (endsWithEol(before) && (stripOneEol(before).length === floor || endsWithEol(stripOneEol(before))));
+  if (blankBefore && startsWithEol(after)) after = dropLeadingEol(after);
+  else if (after === '' && before.length > floor && blankBefore) before = stripOneEol(before);
+  return before + after;
+}
+
+function isLegacyHeading(line) {
+  return LEGACY_HEADINGS.find((heading) => line === heading || line.startsWith(`${heading} `) || line.startsWith(`${heading}:`)) || null;
+}
+
+/**
+ * findLegacy(fileText, legacyHashes) → [{start, end, kind, sha?, host?, hosts?, heading?}]
+ * exact   = a run of lines whose normalised hash and line count match a ruleset
+ *           SynaBun served before the managed blocks existed; `hosts` names
+ *           every tool that text was served for (`host` is the first of them)
+ * heading = one of the old ruleset headings with no exact match around it
+ * `start` and `end` are character offsets; `end` stops before the last line's
+ * line break. Text inside a managed block or a fenced code block is never
+ * reported: the first is SynaBun's own, the second is someone quoting it.
+ */
+export function findLegacy(fileText, legacyHashes) {
+  const text = String(fileText ?? '');
+  const entries = Array.isArray(legacyHashes) ? legacyHashes : (legacyHashes?.entries || []);
+  const { lines, fenced, blocks: managed } = analyse(text);
+  const trimmed = lines.map((line) => line.text.replace(/\s+$/, ''));
+  const inManaged = (line) => managed.some((block) => line.start >= block.start && line.start < block.eolEnd);
+
+  const byFirstLine = new Map();
+  const hostsOf = new Map();
+  for (const entry of entries) {
+    if (!entry?.sha || !entry.firstLine || !(entry.lines > 0)) continue;
+    if (!byFirstLine.has(entry.firstLine)) byFirstLine.set(entry.firstLine, []);
+    byFirstLine.get(entry.firstLine).push(entry);
+    const key = `${entry.sha}:${entry.lines}`;
+    if (!hostsOf.has(key)) hostsOf.set(key, []);
+    if (entry.host && !hostsOf.get(key).includes(entry.host)) hostsOf.get(key).push(entry.host);
+  }
+  for (const list of byFirstLine.values()) list.sort((a, b) => b.lines - a.lines);
+
+  const spans = [];
+  for (let i = 0; i < lines.length; i++) {
+    if (fenced[i] || inManaged(lines[i])) continue;
+    let matched = null;
+    for (const entry of byFirstLine.get(trimmed[i]) || []) {
+      if (i + entry.lines > lines.length) continue;
+      // A copy that runs into a code fence or a managed block is not a plain pasted copy.
+      if (fenced[i + entry.lines - 1] || inManaged(lines[i + entry.lines - 1])) continue;
+      const candidate = trimmed.slice(i, i + entry.lines).join('\n');
+      if (createHash('sha256').update(candidate, 'utf8').digest('hex').slice(0, 12) !== entry.sha) continue;
+      matched = entry;
+      break;
+    }
+    if (matched) {
+      const last = lines[i + matched.lines - 1];
+      const hosts = hostsOf.get(`${matched.sha}:${matched.lines}`) || [];
+      spans.push({ start: lines[i].start, end: last.end, kind: 'exact', sha: matched.sha, host: matched.host || null, hosts });
+      i += matched.lines - 1;
+      continue;
+    }
+    const heading = isLegacyHeading(trimmed[i]);
+    if (heading) spans.push({ start: lines[i].start, end: lines[i].end, kind: 'heading', heading });
+  }
+  return spans;
+}