Choose Resource Identity Model
BOUNDARY-CHOOSE-RESOURCE-IDENTITY-MODEL
Summary
Decide whether the boundary mutates records, sets, files, sessions, handles, or whole documents before designing reconciliation. The chosen unit controls idempotency, matching, conflict handling, and the cost of later migration.
Rule
Choose the resource identity model up front.
Why
A system that mutates individual records behaves differently from one that mutates record sets, files, sessions, handles, or whole documents. The identity model determines idempotency, matching, update strategy, conflict handling, and error recovery.
Helps
- Prevents reconciliation bugs caused by comparing or mutating the wrong unit of state.
Limits
The model can evolve, but changing it after callers depend on it is often a breaking API or migration. Choose deliberately at the boundary before broad propagation.
Agent Instruction
Choose the resource identity model up front because a system that mutates individual records behaves
differently from one that mutates record sets, files, sessions, handles, or whole documents.Mechanisms
Supported by resource ID types, API docs, reconciliation tests, provider fixtures, and update functions named after the unit they mutate.