aggregate_limit

aggregate_limit 約束有效資料列群組的精確總和或筆數，不受寫入者可讀範圍影響。它可限制容量上限、非負餘額或守恆等式；這是規則，不是查詢彙總或用戶端算出的總計。

宣告契約


{
  "type": "aggregate_limit",
  "name": "Conserve signed units",
  "group_by": [],
  "guard_partitions": [],
  "metric": "sum",
  "column": "Signed units",
  "op": "==",
  "bound": "0",
  "timing": "deferred"
}

此範例是完整 rules 清單中的一項，使用 integer 或 decimal 儲存欄位。平衡 Command 中途可暫時偏離零，但最後必須回到零；單獨的不平衡新增仍會被拒絕。

欄位	契約
`group_by`	必填，0–4 個不重複的儲存 scalar 或 cardinality-one 原生 link 欄位；空清單代表整張表一組
`guard_partitions`	選填，必須解析成與 `group_by` 完全相同、順序相同的欄位 key；省略就用相同 key，包含 `[]`
`metric`	`sum` 或 `count`
`column`	Sum 必填，只能是 integer／decimal；count 不得設定
`op`	`<=`、`>=` 或 `==`
`bound`	精確整數或一般 decimal 字串、數值群組 key `$row.<column>`，或 `{link, column}` 連結上限
`timing`	`immediate`（預設）或 `deferred`
`when`	選用參與條件，最多五個，沿用一般規則 predicate 契約

群組支援 string／text、integer／float／decimal、boolean、select、date／datetime、user／social_client／principal scalar 與 single-link。計算值、JSON、附件、multi-select、interval、many-link 不能當群組 key；float 可分組，但不能作精確 sum 欄位。Decimal bound 最多 65 位數、18 位小數。$row bound 必須指向 integer／decimal 群組 key，不能任選列值。Linked bound 的 link 必須本身就是 cardinality-one 群組 key；column 指向同範圍、有效目標的 integer／decimal 欄位。REST 接受顯示名稱或 internal key，儲存正規化後的 key。

群組保留 scalar 型別、空白與 null，不全部轉成文字。Link 群組 key 必須解析到恰好一筆有效目標。Count 計算有效參與列；sum 使用精確算術，隱藏列也會納入。移動列或改變參與條件時，舊群組與新群組都要檢查；刪除列也可能違反下限或等式。

守衛採用持久化的 generation 與群組錨點，連空群組及新群組也涵蓋，避免租戶參照圖中的 phantom 成員變化。舊／新群組與 linked-bound 供應端仍依確定順序受保護。guard_partitions 不是任意鎖分片、分組欄位的子集，也不是應用程式自訂的鎖識別。

所有寫入途徑與最終狀態邊界

共用規則與參照保護涵蓋新增／更新／刪除、restore／revert、原生 link 變更、import／bulk／publish、callback／trigger、Command 與審批寫入。Bound 目標的編輯／刪除與 schema 相依也受約束；不能藉修改父表上限繞過子表彙總。檢查使用鎖定後的目前群組狀態，不使用先前用戶端總計。

immediate 每次寫入都檢查；deferred 收集受影響群組，在 一次原子 Command 或暫存世代啟用的最終狀態、commit 前檢查，包含 Command 審批重播。離開這兩種邊界仍立即檢查。它不會把整個排隊 bulk job 變成同一個延後交易，也不豁免其他規則的逐步檢查。另見暫存世代。

規則預覽與宣告 admission 使用 prospective state，包含現有有效列；不能直接安裝已經違反的政策並當成有效。預覽僅供參考，之後寫入仍須通過目前鎖定檢查。PUT rules 仍取代完整清單、最多 10 條規則，請保留既有規則與 ID。

拒絕與 IaC

群組違反時回不洩漏數值的 409：


{"detail":{"error":"aggregate_limit_violation","rule_id":"rule_3f9a1c2b7d4e","message":"Aggregate constraint cannot be satisfied."}}

不揭露群組總計、bound 值或隱藏列 ID。Aggregate guard 改變可用相同代碼，訊息為 Aggregate guards changed; retry the operation. 宣告不合法使用規則驗證器的 field／message／hint 400 契約；請求形狀驗證可能改回 422。Command／IaC wrapper 保留各自錯誤 envelope，不能假設每個介面都原樣回傳上述 REST 結構。

IaC rule 行的 group_by、guard_partitions、sum column、$row bound 與 linked-bound 欄位使用 column ref；linked bound 經宣告的 link 解析目標。Plan、apply、export 都會轉譯這些 ref。CT schema 呈現與工具指引列出此規則；此來源 build 沒有獨立宣告 ct.aggregate_limit capability ID。另見規則參考、IaC rule 行與凍結提案。