header line

header 是可選的文件控制行。若提供，它必須是第一個非空白行，而且整份文件最多一行；它不建立獨立 resource，卻決定後續 refs 使用哪個 IaC state 命名空間。省略 header 等同使用空 system 與空 description。

JSONL Line

{"kind":"header","version":1,"system":"crm","description":"Shared contact workflow"}

欄位契約

只接受這四個頂層欄位；ref、table、state 與 spec 都是 extra input。這份契約對應 IacHeaderLine，不是 plan response 的欄位集合。

Ref 與身分規則

Header 沒有 authored ref。system 是整份文件的 state namespace，也會在非空時同步成受管理表格的 IaC tag。相同 scope 中，相同 system 下的 table/child refs 才能延續先前 state；更改 system 等同改用另一個 namespace，而不是支援 system rename。

Tag 同步是只增不減的。每次 apply 結束時，會在需要時建立以 system 命名的 tag，並把每張仍解析得到 live 的受管理表格指派給它；從來不會取消指派。離開文件或已刪除的表格仍保有這個 tag，手動指派的 tag 也會保留。同步失敗時在 line 0 回報 tag sync failed: {exception}；在 apply 較早階段就需要這個 tag 的 rule、trigger 或 command 行，則回報 {kind} '{ref}': system tag sync failed: {exception}。

空 system 合法，代表不做 tag sync，但此時有兩種 line kind 會變得不可用：insight_selection line 需要非空的 system，因為 system tag 就是它的隱含主體；省略 spec.tag_id 的 command line 會綁定到文件的 system tag，因此同樣需要一個非空 system。長期維護的文件仍應使用穩定、可讀的 system 名稱。

生命週期與規劃

Header 不產生 create/update action，也沒有 state: "absent"。Parser 先取出 header，再將 system 傳給 differ、state 與 export 行為。所有 resource lines 都以該 system 解析；同一份 apply 不能混用多個 namespace。

驗證錯誤

Header 的順序/唯一性錯誤是：

header must be the first line and unique

缺少 version 與錯誤版本的 byte-exact detail 分別是：

[{"type": "missing", "loc": ["header", "version"], "msg": "Field required", "url": "https://errors.pydantic.dev/<pydantic-version>/v/missing"}]

[{"type": "literal_error", "loc": ["header", "version"], "msg": "Input should be 1", "url": "https://errors.pydantic.dev/<pydantic-version>/v/literal_error"}]

超過 system/description 長度會得到 Pydantic string_too_long detail；未知欄位得到 extra_forbidden。精確 detail 產生來源：components/iac/parse.ts。

動手試試

在 IaC 工作台貼上範例，先把 version 改成 2，再把 header 移到 table 後方，觀察 parse phase 的兩種錯誤。完整端點契約請見 plan 參考。