伺服器指派的流水號

流水號是字串欄位的頂層 sequence 選項，不是另一種欄位型別。伺服器為新插入的資料列配號，讀取時得到已格式化字串；不會自動回填既有資料列。此能力屬於 ct.calendars。

宣告序列


{
  "name": "Document number",
  "type": "string",
  "sequence": {
    "series": "invoice.number",
    "pattern": { "prefix": "INV-", "date_column": "Date", "date_format": "yyyymm", "separator": "-", "width": 6 },
    "scope_columns": [],
    "reset": "monthly",
    "gap_policy": "gapless"
  }
}

日期落在 2026 年 10 月時，該 bucket 的首號為 INV-202610-000001，計數器從 1 開始。這是 schema 片段；表格也必須宣告名為 Date 的已儲存 date／datetime 欄位。

欄位	契約
`series`	公司層級的持久 key，符合 `^[a-z][a-z0-9_.-]{0,63}$`；同一時間只能有一個有效的擁有欄位
`pattern.prefix`	預設 `""`；最多 16 個可列印字元，首尾不得有空白
`pattern.date_column`	同表已儲存 date／datetime 的參照；使用日期片段或重置時必填
`pattern.date_format`	`""`、`yyyy`、`yyyymm`、`yyyymmdd`、`yy`、`yymm`、`yymmdd`；預設 `""`
`pattern.separator`	預設 `""`；最多 3 個可列印字元，只有存在日期片段時才插入
`pattern.width`	必填嚴格整數 `1..12`；用盡時拒絕，不自行加寬
`scope_columns`	預設 `[]`；最多 2 個不重複的同表 string／select／integer 或 cardinality-one link 欄位
`reset`	`never`（預設）、`yearly`、`monthly`；年度重置要求四位數年份格式，月度重置還須包含月份
`gap_policy`	`gapless`（預設）或 `allow_gaps`

流水號欄位不得設 required、非 null 的 default_value 或 options；若宣告 max_length，必須容納完整配號字串。Scope 欄位不得是流水號欄位本身或它的日期欄位；配號時，每個 link 維度必須恰好解析到一個目標。

寫入、回滾與生命週期

Insert 時省略流水號儲存格。提供非空號碼會得到 422 ct.sequence_server_assigned；缺少必要日期或 scope 維度則是 422 ct.sequence_date_required 或 ct.sequence_scope_required。
已配號的值不能改寫或清空。已配號資料列的 scope 維度固定不變（422 ct.sequence_scope_pinned）。Restore 保留原號，revert 覆蓋回目前號碼，不還原舊號或重新配號。
計數器依公司持久序列、scope tuple 與重置 bucket 分區。gapless 配號隨交易一起回滾；allow_gaps 的非 Command 寫入即使稍後回滾，仍可能消耗號碼。Command 配號一律參與該 Command 的交易。
Delete／purge 不回收已發號碼。釋放擁有欄位後，以同一 series 重建時，pattern／reset／gap-policy／維度型別必須相容，並接續持久計數器；已有其他有效擁有者時，以 ct.sequence_series_in_use 拒絕。
已發號後，流水號設定不可變更（ct.sequence_config_immutable）。使用中的日期／scope 相依欄位不得刪除或改成不相容型別（ct.sequence_dependency_in_use）。持久序列定義衝突為 ct.sequence_series_incompatible，缺少序列 metadata 為 ct.sequence_key_unavailable。固定寬度 bucket 用盡時，回傳 409 ct.sequence_exhausted。

等待核准的 Command 不會預留或揭露已發號碼。審查顯示 (assigned at release)，真正配號發生在 release。待核准程式可複製產生的值，但不能拿來做 predicate、排序、分組、aggregate、distinct、match key 或任意運算；不安全用法以 Command 錯誤 sequence_value_computed 拒絕。流水號不是業務效果的冪等 key；該契約請使用 effect identity。

IaC

在 column line 的 spec.sequence 放入相同物件，pattern.date_column 與 scope_columns 使用 IaC column ref。Planner 檢查參照型別與持久序列相容性，並將 series fingerprint 納入 plan hash；擁有權或設定漂移會讓 plan 過期。Record line 不能指定流水號。Workbench 的本機驗證不等於伺服器流水號 admission。