agent-sanitizer 2.25.0 → 2.26.1

package/types/index.d.mts

@@ -10,7 +10,8 @@
  * its own removal.
  *
  * `found` names the categories neutralized; `warnings` carries the
- * operator-facing notices. `cleaned` is always a string, and a change only
+ * operator-facing notices and `notes` the quiet tier (see `./severity.mjs`).
+ * `cleaned` is always a string, and a change only
  * ever carries a warning (no silent suppression). `options` is optional and
  * tolerates an explicit `null`/`undefined` (treated the same as omitted) —
  * only a genuinely malformed `text` (not a string) throws, deliberately: a
@@ -20,7 +21,7 @@
  *
  * The layer bodies live in `./output.mjs`; this is a facade over them, not a
  * second implementation (see the module doc). It narrows `sanitizeText`'s result
- * to the three fields this entry has always promised — `modified`/`sgrNote`
+ * to the four fields this entry promises — `modified`/`sgrNote`
  * describe the tool-output pipeline's banner, and `reveal` is produced only by
  * options this facade does not expose. `html` selects Layers 2 AND 3 together
  * here, which is the surface this entry has always had; `sanitizeText` takes
@@ -28,7 +29,7 @@
  * detection without Layer 2's splice.
  * @param {string} text
  * @param {{ html?: boolean } | null} [options]
- * @returns {Promise<{ cleaned: string, found: string[], warnings: string[] }>}
+ * @returns {Promise<{ cleaned: string, found: string[], warnings: string[], notes: string[] }>}
  */
 export function sanitize(text: string, options?: {
     html?: boolean;
@@ -36,6 +37,7 @@ export function sanitize(text: string, options?: {
     cleaned: string;
     found: string[];
     warnings: string[];
+    notes: string[];
 }>;
 export { applyLayer1, isBenignAnsi, isBenignAnsiKinds, stripAnsiFully, LONE_SURROGATE_RE } from "./layer1.mjs";
 export { stripInvisible, stripInvisibleWithReport, isSgrOnly, STRIP, SGR_RE, CHECKS, CATEGORY, CATEGORY_LABELS, LINGUISTIC_SCRIPTS, VS, BLANK_NON_CF, LONG_RUN_RE, LONG_RUN_THRESHOLD, SCATTERED_THRESHOLD } from "./invisible.mjs";

package/types/instructions.d.mts

@@ -40,23 +40,32 @@ export function scanText(content: string): Array<{
  * cannot be resolved (a dangling symlink or unreadable entry inside the
  * tree), is SKIPPED, so one bad symlink never aborts scanning the rest of the
  * project.
+ *
+ * `exclude` prunes the WALK, which is where a wide glob's cost actually is —
+ * a pattern that merely fails to match a bulk directory still pays to read it.
+ * It is composed with, never replaces, the unconditional `node_modules` prune:
+ * a caller narrowing the scan must not be able to widen it into a dependency
+ * tree. Pass {@link excludeFromContextScan} to take Claude Code's own scope.
  * @param {string[]} globs
- * @param {{ cwd?: string }} [options]
+ * @param {{ cwd?: string, exclude?: (entry: string) => boolean }} [options]
  * @returns {string[]}
  */
-export function findInstructionFiles(globs: string[], { cwd }?: {
+export function findInstructionFiles(globs: string[], { cwd, exclude }?: {
     cwd?: string;
+    exclude?: (entry: string) => boolean;
 }): string[];
 /**
  * Scan every instruction file matched by `globs` and return only those with
  * findings, each path reported relative to `cwd`. Unreadable/missing files are
  * skipped. Pure scan — no mutation; pair with {@link cleanFile} to strip.
  * @param {string[]} globs
- * @param {{ cwd?: string }} [options]
+ * @param {{ cwd?: string, exclude?: (entry: string) => boolean }} [options]
+ *   `exclude` is forwarded to {@link findInstructionFiles}
  * @returns {Array<{ file: string, findings: ReturnType<typeof scanText> }>}
  */
-export function scanInstructionFiles(globs: string[], { cwd }?: {
+export function scanInstructionFiles(globs: string[], { cwd, exclude }?: {
     cwd?: string;
+    exclude?: (entry: string) => boolean;
 }): Array<{
     file: string;
     findings: ReturnType<typeof scanText>;
@@ -135,3 +144,4 @@ export function atomicReplaceFile(absPath: string, data: string, mode: number, t
  * @returns {boolean}
  */
 export function cleanFile(absPath: string, lstat?: (path: string) => import("node:fs").Stats): boolean;
+export { CLAUDE_CONTEXT_SUBDIRS, CLAUDE_INSTRUCTION_GLOBS, excludeFromContextScan } from "./claude-context.mjs";

package/types/invisible.d.mts

@@ -46,6 +46,72 @@ export function countPayloadInvisible(text: string): number;
  * @returns {string}
  */
 export function payloadInvisibleView(text: string): string;
+/**
+ * The first payload-invisible LONG RUN in `text`, or null when there is none.
+ *
+ * THE definition of "this text carries a hidden run", shared by every consumer
+ * that has an opinion about one: the strip's `[LONG RUN — possible injection
+ * payload]` marker, the prompt gate's block decision, and the tool-output
+ * severity tier. They used to spell it twice, and differently — the marker
+ * probed the PAYLOAD view while the prompt gate probed the raw text, so a
+ * legitimate ten-emoji flag sequence (carve-out-preserved, never stripped) was
+ * quietly enough to BLOCK a prompt while the strip that saw the same text
+ * declined to even flag it. Masking the preserved invisibles is the right half
+ * of that disagreement: a run the carve-out keeps is rendering work, not a
+ * channel, and the joiners it does NOT keep are counted as payload anyway (see
+ * {@link countEffectiveInvisible}).
+ *
+ * Because the view replaces only PRESERVED invisibles (and visible characters)
+ * with spaces, a match consists solely of payload code points and is therefore
+ * byte-identical to the corresponding span of `text` — so a caller may report
+ * the sample verbatim.
+ * @param {string} text
+ * @returns {string | null}
+ */
+export function payloadLongRunSample(text: string): string | null;
+/**
+ * How many invisible code points in `text` the strip layer treats as PAYLOAD:
+ * the ones {@link countPayloadInvisible} counts, plus the joiners that sit in a
+ * genuine linguistic context but exceed the carve-out's preservation budget.
+ *
+ * The surplus term closes the preserved-joiner covert channel (O3):
+ * `countPayloadInvisible` excludes every ZWNJ/ZWJ doing real rendering work, so
+ * an attacker who alternates `letter joiner letter joiner …` — every joiner
+ * legitimately between two cursive letters — counts as ZERO there. The strip
+ * layer already refuses that (it preserves joiners only up to
+ * TOTAL_PRESERVED_JOINER_BUDGET / CONSECUTIVE_JOINER_CAP and strips the rest),
+ * so the surplus is read back OFF the strip — the SSOT — rather than by
+ * re-deriving the budget here, which is what would drift.
+ *
+ * A leading BOM is preserved by the strip but counted by
+ * {@link countPayloadInvisible}, so the difference can go slightly negative;
+ * hence the clamp.
+ * @param {string} text  ANSI-stripped text (an escape sequence can hide invisibles)
+ * @returns {number}
+ */
+export function countEffectiveInvisible(text: string): number;
+/**
+ * True when the invisible characters in `text` are INCIDENTAL: no hidden run,
+ * and too few of them in total to carry an instruction.
+ *
+ * This is a severity line, not a strip line — the bytes are removed either way
+ * (see ../src/severity.mjs). It exists because a single soft hyphen in a
+ * pasted paragraph, or one variation selector a font demanded, raised the exact
+ * `WARNING: Tool output sanitized` an encoded payload does, and a warning that
+ * fires on a stray character in ordinary prose is one operators learn to skip.
+ *
+ * The bar is {@link LONG_RUN_THRESHOLD} — the count this module already calls
+ * "payload length" — applied to the WHOLE text rather than to one run, so it is
+ * strictly stronger than the run probe: fewer than ten payload-invisible code
+ * points, however they are distributed, cannot spell a smuggled instruction (ten
+ * tag characters are ten ASCII letters). Deliberately NOT the far looser
+ * {@link SCATTERED_THRESHOLD} of 30, which is the prompt gate's BLOCK bar: 29
+ * tag characters is a short sentence, and staying quiet about a short sentence
+ * hidden in a tool result is not a trade worth making.
+ * @param {string} text  ANSI-stripped text, invisible runs intact
+ * @returns {boolean}
+ */
+export function isIncidentalInvisible(text: string): boolean;
 /**
  * Strip payload-capable invisible chars and report which categories were
  * removed. A single leading U+FEFF (BOM) is preserved as a legitimate marker;

package/types/layer1.d.mts

@@ -99,3 +99,15 @@ export function applyLayer1(text: string): {
     ansiKinds: string[];
 };
 export const LONE_SURROGATE_RE: RegExp;
+/**
+ * What a reader is told when the ONLY thing a strip removed was inert ANSI (see
+ * {@link isBenignAnsiKinds}).
+ *
+ * It lives here, beside the predicate that decides it, because every entry point
+ * that can reach that verdict must say the same thing: the tool-output pipeline,
+ * the prompt gate's pass-with-note, and any host wiring its own. The wording is
+ * deliberately not `describeStripped`'s — "Stripped: ANSI escapes" names a
+ * category that reads like an attack, when the honest report is "these were
+ * colour codes, and here is how to look at the raw bytes".
+ */
+export const INERT_ANSI_NOTE: string;

package/types/output.d.mts

@@ -50,18 +50,26 @@ export function deleteVerbatimSpans(text: string, spans: string[]): {
  * post-mutation invariants and forget the rest, and every string in the returned
  * object has traversed Layer 4.
  *
- * `found` is the machine-readable twin of `warnings` — the {@link CATEGORY}
- * codes for what Layers 1-3 neutralized or flagged, in the order the layers ran.
- * Layers 4 and 5 have no category codes (their findings are the injected seam's
- * own vocabulary), so they contribute warnings only.
+ * Findings come back SPLIT BY SEVERITY (see ./severity.mjs): `warnings` holds
+ * everything injection-shaped — the banner a caller must show — and `notes`
+ * holds what happened but is not alarming. `warnings` therefore keeps exactly
+ * the meaning it always had, and a caller that ignores `notes` is no louder
+ * than before, just quieter about incidental bytes.
+ *
+ * `found` is the machine-readable twin, and the severity split does NOT reach
+ * it — the {@link CATEGORY} codes for what Layers 1-3 neutralized or flagged,
+ * in the order the layers ran, whichever tier described them. Layers 4 and 5
+ * have no category codes (their findings are the injected seam's own
+ * vocabulary), so they contribute findings only.
  * @param {string} text
  * @param {SanitizeTextOptions} [options]
- * @returns {Promise<{ cleaned: string, found: string[], warnings: string[], modified: boolean, sgrNote: boolean, reveal?: string }>}
+ * @returns {Promise<{ cleaned: string, found: string[], warnings: string[], notes: string[], modified: boolean, sgrNote: boolean, reveal?: string }>}
  */
 export function sanitizeText(text: string, options?: SanitizeTextOptions): Promise<{
     cleaned: string;
     found: string[];
     warnings: string[];
+    notes: string[];
     modified: boolean;
     sgrNote: boolean;
     reveal?: string;
@@ -82,8 +90,10 @@ export function isWalkableContainer(value: any): boolean;
 /**
  * Sanitize every string leaf of a tool-output value, preserving its shape (a
  * structured tool output whose shape changes would be ignored by a harness,
- * leaking the raw value). Non-string leaves pass through; `warnings`
- * accumulates across leaves. `sgrNote` is the OR across leaves.
+ * leaking the raw value). Non-string leaves pass through; `warnings` and
+ * `notes` accumulate across leaves, split by severity (see ./severity.mjs).
+ * `sgrNote` is the OR across leaves — true when SOME leaf was note-only — so a
+ * caller can still pick the quiet banner when no leaf raised a warning.
  *
  * Fails CLOSED on two hostile shapes that would otherwise throw a `RangeError`
  * as an unhandled async rejection (a DoS that leaves the output un-sanitized):
@@ -99,9 +109,12 @@ export function isWalkableContainer(value: any): boolean;
  * @param {SanitizeTextOptions} options
  * @param {string[]} warnings
  * @param {string[]} [reveals]
+ * @param {string[]} [notes]  the NOTE-severity counterpart of `warnings`;
+ *   appended last so an existing positional caller keeps working (it simply
+ *   discards the notes, which is exactly as loud as before the split)
  * @returns {Promise<{ value: any, modified: boolean, sgrNote: boolean }>}
  */
-export function sanitizeValue(value: any, options: SanitizeTextOptions, warnings: string[], reveals?: string[]): Promise<{
+export function sanitizeValue(value: any, options: SanitizeTextOptions, warnings: string[], reveals?: string[], notes?: string[]): Promise<{
     value: any;
     modified: boolean;
     sgrNote: boolean;
@@ -199,16 +212,18 @@ export type Layer5Result = {
 };
 /**
  * The running state of one {@link sanitizeText} call. Layers read `text` and
- * mutate it ONLY through {@link applyMutation}. `found` is the machine-readable
- * twin of `warnings`: the {@link CATEGORY} codes for whatever Layers 1-3
- * neutralized or flagged.
+ * mutate it ONLY through {@link applyMutation}. Findings carry their own
+ * severity (see ./severity.mjs) and are split into `warnings`/`notes` at the
+ * single exit, so no layer can push into the wrong list. `found` is the
+ * machine-readable twin, unaffected by the split: the {@link CATEGORY} codes
+ * for whatever Layers 1-3 neutralized or flagged.
  */
 export type PipelineState = {
     text: string;
     found: string[];
-    warnings: string[];
+    findings: import("./severity.mjs").Finding[];
     modified: boolean;
-    sgrNote: boolean;
+    unreportedChange: boolean;
 };
 export type SanitizeTextOptions = {
     html?: boolean;
@@ -218,4 +233,4 @@ export type SanitizeTextOptions = {
     sgrCarveOut?: boolean;
 };
 import { needsMarkdownPipeline } from "./gates.mjs";
-export { describeRemoved, describeWarned } from "./warnings.mjs";
+export { describeExfil, describeRemoved, describeWarned } from "./warnings.mjs";

package/types/severity.d.mts

@@ -0,0 +1,83 @@
+/**
+ * @typedef {{ severity: string, message: string }} Finding
+ *   A single reportable outcome and how loudly to report it.
+ */
+/**
+ * A WARNING-severity finding: injection-shaped, worth the banner.
+ * @param {string} message
+ * @returns {Finding}
+ */
+export function warning(message: string): Finding;
+/**
+ * A NOTE-severity finding: reported, not alarming.
+ * @param {string} message
+ * @returns {Finding}
+ */
+export function note(message: string): Finding;
+/**
+ * A finding at `severity` — the constructor for a caller that has already
+ * computed the tier as a boolean and would otherwise write the ternary itself.
+ * @param {boolean} isWarning
+ * @param {string} message
+ * @returns {Finding}
+ */
+export function finding(isWarning: boolean, message: string): Finding;
+/**
+ * The messages of every WARNING-severity finding, in order.
+ * @param {readonly Finding[]} findings
+ * @returns {string[]}
+ */
+export function warningMessages(findings: readonly Finding[]): string[];
+/**
+ * The messages of every NOTE-severity finding, in order.
+ * @param {readonly Finding[]} findings
+ * @returns {string[]}
+ */
+export function noteMessages(findings: readonly Finding[]): string[];
+/**
+ * The one place a finding's LOUDNESS is decided, and the vocabulary every layer
+ * reports in.
+ *
+ * Every layer of this pipeline used to have exactly one volume. A cursor-spoofing
+ * ANSI payload and a single stray escape byte in a README produced the same
+ * `WARNING: Tool output sanitized` banner; so did one soft hyphen, and so did
+ * the `<script>` tag that every fetched web page carries. That is the failure
+ * mode a detector dies of: a banner that fires on every ordinary page teaches its
+ * reader to skip the banner, and then the one that mattered scrolls past too.
+ *
+ * So a finding carries a SEVERITY, and the two tiers mean specific things:
+ *
+ *   WARNING — this text is injection-shaped. Something was hidden from a human
+ *             reader, something was removed that a payload would have used, or a
+ *             secret was redacted. Worth interrupting the reader for.
+ *   NOTE    — this happened, and here is how to look at it, but nothing about it
+ *             is attack-shaped. Incidental bytes, or content that was PRESERVED
+ *             and merely described.
+ *
+ * The tier never changes what the pipeline DOES: the same bytes are stripped,
+ * spliced and redacted either way, and a note is still reported. All that rides
+ * on it is which banner the operator sees, which is why a note is the right
+ * answer whenever the evidence is thin — an under-loud true finding is still
+ * delivered, while an over-loud false one costs the channel its credibility.
+ *
+ * Mechanism only, deliberately: WHICH findings qualify is each layer's own
+ * judgement, made where that layer's evidence lives (see isBenignAnsiKinds in
+ * ./layer1.mjs, isIncidentalInvisible in ./invisible.mjs, and the exfil/HTML
+ * tiers in ./output.mjs and ./index.mjs). This module owns the enum, the constructors and the
+ * queries so nobody spells `severity === "warning"` by hand.
+ */
+/**
+ * The closed severity vocabulary. Stable, machine-readable values: branch on
+ * these, not on the prose.
+ */
+export const SEVERITY: Readonly<{
+    NOTE: "note";
+    WARNING: "warning";
+}>;
+/**
+ * A single reportable outcome and how loudly to report it.
+ */
+export type Finding = {
+    severity: string;
+    message: string;
+};

package/types/src/claude-context.d.mts

@@ -0,0 +1,88 @@
+/**
+ * The one directory no instruction-file walk ever descends into. Its own
+ * function so the name is spelled once, and so the two predicates that need it
+ * (a plain glob walk, and {@link excludeFromContextScan}) cannot disagree.
+ * @param {string} entry  a bare entry name or a path relative to the scan root
+ * @returns {boolean}
+ */
+export function excludeNodeModules(entry: string): boolean;
+/**
+ * Entries a context scan must not descend into or return: `node_modules`, and
+ * every child of a `.claude` directory that is not whitelisted context.
+ *
+ * The globs alone would already refuse to MATCH those files, but a glob walker
+ * calls this on directories as it walks and prunes the ones it rejects — which
+ * is where the cost actually is. Without the prune, a `.claude/worktrees/`
+ * holding a few repo checkouts is walked in full on every session start (and,
+ * because a doubled-star segment does cross into a dot directory when the
+ * pattern names one, a `.claude` NESTED inside a worktree was matched and
+ * scanned as if it were this session's context).
+ *
+ * A walker calls this with both bare names and root-relative paths, so it must
+ * answer for either; a bare name carries no `.claude` context and is judged only
+ * against `node_modules`.
+ * @param {string} entry  a bare entry name or a path relative to the scan root
+ * @returns {boolean}
+ */
+export function excludeFromContextScan(entry: string): boolean;
+/**
+ * WHICH files an agent loads as model context, as data: the glob set and the
+ * walk-pruning predicate that together define "everything Claude Code reads as
+ * instructions, and nothing else".
+ *
+ * This is the SINGLE SOURCE for that scope. It used to live inside
+ * `claude-hooks/scan-invisible-chars.mjs`, which meant the SessionStart hook
+ * knew the answer and nobody else did: `src/instructions.mjs` takes
+ * caller-supplied globs by design (no agent's convention is baked into the
+ * engine), so the CLI, the Python port and every downstream fork spelled their
+ * own approximation of this list — and an approximation that drifts either
+ * scans bulk data that can never reach the model (the 30-second session start
+ * this whitelist exists to fix) or MISSES a context directory entirely, which
+ * is a silent hole in the one scan standing between a poisoned instruction file
+ * and a session that loads it.
+ *
+ * It is a standalone, dependency-free DATA module (like ./cf-charset.mjs) for
+ * two reasons: `src/instructions.mjs` re-exports it as the library's public
+ * door, and the hook imports it RELATIVELY — deliberately not through the
+ * `agent-sanitizer` specifier the plugin bundle pins to a published engine.
+ * This scope is hook POLICY, not engine behavior: it must ship and move with the
+ * hook that walks it, or a plugin built against an older pin would prune the
+ * wrong directories while believing it had scanned everything.
+ */
+/**
+ * The `.claude/` subdirectories whose markdown Claude Code loads as model
+ * context. This is a WHITELIST, and that is the point: `.claude/` is also where
+ * tooling parks bulk data that is never loaded as context — `worktrees/`
+ * (entire checked-out copies of the repo), plus caches, transcripts and
+ * snapshots — and globbing `.claude/**` swept all of it in. On a repo with a few
+ * populated worktrees that is thousands of files READ at every session start:
+ * one report put it at 30 seconds of blocked startup, paid for scanning files
+ * that cannot reach the model.
+ *
+ * A whitelist, not a `worktrees` denylist, because the failure modes are not
+ * symmetric: an unlisted context directory costs a scan nobody asked for anyway
+ * (the PostToolUse sanitizer still cleans those bytes when a tool reads them),
+ * while an unlisted BULK directory silently costs every future session its
+ * startup. Add an entry here when Claude Code starts loading a new `.claude/`
+ * subdirectory as context.
+ */
+export const CLAUDE_CONTEXT_SUBDIRS: readonly string[];
+/**
+ * Every glob whose matches Claude Code loads as model context: the
+ * per-directory instruction files (CLAUDE.md, CLAUDE.local.md, AGENTS.md) and
+ * the whitelisted `.claude/` markdown. Claude Code loads these on entry to their
+ * containing directory — a load path that bypasses the PostToolUse sanitizer —
+ * so a payload planted in e.g. `packages/foo/CLAUDE.md` reaches the model
+ * uncleaned unless something scans it here.
+ *
+ * `**` does not descend into dot directories, so NESTED `.claude/` trees need
+ * their own doubled-star-prefixed patterns: without them a directory-scoped
+ * skill at `packages/foo/.claude/skills/x/SKILL.md` — model context by the same
+ * load path — is never matched. That same rule is why the root `.claude` needs
+ * no separate entry: a leading doubled star matches zero segments, so the
+ * nested patterns cover the root tree too.
+ *
+ * Pair with {@link excludeFromContextScan}: the patterns alone already refuse to
+ * MATCH a bulk directory, but only pruning the WALK avoids paying to read it.
+ */
+export const CLAUDE_INSTRUCTION_GLOBS: readonly string[];

package/types/view-map.d.mts

@@ -1,37 +1,48 @@
 /**
  * @typedef {{ placeholder: string, original: string, start: number }} RedactionPair
- * @typedef {{ text: string, pairs: readonly RedactionPair[] }} FileView
- *   A branded, frozen carrier from {@link makeFileView}. `pairs` are in UTF-16
- *   offsets, sorted and non-overlapping — both enforced at construction.
+ * @typedef {"codePoint" | "utf16"} OffsetSpace
+ *   Units a {@link FileView}'s pair offsets are expressed in. `codePoint` is
+ *   what the redactor's map mode emits (Python indexes strings by code point);
+ *   `utf16` is what every function in this module indexes by (JS
+ *   `indexOf`/`slice`/`.length` count UTF-16 code units).
  */
 /**
- * Build the branded file view from a redactor's map-mode result.
+ * A branded, frozen carrier from {@link makeFileView}, tagged with the space its
+ * `pairs` offsets live in. Its own JSDoc block: a `@template` applies to every
+ * typedef in the comment it sits in, so sharing one with the two above would
+ * make `RedactionPair` and `OffsetSpace` generic too.
+ * @template {OffsetSpace} S
+ * @typedef {{ readonly space: S, readonly text: string,
+ *   readonly pairs: readonly RedactionPair[] }} FileView
+ */
+/**
+ * Wrap a redactor's map-mode result in a frozen, branded view tagged with the
+ * space its offsets are in.
  *
  * The redactor's own object is never touched. It used to be: the caller did
  * `view.pairs = pairsToUtf16(view.text, view.pairs)`, an in-place mutation of a
  * value returned from an INJECTED seam. A redactor that memoizes its map result
  * (a reasonable thing for a caller to build) hands back the same object on the
- * second identical call, which then gets converted a SECOND time — every
+ * second identical call, which then got converted a SECOND time — every
  * placeholder preceded by an astral character shifts again and the same input
- * yields a different verdict. Converting into a fresh frozen carrier removes
- * that: the conversion is part of construction, the redactor's value is left
- * alone, and every consumer asserts the brand rather than accepting a
- * hand-assembled `{text, pairs}` whose offsets may or may not be converted.
+ * yields a different verdict.
  *
- * It does NOT make double conversion impossible — `makeFileView(v.text,
- * v.pairs)` on an existing view would convert again. Nothing does that, and a
- * guard would have to reject legitimately-frozen caller input to catch it, so
- * the defence here is that there is exactly one construction site and it takes
- * the redactor's result directly.
+ * Construction no longer converts. It brands and records the space, and
+ * {@link toUtf16View} does the conversion behind a check that the input is
+ * still in code-point space — so `toUtf16View(alreadyConverted)` throws where
+ * `makeFileView(v.text, v.pairs)` on an existing view used to silently convert
+ * a second time. That was the one door this carrier left open.
  *
- * The frozen `pairs` array is likewise a copy — `pairsToUtf16` returns its
- * argument unchanged for the empty case, and freezing the redactor's array
- * would reach back into the seam's memoized value.
+ * Both the array AND each pair object are copied before freezing, so nothing
+ * here reaches back into the seam's (possibly memoized) value, and a caller that
+ * later mutates its own pairs cannot change what this view resolves.
+ * @template {OffsetSpace} S
  * @param {string} text redacted view text
- * @param {RedactionPair[]} pairs redactor pairs, in CODE-POINT offsets
- * @returns {FileView}
+ * @param {readonly RedactionPair[]} pairs redactor pairs, offsets in `space`
+ * @param {S} space
+ * @returns {FileView<S>}
  */
-export function makeFileView(text: string, pairs: RedactionPair[]): FileView;
+export function makeFileView<S extends OffsetSpace>(text: string, pairs: readonly RedactionPair[], space: S): FileView<S>;
 /**
  * Non-overlapping occurrence indices of `needle` in `haystack`.
  * @param {string} haystack
@@ -77,24 +88,33 @@ export function alignDeletions(content: string, cleaned: string): {
  * placeholder mis-anchors the edit onto the wrong bytes.
  *
  * Exactly once, though: applying it to its own output shifts every
- * astral-preceded placeholder a second time. Prefer {@link makeFileView}, which
- * runs it as part of construction and hands back a branded carrier the rest of
- * this module accepts; this stays exported (it is public API on the
- * `./view-map` subpath) for callers doing their own offset bookkeeping, who own
- * the once-only discipline themselves.
+ * astral-preceded placeholder a second time, and bare arrays of numbers give
+ * nothing to check that against. Prefer {@link toUtf16View}, which runs this
+ * behind a space check so the second application throws instead. This stays
+ * exported — it is public API on the `./view-map` subpath, and removing it
+ * would be a breaking change the release workflow cannot express (it caps
+ * automated bumps at minor) — for callers doing their own offset bookkeeping,
+ * who own the once-only discipline themselves.
  * @param {string} text the redacted view text the offsets index into
- * @param {{placeholder: string, original: string, start: number}[]} pairs
- * @returns {{placeholder: string, original: string, start: number}[]}
+ * @param {RedactionPair[]} pairs
+ * @returns {RedactionPair[]}
  */
-export function pairsToUtf16(text: string, pairs: {
-    placeholder: string;
-    original: string;
-    start: number;
-}[]): {
-    placeholder: string;
-    original: string;
-    start: number;
-}[];
+export function pairsToUtf16(text: string, pairs: RedactionPair[]): RedactionPair[];
+/**
+ * The same view with its pair offsets re-expressed in UTF-16 code units — a NEW
+ * frozen carrier; `view` is untouched.
+ *
+ * The one-way door. Only a `"codePoint"` view is accepted, so converting an
+ * already-converted view throws rather than shifting every astral-preceded
+ * offset a second time — which either mis-anchors the edit or rejects it as
+ * cutting a placeholder, both from an input that was fine the first time it was
+ * seen. Offset range/sort/overlap validity is not this door's job — every
+ * carrier is checked at construction (see {@link assertPairsOrdered}), in
+ * whichever space it declares.
+ * @param {FileView<"codePoint">} view
+ * @returns {FileView<"utf16">}
+ */
+export function toUtf16View(view: FileView<"codePoint">): FileView<"utf16">;
 /**
  * Resolve view span [viewStart, viewEnd) to its on-disk text and the redaction
  * pairs it wholly contains, mapping across placeholder expansion (view →
@@ -108,12 +128,12 @@ export function pairsToUtf16(text: string, pairs: {
  * and a mis-attributed run would mis-anchor the edit.
  * @param {string} content disk file content
  * @param {string} cleaned Layer-1 view of `content`
- * @param {FileView} view
+ * @param {FileView<"utf16">} view
  * @param {{start: number, deleted: string}[]} deletions
  * @param {number} viewStart
  * @param {number} viewEnd
  */
-export function resolveSpan(content: string, cleaned: string, view: FileView, deletions: {
+export function resolveSpan(content: string, cleaned: string, view: FileView<"utf16">, deletions: {
     start: number;
     deleted: string;
 }[], viewStart: number, viewEnd: number): {
@@ -185,11 +205,11 @@ export function spliceOrdered(text: string, matches: {
  * was never part of the secret); interior runs are included. Callers use these
  * to detect an edit whose on-disk footprint intrudes into bytes the model was
  * never shown.
- * @param {FileView} view
+ * @param {FileView<"utf16">} view
  * @param {{start: number, deleted: string}[]} deletions
  * @returns {{start: number, end: number}[]}
  */
-export function pairDiskSpans(view: FileView, deletions: {
+export function pairDiskSpans(view: FileView<"utf16">, deletions: {
     start: number;
     deleted: string;
 }[]): {
@@ -221,10 +241,20 @@ export type RedactionPair = {
     start: number;
 };
 /**
- * A branded, frozen carrier from {@link makeFileView}. `pairs` are in UTF-16
- * offsets, sorted and non-overlapping — both enforced at construction.
+ * Units a {@link FileView}'s pair offsets are expressed in. `codePoint` is
+ * what the redactor's map mode emits (Python indexes strings by code point);
+ * `utf16` is what every function in this module indexes by (JS
+ * `indexOf`/`slice`/`.length` count UTF-16 code units).
  */
-export type FileView = {
-    text: string;
-    pairs: readonly RedactionPair[];
+export type OffsetSpace = "codePoint" | "utf16";
+/**
+ * A branded, frozen carrier from {@link makeFileView}, tagged with the space its
+ * `pairs` offsets live in. Its own JSDoc block: a `@template` applies to every
+ * typedef in the comment it sits in, so sharing one with the two above would
+ * make `RedactionPair` and `OffsetSpace` generic too.
+ */
+export type FileView<S extends OffsetSpace> = {
+    readonly space: S;
+    readonly text: string;
+    readonly pairs: readonly RedactionPair[];
 };