docs: add SaaS dispatcher agent contracts

docs/contracts/dispatcher-agent.md

@@ -0,0 +1,362 @@
+# Dispatcher ↔ Agent 对接契约（实现事实）
+
+## 1. 适用范围与实现边界
+
+当前边界是项目自有的 Unary gRPC `agent.v1.AgentControlService`。消息只携带控制数据、执行绑定、事实和上传元信息，不经过 Dispatcher 传输音频字节。
+
+| 方向/角色 | 当前实现 |
+| --- | --- |
+| Dispatcher → Agent | `internal/rpc.Server` 提供 Agent 侧服务；`internal/dispatcher.AgentCoordinator` 通过配置的 endpoint 调用 |
+| Agent → Dispatcher | `internal/rpc.DispatcherServer` 提供 Dispatcher 侧同名服务，仅接收事件和上传 RPC |
+| 传输 | gRPC Unary + mTLS；`internal/rpc.Client` 不做业务自动重试 |
+| 业务权威 | Dispatcher SQLite 管理任务、配额、事实、outbox；Agent 只维护本地会话、执行/文件恢复事实 |
+| 数据面 | Agent 按 Dispatcher 下发的 grant 直接 PUT 到 OSS；Dispatcher 不接收或转发录音内容 |
+
+精确字段号和枚举以 `proto/agent/v1/agent.proto` 为唯一源；本文不另造 protobuf。
+
+## 2. Service 方法与方向
+
+| RPC | 方向 | 当前代码状态 | 接收端 |
+| --- | --- | --- | --- |
+| `GetAgentStatus` | Dispatcher → Agent | 已由 `AgentCoordinator.Probe` 调用 | Agent `rpc.Server` |
+| `ActivateAgent` | Dispatcher → Agent | 已由 `AgentCoordinator.Activate` 调用 | Agent `rpc.Server` |
+| `GetBootstrap` | Dispatcher → Agent | Agent 侧已实现；当前启动绑定流程未调用 | Agent `rpc.Server` |
+| `SetAdmissionState` | Dispatcher → Agent | Agent 侧已实现；当前 `AgentCoordinator` 没有调用封装 | Agent `rpc.Server` |
+| `Execute` | Dispatcher → Agent | 已调用；当前 RPC handler 只准备并记录执行状态 | Agent `rpc.Server` |
+| `GetExecutionPermit` | Dispatcher → Agent | 已由 `ExecuteRaw` 调用 | Agent `rpc.Server` |
+| `ApplyTaskControl` | Dispatcher → Agent | 已由 `AgentCoordinator.Control` 调用 | Agent `rpc.Server` |
+| `QueryExecution` | Dispatcher → Agent | 用于超时/响应丢失后的对账 | Agent `rpc.Server` |
+| `ReportExecutionEvent` | Agent → Dispatcher | 已接收、去重并生成 MQ outbox | Dispatcher `rpc.DispatcherEventServer` |
+| `RequestUpload` | Agent → Dispatcher | 已接收并签发 OSS grant | Dispatcher `rpc.DispatcherUploadServer` |
+| `CompleteUpload` | Agent → Dispatcher | 已验证 OSS 对象并生成 `recording.ready` outbox | Dispatcher `rpc.DispatcherUploadServer` |
+
+`DispatcherServer` 对外只实现 `ReportExecutionEvent`、`RequestUpload`、`CompleteUpload`；其它 RPC 在 Dispatcher listener 上返回 `UNIMPLEMENTED`。Agent `rpc.Server` 虽实现完整 generated service，但其 upload handler 在非 `mock` 模式明确返回 `UNIMPLEMENTED`。
+
+## 3. 连接、认证与会话
+
+### 3.1 连接
+
+1. Dispatcher 从受控 Agent endpoint 文件读取 `agent_id`、`cell_id`、地址和 `server_name`。
+2. `rpc.DialFromFiles` 使用 CA、客户端证书、私钥和 server name 建立 TLS gRPC 连接。
+3. Dispatcher 对每个 endpoint 先 `GetAgentStatus`，再以返回的 `boot_id` 调 `ActivateAgent`。
+4. Dispatcher 生成本次 `dispatcher_epoch`；Agent 用 `session_generation` 持久化 fencing 水位。
+5. Agent 新会话会 fence 旧的 `agent_id + cell_id + boot_id + epoch + generation` 组合；旧请求返回 `ABORTED`，不会自动释放未知执行。
+
+### 3.2 mTLS 与身份
+
+- Agent listener 要求 verified peer certificate；可按证书 fingerprint 和允许的 Agent ID 限制。
+- Dispatcher listener 同样要求 verified mTLS peer、fingerprint allowlist 和可选的 `AllowedAgentIDs`。
+- 共用证书只证明证书组；`agent_id`、`cell_id`、`boot_id` 必须经过 Dispatcher 激活绑定，不能信任 Agent 自报 endpoint。
+- gRPC RPC 失败不等于业务失败。尤其 `Execute`、permit 和上传完成超时后，调用方必须查询原执行/上传状态，不能换 execution ID、attempt ID 或 upload ID。
+
+## 4. 公共消息结构
+
+### 4.1 `RequestMeta`
+
+| 字段 | 类型 | 用途 |
+| --- | --- | --- |
+| `protocol_version` | string | 当前实现发送 `agent.v1` |
+| `request_id` | string | 单次 RPC 请求关联 |
+| `trace_id` | string | 跨模块追踪 |
+| `operation_id` | string | 业务操作标识；写操作必填 |
+| `deadline_unix_ms` | int64 | 协议字段；当前 handler 未单独执行该值的截止检查 |
+| `dispatcher_epoch` | string | 当前 Dispatcher 会话代次 |
+| `agent_id` / `cell_id` | string | endpoint 绑定身份 |
+| `boot_id` | string | Agent 进程启动身份 |
+| `session_generation` | uint64 | 会话 fencing 代次 |
+| `idempotency_key` | string | 同操作重报必须复用；写操作必填 |
+
+### 4.2 `ResponseMeta`、`Failure`、`OperationReceipt`
+
+`ResponseMeta` 回显协议、请求、trace、operation、Dispatcher epoch、Agent/Cell/boot/generation，并增加 `observed_at_unix_ms`。
+
+`Failure`：
+
+| 字段 | 类型 |
+| --- | --- |
+| `code` | `FailureCode` |
+| `retryable` | bool |
+| `detail` | string |
+| `field` | string |
+
+`OperationReceipt`：`meta`、`result`、可选 `failure`、`fact_id`、`content_sha256`、`accepted_at_unix_ms`。
+
+`ResultCode` 为 `ACCEPTED`、`APPLIED`、`REJECTED`、`UNKNOWN`、`CONFLICT`；`ACCEPTED` 只表示接收/持久记录，不能直接解释为已拨号或已挂断。
+
+### 4.3 `ExecutionBinding`
+
+| 字段 |
+| --- |
+| `tenant_id`, `tenant_key` |
+| `execution_id`, `task_id`, `task_item_id` |
+| `task_revision` |
+| `call_id`, `attempt_id` |
+| `agent_version_id` |
+| `route_policy_id`, `caller_profile_id` |
+
+Dispatcher 从已校验的 `call.execute` 构造 binding；Agent 回报不能改写租户、任务或资产归属。
+
+### 4.4 `AssetDescriptor`、`ExecutionFact`、`UploadGrant`
+
+`AssetDescriptor`：
+
+| 字段 | 类型/约束 |
+| --- | --- |
+| `kind` | `RECORDING` 或 `TRANSCRIPT` |
+| `asset_id`, `call_id`, `execution_id` | string |
+| `format` | string |
+| `size_bytes`, `duration_ms` | int64 |
+| `checksum_sha256` | string |
+| `channels`, `sample_rate_hz` | int32 |
+
+`ExecutionFact`：
+
+| 字段 | 类型/约束 |
+| --- | --- |
+| `fact_id` | 稳定事实 ID，必填 |
+| `content_sha256` | 事实内容摘要，必填 |
+| `binding` | `ExecutionBinding` |
+| `kind` | `FactKind` |
+| `observed_at_unix_ms` | Agent 事实发生时间，必填 |
+| `source_boot_id` | 事实来源 boot，必填 |
+| `source_sequence` | uint64，诊断/排序关联 |
+| `payload_json` | JSON object 字节，必填 |
+
+`UploadGrant`：`upload_id`、`target_url`、`headers[]`、`expires_at_unix_ms`、`object_key`、`required_checksum_sha256`、`max_bytes`。grant 不包含长期 OSS 密钥。
+
+## 5. Dispatcher → Agent RPC
+
+### 5.1 `GetAgentStatus`
+
+请求：`RequestMeta` + 可选 `AgentBinding target`。激活前仅发送 protocol/request/trace/operation/agent/cell，不能带 session binding。
+
+响应：`ResponseMeta` + `AgentStatus`：
+
+- `agent_id`、`cell_id`、`boot_id`；
+- `software_version`、`protocol_version`、`asterisk_version`；
+- `admission_state`；
+- `capabilities[]`；
+- `resources`（CPU、内存、FD、spool、媒体端口及 `sample_fresh`）；
+- `applied_configs[]`；
+- `mtls_authenticated`、`session_active`、`status_reason`。
+
+当前 `Probe` 至少校验返回的 Agent/Cell 与目标一致且 `boot_id` 非空。
+
+### 5.2 `ActivateAgent`
+
+请求：`RequestMeta`、`AgentBinding`、`activation_operation_id`、可选 `session_nonce`、`session_expires_at_unix_ms`。
+
+`AgentBinding` 由 Dispatcher 提供：`agent_id`、`cell_id`、`expected_boot_id`、`dispatcher_epoch`、`session_generation`、`endpoint_id`。
+
+响应：`ResponseMeta`、`state=ACTIVE`、`Session`：
+
+- `dispatcher_epoch`；
+- `session_generation`；
+- `expires_at_unix_ms`；
+- `session_credential`（bytes，敏感数据）。
+
+当前 Agent 实现实际将 session 有效期固定为 `now + 10 分钟`；`session_nonce` 和调用方提供的 `session_expires_at_unix_ms` 当前没有参与校验。后续请求由 mTLS + 会话绑定字段授权，当前 handler 未在每个请求中再次传输或校验 `session_credential`。
+
+### 5.3 `GetBootstrap`
+
+请求：`RequestMeta`、`agent_id`、`cell_id`、`boot_id`、`session_generation`。当前 Agent handler 以 `RequestMeta` 会话授权为准。
+
+响应：`ResponseMeta`、`state`、`runtime_configs[]`、`UploadPolicy`：
+
+- `ConfigReference`：`kind`、`version`、`sha256`、`source`；
+- `UploadPolicy`：`enabled`、`max_asset_bytes`、`min_retention_ms`、`allowed_hosts[]`。
+
+当前 Dispatcher 启动绑定流程只执行 status + activate，没有调用 bootstrap。
+
+### 5.4 `SetAdmissionState`
+
+请求字段：`meta`、`target`、`state`（`OPEN/CLOSED/DRAINING/QUARANTINED`）、`barrier_id`、`expected_admission_generation`、`reason`。
+
+响应：`OperationReceipt` + `applied_admission_generation`。Agent 侧按目标 Agent 做 generation CAS；代次不匹配返回 `CONFLICT`。当前代码没有 `AgentCoordinator` 的调用封装，也没有把此状态操作接到 SaaS HTTP 控制入口。
+
+### 5.5 `GetExecutionPermit`
+
+请求：`meta`、`ExecutionBinding`、`resource_reservation_id`、`expected_task_revision`、`admission_generation`、`config_sha256`。
+
+响应：`OperationReceipt` + `ExecutionPermit`：
+
+| 字段 | 含义 |
+| --- | --- |
+| `permit_id` | 当前实现为 `permit-<execution_id>` |
+| `resource_reservation_id` | 对应 Dispatcher reservation |
+| `issued_at_unix_ms` / `expires_at_unix_ms` | 许可时间窗 |
+| `dispatcher_epoch` / `session_generation` | fencing 绑定 |
+| `fencing_token` | 随机 fencing token |
+| `config_sha256` | 执行配置摘要 |
+
+当前 `rpc.Server` 的 permit 默认有效期为 1 秒；Dispatcher 在收到传输错误时不重新申请另一个 reservation，而是先 `QueryExecution` 对账。
+
+### 5.6 `Execute`
+
+请求字段：`meta`、`ExecutionBinding`、`call_execute_json`、`config_sha256`、`admission_generation`、`resource_reservation_id`、`permit_id`。
+
+`call_execute_json` 必须是原始、已通过 `mq.schema.json` 的 `call.execute` body。Agent 当前会再次解码并校验：租户、execution、task、task item、AI version 必须与 binding 一致，并在已提供本地 AI 快照/授权时校验摘要、版本、租户、模式、有效期和 egress pool。
+
+成功响应：`OperationReceipt` + `state`。当前 `rpc.Server.Execute` 的可证明副作用是：
+
+- 写入执行准备日志；
+- 写入内存 execution record；
+- 同 idempotency key 同内容返回原 receipt；不同内容返回 `CONFLICT`；
+- 在非 mock 模式检查 Asia/Shanghai 外呼时间窗口。
+
+当前该 RPC handler 本身不证明已调用 ARI/RTP 或已经产生 SIP 外呼。`AgentCoordinator.ExecuteRaw` 当前发送 binding、原始 command JSON、config digest 和 permit ID，不填充 `admission_generation` 与 `resource_reservation_id`。
+
+### 5.7 `ApplyTaskControl`
+
+请求：`meta`、`ExecutionBinding`、`action`（`PAUSE/RESUME/STOP`）、`active_call_policy`（`DRAIN/HANGUP`）、`expected_task_revision`、`reason`。
+
+响应：`OperationReceipt`、`applied_task_revision`、`state`。
+
+当前 Agent handler：
+
+- 找不到 execution 返回 `NOT_FOUND`；
+- task revision 不一致返回 `CONFLICT`；
+- terminal execution 不允许 resume；
+- `STOP` 将 call state 置为 `stopped`/terminal；
+- `PAUSE`/`RESUME` 更新内存 call state。
+
+当前 handler 没有依据 `active_call_policy` 实施实际 drain/hangup，也没有把 `reason` 写入业务事实；真正通话屏障仍需 ARI/执行器事实补齐。
+
+### 5.8 `QueryExecution`
+
+请求：`meta` + `ExecutionBinding`。
+
+成功响应包含 `ExecutionSnapshot`：binding、execution state、`call_state`、`attempt_id`、`reason_code`、`observed_at_unix_ms`、`unknown`、`assets[]`。
+
+当前 handler 查询 Agent 内存 execution record；未找到返回 `NOT_FOUND`，当前实现不会填充资产列表。Dispatcher 只在原 RPC 结果未知或回包不完整时用原 binding 对账，不能据此自动重拨。
+
+## 6. Agent → Dispatcher RPC
+
+### 6.1 `ReportExecutionEvent`
+
+请求：`RequestMeta` + `ExecutionFact`。
+
+Dispatcher 侧额外要求：
+
+- verified mTLS peer；可选允许的 Agent ID；
+- `meta.agent_id/cell_id/boot_id` 非空；
+- operation/idempotency key 非空；
+- fact ID、内容摘要、source boot、观测时间和 payload 非空；
+- binding 至少包含 `tenant_id`、`tenant_key`、`execution_id`；
+- `payload_json` 必须解码为 JSON object。
+
+`FactKind` 到 SaaS MQ 事件的当前映射：
+
+| FactKind | Dispatcher 输出 | aggregate |
+| --- | --- | --- |
+| `EXECUTION_ACCEPTED` | `command.result` | `command` |
+| `CALL_STATUS` | `call.status` | `call` |
+| `CALL_FINISHED` | `call.finished` | `call` |
+| `TRANSCRIPT_UPDATED` | `transcript.updated` | `transcript_segment` |
+| `TRANSCRIPT_FAILED` | 尝试生成 `transcript.failed`，但当前 `aggregate_type=transcript` 不通过 `mq.schema.json` | 当前路径阻塞 |
+| `CONTACT_OPT_OUT` | `contact.opt_out` | `call` |
+| `RECORDING_PROGRESS` | 不发布 MQ 事件，只保存 fact | `execution_fact` |
+
+当前 Dispatcher 为有事件的 fact 生成 `event_id = execution-fact-<fact_id>`，并在同一 SQLite 事务内。注意：`TRANSCRIPT_FAILED` 的当前代码映射使用 `aggregate_type=transcript`，而 `mq.schema.json` 只允许 `transcript_segment`；因此该 fact 当前会在事件 Schema 校验阶段失败，不能按成功回报处理。
+
+具体流程为：
+
+1. 以 `fact_id + content_sha256` 去重；
+2. 保存 binding、payload、source boot、source sequence、观测时间；
+3. 分配 aggregate version；
+4. 写入权威事件 outbox。
+
+重复 fact 同摘要返回 `ACCEPTED`；同 fact ID 不同摘要返回 `CONFLICT`。Agent 不能通过 payload 或请求字段指定 `aggregate_version`。
+
+### 6.2 `RequestUpload`
+
+请求：`meta`、`ExecutionBinding`、`AssetDescriptor`、`upload_id`。
+
+当前 Dispatcher 验证：Agent/Cell/operation/idempotency 元数据、完整 execution/tenant binding、合法 `tenant_key`、asset ID、upload ID、正数文件大小和 SHA-256；超过 OSS 最大文件大小返回 `RESOURCE_EXHAUSTED`。
+
+成功响应：`OperationReceipt`、`UploadGrant`、`state`。当前生产 Dispatcher handler：
+
+- 以 `tenant_key + "\\0" + execution_id + "\\0" + asset_id` 的 SHA-256 hex 生成 object key，并加配置的 key prefix；
+- 将 binding、asset、grant、object key、state 持久到 Dispatcher SQLite；
+- grant 的过期时间由 OSS client 配置提供；
+- 同 upload ID 同 binding/asset 返回原 grant；绑定不同返回冲突；
+- 过期 grant 只有在显式再次 `RequestUpload` 时才替换，不自动续期。
+
+新请求当前返回 `UPLOAD_STATE_REQUESTED`；持久层状态为 `granted`。`UPLOADING` 枚举存在，但当前 Dispatcher handler 不把 Agent 的 PUT 过程映射为该状态。
+
+### 6.3 Agent → OSS 直接上传
+
+Agent 获得 grant 后使用 `internal/agent.UploadClient.UploadFile`：
+
+- 只允许 HTTPS；除非显式配置，否则不允许 HTTP；
+- 可限制目标 host；禁止 grant 注入 `Host` 和 `Content-Length`；
+- 预先读取文件计算 SHA-256，再按 `Content-Length` PUT；
+- 禁止重定向；2xx 才算 PUT 成功；
+- 返回 HTTP status、文件大小、SHA-256、ETag；
+- 文件内容不经过 Dispatcher，Agent 不把源文件删除或移动。
+
+PUT 成功不等于 OSS verified，也不等于 SaaS 已应用。
+
+### 6.4 `CompleteUpload`
+
+请求：`meta`、原 `ExecutionBinding`、原 `AssetDescriptor`、`upload_id`、`uploaded_size_bytes`、`uploaded_checksum_sha256`。
+
+Dispatcher 当前执行：
+
+1. 校验 upload ID 对应的 binding/asset 完全一致；
+2. 校验上传大小、SHA-256 和 grant `max_bytes`；
+3. 校验 grant 未过期；
+4. 调用 OSS client 独立验证 object；
+5. 只允许 `AssetKind=RECORDING` 进入 verified recording 路径；
+6. 在一个 SQLite 事务内更新 upload 为 completed、保存 `oss_id` 并写入 `recording.ready` outbox。
+
+响应为 `OperationReceipt`、`state=COMPLETED`、`oss_id`。同 upload ID 同 OSS ID 的重复 complete 返回 `ACCEPTED`；未知 upload 返回 `NOT_FOUND`；对象校验失败返回 `FAILED_PRECONDITION` 且标记可重试。
+
+## 7. 错误、幂等与未知结果
+
+### 7.1 gRPC FailureCode
+
+`INVALID_ARGUMENT`、`UNAUTHENTICATED`、`PERMISSION_DENIED`、`FAILED_PRECONDITION`、`ABORTED`、`RESOURCE_EXHAUSTED`、`UNAVAILABLE`、`DEADLINE_EXCEEDED`、`NOT_FOUND`、`ALREADY_EXISTS`。
+
+调用方处理原则：
+
+- 参数、Schema、绑定错误：拒绝，不改写成另一任务；
+- CAS、session、fact、upload 绑定冲突：查询原对象，不换 ID 绕过；
+- `UNAVAILABLE`/`DEADLINE_EXCEEDED`：结果可能已发生，先查询/对账；
+- `Execute` 结果未知：Dispatcher 标记 reservation/task 为 unknown，禁止自动重新 originate；
+- 上传回包丢失：复用原 `upload_id` 和原资产摘要；
+- Agent 新 boot：保留旧未知占用，先恢复和对账，不因新 boot 的空状态释放配额。
+
+### 7.2 RPC 幂等键
+
+Agent 侧写操作的内存 operation key 为：
+
+`agent_id + "\\0" + operation_id + "\\0" + idempotency_key`
+
+同 key 同 protobuf 内容返回原 receipt；同 key 不同内容返回 `CONFLICT`。Dispatcher 事件侧使用 `fact_id + content_sha256`，上传侧使用 `upload_id + binding + asset` 绑定。
+
+## 8. 当前未实现或未接通的部分
+
+1. `GetBootstrap`、`SetAdmissionState` 虽有 handler，但当前 Dispatcher 启动流程没有调用完整 bootstrap/admission 编排。
+2. `Execute` 的当前 RPC 实现只证明准备/幂等/配置校验，不证明 ARI/RTP/SIP 已由该 RPC 直接完成。
+3. Dispatcher → SaaS 的 `recording-uploads` HTTP handshake 未在当前 Go client 中接入；当前完成路径是 Dispatcher 直接验证 OSS。
+4. Dispatcher → SaaS 的 AI version GET 未接入；当前 AI snapshot/authorization 由启动输入提供并在 Agent 侧校验。
+5. 不能把 generated service 中的全量方法数当作每个 listener 都可调用；实际 listener 能力以第 2 节和 `DispatcherServer` 代码为准。
+
+## 9. 依据文件
+
+- `proto/agent/v1/agent.proto`
+- `internal/dispatcher/agent.go`
+- `internal/rpc/client.go`
+- `internal/rpc/server.go`
+- `internal/rpc/dispatcher_server.go`
+- `internal/rpc/dispatcher_events.go`
+- `internal/rpc/dispatcher_upload.go`
+- `internal/agent/upload.go`
+- `internal/store/facts.go`
+- `internal/store/uploads.go`
+- `internal/ai/snapshot.go`
+- `internal/ai/authorization.go`
+- `cmd/sip-go-agent/main.go`
+- `contracts/upstream/2026-09-19-p1-v1/event-payloads.schema.json`
+- `contracts/upstream/2026-09-19-p1-v1/ai-authorization.schema.json`

docs/contracts/saas-dispatcher.md

@@ -0,0 +1,344 @@
+# SaaS ↔ Dispatcher 对接契约（实现事实）
+
+## 1. 适用范围与事实等级
+
+本文只描述当前 Go 实现能够证明的字段、方向、接口和状态；不把上游 OpenAPI 中尚未接入的 HTTP 客户端写成“已实现”。
+
+| 内容 | 当前状态 | 事实来源 |
+| --- | --- | --- |
+| SaaS → Dispatcher：`call.execute` RabbitMQ 命令 | 已实现 | `internal/dispatcher/consumer.go`、`internal/store/store.go` |
+| Dispatcher → SaaS：RabbitMQ 业务事件及 outbox | 已实现 | `internal/contract/contract.go`、`internal/store/facts.go`、`internal/dispatcher/dispatcher.go` |
+| SaaS → Dispatcher：控制、命令查询、命令补传 HTTP | 已实现，但只有当前代码列出的行为 | `internal/control/http.go` |
+| SaaS → Dispatcher：通话查询、通话补传 HTTP | 路由存在，当前固定返回 `404` | `internal/control/http.go` |
+| Dispatcher → SaaS：录音 upload-session/complete HTTP | 上游契约已定义，当前代码没有 SaaS HTTP client | `contracts/upstream/2026-09-19-p1-v1/saas.openapi.yaml` |
+| Dispatcher → SaaS：AI version GET | 上游契约已定义，当前代码没有 SaaS HTTP client；当前 Agent 启动时读取本地快照 | `contracts/upstream/2026-09-19-p1-v1/ai-config.openapi.yaml`、`internal/ai/*.go` |
+
+契约包固定来源为 `contracts.SourceCommit = 2026-09-19-p1-v1`。MQ 与事件正文必须以该目录中的 JSON Schema 为准，不维护第二套手写 Schema。
+
+## 2. 通信拓扑与方向
+
+| 方向 | 接口 | 传输 | 交付语义 |
+| --- | --- | --- | --- |
+| SaaS → Dispatcher | `call.execute` | RabbitMQ command exchange | Dispatcher 完成 Schema、租户路由、截止时间和 SQLite 持久化后才 ACK |
+| Dispatcher → SaaS | `command.result` 等事件 | RabbitMQ event exchange + SQLite outbox | publisher confirm 只代表 broker 收到；不代表 SaaS 业务事务已应用 |
+| SaaS → Dispatcher | 控制/查询/补传 | 内部 HTTP | 控制和补传的 `202` 只代表已接受/持久化，不代表 Agent 已执行 |
+| Dispatcher → SaaS | 录音会话申请/完成 | 上游定义的内部 HTTP | 当前项目尚未接入；不能用本地 OSS 结果代替 SaaS `verified` |
+| Dispatcher → SaaS | `GET /internal/v1/ai/agent-versions/{agent_version_id}` | 上游定义的内部 HTTP | 当前项目尚未接入；不能读取 `latest` 或用默认配置替代 |
+
+`tenant_key` 原值复制到消息体、队列、binding 和 routing key；必须是有效 UTF-8，最大 `224` 字节，不清洗、编码或截断。
+
+## 3. RabbitMQ 命令：SaaS → Dispatcher
+
+### 3.1 拓扑
+
+| 元素 | 值 |
+| --- | --- |
+| command exchange | `agent-call.commands.v1`，durable `direct` |
+| tenant queue | `agent-call.executor.{tenant_key}.v1`，durable、单一精确 binding |
+| routing key | `agent-call.tenant.{tenant_key}.call.execute` |
+| event exchange | `agent-call.events.v1`，durable `topic` |
+| Dispatcher dead-letter exchange | `agent-call.dead-letter.v1`，durable `topic` |
+| 默认 prefetch | `1` |
+
+Dispatcher 为每个消费租户声明 command queue 和 `.dlq.v1` 队列。SaaS 结果队列由 SaaS 管理，拓扑基线为 `agent-call.saas.events.v1`，binding `agent-call.#`。
+
+### 3.2 `call.execute` 外壳
+
+消息为 JSON，`additionalProperties: false`：
+
+| 字段 | 类型 | 必填/约束 |
+| --- | --- | --- |
+| `schema_version` | string | 必须为 `1.0` |
+| `command_type` | string | 必须为 `call.execute` |
+| `command_id` | string | 1–128 字节；不可含空白、`/`、`\\` |
+| `tenant_id` | string | 同上 |
+| `tenant_key` | string | 非空；有效 UTF-8；实现额外限制 224 字节 |
+| `trace_id` | string | 同 `id` 约束 |
+| `issued_at` | RFC3339 时间 | 必填 |
+| `not_after` | RFC3339 时间 | 必填；Dispatcher 接收时已到期则拒绝 |
+| `payload` | object | 必须符合 `executePayload` |
+
+### 3.3 `payload` 数据结构
+
+| 字段 | 类型 | 约束 |
+| --- | --- | --- |
+| `execution_id` | string | 必填 ID |
+| `task_id` | string | 必填 ID |
+| `task_item_id` | string | 必填 ID |
+| `task_revision` | integer | `>= 1` |
+| `callee` | string | 1–256 字符；保留业务原始被叫号码 |
+| `route_policy_id` | string | 必填 ID |
+| `caller_profile_id` | string | 必填 ID |
+| `agent_version_id` | string | 必填 ID |
+| `variables` | object | 必填；当前 Schema 允许任意附加属性，业务白名单仍由上游约束 |
+| `ring_timeout_ms` | integer | `>= 1` |
+| `max_call_duration_ms` | integer | `>= 1` |
+
+Go 实现对应 `internal/contract.ExecutePayload`；`payload` 以 `json.RawMessage` 保留原始 JSON，Dispatcher 不把变量转成另一套协议。
+
+### 3.4 接收、幂等与 ACK
+
+1. `ConsumeTenant` 先校验 `tenant_key`，声明租户队列，再以 `prefetch=1` 消费。
+2. `AcceptCommand` 调用 `Store.IngestCommand`：校验源 Schema、routing key、`not_after`，计算原始 body 的 SHA-256。
+3. 以 `command_id` 查 inbox：同 ID 同 body 为重复；同 ID 不同 body 为冲突并拒绝。
+4. 新命令在一个 SQLite 事务内写入 inbox、task 和 `command.result(accepted)` outbox。
+5. handler 成功后才 ACK。Schema、JSON、租户路由等永久错误 `Reject(false)`，经死信队列处理；其它错误 `Nack(requeue=true)`。
+6. `command_id`、`execution_id`、`task_id` 等业务标识不因重投而更换；`not_after` 不因重投延期。
+
+当前 `command.result` 初始 payload 为：
+
+```json
+{
+  "command_id": "<command_id>",
+  "command_type": "call.execute",
+  "execution_id": "<execution_id>",
+  "status": "accepted",
+  "reason_code": "accepted",
+  "requested_task_revision": 1
+}
+```
+
+## 4. RabbitMQ 事件：Dispatcher → SaaS
+
+### 4.1 通用外壳
+
+事件 routing key 固定为 `agent-call.{event_type}`。外壳字段全部必填：
+
+```json
+{
+  "schema_version": "1.0",
+  "event_id": "<id>",
+  "event_type": "<event_type>",
+  "tenant_id": "<id>",
+  "tenant_key": "<原值>",
+  "trace_id": "<id>",
+  "occurred_at": "2026-09-19T00:00:00Z",
+  "aggregate_type": "<aggregate>",
+  "aggregate_id": "<id>",
+  "aggregate_version": 1,
+  "payload": {}
+}
+```
+
+`event_type` 的源 Schema 枚举为：
+
+`command.result`、`call.status`、`transcript.updated`、`call.finished`、`recording.ready`、`recording.failed`、`transcript.failed`、`contact.opt_out`。
+
+事件 payload 必须同时通过 `mq.schema.json` 和 `event-payloads.schema.json`。`EventBuilder` 不接受未知字段；`aggregate_version` 由 Dispatcher SQLite 按 `aggregate_type + aggregate_id` 递增，Agent 不能指定它。
+
+### 4.2 当前代码实际生成的事件
+
+| 事件 | 事实来源 | 当前代码行为 |
+| --- | --- | --- |
+| `command.result` | 命令持久受理、执行接受事实 | 命令接收路径直接生成；Agent `EXECUTION_ACCEPTED` fact 也映射到该类型 |
+| `call.status` | Agent `CALL_STATUS` fact | Dispatcher 校验 fact 后生成 |
+| `call.finished` | Agent `CALL_FINISHED` fact | Dispatcher 校验 fact 后生成 |
+| `transcript.updated` | Agent `TRANSCRIPT_UPDATED` fact | 保留实时文字事件名，不使用 `call.transcript` |
+| `transcript.failed` | Agent `TRANSCRIPT_FAILED` fact | 当前代码尝试映射，但使用 `aggregate_type=transcript`；`mq.schema.json` 只允许 `transcript_segment`，因此该路径当前无法通过双 Schema 校验 |
+| `contact.opt_out` | Agent `CONTACT_OPT_OUT` fact | Dispatcher 校验 fact 后生成 |
+| `recording.ready` | 已验证 OSS 上传完成 | `CompleteUpload` 将完成状态和 outbox 放在同一 SQLite 事务 |
+| `recording.failed` | 上游 Schema | 当前 Go 代码没有对应 `FactKind` 或事件生成路径 |
+
+`RECORDING_PROGRESS` fact 只写入 Dispatcher 事实表，不生成 SaaS MQ 事件。`TRANSCRIPT_FAILED` 虽在两个事件 payload Schema 中声明，但当前 `internal/rpc/dispatcher_events.go` 将其聚合类型写成 `transcript`，随后被 `mq.schema.json` 拒绝；不能把该路径记为已交付。
+
+### 4.3 已冻结的专属 payload 关键字段
+
+完整约束在 `event-payloads.schema.json`；下面列出对接方必须使用的字段，不是新的 Schema：
+
+| 事件 | 必填字段 |
+| --- | --- |
+| `command.result` | `command_id`, `command_type`, `status`, `reason_code` |
+| `call.status` | `call_id`, `execution_id`, `call_state`, `call_version`, `attempt_id`, `attempt_state` |
+| `transcript.updated` | `call_id`, `turn_id`, `segment_id`, `role`, `revision`, `text`, `is_final`, `start_ms`, `end_ms`, `playback_state` |
+| `call.finished` | `call_id`, `execution_id`, `call_version`, `outcome`, `started_at`, `ended_at`, `duration_ms`, `reason_code` |
+| `recording.ready` | `call_id`, `recording_id`, `oss_id`, `format`, `channels`, `sample_rate_hz`, `duration_ms`, `size_bytes`, `checksum_sha256` |
+| `recording.failed` | `call_id`, `recording_id`, `stage`, `reason_code`, `retryable` |
+| `transcript.failed` | `call_id`, `reason_code`, `retryable` |
+| `contact.opt_out` | `call_id`, `task_id`, `task_item_id`, `requested_at` |
+
+`recording.ready` 只能表示对象已验证；不能用 PUT 成功、ETag 或本地路径替代 `oss_id` 和 SHA-256。
+
+### 4.4 Outbox 交付
+
+`Store.RecordExecutionFact`、命令接收和上传完成均可在状态事务中写 outbox。`Dispatcher.FlushOutbox`：
+
+- claim `pending/retry` 记录并标记 `dispatching`；
+- 通过 RabbitMQ persistent JSON message 发布并等待 publisher confirm；
+- 成功标记 `published`；失败标记 `retry`；
+- 重启时将 `dispatching` 恢复为 `retry`。
+
+重复 fact 使用相同 `fact_id + content_sha256` 时不创建第二条事件；同 fact ID 不同摘要返回冲突。SaaS 必须以 `event_id` 做 inbox 幂等，broker confirm 不能当作 SaaS 应用收讫。
+
+## 5. Dispatcher 提供的 HTTP 接口：SaaS → Dispatcher
+
+### 5.1 公共请求头
+
+当前 `internal/control.Handler` 要求：
+
+- `Authorization: Bearer <token>`；配置了 token 时必须精确匹配；
+- `X-Tenant-ID`；
+- `X-Request-ID`。
+
+当前 Handler 未强制检查权限 scope。源 `executor.openapi.yaml` 另外要求 `Idempotency-Key`；控制接口当前代码只把该值传入存储层，没有把缺失值直接拒绝，这属于实现与源 OpenAPI 的已知差异。
+
+错误响应为 JSON：
+
+```json
+{
+  "type": "about:blank",
+  "title": "<HTTP status>",
+  "status": 400,
+  "code": "<code>",
+  "detail": "<detail>",
+  "request_id": "<X-Request-ID>",
+  "retryable": false
+}
+```
+
+### 5.2 控制任务
+
+**方向：SaaS → Dispatcher**
+
+`POST /internal/v1/outbound/tasks/{task_id}/controls`
+
+请求体：
+
+| 字段 | 类型/约束 |
+| --- | --- |
+| `command_id` | 必填 ID；当前代码用于响应，不单独生成控制 outbox |
+| `action` | `pause`、`resume`、`stop` |
+| `expected_task_revision` | integer，`>=1`；CAS 版本 |
+| `active_call_policy` | 可选：`drain` 或 `hangup` |
+| `reason` | 非空，最大 512 字符 |
+
+当前成功响应为 `202`：
+
+```json
+{
+  "command_id": "<id>",
+  "tenant_id": "<tenant>",
+  "tenant_key": "<tenant_key>",
+  "task_id": "<task_id>",
+  "status": "accepted",
+  "requested_task_revision": 1,
+  "accepted_at": "2026-09-19T00:00:00Z"
+}
+```
+
+实现先按 `X-Tenant-ID + task_id` 查询任务，再以任务的 `execution_id` 调用 `ApplyControlDetailed`。版本冲突为 `409`；任务不存在为 `404`；输入错误为 `400`。`202` 不表示 Agent 已应用控制。
+
+### 5.3 查询命令
+
+**方向：SaaS → Dispatcher**
+
+`GET /internal/v1/outbound/commands/{command_id}`
+
+当前成功响应字段：
+
+```json
+{
+  "command_id": "<id>",
+  "command_type": "call.execute",
+  "tenant_id": "<tenant>",
+  "tenant_key": "<tenant_key>",
+  "task_id": "<task_id>",
+  "execution_id": "<execution_id>",
+  "call_id": null,
+  "status": "persisted",
+  "reason_code": null,
+  "wait_reason_code": null,
+  "accepted_at": "<inbox.persisted_at>",
+  "waiting_since": null,
+  "admission_deadline": "<envelope.not_after>",
+  "requested_task_revision": 1,
+  "applied_task_revision": null,
+  "task_state": null,
+  "aggregate_version": 1,
+  "updated_at": "<inbox.received_at>"
+}
+```
+
+查询按租户隔离；不存在返回 `404`。当前实现不返回 call snapshot、控制应用版本或完整状态机。
+
+### 5.4 按 source command 补传
+
+**方向：SaaS → Dispatcher**
+
+`POST /internal/v1/outbound/commands/{source_command_id}/replays`
+
+请求体：
+
+```json
+{"command_id":"<new-request-id>","reason":"<1..512 chars>"}
+```
+
+必须提供 `Idempotency-Key`。成功响应为 `202`：
+
+```json
+{"command_id":"<new-request-id>","status":"accepted","snapshot_cutoff":"<now>"}
+```
+
+当前实现读取原 inbox body，保留原 `command_id` 和原消息内容，按原租户 routing key 写入 outbox；`replay-<Idempotency-Key>` 只是 outbox event ID，不是新的业务 command ID。不存在 source command 返回 `404`。原消息的 `not_after` 不会被改写，重发后仍可能因过期被拒绝。
+
+### 5.5 当前不可用的通话接口
+
+以下路由已匹配，但当前固定返回 `404`：
+
+- `GET /internal/v1/outbound/calls/{call_id}`；
+- `POST /internal/v1/outbound/calls/{call_id}/replays`。
+
+不得依据上游 OpenAPI 的 `Call` 结构宣称当前代码已经提供通话查询或通话补传。
+
+## 6. Dispatcher → SaaS 的已声明、未接入 HTTP
+
+### 6.1 录音 upload session / complete
+
+权威源为 `contracts/upstream/2026-09-19-p1-v1/saas.openapi.yaml`。
+
+| 方向 | 方法 | 路径 |
+| --- | --- | --- |
+| Dispatcher → SaaS | `POST` | `/internal/v1/outbound/recording-uploads` |
+| Dispatcher → SaaS | `POST` | `/internal/v1/outbound/recording-uploads/{upload_id}/complete` |
+
+公共要求：Bearer、`X-Tenant-ID`、`X-Request-ID`、`Idempotency-Key`。
+
+申请请求的实际源字段为 `recording_id`、`call_id`、`content_type=audio/wav`、`size_bytes`、`checksum_algorithm=SHA-256`、`checksum`、`channels=1`、`sample_rate_hz`、`duration_ms`。返回 `upload_id`、`recording_id`、`expires_at`、`upload_method=PUT`、`upload_url`、`required_headers`、`constraints` 和可空 `oss_id`。
+
+complete 请求为 `recording_id`、`size_bytes`、`checksum_algorithm=SHA-256`、`checksum`、可空 `etag`；成功返回 `status=verified`、`oss_id`、`verified_at`。
+
+当前 Go 代码没有调用这两个 SaaS HTTP 路径。当前 Dispatcher upload handler 直接使用本地 `internal/oss` client 签发和验证 OSS grant；这条路径属于 Dispatcher ↔ Agent 的当前实现，不能写成 SaaS 已联调。
+
+### 6.2 AI immutable version GET
+
+权威源为 `contracts/upstream/2026-09-19-p1-v1/ai-config.openapi.yaml`：
+
+`GET /internal/v1/ai/agent-versions/{agent_version_id}`
+
+请求要求租户和 request header，返回不可变版本的 `tenant_id`、`agent_version_id`、`status`、`immutable=true`、`content_sha256` 和 `config`。`config` 顶层由 `agent_version_id`、`immutable=true`、`asr`、`conversation` 以及 full-AI 模式所需的 `llm`、`prompt`、`tts` 组成；ASR-only 不得带后三者。
+
+当前实现只在 `internal/rpc.ServerOptions` 接收本地 `AISnapshotRaw`/`AIAuthorizationRaw`，由 `internal/ai/snapshot.go` 和 `internal/ai/authorization.go` 校验版本、摘要、租户、模式、有效期和 egress；没有 SaaS GET client，也没有“断 SaaS 后使用任意默认配置”的回退。
+
+## 7. 禁止误读
+
+1. RabbitMQ publisher confirm ≠ SaaS 已应用。
+2. HTTP `202 accepted` ≠ Agent 已执行或控制已生效。
+3. 当前本地 OSS grant/verify ≠ SaaS recording session/verified 已完成。
+4. Schema 支持 `recording.failed`、通话查询或 AI GET ≠ 当前 Go 代码已经生成或提供这些接口。
+5. 任何重试都必须保留原 `command_id`、`execution_id`、`event_id` 或 `upload_id` 的业务语义；未知执行不能换 ID 重拨。
+
+## 8. 依据文件
+
+- `internal/contract/contract.go`
+- `internal/mq/amqp.go`
+- `internal/tenant/routing.go`
+- `internal/dispatcher/consumer.go`
+- `internal/dispatcher/dispatcher.go`
+- `internal/store/store.go`
+- `internal/store/facts.go`
+- `internal/control/http.go`
+- `contracts/upstream/2026-09-19-p1-v1/mq.schema.json`
+- `contracts/upstream/2026-09-19-p1-v1/event-payloads.schema.json`
+- `contracts/upstream/2026-09-19-p1-v1/mq-topology.md`
+- `contracts/upstream/2026-09-19-p1-v1/executor.openapi.yaml`
+- `contracts/upstream/2026-09-19-p1-v1/saas.openapi.yaml`
+- `contracts/upstream/2026-09-19-p1-v1/ai-config.openapi.yaml`