歷史讀取與資料列版本

As-of 讀取回傳指定時間點的已儲存資料列版本，不重建當年的完整權限、schema 或計算值。此操作唯讀；還原版本 是另一個會建立新版本的寫入。

REST 契約

使用 GET /private/module/custom_tables/{scope}/tables/{table_id}/records/{record_id}/as-of?as_of=2026-10-01T00:00:00Z。{scope} 是 chatroom/{chatroom_id}、department/{department_id} 或不帶 company ID 的 company，與 Command 不同。

as_of 必填，須為帶明確時區（Z 或 offset）的 RFC3339 時間戳記；只有日期或沒有時區都不合法。截止時間包含該時間點，選擇 created_at <= as_of 的最新歷史項目；時間相同時以 version 決定。回應是 RecordAsOfResponse：

{
  "record_id": "88888888-8888-4888-8888-888888888888",
  "table_id": "44444444-4444-4444-8444-444444444444",
  "version": 2,
  "as_of": "2026-10-01T00:00:00Z",
  "recorded_at": "2026-09-30T23:00:00Z",
  "change_type": "update",
  "is_deleted": false,
  "data": {"col_11111111111111111111111111111111": "Draft"},
  "links": {}
}

recorded_at 是所選歷史項目的時間，不是請求的截止時間。is_deleted 依該版本的生命週期決定：delete 版本是 tombstone，後續 restore 版本則有效。新歷史寫入會擷取有序 link ID，包含 schema-history 途徑；不會回填所有較舊項目。

目前授權，歷史數值

資料表與目前資料列必須仍存在於租戶內，且目前讀取政策允許該列；不會回到舊 ACL。找不到列、目前列被隱藏，或截止時間沒有歷史，皆回 404 {"detail":"Record not found"}，不揭露隱藏列是否曾存在。

data 只含目前可見欄位下的已儲存值；已移除或目前隱藏的欄位省略，link／lookup／rollup／formula 不重建進 data。擷取的有序 ID 另放在 links，經目前 link 定義、目標資料表／列權限與有效目標列篩選。歷史 link 不會復活已刪除或目前隱藏的目標。

如果目前有可見 link 欄位，但所選舊歷史沒有擷取的 link 狀態，會 fail-closed 回 409：

{"detail":{"error":"history_links_unavailable","message":"This version has no captured link state"}}

不要用現在的 link 代替缺少的歷史 link。資料表 purge、歷史已移除與目前權限仍限制可讀內容。

Lookup cutoff 是不同操作

Picked many-link lookup 可設定 pick.as_of: "$row.<來源 date/datetime 欄位>"。來源 cutoff 型別須與連結目標的 pick.order_column 相同（date 或 datetime）。它先依 order-column 截止值篩選目前連結的目標列，包含截止值，再套用方向與同值排序；不是對每個目標做歷史 as-of 讀取。

Cutoff 輸入為 null、隱藏、已移除或不相容重設型別時回 null，計算欄位的 filter／sort pushdown 也相同。仍套用一般目標 ACL 與排名欄位可見性。IaC 使用 pick.as_of: "$row.<來源 column ref>"，會轉譯與匯出 ref。既有 lookup 設定仍在建立後不可變更。另見 lookup 欄位。

MCP、CT Agent 與 discovery

MCP records_history 接受 as_of，不能同時指定 version、change_type、非預設 limit 或非零 offset；結果是一個 snapshot，不是分頁時間線。CT Analyst 提供 custom_tables_get_record_as_of；schema 呈現與工具指引也描述 lookup cutoff。兩者皆遵守相同目前授權邊界。沒有新增名為 revision 的欄位型別，此 pin 也不宣告獨立的 ct.revisions capability ID。請以來源 pin 的 schema 與歷史參考 為準，不要推測 enum 或部署狀態。