Lesson 0045 · Initiative Lead · Module 2
Design State, Data Ownership, and Contracts
Most integration bugs are unanswered state questions wearing API syntax. Model transitions, ownership, failure, and change before polishing endpoints.
Mission tie-in: data is the durable part of a system. A lead makes its invariants, writer, lifecycle, and compatibility explicit before code makes accidental promises.
Knowledge: state first, transport second
“Return status” sounds like a field. It is actually a state machine with allowed transitions and actors:
| From | Command | To | Rule / owner |
|---|---|---|---|
| — | request return | pending decision | Journey creates one request per intent. |
| pending decision | record eligibility | approved / refused | Eligibility owns decision and reasons. |
| approved | attach label | ready to ship | Journey accepts one carrier label. |
| ready to ship | record receipt | received | Warehouse event must match item. |
| received | record settlement | refunded | Payments owns settled-money truth. |
The state machine answers what is legal. Data ownership answers who may establish each fact. Prefer one authoritative writer for a piece of state; other modules receive a contract, event, or read model. A shared database does not require shared ownership. If both Journey and Payments can set refunded, the invariant lives nowhere.
For every command, API, or event contract, answer:
- Meaning: command, fact, or query? What business promise does success make?
- Identity: what identifies the resource and the user's intent? How are retries deduplicated?
- Validation and authorization: which edge rejects malformed data, and which domain rule refuses valid-but-forbidden behavior?
- Failure: timeout, unavailable dependency, conflict, partial success—what may the caller safely do?
- Compatibility: which fields are required, what may be added, how will consumers migrate, and when can old behavior be removed?
- Lifecycle: classification, encryption, retention, deletion, audit, and who may read it.
Design retries with an idempotency key representing one intent. A client retry after timeout must return the original return and label, not create another. Design consumers as tolerant readers, and evolve persisted data with expand/contract. Compatibility is a delivery feature, not cleanup.
Draw data flows across trust boundaries and minimize data early. The carrier needs recipient name and address for a label; it does not need return reason notes or order history. Record retention and deletion in the model, not only a policy document.
| Question | Bad default | Designed answer |
|---|---|---|
| Who may move this state? | Anyone with database access. | One command owner enforces transitions. |
| What did timeout mean? | Assume failure and repeat. | Retry one intent idempotently. |
| Can a field disappear? | Coordinate a big-bang deploy. | Expand, migrate readers, contract. |
| Why retain this PII? | Storage is cheap. | Purpose, duration, deletion owner. |
Skill: locate the durable promise
Who should set “refund settled”?
An idempotency key should identify:
When should privacy enter the design?
Practice: review one critical state transition
Draw the state machine for one initiative entity. For every transition, name command, actor, rule, owner, emitted fact, retry behavior, and audit need. Then choose one cross-boundary contract and document its meaning, failure semantics, compatibility policy, PII, and a contract test.
Reveal: the contract review test
Ask the producer and consumer separately what success, timeout, duplicate, missing field, new field, and deleted user mean. Any different answer is already a production defect; the code has merely not executed it yet.
Your win
You can design a system's durable promises: legal transitions, authoritative writers, safe retries, evolvable contracts, and purposeful data lifecycles.
Read and watch deeper
- Designing Data-Intensive Applications, Kleppmann — ch. 4 and 8: evolvable data, partial failure, and distributed-system ambiguity.
- Domain-Driven Design, Evans — entities, aggregates, repositories, and context boundaries as consistency tools.
- OWASP Threat Modeling Cheat Sheet — model data flows and trust boundaries early, then ask what can go wrong.
- Reference: Initiative Playbook · state and contract review.
Ask your agent-teacher to generate adversarial sequences—duplicate, reorder, timeout, stale read, unauthorized identifier—then decide which your contract prevents or absorbs.