@harrylabsj/kiwi 0.6.0

package/dist/handoff/delivery.d.ts

@@ -0,0 +1,59 @@
+/**
+ * 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 { LedgerCapabilitySnapshot, LedgerEvent, LedgerIdentitySnapshot } from "../negotiation/ledger/event.js";
+import type { HandoffCandidate } from "./candidate.js";
+import type { HandoffDeliveryEventKind, HandoffEventStore } from "./ledger.js";
+export declare const HANDOFF_DELIVERY_STATES: readonly ["DELIVERED", "LAUNCHED", "OPENED_CONFIRMED", "EXPIRED", "REVOKED"];
+export type HandoffDeliveryState = (typeof HANDOFF_DELIVERY_STATES)[number];
+/** 允许的 OPENED_CONFIRMED 证据种类（KTH rev0.3 §9）。 */
+export declare const OPEN_EVIDENCE_KINDS: readonly ["local_callback", "merchant_callback", "platform_callback", "verified_return_uri"];
+export type OpenEvidenceKind = (typeof OPEN_EVIDENCE_KINDS)[number];
+/** 可归属打开证据：必须绑定 handoff_id + 时间戳。 */
+export interface OpenEvidence {
+    readonly kind: OpenEvidenceKind;
+    readonly handoff_id: string;
+    readonly at: string;
+    readonly details?: Readonly<Record<string, unknown>>;
+}
+/** 从 Ledger 交付事件投影交付状态（纯函数，最后事件胜出）。 */
+export declare function deliveryState(events: readonly Pick<LedgerEvent, "event_kind" | "event_id">[]): HandoffDeliveryState | undefined;
+/** 迁移校验：非法转换抛 schemaError（fail-closed）。 */
+export declare function transitionDeliveryState(current: HandoffDeliveryState | undefined, eventKind: HandoffDeliveryEventKind): HandoffDeliveryState;
+export declare function isHandoffDeliveryEventKind(kind: string): kind is HandoffDeliveryEventKind;
+/** 校验打开证据（fail-closed）：kind 白名单 + handoff_id 绑定 + RFC 3339。 */
+export declare function validateOpenEvidence(value: unknown, path?: string): OpenEvidence;
+export interface DeliveryEventDeps {
+    ledger: HandoffEventStore;
+    candidate: HandoffCandidate;
+    handoff_id: string;
+    identity: LedgerIdentitySnapshot;
+    capability: LedgerCapabilitySnapshot;
+    now?: () => string;
+}
+/**
+ * 记录 LAUNCHED：只表示成功请求 OS/browser/deep-link handler 启动目的地，
+ * 不证明页面加载（§36-28）。
+ */
+export declare function recordLaunch(deps: DeliveryEventDeps): void;
+/**
+ * 记录 OPENED_CONFIRMED —— 证据门：只有通过 validateOpenEvidence 的
+ * 可归属证据才允许进入该状态；无证据的 launch 永不成为 OPENED_CONFIRMED。
+ */
+export declare function recordOpenEvidence(deps: DeliveryEventDeps & {
+    evidence: unknown;
+}): OpenEvidence;
+/** 记录 REVOKED（仅当目的地支持撤销；§9）。 */
+export declare function recordRevoked(deps: DeliveryEventDeps, reason?: string): void;

package/dist/handoff/delivery.js

@@ -0,0 +1,185 @@
+/**
+ * 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.
+ */
+/**
+ * KTH/0.1 交付观察状态（rev0.3 §9；架构 rev1.4.1 §36-27/28）。
+ *
+ * DELIVERED / LAUNCHED / OPENED_CONFIRMED / EXPIRED / REVOKED ——
+ * 这些状态只描述「交接动作」，**绝不**伪装成 ORDER_CREATED / PAID /
+ * FULFILLED（外部交易结果必须由外部 authority 明确回传）。
+ *
+ * 证据门：`LAUNCHED` 只表示成功请求 OS/browser/deep-link handler 启动
+ * 目的地，不证明页面加载；`OPENED_CONFIRMED` 必须由**可归属证据**触发
+ * （local_callback 绑定 handoff_id / merchant_callback / platform_callback /
+ * verified_return_uri）。无证据永不 OPENED_CONFIRMED（完成定义 #19、
+ * 完成标准 12）。明确拒绝：button click / openURL 成功 / 计时 / UA 猜测。
+ */
+import { requireIsoTimestamp, requireNonEmptyString, schemaError } from "../negotiation/domain/common.js";
+export const HANDOFF_DELIVERY_STATES = [
+    "DELIVERED",
+    "LAUNCHED",
+    "OPENED_CONFIRMED",
+    "EXPIRED",
+    "REVOKED",
+];
+/** 允许的 OPENED_CONFIRMED 证据种类（KTH rev0.3 §9）。 */
+export const OPEN_EVIDENCE_KINDS = [
+    "local_callback",
+    "merchant_callback",
+    "platform_callback",
+    "verified_return_uri",
+];
+// handoff_delivery_failed 不在此表：失败交付不产生观察状态，fold 时保留
+// 前态（此前映射为 DELIVERED 会把 LAUNCHED 倒退成 DELIVERED）。
+const DELIVERY_EVENT_TO_STATE = {
+    handoff_delivered: "DELIVERED",
+    handoff_launched: "LAUNCHED",
+    handoff_opened_confirmed: "OPENED_CONFIRMED",
+    handoff_expired: "EXPIRED",
+    handoff_revoked: "REVOKED",
+};
+/** 从 Ledger 交付事件投影交付状态（纯函数，最后事件胜出）。 */
+export function deliveryState(events) {
+    let state;
+    for (const event of events) {
+        if (!isHandoffDeliveryEventKind(event.event_kind))
+            continue;
+        const next = DELIVERY_EVENT_TO_STATE[event.event_kind];
+        if (next !== undefined)
+            state = next;
+    }
+    return state;
+}
+/**
+ * 显式迁移表（评审项：delivery 域补齐与 candidate lifecycle 对称的状态机）。
+ * `handoff_delivery_failed` 不映射状态（保留前态），不出现在表中。
+ *
+ *   (none)            --delivered--> DELIVERED        （交付事件必须是首个）
+ *   DELIVERED         --launched-->  LAUNCHED
+ *   DELIVERED/LAUNCHED --opened-->   OPENED_CONFIRMED
+ *   DELIVERED/LAUNCHED --expired-->  EXPIRED          （打开时限过期，终态）
+ *   DELIVERED/LAUNCHED --revoked-->  REVOKED          （终态）
+ *   OPENED_CONFIRMED/EXPIRED/REVOKED 无后继
+ *
+ * 由此拒绝：无 delivered 的 launch（审计污染）、REVOKED/EXPIRED 后的任何
+ * 事件（终态）、OPENED_CONFIRMED 后的倒退（expired/launch/再次确认）。
+ */
+const DELIVERY_TRANSITIONS = {
+    "": new Set(["DELIVERED"]),
+    DELIVERED: new Set(["LAUNCHED", "OPENED_CONFIRMED", "EXPIRED", "REVOKED"]),
+    LAUNCHED: new Set(["OPENED_CONFIRMED", "EXPIRED", "REVOKED"]),
+    OPENED_CONFIRMED: new Set(),
+    EXPIRED: new Set(),
+    REVOKED: new Set(),
+};
+/** 迁移校验：非法转换抛 schemaError（fail-closed）。 */
+export function transitionDeliveryState(current, eventKind) {
+    const target = DELIVERY_EVENT_TO_STATE[eventKind];
+    if (target === undefined) {
+        throw schemaError("handoff_delivery_state", `event kind ${eventKind} has no delivery state mapping`);
+    }
+    const allowed = DELIVERY_TRANSITIONS[current ?? ""] ?? new Set();
+    if (!allowed.has(target)) {
+        throw schemaError("handoff_delivery_state", `illegal handoff delivery transition ${current ?? "(none)"} --${eventKind}--> ${target}`);
+    }
+    return target;
+}
+export function isHandoffDeliveryEventKind(kind) {
+    return (kind === "handoff_delivered" ||
+        kind === "handoff_launched" ||
+        kind === "handoff_opened_confirmed" ||
+        kind === "handoff_expired" ||
+        kind === "handoff_revoked" ||
+        kind === "handoff_delivery_failed");
+}
+/** 校验打开证据（fail-closed）：kind 白名单 + handoff_id 绑定 + RFC 3339。 */
+export function validateOpenEvidence(value, path = "open_evidence") {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        throw schemaError(path, "open evidence must be an object");
+    }
+    const obj = value;
+    const kind = obj.kind;
+    if (!OPEN_EVIDENCE_KINDS.includes(String(kind))) {
+        throw schemaError(path, `unsupported open evidence kind "${String(kind)}" (allowed: ${OPEN_EVIDENCE_KINDS.join(", ")})`);
+    }
+    return {
+        kind: kind,
+        handoff_id: requireNonEmptyString(obj.handoff_id, `${path}/handoff_id`),
+        at: requireIsoTimestamp(obj.at, `${path}/at`),
+        ...(obj.details !== undefined ? { details: obj.details } : {}),
+    };
+}
+/**
+ * 记录 LAUNCHED：只表示成功请求 OS/browser/deep-link handler 启动目的地，
+ * 不证明页面加载（§36-28）。
+ */
+export function recordLaunch(deps) {
+    deps.ledger.appendDeliveryEvent({
+        kind: "handoff_launched",
+        candidate: deps.candidate,
+        handoff_id: deps.handoff_id,
+        identity: deps.identity,
+        capability: deps.capability,
+        occurred_at: deps.now?.() ?? new Date().toISOString(),
+    });
+}
+/**
+ * 记录 OPENED_CONFIRMED —— 证据门：只有通过 validateOpenEvidence 的
+ * 可归属证据才允许进入该状态；无证据的 launch 永不成为 OPENED_CONFIRMED。
+ */
+export function recordOpenEvidence(deps) {
+    const evidence = validateOpenEvidence(deps.evidence);
+    if (evidence.handoff_id !== deps.handoff_id) {
+        throw schemaError("open_evidence/handoff_id", `evidence handoff_id ${evidence.handoff_id} does not match ${deps.handoff_id}`);
+    }
+    // 前置状态门：只允许对已交付的 handoff 记录打开确认（交付观察层此前无
+    // 状态机——链上根本没有 delivered 事件也可直接落 opened_confirmed，审计可被污染）。
+    const delivered = deps.ledger
+        .events(deps.candidate.negotiation_id)
+        .find((e) => e.event_kind === "handoff_delivered" && e.handoff_id === deps.handoff_id);
+    if (delivered === undefined) {
+        throw schemaError("handoff_id", `cannot confirm opened for handoff ${deps.handoff_id}: no delivered event on chain`);
+    }
+    deps.ledger.appendDeliveryEvent({
+        kind: "handoff_opened_confirmed",
+        candidate: deps.candidate,
+        handoff_id: deps.handoff_id,
+        identity: deps.identity,
+        capability: deps.capability,
+        evidence: { ...evidence },
+        occurred_at: deps.now?.() ?? new Date().toISOString(),
+    });
+    return evidence;
+}
+/** 记录 REVOKED（仅当目的地支持撤销；§9）。 */
+export function recordRevoked(deps, reason = "operator revocation") {
+    // 前置状态门：只允许对已交付的 handoff 撤销（同 recordOpenEvidence）。
+    const delivered = deps.ledger
+        .events(deps.candidate.negotiation_id)
+        .find((e) => e.event_kind === "handoff_delivered" && e.handoff_id === deps.handoff_id);
+    if (delivered === undefined) {
+        throw schemaError("handoff_id", `cannot revoke handoff ${deps.handoff_id}: no delivered event on chain`);
+    }
+    deps.ledger.appendDeliveryEvent({
+        kind: "handoff_revoked",
+        candidate: deps.candidate,
+        handoff_id: deps.handoff_id,
+        identity: deps.identity,
+        capability: deps.capability,
+        evidence: { reason },
+        occurred_at: deps.now?.() ?? new Date().toISOString(),
+    });
+}
+//# sourceMappingURL=delivery.js.map

package/dist/handoff/delivery.js.map

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

package/dist/handoff/destination.d.ts

@@ -0,0 +1,39 @@
+/**
+ * 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.
+ */
+/** KTH/0.1 目的地类型（rev0.3 §7；顺序即文档枚举顺序）。 */
+export declare const DESTINATION_TYPES: readonly ["ucp_checkout", "ucp_order", "external_checkout_url", "merchant_checkout_session", "platform_deep_link", "buyer_erp_request", "procurement_request", "purchase_order_draft", "quote_document", "merchant_contact", "sales_handoff"];
+export type DestinationType = (typeof DESTINATION_TYPES)[number];
+/**
+ * 归一化后的目的地（不可变）。`payload` 必须是最小化、schema-validated、
+ * 非秘密数据（KTH rev0.3 §5/§11.3）。
+ */
+export interface Destination {
+    readonly type: DestinationType;
+    /** 目的地引用：URL 类为 http(s) URL，会话/文档类为 opaque ref。 */
+    readonly ref: string;
+    /** 最小化目的地载荷（可选）。 */
+    readonly payload?: Readonly<Record<string, unknown>>;
+}
+/** URL 承载类目的地（external checkout / deep link）——URL 安全策略适用。 */
+export declare function isUrlDestinationType(type: DestinationType): boolean;
+/** 校验是否为目标类型已知值。 */
+export declare function isDestinationType(value: unknown): value is DestinationType;
+/**
+ * 结构校验一个目的地。URL 类要求 http(s)；其余要求非空 opaque ref。
+ * 安全策略（scheme 白名单 / redirect / phishing）在 url-safety.ts 执行。
+ * 校验失败抛 schemaError（fail-closed）。
+ */
+export declare function validateDestination(input: unknown, path?: string): Destination;

package/dist/handoff/destination.js

@@ -0,0 +1,99 @@
+/**
+ * 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.
+ */
+/**
+ * KTH/0.1 —— destination_type 词表（单一来源，KTH rev0.3 §7）。
+ *
+ * ⚠️ 禁止平行词表：kiwi-catalog 搜索词表、shopping-cli Handoff 元数据、Agent
+ * 公开发现元数据一律从本模块 import（架构 rev1.4.1 §35A 一致性原则：
+ * "destination vocabulary = KTH destination_type vocabulary"）。任何地方不得
+ * 再发明 supports_* 之类的第二套命名。
+ *
+ * URL 类目的地的安全策略（HTTPS / redirect / anti-phishing）在 url-safety.ts
+ * （WP-C2）实施；本模块只做结构校验（类型 + ref 形状 + payload 最小化约束）。
+ */
+import { requireNonEmptyString, requireObject, schemaError } from "../negotiation/domain/common.js";
+/** KTH/0.1 目的地类型（rev0.3 §7；顺序即文档枚举顺序）。 */
+export const DESTINATION_TYPES = [
+    "ucp_checkout",
+    "ucp_order",
+    "external_checkout_url",
+    "merchant_checkout_session",
+    "platform_deep_link",
+    "buyer_erp_request",
+    "procurement_request",
+    "purchase_order_draft",
+    "quote_document",
+    "merchant_contact",
+    "sales_handoff",
+];
+/** URL 承载类目的地：ref 必须是 http(s) URL（scheme 白名单在 url-safety.ts）。 */
+const URL_DESTINATION_TYPES = new Set([
+    "external_checkout_url",
+    "platform_deep_link",
+]);
+/** 会话/引用类目的地：ref 是 opaque 会话或引用 id。 */
+const SESSION_DESTINATION_TYPES = new Set([
+    "ucp_checkout",
+    "ucp_order",
+    "merchant_checkout_session",
+]);
+/** 文档/联系人类目的地：ref 是 opaque 引用（PO/quote 草稿、联系方式）。 */
+const DOCUMENT_DESTINATION_TYPES = new Set([
+    "buyer_erp_request",
+    "procurement_request",
+    "purchase_order_draft",
+    "quote_document",
+    "merchant_contact",
+    "sales_handoff",
+]);
+/** URL 承载类目的地（external checkout / deep link）——URL 安全策略适用。 */
+export function isUrlDestinationType(type) {
+    return URL_DESTINATION_TYPES.has(type);
+}
+/** 校验是否为目标类型已知值。 */
+export function isDestinationType(value) {
+    return typeof value === "string" && DESTINATION_TYPES.includes(value);
+}
+/**
+ * 结构校验一个目的地。URL 类要求 http(s)；其余要求非空 opaque ref。
+ * 安全策略（scheme 白名单 / redirect / phishing）在 url-safety.ts 执行。
+ * 校验失败抛 schemaError（fail-closed）。
+ */
+export function validateDestination(input, path = "destination") {
+    const obj = requireObject(input, path);
+    const typeRaw = obj.type;
+    if (!isDestinationType(typeRaw)) {
+        throw schemaError(`${path}/type`, `unknown destination type (must be one of: ${DESTINATION_TYPES.join(", ")})`);
+    }
+    const type = typeRaw;
+    const ref = requireNonEmptyString(obj.ref, `${path}/ref`);
+    if (URL_DESTINATION_TYPES.has(type) && !/^https?:\/\/\S+$/.test(ref)) {
+        throw schemaError(`${path}/ref`, `destination type "${type}" requires an http(s) URL ref`);
+    }
+    if (SESSION_DESTINATION_TYPES.has(type) || DOCUMENT_DESTINATION_TYPES.has(type)) {
+        if (/^https?:\/\//.test(ref) && !URL_DESTINATION_TYPES.has(type)) {
+            // 会话/文档类目的地不禁止 URL（如 buyer_erp_request 的 ERP 端点引用），
+            // 但不会被当作可点击链接处理——ref 语义由 destination type 决定。
+        }
+    }
+    let payload;
+    if (obj.payload !== undefined) {
+        const payloadObj = requireObject(obj.payload, `${path}/payload`);
+        payload = Object.freeze({ ...payloadObj });
+    }
+    return Object.freeze({ type, ref, ...(payload !== undefined ? { payload } : {}) });
+}
+//# sourceMappingURL=destination.js.map

package/dist/handoff/destination.js.map

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

package/dist/handoff/errors.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 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.
+ */
+/**
+ * Kiwi v0.7.0 Transaction Handoff（WP1）错误模型。
+ *
+ * 交接域内两类失败语义分得很开：
+ * - 结构化结果（HandoffChannel / AuthorizationProvider 返回 `{ok}` /
+ *   `{fail_closed}` / `{requires_user}`）表达「运行时拒绝」，调用方按结果分支；
+ * - `HandoffError` 表达「构造/校验失败」，只在工件构造与授权对象构造这类纯函数
+ *   里抛出 —— 构造失败即 fail-closed：坏工件绝不会被创建出来。
+ *
+ * 代码与协议错误词表（§18）保持对齐，`terms_digest_mismatch` 直接复用 KNP 词表。
+ */
+export declare const HANDOFF_ERROR_CODES: readonly ["terms_digest_mismatch", "invalid_agreement", "invalid_authorization", "invalid_session", "invalid_input", "concurrency_lock_timeout"];
+export type HandoffErrorCode = (typeof HANDOFF_ERROR_CODES)[number];
+/** Handoff 工件/授权对象构造失败。`path` 为字段路径（JSON Pointer 风格）。 */
+export declare class HandoffError extends Error {
+    readonly code: HandoffErrorCode;
+    readonly path?: string;
+    constructor(code: HandoffErrorCode, message: string, path?: string);
+}

package/dist/handoff/errors.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.
+ */
+/**
+ * Kiwi v0.7.0 Transaction Handoff（WP1）错误模型。
+ *
+ * 交接域内两类失败语义分得很开：
+ * - 结构化结果（HandoffChannel / AuthorizationProvider 返回 `{ok}` /
+ *   `{fail_closed}` / `{requires_user}`）表达「运行时拒绝」，调用方按结果分支；
+ * - `HandoffError` 表达「构造/校验失败」，只在工件构造与授权对象构造这类纯函数
+ *   里抛出 —— 构造失败即 fail-closed：坏工件绝不会被创建出来。
+ *
+ * 代码与协议错误词表（§18）保持对齐，`terms_digest_mismatch` 直接复用 KNP 词表。
+ */
+export const HANDOFF_ERROR_CODES = [
+    "terms_digest_mismatch",
+    "invalid_agreement",
+    "invalid_authorization",
+    "invalid_session",
+    "invalid_input",
+    "concurrency_lock_timeout",
+];
+/** Handoff 工件/授权对象构造失败。`path` 为字段路径（JSON Pointer 风格）。 */
+export class HandoffError extends Error {
+    code;
+    path;
+    constructor(code, message, path) {
+        super(message);
+        this.name = "HandoffError";
+        this.code = code;
+        if (path !== undefined)
+            this.path = path;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/handoff/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/handoff/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH;;;;;;;;;;GAUG;AAEH,MAAM,CAAC,MAAM,mBAAmB,GAAG;IACjC,uBAAuB;IACvB,mBAAmB;IACnB,uBAAuB;IACvB,iBAAiB;IACjB,eAAe;IACf,0BAA0B;CAClB,CAAC;AAGX,yDAAyD;AACzD,MAAM,OAAO,YAAa,SAAQ,KAAK;IAC5B,IAAI,CAAmB;IACvB,IAAI,CAAU;IACvB,YAAY,IAAsB,EAAE,OAAe,EAAE,IAAa;QAChE,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;QAC3B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,IAAI,KAAK,SAAS;YAAE,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IAC3C,CAAC;CACF"}

package/dist/handoff/idempotency.d.ts

@@ -0,0 +1,51 @@
+/**
+ * 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 HandoffIdempotencyStoreOptions {
+    dir: string;
+    /** 保留期（缺省 7 天）。 */
+    retentionDays?: number;
+    now?: () => string;
+    /**
+     * 候选执行锁等待上限（ms，缺省 120_000）。executeHandoff 内可能含 URL
+     * 探测（最长 15s 超时 × 重定向链），等待上限要容纳完整执行。
+     */
+    lockTimeoutMs?: number;
+}
+export declare class HandoffIdempotencyStore {
+    private readonly dir;
+    private readonly filePath;
+    private readonly retentionMs;
+    private readonly now;
+    private readonly lockTimeoutMs;
+    constructor(options: HandoffIdempotencyStoreOptions);
+    /**
+     * 以候选为粒度的互斥（§10.1 幂等的并发保护）：executeHandoff 的
+     * lookup→(多次 await)→record 是 check-then-act，两个并发执行会双双通过
+     * 幂等检查、同一候选交付两次。锁文件用 `openSync("wx")` 原子创建——
+     * 单进程内 async 交错与跨进程共享 dir 两个场景都互斥；持锁期间崩溃由
+     * 等待方超时（fail-closed：抛 HandoffError，绝不并发执行）。
+     */
+    withCandidateLock<T>(candidateId: string, fn: () => Promise<T>): Promise<T>;
+    /** 幂等查询：同候选同 digest 已交付 → 返回 handoff_id。 */
+    lookup(candidateId: string, candidateDigest: string): {
+        handoff_id: string;
+    } | undefined;
+    /** 记录一次成功交付（幂等键 → handoff_id）。 */
+    record(candidateId: string, candidateDigest: string, handoffId: string): void;
+    /** 惰性清理：删除超过保留期的行（重写文件，原子 rename）。 */
+    prune(): number;
+    private rows;
+}