@harrylabsj/kiwi 0.6.0

package/dist/negotiation/context-map/types.d.ts

@@ -0,0 +1,29 @@
+/**
+ * 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.
+ */
+export interface ContextMapping {
+    negotiation_id: string;
+    /** 远端 A2A contextId（opaque，§9.2）。 */
+    remote_context_id?: string;
+    /** 本 negotiation 用过的 A2A taskId 列表（§9.5，非 negotiation_id 替代）。 */
+    task_ids: string[];
+    updated_at: string;
+}
+/** 增量更新：只更新提供的字段；task_ids 通过 addTask 追加。 */
+export interface ContextMappingPatch {
+    remote_context_id?: string;
+}
+/** 从磁盘解析一条映射（untrusted）。任何字段违规 → 抛 NegotiationValidationError。 */
+export declare function parseContextMapping(value: unknown): ContextMapping;

package/dist/negotiation/context-map/types.js

@@ -0,0 +1,57 @@
+/**
+ * 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.
+ */
+/**
+ * negotiation_id ↔ 远端 A2A context 映射模型（基线 §9.2 / 子规范 §6.6–§6.7）。
+ *
+ * Kiwi 持久化：
+ *
+ * ```text
+ * negotiation_id ↔ remote contextId（可含 taskId 列表）
+ * ```
+ *
+ * 边界（§9.2 / §24.4 / §24.5）：
+ * - `remote_context_id` 对 Kiwi 完全 opaque —— 只做结构校验（validateContextId），
+ *   不解析、不推断其含义；后续交互复用同一 contextId。
+ * - `task_ids` 是同一 negotiation 用过的 A2A taskId 列表；taskId 只是
+ *   transport/session 状态，不得替代 negotiation_id（§9.5）。
+ * - 校验 fail-closed：任何字段不符合 opaque 标识符规则即拒绝。
+ */
+import { requireIsoTimestamp } from "../domain/common.js";
+import { validateContextId, validateIdentifier, validateTaskId } from "../domain/identifiers.js";
+/** 从磁盘解析一条映射（untrusted）。任何字段违规 → 抛 NegotiationValidationError。 */
+export function parseContextMapping(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error("context mapping must be an object");
+    }
+    const obj = value;
+    const negotiationId = validateIdentifier(obj.negotiation_id, "negotiation_id");
+    const mapping = {
+        negotiation_id: negotiationId,
+        task_ids: [],
+        updated_at: requireIsoTimestamp(obj.updated_at, "updated_at"),
+    };
+    if (obj.remote_context_id !== undefined) {
+        mapping.remote_context_id = validateContextId(obj.remote_context_id, "remote_context_id");
+    }
+    if (obj.task_ids !== undefined) {
+        if (!Array.isArray(obj.task_ids)) {
+            throw new Error("context mapping task_ids must be an array");
+        }
+        mapping.task_ids = obj.task_ids.map((id, i) => validateTaskId(id, `task_ids/${i}`));
+    }
+    return mapping;
+}
+//# sourceMappingURL=types.js.map

package/dist/negotiation/context-map/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/negotiation/context-map/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAgBjG,kEAAkE;AAClE,MAAM,UAAU,mBAAmB,CAAC,KAAc;IAChD,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACxE,MAAM,IAAI,KAAK,CAAC,mCAAmC,CAAC,CAAC;IACvD,CAAC;IACD,MAAM,GAAG,GAAG,KAAgC,CAAC;IAC7C,MAAM,aAAa,GAAG,kBAAkB,CAAC,GAAG,CAAC,cAAc,EAAE,gBAAgB,CAAC,CAAC;IAC/E,MAAM,OAAO,GAAmB;QAC9B,cAAc,EAAE,aAAa;QAC7B,QAAQ,EAAE,EAAE;QACZ,UAAU,EAAE,mBAAmB,CAAC,GAAG,CAAC,UAAU,EAAE,YAAY,CAAC;KAC9D,CAAC;IACF,IAAI,GAAG,CAAC,iBAAiB,KAAK,SAAS,EAAE,CAAC;QACxC,OAAO,CAAC,iBAAiB,GAAG,iBAAiB,CAAC,GAAG,CAAC,iBAAiB,EAAE,mBAAmB,CAAC,CAAC;IAC5F,CAAC;IACD,IAAI,GAAG,CAAC,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC/B,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;YACjC,MAAM,IAAI,KAAK,CAAC,2CAA2C,CAAC,CAAC;QAC/D,CAAC;QACD,OAAO,CAAC,QAAQ,GAAG,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC,cAAc,CAAC,EAAE,EAAE,YAAY,CAAC,EAAE,CAAC,CAAC,CAAC;IACtF,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/negotiation/domain/common.d.ts

@@ -0,0 +1,95 @@
+/**
+ * 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 公共数据类型与校验原语（子规范 §7 Common Data Types）。
+ *
+ * Money、Quantity、TermSet 是所有 negotiation object 共享的基础类型。
+ * 校验采用 fail-closed（基线 §4.6 / §33）：无法证明合法即为非法。
+ * 所有校验错误统一抛出 NegotiationValidationError，`code` 对齐子规范 §18
+ * 的 protocol error 词表（默认 schema_invalid；具体语义错误如
+ * protocol_version_unsupported / field_unsupported / state_conflict 单独标注）。
+ */
+export declare const KNP_PROTOCOL_VERSION: "1.0";
+/** KNP/1.0 协议错误词表（子规范 §18）。 */
+export declare const PROTOCOL_ERROR_CODES: readonly ["protocol_version_unsupported", "capability_incompatible", "schema_invalid", "field_unsupported", "structured_text_conflict", "identity_rejected", "authentication_required", "authorization_failed", "offer_unknown", "offer_expired", "offer_withdrawn", "terms_digest_mismatch", "condition_conflict", "state_conflict", "approval_required", "idempotency_conflict", "replay_detected", "rate_limited", "temporarily_unavailable", "reconciliation_required"];
+export type ProtocolErrorCode = (typeof PROTOCOL_ERROR_CODES)[number];
+/** 结构/语义校验失败。`path` 为 JSON Pointer 风格的字段路径。 */
+export declare class NegotiationValidationError extends Error {
+    readonly code: ProtocolErrorCode;
+    readonly path: string;
+    constructor(code: ProtocolErrorCode, message: string, path: string);
+}
+/** 默认 schema 校验错误。 */
+export declare function schemaError(path: string, message: string): NegotiationValidationError;
+export declare function requireObject(value: unknown, path: string): Record<string, unknown>;
+export declare function requireArray(value: unknown, path: string): unknown[];
+export declare function requireString(value: unknown, path: string): string;
+export declare function requireNonEmptyString(value: unknown, path: string): string;
+/** 整数（含 0 与负数）；Number.isInteger 同时排除 NaN/Infinity/float。 */
+export declare function requireInteger(value: unknown, path: string): number;
+/** 布尔（v0.7.0 KTH 三副作用不变量等）。 */
+export declare function requireBoolean(value: unknown, path: string): boolean;
+export declare function requirePositiveNumber(value: unknown, path: string): number;
+export declare function requireEnum<T extends string>(value: unknown, allowed: readonly T[], path: string): T;
+/**
+ * RFC 3339 时间戳（子规范 §7.3）。
+ * 格式正则之外还要 Date.parse 真实可解析：`2026-13-01T00:00:00Z` 等越界
+ * 时间/日期能过正则但 Date.parse 返回 NaN（fail-open 缺口，见
+ * transaction.ts 过期门）。不可解析 → schemaError（fail-closed）。
+ */
+export declare function requireIsoTimestamp(value: unknown, path: string): string;
+/** `sha256:` 前缀的小写 hex 摘要（子规范 §19.2/§19.3）。 */
+export declare function requireDigest(value: unknown, path: string): string;
+/** 判别字段检查：`obj.type` 必须等于期望值。 */
+export declare function requireType(obj: Record<string, unknown>, expected: string, path: string): void;
+export interface Money {
+    /** 三位大写货币代码。 */
+    currency: string;
+    /** 最小货币单位；协议禁止 float 金额（§7.1）。 */
+    amount_minor: number;
+}
+export declare function validateMoney(value: unknown, path: string): Money;
+export interface Quantity {
+    /** 正数（§7.2）。 */
+    value: number;
+    unit: string;
+}
+export declare function validateQuantity(value: unknown, path: string): Quantity;
+export interface LineItem {
+    sku: string;
+    quantity: Quantity;
+    /** Offer 等 offer-like 项的 unit_price 由调用方通过 opts 强制。 */
+    unit_price?: Money;
+}
+export declare function validateLineItem(value: unknown, path: string, opts?: {
+    requireUnitPrice?: boolean;
+}): LineItem;
+export interface TermSet {
+    items?: LineItem[];
+    price_terms?: Record<string, unknown>;
+    fulfillment_terms?: Record<string, unknown>;
+    service_terms?: Record<string, unknown>;
+    payment_terms?: Record<string, unknown>;
+    valid_until?: string;
+}
+/**
+ * TermSet 校验（§7.4）。稳定顶层域：items / price_terms / fulfillment_terms /
+ * service_terms / payment_terms / valid_until。payment_terms 只表达商业条件，
+ * 不代表支付授权。
+ */
+export declare function validateTermSet(value: unknown, path: string, opts?: {
+    requireUnitPrice?: boolean;
+}): TermSet;

package/dist/negotiation/domain/common.js

@@ -0,0 +1,216 @@
+/**
+ * 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 公共数据类型与校验原语（子规范 §7 Common Data Types）。
+ *
+ * Money、Quantity、TermSet 是所有 negotiation object 共享的基础类型。
+ * 校验采用 fail-closed（基线 §4.6 / §33）：无法证明合法即为非法。
+ * 所有校验错误统一抛出 NegotiationValidationError，`code` 对齐子规范 §18
+ * 的 protocol error 词表（默认 schema_invalid；具体语义错误如
+ * protocol_version_unsupported / field_unsupported / state_conflict 单独标注）。
+ */
+export const KNP_PROTOCOL_VERSION = "1.0";
+/** KNP/1.0 协议错误词表（子规范 §18）。 */
+export const PROTOCOL_ERROR_CODES = [
+    "protocol_version_unsupported",
+    "capability_incompatible",
+    "schema_invalid",
+    "field_unsupported",
+    "structured_text_conflict",
+    "identity_rejected",
+    "authentication_required",
+    "authorization_failed",
+    "offer_unknown",
+    "offer_expired",
+    "offer_withdrawn",
+    "terms_digest_mismatch",
+    "condition_conflict",
+    "state_conflict",
+    "approval_required",
+    "idempotency_conflict",
+    "replay_detected",
+    "rate_limited",
+    "temporarily_unavailable",
+    "reconciliation_required",
+];
+/** 结构/语义校验失败。`path` 为 JSON Pointer 风格的字段路径。 */
+export class NegotiationValidationError extends Error {
+    code;
+    path;
+    constructor(code, message, path) {
+        super(message);
+        this.name = "NegotiationValidationError";
+        this.code = code;
+        this.path = path;
+    }
+}
+/** 默认 schema 校验错误。 */
+export function schemaError(path, message) {
+    return new NegotiationValidationError("schema_invalid", message, path);
+}
+// ---------------------------------------------------------------------------
+// 校验原语
+// ---------------------------------------------------------------------------
+export function requireObject(value, path) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        throw schemaError(path, `${path} must be an object`);
+    }
+    return value;
+}
+export function requireArray(value, path) {
+    if (!Array.isArray(value)) {
+        throw schemaError(path, `${path} must be an array`);
+    }
+    return value;
+}
+export function requireString(value, path) {
+    if (typeof value !== "string") {
+        throw schemaError(path, `${path} must be a string`);
+    }
+    return value;
+}
+export function requireNonEmptyString(value, path) {
+    const s = requireString(value, path);
+    if (s.length === 0) {
+        throw schemaError(path, `${path} must be a non-empty string`);
+    }
+    return s;
+}
+/** 整数（含 0 与负数）；Number.isInteger 同时排除 NaN/Infinity/float。 */
+export function requireInteger(value, path) {
+    if (typeof value !== "number" || !Number.isInteger(value)) {
+        throw schemaError(path, `${path} must be an integer`);
+    }
+    return value;
+}
+/** 布尔（v0.7.0 KTH 三副作用不变量等）。 */
+export function requireBoolean(value, path) {
+    if (typeof value !== "boolean") {
+        throw schemaError(path, `${path} must be a boolean`);
+    }
+    return value;
+}
+export function requirePositiveNumber(value, path) {
+    if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
+        throw schemaError(path, `${path} must be a positive number`);
+    }
+    return value;
+}
+export function requireEnum(value, allowed, path) {
+    const s = requireNonEmptyString(value, path);
+    if (!allowed.includes(s)) {
+        throw schemaError(path, `${path} must be one of ${allowed.join("|")}`);
+    }
+    return s;
+}
+const RFC3339 = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$/;
+/**
+ * RFC 3339 时间戳（子规范 §7.3）。
+ * 格式正则之外还要 Date.parse 真实可解析：`2026-13-01T00:00:00Z` 等越界
+ * 时间/日期能过正则但 Date.parse 返回 NaN（fail-open 缺口，见
+ * transaction.ts 过期门）。不可解析 → schemaError（fail-closed）。
+ */
+export function requireIsoTimestamp(value, path) {
+    const s = requireNonEmptyString(value, path);
+    if (!RFC3339.test(s)) {
+        throw schemaError(path, `${path} must be an RFC 3339 timestamp`);
+    }
+    if (!Number.isFinite(Date.parse(s))) {
+        throw schemaError(path, `${path} must be a parseable RFC 3339 timestamp`);
+    }
+    return s;
+}
+const DIGEST = /^sha256:[0-9a-f]{64}$/;
+/** `sha256:` 前缀的小写 hex 摘要（子规范 §19.2/§19.3）。 */
+export function requireDigest(value, path) {
+    const s = requireNonEmptyString(value, path);
+    if (!DIGEST.test(s)) {
+        throw schemaError(path, `${path} must be sha256:<64 lowercase hex>`);
+    }
+    return s;
+}
+/** 判别字段检查：`obj.type` 必须等于期望值。 */
+export function requireType(obj, expected, path) {
+    if (obj.type !== expected) {
+        throw schemaError(`${path}/type`, `type must be ${expected}`);
+    }
+}
+export function validateMoney(value, path) {
+    const obj = requireObject(value, path);
+    const currency = requireNonEmptyString(obj.currency, `${path}/currency`);
+    if (!/^[A-Z]{3}$/.test(currency)) {
+        throw schemaError(`${path}/currency`, "currency must be a three-letter uppercase code");
+    }
+    const amountMinor = requireInteger(obj.amount_minor, `${path}/amount_minor`);
+    if (amountMinor < 0) {
+        throw schemaError(`${path}/amount_minor`, "amount_minor must be a non-negative integer");
+    }
+    return { currency, amount_minor: amountMinor };
+}
+export function validateQuantity(value, path) {
+    const obj = requireObject(value, path);
+    return {
+        value: requirePositiveNumber(obj.value, `${path}/value`),
+        unit: requireNonEmptyString(obj.unit, `${path}/unit`),
+    };
+}
+export function validateLineItem(value, path, opts = {}) {
+    const obj = requireObject(value, path);
+    const item = {
+        sku: requireNonEmptyString(obj.sku, `${path}/sku`),
+        quantity: validateQuantity(obj.quantity, `${path}/quantity`),
+    };
+    if (obj.unit_price !== undefined) {
+        item.unit_price = validateMoney(obj.unit_price, `${path}/unit_price`);
+    }
+    else if (opts.requireUnitPrice === true) {
+        throw schemaError(`${path}/unit_price`, "unit_price is required on offer-like items");
+    }
+    return item;
+}
+/**
+ * TermSet 校验（§7.4）。稳定顶层域：items / price_terms / fulfillment_terms /
+ * service_terms / payment_terms / valid_until。payment_terms 只表达商业条件，
+ * 不代表支付授权。
+ */
+export function validateTermSet(value, path, opts = {}) {
+    const obj = requireObject(value, path);
+    const terms = {};
+    if (obj.items !== undefined) {
+        terms.items = requireArray(obj.items, `${path}/items`).map((item, i) => validateLineItem(item, `${path}/items/${i}`, opts));
+    }
+    if (obj.price_terms !== undefined) {
+        terms.price_terms = requireObject(obj.price_terms, `${path}/price_terms`);
+    }
+    if (obj.fulfillment_terms !== undefined) {
+        const fulfillment = requireObject(obj.fulfillment_terms, `${path}/fulfillment_terms`);
+        if (fulfillment.delivery_before !== undefined) {
+            requireIsoTimestamp(fulfillment.delivery_before, `${path}/fulfillment_terms/delivery_before`);
+        }
+        terms.fulfillment_terms = fulfillment;
+    }
+    if (obj.service_terms !== undefined) {
+        terms.service_terms = requireObject(obj.service_terms, `${path}/service_terms`);
+    }
+    if (obj.payment_terms !== undefined) {
+        terms.payment_terms = requireObject(obj.payment_terms, `${path}/payment_terms`);
+    }
+    if (obj.valid_until !== undefined) {
+        terms.valid_until = requireIsoTimestamp(obj.valid_until, `${path}/valid_until`);
+    }
+    return terms;
+}
+//# sourceMappingURL=common.js.map

package/dist/negotiation/domain/common.js.map

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

package/dist/negotiation/domain/envelope.d.ts

@@ -0,0 +1,55 @@
+/**
+ * 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 { KNP_PROTOCOL_VERSION } from "./common.js";
+import type { NegotiationAction, NegotiationActor, NegotiationPayload } from "./objects.js";
+export type EnvelopeContent = Omit<NegotiationEnvelope, "digest">;
+export interface NegotiationEnvelope {
+    capability: string;
+    protocol_version: typeof KNP_PROTOCOL_VERSION;
+    negotiation_id: string;
+    exchange_id: string;
+    message_id: string;
+    in_reply_to?: string;
+    actor: NegotiationActor;
+    action: NegotiationAction;
+    created_at: string;
+    payload: NegotiationPayload;
+    public_message?: string;
+    digest: string;
+}
+/**
+ * 计算 envelope digest（§19.2）：移除 digest 自身与 transport signature 字段，
+ * 其余字段 JCS 规范化 + SHA-256。JCS 排序键且跳过 undefined，因此字段顺序
+ * 无关、可选字段缺省不影响摘要。
+ */
+export declare function computeEnvelopeDigest(input: object): string;
+/**
+ * 对未签名字段计算 digest 并返回完整 envelope。
+ *
+ * 命名说明（基线 §19 / §31）：本函数只做内容寻址 digest（JCS + SHA-256），
+ * 不做任何密码学签名。KNP/1.0 envelope 的 digest 是完整性/防篡改校验；
+ * signature 属于 transport 层且 §19.2 显式从 digest 输入中排除——digest 与
+ * signature 是两种性质，故不命名为 sign*。
+ */
+export declare function finalizeEnvelope(fields: EnvelopeContent): NegotiationEnvelope;
+/** 重算 digest 并与 wire digest 比较；false 表示被篡改或过期。 */
+export declare function verifyEnvelopeDigest(envelope: NegotiationEnvelope): boolean;
+/**
+ * Envelope schema 校验。未知 protocol_version / actor 非 buyer|merchant /
+ * action-payload 类型不匹配 / digest 格式错误均 fail-closed。
+ * digest 内容一致性由 verifyEnvelopeDigest 单独校验。
+ */
+export declare function validateEnvelope(value: unknown): NegotiationEnvelope;

package/dist/negotiation/domain/envelope.js

@@ -0,0 +1,110 @@
+/**
+ * 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 Envelope（子规范 §8，基线 §13）。
+ *
+ * digest 按 §19.2 计算：clone 后移除 `digest` 自身与 transport signature 字段，
+ * RFC 8785 JCS 规范化 + SHA-256，hex 小写并加 `sha256:` 前缀。
+ * protocol_version 只认 1.0，未知版本 fail-closed（§5 / §33-6）。
+ * actor 仅 buyer|merchant；system/内部事件不得冒充商业角色（§8.1）。
+ */
+import { contentDigest } from "../jcs.js";
+import { KNP_PROTOCOL_VERSION, NegotiationValidationError, requireDigest, requireEnum, requireIsoTimestamp, requireNonEmptyString, requireObject, requireString, schemaError, } from "./common.js";
+import { validateIdentifier } from "./identifiers.js";
+import { KNP_ACTIONS, validatePayloadForAction } from "./objects.js";
+/** KNP 未定义的 transport signature 字段名：digest 计算时排除（§19.2）。 */
+const TRANSPORT_SIGNATURE_FIELDS = new Set([
+    "signature",
+    "transport_signature",
+    "http_message_signature",
+    "x_message_signature",
+]);
+/**
+ * 计算 envelope digest（§19.2）：移除 digest 自身与 transport signature 字段，
+ * 其余字段 JCS 规范化 + SHA-256。JCS 排序键且跳过 undefined，因此字段顺序
+ * 无关、可选字段缺省不影响摘要。
+ */
+export function computeEnvelopeDigest(input) {
+    const clean = {};
+    for (const key of Object.keys(input)) {
+        if (key === "digest")
+            continue;
+        if (TRANSPORT_SIGNATURE_FIELDS.has(key))
+            continue;
+        clean[key] = input[key];
+    }
+    return contentDigest(clean);
+}
+/**
+ * 对未签名字段计算 digest 并返回完整 envelope。
+ *
+ * 命名说明（基线 §19 / §31）：本函数只做内容寻址 digest（JCS + SHA-256），
+ * 不做任何密码学签名。KNP/1.0 envelope 的 digest 是完整性/防篡改校验；
+ * signature 属于 transport 层且 §19.2 显式从 digest 输入中排除——digest 与
+ * signature 是两种性质，故不命名为 sign*。
+ */
+export function finalizeEnvelope(fields) {
+    return { ...fields, digest: computeEnvelopeDigest(fields) };
+}
+/** 重算 digest 并与 wire digest 比较；false 表示被篡改或过期。 */
+export function verifyEnvelopeDigest(envelope) {
+    const { digest, ...rest } = envelope;
+    return computeEnvelopeDigest(rest) === digest;
+}
+/**
+ * Envelope schema 校验。未知 protocol_version / actor 非 buyer|merchant /
+ * action-payload 类型不匹配 / digest 格式错误均 fail-closed。
+ * digest 内容一致性由 verifyEnvelopeDigest 单独校验。
+ */
+export function validateEnvelope(value) {
+    const obj = requireObject(value, "/");
+    const capability = requireNonEmptyString(obj.capability, "/capability");
+    const protocolVersion = requireNonEmptyString(obj.protocol_version, "/protocol_version");
+    if (protocolVersion !== KNP_PROTOCOL_VERSION) {
+        throw new NegotiationValidationError("protocol_version_unsupported", `unsupported protocol_version ${protocolVersion}; this runtime implements ${KNP_PROTOCOL_VERSION}`, "/protocol_version");
+    }
+    const negotiationId = validateIdentifier(obj.negotiation_id, "/negotiation_id");
+    const exchangeId = validateIdentifier(obj.exchange_id, "/exchange_id");
+    const messageId = validateIdentifier(obj.message_id, "/message_id");
+    const inReplyTo = obj.in_reply_to === undefined ? undefined : validateIdentifier(obj.in_reply_to, "/in_reply_to");
+    const actor = requireEnum(obj.actor, ["buyer", "merchant"], "/actor");
+    const action = requireEnum(obj.action, KNP_ACTIONS, "/action");
+    const createdAt = requireIsoTimestamp(obj.created_at, "/created_at");
+    const payload = validatePayloadForAction(action, obj.payload, "/payload");
+    const publicMessage = obj.public_message === undefined
+        ? undefined
+        : requireString(obj.public_message, "/public_message");
+    const digest = requireDigest(obj.digest, "/digest");
+    // §14：clarification_response 必须通过 in_reply_to 引用被回答的澄清消息。
+    if (action === "clarification_response" && inReplyTo === undefined) {
+        throw schemaError("/in_reply_to", "clarification_response requires in_reply_to");
+    }
+    return {
+        capability,
+        protocol_version: KNP_PROTOCOL_VERSION,
+        negotiation_id: negotiationId,
+        exchange_id: exchangeId,
+        message_id: messageId,
+        in_reply_to: inReplyTo,
+        actor,
+        action,
+        created_at: createdAt,
+        payload,
+        public_message: publicMessage,
+        digest,
+    };
+}
+//# sourceMappingURL=envelope.js.map

package/dist/negotiation/domain/envelope.js.map

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

package/dist/negotiation/domain/identifiers.d.ts

@@ -0,0 +1,65 @@
+/**
+ * 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.
+ */
+export declare const IDENTIFIER_PREFIX: {
+    readonly negotiation: "neg";
+    readonly exchange: "ex";
+    readonly message: "msg";
+    readonly offer: "off";
+    readonly agreement: "agr";
+    readonly handoff_candidate: "hcan";
+    readonly handoff: "hnd";
+};
+export type IdentifierKind = keyof typeof IDENTIFIER_PREFIX;
+/**
+ * UUIDv7：48 位毫秒时间戳 + version(7)/variant(10) 位 + 随机尾（§6 建议可排序）。
+ * rand_a 作 12 位每毫秒计数器，保证同毫秒内也单调不减（时钟回拨时锚定 lastMs）。
+ */
+export declare function uuidv7(): string;
+/** 生成带前缀的 identifier（`neg_<uuidv7>` 等）。 */
+export declare function generateId(kind: IdentifierKind): string;
+export declare const newNegotiationId: () => string;
+export declare const newExchangeId: () => string;
+export declare const newMessageId: () => string;
+export declare const newOfferId: () => string;
+export declare const newAgreementId: () => string;
+/** opaque identifier 校验：非空、无前后空白、无控制字符、长度受限。 */
+export declare function validateIdentifier(value: unknown, path: string): string;
+/** A2A `contextId`：对 Kiwi opaque（§6.6）。 */
+export declare function validateContextId(value: unknown, path: string): string;
+/** A2A `taskId`：transport/session 状态，不得替代 negotiation_id（§6.7）。 */
+export declare function validateTaskId(value: unknown, path: string): string;
+/**
+ * 扁平 target 引用：target_message_id 是通用引用；target_offer_id 仅用于
+ * Offer-like 目标。两者同时存在时 MUST 解析到同一 Ledger 对象，否则
+ * state_conflict。
+ */
+export interface TargetRef {
+    target_message_id: string;
+    target_offer_id?: string;
+}
+export declare function validateTargetRef(value: unknown, path: string): TargetRef;
+export interface TargetRefResolver {
+    /** 消息 id → 其承载的 offer_id；未知返回 null。 */
+    resolveMessageOffer(messageId: string): string | null;
+    /** offer id → 承载它的 message_id；未知返回 null。 */
+    resolveOfferMessage(offerId: string): string | null;
+}
+/**
+ * 用 Ledger 视图核对 TargetRef 的一致性。只有双方都能解析且发生矛盾时才抛
+ * state_conflict（§9.7）；单侧未知不属于这里可判定的矛盾，留给引擎按
+ * offer_unknown 等状态错误处理。
+ */
+export declare function checkTargetRefAgreement(target: TargetRef, resolver: TargetRefResolver): void;