Maker-Checker
Maker-Checker is the platform's structural answer to high-stakes write authorisation: it separates the actor who proposes a change (the maker) from the actor who approves it (the checker), and it enforces that separation in the platform rather than in application code that can be forgotten or bypassed.
It serves two related concerns:
- Destructive single-action gating. Actions like a custody downgrade, a project deletion, or a key zeroize cannot be undone — even a fully authenticated, authorised admin should not be able to perform them with a single click. The
IRREVERSIBLE_ACTION_GATEfamily enforces a multi-signature loop. - Multi-row data-write approval. Operational workflows — expense sign-off, content publishing, regulated record changes — route proposed writes through approvers before they commit.
Both are configured as rules inside the project's policy bundle — the single versioned policy document (pol_<base62>) that also holds RLS and storage rules, moving through the draft → publish-pending → active → archived lifecycle described in Guides → Unified Policy §7. A gate or approval configuration can't be edited in place once its bundle is active; a change is a new draft, published (itself gated) to supersede the old bundle.
This guide is the conceptual model. For the canonical rule syntax, gate-token endpoints, and approval-queue API, see API → Control.
1. The IRREVERSIBLE_ACTION_GATE family
The gate family applies to platform-destructive actions where an incorrect or unauthorised execution cannot be rolled back:
| Action | Why it's gated |
|---|---|
| Custody downgrade (HYOK → BYOK, BYOK → SKR, SKR → Platform-Managed) | Surrenders custody to a weaker mode; recovery requires re-uploading key material under the old mode, which may be operationally impossible |
| Project KEK zeroize | Crypto-shreds the project's key-encryption key, rendering every secret and encrypted record under it unrecoverable |
| Residency region removal | A zero-residue erasure of one jurisdiction's data from the project's residency set |
| Audit-retention reduction | Shortening the window deletes historical evidence permanently — an attacker who reduces it erases the record of their own act |
| Extension purge | Destroys the extension's per-project schema and all extension-owned data |
Each gate is parameterised by its approver requirements: how many signatures (minApprovals), which approvers are eligible, and which distinctness constraints apply. The approver constraints — not_originator, not_subject_of, distinct_from, role_required, group_required — are the same JSON-policy vocabulary RLS uses; the language stays one. For the record-of-authority actions above, the platform enforces a floor a caller cannot weaken: not_originator and at least one approval are mandatory, so a self-approval can never hollow out the maker-checker guarantee.
Gate-evaluation failures surface as specific codes: an approver failing a constraint returns K9O_GATE_CONSTRAINT_VIOLATION; a chain that doesn't meet the mandatory floor returns K9O_GATE_CONSTRAINT_POLICY_VIOLATION; an invalid or expired token returns K9O_GATE_TOKEN_INVALID; a rejected gate returns K9O_GATE_REJECTED; a scope mismatch returns K9O_GATE_ACTION_SCOPE_MISMATCH; and an unknown token returns K9O_GATE_NOT_FOUND.
1.1 The gate-token lifecycle
Triggering a gated action creates a gate token representing the in-flight request. Its status moves through:
pending_approval ──▶ approved ──▶ redeemed
│
├──▶ rejected (an approver rejected it, with a comment)
├──▶ expired (the approval window elapsed)
├──▶ cancelled (the requester or an admin withdrew it)
└──▶ superseded (a newer request replaced it)
- The requester calls the gated action; the platform records a token carrying the action context, the requester's identity, and the chain configuration.
- Eligible approvers review it — via the Console or the SDK — and approve or reject. A rejection carries a comment saying what to change. Each approval is checked against the chain constraints and recorded.
- Once
minApprovalsvalid approvals land, the token isapprovedand redeemable. There is no automatic execution and no cooldown timer: the requester redeems it by re-issuing the original call carryingX-K9O-Gate-Token: <gate-id>, and the token transitions toredeemedon success.
A token that isn't approved within its window expires; the requester or an admin can cancel a pending one. A rejected request is resubmitted as a new gate; prior approvals do not carry over, which keeps each gate's audit trail terminal.
1.2 The approval record
A gate token carries an approvals array — one entry per approver, recording the approver's Gate-verified identity, the timestamp, and which constraints they satisfied. That array, together with the gate.* audit events the platform emits at each transition (created, approved, rejected, redeemed), is the record of who approved what and when. Because those audit events land in the project's signed, hash-chained Kibo audit ledger, the account of an irreversible action is externally verifiable after the fact — if a downgrade is later challenged, the ledger answers definitively.
2. Declarative approval for data writes
For multi-row data workflows, the same separation is expressed as an approval policy on a collection's write operation. An approval policy names a collection, an operation, the action queue, and a JSON predicate over the pending change; a write that matches the predicate enters the queue, and one that does not commits directly. The canonical syntax is in API → Control §7.3.
Approval-time failures surface as named codes: a change matching no rule (with the project's default set to reject) returns K9O_APPROVAL_POLICY_NOT_MATCHED; a change whose base version has gone stale returns K9O_APPROVAL_STALE_BASE; a bulk approval where the approver lacks authority over one of the matched changes returns K9O_BULK_APPROVAL_AUTHORITY_INSUFFICIENT (the bulk call answers 200 and lists that change in failed; it does not roll back changes already decided); a re-delegation returns K9O_APPROVAL_DELEGATION_TRANSITIVE_PROHIBITED; a delegation exceeding the grantor's scope returns K9O_APPROVAL_DELEGATION_SCOPE_EXCEEDED; and authoring a rule outside your policy_authored_by_role scope returns K9O_POLICY_AUTHORING_AUTHORITY_INSUFFICIENT.
Create the client once
import { createClient } from "@k9o/core";
const k9o = createClient({
orgSlug: "acme",
projectSlug: "task-app",
apiKey: process.env.K9O_API_KEY,
});Control · E1: Agentic Governance: approvals and approval policies
A policy decides which writes wait for a person. A write sent with requireApproval() is queued when a queue policy matches (HTTP 202) and applied at once when an auto_approve policy matches. Project admins and auditors see the whole queue; other members see only the changes they proposed.
// The collection this example uses (created once, by a migration): expenses (id text PRIMARY KEY, amount integer)
import { isQueuedWrite } from "@k9o/core";
// 1. A rule: inserts into "expenses" above 1000 wait for a decision.
const { data: policy } = await k9o.approvalPolicies.create({
collection: "expenses",
operation: "insert",
action: "queue",
predicate: { gt: ["change.row.amount", 1000] },
});
console.log(policy.id, policy.action);
// 2. Writes that ask to be queued. Each one is either queued (202) or applied at once.
for (const [id, amount] of [["e1", 5000], ["e2", 7000], ["e3", 9000]] as const) {
const write = await k9o.from("expenses").insert({ id, amount }).requireApproval();
console.log(id, isQueuedWrite(write) ? "queued" : "applied");
}apo_c5bV8hGbeor3 queue
e1 queued
e2 queued
e3 queued- Remove the rule when the example is done:
k9o.approvalPolicies.delete(policy.id).
2.1 Auto-approval
Most writes should never wait on a human. An approval policy queues only the writes its predicate matches, so a write below a value cap commits directly where approval would be a rubber-stamp. This is not a back door: approval policies are policy, version-controlled and change-managed. A misconfigured predicate is a misconfigured policy, surfaced the same way any other policy change is before it goes live.
2.2 The queue, expiry, and escalation
A write that requires approval enters the queue and waits for an eligible checker. When the approval window elapses with no decision, the change transitions to expired and the platform emits a data.write.approval.expired audit event — the record is sealed, not silently dropped.
2.3 Delegation
An approver can delegate their authority to another subject for a bounded window. The delegation is a signed assertion naming the delegator, the delegate, and the scope; the audit log shows not only that a subject approved, but that they acted under a delegation, with its scope preserved. Delegation is non-transitive — a delegate cannot re-delegate — and can never exceed the delegator's own authority.
2.4 Concurrent edits
The platform tracks the base committed-state version each pending change was evaluated against. If a concurrent write moves that state before the change is approved, the change is auto-rejected as stale (K9O_APPROVAL_STALE_BASE, 409) rather than applied against data it never saw. A PROJECT_ADMIN can override with ?force_overwrite=true when the overwrite is intended. This is the one built-in model; a workflow needing something richer (field-level merge, for instance) builds it at the application layer.
3. Composition with audit and identity
Maker-Checker rests on two other platform surfaces:
- Identity-Aware Kernel — every approval carries the Gate-verified identity of the approver. A gated action's record of authority is only as strong as the identity behind each signature, and Gate is what establishes it.
- Kibo Audit Ledger — the
gate.*anddata.write.approval.*events land in the project's signed, tamper-evident ledger, so the forensic question "who approved this, and when" has a cryptographic answer.
4. Operational patterns
- Gate and approval configuration lives in policy — version-controlled, reviewable, and published through the same gated lifecycle as any other policy change.
- Approver pools are roles, not individuals — a policy names an eligible role, so personnel changes don't require policy changes.
- Publishing a policy is itself maker-checked — the second-admin requirement on publish means no single admin can quietly change who can approve what.
- Drills are hygiene — periodically exercising a gate chain against a test project confirms the roles still exist, the routing still works, and the ledger record lands. See Tutorials → Warden → Custody Downgrade Drill.
5. See also
- API → Control — the canonical rule syntax, gate-token endpoints, approval-queue API, and the full gated-action family.
- Guides → Unified Policy — the authoring surface these rules live in.
- Architecture → Unified Policy — the policy bundle lifecycle and where gates and approvals sit in the request flow.
- Kibo Audit Ledger — where the gate and approval events are preserved.
- Security → Identity-Aware Kernel — the identity behind every signature.