agent-sanitizer 2.19.2 → 2.19.4

package/types/claude-hooks/lib/hook-fault.d.mts

@@ -0,0 +1,104 @@
+/**
+ * Declare a hook's failure posture. Called at module scope by each hook, so
+ * importing the hook is what makes its posture reachable.
+ * @param {string} hook  a member of {@link FAULT_POLICY_HOOKS}
+ * @param {FaultPolicy} policy
+ * @returns {void}
+ */
+export function registerFaultPolicy(hook: string, policy: FaultPolicy): void;
+/**
+ * The registered policy for `hook`. Throws rather than defaulting: a hook whose
+ * posture nobody declared has no defensible default — guessing OPEN would let
+ * the guarded action through on a hook an operator believed was strict, and
+ * guessing CLOSED would block a session on a wiring bug.
+ * @param {string} hook
+ * @returns {FaultPolicy}
+ */
+export function faultPolicy(hook: string): FaultPolicy;
+/**
+ * Resolve `hook`'s response to its own failure under the caller's posture. This
+ * is the ONLY place {@link failOpenEnabled} is consulted on a hook fault, so the
+ * knob cannot be honored in three hooks and skipped in the fourth.
+ * @param {string} hook
+ * @param {unknown} err
+ * @param {Record<string, any> & {
+ *   env?: NodeJS.ProcessEnv | Record<string, string | undefined>,
+ * }} [ctx]  hook-specific inputs threaded to the builders (a message table, the
+ *   parsed input, a remedy). `env` selects the posture; it is threaded to the
+ *   builders along with the rest, though none reads it — the posture is resolved
+ *   here precisely so a builder never has to.
+ * @returns {FaultOutcome}
+ */
+export function hookFaultOutcome(hook: string, err: unknown, ctx?: Record<string, any> & {
+    env?: NodeJS.ProcessEnv | Record<string, string | undefined>;
+}): FaultOutcome;
+/**
+ * Render an outcome's stdout/stderr halves and return its exit code. The caller
+ * decides what to do with the code (a hook that must keep running ignores it),
+ * and performs `armAlert` itself — persisting the alert needs the hook's own
+ * report text, which this module has no view of.
+ * @param {FaultOutcome} outcome
+ * @param {(chunk: string) => void} [write]
+ * @param {(chunk: string) => void} [writeErr]
+ * @returns {number}
+ */
+export function writeFaultOutcome(outcome: FaultOutcome, write?: (chunk: string) => void, writeErr?: (chunk: string) => void): number;
+/**
+ * The hook modules that must register a fault policy — every CLI entry point in
+ * `claude-hooks/*.mjs`. Declared here rather than discovered so registering an
+ * unknown name is an error instead of a typo nobody notices.
+ * @type {readonly string[]}
+ */
+export const FAULT_POLICY_HOOKS: readonly string[];
+/**
+ * What a hook's fault renders to. `fields`/`envelope` are the stdout response
+ * (`fields` is the `hookSpecificOutput` body, wrapped with the policy's event;
+ * `envelope` is a hook that answers with a top-level shape instead, like
+ * UserPromptSubmit's `{decision:"block"}`); `stderr` and `exitCode` are the
+ * process-level halves a hook with no stdout channel uses; `armAlert` asks the
+ * caller to persist its cross-hook alert so a LATER gate carries the closed
+ * posture the faulting hook could not express itself.
+ */
+export type FaultOutcome = {
+    posture: "open" | "closed";
+    fields: Record<string, unknown> | null;
+    fallbackFields: Record<string, unknown> | null;
+    envelope: object | null;
+    stderr: string | null;
+    exitCode: number;
+    armAlert: boolean;
+};
+/**
+ * What a policy's `open`/`closed` builder returns: any subset of a
+ * {@link FaultOutcome}'s renderable slots. Everything omitted takes its default
+ * (no output, exit 0, no alert).
+ */
+export type FaultParts = {
+    fields?: Record<string, unknown>;
+    fallbackFields?: Record<string, unknown>;
+    envelope?: object;
+    stderr?: string;
+    exitCode?: number;
+    armAlert?: boolean;
+};
+/**
+ * The context a builder is handed: the caller's own inputs (whatever it passed
+ * to {@link hookFaultOutcome}) plus the three values every hook derived by hand
+ * before — the hook name, the scrubbed error message, and the model-facing
+ * open-posture warning.
+ */
+export type FaultContext = Record<string, any> & {
+    hook: string;
+    err: unknown;
+    message: string;
+    openContext: string;
+};
+/**
+ * A hook's declared posture.
+ */
+export type FaultPolicy = {
+    event: string | null;
+    guarded: string;
+    open?: (ctx: FaultContext) => FaultParts;
+    closed: (ctx: FaultContext) => FaultParts;
+};

package/types/claude-hooks/lib/layer-pipeline.d.mts

@@ -0,0 +1,113 @@
+/**
+ * Whether `layers` places an erasing layer after a skip-based one — the ordering
+ * whose soundness needs a fixed point. Exported so the property is assertable
+ * about a table directly, not only through a run.
+ * @param {Layer[]} layers
+ * @returns {boolean}
+ */
+export function needsFixedPoint(layers: Layer[]): boolean;
+/**
+ * Run a declared layer chain over one tool input.
+ *
+ * Returns the final input, whether anything changed, and the model-facing notes
+ * in the order they were produced (deduplicated: a fixed-point re-run that
+ * repeats a layer's note would otherwise say the same thing twice). A layer that
+ * denies ends the run immediately, with `deny` set.
+ * @param {string} tool
+ * @param {any} toolInput
+ * @param {Layer[]} layers
+ * @returns {Promise<{ updatedInput: any, changed: boolean, contexts: string[], deny?: string }>}
+ */
+export function runLayerPipeline(tool: string, toolInput: any, layers: Layer[]): Promise<{
+    updatedInput: any;
+    changed: boolean;
+    contexts: string[];
+    deny?: string;
+}>;
+/**
+ * The PreToolUse layer chain as a DECLARED pipeline instead of a run of
+ * sequential statements.
+ *
+ * The confusable fold (Layer 2) carries a soundness precondition: it deliberately
+ * SKIPS a token that still holds an unmapped non-ASCII glyph, because such a
+ * token can never come out byte-equal to an ASCII deny-rule target, so folding it
+ * would only mangle real foreign-language text. That argument holds only while no
+ * later layer ERASES code points from the same field — if it does, the glyph the
+ * fold relied on can disappear after the decision was taken.
+ *
+ * Layer 3 (authored-content stripping) erases exactly that: payload-capable
+ * invisible characters. Running it after the fold made the precondition false,
+ * and the gap was reachable: `cat /etc/p<CYRILLIC A><12 x ZWSP>sswd` put the
+ * zero-width run inside the token, so the fold skipped it, then the strip removed
+ * the padding and emitted `cat /etc/p<CYRILLIC A>sswd` — the homoglyph intact and
+ * the evidence for skipping it gone. Zero-width padding suppressed the fold and
+ * the next layer erased the reason.
+ *
+ * The eliminator is structural: layers declare whether they ERASE code points and
+ * whether their decision is SKIP-BASED (suppressible by code points another layer
+ * erases), and this driver enforces the precondition rather than a comment
+ * asking a future reader to preserve it. When the table puts an erasing layer
+ * after a skip-based one, the driver re-runs the body to a FIXED POINT, so the
+ * emitted value is one every skip-based layer has seen in its final form. A table
+ * that needs no fixed point runs exactly once, so the cost is paid only by the
+ * ordering that creates the hazard.
+ *
+ * Layers may be `terminal`: run once, after the fixed point, never re-run. That
+ * is Layer 4 (rehydration), whose whole contract is that it sees the FINAL
+ * authored text and its restored secrets are not re-stripped by Layer 3. Terminal
+ * layers must be a suffix of the table, which the driver checks.
+ */
+/**
+ * A layer's result: the rewritten input plus the model-facing note, a `deny`
+ * verdict that ends the pipeline, or null when the layer changed nothing.
+ * @typedef {{ updatedInput: any, context: string } | { deny: string } | null} LayerResult
+ */
+/**
+ * One declared layer.
+ * - `erases` — may REMOVE code points from a field another layer reads. This is
+ *   the property that can invalidate a skip-based decision taken earlier.
+ * - `skipBased` — its decision can be suppressed by code points present at the
+ *   time it ran. Such a layer must be re-run after any erasure.
+ * - `terminal` — runs once after the fixed point and is never re-run.
+ * @typedef {{
+ *   name: string,
+ *   erases: boolean,
+ *   skipBased: boolean,
+ *   terminal?: boolean,
+ *   run: (tool: string, input: any) => LayerResult | Promise<LayerResult>,
+ * }} Layer
+ */
+/**
+ * Bound on fixed-point passes. Each pass either changes the input or ends the
+ * loop, and the layers are contractive in practice (folding and stripping both
+ * shrink the space of remaining findings), so a run that is still changing after
+ * this many passes is a layer that oscillates — a bug. Throwing hands it to the
+ * hook's fail-closed catch, which is the loud outcome; looping forever would be
+ * silently killed by the harness and read as a non-blocking pass (fail OPEN).
+ */
+export const MAX_PIPELINE_PASSES: 8;
+/**
+ * A layer's result: the rewritten input plus the model-facing note, a `deny`
+ * verdict that ends the pipeline, or null when the layer changed nothing.
+ */
+export type LayerResult = {
+    updatedInput: any;
+    context: string;
+} | {
+    deny: string;
+} | null;
+/**
+ * One declared layer.
+ * - `erases` — may REMOVE code points from a field another layer reads. This is
+ *   the property that can invalidate a skip-based decision taken earlier.
+ * - `skipBased` — its decision can be suppressed by code points present at the
+ *   time it ran. Such a layer must be re-run after any erasure.
+ * - `terminal` — runs once after the fixed point and is never re-run.
+ */
+export type Layer = {
+    name: string;
+    erases: boolean;
+    skipBased: boolean;
+    terminal?: boolean;
+    run: (tool: string, input: any) => LayerResult | Promise<LayerResult>;
+};

package/types/claude-hooks/pretooluse-sanitize.d.mts

@@ -1,3 +1,19 @@
+/**
+ * The declared layer chain, layers 2-4. Every entry states the two properties
+ * the driver reasons about — whether it ERASES code points another layer reads,
+ * and whether its own decision is SKIP-BASED and therefore invalidated by such
+ * an erasure — so the confusable fold's ordering precondition is enforced by the
+ * table instead of restated as a comment.
+ *
+ * Layer 3 is dropped from the table (not merely skipped at run time) when
+ * AGENT_SANITIZER_OUTPUT_DISABLED=1, so the driver sees the chain that will
+ * actually run: with no erasing layer left after the fold there is no fixed
+ * point to reach and no extra pass to pay for.
+ * @param {(tool: string, toolInput: any) => ReturnType<typeof rehydrateRedacted>} rehydrate
+ * @param {NodeJS.ProcessEnv | Record<string, string | undefined>} [env]
+ * @returns {import("./lib/layer-pipeline.mjs").Layer[]}
+ */
+export function preToolUseLayers(rehydrate: (tool: string, toolInput: any) => ReturnType<typeof rehydrateRedacted>, env?: NodeJS.ProcessEnv | Record<string, string | undefined>): import("./lib/layer-pipeline.mjs").Layer[];
 /**
  * Compose the four protections. Returns the `hookSpecificOutput` fields to
  * emit, or null for a clean no-op. Throws only if a layer's engine throws; the

package/types/claude-hooks/scan-invisible-chars.d.mts

@@ -1,16 +1,86 @@
+/**
+ * Scan every instruction file under the project, ACCOUNTING for every target
+ * the finder returned: `scanned + skipped.length === targets.length`, always.
+ *
+ * The accounting is the point. This scan is the only thing standing between a
+ * poisoned `CLAUDE.md` and a session that loads it as instructions, and its
+ * caller announces "clean" on the trace channel — the channel that exists so a
+ * MISSING announcement is loud. A per-file failure swallowed into an empty
+ * findings list turns "we could not read this file" into "this file is fine",
+ * which is the one lie this hook must never tell. So a file that cannot be read
+ * is REPORTED as unscanned, not dropped.
+ *
+ * ANY errno is a skip; only a non-filesystem throw propagates. The split is
+ * between "this file could not be read" (report it and keep scanning) and "this
+ * code is broken" (a TypeError from an unloaded binding — nothing here can be
+ * trusted, so it goes to the caller's declared failure posture). Catching only
+ * ENOENT would invert the enforcement: one EACCES target would discard the
+ * result for EVERY other instruction file, leaving them unscanned and
+ * un-auto-cleaned, and under the shipped OPEN posture the hook fault arms
+ * nothing — so the SUSPICIOUS failure would get weaker enforcement than the
+ * benign glob race, which reaches `partial` and arms the gate. Same errno-vs-bug
+ * split {@link autoCleanFindings} uses.
+ * @param {string} [dir]  project root to scan (injectable for tests)
+ * @returns {{
+ *   targets: string[],
+ *   scanned: number,
+ *   findings: Array<{file: string, findings: ReturnType<typeof scanFile>}>,
+ *   skipped: Array<{file: string, reason: string}>,
+ * }}
+ */
+export function scanProject(dir?: string): {
+    targets: string[];
+    scanned: number;
+    findings: Array<{
+        file: string;
+        findings: ReturnType<typeof scanFile>;
+    }>;
+    skipped: Array<{
+        file: string;
+        reason: string;
+    }>;
+};
+/**
+ * The report for targets the scan could not read. Rendered into the alert the
+ * PreToolUse gate surfaces, so an incomplete scan reaches the operator as a
+ * checkpoint rather than as silence.
+ * @param {Array<{file: string, reason: string}>} skipped
+ * @returns {string}
+ */
+export function formatSkipped(skipped: Array<{
+    file: string;
+    reason: string;
+}>): string;
 /**
  * The hook's CLI: scan the instruction files, auto-clean what it can, persist
  * the alert for the PreToolUse gate otherwise. Exported so a bundle entry
  * (which must claim the CLI slot before this module loads) can run the exact
  * same scan instead of duplicating it.
- * @param {{ trace?: import("./lib/trace.mjs").TraceFn }} [opts]  `trace` is where
- *   this scan announces engagement; a host with its own trace channel passes its
- *   sink so the announcement lands where its detector reads (see lib/trace.mjs).
+ * @param {{
+ *   trace?: import("./lib/trace.mjs").TraceFn,
+ *   scan?: () => ReturnType<typeof scanProject>,
+ * }} [opts]  `trace` is where this scan announces engagement; a host with its
+ *   own trace channel passes its sink so the announcement lands where its
+ *   detector reads (see lib/trace.mjs). `scan` is the scanner, injectable so the
+ *   FAULT path below — a scanner that throws something other than an errno, i.e.
+ *   a bug — is drivable end to end; no filesystem state can force it, and an
+ *   untested fault path is how a posture goes missing in the first place.
  * @returns {Promise<void>}
  */
-export function cliMain({ trace: sink }?: {
+export function cliMain({ trace: sink, scan: runScan }?: {
     trace?: import("./lib/trace.mjs").TraceFn;
+    scan?: () => ReturnType<typeof scanProject>;
 }): Promise<void>;
+/**
+ * @param {string} filePath
+ * @returns {Array<{ line: number, charCount: number, method: string, decoded: string }>}
+ */
+export function scanFile(filePath: string): Array<{
+    line: number;
+    charCount: number;
+    method: string;
+    decoded: string;
+}>;
 /**
  * @param {string} run
  * @returns {{ method: string, decoded: string }}
@@ -39,16 +109,6 @@ export function findMdFiles(dir: string): string[];
  * @returns {string[]}
  */
 export function findInstructionFiles(dir: string): string[];
-/**
- * @param {string} filePath
- * @returns {Array<{ line: number, charCount: number, method: string, decoded: string }>}
- */
-export function scanFile(filePath: string): Array<{
-    line: number;
-    charCount: number;
-    method: string;
-    decoded: string;
-}>;
 import { ALERT_FILE } from "./lib/invisible-alert.mjs";
 import { ALERT_ACK_FILE } from "./lib/invisible-alert.mjs";
 export let LONG_RUN_RE: RegExp;

package/types/confusables.d.mts

@@ -113,8 +113,12 @@ export function normalizeConfusables(tool: string, toolInput: any, { scan, field
  *
  * ORDERING: the soundness argument assumes no later layer erases code points
  * from the same field, which would let an unmapped glyph the gate relied on
- * disappear after the decision. Layer 4 runs before sanitizeAuthoredContent on
- * Bash.command; keep it there.
+ * disappear after the decision — a zero-width run padded into a token suppresses
+ * the fold, and the erasing layer then removes the very evidence for skipping it.
+ * This fold does NOT run last: on Bash.command the invisible-char strip follows
+ * it. A caller that composes the two is therefore responsible for re-running
+ * this fold on the post-erasure text until it reports nothing, which is what the
+ * hook driver in claude-hooks/lib/layer-pipeline.mjs does.
  *
  * Genuine non-confusable non-ASCII (accented Latin, CJK, emoji) is untouched
  * regardless, since a faithful scanner does not flag it.

package/types/invisible.d.mts

@@ -1,8 +1,15 @@
 /**
  * True when every ANSI control introducer in `text` belongs to a display-only
- * SGR color sequence (so stripping the ANSI removed only cosmetic styling,
+ * SGR color sequence (so stripping the ANSI removes only cosmetic styling,
  * nothing that could move the cursor, erase, or carry a payload). Recognizes
  * both the 7-bit `ESC[…m` and 8-bit C1 (`U+009B…m`) SGR encodings.
+ *
+ * Answered by the STRIPPER'S OWN tokenizer: scanAnsi emits one token per raw
+ * introducer — 7-bit ESC and the whole C1 block, so a C1 cursor-move
+ * (`U+009B 2J`), a C1-OSC string (`U+009D … BEL`), a C1-DCS/APC payload and a
+ * lone or partial escape each yield a non-SGR token — and the predicate is
+ * "every token is SGR". Because the same scan decides what Layer 1 splices,
+ * this can no longer report "colour only" for bytes the stripper leaves behind.
  * @param {string} text
  * @returns {boolean}
  */
@@ -84,7 +91,7 @@ export const CATEGORY_LABELS: Readonly<Record<string, string>>;
 /** @type {Array<[string, RegExp]>} Each entry pairs a CATEGORY code with its detector. */
 export const CHECKS: Array<[string, RegExp]>;
 export const STRIP: RegExp;
-export const SGR_RE: RegExp;
+export { SGR_RE } from "./ansi.mjs";
 export const LONG_RUN_THRESHOLD: 10;
 /** Total invisible-char count above which a file/prompt is treated as
  * payload-capable even without a long run (threshold-evasion catch). */
@@ -96,3 +103,5 @@ export const TOTAL_PRESERVED_JOINER_BUDGET: 16;
 export const PRESERVED_JOINER_PER_VISIBLE: 8;
 export const PRESERVE_HARD_CAP: 64;
 export const LINGUISTIC_SCRIPTS: string[];
+/** @type {ReadonlyArray<readonly [string, number, number]>} */
+export const BRAHMIC_CONSONANT_RANGES: ReadonlyArray<readonly [string, number, number]>;

package/types/layer1.d.mts

@@ -19,16 +19,25 @@ export function stripAnsiFully(input: string): string;
  * raw ANSI control introducer (7-bit ESC U+001B and the whole 8-bit C1 control
  * block U+0080–U+009F: CSI, the DCS/SOS/OSC/PM/APC string introducers, and ST).
  *
- * Removing an invisible character can reconstitute an escape its split hid from
- * the ANSI pass (`ESC`<ZWSP>`[32m` → `ESC[32m`), so strip ANSI again after the
- * invisible pass — but only when stripInvisible changed something, since
- * reconstitution is impossible otherwise and the re-strip is a wasted pass on
- * the hot clean path. The ANSI strip still cannot match an *incomplete*
- * reconstituted sequence (a lone `ESC[` left when an inner complete sequence is
- * removed from a nested split), so a final sweep removes every residual raw
- * introducer outright — that sweep, not the regex matching, is the guarantee
- * that no control introducer survives. `deAnsi` is the ANSI strip of the
- * original (invisible runs intact), the scope a LONG_RUN payload check needs.
+ * The two passes FEED each other in both directions, so neither ordering is
+ * enough on its own and the composition is iterated to a fixed point instead:
+ * removing an invisible char reconstitutes an escape its split hid
+ * (`ESC`<ZWSP>`[32m` → `ESC[32m`), and removing an escape makes two invisibles
+ * ADJACENT that were not (`م ZWJ ESC[m ZWJ م` → a joiner run the invisible pass
+ * classifies as a payload channel rather than linguistic). A pipeline with a
+ * fixed number of alternations always leaves one of those unanswered — this used
+ * to re-strip ANSI after the invisible pass and stop, so `applyLayer1` was not
+ * idempotent and the rehydrator's "re-cleaning reproduces the view" assumption
+ * did not hold.
+ *
+ * The residual sweep runs only once the composition is STABLE, because sweeping
+ * an introducer early destroys the sequence a later ANSI pass would have removed
+ * whole, promoting a hidden control to visible text. A final UNCONDITIONAL sweep
+ * follows the loop so the no-raw-introducer guarantee does not depend on the
+ * pass bound.
+ *
+ * `deAnsi` is the ANSI strip of the ORIGINAL text (invisible runs intact), the
+ * scope a LONG_RUN payload check needs — not an intermediate of the loop.
  * @param {string} text
  * @returns {{ cleaned: string, deAnsi: string, found: string[] }}
  */

package/types/output.d.mts

@@ -26,8 +26,21 @@ export function describeWarned(warned: {
 /**
  * Delete each verbatim span in `spans` from `text`. The secure Layer-5
  * primitive: a filter can only ask for deletions, so this can never inject
- * bytes. Returns the new text and how many distinct span-occurrences were
- * removed (0 when no span was present).
+ * bytes. Returns the new text and how many span occurrences were removed (0
+ * when no span was present).
+ *
+ * Every occurrence is located in the ORIGINAL `text` and the deletions applied
+ * in one ordered pass ({@link spliceOrdered}), so every removed byte lies inside
+ * a match some span had in the INPUT. Deleting span-by-span with a
+ * chained `split`/`join` would not hold that line: an earlier deletion joins the
+ * bytes on either side of it and can CREATE a match for a later span that never
+ * occurred in the input — `deleteVerbatimSpans("PRE-XX-POST", ["-XX-", "PREPOST"])`
+ * then deletes the whole document. That would widen the Layer-5 seam's blast
+ * radius (see the module doc) from "a compromised filter can at most remove the
+ * content it named" to "it can remove content it never named".
+ *
+ * Overlapping spans are resolved first-match-wins, so `removed` counts the
+ * occurrences actually spliced out, never a double-count of the same bytes.
  * @param {string} text
  * @param {string[]} spans
  * @returns {{ text: string, removed: number }}

package/types/view-map.d.mts

@@ -106,9 +106,15 @@ export function resolveSpan(content: string, cleaned: string, view: {
     }[];
 } | null;
 /**
- * All occurrences of any needle in `text`, ordered by position. Placeholder
- * texts never substring-overlap one another (each ends in "]" right after its
- * distinguishing label), so the sorted matches are non-overlapping.
+ * All occurrences of any needle in `text`, ordered by position. Every index is
+ * computed against the ORIGINAL `text`, so the caller can splice them in one
+ * pass ({@link spliceOrdered}). Redaction placeholder texts never
+ * substring-overlap one another (each ends in "]" right after its
+ * distinguishing label), so for that caller the sorted matches are also
+ * non-overlapping; needles from an untrusted source (a Layer-5 filter's
+ * removeSpans) can overlap, which spliceOrdered resolves first-match-wins.
+ * Distinct needles matching at the SAME index keep `needles` order (Array#sort
+ * is stable), so first-match-wins is deterministic.
  * @param {string} text
  * @param {string[]} needles
  * @returns {{text: string, index: number}[]}
@@ -117,6 +123,44 @@ export function orderedMatches(text: string, needles: string[]): {
     text: string;
     index: number;
 }[];
+/**
+ * Replace every match in `matches` with `replacementFor(match, i)` in a SINGLE
+ * ordered pass over `text`. THE splice primitive for this codebase — the sole
+ * sound way to substitute several needles at once.
+ *
+ * A chained `text.split(needle).join(value)` per needle is unsound in both
+ * directions, which is why no caller may hand-roll one:
+ *   - substitution: an inserted value whose bytes contain a LATER needle is
+ *     re-matched by the next split and corrupted (or partially exposed);
+ *   - deletion: an earlier deletion joins the bytes on either side of it and
+ *     can CREATE a later needle's match, deleting text that needle never
+ *     matched in the input ("PRE-XX-POST" minus "-XX-" yields "PREPOST").
+ * Because every index in `matches` is measured against the original `text`,
+ * this pass only ever touches bytes the caller actually matched.
+ *
+ * Overlapping matches are resolved first-match-wins: a match starting before
+ * the previous one ended is skipped, never spliced at a shifted offset.
+ * `i` is the match's index in `matches` (stable across skips) so a caller
+ * pairing matches positionally with its own array stays aligned.
+ * @param {string} text
+ * @param {{text: string, index: number}[]} matches ordered by index, indices into `text`
+ * @param {(match: {text: string, index: number}, i: number) => string} replacementFor
+ * @returns {{text: string, spans: {start: number, end: number}[]}} spliced text
+ *   and the [start, end) range each replacement occupies in it
+ */
+export function spliceOrdered(text: string, matches: {
+    text: string;
+    index: number;
+}[], replacementFor: (match: {
+    text: string;
+    index: number;
+}, i: number) => string): {
+    text: string;
+    spans: {
+        start: number;
+        end: number;
+    }[];
+};
 /**
  * On-disk [start, end) span of every redaction pair, mapped from its view
  * offset through placeholder expansion (view → cleaned) and stripped invisible