Govern · Emerging evidence contract

記錄 Host 執行證據

Host 完成已授權的 mutation 後，可以把 durable evidence 附加到既有的 ExecutionPermit。Tonetify 負責記錄證據，不會代替 Host 執行 mutation、判定業務結果或取代 Host 自己的紀錄。

existing ExecutionPermit
  → host execution
  → ExecutionReceipt
  → optional WitnessEvent
  → optional ReversalEvent

契約	目前狀態
版本	host-evidence-v0
身分驗證	Host bearer token
執行權	Host 執行；Tonetify 記錄證據
成熟度	Emerging host-facing API

身分驗證與 Scope

請傳送 Authorization: Bearer <host-api-key>。這個 token 必須對應到 Bot Profile，且該 Bot Profile 與 URL 中的 permit 屬於同一個 organization。

寫入 receipt 時，還必須提供屬於該 permit 的既有 permit_credential_id。這會檢查 organization 與 permit correlation，但不等於 credential signing，也不代表 bearer token 已與 credential 建立加密綁定。

記錄 Execution Receipt

POST /api/execution-permits/<execution-permit-id>/receipts
Authorization: Bearer <host-api-key>
Content-Type: application/json

{
  "idempotency_key": "receipt-api-1",
  "permit_credential_id": "permit-credential-id",
  "receipt_ref": "host-receipt-1",
  "status": "succeeded",
  "executed_at": "2026-05-28T00:00:01Z",
  "outcome": {},
  "evidence": {}
}

Tonetify 會從已保存的 permit 推導 organization、permit、host、action、resource、subject 與 executor scope。Host 提供的欄位無法擴大這些範圍。

記錄 Witness Evidence

POST /api/execution-permits/<execution-permit-id>/witness-events
Authorization: Bearer <host-api-key>
Content-Type: application/json

{
  "execution_receipt_id": "receipt-id",
  "idempotency_key": "witness-api-1",
  "witness_kind": "host",
  "event_kind": "receipt_attested",
  "observer_ref": "hr_knowledge_host",
  "subject_ref": "host-receipt-1",
  "evidence_ref": "knowledge:annual_leave",
  "observed_at": "2026-05-28T00:00:02Z",
  "evidence": {},
  "metadata": {}
}

execution_receipt_id 是選填欄位。提供時，該 receipt 必須屬於同一個 permit。

記錄 Reversal 或 Remediation Evidence

POST /api/execution-permits/<execution-permit-id>/reversal-events
Authorization: Bearer <host-api-key>
Content-Type: application/json

{
  "execution_receipt_id": "receipt-id",
  "idempotency_key": "reversal-api-1",
  "reversal_kind": "remediation",
  "status": "requested",
  "actor_ref": "operator-1",
  "target_ref": "host-receipt-1",
  "reason": "Host execution requires remediation evidence.",
  "recorded_at": "2026-05-28T00:00:03Z",
  "outcome": {},
  "evidence": {}
}

ReversalEvent 記錄 undo、counter-action、remediation 或不可逆的證據。它不是 rollback command，也不會改動 Host 的 business truth。

Idempotency

每筆 evidence write 都必須提供 idempotency_key。

Evidence	Idempotency scope
ExecutionReceipt	Execution permit
WitnessEvent	Organization
ReversalEvent	Organization

成功時，response envelope 會指出契約版本與記錄的 evidence kind：

{
  "data": {
    "contract_version": "host-evidence-v0",
    "kind": "execution_receipt",
    "evidence": {}
  }
}

使用相同 identity 的重複請求會回傳既有 evidence。若重複使用相同 key，卻傳送衝突內容，API 會回傳 409 idempotency_key_conflict。

這個 API 不負責什麼

這個介面不會公開簽發或驗證 permit、不會簽署 credential、不會執行 Host mutation、不會驗證 Host-specific policy，也不會自動推進 permit lifecycle。

目前 Golden Loop 已驗證 proposal 與 lifecycle reconciliation，但尚未驗證 live mutation 從 permit issuance 一路走到這組 evidence API。

下一步：選擇正確的重試或 Replay 機制。