@harrylabsj/kiwi 0.6.0

package/dist/handoff/idempotency.js

@@ -0,0 +1,168 @@
+/**
+ * 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.
+ */
+/**
+ * HandoffIdempotencyStore —— 执行域幂等（KTH rev0.3 §10.1）。
+ *
+ * 幂等键：(source_candidate_id, source_candidate_digest)。与 negotiation
+ * 的 `(sender_identity, message_id)` 协议域幂等**不混用**——handoff 重试
+ * 窗口比 24h 长（候选可能存活数天），保留期缺省 ≥ 7 天。
+ *
+ * 存储：JSONL（`<dir>/handoff-idempotency.jsonl`，目录 0700），追加式 +
+ * 惰性清理过期行。lookup 命中 → 返回已交付的 handoff_id（重试不重复交付）。
+ */
+import { chmodSync, closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync, writeSync, } from "node:fs";
+import path from "node:path";
+import { HandoffError } from "./errors.js";
+const DEFAULT_RETENTION_DAYS = 7;
+const DEFAULT_LOCK_TIMEOUT_MS = 120_000;
+const LOCK_POLL_MS = 25;
+/** 陈旧锁阈值：持锁超此即视为崩溃残留（executeHandoff 锁持有上限 = 锁超时
+ *  + URL 探测，10 分钟对正常操作是安全上限）。 */
+const LOCK_STALE_MS = 10 * 60 * 1000;
+export class HandoffIdempotencyStore {
+    dir;
+    filePath;
+    retentionMs;
+    now;
+    lockTimeoutMs;
+    constructor(options) {
+        mkdirSync(options.dir, { recursive: true, mode: 0o700 });
+        chmodSync(options.dir, 0o700);
+        this.dir = options.dir;
+        this.filePath = path.join(options.dir, "handoff-idempotency.jsonl");
+        this.retentionMs = (options.retentionDays ?? DEFAULT_RETENTION_DAYS) * 24 * 60 * 60 * 1000;
+        this.lockTimeoutMs = options.lockTimeoutMs ?? DEFAULT_LOCK_TIMEOUT_MS;
+        this.now = options.now ?? (() => new Date().toISOString());
+    }
+    /**
+     * 以候选为粒度的互斥（§10.1 幂等的并发保护）：executeHandoff 的
+     * lookup→(多次 await)→record 是 check-then-act，两个并发执行会双双通过
+     * 幂等检查、同一候选交付两次。锁文件用 `openSync("wx")` 原子创建——
+     * 单进程内 async 交错与跨进程共享 dir 两个场景都互斥；持锁期间崩溃由
+     * 等待方超时（fail-closed：抛 HandoffError，绝不并发执行）。
+     */
+    async withCandidateLock(candidateId, fn) {
+        const lockDir = path.join(this.dir, "locks");
+        mkdirSync(lockDir, { recursive: true, mode: 0o700 });
+        const safeId = candidateId.replace(/[^A-Za-z0-9_-]/g, "_");
+        const lockPath = path.join(lockDir, `${safeId}.lock`);
+        const deadline = Date.now() + this.lockTimeoutMs;
+        for (;;) {
+            try {
+                const fd = openSync(lockPath, "wx");
+                closeSync(fd);
+                break;
+            }
+            catch (err) {
+                if (err.code !== "EEXIST")
+                    throw err;
+                // 陈旧锁自愈（评审项 B2）：持锁进程崩溃（finally 未执行）→ 锁文件
+                // 永久残留，该候选永远 concurrency_lock_timeout（每次等满超时）。
+                // mtime 超 LOCK_STALE_MS 即视为残留删除重试。
+                try {
+                    const st = statSync(lockPath);
+                    if (Date.now() - st.mtimeMs > LOCK_STALE_MS) {
+                        unlinkSync(lockPath);
+                        continue;
+                    }
+                }
+                catch {
+                    // 锁文件刚被释放 → 重试
+                    continue;
+                }
+                if (Date.now() >= deadline) {
+                    throw new HandoffError("concurrency_lock_timeout", `handoff candidate ${candidateId} is locked by another executor (waited ${this.lockTimeoutMs}ms); refusing concurrent execution`);
+                }
+                await new Promise((resolve) => setTimeout(resolve, LOCK_POLL_MS));
+            }
+        }
+        try {
+            return await fn();
+        }
+        finally {
+            try {
+                unlinkSync(lockPath);
+            }
+            catch {
+                // 锁文件已不存在（异常清理）则忽略。
+            }
+        }
+    }
+    /** 幂等查询：同候选同 digest 已交付 → 返回 handoff_id。 */
+    lookup(candidateId, candidateDigest) {
+        for (const row of this.rows()) {
+            if (row.candidate_id === candidateId && row.candidate_digest === candidateDigest) {
+                return { handoff_id: row.handoff_id };
+            }
+        }
+        return undefined;
+    }
+    /** 记录一次成功交付（幂等键 → handoff_id）。 */
+    record(candidateId, candidateDigest, handoffId) {
+        const row = {
+            candidate_id: candidateId,
+            candidate_digest: candidateDigest,
+            handoff_id: handoffId,
+            recorded_at: this.now(),
+        };
+        // 追加 + fsync（评审项 B2）：此前纯追加无 fsync，崩溃时最后一行可能
+        // 撕裂——rows() 容忍撕裂行（跳过）→ 同候选再次执行会重复交付。fsync
+        // 后成功返回即持久，重试路径可依赖幂等表。
+        const fd = openSync(this.filePath, "a", 0o600);
+        try {
+            writeSync(fd, `${JSON.stringify(row)}\n`);
+            fsyncSync(fd);
+        }
+        finally {
+            closeSync(fd);
+        }
+    }
+    /** 惰性清理：删除超过保留期的行（重写文件，原子 rename）。 */
+    prune() {
+        const cutoff = Date.parse(this.now()) - this.retentionMs;
+        const rows = this.rows();
+        const fresh = rows.filter((row) => Date.parse(row.recorded_at) >= cutoff);
+        if (fresh.length === rows.length)
+            return 0;
+        const tmp = `${this.filePath}.tmp`;
+        writeFileSync(tmp, fresh.map((r) => JSON.stringify(r)).join("\n") + (fresh.length > 0 ? "\n" : ""), {
+            mode: 0o600,
+        });
+        renameSync(tmp, this.filePath);
+        return rows.length - fresh.length;
+    }
+    rows() {
+        if (!existsSync(this.filePath))
+            return [];
+        const raw = readFileSync(this.filePath, "utf-8");
+        const rows = [];
+        for (const line of raw.split("\n")) {
+            if (line.length === 0)
+                continue;
+            try {
+                const parsed = JSON.parse(line);
+                if (typeof parsed.candidate_id === "string" && typeof parsed.handoff_id === "string") {
+                    rows.push(parsed);
+                }
+            }
+            catch {
+                // 撕裂行跳过（审计由 Ledger 承担；幂等表容忍最后一行撕裂）。
+            }
+        }
+        return rows;
+    }
+}
+//# sourceMappingURL=idempotency.js.map

package/dist/handoff/idempotency.js.map

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

package/dist/handoff/index.d.ts

@@ -0,0 +1,46 @@
+/**
+ * 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）—— 域模型与授权接缝。
+ *
+ * 基线 §3.4 / §43：订单/支付发生在外部交易系统（UCP Checkout，business 是
+ * Merchant of Record）；Kiwi 只做「非绑定共识 → 交易系统」的安全交接。本包只
+ * 提供交接工件、交易系统适配接缝、AP2 授权接缝与完成门禁，不创建订单、不处理
+ * 原始支付凭据、不实现真实 UCP Checkout / AP2（分别属于 WP2 / 外部系统）。
+ *
+ * 两层关系（术语对齐决策，KTH rev0.3）：
+ *   外层 —— KTH 候选链：Agreement → HandoffCandidate（candidate.ts，
+ *   不可变 + event-sourced 生命周期 lifecycle.ts/ledger.ts）→ 交付观察
+ *   （delivery 状态，Phase 2）。
+ *   内层 —— UCP checkout session 适配：HandoffPackage/HandoffSession/
+ *   HandoffChannel（package.ts/channel.ts，v0.6.0 WP1 工件，不重命名保留）。
+ *   `ucp_checkout`/`ucp_order` 目的地走内层；URL/PO/quote/contact 目的地
+ *   走外层交付。
+ */
+export { HandoffError, HANDOFF_ERROR_CODES, type HandoffErrorCode, } from "./errors.js";
+export { HANDOFF_PACKAGE_VERSION, createHandoffPackage, verifyHandoffPackageDigest, isHandoffPackage, type HandoffIdentitySnapshot, type HandoffPackage, type HandoffPackageInput, } from "./package.js";
+export { HANDOFF_SESSION_STATUSES, ManualHandoffChannel, type HandoffChannel, type HandoffResult, type HandoffSession, type HandoffSessionStatus, type ManualHandoffChannelOptions, } from "./channel.js";
+export { CONFIRMATION_EVIDENCE_KINDS, FailClosedAuthorizationProvider, createPaymentAuthorization, createUserConfirmationEvidence, digestTerms, newAuthorizationId, type AuthorizeCheckoutInput, type AuthorizeCheckoutResult, type AuthorizationProvider, type ConfirmationEvidenceKind, type CreateIntentMandateInput, type CreateIntentMandateResult, type PaymentAuthorization, type PaymentAuthorizationInput, type UserConfirmationEvidence, type UserConfirmationEvidenceInput, type VerifyIntentMandateInput, type VerifyIntentMandateResult, } from "./authorization.js";
+export { COMPLETION_GATE_FAILURE_CODES, evaluateCompletionGate, isStructurallyValidAuthorization, type CompletionGateContext, type CompletionGateDecision, type CompletionGateFailureCode, } from "./completion.js";
+export { DESTINATION_TYPES, isDestinationType, isUrlDestinationType, validateDestination, type Destination, type DestinationType, } from "./destination.js";
+export { computeCandidateDigest, createHandoffCandidate, isHandoffCandidate, validateHandoffCandidate, verifyHandoffCandidateDigest, type HandoffCandidate, type HandoffCandidateInput, type HandoffDisplaySummary, } from "./candidate.js";
+export { HANDOFF_CANDIDATE_EVENT_KINDS, HANDOFF_CANDIDATE_LIFECYCLE_STATES, foldCandidateLifecycle, isHandoffCandidateEventKind, isTerminalLifecycleState, transitionCandidateLifecycle, type HandoffCandidateEventKind, type HandoffCandidateLifecycleState, } from "./lifecycle.js";
+export { HANDOFF_DELIVERY_EVENT_KINDS, HandoffEventStore, type HandoffDeliveryEventKind, type HandoffEventInput, type HandoffEventStoreOptions, } from "./ledger.js";
+export { HANDOFF_DELIVERY_STATES, OPEN_EVIDENCE_KINDS, deliveryState, isHandoffDeliveryEventKind, recordLaunch, recordOpenEvidence, recordRevoked, validateOpenEvidence, type HandoffDeliveryState, type OpenEvidence, type OpenEvidenceKind, } from "./delivery.js";
+export { executeHandoff, defaultUrlSafety, type AgreementReadResult, type ExecuteHandoffInput, type ExecuteHandoffResult, type TransactionHandoff, } from "./transaction.js";
+export { HandoffIdempotencyStore, type HandoffIdempotencyStoreOptions } from "./idempotency.js";
+export { validateExternalDestinationUrl, type SafeDestinationUrl, type UrlSafetyOptions, } from "./url-safety.js";
+export { computeHandoffMetrics, type HandoffMetrics } from "./metrics.js";

package/dist/handoff/index.js

@@ -0,0 +1,48 @@
+/**
+ * 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）—— 域模型与授权接缝。
+ *
+ * 基线 §3.4 / §43：订单/支付发生在外部交易系统（UCP Checkout，business 是
+ * Merchant of Record）；Kiwi 只做「非绑定共识 → 交易系统」的安全交接。本包只
+ * 提供交接工件、交易系统适配接缝、AP2 授权接缝与完成门禁，不创建订单、不处理
+ * 原始支付凭据、不实现真实 UCP Checkout / AP2（分别属于 WP2 / 外部系统）。
+ *
+ * 两层关系（术语对齐决策，KTH rev0.3）：
+ *   外层 —— KTH 候选链：Agreement → HandoffCandidate（candidate.ts，
+ *   不可变 + event-sourced 生命周期 lifecycle.ts/ledger.ts）→ 交付观察
+ *   （delivery 状态，Phase 2）。
+ *   内层 —— UCP checkout session 适配：HandoffPackage/HandoffSession/
+ *   HandoffChannel（package.ts/channel.ts，v0.6.0 WP1 工件，不重命名保留）。
+ *   `ucp_checkout`/`ucp_order` 目的地走内层；URL/PO/quote/contact 目的地
+ *   走外层交付。
+ */
+export { HandoffError, HANDOFF_ERROR_CODES, } from "./errors.js";
+export { HANDOFF_PACKAGE_VERSION, createHandoffPackage, verifyHandoffPackageDigest, isHandoffPackage, } from "./package.js";
+export { HANDOFF_SESSION_STATUSES, ManualHandoffChannel, } from "./channel.js";
+export { CONFIRMATION_EVIDENCE_KINDS, FailClosedAuthorizationProvider, createPaymentAuthorization, createUserConfirmationEvidence, digestTerms, newAuthorizationId, } from "./authorization.js";
+export { COMPLETION_GATE_FAILURE_CODES, evaluateCompletionGate, isStructurallyValidAuthorization, } from "./completion.js";
+// ── KTH/0.1 rev0.3（v0.7.0 WP-C1）──────────────────────────────────────────
+export { DESTINATION_TYPES, isDestinationType, isUrlDestinationType, validateDestination, } from "./destination.js";
+export { computeCandidateDigest, createHandoffCandidate, isHandoffCandidate, validateHandoffCandidate, verifyHandoffCandidateDigest, } from "./candidate.js";
+export { HANDOFF_CANDIDATE_EVENT_KINDS, HANDOFF_CANDIDATE_LIFECYCLE_STATES, foldCandidateLifecycle, isHandoffCandidateEventKind, isTerminalLifecycleState, transitionCandidateLifecycle, } from "./lifecycle.js";
+export { HANDOFF_DELIVERY_EVENT_KINDS, HandoffEventStore, } from "./ledger.js";
+export { HANDOFF_DELIVERY_STATES, OPEN_EVIDENCE_KINDS, deliveryState, isHandoffDeliveryEventKind, recordLaunch, recordOpenEvidence, recordRevoked, validateOpenEvidence, } from "./delivery.js";
+export { executeHandoff, defaultUrlSafety, } from "./transaction.js";
+export { HandoffIdempotencyStore } from "./idempotency.js";
+export { validateExternalDestinationUrl, } from "./url-safety.js";
+export { computeHandoffMetrics } from "./metrics.js";
+//# sourceMappingURL=index.js.map

package/dist/handoff/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/handoff/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EACL,YAAY,EACZ,mBAAmB,GAEpB,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,uBAAuB,EACvB,oBAAoB,EACpB,0BAA0B,EAC1B,gBAAgB,GAIjB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,wBAAwB,EACxB,oBAAoB,GAMrB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,2BAA2B,EAC3B,+BAA+B,EAC/B,0BAA0B,EAC1B,8BAA8B,EAC9B,WAAW,EACX,kBAAkB,GAanB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,6BAA6B,EAC7B,sBAAsB,EACtB,gCAAgC,GAIjC,MAAM,iBAAiB,CAAC;AAEzB,4EAA4E;AAE5E,OAAO,EACL,iBAAiB,EACjB,iBAAiB,EACjB,oBAAoB,EACpB,mBAAmB,GAGpB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EACL,sBAAsB,EACtB,sBAAsB,EACtB,kBAAkB,EAClB,wBAAwB,EACxB,4BAA4B,GAI7B,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,6BAA6B,EAC7B,kCAAkC,EAClC,sBAAsB,EACtB,2BAA2B,EAC3B,wBAAwB,EACxB,4BAA4B,GAG7B,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,4BAA4B,EAC5B,iBAAiB,GAIlB,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,uBAAuB,EACvB,mBAAmB,EACnB,aAAa,EACb,0BAA0B,EAC1B,YAAY,EACZ,kBAAkB,EAClB,aAAa,EACb,oBAAoB,GAIrB,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,cAAc,EACd,gBAAgB,GAKjB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EAAE,uBAAuB,EAAuC,MAAM,kBAAkB,CAAC;AAEhG,OAAO,EACL,8BAA8B,GAG/B,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAE,qBAAqB,EAAuB,MAAM,cAAc,CAAC"}

package/dist/handoff/ledger.d.ts

@@ -0,0 +1,94 @@
+/**
+ * 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.
+ */
+/**
+ * HandoffEventStore —— 复用 `LedgerStore` 引擎（append-only / hash-linked /
+ * verifyChain / 禁词扫描全部继承）的 KTH 事件存储。
+ *
+ * 链 key：negotiation_id（来自候选的 agreement 溯源）——handoff 事件落在
+ * 产生它的 negotiation 的审计链上；`eventsForCandidate` / `eventsForHandoff`
+ * 在链内按 id 过滤。候选生命周期状态由 events 投影（KTH rev0.3 §5.1，
+ * 完成定义 #18 Ledger 可审计 Handoff created/delivered/opened/expired）。
+ */
+import { type LedgerCapabilitySnapshot, type LedgerEvent, type LedgerIdentitySnapshot, type LedgerOutcome, type LedgerVerifyResult } from "../negotiation/ledger/event.js";
+import type { HandoffCandidate } from "./candidate.js";
+import { type HandoffCandidateEventKind } from "./lifecycle.js";
+/** 交付观察事件 kind（KTH rev0.3 §9；不伪装外部成交，§36-27/28）。 */
+export declare const HANDOFF_DELIVERY_EVENT_KINDS: readonly ["handoff_delivered", "handoff_launched", "handoff_opened_confirmed", "handoff_expired", "handoff_revoked", "handoff_delivery_failed"];
+export type HandoffDeliveryEventKind = (typeof HANDOFF_DELIVERY_EVENT_KINDS)[number];
+export interface HandoffEventStoreOptions {
+    /** 基础数据目录；事件落在 `<dir>/ledger/`（与 negotiation 同目录布局）。 */
+    dir: string;
+    /** 可注入时钟（RFC 3339）；缺省 new Date().toISOString()。 */
+    now?: () => string;
+}
+export interface HandoffEventInput {
+    kind: HandoffCandidateEventKind | HandoffDeliveryEventKind;
+    /** 溯源候选。 */
+    candidate: HandoffCandidate;
+    /** 交付事件绑定 handoff_id（candidate 事件省略）。 */
+    handoff_id?: string;
+    identity: LedgerIdentitySnapshot;
+    capability: LedgerCapabilitySnapshot;
+    /** 可归属证据（OPENED_CONFIRMED 必需；其余可选）。 */
+    evidence?: Record<string, unknown>;
+    /** 目的地快照（最小化、非秘密）。 */
+    destination?: Record<string, unknown>;
+    outcome?: LedgerOutcome;
+    occurred_at?: string;
+}
+/** KTH 事件存储（LedgerStore 引擎复用）。 */
+export declare class HandoffEventStore {
+    private readonly store;
+    private readonly now;
+    constructor(options: HandoffEventStoreOptions);
+    /** 追加一条 handoff 事件（candidate 生命周期或交付观察）。 */
+    append(input: HandoffEventInput): LedgerEvent;
+    /** 候选生命周期事件（kind 限定 candidate 域）。 */
+    appendCandidateEvent(input: Omit<HandoffEventInput, "kind"> & {
+        kind: HandoffCandidateEventKind;
+    }): LedgerEvent;
+    /**
+     * 交付观察事件（kind 限定 delivery 域）。
+     *
+     * 落链前做交付状态机迁移校验（delivery.ts 的 DELIVERY_TRANSITIONS，
+     * 与 candidate lifecycle 的迁移校验对称）：交付事件必须绑定 handoff_id，
+     * 且 (none)→DELIVERED 必须是首个事件；REVOKED/EXPIRED/OPENED_CONFIRMED
+     * 之后不再接受任何事件。校验按同 handoff_id 折叠（同一 negotiation 链上
+     * 可并存多个 handoff 的交付事件，互不干扰）。
+     */
+    appendDeliveryEvent(input: Omit<HandoffEventInput, "kind"> & {
+        kind: HandoffDeliveryEventKind;
+    }): LedgerEvent;
+    /** 某 negotiation 链上的全部事件。 */
+    events(negotiationId: string): LedgerEvent[];
+    /** 全部已落账的 negotiation_id（/handoff 列表用）。 */
+    listNegotiations(): string[];
+    /** 某候选的全部生命周期 + 交付事件（按记录时间序；链 key = negotiation_id）。 */
+    eventsForCandidate(negotiationId: string, candidateId: string): LedgerEvent[];
+    /** 某 handoff 的交付观察事件。 */
+    eventsForHandoff(negotiationId: string, handoffId: string): LedgerEvent[];
+    /** 链完整性校验（篡改 / 断链 / 重复检出）。 */
+    verifyChain(negotiationId: string): LedgerVerifyResult;
+    /**
+     * 惰性过期清扫（评审项 L1）：handoff_candidate_expired 此前只在
+     * executeHandoff 的过期门内落链——到期未执行的候选在 TUI /handoff 列表
+     * 永远显示 PROPOSED/READY"从未获批/从未执行"，指标失真。本方法遍历全部
+     * 链，对未终态且 expires_at 已过的候选落 expired 事件。幂等：已终态
+     * （EXPIRED/REJECTED/STALE/CONSUMED）候选不重复处理。调用方挂载在 kernel
+     * 的周期性入口（schedulerTick）与 /handoff 渲染前。
+     */
+    sweepExpiredCandidates(now: string): number;
+}

package/dist/handoff/ledger.js

@@ -0,0 +1,195 @@
+/**
+ * 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.
+ */
+/**
+ * HandoffEventStore —— 复用 `LedgerStore` 引擎（append-only / hash-linked /
+ * verifyChain / 禁词扫描全部继承）的 KTH 事件存储。
+ *
+ * 链 key：negotiation_id（来自候选的 agreement 溯源）——handoff 事件落在
+ * 产生它的 negotiation 的审计链上；`eventsForCandidate` / `eventsForHandoff`
+ * 在链内按 id 过滤。候选生命周期状态由 events 投影（KTH rev0.3 §5.1，
+ * 完成定义 #18 Ledger 可审计 Handoff created/delivered/opened/expired）。
+ */
+import { assertNoForbiddenContent, } from "../negotiation/ledger/event.js";
+import { LedgerStore } from "../negotiation/ledger/store.js";
+import { HANDOFF_CANDIDATE_EVENT_KINDS, } from "./lifecycle.js";
+import { deliveryState, transitionDeliveryState } from "./delivery.js";
+import { isTerminalLifecycleState, foldCandidateLifecycle } from "./lifecycle.js";
+import { HandoffError } from "./errors.js";
+/** 交付观察事件 kind（KTH rev0.3 §9；不伪装外部成交，§36-27/28）。 */
+export const HANDOFF_DELIVERY_EVENT_KINDS = [
+    "handoff_delivered",
+    "handoff_launched",
+    "handoff_opened_confirmed",
+    "handoff_expired",
+    "handoff_revoked",
+    "handoff_delivery_failed",
+];
+/** 从目的地补充字段中剥离候选身份字段（type/ref 属于候选，不可被覆盖）。 */
+function stripDestinationIdentityFields(destination) {
+    const rest = { ...destination };
+    delete rest.type;
+    delete rest.ref;
+    return rest;
+}
+/** KTH 事件存储（LedgerStore 引擎复用）。 */
+export class HandoffEventStore {
+    store;
+    now;
+    constructor(options) {
+        this.store = new LedgerStore({ dir: options.dir, now: options.now });
+        this.now = options.now ?? (() => new Date().toISOString());
+    }
+    /** 追加一条 handoff 事件（candidate 生命周期或交付观察）。 */
+    append(input) {
+        // evidence / destination 是自由对象字段（LedgerStore 的禁词扫描只覆盖
+        // wire_payload / outcome.result）——本地补扫，保证秘密永不落链（§36-5）。
+        if (input.evidence !== undefined)
+            assertNoForbiddenContent(input.evidence, "evidence");
+        if (input.destination !== undefined)
+            assertNoForbiddenContent(input.destination, "destination");
+        const isCandidateEvent = HANDOFF_CANDIDATE_EVENT_KINDS.includes(input.kind);
+        const content = {
+            event_kind: input.kind,
+            negotiation_id: input.candidate.negotiation_id,
+            handoff_candidate_id: input.candidate.handoff_candidate_id,
+            ...(input.handoff_id !== undefined ? { handoff_id: input.handoff_id } : {}),
+            agreement_id: input.candidate.agreement_id,
+            terms_digest: input.candidate.terms_digest,
+            ...(input.destination !== undefined
+                ? {
+                    destination: {
+                        type: input.candidate.destination_type,
+                        ref: input.candidate.destination_ref,
+                        // 调用方只可补充展示字段（如 final_url）；type/ref 是候选的审计
+                        // 事实，不得被覆盖（否则落链目的地与候选内容不一致）。
+                        ...stripDestinationIdentityFields(input.destination),
+                    },
+                }
+                : {}),
+            ...(input.evidence !== undefined ? { evidence: input.evidence } : {}),
+            identity: input.identity,
+            capability: input.capability,
+            // 候选生命周期事件携带完整候选文档（KTH rev0.3 §5.1/§18-13：
+            // lifecycle 从事件重建且不 mutate 候选内容）。
+            outcome: input.outcome ??
+                (isCandidateEvent
+                    ? { kind: "ok", result: { candidate: input.candidate } }
+                    : { kind: "ok", result: {} }),
+            occurred_at: input.occurred_at ?? this.now(),
+        };
+        return this.store.append(content);
+    }
+    /** 候选生命周期事件（kind 限定 candidate 域）。 */
+    appendCandidateEvent(input) {
+        return this.append(input);
+    }
+    /**
+     * 交付观察事件（kind 限定 delivery 域）。
+     *
+     * 落链前做交付状态机迁移校验（delivery.ts 的 DELIVERY_TRANSITIONS，
+     * 与 candidate lifecycle 的迁移校验对称）：交付事件必须绑定 handoff_id，
+     * 且 (none)→DELIVERED 必须是首个事件；REVOKED/EXPIRED/OPENED_CONFIRMED
+     * 之后不再接受任何事件。校验按同 handoff_id 折叠（同一 negotiation 链上
+     * 可并存多个 handoff 的交付事件，互不干扰）。
+     */
+    appendDeliveryEvent(input) {
+        if (input.handoff_id === undefined) {
+            throw new HandoffError("invalid_input", "delivery event requires handoff_id", "handoff_id");
+        }
+        const chain = this.store.events(input.candidate.negotiation_id);
+        const current = deliveryState(chain.filter((e) => e.handoff_id === input.handoff_id));
+        transitionDeliveryState(current, input.kind);
+        return this.append(input);
+    }
+    /** 某 negotiation 链上的全部事件。 */
+    events(negotiationId) {
+        return this.store.events(negotiationId);
+    }
+    /** 全部已落账的 negotiation_id（/handoff 列表用）。 */
+    listNegotiations() {
+        return this.store.listNegotiations();
+    }
+    /** 某候选的全部生命周期 + 交付事件（按记录时间序；链 key = negotiation_id）。 */
+    eventsForCandidate(negotiationId, candidateId) {
+        return this.store
+            .events(negotiationId)
+            .filter((e) => e.handoff_candidate_id === candidateId);
+    }
+    /** 某 handoff 的交付观察事件。 */
+    eventsForHandoff(negotiationId, handoffId) {
+        return this.store.events(negotiationId).filter((e) => e.handoff_id === handoffId);
+    }
+    /** 链完整性校验（篡改 / 断链 / 重复检出）。 */
+    verifyChain(negotiationId) {
+        return this.store.verifyChain(negotiationId);
+    }
+    /**
+     * 惰性过期清扫（评审项 L1）：handoff_candidate_expired 此前只在
+     * executeHandoff 的过期门内落链——到期未执行的候选在 TUI /handoff 列表
+     * 永远显示 PROPOSED/READY"从未获批/从未执行"，指标失真。本方法遍历全部
+     * 链，对未终态且 expires_at 已过的候选落 expired 事件。幂等：已终态
+     * （EXPIRED/REJECTED/STALE/CONSUMED）候选不重复处理。调用方挂载在 kernel
+     * 的周期性入口（schedulerTick）与 /handoff 渲染前。
+     */
+    sweepExpiredCandidates(now) {
+        let swept = 0;
+        for (const negotiationId of this.store.listNegotiations()) {
+            const events = this.store.events(negotiationId);
+            const seen = new Set();
+            for (const event of events) {
+                const candidateId = event.handoff_candidate_id;
+                if (candidateId === undefined || seen.has(candidateId))
+                    continue;
+                seen.add(candidateId);
+                const candidateEvents = events.filter((e) => e.handoff_candidate_id === candidateId);
+                const state = foldCandidateLifecycle(candidateEvents);
+                if (state === undefined || isTerminalLifecycleState(state))
+                    continue;
+                // 过期判定：候选内嵌文档的 expires_at（created 事件携带完整候选）。
+                const created = candidateEvents.find((e) => e.event_kind === "handoff_candidate_created");
+                const embedded = created?.outcome.kind === "ok"
+                    ? created.outcome.result?.candidate
+                    : undefined;
+                const expiresAt = typeof embedded?.expires_at === "string" ? embedded.expires_at : "";
+                // NaN 防护与 executeHandoff 的过期门一致：不可解析视为未过期（不误杀）。
+                if (expiresAt === "" || !Number.isFinite(Date.parse(expiresAt)))
+                    continue;
+                if (Date.parse(expiresAt) >= Date.parse(now))
+                    continue;
+                const candidate = created?.outcome.kind === "ok"
+                    ? created.outcome.result?.candidate
+                    : undefined;
+                if (candidate === undefined)
+                    continue;
+                try {
+                    this.appendCandidateEvent({
+                        kind: "handoff_candidate_expired",
+                        candidate,
+                        identity: { sender_identity: candidate.buyer_identity_ref, counterparty_identity: candidate.merchant_identity_ref, actor: "buyer" },
+                        capability: { capability: "com.harrylabsj.kiwi.shopping.negotiation", protocol_version: "1.0" },
+                        occurred_at: now,
+                    });
+                    swept += 1;
+                }
+                catch {
+                    // 单候选失败不影响整体清扫（fail-closed 但继续其他链）。
+                }
+            }
+        }
+        return swept;
+    }
+}
+//# sourceMappingURL=ledger.js.map

package/dist/handoff/ledger.js.map

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

package/dist/handoff/lifecycle.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.
+ */
+import type { LedgerEvent, LedgerEventKind } from "../negotiation/ledger/event.js";
+export declare const HANDOFF_CANDIDATE_LIFECYCLE_STATES: readonly ["PROPOSED", "READY", "REJECTED", "STALE", "EXPIRED", "CONSUMED"];
+export type HandoffCandidateLifecycleState = (typeof HANDOFF_CANDIDATE_LIFECYCLE_STATES)[number];
+/** candidate 生命周期事件 kind（与 LEDGER_EVENT_KINDS 的 handoff_candidate_* 对齐）。 */
+export declare const HANDOFF_CANDIDATE_EVENT_KINDS: readonly ["handoff_candidate_created", "handoff_candidate_ready", "handoff_candidate_rejected", "handoff_candidate_stale", "handoff_candidate_expired", "handoff_candidate_consumed"];
+export type HandoffCandidateEventKind = (typeof HANDOFF_CANDIDATE_EVENT_KINDS)[number];
+/** 事件 kind 是否 candidate 生命周期事件。 */
+export declare function isHandoffCandidateEventKind(kind: LedgerEventKind): kind is HandoffCandidateEventKind;
+/** 从 Ledger 事件序列投影 candidate 生命周期状态（纯函数，最后事件胜出）。 */
+export declare function foldCandidateLifecycle(events: readonly Pick<LedgerEvent, "event_kind" | "event_id" | "recorded_at">[]): HandoffCandidateLifecycleState | undefined;
+/** 迁移校验：返回 target 或抛 schemaError（fail-closed）。 */
+export declare function transitionCandidateLifecycle(current: HandoffCandidateLifecycleState | undefined, eventKind: HandoffCandidateEventKind): HandoffCandidateLifecycleState;
+/** 终态判定：终态候选不可 revive，必须新建候选（带 supersedes_candidate_id）。 */
+export declare function isTerminalLifecycleState(state: HandoffCandidateLifecycleState): boolean;