@harrylabsj/kiwi 0.6.0

package/dist/protocol/legacy-shopping-negotiation/mapping.d.ts

@@ -0,0 +1,78 @@
+/**
+ * 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 { TermSet } from "../../negotiation/domain/common.js";
+import type { NegotiationAction } from "../../negotiation/domain/objects.js";
+import type { DecisionAction, Proposal, StockState } from "../../negotiation/types.js";
+import type { TranslationNote } from "./types.js";
+/** legacy action → KNP action。`requires_human` = legacy 无 KNP 等价物（§35 unsupported → human）。 */
+export declare const LEGACY_TO_KNP_ACTION: Record<DecisionAction, NegotiationAction | "requires_human">;
+/** KNP action → legacy action。`fail_closed` = 受保护语义无法表达；`requires_human` = unsupported。 */
+export declare const KNP_TO_LEGACY_ACTION: Record<NegotiationAction, DecisionAction | "fail_closed" | "requires_human">;
+/** legacy 消息 id（int）→ KNP message_id（可逆）。 */
+export declare function legacyMessageIdToKnp(messageId: number): string;
+/** KNP message_id → legacy 消息 id（int）；非 `msg_legacy_<int>` 形态返回 null。 */
+export declare function knpMessageIdToLegacy(messageId: string): number | null;
+/** legacy 消息承载的 offer → KNP offer_id（可逆，消息路径）。 */
+export declare function offerIdOfLegacyMessage(messageId: number): string;
+/** KNP offer_id → legacy 消息 id；非 `off_legacy_<int>` 形态返回 null。 */
+export declare function legacyOfferIdFromKnp(offerId: string): number | null;
+/** 内容寻址 id：同一 legacy 决策/terms 产生同一 KNP id（重试幂等，§6.3/§6.4）。 */
+export declare function deterministicId(prefix: "ex" | "msg" | "off", seed: string): string;
+/**
+ * decision 路径的内容种子：不依赖未来才分配的消息 id。
+ * 包含完整商业内容（含 public_message），因此 §6.3 的「不同内容不得复用同一
+ * message_id」成立；同一决策重试产生同一 message_id（§6.3/§20 idempotency）。
+ * 注：created_at 不参与种子 —— 若调用方用适配器时钟缺省填充，重试必须复用
+ * 同一 ctx.created_at，否则 digest 变化会触发 idempotency_conflict。
+ */
+export declare function decisionContentSeed(conversationId: string, action: NegotiationAction, inReplyToMessageId: number, terms: TermSet | undefined, publicMessage: string): string;
+export type MoneyLike = {
+    currency: string;
+    amount_minor: number;
+};
+/** legacy stock 块形状校验：防外来 KNP 注入伪造库存事实。 */
+export declare function isLegacyStockState(value: unknown): value is StockState;
+export interface TermConversion<T> {
+    ok: true;
+    value: T;
+    notes: TranslationNote[];
+}
+export interface TermConversionError {
+    ok: false;
+    reason: string;
+}
+export type TermConversionResult<T> = TermConversion<T> | TermConversionError;
+/**
+ * legacy Proposal → KNP TermSet（§7.4）。
+ *
+ * 无损路径：sku/quantity/unit_price/currency → items[0]；
+ * valid_until → terms.valid_until（expiry 语义保真）。
+ * legacy-extension（记录 note，不属于 KNP/1.0 定义字段）：
+ *   stock → fulfillment_terms.legacy_stock
+ *   delivery.eta_start/eta_end/fee → fulfillment_terms.eta_start/eta_end/delivery_fee
+ *   after_sales_policy_refs → service_terms.after_sales_policy_refs
+ * 默认填充（记录 note）：quantity.unit 缺省 "piece"。
+ * 有损拒绝：金额小数位超出最小单位（§7.1 float 金额禁止）。
+ */
+export declare function proposalToTerms(proposal: Proposal, currencyExponentOf: (currency: string) => number): TermConversionResult<TermSet>;
+/**
+ * KNP TermSet → legacy Proposal（decision.schema.json #/$defs/proposal）。
+ *
+ * legacy proposal 是单 SKU、强制 stock/delivery/valid_until；KNP 缺这些
+ * 语义时 fail-closed（expiry 受保护：KNP 无 valid_until 时不得发明一个；
+ * 缺 stock / delivery 同理不得发明库存/履约事实）。
+ */
+export declare function termsToProposal(terms: TermSet, currencyExponentOf: (currency: string) => number): TermConversionResult<Proposal>;

package/dist/protocol/legacy-shopping-negotiation/mapping.js

@@ -0,0 +1,321 @@
+/**
+ * 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.
+ */
+/**
+ * LegacyNegotiationAdapter 双向字段映射（基线 §35 / 子规范 §32）。
+ *
+ * 核心约定：
+ *
+ * 1. conversation_id ↔ negotiation_id —— 直接映射（双方都是 opaque string）。
+ * 2. legacy message id（int）↔ KNP message_id（string）：
+ *      `msg_legacy_<int>` 可逆编码。KNP 侧出现非该形态的 message_id /
+ *      in_reply_to / target_message_id 时，KNP→legacy 无法恢复 int 语义 →
+ *      fail-closed（identity 语义，§35 不得静默丢弃）。
+ * 3. legacy 消息承载的 offer ↔ KNP offer_id：
+ *      legacy 消息路径（已分配消息 id）：`off_legacy_<message_id>`；
+ *      legacy decision 路径（尚未分配消息 id）：内容寻址 `off_<sha256>`，
+ *      同一决策重试生成同一 offer_id（幂等，§6.4）。
+ * 4. 受保护语义（conditions / expiry / identity / agreement）在 KNP→legacy
+ *      方向无法表达即 fail-closed / requires-human，绝不静默丢弃字段。
+ *
+ * legacy-only 字段（stock / delivery eta / fee / after_sales refs / open_issues）
+ * 在 legacy→KNP 方向用 KNP 允许的 terms 域内 legacy-extension 字段保真，
+ * 并记录 extension note —— 既不丢失，也明确标注不是 KNP/1.0 定义的字段。
+ */
+import { canonicalize, sha256Hex } from "../../negotiation/jcs.js";
+import { requireIsoTimestamp } from "../../negotiation/domain/common.js";
+import { fromMinorUnits, toMinorUnits } from "./money.js";
+// ---------------------------------------------------------------------------
+// Action 映射
+// ---------------------------------------------------------------------------
+/** legacy action → KNP action。`requires_human` = legacy 无 KNP 等价物（§35 unsupported → human）。 */
+export const LEGACY_TO_KNP_ACTION = {
+    ask: "inquiry",
+    propose: "offer",
+    counter: "counter_offer",
+    accept_nonbinding: "accept_nonbinding",
+    decline: "decline",
+    escalate: "requires_human",
+};
+/** KNP action → legacy action。`fail_closed` = 受保护语义无法表达；`requires_human` = unsupported。 */
+export const KNP_TO_LEGACY_ACTION = {
+    inquiry: "ask",
+    rfq: "requires_human", // legacy 无 RFQ；结构化 items 无法塞进 legacy ask
+    offer: "propose",
+    counter_offer: "counter",
+    conditional_offer: "fail_closed", // conditions 受保护（§35）：legacy 无法表达
+    clarification: "ask",
+    clarification_response: "requires_human", // legacy 无结构化澄清应答
+    accept_nonbinding: "accept_nonbinding",
+    withdraw: "requires_human", // legacy 无 withdraw
+    decline: "decline",
+    cancel: "requires_human", // legacy 无 cancel
+};
+// ---------------------------------------------------------------------------
+// Identifier 编码（§35 identity / §6）
+// ---------------------------------------------------------------------------
+const LEGACY_MSG_ID_PATTERN = /^msg_legacy_(\d{1,10})$/;
+const LEGACY_OFFER_ID_PATTERN = /^off_legacy_(\d{1,10})$/;
+/** legacy 消息 id（int）→ KNP message_id（可逆）。 */
+export function legacyMessageIdToKnp(messageId) {
+    return `msg_legacy_${messageId}`;
+}
+/** KNP message_id → legacy 消息 id（int）；非 `msg_legacy_<int>` 形态返回 null。 */
+export function knpMessageIdToLegacy(messageId) {
+    const match = LEGACY_MSG_ID_PATTERN.exec(messageId);
+    return match === null ? null : Number(match[1]);
+}
+/** legacy 消息承载的 offer → KNP offer_id（可逆，消息路径）。 */
+export function offerIdOfLegacyMessage(messageId) {
+    return `off_legacy_${messageId}`;
+}
+/** KNP offer_id → legacy 消息 id；非 `off_legacy_<int>` 形态返回 null。 */
+export function legacyOfferIdFromKnp(offerId) {
+    const match = LEGACY_OFFER_ID_PATTERN.exec(offerId);
+    return match === null ? null : Number(match[1]);
+}
+/** 内容寻址 id：同一 legacy 决策/terms 产生同一 KNP id（重试幂等，§6.3/§6.4）。 */
+export function deterministicId(prefix, seed) {
+    return `${prefix}_${sha256Hex(seed).slice(0, 16)}`;
+}
+/**
+ * decision 路径的内容种子：不依赖未来才分配的消息 id。
+ * 包含完整商业内容（含 public_message），因此 §6.3 的「不同内容不得复用同一
+ * message_id」成立；同一决策重试产生同一 message_id（§6.3/§20 idempotency）。
+ * 注：created_at 不参与种子 —— 若调用方用适配器时钟缺省填充，重试必须复用
+ * 同一 ctx.created_at，否则 digest 变化会触发 idempotency_conflict。
+ */
+export function decisionContentSeed(conversationId, action, inReplyToMessageId, terms, publicMessage) {
+    return canonicalize({
+        conversation_id: conversationId,
+        action,
+        in_reply_to_message_id: inReplyToMessageId,
+        terms,
+        public_message: publicMessage,
+    });
+}
+const STOCK_STATUSES = ["available", "low", "out_of_stock", "unknown"];
+/** legacy stock 块形状校验：防外来 KNP 注入伪造库存事实。 */
+export function isLegacyStockState(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const s = value;
+    return (typeof s.status === "string" &&
+        STOCK_STATUSES.includes(s.status) &&
+        typeof s.quantity === "number" &&
+        Number.isInteger(s.quantity) &&
+        s.quantity >= 0 &&
+        typeof s.observed_at === "string" &&
+        s.reserved === false);
+}
+function isRfc3339(value) {
+    if (typeof value !== "string")
+        return false;
+    try {
+        requireIsoTimestamp(value, "/");
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function isMoneyLike(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const m = value;
+    return (typeof m.currency === "string" &&
+        typeof m.amount_minor === "number" &&
+        Number.isInteger(m.amount_minor) &&
+        m.amount_minor >= 0);
+}
+/**
+ * legacy Proposal → KNP TermSet（§7.4）。
+ *
+ * 无损路径：sku/quantity/unit_price/currency → items[0]；
+ * valid_until → terms.valid_until（expiry 语义保真）。
+ * legacy-extension（记录 note，不属于 KNP/1.0 定义字段）：
+ *   stock → fulfillment_terms.legacy_stock
+ *   delivery.eta_start/eta_end/fee → fulfillment_terms.eta_start/eta_end/delivery_fee
+ *   after_sales_policy_refs → service_terms.after_sales_policy_refs
+ * 默认填充（记录 note）：quantity.unit 缺省 "piece"。
+ * 有损拒绝：金额小数位超出最小单位（§7.1 float 金额禁止）。
+ */
+export function proposalToTerms(proposal, currencyExponentOf) {
+    // 形状守卫（评审项：snapshot schema 的 proposal 只声明 {"type":["object",
+    // "null"]} 未 $ref $defs——网关可回传 {sku:"x"} 之类残缺对象，此前
+    // proposal.delivery.fee 直接取值抛 TypeError，channel 崩溃而非 fail-closed）。
+    if (proposal === null ||
+        typeof proposal !== "object" ||
+        typeof proposal.currency !== "string" ||
+        typeof proposal.unit_price !== "number" ||
+        proposal.delivery === null ||
+        typeof proposal.delivery !== "object" ||
+        typeof proposal.delivery?.fee !== "number") {
+        return {
+            ok: false,
+            reason: "proposal shape invalid: expected {currency, unit_price, delivery.fee} — got " +
+                JSON.stringify(proposal ?? null).slice(0, 200),
+        };
+    }
+    const notes = [];
+    const exponent = currencyExponentOf(proposal.currency);
+    const unitPrice = toMinorUnitsLossy(proposal.unit_price, exponent);
+    if (!unitPrice.ok) {
+        return {
+            ok: false,
+            reason: `unit_price ${proposal.unit_price} ${proposal.currency} is not representable in minor units (exponent ${exponent}): ${unitPrice.reason}`,
+        };
+    }
+    const fee = toMinorUnitsLossy(proposal.delivery.fee, exponent);
+    if (!fee.ok) {
+        return {
+            ok: false,
+            reason: `delivery.fee ${proposal.delivery.fee} ${proposal.currency} is not representable in minor units (exponent ${exponent}): ${fee.reason}`,
+        };
+    }
+    notes.push({
+        kind: "default",
+        path: "proposal.quantity.unit",
+        detail: 'legacy quantity is unit-less; defaulted to "piece"',
+    });
+    notes.push({
+        kind: "extension",
+        path: "proposal.stock",
+        detail: "stock preserved as terms.fulfillment_terms.legacy_stock (legacy-extension field, not defined by KNP/1.0)",
+    });
+    notes.push({
+        kind: "extension",
+        path: "proposal.delivery",
+        detail: "eta_start/eta_end/delivery_fee preserved as terms.fulfillment_terms legacy-extension fields",
+    });
+    notes.push({
+        kind: "extension",
+        path: "proposal.after_sales_policy_refs",
+        detail: "after_sales_policy_refs preserved as terms.service_terms.after_sales_policy_refs (legacy-extension field)",
+    });
+    const terms = {
+        items: [
+            {
+                sku: proposal.sku,
+                quantity: { value: proposal.quantity, unit: "piece" },
+                unit_price: { currency: proposal.currency, amount_minor: unitPrice.amount_minor },
+            },
+        ],
+        fulfillment_terms: {
+            eta_start: proposal.delivery.eta_start,
+            eta_end: proposal.delivery.eta_end,
+            delivery_fee: { currency: proposal.currency, amount_minor: fee.amount_minor },
+            legacy_stock: proposal.stock,
+        },
+        service_terms: { after_sales_policy_refs: proposal.after_sales_policy_refs },
+        valid_until: proposal.valid_until,
+    };
+    return { ok: true, value: terms, notes };
+}
+/**
+ * KNP TermSet → legacy Proposal（decision.schema.json #/$defs/proposal）。
+ *
+ * legacy proposal 是单 SKU、强制 stock/delivery/valid_until；KNP 缺这些
+ * 语义时 fail-closed（expiry 受保护：KNP 无 valid_until 时不得发明一个；
+ * 缺 stock / delivery 同理不得发明库存/履约事实）。
+ */
+export function termsToProposal(terms, currencyExponentOf) {
+    const notes = [];
+    const items = terms.items ?? [];
+    if (items.length !== 1) {
+        return {
+            ok: false,
+            reason: `legacy proposal is single-SKU; KNP terms carry ${items.length} item(s)`,
+        };
+    }
+    const item = items[0];
+    if (item.unit_price === undefined) {
+        return { ok: false, reason: "legacy proposal requires a unit price; KNP item carries none" };
+    }
+    const exponent = currencyExponentOf(item.unit_price.currency);
+    if (item.quantity.unit !== "piece") {
+        notes.push({
+            kind: "dropped",
+            path: "terms.items[0].quantity.unit",
+            detail: `unit "${item.quantity.unit}" dropped; legacy quantity is unit-less`,
+        });
+    }
+    const fulfillment = terms.fulfillment_terms ?? {};
+    const etaStart = fulfillment.eta_start;
+    const etaEnd = fulfillment.eta_end;
+    if (!isRfc3339(etaStart) || !isRfc3339(etaEnd)) {
+        return {
+            ok: false,
+            reason: "legacy proposal requires delivery eta_start/eta_end (RFC 3339); KNP terms carry none",
+        };
+    }
+    const fee = fulfillment.delivery_fee;
+    if (!isMoneyLike(fee)) {
+        return { ok: false, reason: "legacy proposal requires delivery.fee; KNP terms carry no delivery fee" };
+    }
+    if (fee.currency !== item.unit_price.currency) {
+        return {
+            ok: false,
+            reason: `delivery_fee currency ${fee.currency} differs from item currency ${item.unit_price.currency}; legacy proposal is single-currency`,
+        };
+    }
+    const stock = fulfillment.legacy_stock;
+    if (!isLegacyStockState(stock)) {
+        return {
+            ok: false,
+            reason: "legacy proposal requires stock state; KNP terms carry no valid inventory observation",
+        };
+    }
+    const afterSalesRefs = terms.service_terms?.after_sales_policy_refs;
+    const afterSales = Array.isArray(afterSalesRefs) ? afterSalesRefs : [];
+    if (!Array.isArray(afterSalesRefs)) {
+        notes.push({
+            kind: "default",
+            path: "proposal.after_sales_policy_refs",
+            detail: "KNP terms carry no after-sales refs; defaulted to []",
+        });
+    }
+    if (terms.valid_until === undefined) {
+        return {
+            ok: false,
+            reason: "legacy proposal requires valid_until; KNP offer has no expiry and the adapter must not invent one",
+        };
+    }
+    const proposal = {
+        sku: item.sku,
+        quantity: item.quantity.value,
+        unit_price: fromMinorUnitsLossy(item.unit_price.amount_minor, exponent),
+        currency: item.unit_price.currency,
+        stock,
+        delivery: { eta_start: etaStart, eta_end: etaEnd, fee: fromMinorUnitsLossy(fee.amount_minor, exponent) },
+        after_sales_policy_refs: afterSales,
+        valid_until: terms.valid_until,
+    };
+    return { ok: true, value: proposal, notes };
+}
+function toMinorUnitsLossy(amount, exponent) {
+    const conv = toMinorUnits(amount, exponent);
+    if (!conv.lossless) {
+        return {
+            ok: false,
+            reason: `amount ${amount} exceeds minor-unit precision (10^${exponent})`,
+        };
+    }
+    return { ok: true, amount_minor: conv.amount_minor };
+}
+function fromMinorUnitsLossy(amountMinor, exponent) {
+    return fromMinorUnits(amountMinor, exponent);
+}
+//# sourceMappingURL=mapping.js.map

package/dist/protocol/legacy-shopping-negotiation/mapping.js.map

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

package/dist/protocol/legacy-shopping-negotiation/money.d.ts

@@ -0,0 +1,49 @@
+/**
+ * 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.
+ */
+/**
+ * Money 小数位数与 legacy float ↔ KNP minor-units 转换（子规范 §7.1）。
+ *
+ * KNP/1.0 禁止 float 金额（§7.1 / §19.1 JCS）；shopping.negotiation/0.1 的
+ * proposal.unit_price / delivery.fee 是十进制 float。转译仅在 legacy 金额的
+ * 精度不超过目标货币最小单位时无损；否则 fail-closed（legacy→KNP 方向由
+ * 调用方根据 lossless=false 拒绝，绝不把小数位损失静默抹平）。
+ *
+ * 货币指数表只覆盖常见结算货币；未知货币默认指数 2（三位大写货币代码的
+ * 常见小数位）。需要扩展时通过 LegacyNegotiationAdapter 注入
+ * currencyExponentOf。
+ */
+/** 常见货币的最小单位指数（10^exp 个 minor = 1 个主要单位）。 */
+export declare const CURRENCY_EXPONENTS: Readonly<Record<string, number>>;
+export declare const DEFAULT_CURRENCY_EXPONENT = 2;
+/**
+ * 绝对 epsilon：`amount * 10^exp` 的 float 表示误差约 1e-9 量级；1e-6 远大于
+ * 该误差、又远小于 1 个最小单位，因此可区分「float 表示误差」与「真正超出
+ * 最小单位的小数位损失」。
+ */
+export declare const MINOR_UNIT_EPSILON = 0.000001;
+export declare function currencyExponent(currency: string): number;
+export interface MinorUnitConversion {
+    amount_minor: number;
+    /** true 表示精确可表达；false 表示 float 精度超出最小单位，转译有损。 */
+    lossless: boolean;
+}
+/**
+ * legacy 十进制金额 → KNP minor units（§7.1）。`lossless=false` 时
+ * `amount_minor` 为 NaN，调用方必须 fail-closed，不得使用该值。
+ */
+export declare function toMinorUnits(amount: number, exponent: number): MinorUnitConversion;
+/** KNP minor units → legacy 十进制金额（仅用于 KNP→legacy，无损）。 */
+export declare function fromMinorUnits(amount_minor: number, exponent: number): number;

package/dist/protocol/legacy-shopping-negotiation/money.js

@@ -0,0 +1,70 @@
+/**
+ * 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.
+ */
+/**
+ * Money 小数位数与 legacy float ↔ KNP minor-units 转换（子规范 §7.1）。
+ *
+ * KNP/1.0 禁止 float 金额（§7.1 / §19.1 JCS）；shopping.negotiation/0.1 的
+ * proposal.unit_price / delivery.fee 是十进制 float。转译仅在 legacy 金额的
+ * 精度不超过目标货币最小单位时无损；否则 fail-closed（legacy→KNP 方向由
+ * 调用方根据 lossless=false 拒绝，绝不把小数位损失静默抹平）。
+ *
+ * 货币指数表只覆盖常见结算货币；未知货币默认指数 2（三位大写货币代码的
+ * 常见小数位）。需要扩展时通过 LegacyNegotiationAdapter 注入
+ * currencyExponentOf。
+ */
+/** 常见货币的最小单位指数（10^exp 个 minor = 1 个主要单位）。 */
+export const CURRENCY_EXPONENTS = {
+    CNY: 2,
+    USD: 2,
+    EUR: 2,
+    GBP: 2,
+    JPY: 0,
+    KRW: 0,
+    HKD: 2,
+    TWD: 2,
+    SGD: 2,
+    AUD: 2,
+    CAD: 2,
+};
+export const DEFAULT_CURRENCY_EXPONENT = 2;
+/**
+ * 绝对 epsilon：`amount * 10^exp` 的 float 表示误差约 1e-9 量级；1e-6 远大于
+ * 该误差、又远小于 1 个最小单位，因此可区分「float 表示误差」与「真正超出
+ * 最小单位的小数位损失」。
+ */
+export const MINOR_UNIT_EPSILON = 1e-6;
+export function currencyExponent(currency) {
+    const exp = CURRENCY_EXPONENTS[currency];
+    return exp === undefined ? DEFAULT_CURRENCY_EXPONENT : exp;
+}
+/**
+ * legacy 十进制金额 → KNP minor units（§7.1）。`lossless=false` 时
+ * `amount_minor` 为 NaN，调用方必须 fail-closed，不得使用该值。
+ */
+export function toMinorUnits(amount, exponent) {
+    if (!Number.isFinite(amount) || amount < 0) {
+        return { amount_minor: Number.NaN, lossless: false };
+    }
+    const scaled = amount * 10 ** exponent;
+    const amountMinor = Math.round(scaled);
+    const lossless = Math.abs(scaled - amountMinor) <= MINOR_UNIT_EPSILON;
+    return { amount_minor: lossless ? amountMinor : Number.NaN, lossless };
+}
+/** KNP minor units → legacy 十进制金额（仅用于 KNP→legacy，无损）。 */
+export function fromMinorUnits(amount_minor, exponent) {
+    return amount_minor / 10 ** exponent;
+}
+//# sourceMappingURL=money.js.map

package/dist/protocol/legacy-shopping-negotiation/money.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"money.js","sourceRoot":"","sources":["../../../src/protocol/legacy-shopping-negotiation/money.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH;;;;;;;;;;;GAWG;AAEH,6CAA6C;AAC7C,MAAM,CAAC,MAAM,kBAAkB,GAAqC;IAClE,GAAG,EAAE,CAAC;IACN,GAAG,EAAE,CAAC;IACN,GAAG,EAAE,CAAC;IACN,GAAG,EAAE,CAAC;IACN,GAAG,EAAE,CAAC;IACN,GAAG,EAAE,CAAC;IACN,GAAG,EAAE,CAAC;IACN,GAAG,EAAE,CAAC;IACN,GAAG,EAAE,CAAC;IACN,GAAG,EAAE,CAAC;IACN,GAAG,EAAE,CAAC;CACP,CAAC;AAEF,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC,CAAC;AAE3C;;;;GAIG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,IAAI,CAAC;AAEvC,MAAM,UAAU,gBAAgB,CAAC,QAAgB;IAC/C,MAAM,GAAG,GAAG,kBAAkB,CAAC,QAAQ,CAAC,CAAC;IACzC,OAAO,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,yBAAyB,CAAC,CAAC,CAAC,GAAG,CAAC;AAC7D,CAAC;AAQD;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,MAAc,EAAE,QAAgB;IAC3D,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,MAAM,GAAG,CAAC,EAAE,CAAC;QAC3C,OAAO,EAAE,YAAY,EAAE,MAAM,CAAC,GAAG,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC;IACvD,CAAC;IACD,MAAM,MAAM,GAAG,MAAM,GAAG,EAAE,IAAI,QAAQ,CAAC;IACvC,MAAM,WAAW,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IACvC,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,GAAG,WAAW,CAAC,IAAI,kBAAkB,CAAC;IACtE,OAAO,EAAE,YAAY,EAAE,QAAQ,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,EAAE,QAAQ,EAAE,CAAC;AACzE,CAAC;AAED,yDAAyD;AACzD,MAAM,UAAU,cAAc,CAAC,YAAoB,EAAE,QAAgB;IACnE,OAAO,YAAY,GAAG,EAAE,IAAI,QAAQ,CAAC;AACvC,CAAC"}

package/dist/protocol/legacy-shopping-negotiation/types.d.ts

@@ -0,0 +1,107 @@
+/**
+ * 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.
+ */
+/**
+ * LegacyNegotiationAdapter — shopping.negotiation/0.1 ↔ KNP/1.0 转译结果类型
+ * （基线 §35 Legacy Migration / 子规范 §32 Legacy shopping-cli Mapping）。
+ *
+ * 每条转译路径都必须返回结构化结果，禁止静默降级：
+ *
+ *   { translated, notes }          — 成功。notes 逐条记录所有「补默认值 /
+ *                                     丢弃字段 / legacy-extension / identity」
+ *                                     决策，调用方可见、可审计、绝不静默。
+ *   { fail_closed: true, reason }  — 输入在目标协议中无法表达（受保护语义：
+ *                                     conditions / expiry / identity /
+ *                                    agreement），拒绝并说明原因。
+ *   { requires_human: true, reason } — 输入超出目标协议表达能力（如 legacy
+ *                                     escalate → 人工），转人工/fallback。
+ *
+ * 不变量 22（基线 §36）：Legacy Adapter 不得扩大权限 —— 本模块只做纯数据
+ * 转译，不执行任何 side effect，也不把 legacy 消息提升为 KNP 更高权限语义
+ * （如伪造 ConditionalOffer 条件、把 accept 变成订单/支付语义）。
+ */
+import type { TermSet } from "../../negotiation/domain/common.js";
+import type { NegotiationActor } from "../../negotiation/domain/objects.js";
+export type TranslationNote = {
+    kind: "mapped";
+    path: string;
+    detail: string;
+} | {
+    kind: "default";
+    path: string;
+    detail: string;
+} | {
+    kind: "dropped";
+    path: string;
+    detail: string;
+} | {
+    kind: "extension";
+    path: string;
+    detail: string;
+} | {
+    kind: "identity";
+    path: string;
+    detail: string;
+};
+export type TranslationResult<T> = {
+    translated: T;
+    notes: TranslationNote[];
+} | {
+    fail_closed: true;
+    reason: string;
+} | {
+    requires_human: true;
+    reason: string;
+};
+export declare function translated<T>(value: T, notes: TranslationNote[]): TranslationResult<T>;
+export declare function failClosed(reason: string): TranslationResult<never>;
+export declare function requiresHuman(reason: string): TranslationResult<never>;
+export declare function isTranslated<T>(r: TranslationResult<T>): r is {
+    translated: T;
+    notes: TranslationNote[];
+};
+/**
+ * legacy → KNP 方向所需的上下文。legacy decision/message 不携带 actor、
+ * capability、created_at；这些由调用方（运行时的传输/身份层）提供，缺省填
+ * 默认值并记录 note。offer 引用解析是 KNP accept/counter 的 terms_digest /
+ * responding_to_offer_id 的前置条件，无法解析即 fail-closed。
+ */
+export interface LegacyToKnpContext {
+    /** KNP 能力标识（子规范 §4.4）。 */
+    capability: string;
+    /** legacy 传输层绑定的 actor 身份（子规范 §8.1 / §33-1）。 */
+    actor: NegotiationActor;
+    /** envelope.created_at（RFC 3339）；缺省用适配器时钟，记录 note。 */
+    created_at?: string;
+    /** 当前产品 sku（legacy ask → KNP inquiry subject 用）。 */
+    current_sku?: string;
+    /** 解析 legacy accept 所接受的 offer terms，用于计算 §15 terms_digest。 */
+    resolveAcceptedTerms?: (conversationId: string, inReplyToMessageId: number) => TermSet | null;
+}
+/** legacy 消息转译上下文：消息本身不携带 negotiation_id / capability / in_reply_to。 */
+export interface LegacyMessageContext extends LegacyToKnpContext {
+    conversation_id: string;
+    /**
+     * 该消息回复的目标（KNP in_reply_to）；`msg_legacy_<int>` 形态。
+     * counter/decline/accept 消息的目标/被接受 offer 引用依赖它，缺失即 fail-closed。
+     */
+    in_reply_to?: string;
+}
+/**
+ * KNP → legacy 方向无需额外上下文：legacy decision 的网关派生字段
+ * （retries_remaining、actor 等）不属于转译范围 —— KNP 侧的 actor 语义通过
+ * note 显式交给传输层断言（identity，绝不静默丢），其余 KNP-only 字段逐条
+ * 记录为 dropped note。
+ */