Build a Blue solution from a real process

1. Write the ordinary story first#

Describe the process in language the participants would use. Name the people and organizations, the desired outcome, material commitments, approvals, external facts, money movement, exceptions, and disputes. Do not begin with YAML or a package name.

For example:

A customer asks an agent to find a flower-and-dinner package. Alice and Bob each control their own capacity and confirmation. The customer's card may be authorized early but captured only after both merchants confirm. A cancellation before confirmation releases the payment. Material substitutions require the customer.

2. Identify document boundaries#

Create a separate document when the participants, authority, lifecycle, visibility, provider trust, retention, or scaling boundary differs.

A likely network is:

Standing merchant Agreement
    └─ authorizes creation of one customer Order
Order
    ├─ links Alice and Bob confirmations
    ├─ links or owns one PayNote occurrence
    └─ may request a substitution process
Customer-agent Mandate
    └─ authorizes one bounded ordering or scheduling operation

Do not flatten a continuing Agreement, one Order, one payment process, and one authority grant into a single mutable object merely because they are related.

3. Separate terms, processes, and provider truth#

• Terms preserve complete human meaning.
• Processes operationalize selected deterministic meaning.
• Provider facts establish external outcomes such as identity, permit state, delivery, or money movement.

A payment request is not proof of payment. A delivery claim from an untrusted payload is not a delivery fact. An agent's presence is not authority. Each claim must come from the role that can credibly make it.

4. Define the smallest operations#

Each operation should name:

• the document role whose authority it exercises;
• the request shape;
• preconditions on current state;
• the deterministic patch and emitted events;
• actor/source policy where relevant;
• whether a Mandate can authorize another actor to exercise it.

Prefer several narrow operations over one generic updateDocument capability.

5. Model Requests and Responses across boundaries#

Use a Request when another participant or provider must decide or perform work. Use a Response that points to the exact Request occurrence. Keep commercial obligation, data access, authority to respond, and provider result separate.

A provider should independently discover and verify its applicable Mandate. An untrusted requester should not select the authority artifact the provider must trust.

6. Design agent authority explicitly#

For each agent action ask:

• Which exact agent and runtime is attributed?
• Which principal or organization is represented?
• Which document, channel, and operation are targeted?
• What request values and document states are allowed?
• Who confirms the authority relationship?
• When does the Mandate become Active?
• Who can terminate it and how quickly does admission stop?
• Which actions remain principal-only?

Use a KYA provider or another accepted Timeline provider to record operation-level attempts and admission decisions. Let the target feeder verify independently.

7. Define the proof scene before implementation is complete#

A useful Playground story should include:

1. the initial document network;
2. one direct human or provider action;
3. one agent attempt without authority;
4. Mandate confirmation and a valid delegated action;
5. one out-of-scope or stale-state denial;
6. one external provider Response;
7. a deterministic consequence;
8. an authority termination or business exception;
9. a final causal audit.

This forces the architecture to explain both success and non-action.

8. Label maturity honestly#

A polished example is not automatically a released interoperability profile. Mark each package and scene as stable, draft, architecture-stage, design-stage, product-specific, or planned. Link exact semantics to repo.blue and normative specifications rather than restating them as marketing prose.

Design review questions#

• Which system currently owns the truth only because its private database says so?
• Which external facts require a named institution or provider?
• Which actions may an agent perform, and which must remain principal-only?
• Which relationships deserve separate documents?
• What is the safe outcome when evidence is missing?
• Can two independent implementations replay the same admitted history?
• Can the UI explain why nothing happened?