The Constitution — 31 invariants

In plain language

The platform has a written constitution: thirty-one statements of what is architecturally settled, each with a stable identifier (I-1 … I-31). They are binding on every piece of code and every design decision. They can be changed only by an explicit, dated decision of the CTO through an architecture decision record — never by an incidental edit. Every other architectural document cites these identifiers instead of restating the doctrine.

For a client, this is the page that says what will not change under them: what a Capability is, that published versions never change, that their data is theirs, that every run is on the record, that a bill is bound to the cost recorded at the time.

The invariants below are quoted from the constitution. The one-line "why" under each group is the reasoning recorded with them.

The product object

I-1. Capability is the customer-facing unit of value. Customers do not invoke workflows, skills, prompts or models. They invoke Capabilities.
I-2. Capability is the primary product object. All operator-facing surfaces are organised around Capabilities. All commercial entitlements are scoped to Capabilities.
I-7. Capabilities are composed of Skills. A Capability Version specifies a flow over Skills. A Skill is a primitive-locked building block.
I-8. Skill primitives are a closed enumeration owned by the platform. Operators do not author new primitives; they author Skill instances bound to one primitive.
I-9. Skills bind Components. A Skill's behaviour depends on its bound Components (Prompt, Knowledge), Models and Tools.
I-10. A Component is reusable across Skills. A Skill is reusable across Capabilities.
I-30. Matter & Gas owns the Capability concept. Magpie does not. Capability identity is injected into Magpie's execution model and consumed as opaque parameters.

Why: one product object, composed from reusable parts over a closed set of primitives, is what makes Solutions buildable by composition and measurable as a unit.

Immutability and pointers

I-3. Capability Versions are immutable. Once a Version exists in the substrate, its content does not change. Edits produce a new Version.
I-4. Publications are immutable. A Publication binds a Version to an environment at a point in time, recorded once and never amended.
I-5. The active Version of a Capability is a pointer, not a state of the Version itself. Activation moves the pointer; it does not modify any Version.

Why: immutable versions plus movable pointers is what makes promotion and rollback safe and every past run reconstructible — the thing that ran is still exactly there.

Tenancy and identity

I-6. Every Capability is owned by a single tenant. Tenant is the customer-isolation boundary; cross-tenant ownership does not exist.
I-26. Tenant is the customer-isolation boundary. Every substrate row that could carry customer-derived state carries tenantId.
I-27. Caller is the audit identity. Every architecturally meaningful action records who triggered it.

Why: isolation is a property of every row, not a filter added at the edge.

Execution truth

I-11. Every Capability invocation produces exactly one Run. A Run is the canonical execution fact.
I-12. Every Run carries a stable, correlatable identity end-to-end — from invocation through every action, measurement, audit row and operator surface.
I-13. Every emitted measurement identifies (Capability, Run, ActionInstance, MeasurementKind). Producers that cannot satisfy all four fields must not emit; the failure surfaces as a reconciliation candidate, never a silent skip.
I-16. Execution success never depends on metering success. Cost emission, telemetry capture and audit writes are failure-isolated. A degraded measurement path produces honest gaps in visibility; it never blocks a customer invocation.
I-17. Capability Usage Events are append-only and correlation-keyed. The same correlation id produces the same row exactly once.
I-18. Cost Records are append-only. Corrections are new rows referencing the original.
I-19. The audit ledger is append-only. Every architecturally meaningful change writes a ledger entry. The ledger is the canonical history.
I-20. Replay is a first-class capability of the platform. Runs can be reconstructed from substrate alone; the substrate carries enough identity, ordering and content-hash data to make replay deterministic.

Why: an append-only record with a stable identity through every layer is what lets the platform answer "what happened, and what did it cost" months later without trusting anything but the record.

Actions and review

I-14. The Action Layer is closed at the primitive level. Today: Generate, Tool, Human Review. Future Action types extend the layer through the same generic measurement runtime; they do not bypass it.
I-15. Human Review is an Action. It is not infrastructure. It carries the same identity, measurement and audit posture as machine Actions.

Why: a closed action vocabulary is what makes every effect — including a person's decision — measurable and auditable the same way.

Evaluation, knowledge and memory

I-21. Evaluation is a first-class capability of the platform. Test Cases and Test Suites are versioned, hashed and replayable. Publication Evidence depends on Evaluation outcomes.
I-22. Knowledge and Memory are distinct subsystems. Knowledge is operator-curated content available to many Capabilities. Memory is tenant-scoped state accumulated over time. They do not merge.

Why: publication gated on hashed evidence is what makes a change to a running Solution a decision with a record, not an edit.

Commercial

I-23. Subscription and Entitlement are independent state machines.
I-24. Tenant access (suspended / active) is independent of Subscription state.
I-25. Pricing is bound at write time, not at read time. Cost Records are stamped with the rate in effect when the cost is recorded; later rate changes do not retroactively re-price.

Why: a bill is a projection of facts that were true when they were recorded.

Surfaces

I-28. Operator surfaces never expose substrate vocabulary. Table names, column names and internal enums are firewalled from operator surfaces.
I-29. Never synthesise values to fill operator surfaces. When runtime truth is absent, the surface shows the absence honestly. Null is a correct value.

Why: a number on a screen is either a fact from the substrate or an honest blank — never an estimate dressed as a fact.

The substrate boundary

I-31. Magpie's substrate is consumed, not modified. Matter & Gas does not extend Magpie's ledger schema, run schema or executor. New behaviours compose around Magpie, not inside it.

Why: a substrate nobody patches is a substrate whose guarantees hold for every consumer.

How the constitution is governed

The document is versioned (currently v1, effective 2026-06-29) and may be modified only through explicit CTO disposition, with rationale, affected invariants, compatibility assessment and effective date.
Architectural authority cascades: Architectural Truths → accepted ADRs → construction architecture → product experience architecture → UX architecture → design specifications → implementation. A lower layer that contradicts a higher one is presumed in error.
Every architectural document declares itself Normative, Informative or Exploratory; only Normative documents may establish or modify invariants.

The substrate has its own constitution beneath this one — the Magpie architecture constitution — where every invariant names its mechanical enforcement: a CI gate, a deploy gate, a test requirement, a schema check, a lint rule, an infrastructure assertion or a runtime guard. Its preamble states the rule this whole site follows: invariants without enforcement are not invariants; they are aspirations.

Sources

matterandgas-com/docs/architecture/architectural-truths-v1.md — the constitution, quoted.
matterandgas-com/docs/adr/0025-architectural-constitution-governance.md — how it is governed.
magpie/docs/architecture-constitution.md — the substrate constitution and its enforcement vocabulary.