@harrylabsj/kiwi 0.7.9 → 0.7.11

package/contracts/commerce-intent/1.0/schema.json

@@ -0,0 +1,124 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://kiwi.harrylabsj.com/schemas/commerce-intent/1.0/schema.json",
+  "title": "Kiwi CommerceIntent v0.1",
+  "description": "统一所有宿主 Agent 的 Sourcing 委托（战略 v2.5 §5.2）。CommerceIntent 是 Northbound 稳定契约，表达 sourcing intent 而非 UCP transaction payload。宿主（Hermes/Kimi/Codex/OpenClaw/企业 Agent）把自然语言需求映射为同一结构；Kiwi 再把商品检索/交易部分转换为 UCP 调用，把询报价与磋商部分转换为 KNP 流程。context_projection 承载最小商业披露（§5.4）：只投影完成当前交易必需的字段；Principal Memory、原始对话历史与宿主私有工具不得默认进入远程上下文。",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "intent_id",
+    "intent_type",
+    "items"
+  ],
+  "properties": {
+    "intent_id": {
+      "$ref": "#/$defs/identifier"
+    },
+    "intent_type": {
+      "type": "string",
+      "enum": ["purchase", "procurement", "inquiry"]
+    },
+    "items": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "$ref": "#/$defs/intent_item" }
+    },
+    "constraints": {
+      "$ref": "#/$defs/constraints"
+    },
+    "preferences": {
+      "$ref": "#/$defs/preferences"
+    },
+    "context_projection": {
+      "$ref": "#/$defs/context_projection"
+    }
+  },
+  "$defs": {
+    "identifier": {
+      "description": "对端 opaque 标识符（同 KNP/1.0 §6）：非空、≤256、无首尾空白、无控制字符。",
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 256,
+      "pattern": "^\\S(.*\\S)?$"
+    },
+    "timestamp": {
+      "description": "RFC 3339 时间戳（同 KNP/1.0 §7.3）。",
+      "type": "string",
+      "format": "date-time"
+    },
+    "currency": {
+      "type": "string",
+      "pattern": "^[A-Z]{3}$"
+    },
+    "money": {
+      "description": "金额用最小单位整数（同 KNP/1.0 §7.1）。",
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["currency", "amount_minor"],
+      "properties": {
+        "currency": { "type": "string", "pattern": "^[A-Z]{3}$" },
+        "amount_minor": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "quantity": {
+      "description": "数量（同 KNP/1.0 §7.2）：value 为正数。",
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["value", "unit"],
+      "properties": {
+        "value": { "type": "number", "exclusiveMinimum": 0 },
+        "unit": { "type": "string", "minLength": 1 }
+      }
+    },
+    "intent_item": {
+      "description": "单个采购条目：query / sku / attributes 至少其一表达商品语义，quantity 可选。",
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["query"],
+      "properties": {
+        "query": { "type": "string", "minLength": 1 },
+        "sku": { "type": "string", "minLength": 1 },
+        "attributes": { "type": "object" },
+        "quantity": { "$ref": "#/$defs/quantity" }
+      }
+    },
+    "constraints": {
+      "description": "硬约束：预算/目标单价/币种/交付地点/期限/强制要求。",
+      "type": "object",
+      "additionalProperties": true,
+      "properties": {
+        "budget": { "$ref": "#/$defs/money" },
+        "target_unit_price": { "$ref": "#/$defs/money" },
+        "currency": { "$ref": "#/$defs/currency" },
+        "delivery_location": { "type": "string", "minLength": 1 },
+        "deadline": { "$ref": "#/$defs/timestamp" },
+        "mandatory_requirements": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 }
+        }
+      }
+    },
+    "preferences": {
+      "description": "偏好：品牌/质量/服务优先级，不构成硬约束。",
+      "type": "object",
+      "additionalProperties": true,
+      "properties": {
+        "brands": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+        "quality": { "type": "string", "minLength": 1 },
+        "service_priorities": { "type": "array", "items": { "type": "string", "minLength": 1 } }
+      }
+    },
+    "context_projection": {
+      "description": "最小商业披露（§5.4）：宿主只把完成当前交易必需的字段投影给远程 Merchant。Principal Memory、原始对话历史和宿主私有工具不得默认进入远程上下文。disclosure_boundary 固定为 commerce_required。",
+      "type": "object",
+      "additionalProperties": true,
+      "properties": {
+        "disclosure_boundary": { "const": "commerce_required" },
+        "projected_fields": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 }
+        }
+      }
+    }
+  }
+}

package/contracts/delegation-policy/1.0/schema.json

@@ -0,0 +1,143 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://kiwi.harrylabsj.com/schemas/delegation-policy/1.0/schema.json",
+  "title": "Kiwi DelegationPolicy v0.1",
+  "description": "Principal 对每一类商业动作的委托边界（战略 v2.5 §5.3）。商业 Agent 的真正风险不在『能不能调用工具』，而在『被授权做到哪一步』。每个动作映射为 AUTO / ASK / NEVER 之一，并支持价格、数量、时间、商家范围等硬限制。默认映射（§5.3）：discover=auto，inquiry_rfq=auto，compare_offers=auto，counter_offer=auto/受限，accept_nonbinding=ask，handoff=ask，payment=never。payment 恒为 never（KNP 不进入支付/资金托管，属硬不变量）。Host 许可只是 EffectiveAuthorization 的一层（§5.5），不得通过宿主 UI 提升本策略。",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "policy_id",
+    "version",
+    "principal",
+    "actions",
+    "expires_at"
+  ],
+  "properties": {
+    "policy_id": {
+      "$ref": "#/$defs/identifier"
+    },
+    "version": {
+      "type": "string",
+      "const": "1.0"
+    },
+    "principal": {
+      "description": "授权主体（human/company）opaque 标识，对 Merchant 只投影为可验证 Buyer Session，不泄露完整宿主身份（§8.1）。",
+      "type": "string",
+      "minLength": 1
+    },
+    "created_at": {
+      "$ref": "#/$defs/timestamp"
+    },
+    "expires_at": {
+      "description": "委托有效期：过期后 Enter 可解释状态，可重新生成，不留幽灵 pending。",
+      "$ref": "#/$defs/timestamp"
+    },
+    "actions": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "discover",
+        "inquiry_rfq",
+        "compare_offers",
+        "counter_offer",
+        "accept_nonbinding",
+        "handoff",
+        "payment"
+      ],
+      "properties": {
+        "discover": { "$ref": "#/$defs/action_policy" },
+        "inquiry_rfq": { "$ref": "#/$defs/action_policy" },
+        "compare_offers": { "$ref": "#/$defs/action_policy" },
+        "counter_offer": { "$ref": "#/$defs/action_policy" },
+        "accept_nonbinding": { "$ref": "#/$defs/action_policy" },
+        "handoff": { "$ref": "#/$defs/action_policy" },
+        "payment": { "$ref": "#/$defs/payment_policy" }
+      }
+    },
+    "limits": {
+      "$ref": "#/$defs/limits"
+    }
+  },
+  "$defs": {
+    "identifier": {
+      "description": "对端 opaque 标识符（同 KNP/1.0 §6）：非空、≤256、无首尾空白、无控制字符。",
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 256,
+      "pattern": "^\\S(.*\\S)?$"
+    },
+    "timestamp": {
+      "description": "RFC 3339 时间戳（同 KNP/1.0 §7.3）。",
+      "type": "string",
+      "format": "date-time"
+    },
+    "currency": {
+      "type": "string",
+      "pattern": "^[A-Z]{3}$"
+    },
+    "money": {
+      "description": "金额用最小单位整数（同 KNP/1.0 §7.1）。",
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["currency", "amount_minor"],
+      "properties": {
+        "currency": { "type": "string", "pattern": "^[A-Z]{3}$" },
+        "amount_minor": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "quantity": {
+      "description": "数量（同 KNP/1.0 §7.2）：value 为正数。",
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["value", "unit"],
+      "properties": {
+        "value": { "type": "number", "exclusiveMinimum": 0 },
+        "unit": { "type": "string", "minLength": 1 }
+      }
+    },
+    "mode": {
+      "type": "string",
+      "enum": ["auto", "ask", "never"]
+    },
+    "action_policy": {
+      "description": "单类商业动作的委托模式 + 可选说明。",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["mode"],
+      "properties": {
+        "mode": { "$ref": "#/$defs/mode" },
+        "note": { "type": "string", "maxLength": 1024 }
+      }
+    },
+    "payment_policy": {
+      "description": "支付/资金托管（§10 产品边界）：KNP 不进入支付与资金托管，恒为 never。",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["mode"],
+      "properties": {
+        "mode": { "const": "never" },
+        "note": { "type": "string", "maxLength": 1024 }
+      }
+    },
+    "limits": {
+      "description": "AUTO/ASK 的硬边界：金额、数量、商家范围、币种、轮次、期限。",
+      "type": "object",
+      "additionalProperties": true,
+      "properties": {
+        "max_total_price": { "$ref": "#/$defs/money" },
+        "max_unit_price": { "$ref": "#/$defs/money" },
+        "max_quantity": { "$ref": "#/$defs/quantity" },
+        "max_rounds": { "type": "integer", "minimum": 0 },
+        "allowed_merchants": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "allowed_currencies": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/currency" }
+        },
+        "deadline": { "$ref": "#/$defs/timestamp" }
+      }
+    }
+  }
+}

package/contracts/effective-authorization/1.0/schema.json

@@ -0,0 +1,167 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://kiwi.harrylabsj.com/schemas/effective-authorization/1.0/schema.json",
+  "title": "Kiwi EffectiveAuthorization v0.1",
+  "description": "EffectiveAuthorization = PackageTrust ∩ HostToolPolicy ∩ RuntimeApproval ∩ KiwiDelegationPolicy ∩ MerchantHardPolicy（战略 v2.5 §5.5）。五个相互独立边界的交集；任意一层拒绝即拒绝（deny 优先）；任何宿主 UI 的『允许』都不能提升 Kiwi/Merchant 的硬策略。AcceptNonbinding、handoff 以及超出默认披露范围的信息必须写入持久 approval_id；重启后仍可验证授权主体、范围、版本、过期时间与被批准 candidate digest。本 schema 把『granted ⇔ 五层全部 allowed』与『任一层 denied ⇒ denied』编码为可机检不变量。",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "authorization_id",
+    "action",
+    "subject",
+    "layers",
+    "effective_decision",
+    "decided_at"
+  ],
+  "properties": {
+    "authorization_id": {
+      "$ref": "#/$defs/identifier"
+    },
+    "task_id": {
+      "$ref": "#/$defs/identifier"
+    },
+    "candidate_id": {
+      "$ref": "#/$defs/identifier"
+    },
+    "action": {
+      "type": "string",
+      "enum": [
+        "discover",
+        "inquiry_rfq",
+        "compare_offers",
+        "counter_offer",
+        "accept_nonbinding",
+        "handoff",
+        "payment"
+      ]
+    },
+    "subject": {
+      "description": "授权主体：Merchant 只需要知道这是哪个可验证 Buyer Session、由什么 Principal/组织授权、授权范围、何时过期（§8.1）。",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["buyer_agent_id", "session_id", "delegation_id", "expires_at"],
+      "properties": {
+        "buyer_agent_id": { "$ref": "#/$defs/identifier" },
+        "session_id": { "$ref": "#/$defs/identifier" },
+        "delegation_id": { "$ref": "#/$defs/identifier" },
+        "expires_at": { "$ref": "#/$defs/timestamp" }
+      }
+    },
+    "layers": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "package_trust",
+        "host_tool_policy",
+        "runtime_approval",
+        "kiwi_delegation_policy",
+        "merchant_hard_policy"
+      ],
+      "properties": {
+        "package_trust": {
+          "description": "插件/包是否来自可信来源、签名与版本是否允许（§6.11）。不可信包不得获得商业写能力。",
+          "$ref": "#/$defs/layer_decision"
+        },
+        "host_tool_policy": {
+          "description": "宿主 Agent 是否允许调用该工具/暴露相关字段。宿主只可收紧，不可放宽下游策略。",
+          "$ref": "#/$defs/layer_decision"
+        },
+        "runtime_approval": {
+          "description": "当前 task/candidate 的持久审批记录。AcceptNonbinding、handoff、敏感 disclosure 必须可审计。",
+          "$ref": "#/$defs/layer_decision"
+        },
+        "kiwi_delegation_policy": {
+          "description": "Principal 对金额、数量、商家、轮次、期限的委托边界（AUTO/ASK/NEVER + 硬约束）。",
+          "$ref": "#/$defs/layer_decision"
+        },
+        "merchant_hard_policy": {
+          "description": "商家底价、MOQ、区域、客户等级、合规与人工审核。Merchant 最终商业硬边界。",
+          "$ref": "#/$defs/layer_decision"
+        }
+      }
+    },
+    "effective_decision": {
+      "type": "string",
+      "enum": ["granted", "denied"]
+    },
+    "approval_id": {
+      "description": "AcceptNonbinding / handoff / 敏感 disclosure 必须绑定持久 approval_id。",
+      "$ref": "#/$defs/identifier"
+    },
+    "expires_at": {
+      "$ref": "#/$defs/timestamp"
+    },
+    "decided_at": {
+      "$ref": "#/$defs/timestamp"
+    }
+  },
+  "allOf": [
+    {
+      "description": "deny 优先：任一独立层 denied ⇒ effective_decision 必须为 denied。",
+      "if": {
+        "anyOf": [
+          { "type": "object", "properties": { "layers": { "type": "object", "properties": { "package_trust": { "type": "object", "properties": { "status": { "const": "denied" } } } } } } },
+          { "type": "object", "properties": { "layers": { "type": "object", "properties": { "host_tool_policy": { "type": "object", "properties": { "status": { "const": "denied" } } } } } } },
+          { "type": "object", "properties": { "layers": { "type": "object", "properties": { "runtime_approval": { "type": "object", "properties": { "status": { "const": "denied" } } } } } } },
+          { "type": "object", "properties": { "layers": { "type": "object", "properties": { "kiwi_delegation_policy": { "type": "object", "properties": { "status": { "const": "denied" } } } } } } },
+          { "type": "object", "properties": { "layers": { "type": "object", "properties": { "merchant_hard_policy": { "type": "object", "properties": { "status": { "const": "denied" } } } } } } }
+        ]
+      },
+      "then": {
+        "type": "object",
+        "properties": {
+          "effective_decision": { "const": "denied" }
+        }
+      }
+    },
+    {
+      "description": "granted ⇒ 五层必须全部 allowed（交集语义；不是『多数层允许』）。",
+      "if": {
+        "type": "object",
+        "properties": { "effective_decision": { "const": "granted" } }
+      },
+      "then": {
+        "type": "object",
+        "properties": {
+          "layers": {
+            "type": "object",
+            "properties": {
+              "package_trust": { "type": "object", "properties": { "status": { "enum": ["allowed"] } } },
+              "host_tool_policy": { "type": "object", "properties": { "status": { "enum": ["allowed"] } } },
+              "runtime_approval": { "type": "object", "properties": { "status": { "enum": ["allowed"] } } },
+              "kiwi_delegation_policy": { "type": "object", "properties": { "status": { "enum": ["allowed"] } } },
+              "merchant_hard_policy": { "type": "object", "properties": { "status": { "enum": ["allowed"] } } }
+            }
+          }
+        }
+      }
+    }
+  ],
+  "$defs": {
+    "identifier": {
+      "description": "对端 opaque 标识符（同 KNP/1.0 §6）：非空、≤256、无首尾空白、无控制字符。",
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 256,
+      "pattern": "^\\S(.*\\S)?$"
+    },
+    "timestamp": {
+      "description": "RFC 3339 时间戳（同 KNP/1.0 §7.3）。",
+      "type": "string",
+      "format": "date-time"
+    },
+    "layer_decision": {
+      "description": "单层授权判定：allowed / denied。本 schema 不含 not_applicable——交集语义要求五层全部 allowed 才 granted。",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["status"],
+      "properties": {
+        "status": {
+          "type": "string",
+          "enum": ["allowed", "denied"]
+        },
+        "reason": { "type": "string", "maxLength": 1024 }
+      }
+    }
+  }
+}

package/contracts/kiwi-contracts.lock.json

@@ -2,6 +2,6 @@
   "lock_version": 1,
   "source_repository": "harrylabsj/kiwi",
   "source_commit": "009bc25cdae2668c8fd19ccedcc4e0c64a34f6be",
-  "bundle_sha256": "2dbbc52a1113dc5c05dc544802571ee188b44e1567d6bfb0cd8ccd87ea7f4998",
+  "bundle_sha256": "2350ecaacebb791cd980cc2886511359e356378a6f18cdecc1ac6331c31b0e70",
   "contracts_manifest": "contracts/manifest.json"
 }

package/contracts/manifest.json

@@ -1,8 +1,32 @@
 {
   "manifest_version": 1,
   "authority": "kiwi/contracts",
-  "bundle_sha256": "2dbbc52a1113dc5c05dc544802571ee188b44e1567d6bfb0cd8ccd87ea7f4998",
+  "bundle_sha256": "2350ecaacebb791cd980cc2886511359e356378a6f18cdecc1ac6331c31b0e70",
   "contracts": [
+    {
+      "id": "commerce-intent",
+      "version": "1.0",
+      "path": "contracts/commerce-intent/1.0/schema.json",
+      "sha256": "58e24c3d41dab8d582c7e74b540546ccad601b0e219ea1f988eca21c9107a7fb"
+    },
+    {
+      "id": "delegation-policy",
+      "version": "1.0",
+      "path": "contracts/delegation-policy/1.0/schema.json",
+      "sha256": "62a146055a68f9a1014c99ed58d6ba02160e17441f9577de0fd134023c038341"
+    },
+    {
+      "id": "effective-authorization",
+      "version": "1.0",
+      "path": "contracts/effective-authorization/1.0/schema.json",
+      "sha256": "7a04d97de2c5b2777766ee260ca8a8a2bce5024e2bff817a64ad6ff327856aa1"
+    },
+    {
+      "id": "persistent-task",
+      "version": "1.0",
+      "path": "contracts/persistent-task/1.0/schema.json",
+      "sha256": "f01c7df2dd439350daddbc272985bf4caa3db50b9c741cd1454799fdad1afdcc"
+    },
     {
       "id": "candidate-agent-dto",
       "version": "1.0",

package/contracts/persistent-task/1.0/schema.json

@@ -0,0 +1,191 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://kiwi.harrylabsj.com/schemas/persistent-task/1.0/schema.json",
+  "title": "Kiwi Persistent Task / Approval v0.1",
+  "description": "跨进程、跨审批、跨 Merchant 操作必须落到持久任务模型（战略 v2.5 §6.2）。『只有 5—7 个高层工具』不能替代任务生命周期设计：插件和 MCP 连接断开后，Kiwi 仍能解释任务现在在哪里、为什么停住、是否可重试、是否已失效。稳定标识 task_id / candidate_id / approval_id / agreement_id 重启后仍可解析，不得依赖进程内对象或宿主 session 作为权威标识。所有写操作显式携带 idempotency_key；定义 retry、timeout、cancel、resume 与 crash recovery。Offer/candidate/approval/delegation 均有 expires_at，过期后进入可解释状态，可重新生成，不留幽灵 pending。多 Merchant fan-out 允许部分成功（status=partial_success），每个结果保留 provenance、失败分类与 retryability。Buyer Core 持久存储是 task/pending/approval 的唯一权威；Plugin、MCP App、Host UI 只投影状态，不保存第二套状态机。",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "task_id",
+    "task_kind",
+    "status",
+    "idempotency_key",
+    "created_at",
+    "updated_at"
+  ],
+  "properties": {
+    "task_id": {
+      "$ref": "#/$defs/identifier"
+    },
+    "task_kind": {
+      "type": "string",
+      "enum": ["search", "request_quotes", "negotiate", "accept_agreement", "handoff"]
+    },
+    "status": {
+      "type": "string",
+      "enum": [
+        "pending",
+        "in_progress",
+        "awaiting_approval",
+        "partial_success",
+        "succeeded",
+        "failed",
+        "expired",
+        "cancelled"
+      ]
+    },
+    "idempotency_key": {
+      "description": "写操作幂等键：相同 key 的重复提交返回原任务结果，不产生重复写入。",
+      "$ref": "#/$defs/identifier"
+    },
+    "intent_id": {
+      "$ref": "#/$defs/identifier"
+    },
+    "delegation_policy_id": {
+      "$ref": "#/$defs/identifier"
+    },
+    "created_at": {
+      "$ref": "#/$defs/timestamp"
+    },
+    "updated_at": {
+      "$ref": "#/$defs/timestamp"
+    },
+    "expires_at": {
+      "description": "任务整体过期时间；过期后进入 expired 可解释状态。",
+      "$ref": "#/$defs/timestamp"
+    },
+    "resumable": {
+      "description": "crash 后是否可从持久 checkpoint 恢复。",
+      "type": "boolean"
+    },
+    "resumed_from_task_id": {
+      "$ref": "#/$defs/identifier"
+    },
+    "candidates": {
+      "description": "多 Merchant fan-out 的每个子结果；允许部分失败。",
+      "type": "array",
+      "items": { "$ref": "#/$defs/candidate_record" }
+    },
+    "intent": {
+      "description": "本任务操作的 CommerceIntent（§5.2）；由 intent_id 关联，随任务记录持久化。",
+      "type": "object",
+      "additionalProperties": true
+    },
+    "steps": {
+      "description": "磋商步骤记录（counter_offer / clarification），受 DelegationPolicy 轮次限制。",
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": true,
+        "required": ["round", "action"],
+        "properties": {
+          "round": { "type": "integer", "minimum": 1 },
+          "action": { "type": "string", "enum": ["counter_offer", "clarification"] },
+          "summary": { "type": "string" }
+        }
+      }
+    },
+    "approval": {
+      "$ref": "#/$defs/approval_record"
+    },
+    "agreement_id": {
+      "$ref": "#/$defs/identifier"
+    },
+    "handoff_ref": {
+      "$ref": "#/$defs/handoff_ref"
+    }
+  },
+  "$defs": {
+    "identifier": {
+      "description": "对端 opaque 标识符（同 KNP/1.0 §6）：非空、≤256、无首尾空白、无控制字符。",
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 256,
+      "pattern": "^\\S(.*\\S)?$"
+    },
+    "timestamp": {
+      "description": "RFC 3339 时间戳（同 KNP/1.0 §7.3）。",
+      "type": "string",
+      "format": "date-time"
+    },
+    "digest": {
+      "description": "内容摘要（同 KNP/1.0 §19）：sha256:<64 位小写十六进制>。",
+      "type": "string",
+      "pattern": "^sha256:[0-9a-f]{64}$"
+    },
+    "candidate_record": {
+      "description": "单个 Merchant 的 fan-out 子任务结果。",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["candidate_id", "merchant_id", "status"],
+      "properties": {
+        "candidate_id": { "$ref": "#/$defs/identifier" },
+        "merchant_id": { "type": "string", "minLength": 1 },
+        "status": {
+          "type": "string",
+          "enum": ["pending", "succeeded", "failed", "expired", "pending_approval"]
+        },
+        "provenance": { "$ref": "#/$defs/provenance" },
+        "failure": { "$ref": "#/$defs/failure" },
+        "expires_at": { "$ref": "#/$defs/timestamp" },
+        "retryable": { "type": "boolean" }
+      }
+    },
+    "provenance": {
+      "description": "结果来源：Merchant 外部回复/协商标识，用于 Verified Agreement 审计（§12）。",
+      "type": "object",
+      "additionalProperties": true,
+      "properties": {
+        "merchant_reply_id": { "type": "string", "minLength": 1 },
+        "negotiation_id": { "$ref": "#/$defs/identifier" },
+        "offer_id": { "$ref": "#/$defs/identifier" },
+        "source": { "type": "string", "minLength": 1 }
+      }
+    },
+    "failure": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["classification"],
+      "properties": {
+        "classification": {
+          "type": "string",
+          "enum": ["timeout", "rejected", "unreachable", "protocol_error", "expired", "other"]
+        },
+        "retryable": { "type": "boolean" },
+        "detail": { "type": "string", "maxLength": 4096 }
+      }
+    },
+    "approval_record": {
+      "description": "持久审批记录：AcceptNonbinding / handoff / 敏感 disclosure 必须写入持久 approval_id，重启后仍可验证授权主体、范围、版本、过期时间与被批准的 candidate digest。",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["approval_id", "action", "status"],
+      "properties": {
+        "approval_id": { "$ref": "#/$defs/identifier" },
+        "action": {
+          "type": "string",
+          "enum": ["accept_nonbinding", "handoff", "sensitive_disclosure"]
+        },
+        "status": {
+          "type": "string",
+          "enum": ["pending", "approved", "denied", "expired"]
+        },
+        "candidate_digest": { "$ref": "#/$defs/digest" },
+        "approved_authorization_id": { "$ref": "#/$defs/identifier" },
+        "expires_at": { "$ref": "#/$defs/timestamp" },
+        "decided_at": { "$ref": "#/$defs/timestamp" }
+      }
+    },
+    "handoff_ref": {
+      "description": "Agreement → UCP Checkout / merchant transaction endpoint 的 handoff 引用（§5.3/KTH）。",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["handoff_id", "destination_type"],
+      "properties": {
+        "handoff_id": { "$ref": "#/$defs/identifier" },
+        "destination_type": { "type": "string", "minLength": 1 },
+        "url": { "type": "string" }
+      }
+    }
+  }
+}