@sema-agent/server 7.141.0 → 7.143.0

package/dist/trace/model-segment.js

@@ -1,4 +1,9 @@
-import { reasoningEndEventData } from "./project.js";
+import { recordFailOpen } from "../observability/fail-open.js";
+import { errorKindOf } from "../observability/err-text.js";
+import { OVERSIZED_REDACTION_PLACEHOLDER } from "../observability/run-terminal.js";
+import { liveIdentityFields, reasoningEndEventData, textEndEventData } from "./project.js";
+import { dropProjectedFace } from "./projection-drop.js";
+import { createRedactionStream } from "./redact.js";
 const BOUNDARY = new Set([
     "tool_start", "tool_end", "status", "context_usage", "compacted", "diagnostics",
     "steering_injected", "compaction_outcome", "workspace_changed", "wiring_manifest",
@@ -14,9 +19,8 @@ export function reasoningSegmentEventId(anchor) {
 export function reasoningDeltaBytes(ev) {
     return typeof ev.delta === "string" && ev.delta !== "" ? ev.delta : undefined;
 }
-export function reasoningStreamOfTask(...ids) {
-    const set = new Set(ids.filter((v) => typeof v === "string" && v !== ""));
-    return (ident) => (ident.sourceTaskId !== undefined && set.has(ident.sourceTaskId)) || (ident.bgAgentId !== undefined && set.has(ident.bgAgentId));
+export function modelStreamOfTask(taskId) {
+    return (ident) => ident.sourceTaskId === taskId || ident.bgAgentId === taskId;
 }
 function streamKeyOf(ident) {
     return `${ident.parentToolCallId ?? ""}\u0000${ident.sourceTaskId ?? ""}\u0000${ident.bgAgentId ?? ""}`;
@@ -25,44 +29,108 @@ function identOf(ev) {
     const s = (v) => (typeof v === "string" ? v : undefined);
     return { parentToolCallId: s(ev.parentToolCallId), sourceTaskId: s(ev.sourceTaskId), bgAgentId: s(ev.bgAgentId) };
 }
-export function createReasoningSegments() {
-    const open = new Map();
-    const cutKey = (key) => {
-        const seg = open.get(key);
-        if (seg === undefined)
+function release(s) {
+    try {
+        return s.text.takeSettled();
+    }
+    catch (err) {
+        recordFailOpen("server.run-terminal.redact-threw", `live-hold len=${s.text.fed.length} err=${errorKindOf(err)}`);
+        return "";
+    }
+}
+function remainderOf(family, s) {
+    try {
+        const r = s.text.flush();
+        if (r.diverged)
+            recordFailOpen("server.live-text.hold-diverged", `family=${family} len=${s.text.fed.length}`);
+        return r.rest;
+    }
+    catch (err) {
+        recordFailOpen("server.run-terminal.redact-threw", `live-hold len=${s.text.fed.length} err=${errorKindOf(err)}`);
+        return OVERSIZED_REDACTION_PLACEHOLDER;
+    }
+}
+export function createLiveModelText() {
+    const open = { text: new Map(), reasoning: new Map() };
+    const deltaType = (family) => (family === "text" ? "text_delta" : "reasoning_delta");
+    const close = (family, key, deliver) => {
+        const s = open[family].get(key);
+        if (s === undefined)
+            return [];
+        open[family].delete(key);
+        if (!deliver)
             return [];
-        open.delete(key);
-        const data = reasoningEndEventData({ ...seg.ident, eventId: seg.segmentEventId, content: seg.buf });
-        return data === null ? [] : [{ type: "reasoning_end", ...data }];
+        if (!s.delivering)
+            s.text.skip();
+        const out = [];
+        const rest = remainderOf(family, s);
+        if (rest !== "")
+            out.push({ type: deltaType(family), delta: rest, ...liveIdentityFields(s.ident) });
+        if (family === "reasoning") {
+            const data = reasoningEndEventData({ ...s.ident, eventId: s.segmentEventId, content: s.text.fed });
+            if (data !== null)
+                out.push({ type: "reasoning_end", ...data });
+        }
+        return out;
+    };
+    const feed = (family, ev, deliver) => {
+        if (typeof ev.delta !== "string") {
+            if (family === "text")
+                dropProjectedFace("text_delta.delta is not a string");
+            else
+                dropProjectedFace("reasoning_delta.delta is not a string");
+            return [];
+        }
+        const ident = identOf(ev);
+        const key = streamKeyOf(ident);
+        let s = open[family].get(key);
+        if (s === undefined && ev.delta !== "") {
+            s = { ident, text: createRedactionStream(), delivering: deliver };
+            open[family].set(key, s);
+        }
+        if (s !== undefined) {
+            if (deliver && !s.delivering) {
+                s.delivering = true;
+                s.text.skip();
+            }
+            else if (!deliver)
+                s.delivering = false;
+            s.text.feed(ev.delta);
+            if (family === "reasoning" && reasoningDeltaBytes(ev) !== undefined)
+                s.segmentEventId ??= reasoningSegmentEventId(ev.eventId);
+        }
+        if (!deliver)
+            return [];
+        return [{ type: deltaType(family), delta: s === undefined ? "" : release(s), ...liveIdentityFields(ev) }];
     };
     return {
-        onEvent: (ev) => {
-            if (ev.type === "reasoning_delta") {
-                const bytes = reasoningDeltaBytes(ev);
-                if (bytes === undefined)
-                    return [];
-                const ident = identOf(ev);
-                const key = streamKeyOf(ident);
-                const seg = open.get(key);
-                if (seg === undefined)
-                    open.set(key, { ident, segmentEventId: reasoningSegmentEventId(ev.eventId), buf: bytes });
-                else {
-                    seg.buf += bytes;
-                    seg.segmentEventId ??= reasoningSegmentEventId(ev.eventId);
-                }
-                return [];
+        onEvent: (ev, deliver = true) => {
+            if (ev.type === "text_delta")
+                return feed("text", ev, deliver);
+            if (ev.type === "reasoning_delta")
+                return feed("reasoning", ev, deliver);
+            const key = streamKeyOf(identOf(ev));
+            if (ev.type === "text_end") {
+                const out = close("text", key, deliver);
+                const end = deliver ? textEndEventData(ev) : null;
+                if (end !== null)
+                    out.push({ type: "text_end", ...end });
+                return out;
             }
-            return isModelSegmentBoundary(ev.type ?? "") ? cutKey(streamKeyOf(identOf(ev))) : [];
+            return isModelSegmentBoundary(ev.type ?? "") ? [...close("text", key, deliver), ...close("reasoning", key, deliver)] : [];
         },
-        cut: (match) => {
+        cut: (match, deliver = true) => {
             const out = [];
-            for (const [key, seg] of [...open]) {
-                if (match !== undefined && !match(seg.ident))
-                    continue;
-                out.push(...cutKey(key));
+            for (const family of ["text", "reasoning"]) {
+                for (const [key, s] of [...open[family]]) {
+                    if (match !== undefined && !match(s.ident))
+                        continue;
+                    out.push(...close(family, key, deliver));
+                }
             }
             return out;
         },
+        isIdle: () => open.text.size === 0 && open.reasoning.size === 0,
     };
 }
 //# sourceMappingURL=model-segment.js.map

package/dist/trace/project.d.ts

@@ -30,7 +30,7 @@ import type { RunCompanionRecord } from "../observability/prompt-manifest.js";
 import { type SafeText } from "./exit-seat.js";
 import { type SemaProvenanceInput } from "./sema-provenance.js";
 import { type ExtensionRequesterFace, type ToolInputRewriteFace } from "./extension-call-face.js";
-import type { LedgerEventType } from "./ledger-events.js";
+import type { LedgerEventType, ParkLedgerEventType } from "./ledger-events.js";
 import type { InstructionsSegment } from "../instruction-selection.js";
 import type { RunSkillEntry } from "../capabilities/skills.js";
 /** 账本写口的统一签名 —— `type` 是**闭集**(`ledger-events.ts`):新型必须先登记,否则调用点编译红
@@ -222,8 +222,8 @@ export declare function screenedStoredEventData(type: string, data: unknown): un
 /** `text_end` 段末帧的**唯一**铸点(三腿共用:top stream / 转发子代腿 / 子代 tail 面)。content = 段权威全文 ⇒ 与
  *  durable 面(`result` / 账本 `text` 行)同一只 {@link redactModelText}(认出才改写、抛则占位、不设上限)。
  *  此前三处各自逐字透传 —— 同一份文本毫秒后在 `done.result.result` 上已脱,live 面却在凭据生成瞬间明文([ref])。
- *  `text_delta` 仍逐字:跨 chunk 的凭据无法就地判;clay [ref] ②(2026-09-18)裁定**维持逐字成文**([ref] U-3 关票),
- *  权威段 `text_end.content` 已脱敏、消费端段末整段替换即得脱敏读法。
+ *  逐块的 `text_delta` 由 `trace/model-segment.ts` 的登记册铸(7.143.0 起经同一只脱敏器的放行窗,一段的逐块拼接 = 本帧 content);
+ *  本函数由登记册在段末调,三腿不再各自调。
  *  坏形(content 非串/空串)⇒ null(丢帧,不铸「权威空段」:core 契约明言空段不发本帧,消费端收到空段会清掉已攒 delta)。
  *  身份**四键**随行(live 现状带全四键,消费端可能已依赖);值经 {@link identityKey} —— 非空 string 才上 wire
  *  ([ref] 起不再逐字透传:坏形身份键会在 live 写口上铸出假游标)。 */
@@ -419,6 +419,23 @@ export interface ParkEventData {
  * 门身份读法与三处 durable 读面同一只(`durableRowIdentity`,face `run-events-park`):没有暂停因由的行不问身份(没有门可认);有因由而读不出 ⇒ 键缺席 + 计一次。
  */
 export declare function parkEventData(result: unknown, reopened?: string | null): ParkEventData;
+/** 一腿的计量席:E8 累加器 + 这条腿在累加器里的归因键。`modelUsage` 缺席 ⇒ 这条腿没接累加器,没有用量可结。 */
+export interface ModelUsageSeat {
+    readonly modelUsage: ModelUsageTracker | undefined;
+    readonly taskId: string;
+}
+/**
+ * park 账本行的**唯一写口** —— {@link parkEventData} 是行的唯一构造器,本函数是它的唯一落账处:后台腿与同步 detach 腿(`LedgerSink.appendParked`)、
+ * 续跑腿的再停两臂、重开臂与续跑 verify 臂(`resume-legs.ts`)都经这一只。
+ *
+ * **状态帧最后**:一腿账本的状态帧(终局 `done` / `failed`、停驻 `suspended` / `needs_review`)是这一腿主线写下的最后一帧(晚到的子代转发帧、完成后的 suggestions 是旁路写,不在此列),计量帧先于它写出 ——
+ * 终局由 {@link attachModelUsage} 先结清最后一拍再落 `done`,停驻由本函数先 drain 再落停驻行。顺序属于写口、不属于调用点:
+ * 只回结果的 verify 腿没有逐 turn 落账的流(无 `turn_end` 帧),挂起前的用量只有停驻这一拍才落账;若各调用点各自记得「先结清」,
+ * 这条腿的账本尾帧就会是 `model_usage`,与不带 `verify` 的停驻(用量在 `turn_end` 就结清了)两形不同序(`GET /v1/runs/:id/events` 的尾帧)。
+ * 用量行落不下 ⇒ 停驻行**照落**,然后把用量行的失败抛给调用方(失败语义与此前逐字同:账本里有停驻帧、调用方按「停驻没落定」收场 —— bg 腿以 `failed` 收、手里的卡作废;
+ * 尽力而为的调用点(detach 腿的兜底停驻、续跑腿的重开臂)照旧吞掉它,停驻帧不因为一笔用量行的失败而缺席)。顺序变了,谁来写、写不下谁抛没有变。
+ */
+export declare function appendParkRow(append: AppendFn, usage: ModelUsageSeat | undefined, word: ParkLedgerEventType, result: unknown, reopened?: string | null): Promise<void>;
 /**
  * The `task_started` payload(core 7.50.0):一只委派子代**起跑**的那一帧 —— 每周期一只(首派 / 复活;耐久续跑腿不铸),
  * 序在子代的 `wiring_manifest` 之后、它的首个 `task_progress` 与首次模型请求之前。
@@ -620,6 +637,7 @@ export declare function compactionOutcomeEventData(ev: {
     trigger?: unknown;
     reason?: unknown;
     pass?: unknown;
+    requestedBy?: unknown;
     eventId?: unknown;
     parentToolCallId?: unknown;
 }): FrameData<{
@@ -870,8 +888,8 @@ export declare function toolRosterDeltaEventData(ev: {
  * (值可以是 `undefined`)—— 漏递的腿当场 tsc 红,而不是静默投出一个「缺席」(缺席在 wire 上是一句话:「这条腿对这件事没有陈述」)。
  *  · `instructions`([ref],7.111.0)—— 这条腿的 project-memory loader 选中的指令文件链成员 `{ selected: string[] }`;值来自腿的
  *    `InstructionSelectionLeg.segment()`。`undefined` ⇒ 段缺席;`{ selected: [] }` ⇒ 显式空(走了链、没选中)。
- *  · `skills`(7.137.0)—— 这条 run 交给引擎的技能名册(`{ name, description, source }[]`,与场景卡技能清单同一张形);值来自 spec 字段 `runSkillsOf(spec)`
- *    (唯一铸点 = resolveSpec 出口的 `buildRunSkills`)。**run 级** ⇒ 只投根腿 / 续跑腿的帧,委派子代的帧(`parentToolCallId` 在场)不投(子代的技能由它自己的定义决定);
+ *  · `skills`(7.137.0)—— 这条 run 交给引擎的技能名册(`{ name, description, source }[]`,与场景卡技能清单同一张形);值来自这条腿的部署事实 `LegFacts.skills`
+ *    (`leg-facts.ts`;名册由 `buildRunSkills` 合并、resolveSpec 出口登记,漏斗在复制之前读出)。**run 级** ⇒ 只投根腿 / 续跑腿的帧,委派子代的帧(`parentToolCallId` 在场)不投(子代的技能由它自己的定义决定);
  *    `[]` = 零技能(含 `disableSkills`);`undefined` ⇒ 段缺席(这条腿的 spec 不是本仓装配的)。`description` 过上 wire 的自由文本出口 {@link sanitizeWireText}。
  */
 export interface LegWiringSections {
@@ -1059,6 +1077,8 @@ export declare function compactedEventData(ev: {
     };
     /** [ref](core 7.53.0 [ref]):这次落地的压缩 pass 的 id —— 与它的 `compaction_started` 帧同一个值(引擎在每次落地上都设;型上可选)。逐字。 */
     pass?: string;
+    /** core 7.61.0:扩展经 `$.session.compact` 提的手动请求落地的那一 pass —— 谁要的(同 {@link compactionOutcomeEventData} 那一位)。 */
+    requestedBy?: unknown;
 }): FrameData<{
     attachedFiles?: Array<{
         path: SafeText;

package/dist/trace/project.js

@@ -317,6 +317,22 @@ export function parkEventData(result, reopened) {
         ...(reopened !== undefined ? { reopened } : {}),
     };
 }
+export async function appendParkRow(append, usage, word, result, reopened) {
+    let drainFailed = false;
+    let drainFailure;
+    if (usage !== undefined) {
+        try {
+            await appendModelUsageDelta(append, usage.modelUsage, usage.taskId);
+        }
+        catch (e) {
+            drainFailed = true;
+            drainFailure = e;
+        }
+    }
+    await append(word, parkEventData(result, reopened));
+    if (drainFailed)
+        throw drainFailure;
+}
 export function taskStartedEventData(ev) {
     return {
         taskId: ev.taskId,
@@ -418,9 +434,14 @@ export function compactionOutcomeEventData(ev) {
         ...(s(ev.trigger) !== undefined ? { trigger: s(ev.trigger) } : {}),
         ...(ev.reason !== undefined ? { reason: seatText("trace-frame-text", String(ev.reason)) } : {}),
         ...(s(ev.pass) !== undefined ? { pass: s(ev.pass) } : {}),
+        ...requestedByField(ev.requestedBy, "compaction_outcome"),
         ...identityFields(ev),
     };
 }
+function requestedByField(v, where) {
+    const requester = extensionRequesterOf(v, where);
+    return requester !== undefined ? { requestedBy: requester } : {};
+}
 export function compactionStartedEventData(ev) {
     const s = (v) => (typeof v === "string" ? v : undefined);
     return {
@@ -877,6 +898,7 @@ export function compactedEventData(ev) {
         ...(num(ev.durationMs) !== undefined ? { durationMs: num(ev.durationMs) } : {}),
         ...(phaseDurations !== undefined ? { phaseDurations } : {}),
         ...(typeof ev.pass === "string" ? { pass: ev.pass } : {}),
+        ...requestedByField(ev.requestedBy, "compacted"),
     };
 }
 export function contextUsageEventData(ev) {

package/dist/trace/redact.d.ts

@@ -36,6 +36,8 @@ export declare function armPoolBudgetForTest(): {
     ssh2ScanBytes: number;
     mappedUnits: number;
     readings: number;
+    coverageVisits: number;
+    rowVisits: number;
 };
 export declare function resetArmPoolBudgetForTest(): void;
 /**
@@ -54,11 +56,9 @@ export declare function resetArmPoolBudgetForTest(): void;
  * 闭集:加一个档而不在 {@link armPool} 的档表里处置 ⇒ **编译**红。
  */
 type RedactionScope = "free-text" | "bounded-unit";
-/** 测试座:{@link unitCountWithin} 的数组形(`table` 须是合法的已并表:升序、两两不交不相接)。 */
-export declare function unitCountWithinForTest(table: ReadonlyArray<readonly [number, number]>, from: number, to: number, max: number): boolean;
 /** 本模块会写进文本的全部替换 token(`«…»` 字面),从三张表现算 —— 表改这里自动跟,不另抄一份。
  *  🔴 **[ref] v2 修复轮起它只剩一个语义:闭形闭集的加载期校验**。运行期「这一段是不是一枚记号」已经由
- *  {@link credentialSpans} 的闭**形**那一支一处答完({@link opaqueUnitEnd}),按闭**集**再认一遍的
+ *  记号行的闭**形**一处答完({@link tokenUnits} / {@link tokenEnd}),按闭**集**再认一遍的
  *  `redactionTokenEndAt` 与它同义而更窄,已删 —— 两只「什么算记号」的判别器就是两个定义。 */
 /** {@link buildDisplaySafeUrl} 解析不动一个配置型 URL 时的**占位**([ref] 件B)——fail-closed:输出**不含原串的
  *  任何字节**(连 host 都不留),不许回落成原值。它不是任何一条臂的产物,所以要在这里**显式**进闭集
@@ -70,17 +70,22 @@ export { DISPLAY_SAFE_URL_TOKEN };
 /**
  * 🔴 **取证相的重扫模式(测试座,[ref])** —— 生产恒 `"incremental"`;`"full"` 是**参照语义** = 「没有可复用的上一次执行」:
  * 每级全部取证臂整段重跑、URL 臂每段重扫,既不读足迹也不回放(池把每一级的脏区间当作「未知」交下去,与级 0 同一个读法)。
- * 证据表的建法(级 0 记号档 + 逐级折入)与收敛判据(脏区间为空)两种模式是同一条,所以两种模式只差「复用与否」这一位 ——
- * 增量重扫的全部正确性主张只有一句:**任何输入上两种模式输出逐字相同**(`test/forensic-incremental-rescan.test.ts` 并跑比对;
- * 折入本身与整表重建的对拍是那个测试文件里的一份测试本地参照)。
+ * 证据表的建法(级 0 记号 + 逐级折入)与收敛判据(脏区间为空)两种模式是同一条,所以两种模式只差「复用与否」这一位 ——
+ * 增量重扫的全部正确性主张只有一句:**任何输入上两种模式输出逐字相同**(`test/forensic-incremental-rescan.test.ts` 并跑比对)。
  */
 export type ForensicRescanMode = "incremental" | "full";
 export declare function setForensicRescanModeForTest(mode: ForensicRescanMode): void;
-/** 测试座:折入函数的数组形(`prev` 须是合法的已并表:升序、两两不交不相接)。 */
-export declare function credentialSpansFoldForTest(prev: ReadonlyArray<readonly [number, number]>, add: ReadonlyArray<readonly [number, number]>): {
-    next: Array<[number, number]>;
+/** 测试座:折入函数的数组形(行 = `[起点, 终点, 族码, 锚位, 收尾位]`)。 */
+export declare function evidenceRowsFoldForTest(prev: ReadonlyArray<readonly [number, number, number, number, number]>, add: ReadonlyArray<readonly [number, number, number, number, number]>): {
+    next: Array<[number, number, number, number, number]>;
     dirty: Array<[number, number]>;
 };
+/** 测试座:{@link measureWithin} 的数组形(`table` 的每一项是一行 `[起点, 终点]` 或 `[起点, 终点, 键]`:不给键 ⇒ 键 = 起点;同一 (起点, 键) 至多一行;
+ *  `self` 给出 ⇒ 读者 = 键为它的那些行,否则不排除任何读数)。 */
+export declare function unitCountWithinForTest(table: ReadonlyArray<readonly [number, number] | readonly [number, number, number]>, from: number, to: number, max: number, self?: number): boolean;
+/** 测试座:同一张表上依次问一串量问(`[from, to, max, self?]`;读法同 {@link unitCountWithinForTest})—— 终点有界的闭包链缓存在问与问之间共用,
+ *  生产里同一级、同一张表上各臂各读者的量问就是这样串起来的。 */
+export declare function unitCountsWithinForTest(table: ReadonlyArray<readonly [number, number] | readonly [number, number, number]>, queries: ReadonlyArray<readonly [number, number, number, number | undefined]>): boolean[];
 /** 🧪 结构读数(与 {@link ppkScanBytesForTest} 同一条技法):本扫描器读过的单元数,线性钉用。 */
 export declare function anchoredScanUnitsForTest(): number;
 export declare function resetAnchoredScanUnitsForTest(): void;
@@ -226,6 +231,53 @@ export type RedactionSpan = {
 };
 export type { RedactionScope };
 export declare function proposeRedactionSpans(text: string, scope: RedactionScope, layout: RedactionLayout, extent: RedactionExtent): readonly RedactionSpan[];
+/**
+ * 🔴 **未决尾的长度上界**(读法单元):一段还在长的文本,末尾这么多个读法单元里起头的候选,本脱敏器**还判不了**(判定要读到文本之外)。
+ * 它不是另立的常数,是候选池成员表的同一份读数 —— 每条臂的**判定距离**取最大({@link MemberIdentity.reach} 的意义见那里):正则臂从正则源读出
+ * (前缀 + 前瞻判据 + 值 run 的最少重复;熵谓词 {@link ENTROPY_SCAN_MAX} 两窗由此进来),手写扫描器陈述它起头要读全的字面锚。
+ * 判定在**无界**远处的结构(没收尾的 JSON 串值 / URL userinfo / 栅栏 / 带引号的值、起头不设长度上界的栅栏行 / 版本头 / 关键字分隔段)不靠它:
+ * head 读法把它们读成未决尾、从起点遮到文本末尾({@link RedactionExtent}),流式口在它的起点前停下,直到它判定或冲刷。
+ * 加一条判定距离更远的臂,这个数随之变大(钉 `test/live-model-text-hold-law.test.ts` 读每条成员的读数与最大值)。
+ */
+export declare const PENDING_TAIL_UNITS: number;
+/** 测试可见:正则臂判定距离的读法本身(读得出的几形与加载期抛的几形)。 */
+export declare function regexDecisionReachForTest(re: RegExp, lexical: boolean): number;
+/** 测试可见:候选池每条成员的判定距离(成员的替换串、池序、读数)。 */
+export declare function pendingTailReachForTest(): ReadonlyArray<{
+    readonly token: string;
+    readonly order: number;
+    readonly reach: number;
+}>;
+/**
+ * 🔴 **流式口 —— 同一只脱敏器的三口**(live 面逐块到达的模型文本 `text_delta` / `reasoning_delta` 的唯一放行器;登记册在 `trace/model-segment.ts`)。
+ * 同一只 {@link runRedaction}、同一张表,只多一件事:知道文本还在长。
+ *  · **喂入**({@link RedactionStream.feed}):原文追加进本段;
+ *  · **取已判定前缀**({@link RedactionStream.takeSettled}):从上次取到的位置起,已判定的那一截的脱敏读法 —— head 读法,出门区终点 = 末尾 {@link PENDING_TAIL_UNITS}
+ *    个读法单元之前;切点再退到横跨它的那一条跨度的起点(一枚可能还在长、或判定在更远处的凭据整条不出)与码点边界。按重扫节律({@link streamRescanStep})才真扫;
+ *  · **收尾冲刷**({@link RedactionStream.flush}):整段读法交出其余字节,并核对已取出的字节在整段读法下是不是同一份。
+ * 律:各次取出依次拼接 + 冲刷 = 整段读法(`redactSecrets(全段)`)逐字节 —— 只喂一次再冲刷就是整段口本身。前提是 {@link PENDING_TAIL_UNITS} 读对了每条臂的判定距离;
+ * 读错的那一形在冲刷时现形(`diverged`),调用方响亮留痕。
+ * 延迟上界:一个字节在它之后又到 {@link PENDING_TAIL_UNITS} 个读法单元之后的下一次重扫时交出;盖住它的跨度判定之前(或冲刷之前)不交出。
+ * 不喂观察者(`observe:false`,与影子重扫同口):命中只在段末那一次整段脱敏里计(段末帧的铸点),逐块重扫不重复计数。扫描器抛 ⇒ 原样抛(放行位不动)。
+ */
+export interface RedactionStream {
+    /** 喂入下一块原文。 */
+    feed(chunk: string): void;
+    /** 取已判定前缀(可为 `""`)。 */
+    takeSettled(): string;
+    /** 收尾冲刷:其余字节的整段读法 + 已取出的字节与整段读法对不对得上。冲刷之后本流不再用。 */
+    flush(): {
+        readonly rest: string;
+        readonly diverged: boolean;
+    };
+    /** 跳过:已喂入的字节不再交出(没有收件人;tail 面没人在听时),之后的判定仍按整段上下文。 */
+    skip(): void;
+    /** 已喂入的整段原文。 */
+    readonly fed: string;
+}
+export declare function createRedactionStream(): RedactionStream;
+/** 测试可见:同一只流式口,未决尾按调用方给的数(比 {@link PENDING_TAIL_UNITS} 小 ⇒ 律被打破的那一形,冲刷时 `diverged` 现形 —— 响亮臂的触发器;生产调用方只有上面那一只)。 */
+export declare function createRedactionStreamWithTailForTest(units: number): RedactionStream;
 /**
  * 🔴 环 + 深度预算(2026-07-25 补)。原实现是纯递归、**既不记已访问节点也不限深度**,而它的调用位置是
  * **最不可信的边界**:`toolStart`/`toolEnd` 把工具的 `args`/`output`/`structured` 直接喂进来。后果两条: