@harrylabsj/kiwi 0.6.0

package/dist/handoff/lifecycle.js

@@ -0,0 +1,102 @@
+/**
+ * Copyright 2026 harrylabsj
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * HandoffCandidate 生命周期 —— event-sourced 投影（KTH rev0.3 §5.1）。
+ *
+ * 候选内容不可变；lifecycle 状态**不是**候选 JSON 内的字段，而是
+ * Ledger 事件的投影（foldCandidateLifecycle 纯函数）。迁移表：
+ *
+ *   (none)     --created-->  PROPOSED
+ *   PROPOSED   --ready-->    READY      （策略/批准通过）
+ *   PROPOSED/READY --rejected--> REJECTED （终态）
+ *   PROPOSED/READY --stale-->   STALE     （绑定输入变化；不可 revive，
+ *                                        需新候选带 supersedes_candidate_id）
+ *   PROPOSED/READY --expired--> EXPIRED   （终态）
+ *   READY      --consumed--> CONSUMED    （执行完成，终态）
+ *
+ * 终态：REJECTED / STALE / EXPIRED / CONSUMED。
+ */
+import { schemaError } from "../negotiation/domain/common.js";
+export const HANDOFF_CANDIDATE_LIFECYCLE_STATES = [
+    "PROPOSED",
+    "READY",
+    "REJECTED",
+    "STALE",
+    "EXPIRED",
+    "CONSUMED",
+];
+/** candidate 生命周期事件 kind（与 LEDGER_EVENT_KINDS 的 handoff_candidate_* 对齐）。 */
+export const HANDOFF_CANDIDATE_EVENT_KINDS = [
+    "handoff_candidate_created",
+    "handoff_candidate_ready",
+    "handoff_candidate_rejected",
+    "handoff_candidate_stale",
+    "handoff_candidate_expired",
+    "handoff_candidate_consumed",
+];
+const TERMINAL_STATES = new Set([
+    "REJECTED",
+    "STALE",
+    "EXPIRED",
+    "CONSUMED",
+]);
+/** kind → 投影状态。 */
+const EVENT_KIND_TO_STATE = {
+    handoff_candidate_created: "PROPOSED",
+    handoff_candidate_ready: "READY",
+    handoff_candidate_rejected: "REJECTED",
+    handoff_candidate_stale: "STALE",
+    handoff_candidate_expired: "EXPIRED",
+    handoff_candidate_consumed: "CONSUMED",
+};
+/** 显式迁移表：current → allowed next states。 */
+const TRANSITIONS = {
+    "": new Set(["PROPOSED"]),
+    PROPOSED: new Set(["READY", "REJECTED", "STALE", "EXPIRED"]),
+    READY: new Set(["REJECTED", "STALE", "EXPIRED", "CONSUMED"]),
+    REJECTED: new Set(),
+    STALE: new Set(),
+    EXPIRED: new Set(),
+    CONSUMED: new Set(),
+};
+/** 事件 kind 是否 candidate 生命周期事件。 */
+export function isHandoffCandidateEventKind(kind) {
+    return HANDOFF_CANDIDATE_EVENT_KINDS.includes(kind);
+}
+/** 从 Ledger 事件序列投影 candidate 生命周期状态（纯函数，最后事件胜出）。 */
+export function foldCandidateLifecycle(events) {
+    let state;
+    for (const event of events) {
+        if (!isHandoffCandidateEventKind(event.event_kind))
+            continue;
+        state = EVENT_KIND_TO_STATE[event.event_kind];
+    }
+    return state;
+}
+/** 迁移校验：返回 target 或抛 schemaError（fail-closed）。 */
+export function transitionCandidateLifecycle(current, eventKind) {
+    const target = EVENT_KIND_TO_STATE[eventKind];
+    const allowed = TRANSITIONS[current ?? ""] ?? new Set();
+    if (!allowed.has(target)) {
+        throw schemaError("handoff_candidate_lifecycle", `illegal handoff candidate lifecycle transition ${current ?? "(none)"} --${eventKind}--> ${target}`);
+    }
+    return target;
+}
+/** 终态判定：终态候选不可 revive，必须新建候选（带 supersedes_candidate_id）。 */
+export function isTerminalLifecycleState(state) {
+    return TERMINAL_STATES.has(state);
+}
+//# sourceMappingURL=lifecycle.js.map

package/dist/handoff/lifecycle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.js","sourceRoot":"","sources":["../../src/handoff/lifecycle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,iCAAiC,CAAC;AAG9D,MAAM,CAAC,MAAM,kCAAkC,GAAG;IAChD,UAAU;IACV,OAAO;IACP,UAAU;IACV,OAAO;IACP,SAAS;IACT,UAAU;CACF,CAAC;AAIX,4EAA4E;AAC5E,MAAM,CAAC,MAAM,6BAA6B,GAAG;IAC3C,2BAA2B;IAC3B,yBAAyB;IACzB,4BAA4B;IAC5B,yBAAyB;IACzB,2BAA2B;IAC3B,4BAA4B;CACpB,CAAC;AAIX,MAAM,eAAe,GAAgD,IAAI,GAAG,CAAC;IAC3E,UAAU;IACV,OAAO;IACP,SAAS;IACT,UAAU;CACX,CAAC,CAAC;AAEH,mBAAmB;AACnB,MAAM,mBAAmB,GAAgF;IACvG,yBAAyB,EAAE,UAAU;IACrC,uBAAuB,EAAE,OAAO;IAChC,0BAA0B,EAAE,UAAU;IACtC,uBAAuB,EAAE,OAAO;IAChC,yBAAyB,EAAE,SAAS;IACpC,0BAA0B,EAAE,UAAU;CACvC,CAAC;AAEF,2CAA2C;AAC3C,MAAM,WAAW,GAA0E;IACzF,EAAE,EAAE,IAAI,GAAG,CAAC,CAAC,UAAU,CAAC,CAAC;IACzB,QAAQ,EAAE,IAAI,GAAG,CAAC,CAAC,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,SAAS,CAAC,CAAC;IAC5D,KAAK,EAAE,IAAI,GAAG,CAAC,CAAC,UAAU,EAAE,OAAO,EAAE,SAAS,EAAE,UAAU,CAAC,CAAC;IAC5D,QAAQ,EAAE,IAAI,GAAG,EAAE;IACnB,KAAK,EAAE,IAAI,GAAG,EAAE;IAChB,OAAO,EAAE,IAAI,GAAG,EAAE;IAClB,QAAQ,EAAE,IAAI,GAAG,EAAE;CACpB,CAAC;AAEF,mCAAmC;AACnC,MAAM,UAAU,2BAA2B,CAAC,IAAqB;IAC/D,OAAQ,6BAAmD,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;AAC7E,CAAC;AAED,oDAAoD;AACpD,MAAM,UAAU,sBAAsB,CACpC,MAA+E;IAE/E,IAAI,KAAiD,CAAC;IACtD,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,IAAI,CAAC,2BAA2B,CAAC,KAAK,CAAC,UAAU,CAAC;YAAE,SAAS;QAC7D,KAAK,GAAG,mBAAmB,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;IAChD,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,kDAAkD;AAClD,MAAM,UAAU,4BAA4B,CAC1C,OAAmD,EACnD,SAAoC;IAEpC,MAAM,MAAM,GAAG,mBAAmB,CAAC,SAAS,CAAC,CAAC;IAC9C,MAAM,OAAO,GAAG,WAAW,CAAC,OAAO,IAAI,EAAE,CAAC,IAAI,IAAI,GAAG,EAAkC,CAAC;IACxF,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;QACzB,MAAM,WAAW,CACf,6BAA6B,EAC7B,kDAAkD,OAAO,IAAI,QAAQ,MAAM,SAAS,OAAO,MAAM,EAAE,CACpG,CAAC;IACJ,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,4DAA4D;AAC5D,MAAM,UAAU,wBAAwB,CAAC,KAAqC;IAC5E,OAAO,eAAe,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;AACpC,CAAC"}

package/dist/handoff/metrics.d.ts

@@ -0,0 +1,56 @@
+/**
+ * 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 指标（架构 rev1.4.1 §35A.8 / 完成定义 #21：Negotiation-to-Handoff
+ * Rate 可观测）。纯函数：从 Ledger 事件计算，审计即观测源（零新存储）。
+ *
+ * 口径注记：
+ * - "agreements" 以产生 handoff_candidate_created 的候选数为代理
+ *   （候选创建以 agreement 存在为前提；Ledger 没有独立的 agreement 事件）；
+ * - `reported_external_conversion` 必须标注为外部报告——Kiwi 没有权威
+ *   交易集成时恒为 null（KTH rev0.3 §17：MUST be labeled externally
+ *   reported unless authoritative integration exists）。
+ */
+import type { LedgerEvent } from "../negotiation/ledger/event.js";
+export interface HandoffMetrics {
+    /** 产生过 handoff 候选的 negotiation 数（= 已达成协议的代理口径）。 */
+    negotiations_with_candidates: number;
+    /** handoff_candidate_created 总数。 */
+    candidates_created: number;
+    /** handoff_delivered 总数（成功交接的协议数）。 */
+    handoffs_delivered: number;
+    /** handoff_launched 总数。 */
+    launches: number;
+    /** handoff_opened_confirmed 总数（仅计有可归属证据的确认）。 */
+    opened_confirmed: number;
+    /** agreement → handoff 率（delivered / created；无候选时 0）。 */
+    agreement_to_handoff_rate: number;
+    /** handoff → launch 率（launched / delivered）。 */
+    handoff_launch_rate: number;
+    /** opened_confirmed 率（opened / delivered——与实现一致的分母；launch 事件可选，不参与分母）。 */
+    opened_confirmed_rate: number;
+    /** negotiation → handoff 率（delivered / 有候选的 negotiation 数）。 */
+    negotiation_to_handoff_rate: number;
+    /** created → delivered 中位时长（秒）；无样本时 null。 */
+    time_to_handoff_seconds: number | null;
+    /**
+     * 外部报告的外部转化率。Kiwi 无权威交易集成 → 恒 null
+     * （绝不从 delivered/opened 推断外部成功，§36-27）。
+     */
+    reported_external_conversion: null;
+}
+/** 全部 handoff 相关事件 → 指标（跨 negotiation 聚合）。 */
+export declare function computeHandoffMetrics(eventsByNegotiation: ReadonlyMap<string, readonly LedgerEvent[]>): HandoffMetrics;

package/dist/handoff/metrics.js

@@ -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.
+ */
+/** 全部 handoff 相关事件 → 指标（跨 negotiation 聚合）。 */
+export function computeHandoffMetrics(eventsByNegotiation) {
+    let candidatesCreated = 0;
+    let delivered = 0;
+    let launches = 0;
+    let openedConfirmed = 0;
+    const negotiationsWithCandidates = new Set();
+    const timeToHandoff = [];
+    for (const [negotiationId, events] of eventsByNegotiation) {
+        const createdAt = new Map();
+        const deliveredAt = new Map();
+        for (const event of events) {
+            switch (event.event_kind) {
+                case "handoff_candidate_created":
+                    candidatesCreated += 1;
+                    negotiationsWithCandidates.add(negotiationId);
+                    if (event.handoff_candidate_id !== undefined) {
+                        createdAt.set(event.handoff_candidate_id, Date.parse(event.occurred_at));
+                    }
+                    break;
+                case "handoff_delivered":
+                    delivered += 1;
+                    if (event.handoff_candidate_id !== undefined) {
+                        deliveredAt.set(event.handoff_candidate_id, Date.parse(event.occurred_at));
+                    }
+                    break;
+                case "handoff_launched":
+                    launches += 1;
+                    break;
+                case "handoff_opened_confirmed":
+                    // 计数所有 opened 事件（事件已由证据门保证可归属——recordOpenEvidence
+                    // 只落带可归属证据的确认；无证据的 launch 永不产生本事件）。
+                    openedConfirmed += 1;
+                    break;
+                default:
+                    break;
+            }
+        }
+        for (const [candidateId, created] of createdAt) {
+            const deliveredTs = deliveredAt.get(candidateId);
+            if (deliveredTs !== undefined && Number.isFinite(created) && Number.isFinite(deliveredTs)) {
+                timeToHandoff.push(Math.max(0, deliveredTs - created) / 1000);
+            }
+        }
+    }
+    const timeToHandoffSeconds = timeToHandoff.length > 0
+        ? [...timeToHandoff].sort((a, b) => a - b)[Math.floor(timeToHandoff.length / 2)] ?? null
+        : null;
+    return {
+        negotiations_with_candidates: negotiationsWithCandidates.size,
+        candidates_created: candidatesCreated,
+        handoffs_delivered: delivered,
+        launches,
+        opened_confirmed: openedConfirmed,
+        agreement_to_handoff_rate: candidatesCreated > 0 ? delivered / candidatesCreated : 0,
+        handoff_launch_rate: delivered > 0 ? launches / delivered : 0,
+        opened_confirmed_rate: delivered > 0 ? openedConfirmed / delivered : 0,
+        negotiation_to_handoff_rate: negotiationsWithCandidates.size > 0 ? delivered / negotiationsWithCandidates.size : 0,
+        time_to_handoff_seconds: timeToHandoffSeconds,
+        reported_external_conversion: null,
+    };
+}
+//# sourceMappingURL=metrics.js.map

package/dist/handoff/metrics.js.map

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

package/dist/handoff/operator-approval.d.ts

@@ -0,0 +1,143 @@
+/**
+ * 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 AuthorizeCheckoutInput, type AuthorizeCheckoutResult, type AuthorizationProvider, type CreateIntentMandateInput, type CreateIntentMandateResult, type UserConfirmationEvidence, type VerifyIntentMandateInput, type VerifyIntentMandateResult } from "./authorization.js";
+import type { HandoffSession } from "./channel.js";
+import type { HandoffPackage } from "./package.js";
+/** 审批记录自身状态（撤销是显式的；过期是时间派生的）。 */
+export declare const OPERATOR_APPROVAL_RECORD_STATUSES: readonly ["approved", "revoked"];
+export type OperatorApprovalRecordStatus = (typeof OPERATOR_APPROVAL_RECORD_STATUSES)[number];
+/** 底层候选生命周期状态（WriteApprovalCandidate status，write-gate 适配）。 */
+export declare const OPERATOR_APPROVAL_SOURCE_STATUSES: readonly ["pending_approval", "approved", "executed", "rejected", "superseded", "expired"];
+export type OperatorApprovalSourceStatus = (typeof OPERATOR_APPROVAL_SOURCE_STATUSES)[number];
+/**
+ * 审批面（approval face）上展示的 checkout session 摘要。operator 确认的是
+ * 「这个 session + 这些 terms + 这个远端 revision」的组合，任一变化即 stale。
+ */
+export interface CheckoutSessionSummary {
+    session_ref: string;
+    current_terms_digest: string;
+    /** 远端 checkout 的 revision（opaque；变化即 stale）。 */
+    remote_revision: string;
+    status: string;
+}
+/** 从 HandoffSession 构造审批面摘要；缺省 remote_revision 用 session.updated_at。 */
+export declare function summarizeCheckoutSession(session: Pick<HandoffSession, "session_ref" | "current_terms_digest" | "status" | "updated_at">, remoteRevision?: string): CheckoutSessionSummary;
+/** HandoffPackage 的紧凑身份摘要（审批面确认的对象）。 */
+export declare function digestHandoffPackage(pkg: HandoffPackage): string;
+/**
+ * 一条已确认的 operator 审批记录。所有字段只读——状态变化通过替换整条记录实现
+ * （revokeApproval），避免原地突变。
+ */
+export interface OperatorApprovalRecord {
+    /** 审批 id；与 WriteApprovalCandidate.candidate_id 对齐（opaque）。 */
+    readonly approval_id: string;
+    readonly session_ref: string;
+    readonly terms_digest: string;
+    /** 审批面展示的 HandoffPackage 身份摘要。 */
+    readonly package_digest: string;
+    /** §19：候选内容摘要（candidate_digest）。 */
+    readonly candidate_digest: string;
+    /** §19：确认时的远端 checkout revision。 */
+    readonly remote_revision: string;
+    /** §19：审批生效的 policy 版本。 */
+    readonly policy_version: string;
+    readonly status: OperatorApprovalRecordStatus;
+    /** 用户/操作员显式确认时间（RFC 3339）。 */
+    readonly confirmed_at: string;
+    /** 授权有效期终点；过期即 stale（对齐 candidate expires_at）。 */
+    readonly expires_at: string;
+    readonly recorded_at: string;
+}
+export interface RecordOperatorApprovalInput {
+    approval_id: string;
+    /** 审批面展示的 HandoffPackage（operator 确认的对象）。 */
+    package: HandoffPackage;
+    /** 审批面展示的 checkout session 摘要。 */
+    session: CheckoutSessionSummary;
+    /** §19 candidate_digest。 */
+    candidate_digest: string;
+    /** §19 policy_version。 */
+    policy_version: string;
+    /** 可注入确认时间（RFC 3339）；缺省 now。 */
+    confirmed_at?: string;
+    /** 审批有效期长度（毫秒）；缺省 30 分钟。 */
+    ttl_ms?: number;
+}
+/** 缺省审批窗口：对齐 createPaymentAuthorization 的授权 TTL（30 分钟）。 */
+export declare const OPERATOR_APPROVAL_TTL_MS: number;
+/**
+ * 读取底层审批候选生命周期状态的接缝。真实实现由 write-gate 从
+ * WriteApprovalCandidateStore 适配（writeApprovalStatusSource）；provider 只依赖
+ * 这一个窄接口，不直接依赖 agent 层。
+ */
+export interface OperatorApprovalStatusSource {
+    getApprovalState(candidateId: string): {
+        status: OperatorApprovalSourceStatus;
+        expires_at: string;
+    } | undefined;
+}
+export interface OperatorApprovalAuthorizationProviderOptions {
+    /** 可注入时钟（RFC 3339）；缺省 new Date().toISOString()。 */
+    now?: () => string;
+    /** 底层候选生命周期来源（WriteApprovalCandidate 适配）；可选。 */
+    statusSource?: OperatorApprovalStatusSource;
+    /**
+     * 返回某 session 当前的远端 revision；提供时与审批记录的 remote_revision 比对，
+     * 不一致即 stale（§19 remote_revision 绑定）。
+     */
+    currentRevision?: (sessionRef: string) => string | undefined;
+    /**
+     * 可选持久化目录：提供时审批事件（record/revoke）落 JSONL（目录 0700、
+     * 文件 0600），重启恢复 + §19 审计留存；缺省纯内存（进程重启即失效）。
+     */
+    persistDir?: string;
+}
+/**
+ * 把 operator 审批证据桥接为 AuthorizationProvider：
+ *   - recordApproval 记录「人在审批面确认 HandoffPackage + session 摘要」；
+ *   - createIntentMandate：有有效审批 → ok（intent_mandate=approval_id）；
+ *     未确认 / 超时 / 被吊销 → requires_user（绝不自动授权）；
+ *   - verifyIntentMandate：审批 stale / 吊销 / 绑定变化 → verified:false；
+ *   - authorizeCheckout：产出绑定 terms_digest + session_ref + evidence
+ *     （confirmed_at ≤ approved_at）的 PaymentAuthorization。
+ */
+export declare class OperatorApprovalAuthorizationProvider implements AuthorizationProvider {
+    private readonly records;
+    private readonly now;
+    private readonly options;
+    private readonly journalPath?;
+    constructor(options?: OperatorApprovalAuthorizationProviderOptions);
+    /** 从 JSONL 重放审批事件（同 approval_id 后事件胜出；撕裂行容忍跳过）。 */
+    private replayJournal;
+    /** 追加一条审批事件（单行 append，原子）。 */
+    private journalAppend;
+    /** 记录一次显式确认。返回固化后的只读审批记录。 */
+    recordApproval(input: RecordOperatorApprovalInput): OperatorApprovalRecord;
+    /** 显式撤销一条审批（对齐 WriteApprovalCandidate.reject/supersede）。 */
+    revokeApproval(approvalId: string): OperatorApprovalRecord;
+    /** 只读取回一条审批记录。 */
+    getApproval(approvalId: string): OperatorApprovalRecord | undefined;
+    /** 当前审批记录数量（诊断用）。 */
+    get approvalCount(): number;
+    createIntentMandate(input: CreateIntentMandateInput): CreateIntentMandateResult;
+    verifyIntentMandate(intent_mandate: string, input: VerifyIntentMandateInput): VerifyIntentMandateResult;
+    authorizeCheckout(input: AuthorizeCheckoutInput): AuthorizeCheckoutResult;
+    private findUsableApproval;
+    /** 返回审批不可用的原因；可用时返回 undefined。判定顺序固定，便于审计。 */
+    private invalidReason;
+}
+/** 从审批记录构造 UserConfirmationEvidence（供上层在调用 authorizeCheckout 前展示）。 */
+export declare function operatorConfirmationEvidence(approval: OperatorApprovalRecord, now?: () => string): UserConfirmationEvidence;