Documents

The four essential parts

1. Participants

Who is involved. Participants enter the document through channels bound to timeline-backed identities.

2. State

What is true right now: fields, nested objects, references, status, counters, and business facts.

3. Rules / contracts

How the document responds to actions: operations, workflows, policies, triggers, and processing checkpoints.

4. Record

The actions that caused the current state. These come from timelines and become part of the evidence.

Anatomy of a Blue document

At the top level, a document is a typed, structured node. Common fields include:

• name — a human-friendly label.
• type — the document's primary type, often a reference into repo.blue (e.g. Common/Record).
• kind — an optional sub-type used by some patterns (e.g. Shopping Order).
• Business fields — your domain content (counters, statuses, amounts, references).
• contracts — a map of named contracts: channels, operations, workflows, markers.
• Anchors / links — references into related documents (BlueIds or session ids).
• Channel bindings — bind contract channels to specific timelines or actors.

State and contracts are deliberately separated. Business fields hold what is currently true; the contracts map says what can change and how.

A minimal static document

Pure content, no rules:

name: Order — Tulip Bundle
type: Common/Record
kind: Shopping Order
status: pending
buyer:
  accountId: buyer-1
seller:
  accountId: seller-1
total:
  amount: 14500
  currency: USD

This is a perfectly valid Blue document. It has identity, type, and state — but no behavior.

The same document, with contracts

Add contracts to make it interactive:

name: Order — Tulip Bundle
type: Common/Record
kind: Shopping Order
status: pending
buyer:
  accountId: buyer-1
seller:
  accountId: seller-1
total:
  amount: 14500
  currency: USD

contracts:
  buyerChannel:
    type: Conversation/Timeline Channel
    timelineId: buyer-1
  sellerChannel:
    type: Conversation/Timeline Channel
    timelineId: seller-1

  acceptOrder:
    type: Conversation/Operation
    channel: sellerChannel

Now the document is no longer only content. It is an interaction surface: the seller channel can send acceptOrder requests, and a workflow contract — when added — turns those into state changes.

Documents evolve

A document changes when:

• a participant posts an entry to a timeline bound to one of the document's channels
• a workflow runs in response to that entry
• state updates are applied via a deterministic patch
• linked documents trigger new steps

You can watch one document evolve in the document stepper.

Documents may reference other documents

This is how composition works:

• an order references a payment
• a payment is governed by a PayNote
• an agent acts through a mandate
• a service document is linked into a business space

Why this matters

Most software puts state in one place, workflow in another, permissions elsewhere, identity elsewhere, audit trail elsewhere. Blue brings those back together at the interaction level.