The product

The Governed Operation Kernel

In plain language

Nothing on the platform changes silently. Every production change — provisioning a Solution, granting access to a corpus, republishing a prompt, retiring a client — is a registered operation that first shows exactly what it would do, waits for a named person to approve that exact plan, executes, reads everything back to verify, and writes one ledger entry. Machine actors, including AI assistants, may plan; only humans approve. This is the page that explains why the platform can be operated by a small team at scale, and why an operation that cannot tell which table it is pointed at refuses to run rather than guess.

The mechanism

The operation contract (ADR-0040). A governed operation implements one interface: validate (structural, before any client is built), readLiveState (reads only — the single point where live state enters), plan (pure: no I/O, no clock, no randomness; same inputs → same plan), describe (renders the standard dry-run envelope), execute (the only writing member), verify (reads everything back; throws on mismatch; not optional), optional inverse, and idempotencyKey. Nothing writes to governed state except through a registered operation.

The dry-run envelope. One shape for the CLI, Studio and any future UX: operation name, planId, planHash, expiry, approval class, blast radius, rollback posture, willWrite, the list of planned changes with field-level before/after diffs (secrets redacted at plan time), warnings the approver must see, and deterministic refusals (non-empty means execute is unreachable). willWrite: false is a first-class outcome — convergent re-runs are the norm and are cheap and silent.

Approval classes, enforced by the kernel.

The class is a property of the operation, checked at registration; an operation that writes production state but declares draft-write is a registration error, pinned by test.

Machine actors propose; humans approve. An LLM-driven UX may validate, read, plan and describe freely — all read-only — and may never invoke execute on an operation whose class requires approval. The gate lives in the kernel, so every new client inherits it.

Blast radius and rollback are declared. none / single-solution / single-tenant / platform-wide; and inverse-operation, convergent-rerun, forward-only (with rationale) or irreversible (with rationale). An operation that cannot state its rollback posture is not admissible; the approver sees the exit before the entry.

Stale plans refuse. Every plan carries its own hash. execute re-reads live state and re-plans; if the fresh planHash differs from the approved one it refuses with PLAN_STALE rather than writing. The clock is captured once per run so a re-plan of an unmoved world hashes identically. This is what makes queued approval safe later without changing the contract.

Idempotency and ledger. The kernel wraps execute in the substrate's idempotency primitive and appends exactly one ledger entry per writing execute (a no-op appends nothing). Authorisation is checked at the kernel boundary against the caller's tenancy role and the approval class before any live state is read.

Ambiguity is a refusal. Table and stack discovery refuses when a logical name resolves to more than one physical target. Governed writes do not guess which store is the live commercial surface; the operator pins the target from the deployed configuration. That refusal is the feature — it is what stops an audit entry being written to the wrong table and splitting the trail silently.

Operation batches. A many-operation command envelope that is explicitly not a transaction: each operation's outcome is recorded individually so a partial outcome always has a durable record.

Registered today: solution.provision, solution.suspend, solution.restore, solution.retire, desk.configure, knowledge.grant, knowledge.revoke, entitlement.repair-grant-fields, capability.seed, prompt.author, prompt.republish, onboarding.seed. The CLI is a thin client of the same registry — never a second implementation; a plan-equivalence test asserts that the CLI and our API produce byte-identical plans for identical input.

Design notes

• Why harvest rather than build (ADR-0040). The forcing function was the platform audit: "MaG can build one Solution superbly and perhaps thirty acceptably. It cannot build thousands, and the binding constraint is not capability — it is that every governed write is a human running a script." The scripts already implemented the right contract by hand, in four places; the kernel gave it one shared shape.
• Why plan must be pure. It makes the plan unit-testable without AWS, makes the dry-run trustworthy (the thing rendered is the thing executed), and makes replay meaningful.
• Why one implementation, many clients. Porting a script to our API without collapsing the CLI onto the same path would create two code paths that diverge, and the divergence would be discovered in production.

Sources

• matterandgas-com/docs/adr/0040-governed-operation-kernel.md.
• matterandgas-com/infra/scripts/_lib/operation-kernel.ts, operation-registry.ts, operations/.
• matterandgas-com/docs/runbooks/provision-a-solution.md, offboard-a-client.md, seed-operations-env-pins.md.