Solutions — what a client buys
In plain language
A client buys a Solution — nothing else is sold. A Solution is a named package: one client, a set of Capabilities pinned to specific published versions, and the client's own configuration. It carries the entitlements, exposure through our API, the billing rollup and the operational status. Because every run, cost record and ledger entry is attributed to its Solution, the question "what did this Solution do for us last month, and what did it cost" is answered by reading the record, not by estimating.
The mechanism
Solutions are the sole commercial object (ADR-0028). Skills, Recipes, Capabilities and Desk-archetype Capabilities remain construction and product units; none is sold standalone. The ratified definitions:
- Skill — atomic platform behaviour: one locked primitive plus bindings.
- Recipe — a reusable workflow composed of Skills.
- Capability — a publishable, versioned executable behaviour unit.
- Desk — a governed Capability archetype for professional work: a routed shape (interpret → route → behaviours), a governance envelope (review policy, delivery binding, deliverable schemas, corpus), and a durable, multi-turn, human-approval-gated session operation model (ADR-0027).
- Solution — the sold package: a named binding of one client tenant to a set of Capability references and their per-client configuration.
A Solution is packaging, never runtime. It does not orchestrate; the Capabilities it packages execute.
The Solution record (ADR-0041). solutionId, name, description,
clientTenantId, classification, status (ACTIVE | SUSPENDED |
RETIRED), components[], webhookUrl, webhookSigningSecret,
configVersion, timestamps. A component is a reference to a published
Capability — for Desk-shaped components, a reference to its configuration
row, never a copy.
Version pins are mandatory. A component binding carries an explicit published capability version. Silent drift with a moving active pointer is not an allowed default: what a client's Solution runs is exactly identifiable, and changes are deliberate.
solutionId attribution is server-side. Resolved from tenant +
capability + entitlement — never caller-supplied — and stamped on every run,
cost record and ledger entry. Proven live: a single run attributed
end-to-end across run record, cost record and ledger.
Environments. The axis and the names draft / canary / prod are
ratified; prod is instantiated today, with canary and eval-gated
promotion designed to land on the same axis.
Lifecycle is governed. solution.provision, solution.suspend,
solution.restore and solution.retire are registered operations of the
kernel — dry-run, approval, execute, verify, ledger. A retired Solution
persists as the commercial record of what was sold, with its webhook
signing secret removed; the ledger points at it by id, so it is never
deleted.
Customer visibility. A client sees their named Solutions grouping the
surfaces they already have — runs, entitlements, name, status, description
— never internal bindings or configuration. The customer dashboard
(/customer) provides sign-in, entitlements, runs, subscription and team
management per tenant.
Commercial state machines are independent (I-23, I-24). Subscription (the commercial relationship), Entitlement (access to a specific Capability) and tenant access (active / suspended) are separate; an operator can suspend access without cancelling commercial state and vice versa. Stripe ingress, processing and reconciliation functions handle billing events through the same verified-webhook and idempotent-job path as everything else.
Design notes
- Why Solutions only (ADR-0028). The commercial object had been implicit — entitlements and credentials were capability-grained, the storefront said "Desk", and no single identity existed that a client could buy, hold or call. The pull arrived when API-served Solutions, the external consumer and the landing page all needed one thing to name.
- Why Desks are Capabilities, not a layer above (ADR-0027). A manufactured Desk is its capability plus an envelope and a session model; framing it as a separate object above Capability fought the substrate. Solutions are the packaging layer; Desks inhabit the layer below.
- Why pins and server-side attribution (ADR-0041). A Solution must answer "what exactly ran" and "who is this for" from the record alone.
Sources
matterandgas-com/docs/adr/0026,0027,0028,0041.matterandgas-com/amplify/custom/solution-record.ts.matterandgas-com/infra/scripts/_lib/operations/solution-provision.ts.matterandgas-com/app/customer/.