Contract Checklist

Shared reference for architect-agent and implementer-lead-agent.

Resolve all applicable questions before finalizing any API or database contract. Unanswered questions are silent drift points between phases — document your resolution even when the answer is "not applicable," so downstream agents can verify rather than guess.

---

1. Entity Lifecycle

• Does this entity exist independently, or only as a child of a parent?
• Can it be created without a parent reference?
• What happens on parent deletion: cascade delete, orphan (set null), or block?
• Who creates the entity — only through a parent endpoint, or via a dedicated child endpoint?

2. Payload Shape for Master-Detail

• Does the UI edit the parent and its children in one form submission, or independently?
  • One form → nested payload (children array inside the parent body) is natural.
  • Independent management → separate child endpoints are correct.
• If a parent update endpoint accepts child mutations in the same payload, what are the semantics: replace-all, or explicit add/update/delete per child?
• Decision depends on the interaction model — resolve before defining the endpoint.

3. Ownership and IDOR Risk

• Which field establishes ownership (e.g. user_id, org_id, tenant_id)?
• On write operations: is ownership enforced server-side from the authenticated identity, or trusted from the payload?
• On nested updates: can the payload change a child's owning parent?
  • A PUT on parent A containing a child currently owned by parent B is an IDOR vector — explicit defense required.
• On bulk or indirect updates: are all child records re-verified to belong to the same owner as the parent before mutation?

4. Idempotency and Retry Behavior

• Is this endpoint safe to retry (idempotent)?
• If yes, how is idempotency enforced: idempotency-key header, dedup by business key, or upsert semantics?
• What is the response on a duplicate submission: 200 with the original result, 409 Conflict, or 204 No Content?

5. Delete Behavior

• Soft delete (flag + timestamp) or hard delete?
• On soft delete: are soft-deleted records excluded from list and get queries by default?
• On hard delete: which FK constraints cascade? Which block deletion?
• Are cascades explicit in migrations, or enforced in application code?

6. Aggregate Update Diff

When a payload updates a collection (e.g. children array inside a parent PUT):

• Existing children: carry their id field.
• New children: no id (server assigns on creation).
• Deleted children: omitted from the array (replace-all semantics) OR included with _destroy: true (explicit delete semantics).

Which semantics does this contract use? Document it explicitly. If IDs are absent on existing children, the server cannot distinguish an update from a delete + recreate — this must be resolved before implementation begins.

7. Pagination, Filter, and Sort

• Maximum page size? Default page size?
• Which fields are filterable? Any requiring a database index to be viable?
• Which fields are sortable? Default sort order and direction?
• Cursor-based or offset-based pagination?

8. Versioning

• Is this endpoint versioned (e.g. /v1/, /v2/)?
• If extending an existing versioned API: does the addition belong to the current version or require a new version?
• What is the deprecation policy for the version being extended?

9. Error Response Shape

• What is the exact JSON shape for all error responses?
• Are validation errors per-field ([{ field, message }]) or a single aggregate message?
• What is the error-code vocabulary: string codes (e.g. validation_error) or numeric?
• Does the response body structure differ between 4xx client errors and 5xx server errors?