@harrylabsj/kiwi 0.6.0

package/dist/negotiation/ledger/event.d.ts

@@ -0,0 +1,142 @@
+/**
+ * Copyright 2026 harrylabsj
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import type { NegotiationActor } from "../domain/objects.js";
+import type { NegotiationPhase } from "../state/phase.js";
+export declare const LEDGER_EVENT_KINDS: readonly ["message_received", "message_sent", "state_transition", "system", "reconciliation", "error", "handoff_candidate_created", "handoff_candidate_ready", "handoff_candidate_rejected", "handoff_candidate_stale", "handoff_candidate_expired", "handoff_candidate_consumed", "handoff_delivered", "handoff_launched", "handoff_opened_confirmed", "handoff_expired", "handoff_revoked", "handoff_delivery_failed"];
+export type LedgerEventKind = (typeof LEDGER_EVENT_KINDS)[number];
+/** 身份快照（基线 §22 identity snapshot / 子规范 §28）。 */
+export interface LedgerIdentitySnapshot {
+    /** 协议级幂等主键的一半：(sender_identity, message_id)。 */
+    sender_identity: string;
+    /** 对手方身份。 */
+    counterparty_identity: string;
+    /** KNP envelope actor（buyer|merchant），便于审计快速过滤。 */
+    actor?: NegotiationActor;
+}
+/** 能力/版本快照（基线 §22 capability snapshot）。 */
+export interface LedgerCapabilitySnapshot {
+    capability: string;
+    protocol_version: string;
+    agent_version?: string;
+}
+/** Phase 状态转换（对齐 state/phase.ts 的 NegotiationPhase）。 */
+export interface LedgerStateTransition {
+    from_phase?: NegotiationPhase;
+    to_phase: NegotiationPhase;
+}
+/** 处理结果：成功（可带结构化 result）或协议错误（code 对齐子规范 §18 词表）。 */
+export type LedgerOutcome = {
+    kind: "ok";
+    result?: Record<string, unknown>;
+} | {
+    kind: "error";
+    code: string;
+    message: string;
+};
+/** 调用方提供的稳定内容字段（digest / 链指针 / 落账元数据由 store 填充）。 */
+export interface LedgerEventContent {
+    event_kind: LedgerEventKind;
+    negotiation_id: string;
+    /** message/exchange refs（基线 §22）。 */
+    exchange_id?: string;
+    message_id?: string;
+    in_reply_to?: string;
+    /** remote A2A contextId/taskId（基线 §22 / 子规范 §24.4/§24.5）。 */
+    remote_context_id?: string;
+    remote_task_id?: string;
+    identity: LedgerIdentitySnapshot;
+    capability: LedgerCapabilitySnapshot;
+    /** wire digest = KNP envelope digest（§19.2）。 */
+    wire_digest?: string;
+    /** wire payload = 收发时的 envelope 内容（不含 transport signature 字段）。 */
+    wire_payload?: Record<string, unknown>;
+    /** Phase 状态转换（如该事件驱动了状态机推进）。 */
+    state_transition?: LedgerStateTransition;
+    /** handoff candidate id（candidate 生命周期事件必填）。 */
+    handoff_candidate_id?: string;
+    /** handoff id（交付观察事件必填）。 */
+    handoff_id?: string;
+    /** 溯源：产生该 handoff 的 agreement。 */
+    agreement_id?: string;
+    /** 溯源：agreement 的 terms_digest。 */
+    terms_digest?: string;
+    /** 目的地快照（最小化、非秘密；payload 最小化约束见 KTH §11.3）。 */
+    destination?: Record<string, unknown>;
+    /** 证据快照（OPENED_CONFIRMED 的可归属证据，KTH rev0.3 §9）。 */
+    evidence?: Record<string, unknown>;
+    outcome: LedgerOutcome;
+    /** 业务发生时间（如 envelope.created_at），RFC 3339。 */
+    occurred_at: string;
+}
+/** 完整 Ledger 事件。 */
+export interface LedgerEvent extends LedgerEventContent {
+    event_id: string;
+    /** 链上一条的 event_digest；创世事件为 null。 */
+    previous_event_digest: string | null;
+    event_digest: string;
+    /** 落账时间（可注入时钟），RFC 3339。 */
+    recorded_at: string;
+}
+export type LedgerVerifyError = {
+    code: "chain_break";
+    index: number;
+    detail: string;
+} | {
+    code: "tampered";
+    index: number;
+    detail: string;
+} | {
+    code: "duplicate";
+    index: number;
+    detail: string;
+} | {
+    code: "corrupt";
+    index: number;
+    detail: string;
+};
+export interface LedgerVerifyResult {
+    valid: boolean;
+    count: number;
+    error?: LedgerVerifyError;
+}
+export declare const LEDGER_ERROR_CODES: readonly ["ledger_unknown_negotiation", "ledger_chain_corrupt", "ledger_append_only_violation", "ledger_duplicate_content", "ledger_forbidden_content", "ledger_invalid_identity", "ledger_invalid_capability", "ledger_append_locked"];
+export type LedgerErrorCode = (typeof LEDGER_ERROR_CODES)[number];
+/** Ledger 存储/校验失败。与协议错误词表（§18）分开：Ledger 是内部审计域。 */
+export declare class LedgerError extends Error {
+    readonly code: LedgerErrorCode;
+    /** 出错的行索引（verifyChain 解析坏行时携带）。 */
+    readonly index?: number;
+    constructor(code: LedgerErrorCode, message: string, index?: number);
+}
+/**
+ * 递归扫描内容中的每个 key，命中 CoT / Vault plaintext 禁词即抛
+ * ledger_forbidden_content。用于 wire_payload、outcome.result 等自由对象。
+ * 幂等键本身（sender_identity 等）是结构化字段，不在递归范围内。
+ */
+export declare function assertNoForbiddenContent(value: unknown, path?: string): void;
+/** 新事件 id：`evt_<uuidv7>`，跨重启稳定且可排序（同 identifiers 的 §6 约定）。 */
+export declare function newLedgerEventId(): string;
+/**
+ * 事件「稳定内容」视图：digest 的输入。排除 event_id / event_digest /
+ * previous_event_digest / recorded_at（落账元数据），因此同一逻辑事件在任意
+ * 链位置、任意落账时间的地址都一致 —— 内容寻址。JCS 跳过 undefined 字段，
+ * 可选字段缺省不影响摘要。
+ */
+export declare function eventContentAddressable(content: LedgerEventContent | LedgerEvent): Record<string, unknown>;
+/** 由稳定内容计算 event_digest（contentDigest = JCS + SHA-256，`sha256:` 前缀）。 */
+export declare function computeEventDigest(content: LedgerEventContent | LedgerEvent): string;
+/** 基础结构守卫：保证从磁盘解析的事件具有链校验所需的最小形状。 */
+export declare function isLedgerEvent(value: unknown): value is LedgerEvent;

package/dist/negotiation/ledger/event.js

@@ -0,0 +1,206 @@
+/**
+ * Copyright 2026 harrylabsj
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * KNP/1.0 Negotiation Ledger 事件模型（基线 §22 / 子规范 §28）。
+ *
+ * 每条 Ledger 事件是 append-only、content-addressed、hash-linked 的记录：
+ *
+ * - `event_digest`：对事件「稳定内容」的 SHA-256 content digest（`sha256:` 前缀，
+ *   与 jcs.ts 的 contentDigest 同源）。稳定内容 = 除 event_id / event_digest /
+ *   previous_event_digest / recorded_at 之外的全部业务字段。这样同一逻辑事件
+ *   无论何时、以何种链位置落账都产生同一地址 —— 内容寻址。
+ * - `previous_event_digest`：同 negotiation_id 链上前一条的 event_digest。
+ *   创世事件（链首）为 null。该字段由 store 按当前链尾计算，调用方不可伪造。
+ * - 链完整性由 verifyChain 单独校验：断链（前一 digest 不匹配）与篡改
+ *   （重算 digest 不匹配）是两种可区分的错误。
+ *
+ * 不保存（§22 / §28 / §36 不变量 5）：raw chain-of-thought 与 Vault plaintext。
+ * 该约束不止是文档 —— append 前会递归扫描内容字段，命中禁词即 fail-closed。
+ */
+import { contentDigest } from "../jcs.js";
+import { uuidv7 } from "../domain/identifiers.js";
+export const LEDGER_EVENT_KINDS = [
+    "message_received",
+    "message_sent",
+    "state_transition",
+    "system",
+    "reconciliation",
+    "error",
+    // v0.7.0 KTH：candidate 生命周期（KTH rev0.3 §5.1，event-sourced 投影）
+    "handoff_candidate_created",
+    "handoff_candidate_ready",
+    "handoff_candidate_rejected",
+    "handoff_candidate_stale",
+    "handoff_candidate_expired",
+    "handoff_candidate_consumed",
+    // v0.7.0 KTH：交付观察（KTH rev0.3 §9，evidence-gated）
+    "handoff_delivered",
+    "handoff_launched",
+    "handoff_opened_confirmed",
+    "handoff_expired",
+    "handoff_revoked",
+    "handoff_delivery_failed",
+];
+export const LEDGER_ERROR_CODES = [
+    "ledger_unknown_negotiation",
+    "ledger_chain_corrupt",
+    "ledger_append_only_violation",
+    "ledger_duplicate_content",
+    "ledger_forbidden_content",
+    "ledger_invalid_identity",
+    "ledger_invalid_capability",
+    "ledger_append_locked",
+];
+/** Ledger 存储/校验失败。与协议错误词表（§18）分开：Ledger 是内部审计域。 */
+export class LedgerError extends Error {
+    code;
+    /** 出错的行索引（verifyChain 解析坏行时携带）。 */
+    index;
+    constructor(code, message, index) {
+        super(message);
+        this.name = "LedgerError";
+        this.code = code;
+        this.index = index;
+    }
+}
+// ---------------------------------------------------------------------------
+// 禁词检查：不保存 raw chain-of-thought / Vault plaintext（§22 / §28 / §36-5）
+// ---------------------------------------------------------------------------
+/** 归一化 key：小写 + 去非字母数字。`chain_of_thought` → `chainofthought`。 */
+function normalizeKey(key) {
+    return key.toLowerCase().replace(/[^a-z0-9]/g, "");
+}
+/** CoT 相关禁词（精确匹配归一化 key）。 */
+const FORBIDDEN_COT_KEYS = new Set([
+    "chainofthought",
+    "cot",
+    "thought",
+    "thoughts",
+    "reasoning",
+    "rationale",
+    "thinking",
+    "internalmonologue",
+    "scratchpad",
+]);
+/** Vault plaintext / 秘密相关禁词（精确匹配归一化 key）。 */
+const FORBIDDEN_VAULT_KEYS = new Set([
+    "vault",
+    "vaultplaintext",
+    "privatevault",
+    "plaintext",
+    "secret",
+    "secrets",
+    "secretkey",
+    "privatekey",
+    "apikey",
+    "password",
+    "credential",
+    "credentials",
+]);
+/** 子串级兜底：任何 key 中出现即拒绝（双保险，防变形拼写）。 */
+const FORBIDDEN_SUBSTRINGS = ["chainofthought", "vaultplaintext", "privatevault"];
+function isForbiddenKey(key) {
+    const normalized = normalizeKey(key);
+    if (FORBIDDEN_COT_KEYS.has(normalized) || FORBIDDEN_VAULT_KEYS.has(normalized))
+        return true;
+    return FORBIDDEN_SUBSTRINGS.some((sub) => normalized.includes(sub));
+}
+/**
+ * 递归扫描内容中的每个 key，命中 CoT / Vault plaintext 禁词即抛
+ * ledger_forbidden_content。用于 wire_payload、outcome.result 等自由对象。
+ * 幂等键本身（sender_identity 等）是结构化字段，不在递归范围内。
+ */
+export function assertNoForbiddenContent(value, path = "$") {
+    if (Array.isArray(value)) {
+        for (let i = 0; i < value.length; i++) {
+            assertNoForbiddenContent(value[i], `${path}[${i}]`);
+        }
+        return;
+    }
+    if (value !== null && typeof value === "object") {
+        for (const key of Object.keys(value)) {
+            const childPath = `${path}.${key}`;
+            if (isForbiddenKey(key)) {
+                throw new LedgerError("ledger_forbidden_content", `ledger MUST NOT record ${childPath}: key is reserved for chain-of-thought / vault plaintext`);
+            }
+            assertNoForbiddenContent(value[key], childPath);
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// 内容寻址与事件构造
+// ---------------------------------------------------------------------------
+/** 新事件 id：`evt_<uuidv7>`，跨重启稳定且可排序（同 identifiers 的 §6 约定）。 */
+export function newLedgerEventId() {
+    return `evt_${uuidv7()}`;
+}
+/**
+ * 事件「稳定内容」视图：digest 的输入。排除 event_id / event_digest /
+ * previous_event_digest / recorded_at（落账元数据），因此同一逻辑事件在任意
+ * 链位置、任意落账时间的地址都一致 —— 内容寻址。JCS 跳过 undefined 字段，
+ * 可选字段缺省不影响摘要。
+ */
+export function eventContentAddressable(content) {
+    return {
+        event_kind: content.event_kind,
+        negotiation_id: content.negotiation_id,
+        exchange_id: content.exchange_id,
+        message_id: content.message_id,
+        in_reply_to: content.in_reply_to,
+        remote_context_id: content.remote_context_id,
+        remote_task_id: content.remote_task_id,
+        identity: content.identity,
+        capability: content.capability,
+        wire_digest: content.wire_digest,
+        wire_payload: content.wire_payload,
+        state_transition: content.state_transition,
+        // v0.7.0 KTH 字段（JCS 跳过 undefined，KNP 事件向后兼容；KTH 事件的
+        // 溯源/证据字段必须纳入 digest——否则篡改 terms_digest/evidence 无法
+        // 被 verifyChain 检出，审计链形同虚设，§22/#18）。
+        handoff_candidate_id: content.handoff_candidate_id,
+        handoff_id: content.handoff_id,
+        agreement_id: content.agreement_id,
+        terms_digest: content.terms_digest,
+        destination: content.destination,
+        evidence: content.evidence,
+        outcome: content.outcome,
+        occurred_at: content.occurred_at,
+    };
+}
+/** 由稳定内容计算 event_digest（contentDigest = JCS + SHA-256，`sha256:` 前缀）。 */
+export function computeEventDigest(content) {
+    return contentDigest(eventContentAddressable(content));
+}
+/** 基础结构守卫：保证从磁盘解析的事件具有链校验所需的最小形状。 */
+export function isLedgerEvent(value) {
+    if (value === null || typeof value !== "object")
+        return false;
+    const obj = value;
+    return (typeof obj.event_id === "string" &&
+        typeof obj.event_digest === "string" &&
+        (obj.previous_event_digest === null || typeof obj.previous_event_digest === "string") &&
+        typeof obj.negotiation_id === "string" &&
+        typeof obj.event_kind === "string" &&
+        typeof obj.recorded_at === "string" &&
+        typeof obj.occurred_at === "string" &&
+        obj.identity !== null &&
+        typeof obj.identity === "object" &&
+        obj.capability !== null &&
+        typeof obj.capability === "object" &&
+        obj.outcome !== null &&
+        typeof obj.outcome === "object");
+}
+//# sourceMappingURL=event.js.map

package/dist/negotiation/ledger/event.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event.js","sourceRoot":"","sources":["../../../src/negotiation/ledger/event.ts"],"names":[],"mappings":"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"}

package/dist/negotiation/ledger/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Copyright 2026 harrylabsj
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * KNP/1.0 Negotiation Ledger（基线 §22 / §23 / 子规范 §28）。
+ *
+ * append-only、content-addressed、hash-linked 的协商审计日志。每条事件含
+ * event_digest / previous_event_digest，verifyChain 可区分断链与篡改。
+ * 不保存 raw chain-of-thought 与 Vault plaintext（§22 / §28 / §36-5）。
+ */
+export { LedgerError, LEDGER_ERROR_CODES, assertNoForbiddenContent, computeEventDigest, eventContentAddressable, newLedgerEventId, } from "./event.js";
+export type { LedgerCapabilitySnapshot, LedgerEvent, LedgerEventContent, LedgerEventKind, LedgerIdentitySnapshot, LedgerOutcome, LedgerStateTransition, LedgerVerifyError, LedgerVerifyResult, } from "./event.js";
+export { LedgerStore, ledgerFileName } from "./store.js";
+export type { LedgerHighWaterMark, LedgerStoreOptions } from "./store.js";

package/dist/negotiation/ledger/index.js

@@ -0,0 +1,25 @@
+/**
+ * Copyright 2026 harrylabsj
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * KNP/1.0 Negotiation Ledger（基线 §22 / §23 / 子规范 §28）。
+ *
+ * append-only、content-addressed、hash-linked 的协商审计日志。每条事件含
+ * event_digest / previous_event_digest，verifyChain 可区分断链与篡改。
+ * 不保存 raw chain-of-thought 与 Vault plaintext（§22 / §28 / §36-5）。
+ */
+export { LedgerError, LEDGER_ERROR_CODES, assertNoForbiddenContent, computeEventDigest, eventContentAddressable, newLedgerEventId, } from "./event.js";
+export { LedgerStore, ledgerFileName } from "./store.js";
+//# sourceMappingURL=index.js.map

package/dist/negotiation/ledger/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/negotiation/ledger/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH;;;;;;GAMG;AACH,OAAO,EACL,WAAW,EACX,kBAAkB,EAClB,wBAAwB,EACxB,kBAAkB,EAClB,uBAAuB,EACvB,gBAAgB,GACjB,MAAM,YAAY,CAAC;AAYpB,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC"}

package/dist/negotiation/ledger/store.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Copyright 2026 harrylabsj
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import type { LedgerEvent, LedgerEventContent, LedgerVerifyResult } from "./event.js";
+export interface LedgerHighWaterMark {
+    negotiation_id: string;
+    count: number;
+    last_event_id: string | null;
+    last_event_digest: string | null;
+    last_recorded_at: string | null;
+    last_message_id?: string;
+}
+export interface LedgerStoreOptions {
+    /** 基础数据目录；Ledger 文件落在 `<dir>/ledger/`。 */
+    dir: string;
+    /** 可注入时钟（RFC 3339）；缺省用 new Date().toISOString()。 */
+    now?: () => string;
+    /** 跨进程 append 锁等待上限（ms，缺省 5000）；超时 fail-closed。 */
+    lockTimeoutMs?: number;
+}
+/**
+ * 将 opaque negotiation_id 映射为安全文件名：合法字符保留，其余归一为 `_`，
+ * 再附加 id 的 sha256 前缀防止不同 id 归一化碰撞。id 含 `/` 也无法逃逸目录。
+ */
+export declare function ledgerFileName(negotiationId: string): string;
+export declare class LedgerStore {
+    private readonly baseDir;
+    private readonly ledgerDir;
+    private readonly now;
+    private readonly lockTimeoutMs;
+    constructor(options: LedgerStoreOptions);
+    /**
+     * 跨进程 append 互斥（评审项 B1）：append = load → verify → 整文件重写，
+     * 单进程内同步无交错，但**跨进程共享 dir**（handoff 幂等锁文档声称支持
+     * 的场景）两个进程同时 append 会各自读到同一链尾、互相覆盖——一条事件
+     * 静默丢失（无报错）。锁文件用 `openSync("wx")` 原子创建；持锁崩溃残留
+     * 由 mtime 陈旧检测自愈（append 是亚秒级操作，30s 阈值安全）；等待超时
+     * fail-closed（ledger_append_locked）——绝不静默丢事件。
+     */
+    private withChainLock;
+    /** ledger 目录（0700），不存在则创建。 */
+    private ensureLedgerDir;
+    /** negotiation_id → 绝对文件路径（含路径包含检查）。 */
+    private filePathFor;
+    /** 原子写（对齐 supervisor/manifest.ts：同目录临时文件 + fsync + rename，0600）。 */
+    private writeFileAtomic;
+    /** 解析一个 JSONL 行；非对象/非事件形状抛 ledger_chain_corrupt。 */
+    private parseLine;
+    /** 从磁盘读取某 negotiation 的完整事件序列；文件缺失返回 []。 */
+    private load;
+    /** 某 negotiation 是否已有记录。 */
+    hasNegotiation(negotiationId: string): boolean;
+    /** 取某 negotiation 的完整事件序列（磁盘直读，不缓存）。 */
+    events(negotiationId: string): LedgerEvent[];
+    /** 高水位（§23 恢复第 2 步）：count / 链尾 digest / 末条 message_id。 */
+    highWaterMark(negotiationId: string): LedgerHighWaterMark;
+    /**
+     * Append 一条事件。链接由当前链尾计算；重复内容（同 event_digest）拒绝。
+     * 返回完整事件（含 event_id / digests / recorded_at）。
+     */
+    append(content: LedgerEventContent): LedgerEvent;
+    private appendUnlocked;
+    /**
+     * 链完整性校验（§22 verifyChain）。返回结构化结果而非抛错：
+     *   corrupt    某行不是合法 JSON / 事件形状（撕裂或手工破坏）
+     *   tampered   重算 event_digest 与存储值不一致（内容被改）
+     *   chain_break 前一条 digest 不匹配 / 首条非创世（中间删除或链接被改）
+     *   duplicate  event_digest 在链内重复
+     * 空链（无事件）视为 valid。
+     */
+    verifyChain(negotiationId: string): LedgerVerifyResult;
+    /** 对一组事件做链校验（append 与 verifyChain 共用）。 */
+    private verifyEvents;
+    /** 所有已落账的 negotiation_id（按文件名扫描）。 */
+    listNegotiations(): string[];
+    /** 按 message_id 查重（§23 第 5 步：compare acknowledged messages）。 */
+    findByMessageId(messageId: string): {
+        negotiation_id: string;
+        event: LedgerEvent;
+    } | null;
+    /** 内容寻址查询：按 event_digest 取事件（供幂等/审计交叉引用）。 */
+    findEventByDigest(negotiationId: string, eventDigest: string): LedgerEvent | null;
+    /** 按已落账文件名读取（listNegotiations / findByMessageId 内部复用）。 */
+    private loadFromFile;
+}