@harrylabsj/kiwi-merchant-cloud 0.12.0

package/app/merchant/service-control-executors.d.ts

@@ -0,0 +1,15 @@
+/** Owner-only committed execution for restoring service availability. */
+import type { MutableServiceState } from "../http/merchant-management/service-state.js";
+import type { CommandExecutor } from "../merchant-core/executor.js";
+export declare const SERVICE_CONTROL_TOOLS: {
+    readonly resume: "kiwi_workbench_service_resume";
+};
+export declare function createServiceControlExecutors(options: {
+    state: MutableServiceState;
+    readiness: () => Promise<{
+        ready: boolean;
+        checks: Record<string, {
+            ok: boolean;
+        }>;
+    }>;
+}): CommandExecutor[];

package/app/merchant/service-control-executors.js

@@ -0,0 +1,52 @@
+/** Owner-only committed execution for restoring service availability. */
+export const SERVICE_CONTROL_TOOLS = {
+    resume: "kiwi_workbench_service_resume",
+};
+export function createServiceControlExecutors(options) {
+    return [
+        {
+            tool: SERVICE_CONTROL_TOOLS.resume,
+            risk: "service_resume",
+            requiresCommittedDecision: true,
+            readPreconditions: async () => ({
+                state: options.state.state,
+                revision: options.state.serviceRevision,
+            }),
+            execute: async (args, _context, decision) => {
+                const expected = requirePositiveInteger(args["expected_revision"], "expected_revision");
+                if (expected !== options.state.serviceRevision) {
+                    throw new Error("service control revision changed");
+                }
+                const readiness = await options.readiness();
+                const failed = Object.entries(readiness.checks)
+                    .filter(([, value]) => !value.ok)
+                    .map(([name]) => name);
+                // committed decision 的 operationId 与状态迁移同一个 UPDATE 落库（对账反查用）
+                return options.state.resume(readiness.ready, failed, decision?.kind === "committed" ? decision.operationId : undefined);
+            },
+            /**
+             * 对账适配器：写后不确定时查**我们自己的**权威行——服务恢复是 kiwi 内部写，
+             * 没有下游服务可问。`resume_operation_id` 与状态迁移同一个 UPDATE 提交，
+             * 状态为 OPERATING 且引用等于本次 operationId 即成功。没有这个适配器时
+             * `MerchantCommandLog.reconcile` 会返回 unknown +「no downstream operation
+             * query adapter」，把一次可自动判定的对账变成人工升级。
+             */
+            queryOutcome: async (_args, _ctx, decision) => options.state.state === "OPERATING" &&
+                options.state.lastResumeOperationId === decision.operationId
+                ? { status: "succeeded" }
+                : { status: "unknown", error: "service resume receipt does not match" },
+            verifyAfter: async () => {
+                if (options.state.state !== "OPERATING") {
+                    throw new Error("service resume readback failed");
+                }
+            },
+        },
+    ];
+}
+function requirePositiveInteger(value, field) {
+    if (!Number.isSafeInteger(value) || Number(value) < 1) {
+        throw new Error(`${field} must be a positive integer`);
+    }
+    return Number(value);
+}
+//# sourceMappingURL=service-control-executors.js.map

package/app/merchant/service-control-executors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"service-control-executors.js","sourceRoot":"","sources":["../../src/merchant/service-control-executors.ts"],"names":[],"mappings":"AAAA,yEAAyE;AAKzE,MAAM,CAAC,MAAM,qBAAqB,GAAG;IACnC,MAAM,EAAE,+BAA+B;CAC/B,CAAC;AAEX,MAAM,UAAU,6BAA6B,CAAC,OAG7C;IACC,OAAO;QACL;YACE,IAAI,EAAE,qBAAqB,CAAC,MAAM;YAClC,IAAI,EAAE,gBAAgB;YACtB,yBAAyB,EAAE,IAAI;YAC/B,iBAAiB,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC;gBAC9B,KAAK,EAAE,OAAO,CAAC,KAAK,CAAC,KAAK;gBAC1B,QAAQ,EAAE,OAAO,CAAC,KAAK,CAAC,eAAe;aACxC,CAAC;YACF,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,EAAE;gBAC1C,MAAM,QAAQ,GAAG,sBAAsB,CAAC,IAAI,CAAC,mBAAmB,CAAC,EAAE,mBAAmB,CAAC,CAAC;gBACxF,IAAI,QAAQ,KAAK,OAAO,CAAC,KAAK,CAAC,eAAe,EAAE,CAAC;oBAC/C,MAAM,IAAI,KAAK,CAAC,kCAAkC,CAAC,CAAC;gBACtD,CAAC;gBACD,MAAM,SAAS,GAAG,MAAM,OAAO,CAAC,SAAS,EAAE,CAAC;gBAC5C,MAAM,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,MAAM,CAAC;qBAC5C,MAAM,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC;qBAChC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC;gBACzB,6DAA6D;gBAC7D,OAAO,OAAO,CAAC,KAAK,CAAC,MAAM,CACzB,SAAS,CAAC,KAAK,EACf,MAAM,EACN,QAAQ,EAAE,IAAI,KAAK,WAAW,CAAC,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC,CAAC,SAAS,CAClE,CAAC;YACJ,CAAC;YACD;;;;;;eAMG;YACH,YAAY,EAAE,KAAK,EACjB,KAAK,EACL,IAAI,EACJ,QAAiC,EACwC,EAAE,CAC3E,OAAO,CAAC,KAAK,CAAC,KAAK,KAAK,WAAW;gBACnC,OAAO,CAAC,KAAK,CAAC,qBAAqB,KAAK,QAAQ,CAAC,WAAW;gBAC1D,CAAC,CAAC,EAAE,MAAM,EAAE,WAAW,EAAE;gBACzB,CAAC,CAAC,EAAE,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,uCAAuC,EAAE;YAC3E,WAAW,EAAE,KAAK,IAAI,EAAE;gBACtB,IAAI,OAAO,CAAC,KAAK,CAAC,KAAK,KAAK,WAAW,EAAE,CAAC;oBACxC,MAAM,IAAI,KAAK,CAAC,gCAAgC,CAAC,CAAC;gBACpD,CAAC;YACH,CAAC;SACF;KACF,CAAC;AACJ,CAAC;AAED,SAAS,sBAAsB,CAAC,KAAc,EAAE,KAAa;IAC3D,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,IAAI,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;QACtD,MAAM,IAAI,KAAK,CAAC,GAAG,KAAK,6BAA6B,CAAC,CAAC;IACzD,CAAC;IACD,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;AACvB,CAAC"}

package/app/merchant/stats-store.d.ts

@@ -0,0 +1,86 @@
+/**
+ * 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";
+/** 一次买家触达事实（来自入站 KNP envelope，已经过了 schema/digest/幂等校验）。 */
+export interface BuyerContactEvent {
+    /** envelope.message_id（幂等主键）。 */
+    message_id: string;
+    /** 传输层认证身份（signature 模式 = 真实买家；其余模式可能坍缩）。 */
+    buyer_identity: string;
+    negotiation_id: string;
+    exchange_id: string;
+    /** envelope.action（inquiry/rfq/offer/counter_offer/...）。 */
+    action: string;
+    /** 从 payload 提取的 SKU（inquiry 等无 SKU 动作为空数组）。 */
+    skus: string[];
+    /** envelope.created_at（RFC 3339）。 */
+    occurred_at: string;
+}
+/** 窗口总量。 */
+export interface ContactTotals {
+    distinct_buyers: number;
+    contact_events: number;
+    negotiations: number;
+}
+/** 单日聚合（day 为 UTC `YYYY-MM-DD`）。 */
+export interface DailyBucket {
+    day: string;
+    distinct_buyers: number;
+    contact_events: number;
+    negotiations: number;
+}
+/** 单日买家身份集合的去重行，用于跨日粒度聚合。 */
+export interface DailyBuyerIdentity {
+    day: string;
+    buyer_identity: string;
+}
+/** 单 SKU 聚合。 */
+export interface SkuStat {
+    sku: string;
+    contact_events: number;
+    distinct_buyers: number;
+    negotiations: number;
+}
+/** 本地存储：目录 0700 / 数据库文件 0600（对齐 agent 数据布局）。 */
+export interface MerchantStatsStoreOptions {
+    dbPath: string;
+}
+/** 商家买家触达统计存储。写入面只有 recordBuyerContact；其余为聚合查询。 */
+export declare class MerchantStatsStore {
+    private readonly db;
+    constructor(db: DatabaseSync);
+    /**
+     * 记录一次买家触达（INSERT OR IGNORE：同 message_id 幂等去重——协议层已
+     * 保证恰好一次调用，这里是崩溃/重试窗口的兜底）。
+     */
+    recordBuyerContact(event: BuyerContactEvent): void;
+    /** 窗口总量（sinceDay 含当天，UTC `YYYY-MM-DD`）。 */
+    totalsSince(sinceDay: string): ContactTotals;
+    /**
+     * 有界窗口总量（sinceDay 含、untilDayExclusive 不含；运营报告的周期与
+     * 对比周期用）。跨日的 distinct 计数在 SQL 内一次完成，不做日桶累加。
+     */
+    windowTotals(sinceDay: string, untilDayExclusive: string): ContactTotals;
+    /** 按日聚合（只返回有数据的天；零填充由调用方做）。 */
+    dailySince(sinceDay: string): DailyBucket[];
+    /** 按日返回原始身份去重行，避免周/月把同一买家跨日重复相加。 */
+    dailyBuyerIdentitiesSince(sinceDay: string): DailyBuyerIdentity[];
+    /** SKU 热度榜（按触达事件数降序，sku 升序兜底，截断 limit）。 */
+    topSkus(sinceDay: string, limit: number): SkuStat[];
+    close(): void;
+}
+/** 打开（必要时创建）本地统计存储；目录 0700 / 文件 0600。 */
+export declare function openMerchantStatsStore(options: MerchantStatsStoreOptions): MerchantStatsStore;

package/app/merchant/stats-store.js

@@ -0,0 +1,176 @@
+/**
+ * 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.
+ */
+/**
+ * 商家侧运营统计（merchant stats）——本地买家触达事实。
+ *
+ * 数据来源唯一：merchant 自己的 A2A 入站管线（InboundPipeline）在
+ * `message_received` 落账成功后写入一条 buyer_contact_events。数据只落
+ * 商家本地 DB（<dataDir>/a2a/stats.sqlite），永不上报任何远端。
+ *
+ * 语义：
+ *   - 主键 message_id（INSERT OR IGNORE）：与协议幂等（§20）对齐，
+ *     同一消息重放不重复计数；
+ *   - distinct_buyers 仅在 KIWI_A2A_AUTH=signature 下有真实去重语义——
+ *     loopback/none/bearer 模式下 buyer 身份坍缩（loopback 地址、
+ *     "anonymous"、静态 token 身份），CLI 输出附带 identity_note 说明；
+ *   - 天数一律 UTC（occurred_at ISO 串切前 10 位），与全仓时间处理一致。
+ */
+import { chmodSync, existsSync, mkdirSync } from "node:fs";
+import path from "node:path";
+import { DatabaseSync } from "node:sqlite";
+import { requireIsoTimestamp, requireNonEmptyString } from "../negotiation/domain/common.js";
+const STATS_SCHEMA = `
+CREATE TABLE IF NOT EXISTS buyer_contact_events (
+  message_id      TEXT PRIMARY KEY,
+  buyer_identity  TEXT NOT NULL,
+  negotiation_id  TEXT NOT NULL,
+  exchange_id     TEXT,
+  action          TEXT NOT NULL,
+  skus_json       TEXT NOT NULL DEFAULT '[]',
+  occurred_at     TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_buyer_contact_buyer ON buyer_contact_events(buyer_identity);
+CREATE INDEX IF NOT EXISTS idx_buyer_contact_time ON buyer_contact_events(occurred_at);
+`;
+/** 商家买家触达统计存储。写入面只有 recordBuyerContact；其余为聚合查询。 */
+export class MerchantStatsStore {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    /**
+     * 记录一次买家触达（INSERT OR IGNORE：同 message_id 幂等去重——协议层已
+     * 保证恰好一次调用，这里是崩溃/重试窗口的兜底）。
+     */
+    recordBuyerContact(event) {
+        const messageId = requireNonEmptyString(event.message_id, "message_id");
+        const buyerIdentity = requireNonEmptyString(event.buyer_identity, "buyer_identity");
+        const negotiationId = requireNonEmptyString(event.negotiation_id, "negotiation_id");
+        const action = requireNonEmptyString(event.action, "action");
+        const occurredAt = requireIsoTimestamp(event.occurred_at, "occurred_at");
+        // SKU 去重（单条事件内同 SKU 重复出现只计一次触达）。
+        const skus = [...new Set(event.skus.filter((s) => typeof s === "string" && s !== ""))];
+        this.db
+            .prepare(`INSERT OR IGNORE INTO buyer_contact_events
+           (message_id, buyer_identity, negotiation_id, exchange_id, action, skus_json, occurred_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?)`)
+            .run(messageId, buyerIdentity, negotiationId, event.exchange_id === "" ? null : event.exchange_id, action, JSON.stringify(skus), occurredAt);
+    }
+    /** 窗口总量（sinceDay 含当天，UTC `YYYY-MM-DD`）。 */
+    totalsSince(sinceDay) {
+        const row = this.db
+            .prepare(`SELECT COUNT(DISTINCT buyer_identity) AS distinct_buyers,
+                COUNT(*) AS contact_events,
+                COUNT(DISTINCT negotiation_id) AS negotiations
+         FROM buyer_contact_events
+         WHERE substr(occurred_at, 1, 10) >= ?`)
+            .get(sinceDay);
+        return {
+            distinct_buyers: row.distinct_buyers,
+            contact_events: row.contact_events,
+            negotiations: row.negotiations,
+        };
+    }
+    /**
+     * 有界窗口总量（sinceDay 含、untilDayExclusive 不含；运营报告的周期与
+     * 对比周期用）。跨日的 distinct 计数在 SQL 内一次完成，不做日桶累加。
+     */
+    windowTotals(sinceDay, untilDayExclusive) {
+        const row = this.db
+            .prepare(`SELECT COUNT(DISTINCT buyer_identity) AS distinct_buyers,
+                COUNT(*) AS contact_events,
+                COUNT(DISTINCT negotiation_id) AS negotiations
+         FROM buyer_contact_events
+         WHERE substr(occurred_at, 1, 10) >= ? AND substr(occurred_at, 1, 10) < ?`)
+            .get(sinceDay, untilDayExclusive);
+        return {
+            distinct_buyers: row.distinct_buyers,
+            contact_events: row.contact_events,
+            negotiations: row.negotiations,
+        };
+    }
+    /** 按日聚合（只返回有数据的天；零填充由调用方做）。 */
+    dailySince(sinceDay) {
+        const rows = this.db
+            .prepare(`SELECT substr(occurred_at, 1, 10) AS day,
+                COUNT(DISTINCT buyer_identity) AS distinct_buyers,
+                COUNT(*) AS contact_events,
+                COUNT(DISTINCT negotiation_id) AS negotiations
+         FROM buyer_contact_events
+         WHERE substr(occurred_at, 1, 10) >= ?
+         GROUP BY day
+         ORDER BY day`)
+            .all(sinceDay);
+        return rows.map((r) => ({
+            day: r.day,
+            distinct_buyers: r.distinct_buyers,
+            contact_events: r.contact_events,
+            negotiations: r.negotiations,
+        }));
+    }
+    /** 按日返回原始身份去重行，避免周/月把同一买家跨日重复相加。 */
+    dailyBuyerIdentitiesSince(sinceDay) {
+        const rows = this.db
+            .prepare(`SELECT substr(occurred_at, 1, 10) AS day, buyer_identity
+         FROM buyer_contact_events
+         WHERE substr(occurred_at, 1, 10) >= ?
+         GROUP BY day, buyer_identity
+         ORDER BY day, buyer_identity`)
+            .all(sinceDay);
+        return rows.map((row) => ({ day: row.day, buyer_identity: row.buyer_identity }));
+    }
+    /** SKU 热度榜（按触达事件数降序，sku 升序兜底，截断 limit）。 */
+    topSkus(sinceDay, limit) {
+        const rows = this.db
+            .prepare(`SELECT je.value AS sku,
+                COUNT(*) AS contact_events,
+                COUNT(DISTINCT buyer_identity) AS distinct_buyers,
+                COUNT(DISTINCT negotiation_id) AS negotiations
+         FROM buyer_contact_events,
+              json_each(buyer_contact_events.skus_json) AS je
+         WHERE substr(occurred_at, 1, 10) >= ?
+         GROUP BY je.value
+         ORDER BY contact_events DESC, sku ASC
+         LIMIT ?`)
+            .all(sinceDay, limit);
+        return rows.map((r) => ({
+            sku: r.sku,
+            contact_events: r.contact_events,
+            distinct_buyers: r.distinct_buyers,
+            negotiations: r.negotiations,
+        }));
+    }
+    close() {
+        this.db.close();
+    }
+}
+/** 打开（必要时创建）本地统计存储；目录 0700 / 文件 0600。 */
+export function openMerchantStatsStore(options) {
+    if (options.dbPath === ":memory:") {
+        const db = new DatabaseSync(":memory:");
+        db.exec(STATS_SCHEMA);
+        return new MerchantStatsStore(db);
+    }
+    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(STATS_SCHEMA);
+    return new MerchantStatsStore(db);
+}
+//# sourceMappingURL=stats-store.js.map

package/app/merchant/stats-store.js.map

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

package/app/merchant/ucp-profile.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.
+ */
+/**
+ * Merchant UCP Profile 生成（战略 v2.5 §7.1 Protocol Publishing / §7.8 UCP-ready）。
+ *
+ * 商家在 `/.well-known/ucp` 发布 UCP Profile：声明 Catalog service（指向真实
+ * 商品 endpoint）与 KNP 磋商 capability。Kiwi 的 Buyer 端（UcpProfileResolver）
+ * 通过该 profile 发现商家能力；商品 truth 仍在 merchant/marketplace，不落 Kiwi。
+ *
+ * UCP 命名不变量（基线 §8.3）：service 名 = {reverse-domain}.{service}，
+ * reverse-domain 反转即 namespace authority host；spec/schema URL origin MUST
+ * 与 namespace authority 一致。
+ */
+import type { UcpProfile } from "../discovery/ucp/types.js";
+export declare const UCP_VERSION = "2026-04-08";
+export interface MerchantUcpProfileOptions {
+    /** 商家规范域名（如 xihu-digital.example.com）——决定 namespace authority。 */
+    domain: string;
+    /** 商家 id（marketplace 商家 id，如 merchant-hz-xihu）。 */
+    merchantId: string;
+    /** 真实商品 catalog endpoint（marketplace search，如 http://127.0.0.1:8765/search/products）。 */
+    catalogEndpoint: string;
+}
+/** 由域名派生 reverse-domain（UCP §8.3：反转 authority host 的 label）。 */
+export declare function reverseDomain(domain: string): string;
+export declare function buildMerchantUcpProfile(options: MerchantUcpProfileOptions): UcpProfile;

package/app/merchant/ucp-profile.js

@@ -0,0 +1,55 @@
+/**
+ * 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 const UCP_VERSION = "2026-04-08";
+/** 由域名派生 reverse-domain（UCP §8.3：反转 authority host 的 label）。 */
+export function reverseDomain(domain) {
+    return domain.split(".").reverse().join(".");
+}
+export function buildMerchantUcpProfile(options) {
+    const authority = options.domain;
+    const rd = reverseDomain(options.domain);
+    const catalogService = `${rd}.catalog`;
+    const negotiationCapability = "com.harrylabsj.kiwi.shopping.negotiation";
+    return {
+        ucp: {
+            version: UCP_VERSION,
+            services: {
+                [catalogService]: [
+                    {
+                        version: UCP_VERSION,
+                        spec: `https://${authority}/.well-known/ucp#catalog`,
+                        transport: "rest",
+                        endpoint: options.catalogEndpoint,
+                        schema: `https://${authority}/schemas/catalog.json`,
+                    },
+                ],
+            },
+            capabilities: {
+                [negotiationCapability]: [
+                    {
+                        version: "1.0",
+                        spec: "https://kiwi.harrylabsj.com/spec/negotiation/1.0",
+                        schema: "https://kiwi.harrylabsj.com/schemas/negotiation/1.0/schema.json",
+                    },
+                ],
+            },
+        },
+        signing_keys: [],
+        // 商家元信息（非 UCP 标准字段，forward-compat）。
+        merchant_id: options.merchantId,
+    };
+}
+//# sourceMappingURL=ucp-profile.js.map

package/app/merchant/ucp-profile.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ucp-profile.js","sourceRoot":"","sources":["../../src/merchant/ucp-profile.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAgBH,MAAM,CAAC,MAAM,WAAW,GAAG,YAAY,CAAC;AAWxC,gEAAgE;AAChE,MAAM,UAAU,aAAa,CAAC,MAAc;IAC1C,OAAO,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC/C,CAAC;AAED,MAAM,UAAU,uBAAuB,CAAC,OAAkC;IACxE,MAAM,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC;IACjC,MAAM,EAAE,GAAG,aAAa,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IACzC,MAAM,cAAc,GAAG,GAAG,EAAE,UAAU,CAAC;IACvC,MAAM,qBAAqB,GAAG,0CAA0C,CAAC;IAEzE,OAAO;QACL,GAAG,EAAE;YACH,OAAO,EAAE,WAAW;YACpB,QAAQ,EAAE;gBACR,CAAC,cAAc,CAAC,EAAE;oBAChB;wBACE,OAAO,EAAE,WAAW;wBACpB,IAAI,EAAE,WAAW,SAAS,0BAA0B;wBACpD,SAAS,EAAE,MAAM;wBACjB,QAAQ,EAAE,OAAO,CAAC,eAAe;wBACjC,MAAM,EAAE,WAAW,SAAS,uBAAuB;qBACpD;iBACF;aACF;YACD,YAAY,EAAE;gBACZ,CAAC,qBAAqB,CAAC,EAAE;oBACvB;wBACE,OAAO,EAAE,KAAK;wBACd,IAAI,EAAE,kDAAkD;wBACxD,MAAM,EAAE,iEAAiE;qBAC1E;iBACF;aACF;SACF;QACD,YAAY,EAAE,EAAE;QAChB,oCAAoC;QACpC,WAAW,EAAE,OAAO,CAAC,UAAU;KAChC,CAAC;AACJ,CAAC"}

package/app/merchant/workbench-service.d.ts

@@ -0,0 +1,190 @@
+/**
+ * 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.
+ */
+/**
+ * Merchant Workbench Facade（WorkBuddy Buddy 应用开发计划 阶段一）。
+ *
+ * 从 src/agent/merchant/merchant-tools.ts 抽取的**不依赖 Pi Agent Core** 的
+ * 业务服务层，供现有 Pi 工具与后续 MCP Server（阶段二）共同复用。分层对齐
+ * buyer 侧先例（src/buyer-core/service.ts 承载业务、src/mcp 只放协议层）：
+ * 本服务放 src/merchant/，src/mcp 不被 src/agent 反向依赖。
+ *
+ * 横切约定：
+ *   - 租户校验：服务持有 expectedMerchantId（= profile.owner_id），入参带
+ *     merchant_id 必须匹配，否则 validation 错误；
+ *   - 白名单/脱敏：所有对外返回显式 pick 公开字段；私有值（底价/成本/利润/
+ *     凭据）只留在 profile.merchant_policy 与 Vault，绝不进入返回值；
+ *   - 统一错误映射：MerchantClientError / CommerceError / 底层异常统一映射为
+ *     MerchantWorkbenchError（auth / not_found / validation / unavailable）；
+ *   - fail-closed：商品源故障、未配置 ledger / intelligence 一律抛错，绝不
+ *     回退演示数据；
+ *   - 模型面关注点（fenceModelPayload、中文文案）留在工具层，不进本服务。
+ */
+import type { AgentProfile } from "../config/profile.js";
+import type { CommerceDataSource } from "../commerce/data-source.js";
+import type { AgentMode } from "../agent/mode.js";
+import type { ApprovalExecutionResult, WriteApprovalCandidateStore } from "../agent/merchant/action-candidate.js";
+import type { InventorySnapshot, MerchantCatalogProduct, MerchantClient, MerchantProductPatch } from "../agent/merchant/types.js";
+import type { MerchantIntelligenceBackend } from "../agent/merchant/intelligence/backend.js";
+import type { MerchantBusinessSnapshot } from "../agent/merchant/intelligence/types.js";
+import type { WriteGateDeps, WriteGateResult } from "../agent/write-gate.js";
+/** Facade 统一错误（kind 为跨调用方语义不变量）。 */
+export declare class MerchantWorkbenchError extends Error {
+    readonly kind: "auth" | "not_found" | "validation" | "unavailable";
+    constructor(kind: MerchantWorkbenchError["kind"], message: string);
+}
+/** 商品公开字段白名单（无私有值；显式 pick，不透传整个对象）。
+ *  用 type alias 而非 interface：保留隐式索引签名，可直接作为写门 preconditions
+ *  （Record<string, unknown>）参与 content hash。 */
+export type PublicProductView = {
+    sku: string;
+    merchant_id: string;
+    title: string;
+    price: number;
+    /** 精确库存仅在持有商户凭据时存在；匿名读为 undefined，数据源路径为 null。 */
+    stock?: number | null;
+    paused: boolean;
+};
+/** Public precondition snapshot of a product (no private values). */
+export declare function publicProductView(product: MerchantCatalogProduct): PublicProductView;
+/** 解析商品变更 patch（等价于原 merchant-tools.parseChanges；静默忽略未知字段）。 */
+export declare function parseProductPatch(value: unknown): MerchantProductPatch;
+/** A2A 磋商结构化行（格式化留给调用方）。 */
+export interface A2aNegotiationRow {
+    negotiation_id: string;
+    /** 当前相位（无 state_transition 事件时为 "OPEN"）。 */
+    phase: string;
+    /** 最后一条 message_sent 的 action（无则为 ""）。 */
+    last_action: string;
+    sku: string;
+    quantity?: number;
+    price_minor?: number;
+    agreement: boolean;
+    /** 最近一条事件的落账时间（排序键）。 */
+    recorded_at: string;
+}
+/** 人工审核队列白名单行。 */
+export interface HumanReviewRow {
+    review_id: string | number;
+    conversation_id: string;
+    sku: string;
+    severity: string;
+    reason: string;
+}
+export interface DraftProductChangeInput {
+    sku: string;
+    changes: unknown;
+    reason?: string;
+    /** 可选租户标识；提供时必须等于本商家 owner_id。 */
+    merchant_id?: string;
+}
+export interface DraftProductChangeResult {
+    /** 写门结果；force_pending 下绝不自动执行（manual→advice_only，其余→pending_approval）。 */
+    outcome: WriteGateResult;
+    /** 生成候选时读取的当前商品公开快照。 */
+    product: PublicProductView;
+}
+export interface MerchantWorkbenchServiceDeps {
+    profile: AgentProfile;
+    merchantClient: MerchantClient;
+    /** 经营事实数据源；提供时目录列表优先走数据源（本地商品库 / ERP 适配器）。 */
+    dataSource?: CommerceDataSource;
+    approvals: WriteApprovalCandidateStore;
+    mode: () => AgentMode;
+    now: () => string;
+    /** Register /approve execution hooks for pending candidates. */
+    registerPending?: WriteGateDeps["registerPending"];
+    /** 商家 A2A 节点 ledger 目录；缺失时磋商记录方法 fail-closed 抛 unavailable。 */
+    a2aLedgerDir?: string;
+    /** 经营指标后端；缺失时 getAnalytics fail-closed 抛 unavailable（不返回演示数据）。 */
+    intelligence?: MerchantIntelligenceBackend;
+}
+/** MCP 工具层依赖的服务面（结构类型；merchant-core 包装层同样满足）。 */
+export type MerchantWorkbenchSurface = Pick<MerchantWorkbenchService, "listPublicProducts" | "getPublicProduct" | "getInventorySnapshot" | "listA2aNegotiations" | "listActiveConsultations" | "listHumanReviews" | "getAnalytics" | "draftProductChange">;
+export declare class MerchantWorkbenchService {
+    private readonly profile;
+    private readonly merchantClient;
+    private readonly dataSource?;
+    private readonly approvals;
+    private readonly mode;
+    private readonly now;
+    private readonly registerPending?;
+    private readonly a2aLedgerDir?;
+    private readonly intelligence?;
+    private readonly ownerId;
+    /**
+     * 本进程内的候选执行钩子（draft_product_change）。钩子是进程级的，但
+     * draft 候选的参数在 store 里、钩子可从参数确定性重建——因此本服务
+     * （MCP 进程）内也能批准并执行自己的候选（阶段四最小闭环）。
+     * 外部 registerPending（如 chat kernel）照常透传。
+     */
+    private readonly pendingHooks;
+    constructor(deps: MerchantWorkbenchServiceDeps);
+    /** 内部依赖只读访问（merchant-core 包装层/两轨适配用；不提供写路径）。 */
+    get merchantClientRef(): MerchantClient;
+    get ownerIdRef(): string;
+    /** 列出本商家目录商品（白名单）；dataSource 优先，否则公开搜索端点按 owner 过滤。 */
+    listPublicProducts(): Promise<{
+        items: PublicProductView[];
+        source: "data_source" | "merchant_client";
+    }>;
+    /** 按 SKU 读取一个商品（白名单）。审查 P2：非本商家的 SKU 按未找到处理
+     *  （工具语义是「本商家目录中的商品」，不校验会返回其他商家的公开商品）。 */
+    getPublicProduct(sku: string, merchantId?: string): Promise<PublicProductView>;
+    /** 读取一个商品的当前库存快照（含观察时间，不是永恒事实）。 */
+    getInventorySnapshot(sku: string): Promise<InventorySnapshot>;
+    /**
+     * 列出商家节点的 A2A 磋商记录（结构化行，按最近落账时间倒序）。
+     * limit 缺省 20，clamp 1..100。未配置 ledger 目录时 fail-closed 抛 unavailable。
+     */
+    listA2aNegotiations(limit?: unknown): Promise<{
+        total: number;
+        items: A2aNegotiationRow[];
+    }>;
+    getA2aNegotiation(negotiationId: string): Promise<A2aNegotiationRow>;
+    /** 只留**进行中**（非终态）的磋商。未配置 ledger 目录时 fail-closed 抛 unavailable。 */
+    listActiveConsultations(): Promise<A2aNegotiationRow[]>;
+    /** 商家人工处理队列（白名单：review_id / conversation_id / sku / severity / reason）。 */
+    listHumanReviews(): Promise<HumanReviewRow[]>;
+    /** 经营摘要（intelligence）；未配置时 fail-closed 抛 unavailable，不返回演示数据。 */
+    getAnalytics(period?: string): Promise<MerchantBusinessSnapshot>;
+    /**
+     * 商品变更草稿：校验 changes、确认商品存在，经 approvals + routeWriteCandidate
+     * 以 force_pending 生成审批候选（任何模式都不自动执行）。只返回候选元数据
+     * 与当前商品公开快照。
+     */
+    draftProductChange(input: DraftProductChangeInput): Promise<DraftProductChangeResult>;
+    /** draft 候选的执行钩子（execute 只执行库内已批准参数；preconditions 重读重哈希）。 */
+    private buildDraftHooks;
+    /**
+     * 启动恢复（MCP 进程重启后）：为 store 里本服务可执行工具
+     * （draft_product_change）的 pending 候选从库存参数重建执行钩子，返回恢复
+     * 条数。其他工具的候选不处理（由调用方按 expireForRecovery 语义失效）。
+     */
+    recoverPendingDrafts(): number;
+    /**
+     * 批准并执行一个 pending 候选（语义对齐 chat kernel 的 /approve：重读前置
+     * 状态并重哈希，stale/expired 的候选 supersede、绝不执行；只执行库内已
+     * 批准参数）。候选没有本进程执行钩子时按恢复语义失效（fail-closed）。
+     * 幂等：重复批准不会重复执行（executed 后返回 not_approvable）。
+     */
+    approveCandidate(candidateId: string): Promise<ApprovalExecutionResult>;
+    private readonly approveInFlight;
+    private doApproveCandidate;
+    /** 租户校验：入参 merchant_id 提供时必须等于本商家 owner_id。 */
+    private assertMerchantId;
+    /** 扫 A2A ledger 生成结构化行（按最近落账时间倒序）；activeOnly 时剔除非终态以外的记录。 */
+    private scanLedger;
+}