Skip to main content

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_GATE family 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:

ActionWhy 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 zeroizeCrypto-shreds the project's key-encryption key, rendering every secret and encrypted record under it unrecoverable
Residency region removalA zero-residue erasure of one jurisdiction's data from the project's residency set
Audit-retention reductionShortening the window deletes historical evidence permanently — an attacker who reduces it erases the record of their own act
Extension purgeDestroys 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 minApprovals valid approvals land, the token is approved and redeemable. There is no automatic execution and no cooldown timer: the requester redeems it by re-issuing the original call carrying X-K9O-Gate-Token: <gate-id>, and the token transitions to redeemed on 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.

pending_approvalin-flight requestminApprovals metapprovedredeemablerequester re-issuescall with gate tokenredeemedon successotherwiserejectedan approverrejected itexpiredthe approval windowelapsedcancelledrequester or adminwithdrew itsupersededa newer requestreplaced it
A gate token is redeemable only after enough valid approvals land; every other path ends in a terminal status.

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.

Proposed writeto a collectionApproval policypredicate on changeno matchCommits directlywithout approvalmatchApproval queuewaits for a checkerapprovedchange commitsexpireddata.write.approval.expiredauto-rejected as staleK9O_APPROVAL_STALE_BASE, 409
Only the writes a predicate matches wait for a checker; the rest commit directly.

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

client
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.

1. Queue writes
// 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");
}
Output · bash
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.* and data.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​