@event4u/agent-config 17.2.1 → 17.4.0

package/src/scripts/_cli/upgrade_unattended.ts

@@ -22,17 +22,14 @@
  * registry, a live session) · `1` a step failed and the previous version was
  * restored · `4` a step failed and the restore did not reach the previous version.
  */
+import * as crypto from 'node:crypto';
 import * as fs from 'node:fs';
+import * as os from 'node:os';
 import * as path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import process from 'node:process';
 
-import {
-    EXPECTED_WORKFLOW_REF,
-    attestation_workflow_ref,
-    provenance_matches_publish,
-    verify_attestation_signature,
-} from '../_lib/provenance_verify.js';
+import { type ReleaseToVerify, verify_release_provenance } from '../_lib/sigstore_provenance.js';
 import { read_candidate, unattended_decision, type RegistryCandidate } from '../_lib/unattended_gates.js';
 import type { InstallOrigin } from '../_lib/classify_update.js';
 import * as installed_lock from '../_lib/installed_lock.js';
@@ -97,10 +94,13 @@ export interface StepResult {
 
 export type Packument = { readonly ok: true; readonly doc: unknown } | { readonly ok: false; readonly reason: string };
 
+/** A verified tarball on disk, the only thing the install step may install — or why there is none. */
+export type Provenance = { readonly ok: true; readonly tarball: string } | { readonly ok: false; readonly reason: string };
+
 export interface UnattendedDeps {
     readonly fetchPackument: () => Promise<Packument>;
-    /** Refusal reason when the attestation does not tie to this package's publish workflow, else `null`. */
-    readonly verifyProvenance: (candidate: RegistryCandidate) => Promise<string | null>;
+    /** Download the candidate, verify its attestations against it, and hand back the verified file. */
+    readonly verifyProvenance: (candidate: RegistryCandidate) => Promise<Provenance>;
     readonly run: (cmd: string[]) => StepResult;
     /** The version recorded in `installed.lock`; `''` when unknown. */
     readonly readInstalled: () => string;
@@ -243,9 +243,10 @@ function release_lock(deps: Pick<UnattendedDeps, 'lockPath' | 'pid'>): void {
 
 // --- the run -----------------------------------------------------------------
 
-function install_steps(version: string, deps: UnattendedDeps): string[][] {
+/** `spec` is the verified tarball for an upgrade, and `<package>@<version>` only for a restore. */
+function install_steps(spec: string, deps: UnattendedDeps): string[][] {
     return [
-        ['npm', 'install', '-g', `${PACKAGE_NAME}@${version}`],
+        ['npm', 'install', '-g', spec],
         [deps.agentConfigBin, 'global', '--no-ui'],
         ...deps.globalSettings.map((target) => [deps.agentConfigBin, 'settings:sync', '--path', target]),
     ];
@@ -263,7 +264,7 @@ function run_steps(steps: string[][], deps: UnattendedDeps, honourSignal = true)
 
 /** Restored means both the binary and `installed.lock` read the previous version again. */
 function restore(previous: string, deps: UnattendedDeps): number {
-    const back = run_steps(install_steps(previous, deps).slice(0, 2), deps, false);
+    const back = run_steps(install_steps(`${PACKAGE_NAME}@${previous}`, deps).slice(0, 2), deps, false);
     const lock = deps.readInstalled();
     const binary = deps.readBinary();
     if (back.ok && lock === previous && binary === previous) {
@@ -279,7 +280,10 @@ function restore(previous: string, deps: UnattendedDeps): number {
     return EXIT_RESTORE_FAILED;
 }
 
-async function decide(installed: string, deps: UnattendedDeps): Promise<{ candidate: RegistryCandidate } | { refused: string[] }> {
+async function decide(
+    installed: string,
+    deps: UnattendedDeps,
+): Promise<{ candidate: RegistryCandidate; tarball: string } | { refused: string[] }> {
     const fetched = await deps.fetchPackument();
     if (!fetched.ok) return { refused: [`registry unavailable: ${fetched.reason}`] };
     const candidate = read_candidate(fetched.doc);
@@ -292,85 +296,89 @@ async function decide(installed: string, deps: UnattendedDeps): Promise<{ candid
         env: { ...deps.env, now: deps.now().toISOString() },
     });
     if (!decision.install) return { refused: [...decision.reasons] };
-    // 2.1's open half. `decision` accepted an attestation that EXISTS and
-    // carries an SLSA predicate; that document is producible by any workflow
-    // in any repository with `id-token: write`, so it is checked here against
-    // the one workflow this package publishes from before anything installs.
+    // `decision` accepted an attestation that EXISTS and carries an SLSA
+    // predicate, which any workflow with `id-token: write` can produce; the
+    // tarball is verified here against pinned roots before anything installs.
     const provenance = await deps.verifyProvenance(candidate);
-    if (provenance !== null) return { refused: [provenance] };
-    return { candidate };
+    if (!provenance.ok) return { refused: [provenance.reason] };
+    return { candidate, tarball: provenance.tarball };
 }
 
+/** Largest tarball the unattended path downloads; a release is about 16 MB. */
+export const MAX_TARBALL_BYTES = 64 * 1024 * 1024;
+
 /**
- * Fetch the attestation bundle, require it to name this package's publish
- * workflow, and require its DSSE signature to verify. Returns a refusal
- * reason, or `null` when both hold.
+ * Download the candidate's tarball, check it against the packument's integrity
+ * and against both attestations, and write exactly those bytes to a private
+ * temp file — the file the install step installs. Returns that file, or why
+ * there is none.
  *
- * **This used to say the signature half was `npm audit signatures` "in the
- * install step". It was not, and never had been** — `install_steps` runs
- * `npm install -g`, `agent-config global` and `settings:sync`, and no audit.
- * The sentence described a composition nobody wrote, which is the worst shape
- * a security note can have, so it is replaced by what the code does rather
- * than corrected in place.
+ * The bytes verified and the bytes installed are one buffer: installing by
+ * `<package>@<version>` would let the registry serve different bytes to the
+ * second request than to the first.
  *
- * What runs now: the payload is tied to the workflow, the envelope's signature
- * is verified against the certificate the bundle carries, and that
- * certificate's SAN is required to name the same workflow. What does NOT run:
- * any check of who ISSUED that certificate. The residue is the
- * `dsse-trust-root` blocker on the roadmap, and
- * `verify_attestation_signature`'s header states it in full.
- *
- * A bundle that cannot be fetched REFUSES rather than passing. Unlike the live
- * session register, there is no second independent gate behind this one: an
- * unreachable attestation is exactly what an attacker serving a tarball
- * without one produces, so failing open here would hand back the property the
- * check exists to establish.
+ * Every URL comes from the packument, so each must be on the registry's own
+ * origin; a hostile answer would otherwise choose both the host fetched and the
+ * document verified. A fetch that fails REFUSES rather than passing: an
+ * unreachable attestation is exactly what an attacker serving a tarball without
+ * one produces.
  */
 export async function verify_provenance_default(
     candidate: RegistryCandidate,
     fetch_impl: typeof fetch = fetch,
-    timeoutMs = 10_000,
-): Promise<string | null> {
-    if (candidate.attestationsUrl === null) {
-        return `${candidate.version} carries no attestation bundle to verify`;
+    timeoutMs = 60_000,
+    verify: (release: ReleaseToVerify) => Promise<string | null> = (r) => verify_release_provenance(r),
+): Promise<Provenance> {
+    const v = candidate.version;
+    const registry = new URL(PACKUMENT_URL).origin;
+    const refuse = (reason: string): Provenance => ({ ok: false, reason: `${v}: ${reason}` });
+    for (const [what, url] of [
+        ['attestation bundle', candidate.attestationsUrl],
+        ['tarball', candidate.tarballUrl],
+    ] as const) {
+        if (url === null) return refuse(`the registry names no ${what} to verify`);
+        let origin = '';
+        try {
+            origin = new URL(url).origin;
+        } catch {
+            // an unparsable URL is refused below like a foreign one
+        }
+        if (origin !== registry) return refuse(`the ${what} url is not on ${registry}`);
     }
-    // The URL comes from the packument, so a hostile registry answer would
-    // otherwise choose both the host fetched and the document verified.
-    let origin: string;
+    const integrity = /^sha512-([A-Za-z0-9+/=]+)$/.exec(candidate.integrity ?? '');
+    if (integrity === null) return refuse('the registry records no sha512 integrity for the tarball');
+
+    const get = async (url: string): Promise<Response> => {
+        const resp = await fetch_impl(url, { signal: AbortSignal.timeout(timeoutMs), redirect: 'error' });
+        if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
+        return resp;
+    };
+    let attestations: unknown;
+    let bytes: Buffer;
     try {
-        origin = new URL(candidate.attestationsUrl).origin;
-    } catch {
-        origin = '';
+        attestations = await (await get(candidate.attestationsUrl as string)).json();
+        const resp = await get(candidate.tarballUrl as string);
+        if (Number(resp.headers.get('content-length') ?? 0) > MAX_TARBALL_BYTES) return refuse('the tarball is larger than allowed');
+        bytes = Buffer.from(await resp.arrayBuffer());
+    } catch (err) {
+        return refuse(`download failed: ${err instanceof Error ? err.message : String(err)}`);
     }
-    if (origin !== new URL(PACKUMENT_URL).origin) {
-        return `${candidate.version}: attestation url is not on ${new URL(PACKUMENT_URL).origin}`;
+    if (bytes.length > MAX_TARBALL_BYTES) return refuse('the tarball is larger than allowed');
+    const digest = crypto.createHash('sha512').update(bytes).digest();
+    if (!digest.equals(Buffer.from(integrity[1] as string, 'base64'))) {
+        return refuse('the downloaded tarball does not match the integrity the registry records');
     }
-    let doc: unknown;
+    const reason = await verify({ version: v, tarballSha512Hex: digest.toString('hex'), attestations });
+    if (reason !== null) return refuse(reason);
+
     try {
-        const resp = await fetch_impl(candidate.attestationsUrl, {
-            signal: AbortSignal.timeout(timeoutMs),
-            headers: { accept: 'application/json' },
-            redirect: 'error',
-        });
-        if (!resp.ok) return `attestation fetch failed: HTTP ${resp.status}`;
-        doc = await resp.json();
+        const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-config-upgrade-'));
+        const tarball = path.join(dir, `agent-config-${v}.tgz`);
+        fs.writeFileSync(tarball, bytes, { mode: 0o600, flag: 'wx' });
+        return { ok: true, tarball };
     } catch (err) {
-        return `attestation fetch failed: ${err instanceof Error ? err.message : String(err)}`;
-    }
-    if (!provenance_matches_publish(doc)) {
-        const named = attestation_workflow_ref(doc);
-        return named === null
-            ? `${candidate.version} has no readable provenance workflow in its attestation`
-            : `${candidate.version} was built by ${named}, not ${EXPECTED_WORKFLOW_REF}`;
+        return refuse(`cannot write the verified tarball: ${err instanceof Error ? err.message : String(err)}`);
     }
-    // The payload says the right thing; this asks whether the payload is the
-    // one that was signed, and whether the certificate that signed it carries
-    // the same identity. It does NOT establish who issued that certificate —
-    // see `verify_attestation_signature`'s own note and the `dsse-trust-root`
-    // blocker, which is where the trust root is decided.
-    const signature = await verify_attestation_signature(doc);
-    if (signature !== null) return `${candidate.version}: ${signature}`;
-    return null;
 }
 
 /** Contexts where even the registry fetch and the lock file are side effects nobody asked for. */
@@ -397,14 +405,16 @@ export async function run_unattended(deps: UnattendedDeps): Promise<number> {
         say(deps.err, `${PREFIX}: not installing — ${locked}.`);
         return EXIT_REFUSED;
     }
+    let verified: string | null = null;
     try {
         const verdict = await decide(previous, deps);
         if ('refused' in verdict) {
             say(deps.out, `ℹ️  ${PREFIX}: not installing (installed: ${previous}) — ${verdict.refused.join('; ')}.`);
             return EXIT_REFUSED;
         }
+        verified = verdict.tarball;
         const target = verdict.candidate.version;
-        const steps = install_steps(target, deps);
+        const steps = install_steps(verified, deps);
         if (deps.activationBlocked !== null) {
             const how = deps.dryRun ? 'dry run: a real run would not install' : 'not installing';
             say(deps.out, `ℹ️  ${PREFIX}: every gate passed for ${target}, but ${how} — ${deps.activationBlocked}.`);
@@ -422,10 +432,13 @@ export async function run_unattended(deps: UnattendedDeps): Promise<number> {
         }
         const what = `${ran.cmd.join(' ')} (exit ${ran.result.rc})`;
         if (/\bEACCES\b/.test(ran.result.stderr)) {
+            // The verified file is removed when this run ends, so the command a
+            // person can still run names the version instead.
+            const manual = ran.cmd === steps[0] ? ['npm', 'install', '-g', `${PACKAGE_NAME}@${target}`] : ran.cmd;
             say(
                 deps.err,
                 `❌  ${PREFIX}: permission denied on ${what}. agent-config never runs sudo; ` +
-                    `run this yourself with the right permissions: ${ran.cmd.join(' ')}`,
+                    `run this yourself with the right permissions: ${manual.join(' ')}`,
             );
             // Denied on the very first write, npm changed nothing; any later step leaves a mixed install.
             const untouched = ran.cmd === steps[0] && deps.readInstalled() === previous && deps.readBinary() === previous;
@@ -435,6 +448,7 @@ export async function run_unattended(deps: UnattendedDeps): Promise<number> {
         say(deps.err, `❌  ${PREFIX}: step failed: ${what} — restoring ${previous}.`);
         return restore(previous, deps);
     } finally {
+        if (verified !== null) fs.rmSync(path.dirname(verified), { recursive: true, force: true });
         release_lock(deps);
     }
 }

package/src/scripts/_dispatch.bash

@@ -104,7 +104,8 @@ EOF
     cat <<'EOF'
 
 Tier 1 — power-user (release shape, audit, migration):
-  update                     Update the agent_config_version pin in .agent-settings.yml
+  update                     Pin agent_config_version in .agent-settings.yml; installs that
+                             version globally first when the global install is older
                              Flags: --check (read-only) | --to <version> (explicit pin)
   upgrade                    Install the latest @event4u/agent-config globally
                              (npm i -g) and refresh the global install + plugin.
@@ -227,7 +228,7 @@ Tier 2 — maintenance / internal (hooks, MCP, memory, telemetry):
   benchmark                  Report context-token reduction vs the full always-loaded
                              projection (from the pinned token baseline). Flags: --format
   code-graph                 Deterministic code-graph engine (ADR-124, Class A).
-                             Usage: code-graph build|validate|detect|query|explain|affected|path [options]
+                             Usage: code-graph build|refresh|map|validate|detect|query|explain|affected|path [options]
   sessions:list              List live agent sessions on this repository (shared
                              session register) PLUS the unmerged branches checked
                              out in other worktrees — the axis that needs no
@@ -1400,7 +1401,7 @@ cmd_use() {
 }
 
 # `agent-config update` — flip the agent_config_version pin in
-# .agent-settings.yml. See scripts/_cli/cmd_update.ts (P3.1 of
+# .agent-settings.yml, upgrading the global install first when it is older. See scripts/_cli/cmd_update.ts (P3.1 of
 # road-to-portable-runtime-and-update-check.md).
 cmd_update() {
   exec_ts "$PACKAGE_ROOT/src/scripts/_cli/cmd_update.ts" "$@"

package/src/scripts/_lib/confusables.ts

@@ -49,25 +49,6 @@ export const CONFUSABLE_FOREIGN: ReadonlySet<number> = new Set([
     0x03a1 /*Ρ→P*/, 0x03a4 /*Τ→T*/, 0x03a5 /*Υ→Y*/, 0x03a7 /*Χ→X*/, 0x0392 /*Β→B*/,
 ]);
 
-/**
- * The basic-Latin twin of each confusable foreign letter that has one, for a
- * detector that folds a lookalike back before matching. Every key is in
- * `CONFUSABLE_FOREIGN`, which a test holds.
- */
-export const LATIN_TWIN: ReadonlyMap<number, string> = new Map([
-    [0x0430, 'a'], [0x0435, 'e'], [0x043e, 'o'], [0x0440, 'p'], [0x0441, 'c'],
-    [0x0443, 'y'], [0x0445, 'x'], [0x0455, 's'], [0x0456, 'i'], [0x0458, 'j'],
-    [0x04bb, 'h'], [0x0501, 'd'], [0x051b, 'q'],
-    [0x0410, 'A'], [0x0412, 'B'], [0x0415, 'E'], [0x041a, 'K'], [0x041c, 'M'],
-    [0x041d, 'H'], [0x041e, 'O'], [0x0420, 'P'], [0x0421, 'C'], [0x0422, 'T'],
-    [0x0423, 'Y'], [0x0425, 'X'], [0x0405, 'S'], [0x0406, 'I'], [0x0408, 'J'],
-    [0x03b1, 'a'], [0x03b5, 'e'], [0x03bf, 'o'], [0x03bd, 'v'], [0x03c1, 'p'],
-    [0x03c5, 'u'], [0x03c7, 'x'], [0x03ba, 'k'],
-    [0x0391, 'A'], [0x0392, 'B'], [0x0395, 'E'], [0x0396, 'Z'], [0x0397, 'H'],
-    [0x0399, 'I'], [0x039a, 'K'], [0x039c, 'M'], [0x039d, 'N'], [0x039f, 'O'],
-    [0x03a1, 'P'], [0x03a4, 'T'], [0x03a5, 'Y'], [0x03a7, 'X'],
-]);
-
 type ScriptName = 'latin' | 'cyrillic' | 'greek' | 'other';
 
 function _script_of(ch: string): ScriptName {

package/src/scripts/_lib/egress_normalize.ts

@@ -8,9 +8,20 @@
  * back to the original offsets, so a replacement removes the disguised bytes
  * too. Pure: no I/O.
  */
-import { LATIN_TWIN } from './confusables.js';
 import { detect, EGRESS_RULES, type EgressRule, type EgressSpan } from './egress_rules.js';
 
+// Aligned: the n-th code point of FOREIGN, three hex digits each, folds to the
+// n-th letter of LATIN. Kept here, not in confusables.ts, so the engine chunk
+// does not carry that module's script regexes.
+const FOREIGN = '43043543e4404414434454554564584bb50151b41041241541a41c41d41e4204214224234254054064083b13b53bf3bd3c13c53c73ba39139239539639739939a39c39d39f3a13a43a53a7';
+const LATIN = 'aeopcyxsijhdqABEKMHOPCTYXSIJaeovpuxkABEZHIKMNOPTYX';
+
+/**
+ * The basic-Latin twin of each confusable foreign letter that has one. Every
+ * key is in `CONFUSABLE_FOREIGN` (confusables.ts), which a test holds.
+ */
+export const LATIN_TWIN: ReadonlyMap<number, string> = new Map([...LATIN].map((c, i) => [parseInt(FOREIGN.slice(i * 3, i * 3 + 3), 16), c]));
+
 /**
  * Invisible and bidirectional-control characters: soft hyphen, zero-width
  * marks, bidi embeddings and isolates, word joiners, the BOM and the Tag block.
@@ -19,17 +30,15 @@ export const HIDDEN_UNICODE_RE = /[­​-‏‪-‮⁠-⁤⁦-⁩\u{E0000}-\u
 
 export interface Normalized {
     readonly text: string;
-    /** For each UTF-16 unit of `text`, the original offsets of the character it came from. */
-    readonly originStart: readonly number[];
-    readonly originEnd: readonly number[];
+    /** For each UTF-16 unit of `text`, the original offset of the character it came from. */
+    readonly origin: readonly number[];
     readonly hidden: number;
     readonly folded: number;
 }
 
 export function normalizeForDetection(text: string): Normalized {
-    const out: string[] = [];
-    const originStart: number[] = [];
-    const originEnd: number[] = [];
+    let out = '';
+    const origin: number[] = [];
     let hidden = 0;
     let folded = 0;
     let at = 0;
@@ -38,30 +47,51 @@ export function normalizeForDetection(text: string): Normalized {
         if (HIDDEN_UNICODE_RE.test(ch)) {
             hidden += 1;
         } else {
-            const twin = LATIN_TWIN.get(ch.codePointAt(0) as number);
-            if (twin !== undefined) folded += 1;
-            const emit = twin ?? ch;
-            for (let k = 0; k < emit.length; k += 1) {
-                originStart.push(at);
-                originEnd.push(at + ch.length);
-            }
-            out.push(emit);
+            const emit = LATIN_TWIN.get(ch.codePointAt(0) as number) ?? ch;
+            if (emit !== ch) folded += 1;
+            out += emit;
+            for (let k = 0; k < emit.length; k += 1) origin.push(at);
         }
         at += ch.length;
     }
-    return { text: out.join(''), originStart, originEnd, hidden, folded };
+    return { text: out, origin, hidden, folded };
+}
+
+export interface NormalizedDetection {
+    readonly spans: EgressSpan[];
+    /**
+     * An extent reader such as a rule's `through`, applied to the text the spans
+     * were found in, with its end in original offsets. A disguised END marker is
+     * then seen by the reader exactly as the disguised BEGIN was by the rule.
+     */
+    end<S extends EgressSpan>(span: S, read: (text: string, span: S) => number | null): number | null;
 }
 
 /**
  * `detect`, run on the normalised text with spans in original offsets. With no
  * invisible or confusable character the result is `detect(text)` exactly.
  */
-export function detectNormalized(text: string, rules: readonly EgressRule[] = EGRESS_RULES): EgressSpan[] {
+export function detectWithExtent(text: string, rules: readonly EgressRule[] = EGRESS_RULES): NormalizedDetection {
     const n = normalizeForDetection(text);
-    if (n.hidden === 0 && n.folded === 0) return detect(text, rules);
-    return detect(n.text, rules).map((s) => ({
-        ...s,
-        start: n.originStart[s.start] as number,
-        end: n.originEnd[s.end - 1] as number,
-    }));
+    if (n.hidden === 0 && n.folded === 0) return { spans: detect(text, rules), end: (s, read) => read(text, s) };
+    const back = (i: number): number => {
+        const o = n.origin[i - 1] as number;
+        return o + ((text.codePointAt(o) as number) > 0xffff ? 2 : 1);
+    };
+    const fwd = (o: number): number => {
+        let i = 0;
+        while (i < n.origin.length && (n.origin[i] as number) < o) i += 1;
+        return i;
+    };
+    return {
+        spans: detect(n.text, rules).map((s) => ({ ...s, start: n.origin[s.start] as number, end: back(s.end) })),
+        end: (s, read) => {
+            const e = read(n.text, { ...s, start: fwd(s.start), end: fwd(s.end) });
+            return e === null ? null : back(e);
+        },
+    };
+}
+
+export function detectNormalized(text: string, rules: readonly EgressRule[] = EGRESS_RULES): EgressSpan[] {
+    return detectWithExtent(text, rules).spans;
 }

package/src/scripts/_lib/egress_rules.ts

@@ -133,12 +133,18 @@ export interface AssignmentShape {
     readonly gap?: string;
 }
 
-/** Source of a keyword-assignment shape: keyword group, operator, then the consumer's value. */
+/**
+ * Source of a keyword-assignment shape: keyword group, operator, then the consumer's value.
+ * Not an assignment: `===` (strict equality), `==` followed by whitespace (a spaced
+ * comparison) and `=>` (an arrow) — read as one, `token === 'x'` yielded the value `==` and
+ * the council bundle refused every later `==`. A shell `name==value` stays an assignment,
+ * and its second `=` belongs to the operator, so the value read is `value`, never a lone `=`.
+ */
 export function assignmentSource(shape: AssignmentShape): string {
     const alt = shape.keywords.map((k) => ASSIGNMENT_KEYWORDS[k]).join('|');
     const group = shape.capture === true ? `(${alt})` : `(?:${alt})`;
     const gap = shape.gap ?? '\\s*';
-    const head = `${shape.before ?? ''}${group}${shape.after ?? ''}${gap}[:=]`;
+    const head = `${shape.before ?? ''}${group}${shape.after ?? ''}${gap}(?::|=(?!==|=\\s|>)=?)`;
     return shape.value === undefined ? head : `${head}${gap}${shape.value}`;
 }
 

package/src/scripts/_lib/egress_text.ts

@@ -3,7 +3,8 @@
 // (`egress_engine.ts`, D9), so the stage keeps the field walk and the chunk
 // keeps everything that reads a rule.
 
-import { detect, EGRESS_RULES, type EgressClass } from './egress_rules.js';
+import { detectWithExtent } from './egress_normalize.js';
+import { EGRESS_RULES, type EgressClass } from './egress_rules.js';
 import { EgressRefusedError, replaceValues, type TokenScope } from './egress_token.js';
 
 const RULE_BY_ID = new Map(EGRESS_RULES.map((r) => [r.rule, r]));
@@ -19,10 +20,11 @@ export interface TextTally {
 export function tallyText(text: string): TextTally {
     const found: Array<{ class: EgressClass; type: string }> = [];
     const refused: string[] = [];
-    for (const span of detect(text)) {
+    const at = detectWithExtent(text);
+    for (const span of at.spans) {
         const policy = RULE_BY_ID.get(span.rule)?.replacement;
         if (policy !== undefined && policy !== 'detection') {
-            const end = policy.through(text, span);
+            const end = at.end(span, policy.through);
             if (end === null || end < span.end) {
                 refused.push(span.rule);
                 continue;

package/src/scripts/_lib/egress_token.ts

@@ -5,7 +5,8 @@
 
 import { createHmac, randomBytes } from 'node:crypto';
 
-import { detect, EGRESS_RULES, type EgressClass, type EgressSpan, replaceSpans } from './egress_rules.js';
+import { detectWithExtent, type NormalizedDetection } from './egress_normalize.js';
+import { EGRESS_RULES, type EgressClass, type EgressSpan, replaceSpans } from './egress_rules.js';
 
 export const TOKEN_FP_LENGTH = 6;
 
@@ -209,12 +210,12 @@ const RULE_BY_ID = new Map(EGRESS_RULES.map((r) => [r.rule, r]));
 const CLASS_RANK: Readonly<Record<EgressClass, number>> = { credential: 1, identifier: 0 };
 
 /** The bytes each detection obliges a replacement to remove; overlapping extents merge. */
-function replacementSpans(text: string, detected: readonly EgressSpan[]): EgressSpan[] {
+function replacementSpans(detected: readonly EgressSpan[], at: NormalizedDetection): EgressSpan[] {
     const extents = detected.map((s) => {
         const policy = RULE_BY_ID.get(s.rule)?.replacement;
         if (policy === undefined) throw new EgressRefusedError(s.rule);
         if (policy === 'detection') return s;
-        const end = policy.through(text, s);
+        const end = at.end(s, policy.through);
         if (end === null || end < s.end) throw new EgressRefusedError(s.rule);
         return { ...s, end };
     });
@@ -243,8 +244,9 @@ function replacementSpans(text: string, detected: readonly EgressSpan[]): Egress
  */
 export function replaceValues(text: string, scope: TokenScope): string {
     const owned = parseTokens(text).filter((t) => scope.owns(text.slice(t.start, t.end)));
-    const detected = detect(text).filter((s) => !owned.some((t) => t.start <= s.start && s.end <= t.end));
-    const spans = replacementSpans(text, detected);
+    const at = detectWithExtent(text);
+    const detected = at.spans.filter((s) => !owned.some((t) => t.start <= s.start && s.end <= t.end));
+    const spans = replacementSpans(detected, at);
     // Mint in text order first: replaceSpans substitutes right to left, and minting
     // inside its callback would number the last value 1.
     const tokens = spans.map((s) => scope.mint(s.type, s.class, text.slice(s.start, s.end)));