mirror-mind 0.0.1 → 0.32.1

package/ts/src/providers/transport.ts

@@ -0,0 +1,410 @@
+/**
+ * The one transport-selection precedence for provider-backed command families
+ * (CV22.DS8.US1, generalized by CV22.DS8.US3 / CR077).
+ *
+ * Sixteen leaves reach a provider. Each one needs the same decision: a
+ * deterministic replay fixture for CI and the smokes, or the live provider.
+ * Deriving that per leaf is how the US11 defect happened -- `LLM_ROLES` had a
+ * type and a hand-maintained guard that drifted apart, and the unit tests
+ * still passed. One list, no drift.
+ *
+ * Until CV22.DS10.TS5 there was a third answer, an operational revert to
+ * Python (`<revertVar>=0`), and it outranked everything else. It left with the
+ * engine it reverted to (decision D3). A leftover variable is inert, and
+ * `runtime diagnose` says so.
+ *
+ * CR077: a family may need MORE THAN ONE replay fixture (the close tail needs
+ * an LLM fixture and an embedding fixture; `mirror load --query` and the
+ * cultivation family are the same shape). The spec used to name one variable,
+ * so the "both or neither" rule lived privately in `loggerRuntime` -- and the
+ * router could report `replay` for an invocation the runtime then refused.
+ * The spec now carries the whole rule and `incomplete_replay` is a mode, so
+ * routing and the runtime agree by construction.
+ */
+
+export type ProviderTransportMode = "replay" | "incomplete_replay" | "live";
+
+/**
+ * Read-only env view. Indexed access is deliberate: families name their
+ * variables as data, so a typed per-variable interface would have to be
+ * extended for every family US3 flips.
+ */
+export type ProviderTransportEnv = Readonly<Record<string, string | undefined>>;
+
+/** The provider kinds a replay fixture can answer for. */
+export type ProviderKind = "llm" | "embedding" | "credits";
+
+/**
+ * Which fixture variable answers for which provider kind.
+ *
+ * Keyed rather than a bare list because the family provider factory has to
+ * know what each fixture IS, not only that it is required. The "all or none"
+ * rule derives from the declared set either way.
+ */
+export type ProviderReplaySpec = Partial<Record<ProviderKind, string>>;
+
+export interface ProviderTransportSpec {
+  /** Replay fixture variables this family needs. All of them, or none. */
+  replay?: ProviderReplaySpec;
+  /** Reason recorded when the live provider is selected. */
+  liveReason?: string;
+}
+
+export interface ProviderTransportDecision {
+  mode: ProviderTransportMode;
+  /** Route-decision reason, surfaced in the front-door log. Never a payload. */
+  reason: string;
+  /** Set only in `replay` mode: the fixture path for each declared kind. */
+  replayPaths?: Readonly<ProviderReplaySpec>;
+  /** Set only in `incomplete_replay`: the fixtures that must also be set. */
+  missingReplayVars?: readonly string[];
+  /** Set only in `incomplete_replay`: the fixtures that already are. */
+  presentReplayVars?: readonly string[];
+}
+
+/**
+ * Resolve which transport answers a provider-backed command.
+ *
+ * Precedence, highest first:
+ *
+ * 1. **replay** -- every declared fixture variable is set. Deterministic, no
+ *    network, no spend. This is what CI and the smokes use. It deliberately
+ *    does not require `MIRROR_TS_EXTERNAL_ROUTES`: that gate was DS5's safety
+ *    catch while replay was the PRODUCTION route, and after the live cutover
+ *    replay is a test transport.
+ * 2. **incomplete_replay** -- some declared fixtures are set and some are not.
+ *    Never live: someone who set one variable meant to replay, and running
+ *    half a fixture would spend real money. The only honest answer names the
+ *    missing half.
+ * 3. **live** -- the DS8 default. An unconfigured install reaches the provider
+ *    through TypeScript.
+ *
+ * An exported-but-empty fixture variable is treated as absent, because that
+ * shell accident should not become a file-not-found later.
+ */
+export function resolveProviderTransport(
+  env: ProviderTransportEnv,
+  spec: ProviderTransportSpec,
+): ProviderTransportDecision {
+  const declared = declaredReplayVars(spec);
+  const present = declared.filter(([, variable]) => Boolean(env[variable]));
+
+  if (declared.length > 0 && present.length === declared.length) {
+    const replayPaths: ProviderReplaySpec = {};
+    for (const [kind, variable] of declared) replayPaths[kind] = env[variable];
+    return {
+      mode: "replay",
+      reason: `${declared.map(([, variable]) => variable).join(" + ")} replay transport`,
+      replayPaths,
+    };
+  }
+
+  if (present.length > 0) {
+    const missingReplayVars = declared
+      .filter(([, variable]) => !env[variable])
+      .map(([, variable]) => variable);
+    const presentReplayVars = present.map(([, variable]) => variable);
+    return {
+      mode: "incomplete_replay",
+      reason:
+        `incomplete replay fixture: ${presentReplayVars.join(", ")} set, ` +
+        `${missingReplayVars.join(", ")} missing`,
+      missingReplayVars,
+      presentReplayVars,
+    };
+  }
+
+  return { mode: "live", reason: spec.liveReason ?? "live provider" };
+}
+
+/** The declared fixture variables, in a stable kind order for stable reasons. */
+function declaredReplayVars(spec: ProviderTransportSpec): [ProviderKind, string][] {
+  const order: ProviderKind[] = ["llm", "embedding", "credits"];
+  return order
+    .filter((kind) => Boolean(spec.replay?.[kind]))
+    .map((kind) => [kind, spec.replay?.[kind] as string]);
+}
+
+/**
+ * A command whose provider work belongs to families it does not own
+ * (CV22.DS7.US8 item 18b).
+ *
+ * `build load` is the case that forced this. It owns no provider seam: its two
+ * embeddings ARE the search family, and the previous conversation's close tail
+ * IS the conversation-tail family -- both already live in production since DS8.
+ * Its fixtures are the owner's; the composed families only say whether replay
+ * was intended somewhere, so a half-configured harness refuses instead of
+ * reaching the live provider through fixtures nobody set.
+ */
+export interface ComposedProviderTransportSpec {
+  /** Named in every composed reason, so the log says which command composed. */
+  readonly label: string;
+  /** The family whose fixtures the command's providers are actually built from. */
+  readonly owner: ProviderTransportSpec;
+  /**
+   * Families whose work this command performs. Consulted for replay intent --
+   * never for fixtures, because a composing command runs every seam off the
+   * owner's.
+   */
+  readonly composes: readonly ProviderTransportSpec[];
+}
+
+/**
+ * Resolve one transport decision for a command that composes several families.
+ *
+ * Precedence, extending `resolveProviderTransport` rather than replacing it:
+ *
+ * 1. **any incomplete fixture refuses** -- including a composed family's. Its
+ *    own pair rule cannot be honoured by a runtime that never sees it.
+ * 2. **replay intent anywhere requires the OWNER's complete fixture set.** A
+ *    harness that configured the search family for replay and then ran `build
+ *    load` would reach the live provider through fixtures nobody set -- a
+ *    silent charge -- so the only honest answer names the fixtures missing
+ *    here.
+ * 3. otherwise the owner's decision stands, unchanged.
+ *
+ * (A fourth rule, "any revert wins", sat on top until CV22.DS10.TS5 deleted
+ * the reverts with the engine they reverted to.)
+ *
+ * With an empty `composes` the result is byte-identical to the single-family
+ * decision: the composition is data, not a second precedence to drift from.
+ */
+export function resolveComposedProviderTransport(
+  env: ProviderTransportEnv,
+  spec: ComposedProviderTransportSpec,
+): ProviderTransportDecision {
+  const owner = resolveProviderTransport(env, spec.owner);
+  const composed = spec.composes.map((family) => resolveProviderTransport(env, family));
+
+  if (owner.mode === "incomplete_replay") return owner;
+  const incomplete = composed.find((decision) => decision.mode === "incomplete_replay");
+  if (incomplete) return composedReason(incomplete, spec.label);
+
+  const replaying = spec.composes.filter((_, index) => composed[index]?.mode === "replay");
+  if (owner.mode === "live" && replaying.length > 0) {
+    const missingReplayVars = declaredReplayVars(spec.owner).map(([, variable]) => variable);
+    // A composition whose owner declares no fixture has nothing to name, and
+    // nothing of its own to replay either: the owner's decision stands.
+    if (missingReplayVars.length > 0) {
+      const presentReplayVars = replaying.flatMap((family) =>
+        declaredReplayVars(family)
+          .map(([, variable]) => variable)
+          .filter((variable) => Boolean(env[variable])),
+      );
+      return composedReason(
+        {
+          mode: "incomplete_replay",
+          reason:
+            `incomplete replay fixture: ${presentReplayVars.join(", ")} set, ` +
+            `${missingReplayVars.join(", ")} missing`,
+          missingReplayVars,
+          presentReplayVars,
+        },
+        spec.label,
+      );
+    }
+  }
+
+  return owner;
+}
+
+/** Same decision, with the composing command named for the front-door log. */
+function composedReason(
+  decision: ProviderTransportDecision,
+  label: string,
+): ProviderTransportDecision {
+  return { ...decision, reason: `${decision.reason} (composed by ${label})` };
+}
+
+/**
+ * Exactly one half of a multi-fixture family's replay configuration is set.
+ *
+ * Someone who set one variable meant to replay, so the only honest answer is
+ * to stop and name the missing half. (Until CV22.DS10.TS5 a PLAIN family sent
+ * this case to the Python fallback, which has no replay transport and would
+ * have called the live provider; only compositions refused. With the fallback
+ * gone every family refuses.)
+ *
+ * Lived in `loggerRuntime` until CR077; it is the whole family rule's error,
+ * so it belongs beside the rule.
+ */
+export class ReplayFixtureIncompleteError extends Error {
+  constructor(decision: ProviderTransportDecision) {
+    const missing = (decision.missingReplayVars ?? []).join(", ");
+    const present = (decision.presentReplayVars ?? []).join(", ");
+    super(
+      `${present} is set but ${missing} is not. This command needs EVERY replay ` +
+        "fixture its family declares; running with part of one would reach the live " +
+        `provider and spend real money. Set ${missing}, or unset ${present} to run live ` +
+        "deliberately.",
+    );
+    this.name = "ReplayFixtureIncompleteError";
+  }
+}
+
+// --- Family transport specs ------------------------------------------------
+//
+// Each provider-backed family names its variables here, in one place, rather
+// than in the route that happens to consume them: `routing.ts` decides the
+// route and the provider factory builds the providers, and both must read the
+// same spec or they can disagree about which transport is live.
+
+/**
+ * Fresh semantic search (CV22.DS8.US1).
+ *
+ * `MIRROR_TS_EXTERNAL_ROUTES` is deliberately absent: it was DS5's safety gate
+ * while replay was the PRODUCTION route for this leaf, and after the live
+ * cutover replay is a test transport.
+ */
+export const SEARCH_TRANSPORT: ProviderTransportSpec = {
+  replay: { embedding: "MIRROR_TS_SEARCH_EMBEDDING_REPLAY" },
+  liveReason: "DS8.US1 fresh semantic search live",
+};
+
+/**
+ * The conversation close tail (CV22.DS8.US2): title, tags, summary, memory and
+ * task extraction, and their embeddings.
+ *
+ * Two fixtures back this family, not one -- the pair rule that motivated
+ * CR077. It now lives in the spec, so the router cannot report `replay` for an
+ * invocation the runtime refuses.
+ */
+export const CONVERSATION_TAIL_TRANSPORT: ProviderTransportSpec = {
+  replay: {
+    llm: "MIRROR_TS_CONVERSATION_LLM_REPLAY",
+    embedding: "MIRROR_TS_CONVERSATION_EMBEDDING_REPLAY",
+  },
+  liveReason: "DS8.US2 conversation close tail live",
+};
+
+/**
+ * `soul harvest save` (CV22.DS8.US3) -- the one leaf of the Soul command that
+ * crosses the provider seam, and only through the embedding: the save supplies
+ * title, layer, and tags, so the journal classifier is unreachable.
+ */
+export const SOUL_HARVEST_TRANSPORT: ProviderTransportSpec = {
+  replay: { embedding: "MIRROR_TS_SOUL_EMBEDDING_REPLAY" },
+  liveReason: "DS8.US3 soul harvest save live",
+};
+
+/**
+ * `consult credits` and `consult ask` (CV22.DS8.US3).
+ *
+ * TWO specs for one family, because the fixtures are genuinely per leaf:
+ * `credits` needs only the credits fixture, while `ask` needs the chat fixture
+ * AND the credits one (it fetches the call's real cost, then prints the
+ * balance). With the credits fixture alone, `credits` replays and `ask`
+ * refuses -- it must not go live for the half nobody configured.
+ */
+export const CONSULT_CREDITS_TRANSPORT: ProviderTransportSpec = {
+  replay: { credits: "MIRROR_TS_CREDITS_REPLAY" },
+  liveReason: "DS8.US3 consult credits live",
+};
+
+export const CONSULT_ASK_TRANSPORT: ProviderTransportSpec = {
+  replay: { llm: "MIRROR_TS_CONSULT_LLM_REPLAY", credits: "MIRROR_TS_CREDITS_REPLAY" },
+  liveReason: "DS8.US3 consult ask live",
+};
+
+/**
+ * `mirror load --query` (CV22.DS8.US3): the reception classifier plus the
+ * query's own embedding for attachment and journey search.
+ *
+ * `MEMORY_RECEPTION=0` skips the classifier; the embedding half stays, which is
+ * why both fixtures are declared.
+ */
+export const MIRROR_QUERY_TRANSPORT: ProviderTransportSpec = {
+  replay: {
+    llm: "MIRROR_TS_MIRROR_LLM_REPLAY",
+    embedding: "MIRROR_TS_MIRROR_EMBEDDING_REPLAY",
+  },
+  liveReason: "DS8.US3 mirror load --query live",
+};
+
+/**
+ * `consolidate scan` and `shadow scan` -- the two cultivation leaves that send
+ * a PROMPT. Everything around the call landed in CV22.DS8.US3; the flip
+ * itself waited for CV22.DS8.TS2, because until then TypeScript sent a fenced
+ * Markdown dump of the memories with no task statement and no JSON output
+ * contract -- invisible under replay, which answers by role and never reads
+ * the prompt. The real templates now travel with the call and their assembled
+ * bytes are digest-pinned against the Python oracle (`cultivation/propose.ts`).
+ */
+export const CULTIVATION_SCAN_TRANSPORT: ProviderTransportSpec = {
+  replay: { llm: "MIRROR_TS_CULTIVATION_LLM_REPLAY" },
+  liveReason: "DS8.TS2 cultivation scan live",
+};
+
+/**
+ * `consolidate apply` (CV22.DS8.US3).
+ *
+ * A SEPARATE spec, and not blocked by TS2: apply sends no prompt at all. A
+ * `merge` embeds the merged content and an `identity_update` makes no provider
+ * call whatsoever, so the only fixture it can need is the embedding one. The
+ * plan and the burn-down ledger both said "the three cultivation leaves wait
+ * for TS2"; measured, it is two.
+ */
+export const CULTIVATION_APPLY_TRANSPORT: ProviderTransportSpec = {
+  replay: { embedding: "MIRROR_TS_CULTIVATION_EMBEDDING_REPLAY" },
+  liveReason: "DS8.US3 consolidate apply live",
+};
+
+/** `journal` (CV22.DS8.US3): classify the entry, then embed the memory. */
+export const JOURNAL_TRANSPORT: ProviderTransportSpec = {
+  replay: {
+    llm: "MIRROR_TS_JOURNAL_LLM_REPLAY",
+    embedding: "MIRROR_TS_JOURNAL_EMBEDDING_REPLAY",
+  },
+  liveReason: "DS8.US3 journal live",
+};
+
+/** `week plan` (CV22.DS8.US3). `week save` and `week view` make no provider call. */
+export const WEEK_PLAN_TRANSPORT: ProviderTransportSpec = {
+  replay: { llm: "MIRROR_TS_WEEK_LLM_REPLAY" },
+  liveReason: "DS8.US3 week plan live",
+};
+
+/**
+ * `descriptor generate` (CV22.DS8.US3). One call per persona AND per journey
+ * when no `--layer/--key` narrows it, so the front-door log records `calls=N`.
+ */
+export const DESCRIPTOR_TRANSPORT: ProviderTransportSpec = {
+  replay: { llm: "MIRROR_TS_DESCRIPTOR_LLM_REPLAY" },
+  liveReason: "DS8.US3 descriptor generate live",
+};
+
+/**
+ * `build load` (CV22.DS7.US8) -- the one leaf of the 27 that crosses the
+ * provider seam, and the only family here that owns no seam of its own.
+ *
+ * Two fixtures, because `load` reaches the model twice over: the embedding for
+ * its two searches (scoped and global, the same query), and the LLM plus
+ * embedding of the previous conversation's close tail, which `switchConversation`
+ * runs on the way in. Every seam inside the command is built from THESE
+ * variables, which is why an incomplete set here refuses even when another
+ * family's fixtures are present.
+ */
+export const BUILD_LOAD_TRANSPORT: ProviderTransportSpec = {
+  replay: {
+    llm: "MIRROR_TS_BUILD_LLM_REPLAY",
+    embedding: "MIRROR_TS_BUILD_EMBEDDING_REPLAY",
+  },
+  liveReason: "DS7.US8 build load live",
+};
+
+/**
+ * The three specs `build load` resolves BEFORE it prints a byte (item 18b).
+ *
+ * Four surfaces -- transition card, entry surface, identity context, and the
+ * banner on stderr -- print ahead of the first provider call, so a refusal
+ * decided later would come after all of them in the Navigator's terminal.
+ *
+ * The composed pair is what makes a half-configured harness refuse: replay
+ * intent on the search or conversation-tail family requires this command's
+ * own fixtures, rather than reaching the live provider through ones nobody set.
+ */
+export const BUILD_LOAD_COMPOSITION: ComposedProviderTransportSpec = {
+  label: "build load",
+  owner: BUILD_LOAD_TRANSPORT,
+  composes: [SEARCH_TRANSPORT, CONVERSATION_TAIL_TRANSPORT],
+};

package/ts/src/repair/encodingRepair.ts

@@ -0,0 +1,253 @@
+// Reversible UTF-8/Windows mojibake repair for Mirror user text.
+//
+// Port of `src/memory/cli/repair_encoding.py` (CV22.DS7.TS1). Older
+// Windows/local-runtime combinations stored UTF-8 text after decoding it as a
+// legacy code page, producing "é" where "é" was meant. The repair only touches
+// two-code-point sequences that round-trip cleanly: re-encode through Latin-1
+// (first pass) or Windows-1252 (second pass), then decode strictly as UTF-8;
+// anything that fails either step is left exactly as it was. Legitimate text
+// such as "Âncora" therefore survives, which is the whole safety argument.
+//
+// Parity notes, each pinned by the golden:
+//   - `.` matches one CODE POINT (`u` + `s` flags), never a UTF-16 unit.
+//   - Python's `bytes.decode("utf-8")` is strict; so is a fatal TextDecoder.
+//   - Windows-1252 has five undefined bytes and a repertoire outside Latin-1;
+//     a code point it cannot encode makes the pass leave the chunk unchanged,
+//     exactly like Python's UnicodeEncodeError branch.
+//   - The preview collapses whitespace with Python's `str.split()` set, which
+//     is not JavaScript's `\s`, and caps by code point, not `.length`.
+
+import { type Database, type WritableDatabase, withTransaction } from "#db/database.ts";
+import { pythonWhitespaceRegex } from "#util/pythonText.ts";
+
+/** One repairable cell: where it is, what it holds, what it becomes. */
+export interface RepairHit {
+  table: string;
+  column: string;
+  row_id: number;
+  before: string;
+  after: string;
+}
+
+// UTF-8 bytes decoded as Latin-1: "é", "ç", "ã", "º", ...
+const LATIN1_UTF8_PAIR = /[\u00c2-\u00c3][\u0080-\u00bf]/gu;
+// UTF-8 bytes decoded as Windows-1252: "Ó", "É", ... (any following code point).
+const CP1252_UTF8_PAIR = /[\u00c2-\u00c3]./gsu;
+
+/**
+ * User-text columns that can be scanned without touching arbitrary extension
+ * tables. Missing tables/columns are ignored for older database versions.
+ * Order matters: it is the oracle's scan order, hence the hit order.
+ */
+const TEXT_TARGETS: readonly (readonly [string, readonly string[]])[] = [
+  ["identity", ["content"]],
+  ["attachments", ["content"]],
+  ["memories", ["content", "summary", "source", "journey", "layer"]],
+  ["messages", ["content"]],
+  ["conversations", ["title", "summary", "journey", "persona"]],
+  ["memory_access_log", ["access_context"]],
+  ["tasks", ["title", "description", "journey", "status", "notes"]],
+];
+
+/**
+ * Windows-1252 code points for bytes 0x80–0x9F. `undefined` marks the five
+ * bytes (0x81, 0x8D, 0x8F, 0x90, 0x9D) the code page leaves unassigned;
+ * every other byte maps to itself (0x00–0x7F, 0xA0–0xFF), as in Latin-1.
+ */
+const CP1252_HIGH_BLOCK: readonly (number | undefined)[] = [
+  0x20ac,
+  undefined,
+  0x201a,
+  0x0192,
+  0x201e,
+  0x2026,
+  0x2020,
+  0x2021,
+  0x02c6,
+  0x2030,
+  0x0160,
+  0x2039,
+  0x0152,
+  undefined,
+  0x017d,
+  undefined,
+  undefined,
+  0x2018,
+  0x2019,
+  0x201c,
+  0x201d,
+  0x2022,
+  0x2013,
+  0x2014,
+  0x02dc,
+  0x2122,
+  0x0161,
+  0x203a,
+  0x0153,
+  undefined,
+  0x017e,
+  0x0178,
+];
+
+const CP1252_BYTE_FOR_CODE_POINT: ReadonlyMap<number, number> = new Map(
+  CP1252_HIGH_BLOCK.flatMap((codePoint, offset) =>
+    codePoint === undefined ? [] : [[codePoint, 0x80 + offset] as const],
+  ),
+);
+
+const STRICT_UTF8 = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
+
+/** Encode one code point as Latin-1, or `null` when it does not fit. */
+function latin1Byte(codePoint: number): number | null {
+  return codePoint <= 0xff ? codePoint : null;
+}
+
+/** Encode one code point as Windows-1252, or `null` when the code page lacks it. */
+function cp1252Byte(codePoint: number): number | null {
+  if (codePoint < 0x80 || (codePoint >= 0xa0 && codePoint <= 0xff)) return codePoint;
+  return CP1252_BYTE_FOR_CODE_POINT.get(codePoint) ?? null;
+}
+
+/**
+ * Re-encode `chunk` byte-per-code-point through `encodeByte` and decode the
+ * result strictly as UTF-8. Returns the chunk unchanged when either step
+ * fails — the same "leave it alone" contract as Python's `_decode_pair`.
+ */
+function decodePair(chunk: string, encodeByte: (codePoint: number) => number | null): string {
+  const bytes: number[] = [];
+  for (const char of chunk) {
+    const byte = encodeByte(char.codePointAt(0) as number);
+    if (byte === null) return chunk;
+    bytes.push(byte);
+  }
+  try {
+    return STRICT_UTF8.decode(Uint8Array.from(bytes));
+  } catch {
+    return chunk;
+  }
+}
+
+/**
+ * Return `text` with reversible mojibake repaired. Only two-code-point
+ * sequences that decode as UTF-8 after re-encoding through Latin-1 or
+ * Windows-1252 change; everything else — including legitimate Portuguese like
+ * "Âncora" — stays as it is.
+ */
+export function repairText(text: string): string {
+  const latin1Pass = text.replace(LATIN1_UTF8_PAIR, (chunk) => decodePair(chunk, latin1Byte));
+  return latin1Pass.replace(CP1252_UTF8_PAIR, (chunk) => decodePair(chunk, cp1252Byte));
+}
+
+export function hasRepairableMojibake(text: string): boolean {
+  return repairText(text) !== text;
+}
+
+/**
+ * Python's `str.isspace()` set — what `str.split()` with no separator splits
+ * on. Differs from JavaScript `\s`: it includes U+001C–U+001F and excludes
+ * U+FEFF. Shared with the extension migration checksum, which depends on the
+ * same distinction (CV22.DS7.TS3).
+ */
+const PYTHON_WHITESPACE = pythonWhitespaceRegex();
+
+/**
+ * Port of `_preview`: collapse whitespace runs to single spaces, trim, and cap
+ * at `limit` code points with a trailing ellipsis.
+ */
+export function previewText(text: string, limit = 80): string {
+  const compact = text
+    .split(PYTHON_WHITESPACE)
+    .filter((part) => part !== "")
+    .join(" ");
+  const codePoints = Array.from(compact);
+  if (codePoints.length > limit) {
+    return `${codePoints.slice(0, limit - 1).join("")}…`;
+  }
+  return compact;
+}
+
+function existingColumns(db: Database, table: string): Set<string> {
+  try {
+    return new Set(
+      db
+        .prepare(`PRAGMA table_info("${table}")`)
+        .all()
+        .map((row) => String(row.name)),
+    );
+  } catch {
+    return new Set();
+  }
+}
+
+function scanTable(db: Database, table: string, columns: readonly string[]): RepairHit[] {
+  const existing = existingColumns(db, table);
+  const selected = columns.filter((column) => existing.has(column));
+  if (selected.length === 0) return [];
+
+  const quoted = selected.map((column) => `"${column}"`).join(", ");
+  let rows: Record<string, unknown>[];
+  try {
+    // Same statement as the oracle, deliberately without ORDER BY: same
+    // engine, same plan, same rowid order. The golden pins it.
+    rows = db.prepare(`SELECT _rowid_ AS __rowid__, ${quoted} FROM "${table}"`).all();
+  } catch {
+    return [];
+  }
+
+  const hits: RepairHit[] = [];
+  for (const row of rows) {
+    const rowId = Number(row.__rowid__);
+    for (const column of selected) {
+      const value = row[column];
+      if (typeof value !== "string") continue;
+      const fixed = repairText(value);
+      if (fixed !== value) {
+        hits.push({ table, column, row_id: rowId, before: value, after: fixed });
+      }
+    }
+  }
+  return hits;
+}
+
+/** Scan every target table/column and return the ordered list of repairable cells. */
+export function scanDatabase(db: Database): RepairHit[] {
+  return TEXT_TARGETS.flatMap(([table, columns]) => scanTable(db, table, columns));
+}
+
+/** Apply every hit by `_rowid_` in one transaction; returns the count applied. */
+export function applyRepairs(db: WritableDatabase, hits: readonly RepairHit[]): number {
+  return withTransaction(db, () => {
+    for (const hit of hits) {
+      db.prepare(`UPDATE "${hit.table}" SET "${hit.column}" = ? WHERE _rowid_ = ?`).run(
+        hit.after,
+        hit.row_id,
+      );
+    }
+    return hits.length;
+  });
+}
+
+export interface ScanReportOptions {
+  dbPath: string;
+  hits: readonly RepairHit[];
+  /** Maximum preview rows; negative values behave as zero, like `max(limit, 0)`. */
+  limit: number;
+}
+
+/** Render the scan section of the report exactly as the oracle prints it. */
+export function renderScanReport({ dbPath, hits, limit }: ScanReportOptions): string {
+  const shown = Math.max(limit, 0);
+  const lines = [`Database: ${dbPath}`, `Repairable mojibake hits: ${hits.length}`];
+  for (const hit of hits.slice(0, shown)) {
+    lines.push(
+      `- ${hit.table}.${hit.column} row=${hit.row_id}: ${previewText(hit.before)} -> ${previewText(hit.after)}`,
+    );
+  }
+  if (hits.length > shown) lines.push(`… ${hits.length - shown} more`);
+  return `${lines.join("\n")}\n`;
+}
+
+/** Render the trailing line of a successful `--apply`. */
+export function renderApplyReport(applied: number): string {
+  return `Applied repairs: ${applied}\n`;
+}