綁定 Command 的機器寫入者

兩種面向 CT 的機器途徑，都沿用一般 Command executor、目前授權、規則、審批義務與 effect identity。它們不授予原始資料表寫入權、不透露使用者 JWT、不取代 Agent 確認。

Service credential

在 /private/module/custom_tables/{scopeWithId}/commands/{command_id} 下，POST /service-credentials 簽發憑證、GET /service-credentials 列出中繼資料、POST /service-credentials/{credential_id}/revoke 撤銷一張。根路徑為 company/{company_id}、department/{department_id}、chatroom/{chatroom_id}。管理操作使用 JWT 驗證（不是 API key），且目前必須可管理所有已宣告資料表；service account 不能再簽發另一張憑證。

{"service_account_id":"55555555-5555-4555-8555-555555555555","chatroom_id":"11111111-1111-4111-8111-111111111111","expires_in_seconds":3600}

expires_in_seconds 為 60–86,400，預設 3,600。目標 Command 必須具備 definition authority、execute_policy: "restricted" 與 effect_identity。Service account 與執行聊天室必須仍有效、屬於已驗證租戶與同一部門，且目前具有聊天室成員資格與有效 execute grant。部門／聊天室 Command 也要求聊天室符合其範圍。

201 回應包含中繼資料與一個 ctsp_… 格式的 credential；明文只在簽發時回傳。列出／撤銷都不回傳密鑰；只持久化高熵 token 的 SHA-256 驗證值。請放在機器的密鑰儲存區，不能放入 Command 定義、瀏覽器、prompt 或保留的診斷紀錄。

機器只能把 Authorization: Bearer <ctsp credential> 送到所綁定 Command 的 POST …/execute 或 GET …/executions/{execution_id}。不能用來 list／query／prepare／operations、操作另一個 Command／範圍、管理憑證或呼叫一般 CT 資料列 API。聊天室與 principal 來自綁定，不是呼叫者指定的身分。這是執行能力，不是全資料表 API key。

每次請求會重讀憑證期限／撤銷、帳號／聊天室／Command 有效性、租戶／部門綁定、definition-authority／restricted／effect-identity 要求、聊天室成員資格與有效授權。待審計畫核准後執行，也會重讀原始機器來源；舊計畫或收據不能繞過撤銷。

在 definition authority 之下，機器的 POST …/execute 與 GET …/executions/{execution_id} 回應遵循 status-only 結果的規則，除非該服務帳號管理每一張被引用的資料表；回應也會帶作者選擇公開的公開結果。

這些機器拒絕採用 detail: {code}；其他 Command 驗證、受治理寫入與審批拒絕保留既有格式。在已管理 Command 下撤銷不存在的憑證，回 404 Service credential not found；過期不表示其列出中繼資料會消失。

經驗證的 Sandbox 輸出，只進入一個 Command

CT 輸出政策為 {kind: "custom_table_command", command_id, chatroom_id, input_schema}，宣告精確、有順序的 Command 輸入 schema（最多 200 個輸入），不是任意資料列 CRUD 或呼叫者指定 SQL。目標必須是 write mode、restricted、definition-authority 且有 effect identity 的 Command。已發布版本作者與原始 Run principal 都必須是仍有效、已授權的真人；Run 使用部門擁有的 task、綁定聊天室與 JWT principal，不能是 borrowed run。

伺服器的封閉 Run 通道提供 callback URL 與密鑰；不能透過 CT 憑證管理自行簽發。POST /public/module/custom_tables/callback/command-output/{token_id} 只接收 {"inputs": {...}}，Bearer authorization 使用該 Run capability，不是一般使用者 JWT。瀏覽器 Playground／codegen 將此路由視為特權、僅供參考。

呼叫前，伺服器會檢查 token／run／version／task 狀態、聊天室與 principal 綁定、兩位真人目前的 execute 權限、精確輸入 schema 與凍結的 Command digest。Run 只允許 queued、starting、running；task 必須維持 active，版本為 published 且 content active。已撤銷／過期、已完成、移動或過時的輸出採取保守拒絕。

先驗證輸入，才會持久化釘住第一個有效輸出 digest。相同的已驗證輸入可沿用既有 executor 與 effect identity 重試；同一 Run 改送其他輸入，即使第一次呼叫仍待重試，也回 409 output_command_conflict。共用 executor 收到 idempotency_key: "sandbox-output:<run_id>"、預期 Command digest 與伺服器綁定來源。Callback 沿用既有 executor 與傳遞契約。

輸入格式不符為 422 output_schema_violation；政策／Command 過時為 409 output_command_stale；目前 Run 不可用為 409 output_run_unavailable（callback 能力不存在／錯誤則為 404）。權限拒絕仍有型別、不洩漏值。審批不能把已撤銷或過時的輸出來源變成有效寫入者。舊的直接 Sandbox DB／writeback 能力不能繞過 commands_only 資料表。

Sandbox 平台設定不在本手冊範圍；既有 CT 邊界僅交叉參照 Sandbox writeback 頁。CT 契約請看 Command 執行、execute grant與參考卡片。