@sema-agent/client-core 0.77.0 → 0.77.2

package/dist/hitl/persistedRulesWire.js

@@ -2,51 +2,15 @@ import { engineCapTrue } from '../engineCapsCache.js';
 import { hostLog } from '../host.js';
 import { observedPermissionRulesWrite, permissionRulesWriteAvailable } from '../permissionRulesWriteCapability.js';
 import { readToolApprovalRespondAck } from './toolApprovalWire.js';
-// ── 能力位 gate ──────────────────────────────────────────────────────────────────────────────
-/** 规则车道在不在(四口 501 同源谓词)。未判/缺键/base 缺席 = false = 整面藏。 */
 export function persistedRulesLaneAvailable(baseUrl) {
     return engineCapTrue(baseUrl, 'permissionRules');
 }
-/**
- * 治理面(list + revoke)在不在。**两段合取**:
- *  · `permissionRulesRevoke` 在场 = 撤销面路由已铸(缺席 = worker 比撤销面老 ⇒ 藏);
- *  · `permissionRules` 为真 = 车道真答话(店 + 旋钮)。
- * 只查前者会在「7.11.0 且规则店在」的 worker 上渲出一个恒 404 的治理入口。
- */
 export function persistedRulesGovernanceAvailable(baseUrl) {
     return engineCapTrue(baseUrl, 'permissionRulesRevoke') && engineCapTrue(baseUrl, 'permissionRules');
 }
-/**
- * 收紧方向的单步写入口(把某条规则改成 deny/ask)对**这次调用**在不在。
- *
- * 🔴 只派生自 `capabilities.permissionRulesWrite` 自己的四态读数(`permissionRulesWriteAvailable`),
- * **不合取** `permissionRules`、也**不**再读一遍 `engineCapTrue`——那是撤销面(`persistedRulesGovernanceAvailable`)
- * 的读法,上游明说两位的读法别混:撤销面那一位是与调用方身份无关的部署级存在性信号,必须合取车道位
- * 才是完整判据;写口这一位的值本身**已经**编码了「车道在不在 ∧ 这次调用带不带得到身份」两件事,
- * 再合取一次等于给同一件事立第二个判官——车道开着但写口所在的引擎还没起播,或反过来,合取会把
- * 其中一种真实的过渡态错判。
- * 读的也是**同一份**能力位状态(该四态读器自己的 per-baseUrl 表),不是另开一张表。
- *
- * 🔴 **显式 `undefined` 不许回落装好的默认读锚**(异源对抗复审 [medium] 采纳,真病):
- * `observedPermissionRulesWrite(baseUrl = engineWireTarget()?.baseUrl)` 的默认参数只在参数
- * **省略**时生效,而调用方显式传 `undefined` 与省略在 JS 里同判——原样转发会让「这次没有 baseUrl」
- * 被悄悄换成**装好的默认引擎**那一份读数,与上面两口(`engineCapTrue` 对 `undefined` 恒 `unprobed`
- * ⇒ false,零默认读锚回落)不同律;多引擎宿主上会把「这个会话没配 baseUrl」误读成「随便一个已装
- * 引擎的答案」。传空串绕开默认参数(reader 对空串的处置是 `unobserved`,与 `undefined` 的意图一致
- * 但不触发默认值语义)。
- */
 export function persistedRulesWriteAvailable(baseUrl) {
     return permissionRulesWriteAvailable(observedPermissionRulesWrite(baseUrl ?? ''));
 }
-/**
- * cc-import redeem 200 体的兑付计数**双代归一读口**(server 7.46 未声明 BREAKING 的消费半场):
- *  · **新形**(server 7.46+):`result.members[]` 判别联合,member.status ∈ {'persisted','deduped'}
- *    (refused 不上 200 体 —— server 侧折进 404/503,见头注「404 禁按成因分支」);
- *  · **旧形**(≤7.45;SDK 7.2.0 `rules.d.ts` 仍此形):`result.persisted[]` / `result.deduped[]` 桶。
- *  · 纪律与 0.43.0 ruleOffers 窄读器同款:**新键(members)在场就按新键读** —— 即使全 0 也绝不
- *    回落旧键;两形都缺 ⇒ `null`(诚实缺席,调用方渲 unknown,绝不渲 0/成功)。
- * 入参吃 200 体的 `result` 字段(`unknown`:SDK 声明形已与真 wire 脱节,边界必须结构窄化)。
- */
 export function readCcImportRedeemCounts(result) {
     const o = (result ?? {});
     if (Array.isArray(o.members)) {
@@ -77,7 +41,6 @@ function errShape(e) {
         message: typeof o.message === 'string' && o.message !== '' ? o.message : String(e),
     };
 }
-/** `Retry-After` 秒数(SDK 把它折进 `retryAfterMs`)。非数/负数 ⇒ 缺席。 */
 function retryAfterSecOf(e) {
     const ms = e.retryAfterMs;
     if (typeof ms !== 'number' || !Number.isFinite(ms) || ms < 0)
@@ -86,14 +49,10 @@ function retryAfterSecOf(e) {
 }
 export function classifyRulesFailure(e) {
     const { status, errorCode, message } = errShape(e);
-    // 🔴 店缺席只认**机器码**,不认 501 状态码本身(0.77.0 改口):引擎的错误信封恒带机器码,而一个没码的 501
-    //    谁都能发(反代对陌生动词就回它)—— 凭它藏面、或在写腿说「确知没写」,都是把出处让给了状态码。
     if (errorCode === 'capability.rule_store_required') {
         return { kind: 'lane-unavailable', message };
     }
     if (status === 404) {
-        // 🔴 两个 404 是**不同处置**(SDK 头注):route 缺席 = 版本太老(藏面);rule_ticket = 票没了
-        // (丢票重来)。其余 404 一律按通用错误 —— 绝不按成因猜。
         if (errorCode === 'not_found.route')
             return { kind: 'route-missing', message };
         if (errorCode === 'not_found.rule_ticket')
@@ -118,10 +77,6 @@ export function classifyRulesFailure(e) {
         return { kind: 'too-many-candidates', message };
     if (status === 403 && errorCode === 'auth.operator_only')
         return { kind: 'forbidden', message };
-    // 🔴 **405 分两格,判据是「码给不给得出出处」**(异源复审 R2 [medium],真病):引擎那一支发的是没有
-    // 前缀族的裸 `method_not_allowed` —— 见到它才能说「这台 worker 比这个动词老」。而**无码**的 405
-    // (中间层/网关拦 POST 时常回 HTML 或空体)谁都能发,凭它断言对端版本会让调用方去升级一台其实没问题
-    // 的 worker、或藏掉一个其实活着的入口。空串码与缺席同判(都给不出出处),不许两者各落一格。
     if (status === 405) {
         return errorCode === 'method_not_allowed'
             ? { kind: 'method-unsupported', message }
@@ -129,86 +84,25 @@ export function classifyRulesFailure(e) {
     }
     return { kind: 'error', message };
 }
-// ── 三态规则身份(behavior)────────────────────────────────────────────────────────────────────
-/**
- * 一条持久规则是哪一态 —— sdk `RuleBehavior` 的**运行期镜像**(引擎侧同一张闭三词表)。
- * `allow` = 一次人工批准的常驻形(卡上点的「不再询问」);`deny` / `ask` = 「永不运行」与
- * 「每次都问我」的常驻形。**一套文法、一种规范拼法、一族匹配器**服务三态,态是**文本旁边的
- * 一格**,永远不是文本的一部分。
- * 🔴 门 `run-rules-side-test.mjs` G9a 对 sdk 的联合成员**逐词等值**对账(缺一词红、多一词红)。
-
- * 🔴 形制:`Object.freeze` 的数组,**不是**只在类型面只读的 `readonly T[]` —— 后者一行 `.splice()`
- *    就能改,而公面消费者拿到的正是这个实例(本仓已定谳的病形,同 `RESUME_RETRY_LATER_CODES`)。
- */
 export const PERSISTED_RULE_BEHAVIORS = Object.freeze(['deny', 'ask', 'allow']);
 const BEHAVIOR_SET = new Set(PERSISTED_RULE_BEHAVIORS);
-/** 一行上非空字符串字段的取值(其余一律 `undefined`)。 */
 function rowStr(row, key) {
     if (typeof row !== 'object' || row === null || Array.isArray(row))
         return undefined;
     const v = row[key];
     return typeof v === 'string' && v.length > 0 ? v : undefined;
 }
-/**
- * 一条**持久规则行**的身份两键(`rule` / `scope`)读不读得出 —— 列举面与单步写口**共用的那一只**
- * 行型窄化器(🆕 0.77.0 提名:此前它内联在列举面的翻页循环里,写口回包要判同一件事,再写一遍就是
- * 同一份判据的第二个法官)。
- *
- * 🔴 **只判身份两键,不判展示键**:`rule` / `scope` 是撤销按内容寻址那一对,读不出 ⇒ 这一行既渲不出
- * 也撤不掉;而 `tool` / `match` / `command` / `adds` 是展示键,引擎 additive 演进不该把整面打红
- * (消费端对展示键自有坏形容忍)。
- * 🔴 **`behavior` 刻意不在这道门里**:读不出态的行**照样交出去**(丢行 = 把一条活规则从治理清单里
- * 藏起来),呈现走 {@link persistedRuleBehaviorLabel}、撤销侧由
- * {@link revokeTargetFromPersistedRule} 自己拒铸 —— 两条纪律分属两个位置,合并会让「看得见但撤不掉」
- * 这个**正确**的中间态变得不可表达。
- * 🔴 **两处必须同判**:写口 200 体里的那一行与列举面的行在上游是**逐格相同**的一只形;两处各铸一份
- * 判据的那天,同一条规则会在治理清单里在场、在写完回填时被判坏(或反过来)。
- */
 function persistedRuleIdentityRowReadable(row) {
     return rowStr(row, 'rule') !== undefined && rowStr(row, 'scope') !== undefined;
 }
-/**
- * 这一行是哪一态。**闭三词**之外(含整键缺席的老 worker 行)一律 `undefined`。
- *
- * 🔴 **绝不补默认**:缺席是「这台 worker 说不出来」,不是 `allow`。补一个默认会让呈现面
- *    对一条 deny 行说 allow,而撤销面据此瞄准另一态。
- * 🔴 这里**按闭集读**(与本包其余开集读口刻意不同):这一格是**身份**的一格,不是一个展示词——
- *    读不懂的身份必须判「读不出」,而不是原样当成一个能拿去撤销的态。呈现层要原样渲那个词,
- *    走 {@link persistedRuleBehaviorLabel}(它是开集的)。
- */
 export function persistedRuleBehaviorOf(rule) {
     const b = rowStr(rule, 'behavior');
     return b !== undefined && BEHAVIOR_SET.has(b) ? b : undefined;
 }
-/** 读不出态时呈现面渲的那个词。**逐字锚**(三端共用一句;端零自拼)。 */
 export const PERSISTED_RULE_BEHAVIOR_UNKNOWN = '(unknown)';
-/**
- * 治理行上「态」那一列的**唯一措辞铸点**。
- * 🔴 三态渲词本身;**表外词原样渲**(开集 —— 引擎加词那天治理面照样看得见那个词,不至于把一条
- *    真实的行渲成「读不出」);**整键缺席/坏形**才渲 {@link PERSISTED_RULE_BEHAVIOR_UNKNOWN} ——
- *    它不冒充三态里的任何一个,读到它的人知道下一步是升级那台 worker。
- */
 export function persistedRuleBehaviorLabel(rule) {
     return rowStr(rule, 'behavior') ?? PERSISTED_RULE_BEHAVIOR_UNKNOWN;
 }
-/**
- * 一条列举行 → 撤销体(`rules.revoke()` 的入参)。**按内容寻址**,这条面上下没有任何 id。
- *
- * 🔴 **身份三元组逐字回传**(`behavior` / `rule` / `scope`):拼法等价但不逐字相同的 scope 什么都
- *    匹配不上,而且会得到一个笑呵呵的 `no-op`;所以原样送回引擎给的那串字节,别拿解析后的形重铸。
- * 🔴 **只带身份三键 + 可选 `principal`**:`source` / `status` 是**派生键**,回传它们会被拒。
- * 🔴 **`behavior` 读不出 ⇒ 拒铸(返回 `undefined`)**,这正是本次 BREAKING 的全部理由:猜一态的
- *    代价是不可逆地删掉另一态的行且调用方收到 200;拒铸的代价只是治理面少一个按钮。调用方据此
- *    藏掉撤销入口(并可用 {@link persistedRuleBehaviorLabel} 告诉用户为什么)。
- * 🔴 `rule` / `scope` 任一读不出也拒铸:按 `undefined` 撤销什么都对不上。
- * 🔴 **显式给了一个无效 `principal` ≠ 没给**(异源对抗复审 [high]):`principal` **缺席**明确表示
- *    「撤**我自己的**」。若把一个显式传进来的空串/非串静默降级成缺席,一次瞄准**别人**的 operator
- *    撤销就会转向**调用者自己**的规则桶,并且拿到一个 200 —— 而目标值算空在治理面上是常见形
- *    (表单空字段、一次没查到的用户名)。⇒ 键**在场但值不合法**时**拒铸整只**,与 `behavior`
- *    读不出同一条处置。`opts` 整只不给、或给了但不含这个键,才是「缺席 = 撤我自己的」那个合法意图。
- * ⚠️ 合法值**原样送出不 trim**:principal 的规范形归引擎,壳替它 trim 会让两端对「同一个人」的
- *    拼法各有一份判据。
- */
 export function revokeTargetFromPersistedRule(rule, opts) {
     const behavior = persistedRuleBehaviorOf(rule);
     if (behavior === undefined)
@@ -227,17 +121,6 @@ export function revokeTargetFromPersistedRule(rule, opts) {
         ...(override.principal !== undefined ? { principal: override.principal } : {}),
     };
 }
-/**
- * 越权域那一格的**唯一判据**(撤销体与单步写体两条腿共用):`principal` 键**缺席** = 「这一条是
- * 我自己的」;键**在场但指不了人**(非串 / 空白串)⇒ `ok:false` = **整只拒铸**。
- *
- * 🔴 **显式给了一个无效名 ≠ 没给**:把它静默降级成缺席,会让一次瞄准**别人**的 operator 操作转向
- *    **调用者自己**的规则桶并拿到一个 200 —— 在收紧方向上那是「本该给租户加的拒绝,加到了自己头上」,
- *    在撤销方向上是「本该收回租户的放行,删了自己的规则」。而目标值算空在治理面上是常见形
- *    (表单空字段、一次没查到的用户名)。
- * ⚠️ 合法值**原样送出不 trim**:principal 的规范形归引擎,壳替它 trim 会让两端对「同一个人」的拼法
- *    各有一份判据。
- */
 function readPrincipalOverride(carrier) {
     if (carrier === null || typeof carrier !== 'object' || !('principal' in carrier))
         return { ok: true };
@@ -246,26 +129,8 @@ function readPrincipalOverride(carrier) {
         return { ok: false };
     return { ok: true, principal: raw };
 }
-/** 一页要多少条。**必须显式给**(对抗复审 [medium] 实撞):server 缺省是 **50**,而页帽
- *  按「200/页」算 ⇒ 真实上界只有 1250 条,一位规则多于 1250 的 principal 会恒拿到「翻不完」的
- *  失败、整个治理面打不开,而注释还写着 5000。夹取语义在 server(非数/越界夹进 1..200),所以给
- *  上限最省往返、也让页帽的算术与现实一致。 */
 const PAGE_LIMIT = 200;
-/** 页数硬帽:server 恒给 nextCursor 的坏形不该让治理面无限翻(PAGE_LIMIT × 25 = 5000 条)。 */
 const MAX_PAGES = 25;
-/**
- * 列全一位 principal 名下活着的规则。
- *
- * 🔴 **翻页要翻完**:`nextCursor` 缺席才是终点 —— 半途停下拿到的是一份不全的清单,而治理视图
- * 恰恰最不能拿不全的清单当全量。所以这里 drain 到底,任何一页失败都不交部分结果。
- * 🔴 **游标绑 `(rev, principal, scope)`**:两页之间有人加/删了规则 ⇒ 第二页 400
- * `request.query_invalid`。处置 = **丢游标从头列一次**(静默重置成「接着上一页」会得到一份既漏行
- * 又重行的清单);从头再撞一次 ⇒ 如实报 cursor-stale,由调用方(人按 r 刷新)决定。
- * 🔴 **调用方 cursor 不收**(复审 F2 对抗复审 [medium]):类型上剔掉 `cursor` 还不够 —— JS
- * 调用方仍能塞进来,而首页的 `...params` 会把它原样送出 ⇒ 「列全」从**中途**开始却报 `ok:true`
- * 完整清单(治理面据此藏掉仍然生效的规则)。运行期显式剥除 + 留痕:drain 恒从第一页起,
- * 「接着别人的 keyset」证明不了完整性,与本函数的契约(rules 恒完整)结构性冲突。
- */
 export async function listAllPersistedRules(facade, params = {}, opts) {
     const { cursor: callerCursor, ...cleanParams } = params;
     if (callerCursor !== undefined) {
@@ -279,8 +144,6 @@ export async function listAllPersistedRules(facade, params = {}, opts) {
         for (let page = 0; page < MAX_PAGES; page++) {
             let res;
             try {
-                // limit 显式给:①页帽的算术要与真实页大小一致(见 PAGE_LIMIT);②keyset 游标绑的是
-                // 一份确定的翻页参数,页大小在两页之间变会让「接着上一页」失去意义。调用方可覆盖。
                 res = await facade.list({ limit: PAGE_LIMIT, ...cleanParams, ...(cursor !== undefined ? { cursor } : {}) }, opts);
             }
             catch (e) {
@@ -292,13 +155,6 @@ export async function listAllPersistedRules(facade, params = {}, opts) {
                 }
                 return { ok: false, failure };
             }
-            // 🔴 页体 fail-closed 窄化(复审 F2 轮二 [high]):SDK 传输层只 JSON.parse,不做运行期
-            // schema 校验 —— 一个 2xx 的 `{rev:9}`(无 rules 数组)在旧读法下会被认证成「完整的空清单」
-            // (`ok:true, rules:[]`),治理面据此宣称「没有持久规则」而活规则不可见、无法撤销
-            // (版本偏斜/后端降级下静默发生)。坏形页 = 判不出,绝不当「读到了空的」:
-            //   · `rules` 必须是数组、`rev` 必须是有限数(SDK `RuleListResult` 两键皆必填);
-            //   · `nextCursor` 只有两种合法形:**缺席**(= 终页)或**非空字符串**(= 还有下一页);
-            //     `''`/null/数字等坏形不许被折成「到头了」—— 猜终点与猜续点同罪。
             if (typeof res !== 'object' ||
                 res === null ||
                 !Array.isArray(res.rules) ||
@@ -312,9 +168,6 @@ export async function listAllPersistedRules(facade, params = {}, opts) {
                     },
                 };
             }
-            // 🔴 跨页 rev 钉(复审 F2 轮三 [high]):游标契约上绑 rev —— 清单变了,续页**该** 400
-            // cursor-stale。一个 2xx 却换了 rev 的续页 = server 违约或降级形,拼起来是**混合快照**;
-            // 认证它为完整清单,比 400 那条腿(丢游标重列)更坏 —— 这里不猜不修补,如实 failure。
             if (rev !== null && res.rev !== rev) {
                 return {
                     ok: false,
@@ -324,14 +177,7 @@ export async function listAllPersistedRules(facade, params = {}, opts) {
                     },
                 };
             }
-            // 🔴 行级窄化(同轮):撤销承重的两键(`rule` / `scope`,revoke 的按内容身份对)必须是
-            // 非空串 —— `rules:[null]` / 缺 scope 的行被展进 `PersistedRule[]`,下游要么渲空白治理项、
-            // 要么按 undefined 撤销(什么都对不上)。坏行 = 坏页(丢行会把活规则藏起来,正是本函数
-            // 拒绝的病);其余展示键(tool/match/command/adds)不在此过度收紧 —— server additive 演进
-            // 不该把整面打红,消费端对展示键自有坏形容忍。
             for (const r of res.rules) {
-                // 🔴 与单步写口回包**同一只**窄化器(`persistedRuleIdentityRowReadable`)—— 两处各判一遍的
-                // 那天,同一条规则会在一面在场、在另一面被判坏。
                 if (!persistedRuleIdentityRowReadable(r)) {
                     return {
                         ok: false,
@@ -370,118 +216,31 @@ export async function listAllPersistedRules(facade, params = {}, opts) {
     }
     return { ok: false, failure: { kind: 'cursor-stale', message: 'rule list kept changing under the cursor — try again' } };
 }
-// ── 单步写口(收紧方向;engine ≥7.91.0)────────────────────────────────────────────────────────
-/**
- * 单步写口**不收**的那一态 —— 放宽方向的单一铸点。
- *
- * 🔴 `satisfies RuleBehavior` 不是装饰:它把这个字面量钉在**引擎的态词表**上。哪天词表里没有这个词了,
- *    本行当场编译不过 —— 而一个手写的排除词在那天会安静地排除一个不存在的东西。
- */
 const DIRECT_WRITE_EXCLUDED_BEHAVIOR = 'allow';
-/**
- * 单步写口收得下的**态**,运行期表。**由 {@link PERSISTED_RULE_BEHAVIORS} 减去放宽那一词派生**,
- * 源码里**没有第二个 behavior 字面量数组**(门对这一条有边界钉)。
- *
- * 🔴 **为什么必须是派生而不是一张两词表**:态的词表属主只有一个(引擎)。一张手抄的两词表会在词表
- *    加员的那天变成一句没人复核过的旧话 —— 新词既进不来,也没有任何一道门会响。派生式让这句话跟着
- *    词表走:这里表达的不是「有哪两个词」,而是**「三态里哪些进得了这条口」**。
- * 🔴 **放宽方向在类型上就拼不出来**:常驻放行只有两条路(审批卡上的人点头 / 一次显式的 settings 导入),
- *    这条口**不是**第三条。一个能拼出来的放宽入参会让调用方以为它是。
- * 🔴 形制同兄弟表:`Object.freeze` 的数组,不是只在类型面只读的 `readonly T[]` —— 后者一行 `.splice()`
- *    就能改,而公面消费者拿到的正是这个实例。
- */
 export const PERSISTED_RULE_WRITE_BEHAVIORS = Object.freeze(PERSISTED_RULE_BEHAVIORS.filter((b) => b !== DIRECT_WRITE_EXCLUDED_BEHAVIOR));
 const WRITE_BEHAVIOR_SET = new Set(PERSISTED_RULE_WRITE_BEHAVIORS);
-/** 这个值是不是一个写得进去的态。**判据只读上面那张运行期表**(不是第二份词表,也不是一串 `||`)。 */
 function isPersistedRuleWriteBehavior(v) {
     return typeof v === 'string' && WRITE_BEHAVIOR_SET.has(v);
 }
-/**
- * 写**没落地**的成因闭集。每一词都对着一条真码 / 一条本地判据,**核不到的不铸**。
- *
- * 前四词是**发出去之前**就定局的(本地拒铸,连一次往返都没有);后六词是引擎的答话。
- * 🔴 十词共同的、也是唯一的承诺:**这次调用一个字都没写进店**。所以一个拿不出这句话的证据的成因
- *    **不许**进这张表 —— 哪怕它看上去像一次拒绝(例:一个来源不明的 405,见
- *    {@link PERSISTED_RULE_WRITE_UNKNOWN_REASONS} 的 `unattributed_method_refusal`)。「说不清」不在这张表里,它是
- *    {@link PersistedRuleWriteOutcome} 的另一臂({@link PERSISTED_RULE_WRITE_UNKNOWN_REASONS})。
- */
 export const PERSISTED_RULE_WRITE_REFUSAL_CAUSES = Object.freeze([
-    /** 本地:态不在 {@link PERSISTED_RULE_WRITE_BEHAVIORS} 里(放宽那一词,或干脆不是一个态)。 */
     'unwritable_behavior',
-    /** 本地:`rule` / `scope` 任一不是非空串 —— 按缺席寻址什么都对不上。 */
     'unreadable_identity',
-    /** 本地:`principal` 键在场但指不了人(静默改写那一条,见 `readPrincipalOverride`)。 */
     'unusable_principal',
-    /** 本地:注入的 facade 上**没有这个动词**(宿主的客户端比这条口老)⇒ 连发都没发出去。 */
     'client_too_old',
-    /** 400 `request.field_invalid` —— 字段值被拒(方向 / 规则文本 / scope 的字节),机读细格停在 wire 上。 */
     'field_refused',
-    /** 400 `request.body_shape` —— 体读不出形;同一份体重发永远同一个结果。 */
     'body_shape',
-    /** 403 `auth.operator_only` —— 替别人写被拒(显式名单;空名单 = 谁都不是)。 */
     'operator_only',
-    /** 501 `capability.rule_store_required` —— 这台部署没接规则店 / 旋钮关着。 */
     'store_absent',
-    /** 405 **带引擎自己的裸 `method_not_allowed`** —— 路径在、这个动词不在:worker 比这条动词老。 */
     'lane_too_old',
-    /** 404 `not_found.route` —— 这条路径整条不在(worker 比规则面本身还老)。 */
     'route_absent',
 ]);
-/**
- * 「**不知道落没落**」的成因闭集。
- *
- * 🔴 这五词与上面那十词**不可互折**:那些说的是「确知没写」,这五词说的是「**读不出结局**」。
- *    把后者渲成前者会让人以为可以干净地重来一遍;渲成 `persisted` 则是谎报一次可能根本没发生的
- *    收紧。四词的处置一律是:重试,然后用 {@link listAllPersistedRules} 对账。
- *
- * 🔴 **「重试」在批准台账上是安全的,而这条安全性在引擎里、不在这里**(异源复审 R2 [high] 提出的
- *    「重放会让台账无界增长」,亲读引擎的写腿验真后**改成文、不改代码**):引擎在落任何东西之前**先问
- *    「这条身份已经站着吗」**,站着就**一个字都不写**并答 `no-op`。所以一次「说不清」之后**顺序**重发
- *    同一份身份三元组,最坏情况是收到 `no_op` —— 批准台账不增长、桶的修订号不推进。
- *    ⚠️ 真正会让同一条逻辑规则带上两枚因果点的是**并发**:两个写者同时看见「不在」而各落一枚,
- *    那是 add-wins 的正解(两枚点、一条规则),两边都会如实收到 `persisted`,没有人被告知「没写」。
- *    ⚠️ 也正因为这道前问在**引擎**那一侧,本包**不**在重试前自己先列举一遍 —— 那会把引擎已经做了的
- *    读再做一次,并且给同一个问题立第二个说话人。「先对账再决定要不要重发」是调用方的策略自由,
- *    不是本口的前置条件。
- */
 export const PERSISTED_RULE_WRITE_UNKNOWN_REASONS = Object.freeze([
-    /** 503 `state.rule_write_failed` —— 引擎**自己说**它判不出终局(店抖动 / 兑付面没交回可判的终局 /
-     *  写落了而回读它时一条并发撤销已先到,三者在这条口上不可分辨)。 */
     'indeterminate',
-    /** 2xx 但体读不出(`status` 不在闭二词里 / `rev` 不是有限数 / 回包那一行的身份两键读不出)。
-     *  🔴 **绝不**折成 `persisted` —— 一个读不懂的回包证明不了任何事。 */
     'malformed_result',
-    /**
-     * 2xx 形是好的,但回包那一行的**身份三元组与这次发出去的那份对不上**(态 / 文本 / 作用域任一不逐字相同,
-     * 含整格缺席)。
-     * 🔴 **这一格不是「同一份判据的第二个法官」,是另一个问题**(异源复审 R1 [high] 采纳):行型窄化器答的是
-     *    「这一行读得出来吗」(列举面与本口同一只);这里答的是「读出来的这一行**是不是我刚才要写的那条**」——
-     *    后者的材料(刚发出去的身份)只有写腿手上有,列举面根本问不出这个问题。
-     * 🔴 为什么非查不可:规则的身份是**三元组**,同文本不同态是两条不同的行。一个缺了态、或回了兄弟态、
-     *    或回了另一条文本的 200 若被认证成 `persisted`,调用方会对人宣布一条**根本没落地**的收紧,
-     *    而治理面上那条规则并不在。诚实的答案是「读不出结局」:重试,然后用列举面对账。
-     * ⚠️ 对一台如实作答的引擎这一格**恒不发生**:写口的 200 体里那一行是它**按同一份身份三元组**从店里
-     *    找回来的,非规范拼写在更早一道门上就已经被拒(所以 200 ⇒ 发出去的文本就是店里的拼写),
-     *    作用域判别式串的解析与回写是不动点。所以它响起来只意味着版本偏斜、中间层改写或坏回包。
-     */
     'identity_mismatch',
-    /**
-     * 405 **而码给不出出处**(缺席 / 空串 / 别的码)—— 看见的是「这个动词被拒了」,而**谁拒的、拒在哪一段
-     * 不知道**:引擎那一侧的 405 发在路由分派期(请求没进处理腿),但一个中间层 / 网关也能发同一个状态码,
-     * 而它**可能已经把请求转给引擎**、事后才按自己的策略回 405。
-     * 🔴 **所以它进「不知道」而不是「确知没写」**(异源复审 R3 [medium] 采纳):后者那一组的承诺是「一个字
-     *    都没写进店」,而这一形拿不出那句话的证据 —— 一个据此**跳过对账**的调用方会留下一条用户以为没生效
-     *    的常驻拒绝。处置与本组其余各词相同:重试(台账安全),然后用 {@link listAllPersistedRules} 对账。
-     * ⚠️ 与 `lane_too_old` 的分别仍然保留、而且是这一格存在的理由:**别据此要求升级 worker、也别据此藏掉
-     *    入口**(那两个动作要的是能力位或版本证据,不是一个谁都能发的状态码)。要说「这台 worker 比这个
-     *    动词老」,只有引擎自己的裸码才有资格。
-     */
     'unattributed_method_refusal',
-    /** 抛了,而分类器没能把它归进任何一条「确知没写」的腿(网络 / 超时 / 中间层 / 未来的码)。
-     *  非幂等动词上「没分出来」的默认必须是「不知道」,不是「没写」。 */
     'unclassified',
 ]);
-/** 失败分类(单一判官 {@link classifyRulesFailure})→ 写口结局的**全量**映射。 */
 function writeOutcomeFromFailure(failure) {
     const message = failure.message;
     switch (failure.kind) {
@@ -495,43 +254,16 @@ function writeOutcomeFromFailure(failure) {
             return { status: 'refused', cause: 'store_absent', message };
         case 'method-unsupported':
             return { status: 'refused', cause: 'lane_too_old', message };
-        // 🔴 405 但码给不出出处 ⇒ **不知道**,不是「确知没写」(异源复审 R3 [medium]):一个中间层可能已经把
-        //    请求转给引擎、事后才按自己的策略回 405。逐条理由见该词的注。
         case 'method-refused':
             return { status: 'unknown', why: 'unattributed_method_refusal', message };
         case 'route-missing':
             return { status: 'refused', cause: 'route_absent', message };
         case 'write-indeterminate':
             return { status: 'unknown', why: 'indeterminate', message };
-        // 🔴 其余各臂(通用 error,以及票面 / 游标 / 页帽那几条本口结构上到不了的腿)一律「不知道」:
-        //    这是一个**非幂等**动词,「没分出来」的默认是「读不出结局」,不是「什么都没写」——
-        //    一个 500 完全可能发生在店写完之后。
         default:
             return { status: 'unknown', why: 'unclassified', message };
     }
 }
-/**
- * 单步写一条**收紧**规则(deny/ask)进持久店 —— 撤销面的对偶,无同意仪式往返。
- *
- * 判据次序照引擎那一侧逐条对位,**只多一道在最前面**:
- *  ⓪ **口在不在**(注入的 facade 有没有这个动词)—— 与「按能力位 gate、别 trial-by-501」同一条纪律:
- *     一次连动词都拼不出来的调用不该先去撞引擎的限流桶;
- *  ① 体形(身份三键读得出);② 方向(只收收紧);③ scope 读得出形;④ 越权域那一格。
- * ②③④ 的**本地**判据刻意比引擎宽:本地只判「这串是不是一个 X」,「这个 X 写得进去吗」永远由引擎答
- * (规范拼写、scope 的字节、行自洽都是引擎的判据)—— 壳替它判一遍就是同一件事的第二份真源。
- *
- * 🔴 **本函数不重试**:一次「说不清」被自动重放,重试预算与节奏就成了本包替调用方做的决定;而对账
- *    那一步(用 {@link listAllPersistedRules} 读回来看)只有调用方做得了。
- *    ⚠️ 手工重试**在批准台账上是安全的**(引擎落地前先问「已经站着吗」,站着就一个字都不写)——
- *    逐条理由见 {@link PERSISTED_RULE_WRITE_UNKNOWN_REASONS} 的头注。
- * 🔴 **回包那一行走列举面同一只窄化器**,不给同一份判据立第二个法官;读不出 ⇒ `unknown` /
- *    `malformed_result`,**绝不**当成「写上了」。
- * 🔴 **窄化之后还有一道身份对账**(`identity_mismatch`):回包那一行的身份三元组必须与发出去的那份逐字
- *    相同。这不是同一份判据的第二个法官 —— 窄化器答「读得出来吗」,对账答「是不是我要的那条」,而后者的
- *    材料只有写腿手上有。列举面「态读不出的行照样交出去」的纪律在这里不适用:看得见 ≠ 证明得了。
- * ⚠️ 回包行的 `adds[].origin` **不是**「谁写的这条规则」的判据(引擎今天从审批记录的种类派生出处词,
- *    而本口落店走的是同一条兑付腿)—— 原样透传,不进本包任何一条判据。
- */
 export async function writePersistedRule(facade, input, opts) {
     const port = facade?.write;
     if (typeof port !== 'function') {
@@ -575,15 +307,7 @@ export async function writePersistedRule(facade, input, opts) {
     }
     let res;
     try {
-        // 🔴 **`port.call(facade, …)` 而不是 `port(…)`**(异源复审 R1 [high],真病):把方法从对象上取下来
-        //    再裸调,`this` 就没了。本包其余三口走的都是 `facade.list(…)` 这种**方法调用**形,而宿主最自然的
-        //    装配恰恰是把真 client 的资源对象原样交进来(那是一个类实例,它的每个动词都靠 `this` 拿传输层)——
-        //    裸调在那种 facade 上当场抛,而写口会把它读成一次「不知道落没落」,重试多少次都一样。
-        //    绑回接收者让三口同律;注入的是普通对象/箭头函数时,多传一个 thisArg 也无害。
         res = await port.call(facade, {
-            // 🔴 只送身份三键 + 可选越权域:派生键(源 / 站位)回送会被拒,而**原样送引擎给的那串字节**
-            //    是撤销面同一条纪律(拼法等价但不逐字相同的 scope 什么都匹配不上,还会得到一个笑呵呵的
-            //    「没什么可做」)。
             behavior,
             rule,
             scope,
@@ -593,8 +317,6 @@ export async function writePersistedRule(facade, input, opts) {
     catch (e) {
         return writeOutcomeFromFailure(classifyRulesFailure(e));
     }
-    // 🔴 2xx 体 fail-closed 窄化:传输层只 JSON.parse,不做运行期 schema 校验。一个读不懂的 200
-    //    证明不了「写上了」,而把它折成 `persisted` 会让治理面宣布一条**可能根本不存在**的收紧。
     const status = res?.status;
     const rev = res?.rev;
     const row = res?.rule;
@@ -610,12 +332,6 @@ export async function writePersistedRule(facade, input, opts) {
             message: 'the rule write answered 2xx with a body this client cannot read (status, rev or the written row) — refusing to certify it as a standing rule; re-list the rules to reconcile',
         };
     }
-    // 🔴 **身份对账**(异源复审 R1 [high],真病):上面那道门只问「这一行读得出来吗」(与列举面同一只
-    //    窄化器、同一个问题);这一道问的是**另一个**问题 ——「读出来的这一行是不是我刚才要写的那条」。
-    //    规则的身份是**三元组**,同文本不同态是两条不同的行:一个缺了态、回了兄弟态、或回了另一条文本的
-    //    200 若被认成 `persisted`,调用方会对人宣布一条根本没落地的收紧。
-    //    ⚠️ 列举面**刻意**把态读不出的行照样交出去(丢行 = 藏起一条活规则),那条纪律在这里不适用:
-    //    「看得见」与「证明得了」是两件事,两个问题各有各的门,不是一份判据的两个法官。
     const landed = row;
     if (landed.behavior !== behavior || landed.rule !== rule || landed.scope !== scope) {
         return {
@@ -625,20 +341,11 @@ export async function writePersistedRule(facade, input, opts) {
         };
     }
     return {
-        // wire 的 `no-op` 与本包判别联合的 `no_op` 是同一件事的两种拼法;判别位在这里归一**一次**,
-        // 三端各拼一次的那天会长出两种写法。
         status: status === 'persisted' ? 'persisted' : 'no_op',
         rev,
         rule: row,
     };
 }
-// ── skipped.reason 分类 ─────────────────────────────────────────────────────────────────────
-/**
- * `skipped[].reason` 的分类。**只按第一个 `:` 前缀**,且必须容得下**没有前缀**的两种真值形
- * (整层 JSON 解不开 / 条目不是串)——SDK 头注逐字:reason 是给人看的散文,不是机读码,
- * 全串等值匹配与「裸码」两种读法都会漂。
- * 前缀形判据刻意保守(`RuleRejectCode` 形:小写 + 点/下划线),防把散文里的第一个冒号误读成码。
- */
 export function classifySkippedReason(reason) {
     const text = typeof reason === 'string' ? reason : String(reason);
     const idx = text.indexOf(':');
@@ -649,22 +356,6 @@ export function classifySkippedReason(reason) {
         return { text };
     return { code: head, text };
 }
-/**
- * respond 回执上「不再询问到底存上了没」的**结构化读口**。
- *
- * 🔴 **单一台账**(A-028.14 收口本体):`rulePersisted` / `ruleRefusal` 的结构窄化只有
- * {@link readToolApprovalRespondAck} 这一份 —— 本函数不对 wire 原料二次开读,ack 过不了包内
- * 结构门(缺 `delivery:'applied'` / `approvalId` / 三词闭集 `decision`)⇒ **`unknown`**:
- * 一张连回执身份都不成形的 ack,不配驱动一行「已保存」的用户告知(诚实缺席优先)。
- * 收口前 cli 的裸读会把 `{rulePersisted:true}` 这类半形对象读成 `persisted` —— 那正是双份台账
- * 各漂各的形,常驻套对这一格有反向钉。
- *
- * 🔴 `rulePersisted` 缺席 ≠ `false`(未带 persistRule 的回决 / 旧 server ⇒ 字段省略);
- * 🔴 规则没存上**从不翻转裁决** —— 200 + `rulePersisted:false` + `ruleRefusal` 是诚实形,
- * 宿主只说「这次放行了,但『不再询问』没存上」,绝不渲成整次审批失败。
- * 🔴 `rule_lane_unavailable` **四种成因共用一格、两种是本卡局限** ⇒ 禁据一帧判断整台部署的车道
- * 在不在(那要看能力位)。
- */
 export function readRulePersistOutcome(ack) {
     const parsed = readToolApprovalRespondAck(ack);
     if (parsed === undefined)
@@ -672,7 +363,6 @@ export function readRulePersistOutcome(ack) {
     if (parsed.rulePersisted === true)
         return { state: 'persisted' };
     if (parsed.rulePersisted === false) {
-        // 空串/非串已在 readToolApprovalRespondAck 降缺席(单一台账),这里只剩「在场即带」。
         return {
             state: 'refused',
             ...(typeof parsed.ruleRefusal === 'string' ? { reason: parsed.ruleRefusal } : {}),