@harrylabsj/kiwi 0.6.0

package/dist/negotiation/idempotency/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.
+ */
+/**
+ * 协议级幂等（基线 §17 / 子规范 §20 Idempotency and Replay）。
+ *
+ * 主键 (sender_identity, message_id)；同 id 同 digest 重放返回原结果，
+ * 同 id 异 digest 抛 idempotency_conflict（fail-closed）。retention 至少覆盖
+ * max(offer validity, task lifetime, 24h)。判定证据落 Ledger。
+ */
+export { IDEMPOTENCY_FLOOR_MS, IdempotencyConflictError, computeRetentionDeadline, idempotencyKey, } from "./types.js";
+export type { IdempotencyCheckInput, IdempotencyCommitInput, IdempotencyDecision, IdempotencyRecord, RetentionInput, } from "./types.js";
+export { IdempotencyStore } from "./store.js";
+export type { IdempotencyStoreOptions } from "./store.js";

package/dist/negotiation/idempotency/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.
+ */
+/**
+ * 协议级幂等（基线 §17 / 子规范 §20 Idempotency and Replay）。
+ *
+ * 主键 (sender_identity, message_id)；同 id 同 digest 重放返回原结果，
+ * 同 id 异 digest 抛 idempotency_conflict（fail-closed）。retention 至少覆盖
+ * max(offer validity, task lifetime, 24h)。判定证据落 Ledger。
+ */
+export { IDEMPOTENCY_FLOOR_MS, IdempotencyConflictError, computeRetentionDeadline, idempotencyKey, } from "./types.js";
+export { IdempotencyStore } from "./store.js";
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/negotiation/idempotency/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH;;;;;;GAMG;AACH,OAAO,EACL,oBAAoB,EACpB,wBAAwB,EACxB,wBAAwB,EACxB,cAAc,GACf,MAAM,YAAY,CAAC;AAQpB,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC"}

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

@@ -0,0 +1,52 @@
+/**
+ * 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 { IdempotencyCheckInput, IdempotencyCommitInput, IdempotencyDecision, IdempotencyRecord } from "./types.js";
+export interface IdempotencyStoreOptions {
+    /** 基础数据目录；幂等记录落在 `<dir>/idempotency/`。 */
+    dir: string;
+    /** 可注入时钟（RFC 3339）；缺省用 new Date().toISOString()。 */
+    now?: () => string;
+}
+export declare class IdempotencyStore {
+    private readonly baseDir;
+    private readonly indexDir;
+    private readonly now;
+    constructor(options: IdempotencyStoreOptions);
+    private ensureIndexDir;
+    /** 记录文件名：`idem-<sha256(key)>.json`。key 内容在文件内自描述。 */
+    private filePathFor;
+    private writeFileAtomic;
+    private readRecord;
+    /** 记录是否已过期（expires_at <= nowIso）。 */
+    private isExpired;
+    /**
+     * 幂等三态判定（§20.1–§20.3）。只读，不写盘。
+     * 已过期记录视同「新消息」：retention 窗口外重放由状态校验决定，而非幂等层。
+     */
+    check(input: IdempotencyCheckInput): IdempotencyDecision;
+    /**
+     * 提交一次成功处理。check 之后调用；若 check 与 commit 之间已有同 key 记录，
+     * 同 digest → 幂等返回既有记录；异 digest → 抛 IdempotencyConflictError。
+     */
+    commit(input: IdempotencyCommitInput): IdempotencyRecord;
+    /** 读取记录（供恢复/调试）；未知或已过期返回 null。 */
+    get(senderIdentity: string, messageId: string): IdempotencyRecord | null;
+    /** 过期记录清理；返回移除条数。不触碰 Ledger（§22：删除索引不影响审计链）。 */
+    sweep(nowIso?: string): number;
+    /** 索引规模（含过期，供诊断）。 */
+    count(): number;
+    private readRecordFromPath;
+}

package/dist/negotiation/idempotency/store.js

@@ -0,0 +1,189 @@
+/**
+ * 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.
+ */
+/**
+ * 协议级幂等存储（基线 §17 / 子规范 §20）。
+ *
+ * 独立于 Ledger 持久化（幂等索引与审计链可分开部署），但每次 commit 记录都会
+ * 引用判定证据所在 Ledger 事件（ledger_event_id / ledger_event_digest，§22）。
+ *
+ * 判定流程（check → 执行/重放/冲突）：
+ *   1. check((sender_identity, message_id, digest))
+ *      - 无记录或已过期         → { status: "new" }        调用方执行业务效果
+ *      - 同 key 同 digest       → { status: "replayed" }   返回原结果，绝不重复执行
+ *      - 同 key 异 digest       → { status: "conflict" }   返回 idempotency_conflict，fail-closed
+ *   2. 执行成功后 commit(输入 + outcome + ledger 证据) → 落盘。
+ *      commit 再次核验：key 已存在且 digest 不同 → 抛 IdempotencyConflictError
+ *      （check 与 commit 之间的并发兜底）。
+ *
+ * retention（§20.5）：expires_at = max(now + 24h, offer_valid_until,
+ * task_lifetime_until)；sweep() 删除 expires_at <= now 的记录（可独立于 Ledger
+ * 执行 —— Ledger 是 append-only 审计链，删除幂等索引不影响审计完整性）。
+ *
+ * 本地持久化：目录 0700、文件 0600；写采用 supervisor/manifest.ts 的原子写
+ * （同目录临时文件 wx + fsync + rename）。
+ */
+import { chmodSync, closeSync, existsSync, fsyncSync, mkdirSync, openSync, readdirSync, readFileSync, renameSync, rmSync, writeSync, } from "node:fs";
+import path from "node:path";
+import { sha256Hex } from "../jcs.js";
+import { IdempotencyConflictError, computeRetentionDeadline, idempotencyKey } from "./types.js";
+let tmpSeq = 0;
+export class IdempotencyStore {
+    baseDir;
+    indexDir;
+    now;
+    constructor(options) {
+        this.baseDir = options.dir;
+        this.indexDir = path.join(options.dir, "idempotency");
+        this.now = options.now ?? (() => new Date().toISOString());
+    }
+    ensureIndexDir() {
+        mkdirSync(this.indexDir, { recursive: true, mode: 0o700 });
+        chmodSync(this.indexDir, 0o700);
+        return this.indexDir;
+    }
+    /** 记录文件名：`idem-<sha256(key)>.json`。key 内容在文件内自描述。 */
+    filePathFor(key) {
+        const dir = this.ensureIndexDir();
+        const name = `idem-${sha256Hex(key)}.json`;
+        return path.resolve(dir, name);
+    }
+    writeFileAtomic(filePath, record) {
+        const tmp = `${filePath}.tmp-${process.pid}-${++tmpSeq}`;
+        const fd = openSync(tmp, "wx", 0o600);
+        try {
+            writeSync(fd, `${JSON.stringify(record)}\n`);
+            fsyncSync(fd);
+        }
+        finally {
+            closeSync(fd);
+        }
+        renameSync(tmp, filePath);
+        chmodSync(filePath, 0o600);
+    }
+    readRecord(key) {
+        const filePath = this.filePathFor(key);
+        if (!existsSync(filePath))
+            return null;
+        const parsed = JSON.parse(readFileSync(filePath, "utf-8"));
+        if (parsed === null || typeof parsed !== "object")
+            return null;
+        const record = parsed;
+        if (typeof record.sender_identity !== "string" ||
+            typeof record.message_id !== "string" ||
+            typeof record.digest !== "string" ||
+            typeof record.negotiation_id !== "string" ||
+            typeof record.recorded_at !== "string" ||
+            typeof record.expires_at !== "string" ||
+            record.outcome === undefined ||
+            typeof record.outcome !== "object") {
+            return null;
+        }
+        return record;
+    }
+    /** 记录是否已过期（expires_at <= nowIso）。 */
+    isExpired(record, nowIso) {
+        return Date.parse(record.expires_at) <= Date.parse(nowIso);
+    }
+    /**
+     * 幂等三态判定（§20.1–§20.3）。只读，不写盘。
+     * 已过期记录视同「新消息」：retention 窗口外重放由状态校验决定，而非幂等层。
+     */
+    check(input) {
+        const key = idempotencyKey(input.sender_identity, input.message_id);
+        const existing = this.readRecord(key);
+        if (existing === null || this.isExpired(existing, this.now())) {
+            return { status: "new", key };
+        }
+        if (existing.digest === input.digest) {
+            return { status: "replayed", key, record: existing };
+        }
+        return { status: "conflict", key, record: existing };
+    }
+    /**
+     * 提交一次成功处理。check 之后调用；若 check 与 commit 之间已有同 key 记录，
+     * 同 digest → 幂等返回既有记录；异 digest → 抛 IdempotencyConflictError。
+     */
+    commit(input) {
+        const key = idempotencyKey(input.sender_identity, input.message_id);
+        const existing = this.readRecord(key);
+        if (existing !== null && !this.isExpired(existing, this.now())) {
+            if (existing.digest === input.digest)
+                return existing;
+            throw new IdempotencyConflictError(existing, input.digest);
+        }
+        const nowIso = this.now();
+        const expiresAt = computeRetentionDeadline(new Date(nowIso), input.retention).toISOString();
+        const record = {
+            sender_identity: input.sender_identity,
+            message_id: input.message_id,
+            digest: input.digest,
+            negotiation_id: input.negotiation_id,
+            outcome: input.outcome,
+            recorded_at: nowIso,
+            expires_at: expiresAt,
+        };
+        if (input.ledger_event_id !== undefined)
+            record.ledger_event_id = input.ledger_event_id;
+        if (input.ledger_event_digest !== undefined) {
+            record.ledger_event_digest = input.ledger_event_digest;
+        }
+        this.writeFileAtomic(this.filePathFor(key), record);
+        return record;
+    }
+    /** 读取记录（供恢复/调试）；未知或已过期返回 null。 */
+    get(senderIdentity, messageId) {
+        const key = idempotencyKey(senderIdentity, messageId);
+        const record = this.readRecord(key);
+        if (record === null)
+            return null;
+        return this.isExpired(record, this.now()) ? null : record;
+    }
+    /** 过期记录清理；返回移除条数。不触碰 Ledger（§22：删除索引不影响审计链）。 */
+    sweep(nowIso) {
+        const dir = this.ensureIndexDir();
+        const now = nowIso ?? this.now();
+        let removed = 0;
+        for (const name of readdirSync(dir)) {
+            if (!name.startsWith("idem-") || !name.endsWith(".json"))
+                continue;
+            const filePath = path.join(dir, name);
+            try {
+                const record = this.readRecordFromPath(filePath);
+                if (record !== null && this.isExpired(record, now)) {
+                    rmSync(filePath);
+                    removed += 1;
+                }
+            }
+            catch {
+                // 单个损坏记录不阻断 sweep；继续清理其余。
+            }
+        }
+        return removed;
+    }
+    /** 索引规模（含过期，供诊断）。 */
+    count() {
+        const dir = this.ensureIndexDir();
+        return readdirSync(dir).filter((name) => name.startsWith("idem-") && name.endsWith(".json"))
+            .length;
+    }
+    readRecordFromPath(filePath) {
+        const parsed = JSON.parse(readFileSync(filePath, "utf-8"));
+        if (parsed === null || typeof parsed !== "object")
+            return null;
+        return parsed;
+    }
+}
+//# sourceMappingURL=store.js.map

package/dist/negotiation/idempotency/store.js.map

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

package/dist/negotiation/idempotency/types.d.ts

@@ -0,0 +1,102 @@
+/**
+ * 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.
+ */
+/**
+ * 协议级幂等模型（基线 §17 / 子规范 §20 Idempotency and Replay）。
+ *
+ * 主键 (sender_identity, message_id)：
+ * - same id + same digest  → 不得重复执行业务效果，返回原结果或等价 ack（§20.2）；
+ * - same id + different digest → idempotency_conflict，fail-closed，绝不应用新 payload
+ *   （§20.3）。
+ *
+ * retention（§20.5 / 基线 §17）：至少覆盖
+ *   max(offer validity, task lifetime, 24 hours)。
+ * 参考实现以 24h 为地板，配合调用方给出的 offer_valid_until / task_lifetime_until
+ * 计算过期时间；过期后按「新消息」处理（允许再次进入状态校验）。
+ *
+ * 与 Ledger 的关系：幂等索引可独立存储，但判定证据落 Ledger —— 每次 commit 都应
+ * 携带对应的 ledger_event_id / ledger_event_digest，审计可交叉验证（§22）。
+ */
+/** 幂等记录：一次 (sender_identity, message_id) 的处理事实。 */
+export interface IdempotencyRecord {
+    sender_identity: string;
+    message_id: string;
+    /** wire digest（KNP envelope digest，§19.2）。replay 时必须逐字节一致。 */
+    digest: string;
+    negotiation_id: string;
+    /** 原处理结果：成功（可带结构化 result）或协议错误（code 对齐 §18 词表）。 */
+    outcome: {
+        kind: "ok";
+        result?: unknown;
+    } | {
+        kind: "error";
+        code: string;
+        message: string;
+    };
+    /** 判定证据的 Ledger 事件引用（§22：判定证据落 Ledger）。 */
+    ledger_event_id?: string;
+    ledger_event_digest?: string;
+    /** 首处理时间（RFC 3339）。 */
+    recorded_at: string;
+    /** retention 截止（RFC 3339）；sweep 只清理 expires_at <= now 的记录。 */
+    expires_at: string;
+}
+export type IdempotencyDecision = {
+    status: "new";
+    key: string;
+} | {
+    status: "replayed";
+    key: string;
+    record: IdempotencyRecord;
+} | {
+    status: "conflict";
+    key: string;
+    record: IdempotencyRecord;
+};
+export interface IdempotencyCheckInput {
+    sender_identity: string;
+    message_id: string;
+    digest: string;
+}
+/** commit 的完整输入：除了持久化字段，还带 retention 计算所需的时限。 */
+export interface IdempotencyCommitInput extends IdempotencyCheckInput {
+    negotiation_id: string;
+    outcome: IdempotencyRecord["outcome"];
+    ledger_event_id?: string;
+    ledger_event_digest?: string;
+    retention?: RetentionInput;
+}
+/** retention 时限提示；offer_valid_until / task_lifetime_until 均优先于 24h 地板。 */
+export interface RetentionInput {
+    /** 仍有效的 offer 截止（RFC 3339），即 offer terms 的 valid_until。 */
+    offer_valid_until?: string;
+    /** A2A task 生命周期截止（RFC 3339）。 */
+    task_lifetime_until?: string;
+}
+/** 幂等键：null 字节分隔，避免 (a, b) 与 (ab, "") 之类碰撞。 */
+export declare function idempotencyKey(senderIdentity: string, messageId: string): string;
+/** 24 小时 retention 地板（基线 §17 / 子规范 §20.5）。 */
+export declare const IDEMPOTENCY_FLOOR_MS: number;
+/**
+ * 计算过期截止 = max(now + 24h, offer_valid_until, task_lifetime_until)。
+ * 无效/过去的时限自动被地板覆盖。
+ */
+export declare function computeRetentionDeadline(now: Date, input?: RetentionInput): Date;
+/** same id + different digest → idempotency_conflict（§20.3 / §18 词表）。 */
+export declare class IdempotencyConflictError extends Error {
+    readonly code: "idempotency_conflict";
+    readonly record: IdempotencyRecord;
+    constructor(record: IdempotencyRecord, digest: string);
+}

package/dist/negotiation/idempotency/types.js

@@ -0,0 +1,47 @@
+/**
+ * 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.
+ */
+/** 幂等键：null 字节分隔，避免 (a, b) 与 (ab, "") 之类碰撞。 */
+export function idempotencyKey(senderIdentity, messageId) {
+    return `${senderIdentity}\u0000${messageId}`;
+}
+/** 24 小时 retention 地板（基线 §17 / 子规范 §20.5）。 */
+export const IDEMPOTENCY_FLOOR_MS = 24 * 60 * 60 * 1000;
+/**
+ * 计算过期截止 = max(now + 24h, offer_valid_until, task_lifetime_until)。
+ * 无效/过去的时限自动被地板覆盖。
+ */
+export function computeRetentionDeadline(now, input = {}) {
+    let deadline = now.getTime() + IDEMPOTENCY_FLOOR_MS;
+    for (const iso of [input.offer_valid_until, input.task_lifetime_until]) {
+        if (iso === undefined)
+            continue;
+        const t = Date.parse(iso);
+        if (!Number.isNaN(t) && t > deadline)
+            deadline = t;
+    }
+    return new Date(deadline);
+}
+/** same id + different digest → idempotency_conflict（§20.3 / §18 词表）。 */
+export class IdempotencyConflictError extends Error {
+    code = "idempotency_conflict";
+    record;
+    constructor(record, digest) {
+        super(`idempotency_conflict: (${record.sender_identity}, ${record.message_id}) already processed with digest ${record.digest}, got ${digest}`);
+        this.name = "IdempotencyConflictError";
+        this.record = record;
+    }
+}
+//# sourceMappingURL=types.js.map

package/dist/negotiation/idempotency/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/negotiation/idempotency/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAiEH,+CAA+C;AAC/C,MAAM,UAAU,cAAc,CAAC,cAAsB,EAAE,SAAiB;IACtE,OAAO,GAAG,cAAc,SAAS,SAAS,EAAE,CAAC;AAC/C,CAAC;AAED,8CAA8C;AAC9C,MAAM,CAAC,MAAM,oBAAoB,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AAExD;;;GAGG;AACH,MAAM,UAAU,wBAAwB,CAAC,GAAS,EAAE,QAAwB,EAAE;IAC5E,IAAI,QAAQ,GAAG,GAAG,CAAC,OAAO,EAAE,GAAG,oBAAoB,CAAC;IACpD,KAAK,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,iBAAiB,EAAE,KAAK,CAAC,mBAAmB,CAAC,EAAE,CAAC;QACvE,IAAI,GAAG,KAAK,SAAS;YAAE,SAAS;QAChC,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAC1B,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,QAAQ;YAAE,QAAQ,GAAG,CAAC,CAAC;IACrD,CAAC;IACD,OAAO,IAAI,IAAI,CAAC,QAAQ,CAAC,CAAC;AAC5B,CAAC;AAED,yEAAyE;AACzE,MAAM,OAAO,wBAAyB,SAAQ,KAAK;IACxC,IAAI,GAAG,sBAA+B,CAAC;IACvC,MAAM,CAAoB;IACnC,YAAY,MAAyB,EAAE,MAAc;QACnD,KAAK,CACH,0BAA0B,MAAM,CAAC,eAAe,KAAK,MAAM,CAAC,UAAU,mCAAmC,MAAM,CAAC,MAAM,SAAS,MAAM,EAAE,CACxI,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,0BAA0B,CAAC;QACvC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;CACF"}

package/dist/negotiation/jcs.d.ts

@@ -0,0 +1,21 @@
+/**
+ * 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.
+ */
+/** RFC 8785 JCS canonical serialization of a JSON-compatible value. */
+export declare function canonicalize(value: unknown): string;
+/** sha256 hex of a UTF-8 string. */
+export declare function sha256Hex(input: string): string;
+/** Content-addressed digest of a structured value, `sha256:` prefixed. */
+export declare function contentDigest(value: unknown): string;

package/dist/negotiation/jcs.js

@@ -0,0 +1,114 @@
+/**
+ * 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.
+ */
+/**
+ * RFC 8785 JCS (JSON Canonicalization Scheme) — minimal deterministic
+ * serialization used for content addressing (docs §17 "Digest 与幂等").
+ *
+ * Pure and deterministic: no eval/exec, no random or time-dependent output.
+ * Equal inputs always serialize to the same byte string; object key order in
+ * the input is irrelevant (keys are sorted by UTF-16 code unit), which is
+ * what makes the digest stable across retries and restarts.
+ *
+ * The repo previously used a hand-rolled `stableStringify` (sorted keys, JSON
+ * values) for idempotency hashes. JCS is stricter about number serialization
+ * (`-0`, exponent normalization) and rejects non-finite numbers instead of
+ * silently hashing them. New content-addressed values (candidate_digest) MUST
+ * go through this module; the legacy helper is left untouched for v0.3 stores.
+ */
+import { createHash } from "node:crypto";
+/**
+ * RFC 8785 §3.2.2.2 number serialization: shortest round-trip form with a
+ * normalized exponent (lowercase 'e', no leading '+' or exponent zeros), `-0`
+ * preserved, NaN/Infinity rejected.
+ */
+function canonicalNumber(value) {
+    if (!Number.isFinite(value)) {
+        throw new TypeError(`JCS: cannot canonicalize non-finite number ${value}`);
+    }
+    if (Object.is(value, -0))
+        return "-0";
+    // Number#toString produces the shortest round-trip representation, which
+    // RFC 8785 requires. Only the exponent needs normalization.
+    let serialized = String(value);
+    const exponent = /^(.+?)[eE]([+-]?)(\d+)$/.exec(serialized);
+    if (exponent !== null) {
+        const mantissa = exponent[1] ?? serialized;
+        const sign = exponent[2] === "-" ? "-" : "";
+        const digits = (exponent[3] ?? "").replace(/^0+/, "");
+        serialized = `${mantissa}e${sign}${digits === "" ? "0" : digits}`;
+    }
+    return serialized;
+}
+/**
+ * RFC 8785 §3.2.2.1 字符串序列化：`"`/`\`/控制字符（JSON.stringify 已处理）
+ * + U+2028/U+2029（JSON.stringify 原样输出——RFC 8785 要求转义，否则与
+ * 按规范转义的实现产生不同 digest，跨实现互操作断裂）。
+ */
+function canonicalString(value) {
+    // 正则字面量用 \u2028/\u2029 Unicode 转义（非控制字符转义，eslint
+    // no-control-regex 不适用），匹配 U+2028（行分隔符）/ U+2029（段落分隔符）字符本身。
+    return JSON.stringify(value)
+        .replace(/\u2028/g, "\\u2028")
+        .replace(/\u2029/g, "\\u2029");
+}
+function canonicalValue(value) {
+    if (value === null)
+        return "null";
+    switch (typeof value) {
+        case "string":
+            return canonicalString(value);
+        case "boolean":
+            return value ? "true" : "false";
+        case "number":
+            return canonicalNumber(value);
+        case "object": {
+            if (Array.isArray(value)) {
+                return `[${value
+                    .map((element) => {
+                    if (element === undefined) {
+                        throw new TypeError("JCS: array elements must not be undefined");
+                    }
+                    return canonicalValue(element);
+                })
+                    .join(",")}]`;
+            }
+            const record = value;
+            // Undefined-valued keys are optional fields and are skipped, matching
+            // the rest of the codebase; every other non-JSON value fails closed.
+            const keys = Object.keys(record)
+                .filter((key) => record[key] !== undefined)
+                .sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+            return `{${keys.map((key) => `${canonicalString(key)}:${canonicalValue(record[key])}`).join(",")}}`;
+        }
+        default:
+            // functions, symbols, bigint: not part of the JSON data model — fail
+            // closed rather than producing a digest that hides the shape.
+            throw new TypeError(`JCS: cannot canonicalize ${typeof value}`);
+    }
+}
+/** RFC 8785 JCS canonical serialization of a JSON-compatible value. */
+export function canonicalize(value) {
+    return canonicalValue(value);
+}
+/** sha256 hex of a UTF-8 string. */
+export function sha256Hex(input) {
+    return createHash("sha256").update(input, "utf8").digest("hex");
+}
+/** Content-addressed digest of a structured value, `sha256:` prefixed. */
+export function contentDigest(value) {
+    return `sha256:${sha256Hex(canonicalize(value))}`;
+}
+//# sourceMappingURL=jcs.js.map

package/dist/negotiation/jcs.js.map

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