@sema-agent/client-core 0.75.1 → 0.76.1

package/dist/memoryEntriesWire.d.ts

@@ -0,0 +1,302 @@
+/**
+ * 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 MemoryExportReading = {
+    kind: 'malformed';
+    why: MemoryExportUnreadableCause;
+} | {
+    kind: 'present';
+    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` / 翻页 / 重取 / 去问引擎侧判官)。 */
+{
+    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;
+    slug: string;
+} | {
+    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 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;
+    notFound: MemoryEraseNotFoundRow[];
+    notFoundDropped: number;
+    erasedPreviously: MemoryErasePreviouslyRow[] | null;
+    erasedPreviouslyDropped: number;
+    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';
+} | {
+    kind: 'counted';
+    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 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;