@sema-agent/client-core 0.76.0 → 0.76.1

package/dist/memoryEntriesWire.js

@@ -0,0 +1,595 @@
+/**
+ * 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;
+    let n;
+    try {
+        n = v.length;
+    }
+    catch {
+        return null;
+    }
+    if (typeof n !== 'number' || !Number.isSafeInteger(n) || n < 0)
+        return null;
+    if (n > MAX_NARROWED_ROWS)
+        return { items: [], unreadable: 0, tooLarge: true };
+    const items = [];
+    let unreadable = 0;
+    for (let i = 0; i < n; i++) {
+        try {
+            items.push(v[i]);
+        }
+        catch {
+            unreadable++;
+        }
+    }
+    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';
+    const fm = row.frontmatter;
+    if (!plainObject(fm))
+        return 'undecidable';
+    if (ownPresent(fm, 'origin'))
+        return 'marked';
+    if (ownPresent(fm, 'extra'))
+        return 'undecidable';
+    return 'unmarked';
+}
+/**
+ * `GET /v1/memory/export?scope=` 的 200 体 → 条目行读数。四把承重键(`id` / `slug` / `scope` / `rev`)
+ * 任一读不出的行丢弃并计数;同 `id` 的重复行留第一条(后面的计入 `dropped`)。永不抛。
+ */
+export function readMemoryExportRows(body) {
+    let o;
+    let rawEntries;
+    let rawScope;
+    let rawExportedAt;
+    let rawWithheld;
+    let hasWithheld;
+    let rawTruncated;
+    let hasTruncated;
+    let rawNextBefore;
+    try {
+        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');
+        rawTruncated = hasTruncated ? o.truncated : undefined;
+        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);
+    }
+    catch {
+        return { kind: 'malformed', why: 'body_unreadable' };
+    }
+    if (snap === null)
+        return { kind: 'malformed', why: 'envelope_unreadable' };
+    if (snap.tooLarge)
+        return { kind: 'malformed', why: 'too_many_rows' };
+    if (!nonEmptyString(rawScope) || !nonEmptyString(rawExportedAt)) {
+        return { kind: 'malformed', why: 'envelope_unreadable' };
+    }
+    const rows = [];
+    const seen = new Set();
+    // 读不出的那几格先记进 dropped:它们是**真的丢了行**,判词口的否定臂据此当场失去资格。
+    let dropped = snap.unreadable;
+    for (const item of snap.items) {
+        let row = null;
+        try {
+            if (!plainObject(item)) {
+                dropped++;
+                continue;
+            }
+            const id = item.id;
+            const slug = item.slug;
+            const scope = item.scope;
+            const rev = item.rev;
+            if (!nonEmptyString(id) || !nonEmptyString(slug) || !nonEmptyString(scope) || !nonEmptyString(rev)) {
+                dropped++;
+                continue;
+            }
+            if (seen.has(id)) {
+                dropped++;
+                continue;
+            }
+            seen.add(id);
+            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' };
+    return {
+        kind: 'present',
+        scope: rawScope,
+        exportedAt: rawExportedAt,
+        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) {
+    if (reading.kind !== 'present')
+        return { kind: 'unknown', why: 'unreadable' };
+    const visible = reading.rows.filter((r) => r.originMark === 'marked').length;
+    const withheld = reading.withheldOriginTagged;
+    if (visible > 0 || (typeof withheld === 'number' && withheld > 0)) {
+        return {
+            kind: 'marked',
+            scope: reading.scope,
+            visible,
+            withheld: typeof withheld === 'number' ? withheld : null,
+        };
+    }
+    if (withheld === 'unreadable')
+        return { kind: 'unknown', why: 'withheld_unreadable' };
+    if (asked.originAware !== true)
+        return { kind: 'unknown', why: 'fenced' };
+    if (reading.truncated)
+        return { kind: 'unknown', why: 'truncated' };
+    if (reading.dropped > 0)
+        return { kind: 'unknown', why: 'rows_dropped' };
+    if (reading.rows.some((r) => r.originMark === 'undecidable')) {
+        return { kind: 'unknown', why: 'undecidable_rows' };
+    }
+    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;
+}
+function eraseEvidenceCapabilityOf(v) {
+    return v === 'journal' || v === 'none' ? v : null;
+}
+function eraseCustodyStateOf(v) {
+    return v === 'complete' || v === 'damaged' || v === 'capability-absent' ? v : null;
+}
+/** 一行的抹除绑定窄读:两条臂逐字对上才认,别的一律 `null`(读不出,不是 unbound)。 */
+function erasedBindingOf(v) {
+    if (!plainObject(v))
+        return null;
+    const state = v.state;
+    if (state === 'unbound')
+        return { state: 'unbound' };
+    if (state !== 'bound')
+        return null;
+    const scope = v.scope;
+    const slug = v.slug;
+    if (!nonEmptyString(scope) || !nonEmptyString(slug))
+        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;
+    let rawRequestId;
+    let rawStatus;
+    let rawEvidence;
+    let rawCustody;
+    let rawSelected;
+    let rawErased;
+    let rawNotFound;
+    let rawPreviously;
+    let rawConflicts;
+    let envelopeSeen;
+    try {
+        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;
+        rawStatus = o.status;
+        rawEvidence = o.evidenceCapability;
+        rawCustody = o.custodyState;
+        rawSelected = o.resolvedIds;
+        rawErased = o.erased;
+        rawNotFound = o.notFound;
+        rawPreviously = Object.hasOwn(o, 'erasedPreviously') ? o.erasedPreviously : undefined;
+        rawConflicts = o.conflicts;
+    }
+    catch {
+        return { kind: 'malformed', why: 'body_unreadable' };
+    }
+    // 「200 空体」:一把信封键都没有 ⇒ 这不是一份收执。
+    if (!envelopeSeen)
+        return { kind: 'malformed', why: 'envelope_absent' };
+    if (rawV === undefined)
+        return { kind: 'malformed', why: 'version_absent' };
+    if (rawV !== MEMORY_ERASE_RECEIPT_VERSION)
+        return { kind: 'malformed', why: 'unsupported_version' };
+    const status = eraseStatusOf(rawStatus);
+    const evidenceCapability = eraseEvidenceCapabilityOf(rawEvidence);
+    const custodyState = eraseCustodyStateOf(rawCustody);
+    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;
+    let previouslySnap;
+    let selectedIds;
+    try {
+        erasedSnap = snapshotArray(rawErased);
+        notFoundSnap = snapshotArray(rawNotFound);
+        conflictsSnap = snapshotArray(rawConflicts);
+        previouslySnap = rawPreviously === undefined ? null : snapshotArray(rawPreviously);
+        selectedIds = arrayLengthOrNull(rawSelected);
+    }
+    catch {
+        return { kind: 'malformed', why: 'body_unreadable' };
+    }
+    if (erasedSnap === null || notFoundSnap === null || conflictsSnap === null) {
+        return { kind: 'malformed', why: 'envelope_unreadable' };
+    }
+    if (rawPreviously !== undefined && previouslySnap === null) {
+        return { kind: 'malformed', why: 'envelope_unreadable' };
+    }
+    if (erasedSnap.tooLarge || notFoundSnap.tooLarge || conflictsSnap.tooLarge || previouslySnap?.tooLarge === true) {
+        return { kind: 'malformed', why: 'too_many_rows' };
+    }
+    const erased = [];
+    const erasedSeen = new Set();
+    let erasedDropped = erasedSnap.unreadable;
+    for (const item of erasedSnap.items) {
+        try {
+            if (!plainObject(item)) {
+                erasedDropped++;
+                continue;
+            }
+            const id = item.id;
+            const rev = item.rev;
+            if (!nonEmptyString(id) || !nonEmptyString(rev) || erasedSeen.has(id)) {
+                erasedDropped++;
+                continue;
+            }
+            erasedSeen.add(id);
+            erased.push({ id, rev, binding: erasedBindingOf(item.binding) });
+        }
+        catch {
+            erasedDropped++;
+        }
+    }
+    if (erasedSnap.items.length + erasedSnap.unreadable > 0 && erased.length === 0) {
+        return { kind: 'malformed', why: 'erased_rows_unreadable' };
+    }
+    const notFound = [];
+    const notFoundSeen = new Set();
+    let notFoundDropped = notFoundSnap.unreadable;
+    for (const item of notFoundSnap.items) {
+        try {
+            if (!plainObject(item)) {
+                notFoundDropped++;
+                continue;
+            }
+            const id = item.id;
+            if (!nonEmptyString(id) || notFoundSeen.has(id)) {
+                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);
+            notFound.push({
+                id,
+                historyUnknown: !hasHistory ? null : typeof raw === 'boolean' ? raw : 'unreadable',
+            });
+        }
+        catch {
+            notFoundDropped++;
+        }
+    }
+    if (notFoundSnap.items.length + notFoundSnap.unreadable > 0 && notFound.length === 0) {
+        return { kind: 'malformed', why: 'not_found_rows_unreadable' };
+    }
+    const conflicts = [];
+    let conflictsDropped = conflictsSnap.unreadable;
+    for (const item of conflictsSnap.items) {
+        try {
+            if (!plainObject(item)) {
+                conflictsDropped++;
+                continue;
+            }
+            const id = item.id;
+            const reason = item.reason;
+            if (!nonEmptyString(id) || typeof reason !== 'string') {
+                conflictsDropped++;
+                continue;
+            }
+            conflicts.push({ id, reason });
+        }
+        catch {
+            conflictsDropped++;
+        }
+    }
+    if (conflictsSnap.items.length + conflictsSnap.unreadable > 0 && conflicts.length === 0) {
+        return { kind: 'malformed', why: 'conflict_rows_unreadable' };
+    }
+    let erasedPreviously = null;
+    let erasedPreviouslyDropped = 0;
+    if (previouslySnap !== null) {
+        const rows = [];
+        const seen = new Set();
+        erasedPreviouslyDropped = previouslySnap.unreadable;
+        for (const item of previouslySnap.items) {
+            try {
+                if (!plainObject(item)) {
+                    erasedPreviouslyDropped++;
+                    continue;
+                }
+                const id = item.id;
+                if (!nonEmptyString(id) || seen.has(id)) {
+                    erasedPreviouslyDropped++;
+                    continue;
+                }
+                seen.add(id);
+                rows.push({ id });
+            }
+            catch {
+                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' };
+        }
+        erasedPreviously = rows;
+    }
+    return {
+        kind: 'present',
+        requestId: rawRequestId,
+        status,
+        evidenceCapability,
+        custodyState,
+        selectedIds,
+        erased,
+        erasedDropped,
+        notFound,
+        notFoundDropped,
+        erasedPreviously,
+        erasedPreviouslyDropped,
+        conflicts,
+        conflictsDropped,
+    };
+}
+/**
+ * 「这一次抹了几条」的判据单源。
+ * 🔴 读不懂 ⇒ `unknown` + 原成因(**绝不**答 0);任何一段有丢行 ⇒ `unknown` / `'rows_dropped'`
+ * (读得出的行是真的,但这几个**数**已经不是引擎给的那几个了)。
+ */
+export function memoryEraseCounts(reading) {
+    if (reading.kind !== 'present')
+        return { kind: 'unknown', why: reading.why };
+    if (reading.erasedDropped > 0 ||
+        reading.notFoundDropped > 0 ||
+        reading.conflictsDropped > 0 ||
+        reading.erasedPreviouslyDropped > 0) {
+        return { kind: 'unknown', why: 'rows_dropped' };
+    }
+    return {
+        kind: 'counted',
+        erased: reading.erased.length,
+        notFound: reading.notFound.length,
+        conflicts: reading.conflicts.length,
+        erasedPreviously: reading.erasedPreviously === null ? null : reading.erasedPreviously.length,
+        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;
+    let rawClearanceId;
+    let rawLandedSlug;
+    let originReported;
+    let origin;
+    try {
+        if (!plainObject(body))
+            return { kind: 'malformed', why: 'body_unreadable' };
+        o = body;
+        if (!['entryId', 'clearanceId', 'landedSlug'].some((k) => Object.hasOwn(o, k))) {
+            return { kind: 'malformed', why: 'envelope_absent' };
+        }
+        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;
+    }
+    catch {
+        return { kind: 'malformed', why: 'body_unreadable' };
+    }
+    if (!nonEmptyString(rawEntryId) || !nonEmptyString(rawClearanceId) || !nonEmptyString(rawLandedSlug)) {
+        return { kind: 'malformed', why: 'envelope_unreadable' };
+    }
+    return {
+        kind: 'present',
+        entryId: rawEntryId,
+        clearanceId: rawClearanceId,
+        landedSlug: rawLandedSlug,
+        originReported,
+        origin,
+    };
+}

package/dist/memoryOriginCapability.d.ts

@@ -0,0 +1,68 @@
+/**
+ * memoryOriginCapability — `GET /v1/capabilities.memoryOrigin` 的三端共用读面(0.76.1 CC-97a;
+ * 与 `memoryCompliance` 及其余能力位兄弟同一套四态词汇,四口走共用工厂 {@link createEngineCapReader})。
+ *
+ * ── 这一位答的是哪一个问题 ────────────────────────────────────────────────────────────────
+ * 「**外源标记人面三口**(`GET /v1/memory/origin/external` · `GET /v1/memory/origin/clearances` ·
+ * `POST /v1/memory/origin/entries/:entryId/clear`,operator 车道)在这台引擎上在不在」。引擎侧的谓词
+ * 是**两项合取**:外源面在挂载期判出后端自带引擎控制面归属(缺则整口不挂),且 operator 名单**非空**
+ * (空名单下三口对任何身份恒 403)。
+ * ⚠️ 位为真**只**保证「门能过 + 面在场」,**不**保证这一次调用成功:清标账本损坏是**运行期**事实
+ *    (typed 500)。
+ * ⚠️ 与 `memoryCompliance` **同判据不同位**:两族今天查后端的同一个面,但它们是**两个产品面**
+ *    (合规问询 / 抹除 · 外源审计 / 清标),一个部署可以只想开其中一族 —— 引擎**刻意不合并**,
+ *    即使今天两位恒同值。🔴 本包跟着不合并:两只读器各持一张 per-baseUrl 表,喂其中一只畸形回体
+ *    只删它自己那一格,{@link import('./memoryComplianceCapability.js')} 的读数一字不变。把两位
+ *    折成一只读器 = 在未来的分家上让消费端读到假话。
+ * 🔴 位为真**也不**保证 `GET …/external` 的答案**完备**:引擎 v1 没有 scope 枚举读面,答案只覆盖
+ *    调用方点名的那些 scope ⇒ **空答绝不读作「本店干净」**。那是**发现链**的事,能力位表达不了它 ——
+ *    本包把这句话实现在导出条目面的判词口上(`scopeExternalOriginVerdict`),不是只写在注释里。
+ *
+ * ── 🔴 读法(与 `memoryCompliance` 逐条同律,但**各自一张表**)─────────────────────────────
+ *  ① 引擎铸这一位时**恒在场**(一格布尔)⇒ **键缺席 = 老引擎不报这一位** ⇒ `not_reported`(判不出),
+ *     绝不折成 `false`;
+ *  ② `false` 是**明确的否** ⇒ `absent`;成因(后端无控制面归属 / operator 名单为空)在 wire 上不可分,
+ *     措辞不推因由;
+ *  ③ 严格布尔;`null` / 串 / `0` / `1` / 数组 / 对象一律畸形 ⇒ 删格 ⇒ `unobserved`,🔴 绝不折 `absent`;
+ *  ③b caps 回体本身不是对象(`null` / 数组 / 串 / 数)⇒ 畸形删格,**不是** `not_reported`(那一态只说「这是
+ *      一份 caps,但没有这一格」)。
+ *  ④ 判在场用 `hasOwn`(原型键永不上 wire);
+ *  ⑤ 「三口能不能用」的判据归包:{@link memoryOriginVerbsAvailable}。
+ */
+/** 四态读数。`unobserved` 由读口在这一格空缺时铸,不由投影铸。 */
+export type MemoryOriginReading = {
+    kind: 'unobserved';
+}
+/** 键缺席:老引擎不报这一位 ⇒ 判不出(**不是** `absent`)。 */
+ | {
+    kind: 'not_reported';
+}
+/** 位在场且为 `false`:这台部署上三口用不了(成因在 wire 上不可分)。 */
+ | {
+    kind: 'absent';
+}
+/** 位在场且为 `true`:门能过 + 面在场(既不承诺这一次调用成功,也不承诺外源清单完备)。 */
+ | {
+    kind: 'present';
+};
+/** caps 回体 → 本格读数;畸形一律 `undefined`(= 这一格不写 ⇒ 读口答 `unobserved`)。 */
+export declare function projectMemoryOriginCapability(caps: unknown): MemoryOriginReading | undefined;
+/** 宿主 caps probe 的读面 tee 落点。绝不 throw;畸形 ⇒ 删格;`opts.generation` 关掉旧探测覆盖新读数的竞态。 */
+export declare function noteEngineCapsForMemoryOrigin(baseUrl: string, caps: unknown, opts?: {
+    generation?: number;
+}): void;
+/** 本进程观测到的读数;这一格空缺 ⇒ `{kind:'unobserved'}`。 */
+export declare function observedMemoryOrigin(baseUrl?: string | undefined): MemoryOriginReading;
+/**
+ * 「外源标记人面三口能不能用」的判据单源(三态):只有引擎明说在场才 `'yes'`;明说不在 ⇒ `'no'`;
+ * 老引擎不报 / 从没观测 ⇒ `'unknown'`。
+ * 🔴 `'yes'` **只**说三口够得着,对外源清单的**完备性**一个字都没说(那一问归
+ * `scopeExternalOriginVerdict`)。
+ */
+export declare function memoryOriginVerbsAvailable(reading: MemoryOriginReading): 'yes' | 'no' | 'unknown';
+/** doctor 那一行的 detail 串,唯一措辞真源。🔴 两种「读不出」的句子都不许暗示「这台没有外源面」。 */
+export declare function memoryOriginDoctorDetail(reading: MemoryOriginReading): string;
+/** 换代失效口(引擎温切成功后调):清成未观测。空串 ⇒ no-op;绝不 throw。 */
+export declare function forgetMemoryOriginReading(baseUrl: string | undefined): void;
+/** 测试钩子。 */
+export declare function __resetMemoryOriginReadingsForTests(): void;