@sema-agent/server 7.133.0 → 7.135.0

package/dist/trace/redact.d.ts

@@ -35,10 +35,11 @@ export declare function armPoolBudgetForTest(): {
     urlSegmentReplays: number;
     ssh2ScanBytes: number;
     mappedUnits: number;
+    readings: number;
 };
 export declare function resetArmPoolBudgetForTest(): void;
 /**
- * 🔴 **脱敏的两个档 —— 「这段文本是自由文本,还是一个结构有界的单元」**(S-526,闭集两词)。
+ * 🔴 **脱敏的两个档 —— 「这段文本是自由文本,还是一个结构有界的单元」**([ref],闭集两词)。
  *
  * · `"free-text"`:CoT / 日志 / 任意字节。臂**全员**在场,读数就是 {@link redactSecrets} 的对外语义。
  * · `"bounded-unit"`:一个 URL 路径段、一个 query 键名或值 —— 边界由**结构**给(WHATWG 已经把界告诉我们了)。
@@ -54,18 +55,28 @@ export declare function resetArmPoolBudgetForTest(): void;
  */
 type RedactionScope = "free-text" | "bounded-unit";
 /** 本模块会写进文本的全部替换 token(`«…»` 字面),从三张表现算 —— 表改这里自动跟,不另抄一份。
- *  🔴 **S-223 v2 修复轮起它只剩一个语义:闭形闭集的加载期校验**。运行期「这一段是不是一枚记号」已经由
+ *  🔴 **[ref] v2 修复轮起它只剩一个语义:闭形闭集的加载期校验**。运行期「这一段是不是一枚记号」已经由
  *  {@link credentialSpans} 的闭**形**那一支一处答完({@link opaqueUnitEnd}),按闭**集**再认一遍的
  *  `redactionTokenEndAt` 与它同义而更窄,已删 —— 两只「什么算记号」的判别器就是两个定义。 */
-/** {@link buildDisplaySafeUrl} 解析不动一个配置型 URL 时的**占位**(S-475 件B)——fail-closed:输出**不含原串的
+/** {@link buildDisplaySafeUrl} 解析不动一个配置型 URL 时的**占位**([ref] 件B)——fail-closed:输出**不含原串的
  *  任何字节**(连 host 都不留),不许回落成原值。它不是任何一条臂的产物,所以要在这里**显式**进闭集
  *  {@link REDACTION_TOKENS}(闭形的加载期校验对它同样成立),消费端按契约 §5.1 的闭形逐枚解析时认得它。 */
 declare const DISPLAY_SAFE_URL_TOKEN = "\u00ABredacted:url\u00BB";
-/** S-776:出网代理 URL 的回显尺(`outbound-dispatcher.ts` `displayProxyUrl`)形不干净时整只用**同一枚**占位 —— 单独一行导出,
+/** [ref]:出网代理 URL 的回显尺(`outbound-dispatcher.ts` `displayProxyUrl`)形不干净时整只用**同一枚**占位 —— 单独一行导出,
  *  上面那行字面量保持 `const NAME = "…";` 形(`test/api-notice-text-freeze.test.ts` §6 的冻结扫描按这一形认替换 token)。 */
 export { DISPLAY_SAFE_URL_TOKEN };
 /**
- * 🔴 **取证相的重扫模式(测试座,S-375)** —— 生产恒 `"incremental"`;`"full"` 是**参照语义** = 「没有可复用的上一次执行」:
+ * 名表的**只读导出**([ref]:第四处消费 —— 受理口的 URL 凭据判官 `url-credential.ts`;文档同步钉按它对表)。
+ * 表的属主仍是本模块的 {@link CREDENTIAL_NAME_ANCHORS};加一个名字只改那一处,本数组与下面的谓词随之现算。
+ */
+export declare const CREDENTIAL_PARAM_NAMES: readonly string[];
+/**
+ * 「这个**已解码**的参数名是不是凭据名」([ref] 第四处消费)。入参是收方读到的那一形(`URLSearchParams` 解过一次码的名字),
+ * 判法与本模块 URL 参数臂同读 —— 同一只判定 {@link credentialNameAnchor}:整名在表里(ASCII 大小写不敏感,不做 Unicode 折叠)。
+ */
+export declare function isCredentialParamName(decodedName: string): boolean;
+/**
+ * 🔴 **取证相的重扫模式(测试座,[ref])** —— 生产恒 `"incremental"`;`"full"` 是**参照语义** = 「没有可复用的上一次执行」:
  * 每级五条取证臂整段重跑、URL 臂每段重扫,既不读足迹也不回放(池把每一级的脏区间当作「未知」交下去,与级 0 同一个读法)。
  * 证据表的建法(级 0 记号档 + 逐级折入)与收敛判据(脏区间为空)两种模式是同一条,所以两种模式只差「复用与否」这一位 ——
  * 增量重扫的全部正确性主张只有一句:**任何输入上两种模式输出逐字相同**(`test/forensic-incremental-rescan.test.ts` 并跑比对;
@@ -81,7 +92,7 @@ export declare function credentialSpansFoldForTest(prev: ReadonlyArray<readonly
 /** 🧪 结构读数(与 {@link ppkScanBytesForTest} 同一条技法):本扫描器读过的单元数,线性钉用。 */
 export declare function anchoredScanUnitsForTest(): number;
 export declare function resetAnchoredScanUnitsForTest(): void;
-/** 测试可见(S-265 真值表的两半):结构段里**表行只作声明、实现是手写扫描器**的臂 —— 声明正则的**新拷贝**
+/** 测试可见([ref] 真值表的两半):结构段里**表行只作声明、实现是手写扫描器**的臂 —— 声明正则的**新拷贝**
  *  (`lastIndex` 不与模块内那一枚共享)+ 扫描器在一份原文上产的候选跨度 `[起, 止)`。臂名是闭集 ⇒ 穷尽 `switch`
  *  (少一个 `case` = 缺返回 = 编译红)。 */
 export declare function structuralScannerForTest(arm: "json-secret-field" | "pem-fence"): {
@@ -105,19 +116,25 @@ export declare function resetPpkScanBytesForTest(): void;
  *  所以一个 `arm="fragment"` 计数可能来自残片,也可能来自一个恰好落在阈值之上的 look-alike;
  *  core [ref] 落地后这一支**趋零是证据、不归零不是证明**。别把它当截断事实的度量用。 */
 /**
- * 🔴 **词名 = 表归属,不是语义**(clay 裁 [ref] ①,2026-09-18,关 S-307):`"full"` = 强证据表(`SECRET_PATTERNS` 一族,
+ * 🔴 **词名 = 表归属,不是语义**(clay 裁 [ref] ①,2026-09-18,关 [ref]):`"full"` = 强证据表(`SECRET_PATTERNS` 一族,
  * 含 7.76.2 起改判进来的 PEM/ppk 体)命中的臂,`"fragment"` = 弱证据表({@link FRAGMENT_SECRET_PATTERNS})命中的臂。
  * 7.76.2 起两档语义已是「强证据 / 弱证据」,词名**刻意保留**:它是 Prometheus 标签 `redactions_applied_total{arm}` 的
  * 标签值,改名 = 硬 breaking 的标签值漂移(面板与告警按值匹配),而语义只在这一段注释里说全即可。判据是 {@link armOfToken}。
  */
 export type RedactionArm = "full" | "fragment";
 export interface RedactionHitMeta {
-    /** 命中臂的**判别力档位**(闭集两词,S-303):`"fragment"` = {@link FRAGMENT_SECRET_PATTERNS} 那一族
+    /** 命中臂的**判别力档位**(闭集两词,[ref]):`"fragment"` = {@link FRAGMENT_SECRET_PATTERNS} 那一族
      *  「短前缀 + 长度/熵阈值」的弱证据臂;`"full"` = 其余全部(结构锚 / 词法关键字 / 定长裸形)。
      *  判据 = 表归属,不是 token 的 `:partial` 后缀 —— 两条轴的分家逐字见 {@link armOfToken}。 */
     arm: RedactionArm;
 }
 export declare function setRedactionObserver(fn: ((patternLabel: string, count: number, meta: RedactionHitMeta) => void) | undefined): void;
+/**
+ * 一段文本的**出门形**(闭集两词,穷尽 `switch` 消费)—— 读不读第 ④ 类(原始的空白控制字符),只由它定(见 {@link deleteInvisibleCharacters} 顶注的表):
+ *  · `multi-line`:出口保留行结构(trace 帧、结果、CoT、审批预览 …;{@link redactSecrets} 一族全是这一形)⇒ ①②③;
+ *  · `single-line`:出口在读者看见之前把文本压成一行(出口座的日志字段行 / 标题行:空白控制字符被删或折成空格)⇒ ①②③④。
+ */
+export type RedactionLayout = "multi-line" | "single-line";
 export declare function redactSecrets(text: string, opts?: {
     observe?: boolean;
     json?: boolean;
@@ -126,13 +143,13 @@ export declare function redactSecrets(text: string, opts?: {
  * 脱敏 + **这一遍命中了哪些档位的臂**({@link RedactionArm} 闭集两词)—— 与 {@link redactSecrets} 同一只
  * 脱敏器、同一张表、同一遍扫描的另一个出口。
  *
- * 🔴 **为什么要这个出口**(S-303):下游有一类消费方问的不是「脱完长什么样」而是「这段文本里有没有
+ * 🔴 **为什么要这个出口**([ref]):下游有一类消费方问的不是「脱完长什么样」而是「这段文本里有没有
  * **强证据**的凭据形」——`tool-approval.ts` 的规则素材闸是头一个。旧形只能拿「字节变了没有」当谓词,
  * 于是弱证据臂(短前缀 + 阈值启发式)的一次多脱就等于一次「素材整只扣下」,用户拿不到常驻放行。
  * 出口开在脱敏器**自己**身上是硬约束:全仓只该有一个「什么算凭据」的属主,消费方**不许**按 token 字面
  * (`includes(":partial»")`)或另跑一遍正则去反推 —— 那就是第二只脱敏器。
  *
- * `arms` 是**这一遍真命中的档位集合**。「`text !== 入参`」与「`arms` 非空」仍不是一回事(S-1435 起理由换了):
+ * `arms` 是**这一遍真命中的档位集合**。「`text !== 入参`」与「`arms` 非空」仍不是一回事([ref] 起理由换了):
  * 前者 ⇔ 至少一条跨度改写了字节(强弱两档都算 —— 格式字符不再改字节);后者 = 至少一条臂命中,**含**字节没变的那种
  * (重扫已脱敏文本时,臂命中自己产出的记号、换回同一枚记号)。凭据形的证据是档位:规则素材闸问的是 `arms.has("full")`。
  */
@@ -147,8 +164,8 @@ export declare function redactSecretsWithArms(text: string, opts?: {
  * 🧪 **跨度出口 —— 只给测试**(车 UH 脱敏基线门 `test/redaction-baseline-gate.test.ts`:判「必隐字节**每一个**都被盖住」,
  * 而不是「必隐串整串不在」—— 后者对截断式脱敏(值的前缀被洗、尾段留着)恒判已藏,gpt-6 腿 r1-F1 [high])。
  *
- * 同一只 {@link runRedaction}、同一遍扫描,交出池算好的 `kept` 跨度映回**原文**之后的那一份(S-497 那一份;坐标在原文上,
- * 与产物同一套 —— S-1435 起;此前在剥后视图上),
+ * 同一只 {@link runRedaction}、同一遍扫描,交出池算好的 `kept` 跨度映回**原文**之后的那一份([ref] 那一份;坐标在原文上,
+ * 与产物同一套 —— [ref] 起;此前在剥后视图上),
  * 不是第二只脱敏器、不改任何判据、不喂观察者(`observe:false`,与影子重扫同口);`opts.json` 与 {@link redactSecrets} 的同名选项
  * 逐字同义(JSON 模式,`redactedPreview` 走的那一条)。生产代码不调用它:
  * 问「有没有凭据形」的消费方走 {@link redactSecretsWithArms}。
@@ -163,11 +180,11 @@ export declare function redactionSpansForTest(text: string, opts?: {
     }>;
 };
 /**
- * 🔴 **出口座的提案口**(S-485 / RH-1 第一期;座 = `src/trace/exit-seat.ts` 的 `seatText`)。
+ * 🔴 **出口座的提案口**([ref] / RH-1 第一期;座 = `src/trace/exit-seat.ts` 的 `seatText`)。
  *
- * 同一只 {@link runRedaction}、同一遍扫描、同一次观察者计数(`observe` 与 {@link redactSecrets} 的缺省同口 —— 座上的一次脱敏就是一次
- * 主扫),交出**原文坐标**上的跨度与各自的替换串:臂认什么、档里有哪些臂,仍然只由本模块答。座拿它做**一次区间合并 + 一次渲染**
- * (合并律与渲染律住在座里,本模块不拼第二份产物给座)。
+ * 同一只 {@link runRedaction}、同一张不可见字符读法格、同一次观察者计数(座上的一次脱敏就是一次主扫),交出**原文坐标**上的跨度与各自的替换串:臂认什么、档里有哪些臂、
+ * 一段文本有几种读法,仍然只由本模块答。`layout` = 这一行出口的出门形({@link RedactionLayout};必填 —— 出口自己说它把文本压不压成一行,第 ④ 类读不读随之定)。
+ * 座拿它做**一次区间合并 + 一次渲染 + 按出门形整形 + 按记号边界切**(合并律与渲染律住在座里,本模块不拼第二份产物给座)。
  *
  * 第一期交的是池解完重叠之后的那一份(升序、两两不交);第二期改交未解重叠的原始候选,池内并集律 {@link resolveSpanOverlaps} 与
  * {@link applySpans} 随之删除 —— 那时本口是自由文本脱敏的唯一出口。
@@ -178,7 +195,7 @@ export type RedactionSpan = {
     readonly repl: string;
 };
 export type { RedactionScope };
-export declare function proposeRedactionSpans(text: string, scope: RedactionScope): readonly RedactionSpan[];
+export declare function proposeRedactionSpans(text: string, scope: RedactionScope, layout: RedactionLayout): readonly RedactionSpan[];
 /**
  * 🔴 环 + 深度预算(2026-07-25 补)。原实现是纯递归、**既不记已访问节点也不限深度**,而它的调用位置是
  * **最不可信的边界**:`toolStart`/`toolEnd` 把工具的 `args`/`output`/`structured` 直接喂进来。后果两条:
@@ -206,14 +223,14 @@ export declare function redactDeepWith(value: unknown, leaf: (s: string) => stri
  */
 export declare function redactedPreview(value: unknown, cap?: number): string | null;
 /**
- * 🔴 **配置型 URL 上日志 / 诊断面的唯一 display-safe 铸点**(S-475 件B;`build*` = 返回纯数据的一只纯函数)。
+ * 🔴 **配置型 URL 上日志 / 诊断面的唯一 display-safe 铸点**([ref] 件B;`build*` = 返回纯数据的一只纯函数)。
  *
  * 病(7.87.2 亲核):启动日志 `listening` 行把配置里的 URL 写**原值** —— `brain: brainSummary(config)` 里的
  * `gateway: config.gatewayBaseUrl` 与同行的 `otel: config.otel.endpoint`,logger 不脱敏。部署若把凭据放在
  * 网关 URL 的 userinfo / query 里,密码明文落 `engine-*.log`(日志的读者面比 run 错误文本更宽:它落盘、
  * 被采集、进工单)。同类出口不止这两处,类级机器门在 `test/config-url-display-safe.test.ts`。
  *
- * 🔴 **S-483 展示半场(7.90.0 / core 7.24.0):两条正交的律合成一次,名表的射程缩到不可约的那一半**。
+ * 🔴 **[ref] 展示半场(7.90.0 / core 7.24.0):两条正交的律合成一次,名表的射程缩到不可约的那一半**。
  * 改前内部只有一条:`redactSecrets(new URL(raw).href)` —— 自由文本那条**名单制**的律,query 的值只在键名
  * 落在 `CREDENTIAL_NAME_WORDS`(或值本身像个密钥)时才遮,于是**没人列过的那个键名**就是它的盲点
  * (`?sig=…` / `?auth=…` / 部署自定义的网关参数名)。现在前面先跑 core 的 `displayUrlOf`,它是**位置制**的:
@@ -241,20 +258,20 @@ export declare function redactedPreview(value: unknown, cap?: number): string |
  *     成文代价:`MODEL_GATEWAY_BASEURL=gw.internal:8000` 这种缺 scheme 的配置在日志上变成 `«redacted:url»`
  *     —— 而它在 `fetch` 那一侧本来就是必然失败的形(WHATWG 要求绝对 URL),日志上响亮一点方向一致。
  *  ② **空串 = 未设**:里面没有凭据,原样回空串(不铸占位 —— 占位会让「没配」读成「配了但看不见」)。
- * ⚠️ **保形只到 host / port / path 这一层**(S-483 起如实改口;`test/config-url-display-safe.test.ts`
- * 的 S-483-o 是这句话的机器读数,别在散文里再抄一遍):scheme / host / port / path 的字节逐字(模 WHATWG
+ * ⚠️ **保形只到 host / port / path 这一层**([ref] 起如实改口;`test/config-url-display-safe.test.ts`
+ * 的 [ref]-o 是这句话的机器读数,别在散文里再抄一遍):scheme / host / port / path 的字节逐字(模 WHATWG
  * 的 HTTP 等价归一:默认端口省、host 小写、IDN→punycode、点段折叠,再加**整串末尾**的斜杠去掉 ——
  * 是**整串末尾**不是「路径末尾」:`…/p/` ⇒ `…/p`,而 `…/p/?k=v` 的 `/p/` 保留),query 只留**键名**。
  */
 /** 位置律的**形** —— 生产路径恒是 core 的 {@link displayUrlOf}。参数化是**为可测性开的唯一一个缝**
- *  (S-497 的「违反格」要造一个「位置律漏了一段」的世界,而拿上游的现成缺陷当触发器会在它修好那天失效);
+ *  ([ref] 的「违反格」要造一个「位置律漏了一段」的世界,而拿上游的现成缺陷当触发器会在它修好那天失效);
  *  生产调用方**不传**这个参数。 */
 export type PositionalUrlLaw = (url: string) => string;
 /** 测试口(与 `observability/fail-open.ts` 的 `resetFailOpenRecorderForTest` 同姿势):一次性 warn 的闸是
  *  模块级的,而「只 warn 一次」本身要被钉,所以给测试一个复位口。生产零调用。 */
 export declare function resetDisplaySafeFailClosedWarnForTest(): void;
 /**
- * 🔴 **S-497 的不变量 —— 形状律在 query / fragment 区间上有一条凭据跨度 ⇒ 那一整段不出门**。
+ * 🔴 **[ref] 的不变量 —— 形状律在 query / fragment 区间上有一条凭据跨度 ⇒ 那一整段不出门**。
  *
  * 为什么需要它(差分实测 650 形里 26 个反例,本车亲跑复现):两条律**串起来**的时候,前一条会把后一条
  * 赖以认字的**结构**改掉。实测的病形是 `https://h/?next=https://u:&pw@h=` —— 位置律先按 `&` 切段、把
@@ -265,7 +282,7 @@ export declare function resetDisplaySafeFailClosedWarnForTest(): void;
  * 击穿:①凭据**整段**不得是产物的子串 —— 位置律把它切开了,整段自然不是子串;②切成**片** + 长度下限 ——
  * 材料能被切成全是单字符(`&a!b!c!d@`)甚至纯标点(`&!$()*+,;@`),任何下限都漏;③**字符集**包含 ——
  * 密码的每个字符都能在同一条 URL 的 path / host / 别的键名里另外出现一次,包含关系成立而明文骑在产物上
- * (`https://h/abcdefghijklmnopqrstuvwxyz0123456789?ok=1&next=https://u:&secret123=x@h`,S-497-k)。
+ * (`https://h/abcdefghijklmnopqrstuvwxyz0123456789?ok=1&next=https://u:&secret123=x@h`,[ref]-k)。
  * 共同的根:**切开之后,「这个字节来自凭据」在文本上不可判**。⇒ 判据搬到切分之前,用形状律自己报的
  * **跨度坐标**当出处证明({@link shapeLawCredentialInQueryOrFragment})—— 不需要长度下限、字符类白名单
  * 或任何集合运算,**规则比前三版都少**,而且对「将来出现的新形」天然封闭(新形状照样落在跨度里)。
@@ -276,8 +293,8 @@ export declare function resetDisplaySafeFailClosedWarnForTest(): void;
  *  ② 否则照旧合成:位置律 → 形状律。
  * **过度遮的射程如实**:一条 query 里**真的**带凭据的配置型 URL,自本版起读不到它的**其它**参数名了
  * (改前是逐参数遮)。方向一致,而且干净的根**零影响** —— Azure 式 `?api-version=…&deployment=…` 上
- * 形状律一条跨度都没有,结构上走不到这一步(S-497-e 单独钉住)。path 区间的凭据**不**走这条路:位置律
- * 逐字保留 `pathname`,形状律在产物上照常认得它(S-497-f 的并集格)。
+ * 形状律一条跨度都没有,结构上走不到这一步([ref]-e 单独钉住)。path 区间的凭据**不**走这条路:位置律
+ * 逐字保留 `pathname`,形状律在产物上照常认得它([ref]-f 的并集格)。
  * 🔴 这是 fail-**closed**(扣下信息),**不**登记 `recordFailOpen` —— 那张表记的是「放行了本该拒的」。
  *    只打一条一次性 warn(**不含原文**:原文就是那段凭据)。
  */
@@ -297,7 +314,7 @@ export declare function buildDisplaySafeUrlChecked(raw: string, positionalLaw?:
     failedClosed: boolean;
 };
 /**
- * 🔴 **引用了一条「铸点都守不住」的 URL 的自由文本,一律扣下**(S-497 的第二个出口;codex 第三轮 [high] 二)。
+ * 🔴 **引用了一条「铸点都守不住」的 URL 的自由文本,一律扣下**([ref] 的第二个出口;codex 第三轮 [high] 二)。
  *
  * 料 = 上游(core)的路由拒因:一句自由文本,里面嵌着 core **已经用位置律改写过**的那条 URL。到本仓手上时
  * `://<userinfo>@` 的结构已经没了 ⇒ 形状律认不出那一段 ⇒ 光过一遍 `redactSecrets` 兜不住(实测:降级拒因