@harrylabsj/kiwi 0.6.0

package/dist/handoff/operator-approval.js

@@ -0,0 +1,287 @@
+/**
+ * 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 — OperatorApprovalAuthorizationProvider（WP3）。
+ *
+ * 把 operator 审批证据桥接为 AuthorizationProvider（AP2 边界）。用户/操作员在
+ * 审批面（approval face）上看到 HandoffPackage + checkout session 摘要后显式
+ * 确认（recordApproval）；此后 createIntentMandate / authorizeCheckout 才能产出
+ * 绑定 terms_digest + session_ref + evidence 的 PaymentAuthorization。
+ *
+ * 与 WriteApprovalCandidate 生命周期对齐（基线 §19 Approval 绑定语义）：
+ *   - approval stale（expired / revoked / 底层 candidate 被 superseded / rejected）
+ *     即授权失效——verifyIntentMandate 返回 verified:false；
+ *   - 未确认 / 超时 → createIntentMandate 返回 requires_user，绝不自动授权；
+ *   - §19 绑定 candidate_digest / remote_revision / policy_version 固化在审批记录里；
+ *     remote_revision 变化（currentRevision 回调核对）即 stale。
+ *
+ * 本模块不创建订单、不处理支付凭据；它只把「人确认过这个 package + session」这一
+ * 事实安全地变成完成门禁可验证的授权。
+ */
+import { appendFileSync, chmodSync, existsSync, mkdirSync, readFileSync, } from "node:fs";
+import path from "node:path";
+import { requireDigest, requireIsoTimestamp, requireNonEmptyString, } from "../negotiation/domain/common.js";
+import { validateIdentifier } from "../negotiation/domain/identifiers.js";
+import { contentDigest } from "../negotiation/jcs.js";
+import { createPaymentAuthorization, createUserConfirmationEvidence, newAuthorizationId, } from "./authorization.js";
+import { HandoffError } from "./errors.js";
+// ---------------------------------------------------------------------------
+// 审批记录与状态
+// ---------------------------------------------------------------------------
+/** 审批记录自身状态（撤销是显式的；过期是时间派生的）。 */
+export const OPERATOR_APPROVAL_RECORD_STATUSES = ["approved", "revoked"];
+/** 底层候选生命周期状态（WriteApprovalCandidate status，write-gate 适配）。 */
+export const OPERATOR_APPROVAL_SOURCE_STATUSES = [
+    "pending_approval",
+    "approved",
+    "executed",
+    "rejected",
+    "superseded",
+    "expired",
+];
+/** 从 HandoffSession 构造审批面摘要；缺省 remote_revision 用 session.updated_at。 */
+export function summarizeCheckoutSession(session, remoteRevision) {
+    return {
+        session_ref: session.session_ref,
+        current_terms_digest: session.current_terms_digest,
+        remote_revision: remoteRevision ?? session.updated_at,
+        status: session.status,
+    };
+}
+/** HandoffPackage 的紧凑身份摘要（审批面确认的对象）。 */
+export function digestHandoffPackage(pkg) {
+    return contentDigest({
+        agreement_id: pkg.agreement_id,
+        negotiation_id: pkg.negotiation_id,
+        accepted_offer_id: pkg.accepted_offer_id,
+        terms_digest: pkg.terms_digest,
+        package_version: pkg.package_version,
+        capability_version: pkg.capability_version,
+    });
+}
+/** 缺省审批窗口：对齐 createPaymentAuthorization 的授权 TTL（30 分钟）。 */
+export const OPERATOR_APPROVAL_TTL_MS = 30 * 60 * 1000;
+const NOT_CONFIRMED_REASON = "operator approval required: no confirmed approval for this session/terms (explicit user confirmation is mandatory; Kiwi never auto-authorizes)";
+function isUsableSourceStatus(status) {
+    return status === "approved" || status === "executed";
+}
+/**
+ * 把 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 class OperatorApprovalAuthorizationProvider {
+    records = new Map();
+    now;
+    options;
+    journalPath;
+    constructor(options = {}) {
+        this.now = options.now ?? (() => new Date().toISOString());
+        this.options = options;
+        if (options.persistDir !== undefined) {
+            mkdirSync(options.persistDir, { recursive: true, mode: 0o700 });
+            chmodSync(options.persistDir, 0o700);
+            this.journalPath = path.join(options.persistDir, "operator-approvals.jsonl");
+            this.replayJournal();
+        }
+    }
+    /** 从 JSONL 重放审批事件（同 approval_id 后事件胜出；撕裂行容忍跳过）。 */
+    replayJournal() {
+        if (this.journalPath === undefined || !existsSync(this.journalPath))
+            return;
+        const raw = readFileSync(this.journalPath, "utf-8");
+        for (const line of raw.split("\n")) {
+            if (line.length === 0)
+                continue;
+            try {
+                const event = JSON.parse(line);
+                if (event.type === "record" && event.approval?.approval_id !== undefined) {
+                    this.records.set(event.approval.approval_id, event.approval);
+                }
+                else if (event.type === "revoke" && typeof event.approval_id === "string") {
+                    const existing = this.records.get(event.approval_id);
+                    if (existing !== undefined) {
+                        this.records.set(event.approval_id, { ...existing, status: "revoked" });
+                    }
+                }
+            }
+            catch {
+                // 撕裂行跳过（审计由事件流本身承载；审批重放容忍最后一行撕裂）。
+            }
+        }
+    }
+    /** 追加一条审批事件（单行 append，原子）。 */
+    journalAppend(event) {
+        if (this.journalPath === undefined)
+            return;
+        appendFileSync(this.journalPath, `${JSON.stringify(event)}\n`, { mode: 0o600 });
+    }
+    // -- 审批证据写入（审批面） ------------------------------------------------
+    /** 记录一次显式确认。返回固化后的只读审批记录。 */
+    recordApproval(input) {
+        const now = this.now();
+        const confirmedAt = input.confirmed_at ?? now;
+        requireIsoTimestamp(confirmedAt, "confirmed_at");
+        const ttlMs = input.ttl_ms ?? OPERATOR_APPROVAL_TTL_MS;
+        if (!Number.isFinite(ttlMs) || ttlMs <= 0) {
+            throw new HandoffError("invalid_authorization", "ttl_ms must be a positive number", "ttl_ms");
+        }
+        const expiresAt = new Date(Date.parse(confirmedAt) + ttlMs).toISOString();
+        requireIsoTimestamp(expiresAt, "expires_at");
+        const approval = {
+            approval_id: validateIdentifier(input.approval_id, "approval_id"),
+            session_ref: validateIdentifier(input.session.session_ref, "session_ref"),
+            terms_digest: requireDigest(input.session.current_terms_digest, "terms_digest"),
+            package_digest: digestHandoffPackage(input.package),
+            candidate_digest: requireDigest(input.candidate_digest, "candidate_digest"),
+            remote_revision: requireNonEmptyString(input.session.remote_revision, "remote_revision"),
+            policy_version: requireNonEmptyString(input.policy_version, "policy_version"),
+            status: "approved",
+            confirmed_at: confirmedAt,
+            expires_at: expiresAt,
+            recorded_at: now,
+        };
+        this.records.set(approval.approval_id, approval);
+        this.journalAppend({ type: "record", approval });
+        return approval;
+    }
+    /** 显式撤销一条审批（对齐 WriteApprovalCandidate.reject/supersede）。 */
+    revokeApproval(approvalId) {
+        const existing = this.records.get(approvalId);
+        if (existing === undefined) {
+            throw new HandoffError("invalid_authorization", `no recorded approval ${approvalId}`);
+        }
+        const revoked = { ...existing, status: "revoked" };
+        this.records.set(approvalId, revoked);
+        this.journalAppend({ type: "revoke", approval_id: approvalId });
+        return revoked;
+    }
+    /** 只读取回一条审批记录。 */
+    getApproval(approvalId) {
+        return this.records.get(approvalId);
+    }
+    /** 当前审批记录数量（诊断用）。 */
+    get approvalCount() {
+        return this.records.size;
+    }
+    // -- AuthorizationProvider -------------------------------------------------
+    createIntentMandate(input) {
+        const approval = this.findUsableApproval(input.session_ref, input.terms_digest);
+        if (approval === undefined) {
+            return { status: "requires_user", reason: NOT_CONFIRMED_REASON };
+        }
+        return { status: "ok", intent_mandate: approval.approval_id };
+    }
+    verifyIntentMandate(intent_mandate, input) {
+        const approval = this.records.get(intent_mandate);
+        if (approval === undefined) {
+            return { verified: false, reason: `unknown approval: ${intent_mandate}` };
+        }
+        const failure = this.invalidReason(approval, input.session_ref, input.terms_digest);
+        if (failure !== undefined)
+            return { verified: false, reason: failure };
+        return { verified: true };
+    }
+    authorizeCheckout(input) {
+        const approval = this.records.get(input.intent_mandate);
+        if (approval === undefined) {
+            return { status: "fail_closed", reason: `unknown approval: ${input.intent_mandate}` };
+        }
+        const failure = this.invalidReason(approval, input.session_ref, input.terms_digest);
+        if (failure !== undefined) {
+            return { status: "fail_closed", reason: failure };
+        }
+        // 调用方传入的证据必须引用这条已确认的 operator 审批（防挪用它人证据）。
+        if (input.evidence.kind !== "manual" || input.evidence.reference !== approval.approval_id) {
+            return {
+                status: "fail_closed",
+                reason: "evidence does not reference the recorded operator approval",
+            };
+        }
+        const approvedAt = this.now();
+        // 数值比较（非字符串）：跨时区偏移的 confirmed_at 字符串比较可 fail-open。
+        const confirmedMs = Date.parse(approval.confirmed_at);
+        const approvedMs = Date.parse(approvedAt);
+        if (!Number.isFinite(confirmedMs) || !Number.isFinite(approvedMs) || confirmedMs > approvedMs) {
+            return {
+                status: "fail_closed",
+                reason: "confirmed_at MUST NOT be after approved_at",
+            };
+        }
+        const authorization = createPaymentAuthorization({
+            authorization_id: newAuthorizationId(),
+            session_ref: approval.session_ref,
+            terms_digest: approval.terms_digest,
+            intent_mandate: approval.approval_id,
+            evidence: createUserConfirmationEvidence({ kind: "manual", reference: approval.approval_id, confirmed_at: approval.confirmed_at }, this.now),
+            approved_at: approvedAt,
+            expires_at: approval.expires_at,
+        }, this.now);
+        return { status: "ok", authorization };
+    }
+    // -- 内部辅助 ---------------------------------------------------------------
+    findUsableApproval(sessionRef, termsDigest) {
+        for (const approval of this.records.values()) {
+            if (approval.session_ref !== sessionRef)
+                continue;
+            if (approval.terms_digest !== termsDigest)
+                continue;
+            if (this.invalidReason(approval, sessionRef, termsDigest) === undefined)
+                return approval;
+        }
+        return undefined;
+    }
+    /** 返回审批不可用的原因；可用时返回 undefined。判定顺序固定，便于审计。 */
+    invalidReason(approval, sessionRef, termsDigest) {
+        if (approval.status !== "approved")
+            return "approval revoked";
+        if (approval.session_ref !== sessionRef) {
+            return "approval bound to a different session_ref (stale)";
+        }
+        if (approval.terms_digest !== termsDigest) {
+            return "approval bound to different terms_digest (stale)";
+        }
+        const nowMs = Date.parse(this.now());
+        const expiresMs = Date.parse(approval.expires_at);
+        if (!Number.isFinite(nowMs) || !Number.isFinite(expiresMs) || nowMs > expiresMs) {
+            return "approval expired (stale)";
+        }
+        if (this.options.currentRevision !== undefined) {
+            const current = this.options.currentRevision(sessionRef);
+            if (current !== undefined && current !== approval.remote_revision) {
+                return "remote revision changed; approval stale";
+            }
+        }
+        if (this.options.statusSource !== undefined) {
+            const state = this.options.statusSource.getApprovalState(approval.approval_id);
+            if (state === undefined)
+                return "underlying candidate unknown; approval not usable";
+            if (!isUsableSourceStatus(state.status)) {
+                return `underlying candidate status ${state.status}; approval not usable`;
+            }
+        }
+        return undefined;
+    }
+}
+/** 从审批记录构造 UserConfirmationEvidence（供上层在调用 authorizeCheckout 前展示）。 */
+export function operatorConfirmationEvidence(approval, now = () => new Date().toISOString()) {
+    return createUserConfirmationEvidence({ kind: "manual", reference: approval.approval_id, confirmed_at: approval.confirmed_at }, now);
+}
+//# sourceMappingURL=operator-approval.js.map

package/dist/handoff/operator-approval.js.map

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

package/dist/handoff/order-record.d.ts

@@ -0,0 +1,104 @@
+/**
+ * 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 { DatabaseSync } from "node:sqlite";
+/** 订单行项目（只读）。 */
+export interface OrderRecordLineItem {
+    readonly sku: string;
+    readonly quantity: number;
+    readonly unit_price?: Readonly<{
+        currency: string;
+        amount_minor: number;
+    }>;
+}
+/** Kiwi 保存的只读订单事实。全部字段 readonly —— 类型层面不可变。 */
+export interface OrderRecord {
+    /** merchant 侧订单 id（opaque）。 */
+    readonly order_id: string;
+    /** 订单详情页 URL（merchant 权威）。 */
+    readonly permalink_url: string;
+    readonly line_items: readonly OrderRecordLineItem[];
+    /** merchant 侧订单状态（如 confirmed / fulfilled；Kiwi 不解释，只保存）。 */
+    readonly status: string;
+    /** 该订单履约的商业 terms 摘要（溯源：与 agreement/session 一致）。 */
+    readonly terms_digest: string;
+    readonly currency?: string;
+    readonly total_minor?: number;
+    /** 溯源：产生该订单的 agreement。 */
+    readonly agreement_id: string;
+    /** 溯源：产生该订单的 negotiation。 */
+    readonly negotiation_id: string;
+    /** 溯源：产生该订单的 checkout session。 */
+    readonly session_ref: string;
+    readonly recorded_at: string;
+}
+/** 摄取输入：completed checkout 的 order 字段 + 溯源上下文。 */
+export interface OrderRecordSource {
+    order_id: string;
+    permalink_url: string;
+    line_items: readonly OrderRecordLineItem[];
+    status: string;
+    terms_digest: string;
+    currency?: string;
+    total_minor?: number;
+    agreement_id: string;
+    negotiation_id: string;
+    session_ref: string;
+    /** 可注入记录时间（RFC 3339）；缺省 now。 */
+    recorded_at?: string;
+}
+/** 本地存储：目录 0700 / 数据库文件 0600（对齐 agent 数据布局）。 */
+export interface OrderRecordStoreOptions {
+    dbPath: string;
+    /** 可注入时钟（RFC 3339）；缺省 new Date().toISOString()。 */
+    now?: () => string;
+}
+/** 模块私有 symbol：让 ingestOrderRecord（模块函数）访问内部写入，外部不可达。 */
+declare const INGEST: unique symbol;
+/** 模块私有构造 token：外部无法构造 OrderRecordStore，只能经 openOrderRecordStore。 */
+declare const STORE_CTOR: unique symbol;
+/**
+ * 只读订单事实查询面。公开方法只有 get / list / findByTermsDigest /
+ * findByAgreement / count / close —— 没有任何写操作接口。
+ */
+export declare class OrderRecordStore {
+    private readonly db;
+    /**
+     * 构造需要模块私有的 token（`STORE_CTOR` 未导出），外部无法凭空构造；
+     * 只能经 openOrderRecordStore 创建。
+     */
+    constructor(db: DatabaseSync, _token: typeof STORE_CTOR);
+    /** 按 merchant order_id 查询。 */
+    get(orderId: string): OrderRecord | undefined;
+    /** 全部订单事实（按记录时间升序）。 */
+    list(): readonly OrderRecord[];
+    /** 按 terms_digest 溯源查询（审计「哪些订单履约同一组 terms」）。 */
+    findByTermsDigest(termsDigest: string): readonly OrderRecord[];
+    /** 按 agreement 溯源查询。 */
+    findByAgreement(agreementId: string): readonly OrderRecord[];
+    /** 已保存订单事实数量。 */
+    count(): number;
+    close(): void;
+    private rowToRecord;
+    [INGEST](source: OrderRecordSource, recordedAt: string): OrderRecord;
+}
+/** 打开（必要时创建）本地订单事实存储；目录 0700 / 文件 0600。 */
+export declare function openOrderRecordStore(options: OrderRecordStoreOptions): OrderRecordStore;
+/**
+ * 从 completed checkout 的 order 字段摄取一条只读订单事实。这是唯一的写入路径；
+ * 之后只能通过只读查询读取。
+ */
+export declare function ingestOrderRecord(store: OrderRecordStore, source: OrderRecordSource, now?: () => string): OrderRecord;
+export {};

package/dist/handoff/order-record.js

@@ -0,0 +1,235 @@
+/**
+ * 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 — OrderRecord（WP3，只读订单事实）。
+ *
+ * ⚠️ Kiwi 不是订单系统。订单由 merchant 侧创建（business 是 Merchant of Record）；
+ * Kiwi 只保存来自 completed checkout 的只读订单事实，用于审计与溯源。Kiwi 永不
+ * 实现取消订单 / 退款 / 修改订单路径；支付凭据永远不经过 Kiwi。
+ *
+ * 本模块：
+ *   - OrderRecord：类型层面不可变（全部 readonly，数组也只读）；
+ *   - OrderRecordStore：只暴露只读查询 + close，没有任何写操作接口
+ *     （ingestOrderRecord 是模块级函数，通过模块私有 symbol 访问内部写入）；
+ *   - ingestOrderRecord：从 completed checkout 的 order 字段摄取——order
+ *     id / permalink_url / line_items / status / terms_digest，并溯源到
+ *     产生它的 agreement / session。
+ */
+import { chmodSync, existsSync, mkdirSync } from "node:fs";
+import path from "node:path";
+import { DatabaseSync } from "node:sqlite";
+import { requireDigest, requireInteger, requireIsoTimestamp, requireNonEmptyString, requireObject, schemaError, } from "../negotiation/domain/common.js";
+import { validateIdentifier } from "../negotiation/domain/identifiers.js";
+// ---------------------------------------------------------------------------
+// 校验
+// ---------------------------------------------------------------------------
+/** 非负整数（金额/数量语义，与核心 validateMoney 一致——负数不可入审计账）。 */
+function requireNonNegativeInteger(value, path) {
+    const n = requireInteger(value, path);
+    if (n < 0) {
+        throw schemaError(path, `${path} must be a non-negative integer`);
+    }
+    return n;
+}
+function validateLineItem(value, index) {
+    const obj = requireObject(value, `line_items/${index}`);
+    const base = {
+        sku: requireNonEmptyString(obj.sku, `line_items/${index}/sku`),
+        quantity: requireNonNegativeInteger(obj.quantity, `line_items/${index}/quantity`),
+    };
+    if (obj.unit_price === undefined)
+        return base;
+    const price = requireObject(obj.unit_price, `line_items/${index}/unit_price`);
+    return {
+        ...base,
+        unit_price: {
+            currency: requireNonEmptyString(price.currency, `line_items/${index}/unit_price/currency`),
+            amount_minor: requireNonNegativeInteger(price.amount_minor, `line_items/${index}/unit_price/amount_minor`),
+        },
+    };
+}
+function validateSource(source) {
+    if (!/^https?:\/\/\S+$/.test(source.permalink_url)) {
+        throw schemaError("permalink_url", "permalink_url must be an http(s) URL");
+    }
+    return {
+        ...source,
+        order_id: validateIdentifier(source.order_id, "order_id"),
+        permalink_url: requireNonEmptyString(source.permalink_url, "permalink_url"),
+        line_items: source.line_items.map((item, i) => validateLineItem(item, i)),
+        status: requireNonEmptyString(source.status, "status"),
+        terms_digest: requireDigest(source.terms_digest, "terms_digest"),
+        ...(source.currency !== undefined
+            ? { currency: requireNonEmptyString(source.currency, "currency") }
+            : {}),
+        ...(source.total_minor !== undefined
+            ? { total_minor: requireNonNegativeInteger(source.total_minor, "total_minor") }
+            : {}),
+        agreement_id: validateIdentifier(source.agreement_id, "agreement_id"),
+        negotiation_id: validateIdentifier(source.negotiation_id, "negotiation_id"),
+        session_ref: validateIdentifier(source.session_ref, "session_ref"),
+        ...(source.recorded_at !== undefined
+            ? { recorded_at: requireIsoTimestamp(source.recorded_at, "recorded_at") }
+            : {}),
+    };
+}
+const ORDER_SCHEMA = `
+CREATE TABLE IF NOT EXISTS order_records (
+  order_id       TEXT PRIMARY KEY,
+  permalink_url  TEXT NOT NULL,
+  line_items     TEXT NOT NULL,
+  status         TEXT NOT NULL,
+  terms_digest   TEXT NOT NULL,
+  currency       TEXT,
+  total_minor    INTEGER,
+  agreement_id   TEXT NOT NULL,
+  negotiation_id TEXT NOT NULL,
+  session_ref    TEXT NOT NULL,
+  recorded_at    TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_order_terms_digest ON order_records(terms_digest);
+CREATE INDEX IF NOT EXISTS idx_order_agreement_id ON order_records(agreement_id);
+`;
+/** 模块私有 symbol：让 ingestOrderRecord（模块函数）访问内部写入，外部不可达。 */
+const INGEST = Symbol("order-record.ingest");
+/** 模块私有构造 token：外部无法构造 OrderRecordStore，只能经 openOrderRecordStore。 */
+const STORE_CTOR = Symbol("order-record.ctor");
+/**
+ * 只读订单事实查询面。公开方法只有 get / list / findByTermsDigest /
+ * findByAgreement / count / close —— 没有任何写操作接口。
+ */
+export class OrderRecordStore {
+    db;
+    /**
+     * 构造需要模块私有的 token（`STORE_CTOR` 未导出），外部无法凭空构造；
+     * 只能经 openOrderRecordStore 创建。
+     */
+    constructor(db, _token) {
+        this.db = db;
+    }
+    /** 按 merchant order_id 查询。 */
+    get(orderId) {
+        const row = this.db
+            .prepare("SELECT * FROM order_records WHERE order_id = ?")
+            .get(orderId);
+        return row === undefined ? undefined : this.rowToRecord(row);
+    }
+    /** 全部订单事实（按记录时间升序）。 */
+    list() {
+        const rows = this.db
+            .prepare("SELECT * FROM order_records ORDER BY recorded_at, order_id")
+            .all();
+        return rows.map((r) => this.rowToRecord(r));
+    }
+    /** 按 terms_digest 溯源查询（审计「哪些订单履约同一组 terms」）。 */
+    findByTermsDigest(termsDigest) {
+        const rows = this.db
+            .prepare("SELECT * FROM order_records WHERE terms_digest = ? ORDER BY recorded_at")
+            .all(termsDigest);
+        return rows.map((r) => this.rowToRecord(r));
+    }
+    /** 按 agreement 溯源查询。 */
+    findByAgreement(agreementId) {
+        const rows = this.db
+            .prepare("SELECT * FROM order_records WHERE agreement_id = ? ORDER BY recorded_at")
+            .all(agreementId);
+        return rows.map((r) => this.rowToRecord(r));
+    }
+    /** 已保存订单事实数量。 */
+    count() {
+        const row = this.db.prepare("SELECT COUNT(*) AS n FROM order_records").get();
+        return row.n;
+    }
+    close() {
+        this.db.close();
+    }
+    rowToRecord(row) {
+        return {
+            order_id: row.order_id,
+            permalink_url: row.permalink_url,
+            line_items: JSON.parse(row.line_items),
+            status: row.status,
+            terms_digest: row.terms_digest,
+            ...(row.currency !== null ? { currency: row.currency } : {}),
+            ...(row.total_minor !== null ? { total_minor: row.total_minor } : {}),
+            agreement_id: row.agreement_id,
+            negotiation_id: row.negotiation_id,
+            session_ref: row.session_ref,
+            recorded_at: row.recorded_at,
+        };
+    }
+    // 内部写入：只允许本模块的 ingestOrderRecord 调用（symbol 未导出）。
+    [INGEST](source, recordedAt) {
+        const record = {
+            order_id: source.order_id,
+            permalink_url: source.permalink_url,
+            line_items: source.line_items.map((item) => ({ ...item })),
+            status: source.status,
+            terms_digest: source.terms_digest,
+            ...(source.currency !== undefined ? { currency: source.currency } : {}),
+            ...(source.total_minor !== undefined ? { total_minor: source.total_minor } : {}),
+            agreement_id: source.agreement_id,
+            negotiation_id: source.negotiation_id,
+            session_ref: source.session_ref,
+            recorded_at: recordedAt,
+        };
+        this.db
+            .prepare(`INSERT INTO order_records
+           (order_id, permalink_url, line_items, status, terms_digest, currency,
+            total_minor, agreement_id, negotiation_id, session_ref, recorded_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+         ON CONFLICT(order_id) DO UPDATE SET
+           permalink_url=excluded.permalink_url,
+           line_items=excluded.line_items,
+           status=excluded.status,
+           terms_digest=excluded.terms_digest,
+           currency=excluded.currency,
+           total_minor=excluded.total_minor,
+           agreement_id=excluded.agreement_id,
+           negotiation_id=excluded.negotiation_id,
+           session_ref=excluded.session_ref,
+           recorded_at=excluded.recorded_at`)
+            .run(record.order_id, record.permalink_url, JSON.stringify(record.line_items), record.status, record.terms_digest, record.currency ?? null, record.total_minor ?? null, record.agreement_id, record.negotiation_id, record.session_ref, record.recorded_at);
+        return this.get(record.order_id);
+    }
+}
+/** 打开（必要时创建）本地订单事实存储；目录 0700 / 文件 0600。 */
+export function openOrderRecordStore(options) {
+    if (options.dbPath === ":memory:") {
+        const db = new DatabaseSync(":memory:");
+        db.exec(ORDER_SCHEMA);
+        return new OrderRecordStore(db, STORE_CTOR);
+    }
+    const dir = path.dirname(options.dbPath);
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    chmodSync(dir, 0o700);
+    const db = new DatabaseSync(options.dbPath);
+    if (existsSync(options.dbPath))
+        chmodSync(options.dbPath, 0o600);
+    db.exec(ORDER_SCHEMA);
+    return new OrderRecordStore(db, STORE_CTOR);
+}
+/**
+ * 从 completed checkout 的 order 字段摄取一条只读订单事实。这是唯一的写入路径；
+ * 之后只能通过只读查询读取。
+ */
+export function ingestOrderRecord(store, source, now = () => new Date().toISOString()) {
+    const validated = validateSource(source);
+    const recordedAt = validated.recorded_at ?? now();
+    requireIsoTimestamp(recordedAt, "recorded_at");
+    return store[INGEST](validated, recordedAt);
+}
+//# sourceMappingURL=order-record.js.map

package/dist/handoff/order-record.js.map

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