Capabilities

A capability is the overlay's first-class engineering primitive: a durable, implementation-independent statement of what the system can do. It is what you build, what a business process requires, and what a system provides. It says nothing about how — no aggregate, no command, no table — only the capability itself.

Here is the entry point to Chowk's revenue path:

capability OrderCheckout {
  title     "Order checkout"
  value     "A customer opens an order with its first line in one transaction — the entry point to the marketplace's revenue path."
  doc       "Places an order (born PENDING) and adds its first line atomically via the Checkout saga, announcing OrderPlaced so fulfillment can react. The one moment that turns a browsing session into revenue."
  consumers [platform.v1.Customer]
  maturity  "beta"
  labels {
    domain:  "ordering"
    surface: "customer"
    stage:   "checkout"
  }
}

The authoring convention: value, doc, consumers, maturity, labels

A capability is small but disciplined. Each field answers a specific question, and keeping them consistent is what makes a catalog of capabilities readable as a whole:

Splitting value (why) from doc (what/how) is deliberate: a reader scanning the catalog for what the product is worth reads only value; a reader who needs the mechanism drops into doc.

Maturity is a claim the compiler can falsify

maturity looks like a label. It is closer to a promise, and six words are the ones that make it one:

beta   ga   stable   released   production   general_availability

These are strong maturities — words that assert the capability is ready, not merely that it exists. Anything else, including planned, alpha and any word you invent, is a weak claim: a statement of intent.

The distinction matters because the compiler derives an obligation set from your model — every falsifiable statement it makes about runtime behaviour, from each guard and each constraint to each route contract — and then checks your maturity claim against how many of those obligations are actually verified by a test run. The four outcomes:

Read the asymmetry: a modest claim with thin evidence is fine, because alpha never promised otherwise. A strong claim with thin evidence is the one thing the report calls out, because that is the only case where the model is telling a reader something untrue.

⚠️ Choosing your own vocabulary opts you out of the check. An unrecognised token is treated as a weak claim — deliberately, so that a report cannot cry wolf over a word you never meant as a readiness assertion. But it also means that inventing shipped or v1 buys you a maturity nothing will ever verify. If you want the claim checked, use one of the six.

Claim alpha until the obligations are verified. It costs nothing, it is accurate, and the report will tell you the day you have understated yourself.

capability is not kind capability

These look alike and are unrelated:

• capability OrderCheckout { … } — a first-class capability: a unit of what the product can do.
• system OrderingSystem { kind capability … } — the word kind capability classifies a system node as a logical system (as opposed to an infrastructure kind like database or event_bus; see Systems).

A system whose kind is capability is the thing that provides first-class capabilities. Don't let the shared word confuse the two: one is the demand primitive, the other is a node type.

Composite capabilities

A capability can be composed of others. Chowk rolls the three order-lifecycle leaves into one composite so a surface or a business process can reason about "the whole order lifecycle" rather than one leg:

capability OrderManagement {
  title       "Order management"
  value       "The entire order surface a customer operates — opening an order, paying it, and tracking it — as one capability the storefront can reason about."
  doc         "The roll-up of OrderCheckout + OrderPayment + OrderTracking."
  consumers   [platform.v1.Customer]
  composed_of [OrderCheckout, OrderPayment, OrderTracking]
}

A composite declares no maturity of its own — it would be meaningless. Its maturity and its roll-up are derived from the leaves it contains. (Declaring a maturity on a composite is a validation error.) Composition must also be acyclic.

Forward-looking capabilities — the plan before the build

A capability can be declared before anything provides it. That is not an error — it is how you model the plan ahead of the build. Chowk declares the return flow long before the domain model for returns exists:

capability OrderReturn {
  title     "Order return"
  value     "A customer requests a return on a delivered order and is refunded — closing the post-purchase loop."
  doc       "Not built yet: the intended flow is a return request against a delivered order, a refund, and a restock."
  consumers [platform.v1.Customer]
  maturity  "planned"
}

Because no system provides OrderReturn, any business_process step that requires it reconciles as a capability-backlog item — an informational finding, not a failure. The capability sits on the backlog until a system supplies it, at which point it reconciles automatically. This is what lets you author a whole intended flow (the demand) before building the supply. See Reconciliation & the backlog in the Business Process & Journey Modeling manual.