@sema-agent/client-core 0.77.0 → 0.77.2

package/dist/memoryEntriesWire.d.ts

@@ -1,78 +1,12 @@
-/**
- * memoryEntriesWire — 记忆**条目面**三个 200 回体的三端共用**窄读口**(0.76.1 CC-97a):
- *   ① `GET  /v1/memory/export?scope=` 的条目行(`{ scope, exportedAt, entries[] }`);
- *   ② `POST /v1/memory/erase` 的**抹除证明**回体;
- *   ③ `POST /v1/memory/origin/entries/:entryId/clear` 的**清标回执**。
- *
- * 🔴 本件只有**读口**:一个动词都不调、一个请求都不铸(动词半场另票)。入参一律 `unknown` —— 三个回体在
- *    wire 上要么是开放判别式(引擎原样下发、不投影、不复述),要么 SDK 的声明形里就是 `unknown[]`,
- *    所以边界必须**按结构**窄读。
- *
- * ── 逐行窄读的三条边界(与本包既有行读口同律)────────────────────────────────────────────────
- *  · **空数组 = 真 0**(引擎明说「一条都没有」);
- *  · **非空数组却一行都读不出 ⇒ `malformed`**(这一眼没看成),**绝不**答「present + 空列表」——
- *    那是把「取不到」冒充「一条都没有」;
- *  · **半坏 ⇒ `present` + `dropped` 计数**(读得出来的行是真的,丢掉那几条如实交代)。
- *  🔴 「读不懂的行」与「没有行」在本件里**永远不共用一句话**。
- *
- * ── 🔴 「空答不等于本店干净」在代码里的落点 ─────────────────────────────────────────────────
- * 导出读口的答案在两条轴上都不完备,而**两条都不是本包能推翻的**:
- *  · **scope 轴**:引擎 v1 没有 scope 枚举读面,一次答案只覆盖调用方点名的那一个 scope ⇒
- *    {@link scopeExternalOriginVerdict} 的肯定臂叫 `none_in_this_scope` **并且带着那个 scope 串**,
- *    联合里**没有**任何「整店」臂 —— 想把它复述成全店结论,型上就写不出来。
- *  · **围栏轴**:这条读口**缺省不投带外源标的条目**(整条目扣留 + 只在 n>0 时铸一格计数),调用方须在
- *    请求上显式声明认识 origin 键族才放行。回体在两种情形下**形状完全一样** ⇒ 读口光看回体
- *    **判不出**围栏开没开 ⇒ {@link scopeExternalOriginVerdict} 的第二个形参是**必填**的
- *    `{ originAware }`:没声明过 ⇒ 空答一律 `unknown`(`why: 'fenced'`),一个字的「干净」都不给。
- *
- * ── UNTRUSTED ───────────────────────────────────────────────────────────────────────────────
- * slug / scope / reason / origin 载体都是引擎侧与用户侧的内容,只渲染绝不当代码用;本件不 trim、不截、
- * 不改写任何原文字节。
- */
-/**
- * 一行的**外源标记**读数(三态,刻意不是布尔):
- *  · `'marked'`      两个**结构**载体之一在场 —— 行顶层 `origin`,或 `frontmatter.origin`
- *                    (`hasOwn` 且值非 `undefined` 即算在场:值的内部形不读,坏形也算带标 —— 在保护轴上
- *                    「读不出的载体」只许当带标);
- *  · `'unmarked'`    两个结构载体都不在场,且这一行**没有第三载体**;
- *  · `'undecidable'` 判不出 —— `frontmatter` 整个读不懂(缺席 / 非对象 / 数组),或**第三载体**
- *                    (`frontmatter.extra` 里的悬置形行)在场。第三载体要引擎侧那只归一化判官才判得了,
- *                    🔴 本包**不铸第二份**:给同一条判据立第二个判官,两边都会「绿」而结论可以相反。
- *                    `extra` 在场就判不出 = 故意的**过近似**(安全方向),代价是这一行进不了肯定臂。
- */
 export type MemoryEntryOriginMark = 'marked' | 'unmarked' | 'undecidable';
-/** 一条读得懂的导出条目行(窄读后的形;键集即全部)。正文与 frontmatter 的内部形**不过境**(要它们的端直接读原回体)。 */
 export interface MemoryExportEntryRow {
-    /** 不随改名变的条目身份。 */
     id: string;
-    /** 文件名身份(可改名)。 */
     slug: string;
-    /** 归属 scope。 */
     scope: string;
-    /** CAS 基线。 */
     rev: string;
-    /** 这一行的外源标记读数。 */
     originMark: MemoryEntryOriginMark;
 }
-/** {@link readMemoryExportRows} 判「这一眼没看成」的成因(逐个分开,🔴 不许折成同一句话)。 */
-export type MemoryExportUnreadableCause = 
-/** 回体不是对象(`null` / 数组 / 串 / 数),或读它抛。 */
-'body_unreadable'
-/** 对象在场,但 `entries` 键**整个不在** —— 「200 空体」落这里,**不是**「这个 scope 没有条目」。 */
- | 'envelope_absent'
-/** 信封键在场但形不对:`entries` 非数组或长度读不出,或 `scope` / `exportedAt` 不是非空串(行清单没有它归属的 scope 就判不了 scope 级的话)。 */
- | 'envelope_unreadable'
-/** `entries` 自报的行数超过本读口一口能吃下的量 ⇒ 判读不出,🔴 **绝不**静默截断成前 N 行。 */
- | 'too_many_rows'
-/** `entries` 非空却一行都读不出。 */
- | 'rows_unreadable';
-/**
- * `GET /v1/memory/export?scope=` 的 200 体读数。
- * `withheldOriginTagged` 三态:`number` = 引擎明说因围栏扣留了这么多条(**肯定**的外源存在证据);
- * `'unreadable'` = 这一格在场但读不懂;`null` = 键缺席 —— 引擎**只在扣留数 >0 时**铸这一键,所以缺席
- * 读作「这一答没有条目被围栏扣掉」;🔴 但判词口**不靠**这条推论作肯定结论(见 {@link scopeExternalOriginVerdict})。
- * `truncated`:键缺席或显式 `false` ⇒ `false`;**其余一律 `true`** —— 完备性轴上读不懂只许 fail-closed。
- */
+export type MemoryExportUnreadableCause = 'body_unreadable' | 'envelope_absent' | 'envelope_unreadable' | 'too_many_rows' | 'rows_unreadable';
 export type MemoryExportReading = {
     kind: 'malformed';
     why: MemoryExportUnreadableCause;
@@ -81,62 +15,27 @@ export type MemoryExportReading = {
     scope: string;
     exportedAt: string;
     rows: MemoryExportEntryRow[];
-    /** 读不出而丢掉的行数(含同 `id` 重复行)。 */
     dropped: number;
     withheldOriginTagged: number | 'unreadable' | null;
     truncated: boolean;
-    /** 续页游标(非空串才带,否则 `null`);不解析、不自铸。 */
     nextBefore: string | null;
 };
-/**
- * `GET /v1/memory/export?scope=` 的 200 体 → 条目行读数。四把承重键(`id` / `slug` / `scope` / `rev`)
- * 任一读不出的行丢弃并计数;同 `id` 的重复行留第一条(后面的计入 `dropped`)。永不抛。
- */
 export declare function readMemoryExportRows(body: unknown): MemoryExportReading;
-/**
- * {@link scopeExternalOriginVerdict} 的判词。🔴 联合里**没有**任何「整店」臂:肯定的否定话最远只能说到
- * **调用方点名的那一个 scope**,而且那个 scope 串必须跟着一起交出去。
- */
-export type ScopeExternalOriginVerdict = 
-/** 判不出。`why` 逐条分开,消费端据它决定下一步(补 `originAware` / 翻页 / 重取 / 去问引擎侧判官)。 */
-{
+export type ScopeExternalOriginVerdict = {
     kind: 'unknown';
     why: 'unreadable' | 'fenced' | 'withheld_unreadable' | 'truncated' | 'rows_dropped' | 'undecidable_rows';
-}
-/** **肯定有**外源标记条目:`visible` = 这一答里读得出的带标行数,`withheld` = 引擎明说被围栏扣掉的条数(读不出时 `null`)。 */
- | {
+} | {
     kind: 'marked';
     scope: string;
     visible: number;
     withheld: number | null;
-}
-/** 这**一个** scope 里没有外源标记条目 —— 对别的 scope 一个字都没说(引擎 v1 没有 scope 枚举读面)。 */
- | {
+} | {
     kind: 'none_in_this_scope';
     scope: string;
 };
-/**
- * 「这个 scope 里有没有外源标记的条目」的判据单源。
- *
- * 🔴 `asked.originAware` **必填**,且只有它为 `true` 时否定臂才够得着:这条读口缺省围栏掉所有带标条目,
- *    而回体在「围栏开」与「围栏关」两种情形下**形状一样** —— 读口自己判不出,只有发请求的人知道。
- *    没声明 ⇒ 空答一律 `unknown`(`why: 'fenced'`)。这就是「空答绝不读作本店干净」的**代码**落点。
- * 判序(肯定证据先行,否定证据要完备):
- *  ① 回体读不懂 ⇒ `unknown`;
- *  ② 读得出的带标行 >0,**或**引擎明说扣留了 >0 条 ⇒ `marked`(围栏只扣带标条目,所以那个计数本身就是
- *     肯定证据;此时翻页 / 丢行都不影响这句肯定话);
- *  ③ 扣留计数在场但读不懂 ⇒ `unknown`(可能扣了,也可能没扣);
- *  ④ 否定臂的三道完备性闸:没声明 `originAware` ⇒ `'fenced'`;`truncated` ⇒ `'truncated'`;
- *     有丢行 ⇒ `'rows_dropped'`;有判不出标记的行 ⇒ `'undecidable_rows'`;
- *  ⑤ 全过 ⇒ `none_in_this_scope`(带 scope 串)。
- */
 export declare function scopeExternalOriginVerdict(reading: MemoryExportReading, asked: {
     originAware: boolean;
 }): ScopeExternalOriginVerdict;
-/**
- * 一条已抹除行的**绑定坐标**(上游的判别式,原样对形):`bound` = 它当时落在哪个 scope 的哪个文件名身份上;
- * `unbound` = 它当时没有投影。写成具名型而不是内联匿名形:这一格会被端逐臂分支渲染,匿名形让每个端各自手抄一遍。
- */
 export type MemoryErasedBinding = {
     state: 'bound';
     scope: string;
@@ -144,76 +43,32 @@ export type MemoryErasedBinding = {
 } | {
     state: 'unbound';
 };
-/** 一条**已抹除**行。`binding` 为 `null` = 这一格读不出 —— 🔴 绝不当 `{state:'unbound'}`(那是一句肯定话)。 */
 export interface MemoryErasedRow {
     id: string;
     rev: string;
     binding: MemoryErasedBinding | null;
 }
-/**
- * 一条 **notFound** 行:判决那一刻没有这条记录,而且这次请求也不能把它算作「抹掉了」。
- * `historyUnknown` **四态原样过境**:
- *  · `true`         引擎如实标「分不清从没存在过还是早已被抹掉」;
- *  · `false`        位显式为假(上游今日的形里只铸 `true` 或整键省掉,真出现那天照原样带);
- *  · `null`         **键缺席**(上游的铸点纪律 ⇒ 这是一句真判断:链完整,没有洞);
- *  · `'unreadable'` 位在场**但读不懂**(串 / 数 / `null` …)—— 行不丢(`id` 是承重键),坏的只有这一格。
- * 🔴 四态一格都不许折进另一格:把「读不懂」折进「键缺席」,历史判词就会答出一句它没资格答的话。
- */
 export interface MemoryEraseNotFoundRow {
     id: string;
     historyUnknown: boolean | null | 'unreadable';
 }
-/** 一条**先前已抹除**行(只窄读身份;这一段只在非空时上 wire)。 */
 export interface MemoryErasePreviouslyRow {
     id: string;
 }
-/** 一条**冲突**行(逐 id 的计划期故障;`reason` 是给人看的散文,原样带出)。 */
 export interface MemoryEraseConflictRow {
     id: string;
     reason: string;
 }
-/** {@link readMemoryEraseReceipt} 判「这一眼没看成」的成因。🔴 逐条分开 —— 尤其「200 空体」与「读不懂」不共形。 */
-export type MemoryEraseUnreadableCause = 
-/** 回体不是对象(`null` / 数组 / 串 / 数),或读它抛。 */
-'body_unreadable'
-/** 对象在场,但一把信封键都不在 —— **「200 空体」落这里**,🔴 绝不是「抹了 0 条」。 */
- | 'envelope_absent'
-/** 版本信封缺席:没有它就不知道自己在读哪一版契约。 */
- | 'version_absent'
-/** 版本信封不是本包认得的那一版 —— 🔴 上游明令「读到更高版本必须拒,绝不重解释」。 */
- | 'unsupported_version'
-/** 信封键在场但形不对:身份不是非空串,三段不是数组或长度读不出,或三张**闭合**词表里出现了本包不认得的词(新词判读不出,绝不塌进已知臂)。 */
- | 'envelope_unreadable'
-/** 某一段自报的行数超过本读口一口能吃下的量 ⇒ 判读不出,🔴 **绝不**静默截断。 */
- | 'too_many_rows'
-/** `erased` 非空却一行都读不出。 */
- | 'erased_rows_unreadable'
-/** `notFound` 非空却一行都读不出。 */
- | 'not_found_rows_unreadable'
-/** `conflicts` 非空却一行都读不出。 */
- | 'conflict_rows_unreadable'
-/** `erasedPreviously` 在场且非空,却一行都读不出(与另外三段同律)。 */
- | 'erased_previously_rows_unreadable';
-/**
- * `POST /v1/memory/erase` 的 200 体读数(引擎原样下发上游的抹除证明,本包按结构窄读)。
- * 三张词表(`status` / `evidenceCapability` / `custodyState`)是上游声明的**闭集**:出现本包不认得的词
- * ⇒ `malformed`(`envelope_unreadable`),🔴 绝不塌进任何一个已知臂。
- * `erasedPreviously` 为 `null` = 键缺席(上游只在非空时铸它)。
- */
+export type MemoryEraseUnreadableCause = 'body_unreadable' | 'envelope_absent' | 'version_absent' | 'unsupported_version' | 'envelope_unreadable' | 'too_many_rows' | 'erased_rows_unreadable' | 'not_found_rows_unreadable' | 'conflict_rows_unreadable' | 'erased_previously_rows_unreadable';
 export type MemoryEraseReceiptReading = {
     kind: 'malformed';
     why: MemoryEraseUnreadableCause;
 } | {
     kind: 'present';
-    /** 调用方自铸的幂等身份,原样带出(引擎从不替人铸)。 */
     requestId: string;
-    /** `complete` = 每个点名的 id 都有了归宿;`partial` = 还有没落地的(重放会收敛)。 */
     status: 'complete' | 'partial';
-    /** `journal` = 证据腿;`none` = 显式降级腿(静默降级是被禁的形,所以这一格恒在场)。 */
     evidenceCapability: 'journal' | 'none';
-    /** 证据链在装配那一刻的完整性;`damaged` ⇒ 每条 notFound 行都带 `historyUnknown`。 */
     custodyState: 'complete' | 'damaged' | 'capability-absent';
-    /** 被钉住的 id 总数(读不出 ⇒ `null`,绝不折 0)。 */
     selectedIds: number | null;
     erased: MemoryErasedRow[];
     erasedDropped: number;
@@ -224,13 +79,7 @@ export type MemoryEraseReceiptReading = {
     conflicts: MemoryEraseConflictRow[];
     conflictsDropped: number;
 };
-/**
- * `POST /v1/memory/erase` 的 200 体 → 抹除证明读数。永不抛。
- * 🔴 三件必须判成**三回事**:「这一次一条都没抹掉」(`present` 且 `erased` 空)/「200 空体」
- * (`malformed` / `envelope_absent`)/「回体读不懂」(`malformed` / `body_unreadable`)。
- */
 export declare function readMemoryEraseReceipt(body: unknown): MemoryEraseReceiptReading;
-/** {@link memoryEraseCounts} 的判决体。🔴 `unknown` 与「数出来是 0」是两回事。 */
 export type MemoryEraseCounts = {
     kind: 'unknown';
     why: MemoryEraseUnreadableCause | 'rows_dropped';
@@ -239,64 +88,23 @@ export type MemoryEraseCounts = {
     erased: number;
     notFound: number;
     conflicts: number;
-    /** 键缺席 ⇒ `null`(上游只在非空时铸这一段),绝不折 0。 */
     erasedPreviously: number | null;
-    /** 被钉住的 id 总数;读不出 ⇒ `null`。 */
     selectedIds: number | null;
 };
-/**
- * 「这一次抹了几条」的判据单源。
- * 🔴 读不懂 ⇒ `unknown` + 原成因(**绝不**答 0);任何一段有丢行 ⇒ `unknown` / `'rows_dropped'`
- * (读得出的行是真的,但这几个**数**已经不是引擎给的那几个了)。
- */
 export declare function memoryEraseCounts(reading: MemoryEraseReceiptReading): MemoryEraseCounts;
-/**
- * 「这一次是不是一条都没抹掉」的三态判据单源。
- * 🔴 `'yes'` **只**由「数得出来、且已抹除段为空」铸得出(典型形 = 已抹除段空、notFound 段非空 ——
- * 逐 id 交代了为什么一条都没删)。「200 空体」/「回体读不懂」/「有丢行」一律 `'unknown'`,
- * 绝不与 `'yes'` 同形:把取不到冒充「零抹除」,端会据此告诉人「什么都没删」。
- */
 export declare function memoryEraseErasedNothing(reading: MemoryEraseReceiptReading): 'yes' | 'no' | 'unknown';
-/**
- * 一条 notFound 行的历史判词(两态)。🔴 联合里**没有**「从来没存在过」这一臂:上游明说这份证明
- * **不区分**「从没存在过」/「自然删掉了」/「别的请求删的」三义,只有证据链本身分得清。
- * `'unknown'` = 行上明标判不清;`'no_row_at_judgment'` = 判决那一刻没有这条记录 ——
- * 🔴 它也**不**授权任何人说「这条从来不存在」。
- */
 export declare function eraseNotFoundHistoryVerdict(row: MemoryEraseNotFoundRow): 'no_row_at_judgment' | 'unknown';
-/**
- * 「同一个 `requestId` 重发这一口安不安全」的判据单源(三态)。
- *  · `'idempotent'`     证据腿:重发读回被钉住的 id 集,绝不重新解析;
- *  · `'human_decision'` 降级腿:同一个 `requestId` 是**一次新的请求**(重新解析),重发就是第二次真删 ⇒
- *    任何重试都必须是人做的决定,🔴 不许进自动重试策略;
- *  · `'unknown'`        收执读不出 —— 读不出时**不**当幂等(那是最贵的一种猜)。
- */
 export declare function memoryEraseReplayPosture(reading: MemoryEraseReceiptReading): 'idempotent' | 'human_decision' | 'unknown';
-/** {@link readMemoryOriginClearanceReceipt} 判「这一眼没看成」的成因。 */
-export type MemoryOriginClearanceUnreadableCause = 
-/** 回体不是对象,或读它抛。 */
-'body_unreadable'
-/** 对象在场,但三把承重键一把都不在(「200 空体」落这里)。 */
- | 'envelope_absent'
-/** 承重键在场但不是非空串。 */
- | 'envelope_unreadable';
-/**
- * `POST /v1/memory/origin/entries/:entryId/clear` 的 200 体读数(引擎原样下发上游回执)。
- * `origin` = **被清掉的那个标**,开放形 ⇒ 原样带出、一个字不窄读(它的判官在引擎侧);
- * `originReported` 说这一格在不在 —— 🔴 缺席时 `origin` 是 `undefined`,别把它读成「没有标」。
- */
+export type MemoryOriginClearanceUnreadableCause = 'body_unreadable' | 'envelope_absent' | 'envelope_unreadable';
 export type MemoryOriginClearanceReading = {
     kind: 'malformed';
     why: MemoryOriginClearanceUnreadableCause;
 } | {
     kind: 'present';
     entryId: string;
-    /** 这次清标的账本身份(与部署侧审计行按它 join)。 */
     clearanceId: string;
-    /** 清标后条目落在哪个文件名身份上(清标可能连带改名)。 */
     landedSlug: string;
     originReported: boolean;
     origin: unknown;
 };
-/** `POST …/origin/entries/:entryId/clear` 的 200 体 → 清标回执读数。永不抛。 */
 export declare function readMemoryOriginClearanceReceipt(body: unknown): MemoryOriginClearanceReading;

package/dist/memoryEntriesWire.js

@@ -1,67 +1,16 @@
-/**
- * memoryEntriesWire — 记忆**条目面**三个 200 回体的三端共用**窄读口**(0.76.1 CC-97a):
- *   ① `GET  /v1/memory/export?scope=` 的条目行(`{ scope, exportedAt, entries[] }`);
- *   ② `POST /v1/memory/erase` 的**抹除证明**回体;
- *   ③ `POST /v1/memory/origin/entries/:entryId/clear` 的**清标回执**。
- *
- * 🔴 本件只有**读口**:一个动词都不调、一个请求都不铸(动词半场另票)。入参一律 `unknown` —— 三个回体在
- *    wire 上要么是开放判别式(引擎原样下发、不投影、不复述),要么 SDK 的声明形里就是 `unknown[]`,
- *    所以边界必须**按结构**窄读。
- *
- * ── 逐行窄读的三条边界(与本包既有行读口同律)────────────────────────────────────────────────
- *  · **空数组 = 真 0**(引擎明说「一条都没有」);
- *  · **非空数组却一行都读不出 ⇒ `malformed`**(这一眼没看成),**绝不**答「present + 空列表」——
- *    那是把「取不到」冒充「一条都没有」;
- *  · **半坏 ⇒ `present` + `dropped` 计数**(读得出来的行是真的,丢掉那几条如实交代)。
- *  🔴 「读不懂的行」与「没有行」在本件里**永远不共用一句话**。
- *
- * ── 🔴 「空答不等于本店干净」在代码里的落点 ─────────────────────────────────────────────────
- * 导出读口的答案在两条轴上都不完备,而**两条都不是本包能推翻的**:
- *  · **scope 轴**:引擎 v1 没有 scope 枚举读面,一次答案只覆盖调用方点名的那一个 scope ⇒
- *    {@link scopeExternalOriginVerdict} 的肯定臂叫 `none_in_this_scope` **并且带着那个 scope 串**,
- *    联合里**没有**任何「整店」臂 —— 想把它复述成全店结论,型上就写不出来。
- *  · **围栏轴**:这条读口**缺省不投带外源标的条目**(整条目扣留 + 只在 n>0 时铸一格计数),调用方须在
- *    请求上显式声明认识 origin 键族才放行。回体在两种情形下**形状完全一样** ⇒ 读口光看回体
- *    **判不出**围栏开没开 ⇒ {@link scopeExternalOriginVerdict} 的第二个形参是**必填**的
- *    `{ originAware }`:没声明过 ⇒ 空答一律 `unknown`(`why: 'fenced'`),一个字的「干净」都不给。
- *
- * ── UNTRUSTED ───────────────────────────────────────────────────────────────────────────────
- * slug / scope / reason / origin 载体都是引擎侧与用户侧的内容,只渲染绝不当代码用;本件不 trim、不截、
- * 不改写任何原文字节。
- */
 function nonEmptyString(v) {
     return typeof v === 'string' && v !== '';
 }
 function nonNegativeInt(v) {
     return typeof v === 'number' && Number.isFinite(v) && v >= 0 && Number.isInteger(v);
 }
-/** 对象(不含 `null` / 数组)。三个读口的每一层都用它,免得某一层悄悄把数组当对象读。 */
 function plainObject(v) {
     return v !== null && typeof v === 'object' && !Array.isArray(v);
 }
-/** `hasOwn` 且值非 `undefined`。原型链同名键永远不会被序列化上 wire,读成在场就是凭空造一格。 */
 function ownPresent(o, k) {
     return Object.hasOwn(o, k) && o[k] !== undefined;
 }
-/**
- * 一段数组能窄读的**行数上限**。超过它 ⇒ 判 `too_many_rows`(读不出),🔴 **绝不**静默截断成前 N 行 ——
- * 截断出来的「这一答里没有带标行」正是本件要消灭的那句假话。这个数只表达「本读口一口吃不下这么多」,
- * 不是对引擎的任何限额主张;它同时挡住「回体自报一个天文数字长度」把读口挂住那一形。
- */
 const MAX_NARROWED_ROWS = 100_000;
-/**
- * 把不可信的数组**一次性快照**成定长普通数组。
- *
- * 🔴 为什么不能直接 `for…of` 原数组(异源对抗复审 R1 [high],已实测复现):
- *  ① `for…of` 走的是**调用方的** `Symbol.iterator`,它的陷阱抛出会从循环**外**逸出(循环体内的 try 接不到),
- *     整只读口就抛了 —— 而本件承诺永不抛;
- *  ② `length` 会被**反复读**(迭代一次、循环后的「非空全坏」判据再一次):一个首次报 2、之后报 0 的 Proxy
- *     能让循环只走第一格(无标行)而末尾判据看到 0 ⇒ 带标的那一行被丢掉、`dropped` 还是 0 ⇒ 判词口一路走到
- *     `none_in_this_scope`。**把「看不见」渲成「没有」**,正是本件的头号禁形。
- * 所以:`length` **只读一次**并验型,再按**固定索引**各读一次;某一格读不出只记 `unreadable`(它在行层计入
- * `dropped`,于是判词口的否定臂当场失去资格),不作废整段、也不外抛。
- * 返回 `null` = 这一段整个读不出(不是数组 / 长度读不出或不是安全非负整数 / 超过 {@link MAX_NARROWED_ROWS})。
- */
 function snapshotArray(v) {
     if (!Array.isArray(v))
         return null;
@@ -88,18 +37,12 @@ function snapshotArray(v) {
     }
     return { items, unreadable, tooLarge: false };
 }
-/** 数组的**元素个数**(只用于「被钉住的 id 总数」这类纯计数位):读不出 ⇒ `null`,🔴 绝不折 0。 */
 function arrayLengthOrNull(v) {
     const snap = snapshotArray(v);
     if (snap === null || snap.tooLarge)
         return null;
     return snap.items.length + snap.unreadable;
 }
-/**
- * 一行的外源标记三态判定。**每个键只读一次**(变化的 getter 不许让两次读看到两个值)。
- * 载体顺序与保护方向:结构载体命中即 `'marked'`(最强的肯定);`frontmatter` 读不懂 ⇒ 判不出;
- * 第三载体在场 ⇒ 判不出(判官在引擎侧)。
- */
 function originMarkOf(row) {
     if (ownPresent(row, 'origin'))
         return 'marked';
@@ -112,10 +55,6 @@ function originMarkOf(row) {
         return 'undecidable';
     return 'unmarked';
 }
-/**
- * `GET /v1/memory/export?scope=` 的 200 体 → 条目行读数。四把承重键(`id` / `slug` / `scope` / `rev`)
- * 任一读不出的行丢弃并计数;同 `id` 的重复行留第一条(后面的计入 `dropped`)。永不抛。
- */
 export function readMemoryExportRows(body) {
     let o;
     let rawEntries;
@@ -130,15 +69,11 @@ export function readMemoryExportRows(body) {
         if (!plainObject(body))
             return { kind: 'malformed', why: 'body_unreadable' };
         o = body;
-        // 🔴 每把键**恰读一次**并就地快照:回体可以是带 getter / Proxy 的对象,读两次就能拿到两个不同的答案。
         if (!Object.hasOwn(o, 'entries'))
             return { kind: 'malformed', why: 'envelope_absent' };
         rawEntries = o.entries;
         rawScope = o.scope;
         rawExportedAt = o.exportedAt;
-        // 🔴 这两格的在场判据与取值也**分开**(与 `historyUnknown` 同一条采修的族扫):键在场而值读不成时,
-        //    折回「键缺席」会在**完备性轴**上给出更宽松的答案(缺席 = 没扣留 / 缺席 = 这就是全量),而那正是
-        //    这两格存在的意义 —— 在场读不成必须走各自的 fail-closed 臂。
         hasWithheld = Object.hasOwn(o, 'withheldOriginTagged');
         rawWithheld = hasWithheld ? o.withheldOriginTagged : undefined;
         hasTruncated = Object.hasOwn(o, 'truncated');
@@ -146,13 +81,10 @@ export function readMemoryExportRows(body) {
         rawNextBefore = o.nextBefore;
     }
     catch {
-        // 读回体的 getter / Proxy 陷阱抛出 = 这一眼没看成(与「不是对象」同一处置);绝不外抛。
         return { kind: 'malformed', why: 'body_unreadable' };
     }
     if (rawEntries === undefined)
         return { kind: 'malformed', why: 'envelope_absent' };
-    // 🔴 数组**一次快照**(见 {@link snapshotArray} 头注:`for…of` 的迭代器陷阱会从循环外逸出,反复读的 `length`
-    //    能让带标行被丢掉而这一答被判成「干净」)。快照本身也在保护里 —— 它读的是不可信对象。
     let snap;
     try {
         snap = snapshotArray(rawEntries);
@@ -169,7 +101,6 @@ export function readMemoryExportRows(body) {
     }
     const rows = [];
     const seen = new Set();
-    // 读不出的那几格先记进 dropped:它们是**真的丢了行**,判词口的否定臂据此当场失去资格。
     let dropped = snap.unreadable;
     for (const item of snap.items) {
         let row = null;
@@ -194,14 +125,11 @@ export function readMemoryExportRows(body) {
             row = { id, slug, scope, rev, originMark: originMarkOf(item) };
         }
         catch {
-            // 单行的抛 getter 只丢这一行(与坏形行同一处置),不作废整段。
             dropped++;
             continue;
         }
         rows.push(row);
     }
-    // 🔴 非空数组、却一行都读不出 ⇒ `malformed`:那不是「这个 scope 一条都没有」。空数组不在本条射程。
-    //    判据锚在**快照**上(`snap.items.length + snap.unreadable`),不再回头读原数组的 length。
     const seenRows = snap.items.length + snap.unreadable;
     if (seenRows > 0 && rows.length === 0)
         return { kind: 'malformed', why: 'rows_unreadable' };
@@ -212,30 +140,11 @@ export function readMemoryExportRows(body) {
         rows,
         dropped,
         withheldOriginTagged: !hasWithheld ? null : nonNegativeInt(rawWithheld) ? rawWithheld : 'unreadable',
-        // 完备性轴 fail-closed:只有**键缺席**与**显式 `false`** 算「这就是全量」;键在场而值读不成 ⇒ 当成不是全量。
         truncated: hasTruncated ? rawTruncated !== false : false,
         nextBefore: nonEmptyString(rawNextBefore) ? rawNextBefore : null,
     };
 }
-/**
- * 「这个 scope 里有没有外源标记的条目」的判据单源。
- *
- * 🔴 `asked.originAware` **必填**,且只有它为 `true` 时否定臂才够得着:这条读口缺省围栏掉所有带标条目,
- *    而回体在「围栏开」与「围栏关」两种情形下**形状一样** —— 读口自己判不出,只有发请求的人知道。
- *    没声明 ⇒ 空答一律 `unknown`(`why: 'fenced'`)。这就是「空答绝不读作本店干净」的**代码**落点。
- * 判序(肯定证据先行,否定证据要完备):
- *  ① 回体读不懂 ⇒ `unknown`;
- *  ② 读得出的带标行 >0,**或**引擎明说扣留了 >0 条 ⇒ `marked`(围栏只扣带标条目,所以那个计数本身就是
- *     肯定证据;此时翻页 / 丢行都不影响这句肯定话);
- *  ③ 扣留计数在场但读不懂 ⇒ `unknown`(可能扣了,也可能没扣);
- *  ④ 否定臂的三道完备性闸:没声明 `originAware` ⇒ `'fenced'`;`truncated` ⇒ `'truncated'`;
- *     有丢行 ⇒ `'rows_dropped'`;有判不出标记的行 ⇒ `'undecidable_rows'`;
- *  ⑤ 全过 ⇒ `none_in_this_scope`(带 scope 串)。
- */
 export function scopeExternalOriginVerdict(reading, asked) {
-    // 🔴 入口先核 `asked`(0.77.0;外部验收方 F-A):此前只有「干净答案」那条路才读 `asked.originAware`,JS 宿主漏传第二形参会一路顺跑、
-    //    第一次遇到干净的店才炸,而那恰是这道围栏存在的理由。防御方向不改(缺席绝不折成「干净」),改的是把裸属性访问的 TypeError
-    //    换成具名、可解释的错误,并且**每条路**都在入口就问一次 —— 不让「什么时候炸」取决于回体形状。
     if (asked === null || typeof asked !== 'object' || typeof asked.originAware !== 'boolean') {
         throw new TypeError('scopeExternalOriginVerdict: second argument { originAware: boolean } is required — this export read withholds origin-tagged ' +
             'entries unless the request declared originAware=1, and an empty answer without that declaration must never be read as "clean"');
@@ -265,12 +174,7 @@ export function scopeExternalOriginVerdict(reading, asked) {
     }
     return { kind: 'none_in_this_scope', scope: reading.scope };
 }
-/** 本包认得的抹除证明版本信封(上游明写「读到更高版本必须拒,绝不重解释」)。 */
 const MEMORY_ERASE_RECEIPT_VERSION = 1;
-/**
- * 三张**闭合**词表各自的窄读器 —— 认得的词原样带出,🔴 别的一律 `null`(读不出),绝不塌进已知臂。
- * 写成三只小函数而不是三个 `Set` + 断言:词表与返回型在这里是**同一处**声明,加词只能在这一行加。
- */
 function eraseStatusOf(v) {
     return v === 'complete' || v === 'partial' ? v : null;
 }
@@ -280,7 +184,6 @@ function eraseEvidenceCapabilityOf(v) {
 function eraseCustodyStateOf(v) {
     return v === 'complete' || v === 'damaged' || v === 'capability-absent' ? v : null;
 }
-/** 一行的抹除绑定窄读:两条臂逐字对上才认,别的一律 `null`(读不出,不是 unbound)。 */
 function erasedBindingOf(v) {
     if (!plainObject(v))
         return null;
@@ -295,11 +198,6 @@ function erasedBindingOf(v) {
         return null;
     return { state: 'bound', scope, slug };
 }
-/**
- * `POST /v1/memory/erase` 的 200 体 → 抹除证明读数。永不抛。
- * 🔴 三件必须判成**三回事**:「这一次一条都没抹掉」(`present` 且 `erased` 空)/「200 空体」
- * (`malformed` / `envelope_absent`)/「回体读不懂」(`malformed` / `body_unreadable`)。
- */
 export function readMemoryEraseReceipt(body) {
     let o;
     let rawV;
@@ -317,7 +215,6 @@ export function readMemoryEraseReceipt(body) {
         if (!plainObject(body))
             return { kind: 'malformed', why: 'body_unreadable' };
         o = body;
-        // 🔴 每把键恰读一次并快照:后面所有判决都对这一份,变化的 getter 换不掉它。
         envelopeSeen = ['v', 'requestId', 'status', 'erased', 'notFound'].some((k) => Object.hasOwn(o, k));
         rawV = Object.hasOwn(o, 'v') ? o.v : undefined;
         rawRequestId = o.requestId;
@@ -333,7 +230,6 @@ export function readMemoryEraseReceipt(body) {
     catch {
         return { kind: 'malformed', why: 'body_unreadable' };
     }
-    // 「200 空体」:一把信封键都没有 ⇒ 这不是一份收执。
     if (!envelopeSeen)
         return { kind: 'malformed', why: 'envelope_absent' };
     if (rawV === undefined)
@@ -346,8 +242,6 @@ export function readMemoryEraseReceipt(body) {
     if (!nonEmptyString(rawRequestId) || status === null || evidenceCapability === null || custodyState === null) {
         return { kind: 'malformed', why: 'envelope_unreadable' };
     }
-    // 🔴 四段各自**一次快照**(理由见 {@link snapshotArray} 头注:迭代器陷阱会从循环外逸出,反复读的 `length`
-    //    能让半段行被静默丢掉而末尾「非空全坏」判据看不见)。快照与「被钉住的 id 总数」那次长度读都在保护里。
     let erasedSnap;
     let notFoundSnap;
     let conflictsSnap;
@@ -411,13 +305,6 @@ export function readMemoryEraseReceipt(body) {
                 notFoundDropped++;
                 continue;
             }
-            // 🔴 四态原样(异源对抗复审 R1 [medium] 采修 —— 修前「在场但不是布尔」与「键缺席」同形答 null,
-            //    于是一条**读不懂**历史位的行会被历史判词答成 `no_row_at_judgment`,消费端再也看不出这一格没读成):
-            //    键缺席 ⇒ `null`(上游今日只在链有洞时铸 true,不铸 false ⇒ 缺席是一句真判断)/ 严格布尔 ⇒ 原值 /
-            //    在场但不是布尔 ⇒ `'unreadable'`(行不丢:`id` 是承重键,坏的只是这一格)。
-            // 🔴 在场判据与取值**分开各读一次**(异源对抗复审 R2 [medium] 采修):把「键缺席」与「键在场但值是
-            //    `undefined`」合成一个 `raw === undefined` 判据,会让一个**在场却读不成**的历史位落回 `null`(键缺席),
-            //    历史判词随后答出 `no_row_at_judgment` 那句更强的话。`hasOwn` 不读值 ⇒ 值仍恰读一次。
             const hasHistory = Object.hasOwn(item, 'historyUnknown');
             const raw = hasHistory ? item.historyUnknown : undefined;
             notFoundSeen.add(id);
@@ -480,9 +367,6 @@ export function readMemoryEraseReceipt(body) {
                 erasedPreviouslyDropped++;
             }
         }
-        // 🔴 这一段与另外三段**同律**(异源对抗复审 R1 [medium] 采修 —— 修前这里少了这道闸,
-        //    `erasedPreviously: [null]` 会被发布成 `present` + 空列表 + dropped 1,即「一条先前抹除都没有」,
-        //    而真相是这一段一行都没读成)。
         if (previouslySnap.items.length + previouslySnap.unreadable > 0 && rows.length === 0) {
             return { kind: 'malformed', why: 'erased_previously_rows_unreadable' };
         }
@@ -505,11 +389,6 @@ export function readMemoryEraseReceipt(body) {
         conflictsDropped,
     };
 }
-/**
- * 「这一次抹了几条」的判据单源。
- * 🔴 读不懂 ⇒ `unknown` + 原成因(**绝不**答 0);任何一段有丢行 ⇒ `unknown` / `'rows_dropped'`
- * (读得出的行是真的,但这几个**数**已经不是引擎给的那几个了)。
- */
 export function memoryEraseCounts(reading) {
     if (reading.kind !== 'present')
         return { kind: 'unknown', why: reading.why };
@@ -528,41 +407,20 @@ export function memoryEraseCounts(reading) {
         selectedIds: reading.selectedIds,
     };
 }
-/**
- * 「这一次是不是一条都没抹掉」的三态判据单源。
- * 🔴 `'yes'` **只**由「数得出来、且已抹除段为空」铸得出(典型形 = 已抹除段空、notFound 段非空 ——
- * 逐 id 交代了为什么一条都没删)。「200 空体」/「回体读不懂」/「有丢行」一律 `'unknown'`,
- * 绝不与 `'yes'` 同形:把取不到冒充「零抹除」,端会据此告诉人「什么都没删」。
- */
 export function memoryEraseErasedNothing(reading) {
     const counts = memoryEraseCounts(reading);
     if (counts.kind !== 'counted')
         return 'unknown';
     return counts.erased === 0 ? 'yes' : 'no';
 }
-/**
- * 一条 notFound 行的历史判词(两态)。🔴 联合里**没有**「从来没存在过」这一臂:上游明说这份证明
- * **不区分**「从没存在过」/「自然删掉了」/「别的请求删的」三义,只有证据链本身分得清。
- * `'unknown'` = 行上明标判不清;`'no_row_at_judgment'` = 判决那一刻没有这条记录 ——
- * 🔴 它也**不**授权任何人说「这条从来不存在」。
- */
 export function eraseNotFoundHistoryVerdict(row) {
-    // 🔴 `'unreadable'` 与 `true` 同处置:这一格没读成就**没有**资格说「判决那刻没有这条记录」那句更强的话。
     return row.historyUnknown === true || row.historyUnknown === 'unreadable' ? 'unknown' : 'no_row_at_judgment';
 }
-/**
- * 「同一个 `requestId` 重发这一口安不安全」的判据单源(三态)。
- *  · `'idempotent'`     证据腿:重发读回被钉住的 id 集,绝不重新解析;
- *  · `'human_decision'` 降级腿:同一个 `requestId` 是**一次新的请求**(重新解析),重发就是第二次真删 ⇒
- *    任何重试都必须是人做的决定,🔴 不许进自动重试策略;
- *  · `'unknown'`        收执读不出 —— 读不出时**不**当幂等(那是最贵的一种猜)。
- */
 export function memoryEraseReplayPosture(reading) {
     if (reading.kind !== 'present')
         return 'unknown';
     return reading.evidenceCapability === 'journal' ? 'idempotent' : 'human_decision';
 }
-/** `POST …/origin/entries/:entryId/clear` 的 200 体 → 清标回执读数。永不抛。 */
 export function readMemoryOriginClearanceReceipt(body) {
     let o;
     let rawEntryId;
@@ -580,8 +438,6 @@ export function readMemoryOriginClearanceReceipt(body) {
         rawEntryId = o.entryId;
         rawClearanceId = o.clearanceId;
         rawLandedSlug = o.landedSlug;
-        // 🔴 `origin` **恰读一次**:先 `hasOwn` 判键在不在(不读值),再取一次值 —— 用「在场判 + 取值」两次读的写法,
-        //    变化的 getter 能让 `originReported` 说在场而 `origin` 交出 `undefined`。
         origin = Object.hasOwn(o, 'origin') ? o.origin : undefined;
         originReported = origin !== undefined;
     }