DEV Community: Rain S

AI Audit Evidence, Part 5: Five Sources in One File Do Not Check Each Other

Rain S — Fri, 30 Oct 2026 00:49:49 +0000

Has the same conclusion been answered by two paths that share nothing?

Our evidence package puts five sources into one file: the authorization snapshot, the decision evidence, the audit row, the side-effect row and the operation audit row. A root digest pins them together. The package verifies offline and the signature matches.

What that proves is that the five were signed together. It does not prove that they said anything to each other. A digest only answers whether the group was swapped out.

One sentence: cross verification is not "find more sources". It is one conclusion answered independently by two non-sharing paths, with the system itself able to notice when they disagree.

If that is enough, the rest is a table, a code fragment and three admissions.

What counts, and what is only packaging Three criteria. Miss one and it does not count.

The two paths do not share a source. Not two views of the same data, and not the same code run twice.
A disagreement is detectable. Code compares them and returns a distinguishable conclusion. Two values placed side by side, waiting for the reader to spot the conflict, does not count.
It happens at runtime. A comparison that only exists in a test does not count, and neither does one a reader performs by hand.
By those criteria, bundling five sources and hashing the bundle is packaging. Its value is real: the bundle cannot be altered without breaking the hash. But "cannot be altered" answers "was it changed", not "do the parts corroborate each other". Those two questions get conflated because both travel under the word integrity.

Our own account: two and a half This write was authorized. The second path recomputes from the policy version recorded in the row. What it compares is a single item, whether the tool was enabled. Role, writable field domain, destination and approval requirement are not recomputed. This write actually happened. The ledger, the business table and the audit row each carry a view. They are displayed side by side and never judged against each other. The revocation actually completed. The second path compares what this call declared against what the ledger holds, in both directions. This is the only place where a disagreement is detectable. The record was not altered. No second path in this deployment. The external anchor exists as a mechanism; this deployment has no receiver for it, so it is off rather than absent. The coverage statement holds. No second path. The conclusion is derived from one set of facts. Out of five conclusions, one meets all three criteria.

The authorization row is half. A recomputation does happen, but for one of five checks. A reader sees "authorization was reviewed" and what was reviewed is a single item.

Read that list as three grades: complete, meaning a second source that is actually compared; half, meaning a second source with one item compared; and none, meaning no second source at all.

There is a fourth grade that is not on the list, and it costs the most: both sources are present and nobody compares them.

We run two chains, an AI audit chain and an operation audit chain, and the same request lands in both. The material is there, the write points do not overlap, and it looks exactly like two independent paths. But no line of code pairs them by action. They are juxtaposed rather than corroborating.

It is not on the list of five because we never treated "the two chains describe the same event" as a conclusion the package has to answer. The five are what the package claims. This one nobody claimed. The expensive kind of false cross is not missing material. It is material that nobody remembers to compare.

Why the one that counts, counts declared targets vs targets the ledger holds only declared → onlyDeclared only held → onlyStored either non-empty ⇒ mark the group disputed, refuse to report the revocation complete Independence: one side is what this call said it would write, the other is what the ledger already recorded. They are produced in different places, so an error in one does not automatically appear in the other.

Detectability: a mismatch becomes a state, disputed, with the difference kept as evidence. Not two fields waiting to be noticed.

The cost, stated plainly: it triggers in one situation, when a retry with the same arguments hits the idempotency key.

Something a reader asked out of us This section is about us.

We published a five-layer evidence model: that a record exists, its source and integrity, its link to execution, coverage, and the verification of the result. A reader replied that a layer was missing. Some claims have no record at all. "This system complies with X", with nothing attached.

He was right, and it was worse than he put it. Our first layer says that a record exists is not the same as the event happened, and it presupposes that a record exists. A claim with nothing attached sits outside the model: it neither satisfies nor violates it. It cannot enter.

We added the layer, numbered L0. To be explicit: it was added after publication, and the published version does not contain it. If you go back to the article, you will not find it there.

That exchange was itself a cross check. Our own conclusion was asked again by someone who does not share our view, in a different form, and the different form found the gap. The same question in the same wording returns the same blind spot.

Four checks you can run What is the second path for this conclusion? If you cannot name one, it is single source. Label it that way instead of calling it corroborated. Are the two paths independent, or is it the same data dressed differently? Bundling, merging and digesting all fall on the second side. When they disagree, does the system return a state, or does it place two values next to each other? Does that comparison run in production? If only in a test, it proves that test rather than the steady state. Closing Back to the file. It can prove it was not altered. It cannot prove the parts corroborate each other.

To prove that, each conclusion has to name its second source, and the ones that cannot get labelled single source. The list will look bad. It will at least be accurate.

The mechanism above is taken from KeelBase, an open-source runtime that sits between an AI agent and a business system, re-checks identity, authorization, scope, risk and confirmation state before a tool runs, and writes every decision into a record that can be verified offline. Cross verification is a way of reading here, not a shipped feature; KeelBase is its implementation and evidence carrier.

Repository: https://github.com/rain6fish/KeelBase

Three things stated plainly. One of five conclusions is a complete cross check; the rest are half or nothing. The authorization row reviews a single item out of five. And L0 was added after publication, so anyone citing it should carry that sentence along.

Drafted with an AI assistant. The system, the positions and the mistakes are mine.

AI Execution Governance, Part 8: Actions the Tool Registry Does Not Know About

Rain S — Wed, 28 Oct 2026 00:53:05 +0000

One application, one events table, two rows.

One row comes from your AI assistant: it calls create_event, a registered tool marked R3 that waits for your confirmation. The other comes from POST /api/v1/events: an ordinary HTTP route that touches no tool and writes nothing to the AI side-effect ledger.

The two rows look the same. What differs is the entry, not the action.

One sentence: what a governance system can vouch for is not what the registry contains, but which execution paths were verified and which were not — and the deliverable should be a list of unverified entries, not a coverage percentage.

If you only want the conclusion, you can stop here. What follows is the four things that have to be separated, one entry-by-entry list, and a failure of our own; you can skim it.

A registry is a set; an entry is a path At boot this runtime registers 61 tools, all unconditional, into one Map. GET /ai/tools lists them with risk level and gate mode.

That set answers "what do we intend to govern". It does not answer "where does the action enter".

Three concrete places show this is not a matter of wording.

First, there are two catalogues, and an auditor can only see one. GET /ai/tools maps the local registry only and requires read ToolInventory. External MCP tools are discovered at runtime, merged when tools are handed to the model, but absent from that list — they appear on /admin/mcp/tools, which requires manage all. An audit reader holds read only, so on the question "what can the agent call", the auditor can answer half of it; the other half needs an administrator, or is missed.

Second, the gate does not treat "unregistered" as its own denial condition. When assertToolAllowed cannot find a tool, it catches the error and carries on; the comment says it plainly: let the later execute throw "not found". The executor does refuse: toolRegistry.execute calls getTool first and throws Tool "..." not found when the name is absent. So nothing here licenses a bypass — an unregistered name cannot reach the business layer. What it does license is a narrower claim: passing the gate is not the same as being on the registry. The gate checks a tool it found against its declaration; it does not reject what it did not find. Unregistered actions are held by the executor layer, and the two layers each mind their own business. Reading "the gate let it through" as "this action is registered" is exactly the merge this article is trying to take apart.

Third, our own table drifted. The tool metadata table once had four labels pointing at tools that did not exist, while twelve real tools had none. The fix was not another hand-written list; it was to run the check against the live registry. That is our own incident, not a hypothetical: a hand-maintained table drifts silently the moment someone adds a tool and forgets it, or renames a tool and leaves the old entry behind.

Raise the same class of error one level and you get this article's question: we have a gate that checks metadata against the registry, and no gate that checks the registry against the runtime's entry set. Nothing turns red when a new write path appears.

Four things that have to be separated Action catalogue: what we declare we govern. Today: 61 registrations, one metadata table, plus externally discovered tools at runtime. Execution entries: where an action actually starts — an HTTP route, an SSE stream, a WebSocket event, an MCP endpoint, a scheduled job, a workflow node, a queue consumer, a plugin route. Governance coverage: which entries' writes really pass the same gate and the same executor. Verification evidence: what proves the previous line — a source call site, a unit test, an end-to-end test, or "I read it once". Fold these four into a percentage and you get the usual "90% coverage". The problem is the denominator: the set of execution entries, which is exactly what we do not know. A percentage with an unknown denominator is a claim about a set you cannot enumerate. A list is different: it names each unverified entry, can be argued with, and can be closed.

Put another way: coverage answers "how much did we do"; a list answers "what is left". Auditing needs the second.

How to audit the entries Start from the executor, not the registry. Find the few lines where a write actually happens, then walk backwards.

In this repository the write executor is executeWrite, and the whole repository has exactly three call sites: two in the streaming chat loop (the trusted direct write, and the write after a confirmation is approved), and the R4 approval executor. Walking up from those three lines yields the SSE stream, WebSocket ai:chat, the admin streaming assistant, out-of-band decisions, and the governance-console callback.

Then go the other way: for every remaining entry that can carry AI authorship, ask how its write happens. This step is reading source, not reading the registry. The thing most easily missed is not "is there a gate" but whether the gate is an optional argument:

const execute = readOnlyExecutor ?? ((tool: string, args: Record, uid: string) => toolRegistry.execute(tool, args, uid));
Plan and sub-agent steps are supposed to be read-only: with the read-only executor injected, write tools are refused. But the executor is optional; omit it and execution falls back to toolRegistry.execute — no gate, no confirmation, no side-effect ledger. The sub-agent has the same shape.

We ran one call with no executor injected: the planner returned a write-tool step, and the tool name landed directly on registry.execute. Every call site in the current assembly injects the executor, so this is a path no one walks today — not a production bypass. But it is reproducible: a unit test even pins "no executor means direct registry call" as expected behaviour. One optional parameter turns "the gate" into "if the caller remembered".

This method has a flaw it cannot fix itself: it is a snapshot. Add a controller tomorrow that calls toolRegistry.execute directly and nothing goes red. The closest thing to a runtime self-check today is /app/provenance, but it returns counts — total, read/write split, risk distribution. A count cannot name an entry.

Status, evidence level, reachability The status answers one question only: what is the conclusion.

verified — within the scope declared for this path, evidence shows it satisfies the stated governance condition: its write passes the gate and the executor, or an explicit refusal stops it.
failed — it is proven that at least one path violates that condition.
unknown — the evidence is insufficient to decide. Not counted as covered.
not_applicable — it is proven this path is outside the declared governance target, and the scope it belongs to is stated.
A second question is not answered by those four values: on what ground. Folding "I read the source" and "I ran an end-to-end test" into one verified repeats exactly the merge this article criticises. So the evidence level is a separate field, independent of the status:

E1 — source read: the call chain reaches the gate and the executor at the execution point.
E2 — a unit or integration test exercises the path.
E3 — an end-to-end test, or a real run, verifies it.
E4 — a third party reproduces it from the steps in this article in an independent environment.
(E0 means a claim with no evidence and is not used here.) verified / E1 and verified / E3 are not the same sentence: source proves "this call site calls executeWrite", not the runtime assembly, dependency injection, configuration switches or error branches; a passing test proves only the path it ran. The highest level in this piece is E3; nothing reaches E4.

The entries, one by one — status, then evidence level, then whether the current assembly can reach it:

POST /ai/chat (non-streaming), /headless/chat, admin non-streaming. Write tools are refused, not executed; the gate is consulted at the start. No write occurs. Status verified (the refusal holds). Evidence E2. Reachable in the current assembly.
POST /ai/chat/stream, WS ai:chat, admin streaming. Writes go through executeWrite; the execution point re-checks the policy switch, field domain, destination and approval requirement, then claims the call. Audit row + claim row + side-effect ledger. Status verified. Evidence E1 (the entry-to-executor chain) plus E2 for the executor itself. Reachable.
POST /mcp (MCP exit). Write tools return "requires confirmation" and are not executed; executeToolForExternal applies the gate. A tool_call audit row is written with outcome=pending. Status verified (the refusal holds). Evidence E2. Reachable.
POST /admin/mcp/call (external MCP gateway). Calls the third-party server directly after the policy switch, R5 and confirmation checks. Writes an audit row; no local side-effect ledger. Status verified (gate yes, ledger no). Evidence E2. Reachable.
Confirmation and approval: in-conversation decision, out-of-band decision, governance-console callback. On approval, the write goes through executeWrite — the same execution point as streaming. Status verified. Evidence E2. Reachable.
Plan / sub-agent with the read-only executor injected. Write tools are refused; executeAgentRead enforces read-only. Audit is written by the caller. Status verified. Evidence E2. Reachable.
Plan / sub-agent with the executor omitted (the fallback). Calls toolRegistry.execute directly. No gate, no confirmation, no ledger. Status failed on the code structure. Evidence E1 plus the out-of-tree probe. Unreachable in the current assembly (every known call site injects the executor).
FLOW ai_task / human_task. One text generation / a flow_task row plus a notification. No tools involved. Status not_applicable (outside the AI tool surface). Evidence E1.
Scheduled AI (daily digest, 0 8 * * ). LLM output becomes a notification row. No tools, no tool_call row. Status not_applicable (writes a notification, not a business record). Evidence E1.
Queues (knowledge / push / reminder). Transcription, push, reminders. No tools. Status not_applicable (outside the AI tool surface). Evidence E1.
Direct business REST writes (e.g. POST /events). Calls the business service directly; no AI gate; operation audit, not the AI ledger. Status not_applicable (outside the AI entry surface). Evidence E1.
Plugin routes (POST /plugins/). A plugin can fetch any host service and register a route. No gate, no ledger. Status unknown (not examined). Evidence E1 (the interface only). Reachability not examined.
Two things about that list need saying.

A note on the one failed, which has to be read as two sentences. Code structure: failed. With no executor injected, a write-tool name lands on registry.execute (whose real body is tool.execute), and gate, confirmation and ledger are all absent; this is reproducible, not inferred. Current assembly: no evidence that anything walks it. Every call site injects the executor — but that covers only the assembly points checked today, not a call site added tomorrow, and not runtime branches, so it does not amount to "safe". The two sentences must not be merged: writing "the code allows it" as "it happens in production" is one kind of dishonesty; writing "nobody walks it today" as "the code is fine" is the other. The reachability column exists for exactly this.

not_applicable only says the path is outside the declared scope; it does not mean the business write is safe, and it does not mean KeelBase governs it. A direct business REST write and the AI tool write call the same service function (the create_event tool and POST /events both end at eventsService.create) and leave rows in the same table. It is not an AI entry, so the only promise this table makes about it is "we do not claim to govern it" — and if an AI path ever called it, the gate would not stand in the way. Reading not_applicable as "this write is already covered" turns out-of-scope into a pass.

unknown cannot be read as verified. This runtime has a gap registry; each gap declares whether it makes the conclusion partial or unknown, and unknown means "we cannot even say what is missing", which is stronger than partial. A test pins that semantic: only a high-severity gap may produce unknown.

The problem: the registry contains exactly two entries that describe this article's subject — risk-level-not-expressible-for-non-discrete-actions (an action surface that is not a discrete named tool cannot carry a risk level) and host-ai-path-not-governed (the host runs an AI path of its own that does not pass through the engine) — but this deployment's fact set pins both conditions to false, so a statement never declares them.

We can name the gap; we cannot make it appear in the statement. That is slightly worse than not having the gap at all: it looks checked. The file gives a written reason for two of the pinned facts; these two have none. That is what an honest unknown looks like — not a blank, but "there is something here, and we have no input that can decide it".

But this one is no longer an ordinary unknown; it is a defect in the statement mechanism itself. The two cases have to be recorded apart. An ordinary unknown is a missing evidence: not examined, or examined and undecidable, and another round of checking may clear it. This one is a missing mechanism: the gap is in the registry, its name can be said out loud, and yet the fact set pins the trigger to false, so the statement necessarily omits it and no amount of re-checking changes that. A statement that only distinguishes "implemented" from "not implemented" leaves this class permanently in the seam between the two.

Seven checks you can run Which entry did this action come through? A client tap, an HTTP route, a WebSocket event, a scheduled job, a queue, a workflow node — write it down; do not write just "the AI". Does that entry's write pass the same executor? Ask "is there a gate", not "is there an audit". An audit says it happened; a gate says it was allowed. Does the same action produce the same row from two entries? If it does, the row alone cannot say who wrote it — unless you join the audit row and the effect row. How many catalogues are there? Local registrations, the metadata table, externally discovered tools — and who reads each. Where does unknown live? If the response has no value for unknown, absence will be read as a pass. What goes red when a new entry appears? If the answer is "nothing", the coverage is hand-maintained. What level of evidence backs this verified? Source reading and an end-to-end run both get written as "verified", and they vouch for very different amounts.
What we have, and what we do not What exists: 61 unconditionally registered tools with an auditor-readable inventory; a write executor that re-checks policy switch, field domain, destination, approval requirement and claim at the execution point; refusal of write tools on the MCP exit and the non-streaming entries; read-only enforcement for plan and sub-agent steps; a gap registry with unknown semantics and a verdict computed from facts; a completeness gate that checks tool metadata against the live registry.

Boundaries: there are two catalogues (the local inventory omits externally discovered tools); the external MCP gateway has a gate and an audit but no local side-effect ledger (the target is someone else's); the plan/sub-agent fallback makes the gate optional; the gate does not refuse unregistered names; two gaps that should say "there is a path we cannot see" are pinned to false and never appear; a direct business write and an AI write share one service function and cannot be told apart from the row alone.

What is not done: there is no runtime enumeration or assertion of entries — "the action surface is enumerable" remains a bet here, not a proven fact; no test proves "every AI entry is closed"; this table is a manual audit dated 2026-10-26, not a product feature; plugin routes and host-side AI paths have not been assessed.

Keep three surfaces apart, or one of them will end up vouching for another.

The action surface: the 61 registered tools, the metadata table, the external MCP tools discovered at runtime — "what we intend to govern".
The entry surface: HTTP, SSE, WebSocket, MCP, scheduled jobs, queues, workflows, plugins that can trigger execution — "where the action enters".
The business side-effect surface: the write points that actually change business state — "what changed".
Each can be incomplete on its own. A complete entry list does not imply a complete side-effect surface: a plugin can fetch any host service, and a general business service can be reached by a path nobody audited. So the conclusion should not stop at "enumerate the entries" — every business write inside the governed scope must complete only through a verified execution path, and every write outside that scope must have its boundary stated. The entry list is only an approximation of that sentence against today's code.

Closing
Back to the two rows: whether a write is governed depends on which entry it came through, not on which table it landed in.

The mechanism above is taken from KeelBase, an open-source runtime that sits between an AI agent and a business system, re-checks identity, authorization, scope, risk and confirmation state before a tool runs, and writes every decision into a record that can be verified offline. The entry audit is a way of reading, not a shipped feature; KeelBase is its implementation and evidence carrier.

Repository: https://github.com/rain6fish/KeelBase

Four things stated plainly. Six entries carry E2 (one of them only at the executor layer), five carry only E1 (source), and the fallback row is E1 plus one out-of-tree run; nothing reaches E4. The fallback bypass was reproduced with a script that injects no executor; the production assembly does not walk it. The not_applicable calls for scheduled jobs, queues and workflows rest on "no tools are involved", not on a test that writes are impossible. And we do not write "all entries are covered", because nothing proves it.

Responsibility is not in one place. The runtime must prove its own execution paths are actually governed — gate, confirmation, ledger, reproducible by test; the host application must identify and disclose the business entries that bypass the runtime, because only it knows where its writes come from; the integrator must confirm which business writes fall inside the governed scope, because scope is set at integration time. And the governance system must keep verified, failed, unknown and out-of-scope apart, rather than letting one tool catalogue vouch for the whole application.

The registry says what we intend to govern; the entry list says what we actually reach. The difference between them is the governance boundary.

Drafted with an AI assistant. The system, the positions and the mistakes are mine.

AI Audit Evidence, Part 4: What Can One AI Audit Record Actually Prove?

Rain S — Mon, 26 Oct 2026 01:06:39 +0000

An audit record is on the table: one confirmation, one execution, one side effect. The hash chain verifies.

What does that prove?

One sentence: one record does not prove all five layers: a valid signature reaches only the second, and coverage and the external result are separate checks.

Most people read it as two things: the event happened, and the record is true. There are five different questions inside that sentence, and one record usually answers only one or two of them.

This piece gives a five-layer evidence model. If you only want the conclusion, you can stop here. The rest is the failure modes and the five claims behind that sentence, and you can skip it. The bold sentence in each section carries the point.

Five questions, not five fields A record can answer five questions, and they are not the same thing:

Event record: what did the system record?
Source and integrity: who produced the record, and was it altered?
Execution linkage: does this record correspond to the path that actually ran?
Coverage: which execution paths were verified?
Result verification: what actually happened to the business side effect?
The layers build on each other, but they do not upgrade automatically. A higher layer cannot be inferred from a lower layer's fields. A signature does not add coverage. A coverage statement does not verify an external result.

What one real record looks like This is a record from a local run on 2026-10-15. The tool is create_followup_task, risk level R3, approved from the pending list:

confirmation #3 create_followup_task R3 approved
decided 05:54:37.327 claimed .332 executed .365 error null
audit #27 action=tool_call tool=null outcome=null is_error=0
detail="create_followup_task({\"customerId\":1,\"title\":\"Followup Task\"})"
hash=b0d6bf… prev_hash=565b3f…
effect #1 crm_task:10
before_snapshot=null after_snapshot={"id":10,...} revoke_class=local_compensate
The three rows together are "one operation".

But there is a non-obvious detail: audit row #27 has tool and outcome empty. The tool name exists only inside the detail string, and the result can only be inferred from is_error=0. A later row in the same database (#37, later that day) has tool=create_followup_task and outcome=executed. The same kind of record can look different at different times.

The record is not false. It is authentic, on the chain, and the hashes are continuous. It simply does not explain itself. A reader who does not know the detail convention cannot say what ran or what the result was.

Reading the record layer by layer
Layer 1, event record: three rows exist, a confirmation, an audit row and a side-effect row. It does not prove the event happened as recorded; the record itself can be wrong.
Layer 2, source and integrity: the audit row is on the chain, with continuous hash and prev_hash. It does not prove the tail was not deleted or that nothing was omitted. The confirmation and side-effect rows are not on this chain.
Layer 3, execution linkage: the confirmation's execution axis is executed, and the effect is crm_task:10. It does not prove this effect was produced by this confirmation; the link is by tool, argument hash and time, not one foreign key.
Layer 4, coverage: the package's coverage statement can be consulted separately. One record does not say other execution paths were covered.
Layer 5, result verification: after_snapshot is present. It does not make the change comparable, because before_snapshot is null, and it does not prove the external target's state.
The strongest layer in this record is layer 2. The weakest is layer 5. It is a real record, not a complete piece of evidence.
Two counterexamples
Counterexample A: a valid signature over an incomplete record.

Audit row #27 is on the chain, with continuous hash and prev_hash. But its tool and outcome are empty, and the side-effect row has no before_snapshot. So:

you can prove the audit row was not altered
you cannot use this record alone to say which tool ran, what the result was, or what changed before it
A signature authenticates bytes, not meaning. A real, signed record can still fail to answer the question it appears to answer.

Counterexample B: a complete record with an unknown business result.

This is a design-level scenario, not a test of the record above. A write is sent to an external system. The local side-effect row says executed, but the external system is unreachable and has no query endpoint. The correct conclusion is unknown, not success.

A complete local record only says the local side is complete. An unverified external state cannot be written as success.

Not a field checklist The five layers are not a field checklist. They are five refutable claims:

L1: a record exists is not the same as the event happened.
L2: a valid chain or signature is not the same as no omissions and no tail deletion.
L3: a record is linked to an execution is not the same as the execution matched its authorization.
L4: one action was covered is not the same as every path was covered.
L5: a local result was recorded is not the same as the external business state was verified.
These claims do not try to prove that AI never makes mistakes. They ask which guarantees a system can offer when AI misreads, overreaches, retries, times out or hits an exception, and how far each guarantee can be verified.

They also explain why adding fields does not add guarantees: a signature at L2 does not make coverage at L4 true, and coverage at L4 does not make an external result at L5 verified. Each layer needs its own evidence.

The test of these claims is not more terminology. The test is whether they can point at a counterexample, narrow a guarantee, or turn a vague promise into a verifiable criterion. All five are candidates, not proven theorems.

What we have, and what we do not What exists: the confirmation's execution axis (decided_at, execution_claimed_at, executed_at, execution_error); the audit hash chain; side-effect rows with before and after snapshots; the coverage statement; the audit reader role.

Boundaries: the record above already shows three. Structured fields can be empty. A side-effect row can lack a before snapshot. The confirmation and side-effect rows are not on the audit chain. Beyond that: without an external anchor, tail completeness can only be unknown; an unreachable external result is unknown; the operation audit row scope is not yet narrowed by organisation.

What is not done: the five-layer model is not an API or a product feature. It is a way to read evidence, which you can apply to any agent runtime without waiting for us to ship five endpoints.

Five checks you can run Which layer does this record answer? "Recorded" or "verified"? What proves integrity? A chain, a signature, a coverage statement, or only a sentence? What links the record to the execution? One id, or tool plus argument hash plus time? Can someone else rebuild the link? Where is coverage written? How are uncovered paths expressed: unknown, absent, or pretended complete? How far does result verification go? When the external state is unknown, is the conclusion unknown? Closing Back to the opening: what a record proves depends on which layer you are asking about.

What we do: split evidence into five layers and say what each cannot prove; show a real record where "authentic but incomplete" is visible; keep external results and tail completeness as unknown instead of writing them as success.

The mechanism above is taken from KeelBase, an open-source runtime that sits between an AI agent and a business system, re-checks identity, authorization, scope, risk and confirmation state before a tool runs, and writes every decision into a record that can be verified offline. The five-layer model is a way to read evidence, not a shipped feature; KeelBase is its implementation and evidence carrier.

Repository: https://github.com/rain6fish/KeelBase

Four things stated plainly. The record above comes from a local run, not production data. The five-layer model is a method, not a shipped feature. External results and tail completeness remain unknown, and the operation audit row scope is still an open item. The five layers are candidates, and counterexamples are welcome.

An honest record does not claim all five layers are full. It says where each layer stops.

Drafted with an AI assistant. The system, the positions and the mistakes are mine.

AI Audit Evidence, Part 3: An Auditor Is Not an Admin

Rain S — Fri, 23 Oct 2026 01:04:15 +0000

An auditor has to review what an AI did.

The cheapest way to let them do that is to hand them an admin account. But then the person they are supposed to review becomes themselves.

This piece is about building a read-only auditor role: its reach is an explicit list, every field is rebuilt from a whitelist, row scope comes from the account rather than the request, and the signed evidence stays whole and unprojected.

Admin is the cheapest answer, and the wrong one An audit reader's job is to review what someone else did. They need evidence, not operational authority.

But in most systems read access follows write access: whoever can manage everything can obviously read everything. So the shortest path to "let them see the audit" is to give them admin. The cost is that they also gain the ability to change policy, approve requests and execute tools, which is exactly what they came to review.

What is needed is not a weaker admin. It is a role whose reach can be enumerated item by item. If you cannot enumerate it, it is still an admin.

The role's reach is a list Our auditor role gets five rules, and every one grants read only:

{ roleCode: UserRole.AUDITOR, subject: 'AuditLog', actions: ['read'], ownerField: null },
{ roleCode: UserRole.AUDITOR, subject: 'OperationAudit', actions: ['read'], ownerField: null },
{ roleCode: UserRole.AUDITOR, subject: 'GovernancePolicy', actions: ['read'], ownerField: null },
{ roleCode: UserRole.AUDITOR, subject: 'ToolInventory', actions: ['read'], ownerField: null },
{ roleCode: UserRole.AUDITOR, subject: 'ApprovalQueue', actions: ['read'], ownerField: null },
That list is everything the role can touch. Everything else is denied by the policy guard by default.

It deliberately gets none of the USER ownership rules. This role is a reader of the governance record, not a user of the application. It should have no write action either. The day one of these rules grows a write, the role stops being an auditor.

The shape of the rule is worth one sentence too. The underlying role seeds originally had only a subject and an owner field, and every seed implied manage. We added an optional actions; omitting it still means manage, so no existing role changed behaviour. Writing it is how a role narrows itself. Read access is written down, not inferred from management.

Fields: rebuilt from a whitelist, not deleted from a full row The role decides which surface you can reach. The field list decides what you can see on that surface.

We keep one whitelist and rebuild the projection from it:

only keys named on the list are written
a column added tomorrow stays invisible to an audit reader until someone deliberately adds it to the list
deleting forbidden fields from a full row would fail open: the next column leaks by default
That is not a style choice. It is a choice about defaults. Deleting from a full row defaults to visible; rebuilding from a whitelist defaults to invisible.

The fields left off the list have reasons. A conversation id is a pointer into a person's conversation. IP and device ids bind activity to a device or a person. A user's feedback about the assistant is not the audit record. Delegation context is free text that may quote a prompt. The bounded business intent and the agent and caller ids carry the attribution a reader actually needs.

One test injects a key that is not on the list at runtime and asserts it does not appear in the projection. It is not testing deletion. It is testing the default.

Rows: organisation from the account, period from the request Beyond the role and the fields there is the question of which rows. The same surface, with the same fields, must still show different rows to different readers.

The organisation comes from the account, not the request. An organisation parameter on the request can only narrow further, ANDed with the account scope, never replace it.
An auditor who belongs to no organisation falls back to their own rows. A failed organisation lookup also falls back to their own rows. A failed lookup is not a reason to widen.
The period comes from the request window. There is no per-reader period attribute today and no read-plane policy. Inventing one here would invent a dimension, so we use the window the caller asks for.
Fetching a single row by id returns 404 when it is out of scope, the same answer as "no such row". The gate already passed; telling the reader that another organisation has that row is itself a disclosure.
The by-id path and the list call the same scope function. Two implementations would eventually disagree.

Aggregates need the scope too, and so does the cache key Narrowing the list while leaving the counts narrow-free is the same as not doing it.

The auditor's stats, cost, report and coverage statement all read through the same organisation scope. One thing is easy to miss: the aggregates are cached for 60 seconds, and the cache key has to carry the scope.

We hit that class of defect. With no scope in the key, the first reader's organisation answer was served to the next reader for a minute. The fix is not to clear the cache. The fix is to put the scope in the key: all, org: or own:. It is the same class as a verification verdict computed for one database being served for another. A cache does not know who is asking, so the key has to.

One thing we do not slice by organisation: the hash chain inside a signed evidence package. Slicing a chain and verifying the slice produces a false conclusion, so the chain keeps its full scope. Rows can be narrowed. A chain cannot.

What stays closed Listing what the auditor can reach matters as much as listing what they still cannot:

Audit log, single-event explanation, chain, verify, stats, cost, report: the auditor reads projected rows within their organisation scope; an admin reads full rows.
Operation audit: the auditor reads, but row scope is not yet narrowed by organisation; an admin reads.
Governance policy, its history, tool inventory, approval queue: the auditor reads; an admin reads, writes and decides.
Signed evidence package and verify chain payload: the auditor reads them unprojected so they stay verifiable; an admin reads them too.
Users, organisation, sessions, platform analytics, writes, approvals, execution: unreachable for the auditor; reachable for an admin.

Three points deserve their own paragraph:

The signed evidence package and the verify chain payload are not projected. They are verification artifacts whose value is the complete canonical payload. Projecting them makes them unverifiable. Privacy projection covers row-shaped responses, not the evidence itself.
The auditor can read the approval queue but cannot decide it. Approving, rejecting and retrying execution stay admin-only. Reading the queue is not handling it. The same applies to flow approvers: the role list deliberately excludes the auditor. An auditor must not become the kind of person they are reviewing.
Operation audit's read access is open, but its row scope is not narrowed yet. The service filters only by the request's userId; it does not apply the reader's account scope. This is an open item from the role's widening, and saying so here keeps the five rules from implying that every surface is already scoped.

The scene: widening one surface at a time Our first cut changed only the audit controller to read AuditLog. Operation audit still judged manage all, so the auditor reached that surface and got a 403.

That was not an omission. It was deliberate: open one surface, see whether it is enough, then widen one surface at a time. Later, operation audit, governance policy, tool inventory and the approval queue each got their own read subject. Writes, approvals and execution never entered the widening.

The order has a second benefit. Each surface can be verified on its own: what should be visible is visible, what should be blocked is blocked. Opening everything at once makes a hole impossible to attribute.

Five checks you can run Which surfaces can your read-only role reach? Can you enumerate them, or is it "roughly like admin"? Are new fields visible by default? Deleting from a full row fails open. Rebuilding from a whitelist fails closed. Does row scope come from the account or the request? Can the request only narrow it? Where does a missing organisation fall back to? Do the aggregates and the cache carry the same scope? A narrowed list with unscoped counts is not narrowed. Is the signed evidence projected? If it is, can it still be verified? Closing Back to the opening: giving someone the evidence is not giving them the system.

What we do: five read-only rules define the role's entire reach; fields are rebuilt from a whitelist and new columns are invisible by default; organisation comes from the account and the period from the request; an out-of-scope row returns 404; aggregates and cache keys carry the same scope; signed evidence stays whole.

Repository: https://github.com/rain6fish/KeelBase

Four things stated plainly. The role is widened one surface at a time: everything outside the list is still unreachable, and that is default deny rather than unfinished work. Signed evidence cannot be projected, so privacy minimisation has an explicit boundary here. An auditor cannot decide approvals or serve as a flow approver. If they could, they would become the person they are reviewing. And operation audit's row scope is not narrowed by organisation yet: the read access is open, the scope is not, and that is an open item rather than a finished surface.

Read-only is not "a little less permission". It is a reach you can enumerate.

Drafted with an AI assistant. The system, the positions and the mistakes are mine.

AI Audit Evidence, Part 2: Silence Reads as Completeness

Rain S — Wed, 21 Oct 2026 01:29:45 +0000

An auditor receives an evidence package. The hash chain verifies.

What will they read that as?

Most people read it as two things: the rows were not altered, and they are all here.

The chain proves only the first. Delete the last few rows and the remaining chain is still internally consistent.

This piece proposes one thing: every evidence package should carry a coverage statement, in data, saying what it read and what it cannot show, signed together with the package.

What the chain proves, and what it does not A hash chain means each row carries the digest of the one before it. Change a row and the rest stop matching. Remove a row in the middle and the chain breaks. Reorder them and it breaks.

It does not stop deletion from the tail. Remove the last few rows and what remains is a shorter chain that is entirely self-consistent.

So "the chain verifies" answers internal consistency, not completeness. Completeness needs something outside the chain, such as periodically writing the tail digest somewhere else.

This is not an implementation detail. It is the inference a reader will make. A record that does not state its boundary gets read as complete.

The scene: a gap we deliberately left out We maintain a registry of gaps. Each entry says one thing this kind of package cannot show.

As of this writing there are eleven entries.

One candidate is deliberately not among them: the claim that a side-effect row cannot show who did it. We did not add it, because whether it still holds has not been settled. Our side-effect entity carries an owner. That reading may only mean the entity has the field while the endpoint does not expose it.

An unverified gap is worse than no gap. It attaches a false caveat to every package, and the reader has no way to tell which caveat is real.

So one of our tests is dedicated to the absence. It asserts that the registry contains no origin for that claim.

This may be the least intuitive line in the design: this test does not check that something is there. It checks that something is not.

It also says the coverage statement needs a coverage boundary of its own. We can only declare the gaps we have verified.

Gaps are data, not prose If every report carried a hand-written paragraph saying "this report may not include...", that paragraph would drift away from the system. Someone changes collection and forgets the caveat, or changes the caveat and forgets the system.

So the gaps live in one place. Each entry has:

a stable id that is never reused
a severity
whether it limits this package or the whole deployment
a predicate over a closed set of facts, all of which must hold for the gap to apply
one English statement, the field that carries the caveat on the wire
an internal origin that does not
The closed set is deliberate. A predicate that can read anything is a predicate nobody can evaluate, and an entry whose condition cannot be evaluated can only ever apply. That is the silence-is-completeness failure again.

So each package declares the gaps that actually apply to it, not a copied list of caveats that drifts.

Adding a gap changes the registry only, as long as it reads the facts we already collect. The statement gains an entry and the service code does not change. This is structural: change the registry and the registry revision in the statement moves with it. A search for the eleven gap ids in the service code returns nothing.

What a coverage statement contains First make the statement an object rather than a paragraph. In our package it currently has these fields:

registryRevision: which version of the gap registry the statement was computed against
scope: whether it covers one action, a period or an entity, with its start, end and subject
sources: the sources actually read, each with a state and a row count
verdict: complete, partial or unknown
gaps: the gaps that apply, each with an id, severity, scope and one English statement
That is the minimum machine-readable shape. It answers three questions: which rules were used, what was read, and how the verdict reads.

If you want human review in the statement, one sentence is not enough. You need three fields: review status, who confirmed it, and when; plus an exception reason, meaning why something is not covered and who accepted that exception. Those fields are not in our statement today. They live on the authorization and confirmation rows. Putting them in means deciding on a cross-table read and making sure they are signed too. Otherwise you have added another paragraph that drifts.

One more thing about the signature: the statement is not signed on its own. It is signed as part of the package's canonical string. A separate hash for the statement would be a different design.

The verdict is computed The registry also has to say how a verdict reads. Our rule has three lines:

no applicable gap means complete
any gap that says "we cannot even tell what is missing" means unknown
everything else means partial
The important boundary is that unknown is not a stronger partial. partial means I know what is missing. unknown means I cannot even tell.

Reporting unknown as partial would claim we know what we are missing, which is exactly what that gap says we do not.

The verdict is not written by hand. A hand-written verdict is just another value that drifts.

The statement is signed with the package If the coverage statement were a note beside the package, it could be rewritten after the fact into a nicer version and the signature would still verify. The section would be decoration.

So in the new evidence-package format the coverage statement is a required section, and it is part of the canonical string that gets signed. The offline verifier checks for it first; a package of this version without it fails.

The same statement has to say what was consulted. It lists only the sources this package actually read, not the sources the system happens to have. Listing a source nobody queried is the same silence this whole thing exists to break.

The signature covers the statement's content, and two values in that content are not computed. They are pinned, and neither is optimistic.

The first is whether one cache serves more than one deployment. The code cannot see a second deployment. false is the correct answer for the deployment shape this repository supports, one deployment with one set of databases. The gap stays in the registry for shapes it does not support. There is no input for that today, so we record it rather than paper over it.

The second is whether the package has an external anchor. The anchor has no endpoint, which we measured. So a package cannot carry one, and the statement says unknown instead of pretending the chain is enough.

Both are worth stating precisely, because they show what the statement is for. It does not promise completeness. It points at where completeness is missing.

Three common "only" cases
Only a trace, no statement: the reader takes a missing trace as a missing action. Absence of a trace and absence of the action are two different facts.
Only an approval, no approved scope: approving one call is not approving every argument and destination of that run. If the scope is not written, the next person has to guess.
Only a log, no integrity check: a log can be edited. A chain proves internal consistency, but the tail can still be removed. Without an external anchor, completeness is still an inference.
All three point at one thing: the presence of a record is not the same as coverage.
A boundary this design does not cross
A coverage statement makes incompleteness readable. It does not make an audit complete.

It can only cover facts we can compute. What we cannot compute goes to unknown, or, if it is a guess we have not verified, it stays out of the registry entirely.

The fact set is closed, and that is both its shape and its ceiling. A gap that needs a new fact does not appear by adding a row to the registry.

So it is not a compliance certificate. It is a usage note: this is what the package can answer, and this is what it cannot.

Four checks you can run Does your evidence package say what it did not read? If all it says is "verified", the reader will supply "probably complete". Is that sentence hand-written, or computed from a registry? The hand-written one drifts. Is the verdict written or computed? In particular, can unknown be downgraded to partial? Is the statement inside the signature? If not, it can be rewritten after the fact without breaking the seal. If you run high-risk agent sessions, the cheapest implementation is not a new report page. Make package generation an automatic step at the end of the session, and make the coverage statement a required section of the package. The system computes it; the person writing the report does not fill it in. That is the difference between a coverage statement and a disclaimer.

Closing
Back to the opening: silence gets read as completeness.

What we do: the gaps live in one place, eleven entries with an origin for each; predicates read a closed set of facts; the verdict is computed and unknown is not downgraded; the coverage statement is signed with the package; and only the sources actually read are listed.

The mechanism above is taken from KeelBase, an open-source runtime that sits between an AI agent and a business system, re-checks identity, authorization, scope, risk and confirmation state before a tool runs, and writes every decision into a record that can be verified offline. The coverage statement sits at the seam between confirmation and audit in that governance loop: confirmation answers who approved this action, and the statement answers how far the record can prove.

Repository (a Gitee mirror is the faster route from inside China):

GitHub: https://github.com/rain6fish/KeelBase
Gitee: https://gitee.com/rain6fish/KeelBase
Two things stated plainly. The external anchor has no endpoint today, so any conclusion about tail completeness is unknown. That is not caution, it is the fact. And the deliberate absence: we would rather declare one gap fewer than attach an unverified caveat to every package.

An honest audit package does not say it has no gaps. It says which ones it has.

Drafted with an AI assistant. The system, the positions and the mistakes are mine.

AI Execution Governance, Part 7: One Timeout Cannot Answer Two Questions

Rain S — Mon, 19 Oct 2026 00:55:56 +0000

An AI asks to write something, and a person has to approve it.

There are two kinds of "expired" in that sentence, and they are not the same thing:

should the conversation keep waiting for the approval, or move on without it
can this row still be decided at all, or is it dead

We used one timeout to answer both. What that produced was a list showing "waiting on you" for a row where clicking was guaranteed to fail.

This piece is about splitting those into two windows with one function each, and about the single point where a decision has to be arbitrated.

1. Why they look like one question

Both read as "how long does a confirmation last", and once there is one number, the instinct is one column.

But they answer different questions, and different things consume the answers:

The question	Who consumes it	What a wrong answer costs
should the conversation keep waiting?	the one stream that is waiting	waiting a little too long, or moving on a little early
can this row still be decided?	the data layer and every decision entry	a click that cannot execute, or a row that is dead and still actionable

A wrong answer to the first costs experience. A wrong answer to the second costs consistency. And when they share a value, the second question's answer gets dragged around by the first one's needs.

2. The scene: computed in two places, held together by a comment

This happened to us.

The offline window's boundary was computed twice: the read path compared timestamps in memory, and the maintenance sweep compared them in SQL.

What kept the two in agreement was a comment in the code, saying roughly that the predicate here matches the one over there.

A comment is not a predicate. The day the two disagree, you get a row like this:

the list shows "waiting on you", while the sweep has already expired it.

So the click fails, necessarily. And it is not an occasional failure: the list manufactures it, by presenting a dead row as a pending task.

What makes this hard to find is that it looks like "the click sometimes fails", while the cause is two places holding different definitions of the same instant.

3. Fix one: two windows, and one function per boundary

There are two halves to the fix.

First, admit they are two windows.

the in-conversation wait is short, 60 seconds by default, and its expiry only ends that wait so the conversation can continue. It does not touch the data.
the offline window is long, 24 hours by default, and the row stays decidable inside it. Only its expiry flips the row to timed out.

Second, every boundary is computed by exactly one function.

The read path and the sweep both call it and get the same instant. So "shown as actionable" and "already expired" become structurally impossible to be true at once.

The point is not that the arithmetic is right. The point is that there is one place doing it. Two places and all you have left is a comment promising they agree.

4. Fix two: one arbitration point for decisions

Once there are two windows, there are two decision entries: the button in the conversation, and the pending list afterwards. They can race.

So the second thing is to make them contend for the same thing.

What we do is a conditional update in the database, where the condition includes "the current status is still pending". Then:

the update touches one row, so this decision stands and it executes
the update touches zero rows, so somebody already decided, and this one does not execute

Why not read, then decide? Because there is a gap between the read and the write, and both decisions can read "still pending". That is a decision placed before the action without the arbitration being placed before the action. A conditional update is atomic: whoever changes the row first owns the decision.

Two entries, one arbitration point. That is the whole of this section.

5. The second scene: one "we don't know" read as "yes"

Another one of ours.

A decision has to be written before it counts. What if that write throws?

The old behavior swallowed the error and released the in-memory wait anyway. Which gave this chain:

the database hiccups, the write fails
the in-memory wait is released, so the tool runs
the row is still pending
the next decision, in the conversation or from the pending list, sees "still pending" and runs it a second time

A "we do not know whether the decision landed" was read as a "yes".

The fix is plain: without evidence that the decision reached the database, do not release. Fail this one and let the person retry, rather than translating uncertainty into execution.

One thing worth being precise about: for external tools with no idempotency key, that second run is a real replay and the target really does receive it twice. On that path, failing closed is not caution. It is required.

6. A boundary this design does not cross

The arbitration point guarantees at most one decision.

It does not guarantee the tool runs at most once. If the same request gets resent, by a model retry or a restart, that is a different problem and it has to be solved at a different layer.

The two must be kept apart: one is "the same decision cannot be taken twice", the other is "the same call cannot be sent twice". Rolling them into a single sentence about "we guarantee it executes once" is overclaiming.

We put that in the result messages and in the docs rather than leaving it to be discovered.

7. A check you can run yourself

Four questions.

How many questions does your timeout answer? If one value decides both "does the UI keep waiting" and "can this row still be used", that is a shared value.
How many implementations does the boundary have? Two is one comment away from drifting.
What arbitrates a racing decision? An in-memory check is not arbitration. A conditional update, or any atomic compare-and-swap, is.
What is the default when a decision fails to persist? If the next step after a failed write is "execute anyway", the default is allow.

Closing

Back to the opening: one timeout cannot answer two questions.

What we do: split it into two windows, 60 seconds of in-conversation waiting and 24 hours of decidable pending; compute each boundary in exactly one function; make every decision contend for one conditional update; and release nothing without evidence that the decision landed.

The mechanism above is taken from KeelBase, an open-source runtime that sits between an AI agent and a business system and re-checks identity, authorization, scope, risk and confirmation state before a tool actually runs.

Repository (a Gitee mirror is the faster route from inside China):

GitHub: https://github.com/rain6fish/KeelBase
Gitee: https://gitee.com/rain6fish/KeelBase

Two things stated plainly. The boundary above: we guarantee at most one decision, not at most one execution. And a premise of the whole design. It assumes decisions can be persisted. If the database is unavailable we refuse rather than allow, which for some systems means confirmation stops working entirely. That is deliberate. If confirmation means "nothing runs that was not confirmed", then when nothing can be confirmed, nothing should run.

Drafted with an AI assistant. The system, the positions and the mistakes are mine.

AI Execution Governance, Part 6: The Unique Constraint Guards the Ledger, Not the Action

Rain S — Thu, 15 Oct 2026 01:41:24 +0000

An assistant calls a tool that writes. That call can arrive twice: the model retries it, the same confirmation gets decided twice, or the process restarts mid-flight.

A second arrival must not write a second time. The usual answer is an idempotency key with a unique constraint on it, and that is not enough on its own. The constraint is enforced when the row is written, and the row is written after the action. The ledger ends up with one row while the target has been written twice.

A unique constraint protects the ledger, not the action.

The proposal is to take a claim before the action runs, and to let that claim decide who executes. The rest follows from it.

1. Why "check, then act" is not enough

Start with the version that is easiest to write.

Before executing, check whether the key exists. If it does not, execute, and record the key afterwards.

With one request in flight this is fine. Under concurrency it is broken. Both requests read "not there yet", so both execute. When they later record their keys, the unique constraint rejects the second row. The action has already happened.

So the constraint stopped the second recording, not the second write. That is the sentence above, spelled out: a constraint on the ledger cannot reach an action that has already left it.

There is a name for the shape: check, then act. There is a window between the decision and the action, and whatever happens inside that window is invisible to the decision.

2. The fix: claim before acting, and let the claim arbitrate

The fix is small. Replace the check with a claim.

Before executing, insert a row into a claims table. Its unique constraint is the arbitration point:

the insert succeeds, so this execution is mine and I continue
the insert fails because the key is taken, so someone already holds this execution and I do not run it

What matters is not the row. It is that the insert happens before the action. The insert is atomic, so who owns the execution is settled before anything runs, with no window in between.

That also explains why ownership cannot be inferred from completion. If the only thing you can observe is "the write finished", then both concurrent requests observe "not yet" before either acts, and you are back to check, then act.

3. What the key is made of

This part deserves its own section, because it decides what counts as the same write.

Ours is four things hashed together:

hash( who : which conversation : which tool : arguments with keys sorted )

Taking them in turn:

who. The same tool with the same arguments for a different user is a different write.
which conversation. A repeat inside one conversation is a retry. The same call twice across two conversations is two events.
which tool. No explanation needed.
the arguments, with their keys sorted first. This one is load-bearing. Sorting makes two spellings of the same call compute the same key. Without it, {a:1,b:2} and {b:2,a:1} produce two keys, the same call is treated as two writes, and the idempotency has a hole in it.

Those four answer is this the same call. They do not answer what will this write touch. Those are different questions, and collapsing them into one field causes a different set of problems, which is a separate subject.

4. After claiming, if the write fails, does the claim go back

This is the hard part, and our answer is not yes or no. It is two branches, and the branch is chosen by what we actually know.

A local write: we know the outcome. A failure is a failure, a row that landed landed. That branch can release the claim so a retry really retries, or keep it and record the failure honestly. Either way, the point is that we know what we know.

An external write: we do not know. The request went out and no answer came back, or the connection dropped. Across those three cases the other side may well have received it. Release the claim here and let a retry run, and the retry is a real second write.

So the external branch deliberately keeps the claim, and says so in the result:

that request may have reached the target system, the outcome is theirs to report, and nothing is retried here.

That sentence is not a phrasing choice. It is the behavior. When we do not know, we do not let the retry through, because a retry converts "unknown" into "possibly twice".

5. What a second arrival returns

The second request should not write again, and it should not be reported as a failure either. It did nothing wrong.

What we do is replay. On a hit, the recorded outcome is returned to this call, marked as reused:

{ id: <the id recorded the first time>, idempotent: true }

The caller gets the same result the first call got. From its side, "I called once and got an answer" is true.

Composite writes need one more thing. When a single call writes several rows, the base key is held by the root member, so a hit has to replay the whole group rather than the root alone. Return only the root and the caller loses the other members, which will then never be declared again.

6. A boundary we cannot cross

Everything above stops us from sending twice.

It does not make the effect once-only end to end. For that, the target system has to honor the key: we send it along in a header, and whether the other side deduplicates on it is the other side's decision.

Put precisely: we can guarantee we do not resend; we cannot guarantee they receive once.

We put that in the result message rather than leaving it for the reader to discover.

7. A check you can run yourself

Four questions. Any one of them without a good answer is a window.

Is there a gap between deciding and acting? If the code checks and then does, the gap is there.
What defines "the same write"? If the key omits who or which conversation, then a different user or a different session with identical arguments collapses into one write, which is the other kind of wrong.
Are the arguments sorted before hashing? If not, two spellings of one call compute two keys.
After a failure, what does a retry do? If the answer is anything other than "it depends on whether we know the other side received it", it is probably a guess.

Closing

Back to the sentence: a unique constraint protects the ledger, not the action. Remember that and the first check runs itself, because the question becomes whether the decision happens before the action or after it.

What we do: claim before acting and let the claim arbitrate, key on who and which conversation and which tool and sorted arguments, branch the failure policy by what we know, and replay the original outcome when the same call arrives again.

Two things stated plainly. The boundary above, that we do not guarantee the other side receives once. And a limitation on the mechanism itself: it holds only when the arguments fully express the write. If a tool's behavior also depends on something outside its arguments, such as the current time, a random draw, or external state, then the same arguments twice are not the same write, and a key over them says nothing true. A tool like that has to be changed to take those things as arguments first. Until then the key is decoration.

Drafted with an AI assistant. The system, the positions and the mistakes are mine.

AI Execution Governance, Part 5: Human Confirmation Cannot Be a Boolean

Rain S — Mon, 12 Oct 2026 00:55:00 +0000

The earlier pieces were about stopping things: where the boundary sits, how risk gets tiered, how a write gets undone. This one steps back and looks at a single part.

What the system actually holds after a user clicks "yes".

It is the easiest part of the chain to build too thin.

The shape it collapses into: a boolean An AI wants to write something. It asks, the user sees a confirmation, clicks yes, it runs.

If "yes" is a boolean, confirmed = true, there are two problems.

The smaller one is that it can be reused: can the same yes approve a second thing. That is not a new problem, and marking it one-shot settles it.

The larger one is quieter: a boolean is a sentence, not a credential. The word "yes" cannot answer any of these:

which request was approved?
approved to write what?
approved to write it where?
approved to change it how much?
until when is it valid?
If it cannot answer those, then the answers are decided at the moment of execution instead, and that moment sits some distance away from the nod. Anything that changes in between goes unnoticed by the user.

What we do is make the yes a row, binding five things. Each one below comes with what breaks without it.

Bind what: the exact arguments A confirmation binds the arguments of that one call, character for character.

Not "the arguments have to fall in some range", but "these are the arguments". Whatever they were is what has to run; one character off and it is refused.

That is stricter than a value domain, and the cost is worth stating: the whole set is accepted, or the whole set is refused.

It cannot express "in this approval, status may change but owner may not", because the arguments are bound as one sealed package. Expressing that needs something else, which is section 4.

Bind where: the destination This is the one a reader had to point out to us.

The original version recorded the tool and the arguments. That looked sufficient. What would be written was locked down. What else could move?

Where it would be written.

The tool name and its arguments are both things on our side. Which external system the write actually lands in is a separate matter: a proxy tool's configuration can be re-pointed, an external service can be re-registered. The approved record sits in the database with every argument unchanged, while the place it is headed has been swapped for another.

Nothing in the record contradicts it.

The fix is to bind the destination too: record it at issue time, re-resolve it at execution time, refuse when the two disagree. Never follow it silently.

Worth remembering on its own: "approved" and "approved to where" are two different things.

Bind how much: the writable field domain Why this, if the exact arguments are already bound?

Because the exact arguments can only accept or refuse the whole set, while what a confirmation usually means is per field:

this time it may change status;
but it may not change owner.
Only declaring the writable fields separately can say that.

It sits alongside the exact arguments rather than replacing them: one answers "are these the values", the other answers "may this kind of field be written at all". The convention matches the rest of the system: nothing declared means nothing constrained; anything outside the declared set is refused, and not truncated. Truncation would read as "part of it changed" when what actually happened is "a write that should have been refused was silently narrowed and allowed".

Bind when: the window That a confirmation expires is not news. What is easy to miss is where the expiry is kept.

The mistake we made: the window lived only on the token. Once the token was consumed, it was gone. So looking at that row three months later could say "it was approved" and could not say what the window had been.

And that is exactly when it matters. Someone asks why a write was allowed at that time, you go to the record, and the window turns out to have depended on the configuration at issue time, which has since changed.

The fix is plain: write the window into the row at issue time, and later read the value on the row. Do not recompute it from the current configuration.

Bind who, and which one Two last things: the operator, and the moment of the decision.

And refusal goes through the same binding as approval.

That last clause is deliberate. If "no" were a separate path with its own switch, the two would drift apart. A binding added to approval today gets forgotten on the refusal path tomorrow. Sharing one record and one entry point makes that impossible.

A check you can run yourself Don't start with "is my confirmation strict enough". Start with something more specific:

Which fields in your confirmation are computed once at issue time and computed again at execution time?

Anything like that can drift. Three questions to test it:

Point the same confirmation at a different target system. Does it succeed?
Change one argument. Does it succeed?
Three months later, can you say what the window or the policy revision was?
Any "yes" or "can't tell" marks a place that was left unbound.

Closing
Back to the opening shape: if "yes" is a boolean, it is a sentence, not a credential. And every promise in the chain comes to rest on this part. The audit records who approved what. Revocation undoes the write that was approved. Build this part thin and every later link is quietly covering for it.

The five we bind: exact arguments, destination, writable field domain, validity window, operator and decision moment.

Two things we have not done, stated plainly. The field domain can say whether a kind of field may be written, and cannot express a cross-field rule, such as "B may change only if A did". And the window column was added later, so rows older than it do not return that field. Their window is not knowable, and we do not invent a default for it.

One question we decided not to pursue, since it is the natural next step from here: why not issue a credential per approval?

We costed it. The confirmation is already one-shot, a credential is already short-lived and scoped to one target system, and the destination is now bound as well. Together those cover the worry. Another layer buys duplicated complexity, not a new guarantee.

So it is a trade-off, not a gap waiting to be filled. It is here because anyone who takes this seriously will ask it.

Drafted with an AI assistant. The system, the positions and the mistakes are mine.

AI Audit Evidence, Part 1: When a Record Has No Word for Unknown

Rain S — Thu, 08 Oct 2026 01:05:53 +0000

Something happened recently that I want to start with.

We fixed a defect: four different kinds of "nothing" were collapsed into a single switch, so the readings couldn't tell "by design" from "broken". Then we moved on to the next thing. The day after that new field landed, a reader pointed at it in a comment, named the same defect again, and wrote down what to do about it.

This isn't the same bug coming back. It's the same class of bug growing back in the place where we thought we had learned it.

This piece is about one thing: when a record has no slot for "unknown", "unknown" reads as "known" — and specifically as the strongest statement that field can make.

Four kinds of "nothing", one switch Background first.

When the AI writes a record, we keep a snapshot of what it looked like before and after. Revocation needs to know where to go back to.

The trouble was in "we couldn't capture the after-snapshot". There are at least four reasons that happens:

no captor was wired at all — an optional piece by design
the entity didn't resolve, and the fallback data was empty too
the entity resolved but the row is gone — an anomaly
the capture threw — an error
The first two are what the design chose. The last two are something went wrong.

We had one boolean field for all of it. Four reasons, one switch.

So when someone asked "why are these snapshots empty", there was no answer: you couldn't tell by design from broken. The worse part is the direction. That switch defaults to false, which reads as "the snapshot is fine".

"Nothing" is not one value, it is four different values. Collapsing them into one boolean lets the strongest reading answer for all of them.

We split it into four causes, each stored and readable on its own. While splitting it we also found that two of the four names we had first proposed didn't belong in that class at all. One lives on a different path (the table consulted before the write), and the other is a mechanism rather than a cause. So the four that landed are not the four we started with.

The next day, in the field we had just written With that fixed, we moved to the next thing: before a revoke, record which members this attempt intends to compare.

The promise matters here. Before the revoke it's a promise; after it, an actual. Only the difference between them lets you say "a member I promised to compare turned out not to be comparable". The implementation put a column on the group's root row to hold that difference. If this attempt found no difference, the column is written empty.

That looked fine. Then someone wrote this in a comment:

A per-reason column sits on the member row and gets rewritten by whichever revoke attempt ran last, so a second attempt erases the first attempt's broken promise. Append-only keeps them apart.

He's right, and it's slightly worse than he put it.

When the attempt finds no difference, that column is written empty. And that empty means two things at once: "the last comparison found no difference", and "this row was never revoked at all". So:

the first revoke found "promised, but couldn't compare" — recorded
the second revoke went fine — and wrote over the first attempt's record with an empty value
reading that row later: empty. You can't tell "there was once a broken promise", and you can't tell "it was cleared"
A retry that succeeds erases the earlier attempt's failure record.

To be fair to ourselves: that clearing is deliberate. The reasoning is in the design record from when it landed — a stale difference shouldn't outlive the comparison that produced it. The reasoning isn't wrong. What's wrong is that the empty value had no second meaning available.

Then we changed it to what he described.

One row per attempt that reached the comparison, instead of one shared cell. The two readings are separated where they are written: this row is either "a difference was found" or "checked, and there was none". So:

a later attempt no longer erases an earlier one — it writes its own row
an empty history (no attempt ever reached the comparison) and "checked, clean" are no longer the same reading
the old rule — a stale difference shouldn't outlive the comparison that produced it — was withdrawn. It was wrong about using one cell for two things, not about keeping old records
The old column wasn't dropped. It's still read, as a legacy entry marked "written at a time we can't know". Deleting it would erase exactly the evidence this whole argument was about.

One place in the same system got it right Both of the above are "no slot for unknown". But one place in the same system does have a slot.

When a revoke goes out to an external system, all we can do is send the request; the terminal state is on their side. Their 2xx only proves the request arrived, not that they undid anything. So that row doesn't write "revoked". It writes "compensation requested, outcome unknown" — a dedicated reading.

The effect is immediate: nobody misreads it as done. The interface says plainly that the result is with the target system. No gloss needed.

So this isn't impossible. It's a question of whether you noticed that "unknown" needed a slot. Give it one and it stays put. Don't, and it falls into the strongest reading available.

Why it's hard It's hard because the default is silent.

Every field decides for you, and it always picks the cheapest reading:

a null value reads as "no such item"
an empty collection reads as "no difference"
false reads as "not marked", and from there as "fine"
Those readings are correct almost every time. The problem is the rest: when "nothing" and "unknown" share a value, you have a field that lies — and it stays quiet while doing it, until somebody acts on it and gets "everything is fine" on your behalf.

Worse: fixing one instance doesn't remove the class — including while fixing it.

Here's something that happened inside that fix. Once "no difference" had its own reading, there was still a function whose empty return meant two things: everything really was compared, and there was nothing to promise in the first place (with no captor wired, "compare" isn't defined). Writing "checked, clean" is right for the first. Writing it for the second would vouch for a check that never ran.

We nearly did. What we changed it to: nothing was promised, so no row is written.

That's why the entry points for this class are every "nothing" there is. Fix one, and it waits for you in the line of code where you write the fix.

A check you can run yourself Don't start with "is my record complete". Start with something more basic:

List every value in your system that means "none / unknown / empty", and ask of each: what does it read as?

Anything that carries two meanings at once is a potential misreport. Three common shapes:

Shape It also means
a null value "no such item" / "looked, found none" / "never looked"
an empty collection "genuinely none" / "couldn't read it out"
false / a default "not marked" / "marked as no"
The test is simple: when this value is empty, can a reader still say why it's empty? If not, the field is guessing on their behalf.

Closing
This kind of problem is hard to find because it doesn't throw. The system runs, the interface renders, and one cell quietly says something untrue.

And the place it shows up most is the place you just fixed — because that's when you're busy already knowing how to do it.

Where we stand: we know the pattern now, and we've fixed two instances — the second one's shape came from the reader. We have not done a systematic pass: how many of those three shapes are in our record layer, and what each one reads as, is not a list we have.

So this one doesn't close on a conclusion. Run the check against your own system and you'll likely find a few. On our side, we only know we haven't finished looking.

Drafted with an AI assistant. The system, the positions and the mistakes are mine.

AI Execution Governance, Part 4: Before a Boundary Holds, Ask What It Encloses

Rain S — Fri, 02 Oct 2026 13:55:13 +0000

After the first few pieces went out, three questions came back. They don't look related:

Is tool the right unit for an AI's actions?
How do you monitor a path you didn't know existed?
What about a sluice gate on a dam, a reactor's safety systems, a car swerving into pedestrians?

I can't answer any of them completely. But they're all asking the same thing:

What does your boundary actually cover?

And the answer to that matters more than how strict the check is.

1. Hardening is the reflex

When a boundary gets challenged, the reflex is to add. More rules, more confirmations, more logging, a finer-grained check.

All of that helps. All of it applies only to actions the boundary already covers.

A minimal comparison:

Deleting data — has a name (delete_customer), has a tier (R5), a policy can block it
A screen click — has no name

You can't put a gate on the second one. Not because the policy isn't strict enough, but because there is nothing to attach it to.

So the order should be: enumerate first, harden second.

2. Enumeration is the precondition

To put a gate on something you need three things: a name, a set of arguments, a risk tier.

A discrete action surface has all three. A function call, an MCP tool, an OpenAPI endpoint — each has a name, arguments, and can be assigned a tier. With those three in place, everything the earlier pieces described becomes possible: risk classification, human confirmation, an audit trail, revocation. All of it rests on those three.

A non-discrete action surface has none of them. A computer-use agent is clicking around a screen. An agent with a shell is typing commands. A long-running autonomous agent leaves a trajectory. None of that has a name. You can't say which tier it belongs to, which means you can't put a gate anywhere on it.

It isn't that the policy is too loose. There is nothing to attach it to.

3. Where we stand

Three kinds of action surface, three different states:

Action surface	Enumerable	What the boundary can do	Our status
Tool calls (MCP / OpenAPI / function calling)	Yes	Tier, confirmation, audit, revoke	Implemented
Non-discrete (computer-use / shell / long trajectories)	No	Nothing to attach to	Not implemented, and out of scope
Physical actuators (gates / reactors / vehicles)	—	Not a business runtime's job	A different safety regime

The middle row needs to be said plainly, because it's a scope statement, not a todo.

What we build is AI calling business systems. The action surface is tool calls, which are enumerable. Non-discrete action surfaces we don't intend to cover. It's written here so people know where the boundary stops, instead of assuming it extends indefinitely.

The consequence, stated properly: if you wire an agent to a shell, this boundary is worth zero for it. Not weaker — absent.

The third row, since it came up: dam gates, reactor safety systems, self-driving. Those aren't a business runtime's work. They belong to industrial functional safety, with its own standards and its own methods. Answering that with an enterprise application's governance layer is answering the wrong question entirely.

4. A check you can run yourself

Instead of asking how strong your governance is, ask something more basic:

Can you list every action this agent can take?

If you can — there's a list, things have names, each entry is describable — then you can go on: assign tiers, require confirmation, add auditing. Everything the earlier pieces described starts to mean something.

If you can't, don't add rules yet. The actions you can't name are outside the boundary. And what happens outside the boundary is not reachable by any rule, however strict.

A shorter list that's exhaustive is a real boundary. When the list is incomplete, hardening only makes the inside stricter. It doesn't make the outside controllable.

Closing

Back to the three questions. I still can't answer them completely.

But there's one idea that's more useful than an answer:

A boundary isn't drawn. It's listed.

The actions you cover are the list. Outside the list, there is no boundary.

Drafted with an AI assistant. The system, the positions and the mistakes are mine.

AI Execution Governance, Part 3: Revocation Is Not a Button

Rain S — Thu, 24 Sep 2026 00:55:48 +0000

The first two pieces were about stopping things — put the boundary on the execution path, then give every tool an execution policy by risk.

But some of it can't be stopped. The policy allowed it, the confirmation passed, the write completed. The AI has already written to the database. Now the question changes:

Revocation.

It sounds like a simple action: add a button, click it, show "revoked". In practice, revocation is probably the easiest link in the whole governance chain to fake.

1. Revocation is the last link in the chain

Three pieces, three positions:

Before execution: set the boundary (the prompt isn't one; the runtime is)
During execution: set the policy (reads automatic, writes confirmed, high risk blocked)
After execution: be able to take it back — this piece

The first two were about stopping what shouldn't happen. This one is about what to do once it already has.

There's a question that's easy to skip: to revoke an AI write, how far do you have to go before it counts?

Before answering it, here's what we can't do, up front. The reason is blunt — an article that only lists strengths gives a reader nothing to reply to.

2. What we can't do

Async side effects have no intermediate state modelled.

This whole mechanism assumes a tool call lands in the database synchronously. If AI writes ever go async — dropped into a queue, sitting in an "in flight" state — you need a state machine to say "still in flight, can't revoke yet". That layer doesn't exist. AI writes here aren't async today, so it hasn't surfaced, but there's nowhere in the code reserved for it.

The terminal state of external compensation lives with the target, and we don't reconcile it.

The request goes out, the other side never answers, and the state hangs. (Section 5 gets to what it's called.) Today we hang honestly — the UI says the outcome is in the target system — rather than faking completion. Converging it would take polling or a callback. Not built.

Cross-group batches are independent per group.

In one batch revoke, each compensation group succeeds or fails on its own; one failing doesn't affect the others. The isolation is a feature. The cost is that there's no "sweep up what already succeeded" semantics. To back out, you revoke again yourself.

Batch revoke has no pagination and no cap.

It pulls every side effect for that conversation or run in one go and works through them. Simple semantics — one pass, one summary. The cost is unbounded size: a run producing several hundred side effects becomes a long request.

(An abandoned idea, while we're here. A cap of 500 per batch with a truncation marker. It got half-built before the flaw showed up — after truncating, re-running returns the same first 500, forever. Rolled back. Doing it properly means cursor pagination, which is a different piece of work.)

Those four come down to one thing: how mature revocation is doesn't depend on whether there's a button. It depends on whether the contract is written honestly. What follows is the design — what you can revoke should be verifiable, what you can't should be said plainly.

3. The dangerous failure isn't "can't revoke" — it's "think you revoked"

A case.

One AI call creates a project and splits out 10 subtasks. One business action. Eleven rows.

If the revoke only deletes the project, the 10 subtasks are still sitting there — and the UI already says "revoked". The user reads those words and moves on. Nobody looks twice.

That's worse than not revoking at all. Without revocation the user knows the data is still there, and will restrict the AI or clean up by hand. A fake revoke convinces them it's clean. The problem sinks.

Batches are the same shape. One run writes 5 rows; the revoke succeeds on 3 and fails on 2. Without a per-item summary there's no way to know whether it came back clean.

So the first question isn't how to revoke. It's defining the scope — which rows does one business action actually correspond to?

4. Revocation needs tiers, and it needs to be honest

Not every side effect can be revoked. Force them all down one path and you get fake successes everywhere. So revocation starts with tiers:

Class	Meaning	Revoke action	Where the state lands
`none`	Not revocable / the target system has no compensation endpoint	Refuse	No revoke state written
`local_compensate`	A local entity that can be soft-deleted	Soft-delete it	Target soft-deleted → restorable from trash; state `revoked`
`governed_external`	Written into an external system	Call the other side's compensation endpoint	A 2xx only proves "requested" → state `compensating` (terminal state lives in the target)

One thing that's easy to skip: declaring something revocable is not the same as being revocable.

The test is whether the tool, under the class it declares, has a verifiable revocation path. Does it have an entry point, does that entry point actually take effect, and how far does it get. All of that should be checkable.

The none tier is the counter-intuitive one. An operation that can't be undone should say so, instead of offering a fake revoke button.

An email that went out. An SMS. A completed payment. Anything physical. Those don't come back. Giving them a "revoke" entry point that reports success is worse than giving none at all. So they either get blocked at the risk-tier stage (R5), or honestly marked none, with the UI saying "not revocable / no external compensation".

5. External systems: "requested", never "revoked"

Once the data is in someone else's system, revoking involves that system.

The convention looks roughly like this: sign a delegated identity (audience-scoped to the target), then call the compensation endpoint they provide:

KeelBase → DELETE {baseUrl}{revokePath}{resultId}
           Authorization: Bearer <delegated JWT>

The endpoint returns 2xx. What does that mean?

Only that the compensation request went out. Not that they undid anything.

So the state can't be revoked. It can only be compensating, because the terminal state is on their side. That has to be honest at both layers:

API: 2xx → compensating, never impersonating a terminal state
UI: say plainly that the outcome is in the target system, rather than rendering a completed check

This is where products dress things up. Rendering "compensation requested" as "revoked", because the former looks unfinished. But every downstream decision the user makes on that fake state is wrong.

6. When one call writes many rows: compensation groups

Back to the project + 10 subtasks.

The fix is to have the tool declare what it wrote: a composite write tool returns a list of side effects, and by convention the first entry is the principal object — the project.

Everything from that one call then belongs to a single compensation group. The group key is the call's idempotency base key, which has a useful property: a retry lands in the same group by construction, with no extra id to generate.

With groups, the rule is simple: revoke any member, and the whole group is compensated.

The local members of a group go into one database transaction — all of them go, or none. That matters, because "half revoked" is the worst intermediate state here: project deleted, subtasks still present, exactly the fake revoke from §3. The transaction makes it impossible.

Batch revoke has a matching requirement: it must fold by compensation group. Otherwise a three-member group gets compensated three times — the first genuinely, the next two churning on top of it.

One more boundary: for a tool that doesn't declare its side effects, the system's record is exactly as wide as the declaration. If the tool really wrote 10 rows but declared 1, the system knows about 1. That's honest — the recorded scope is the declared scope — but it's a contract defect on the tool's side, not the system's.

7. The revocation itself has to be recorded

Revoking isn't making something disappear. It's taking it back in a way you can point to.

When compensation completes it writes an operation-audit row with action = COMPENSATE, onto the hash chain. The important part: targetId holds the root business object's id — the project — not one of the eleven effect rows. That's what lets you look it up by business object: how exactly was this customer or project revoked, by whom, and when.

Ownership, while we're here: a user can only revoke side effects they triggered; an admin can revoke anyone's. Both paths leave a record. Revocation permission is itself a boundary.

8. Revocable is not the same as restorable

The two get conflated. They're different things.

A local revoke is a soft delete — the row gets a deletion marker, disappears from normal views, and can still be restored from trash.

Revoke: take back something the AI did
Restore: change your mind about the revoke

Taking something back and putting it back are two semantics with two entry points. And the restored state should be authoritative server-side — don't let the frontend infer it, or it drifts on the next refresh.

Closing

Which comes down to: revocation isn't a button, it's a contract.

An honest revocation contract answers at least four questions. Which data does this business action cover (scope). Which class is this tool in (capability). What state is it in once the request goes out (honesty). And was the revocation itself recorded (provability).

If you're building agents, four things worth testing on your own system. When one tool call writes several rows, does the revoke leave some behind. For irreversible operations, is there a revoke entry point that lies. For external compensation, does the state say "revoked" or "requested". And can you find out afterwards who performed the revocation.

Once a system can honestly label both "didn't come back clean" and "can't be revoked", it's something people can actually trust.

Drafted with an AI assistant. The system, the positions and the mistakes are mine.

AI Execution Governance, Part 2: Classify AI Writes First, the R0–R5 Tool Risk Model

Rain S — Sun, 20 Sep 2026 00:25:28 +0000

The previous piece, "Runtime over Prompt", argued that the security boundary belongs on the execution path — immediately before a tool call can produce a side effect.

This one goes a level deeper. Once the boundary sits on the execution path, the runtime has to answer a question it can't dodge: should this tool be allowed to run at all?

And the operations enterprises actually hesitate over are rarely reads. Querying a customer is fine. Updating one? Emailing one? Deleting one?

1. Reads and writes are not symmetric

When an AI gets a read wrong, it "saw it wrong" — you fix it and move on. The blast radius is small.

When an AI gets a write wrong, it "broke it" — a wrong order amount, an overwritten customer record, an email sent to the wrong person. Much of it is irreversible or expensive to undo.

So there's a gap between "let it look" and "let it act", and the gap is really this: should every operation be governed by the same policy?

Obviously not. Querying can be automatic. Changing a contract needs a human. Deleting data shouldn't be allowed at all.

That's what tool risk tiering is for: give every AI operation a risk level, then let the level decide the execution policy — instead of a blanket "all automatic" or "all human-reviewed".

2. R0-R5: a tiering you can actually ship

Six levels, low to high, each mapping to one execution policy:

Tier	Meaning	Example	Execution policy
R0	Informational	Explanations, summary stats	Automatic
R1	Read	List customers	Automatic
R2	Low-risk write	Update a note	Policy decides (governance-configurable)
R3	Business-sensitive write	Create a follow-up task, change an order	Human confirmation
R4	High-impact action	Operations needing dual approval	Dual approval
R5	Irreversible / external action	Delete data, send email	Blocked

Three design decisions worth calling out:

Reads automatic, writes confirmed, high risk blocked. Low-risk work stays automatic; high-risk work gets a human; irreversible work is stopped outright.
Explicit declaration wins; otherwise derive from semantics. If a tool declares its tier, that tier is used. If it doesn't, writes default to R3 (confirmation) and reads to R1 (automatic). An undeclared tool is not waved through — it is conservatively held.
Policy can override. The governance layer can override a single tool's enablement and confirmation requirements at runtime, with immediate effect.

The point of the tiering: it turns "do we dare let the AI do this" from a feeling into a rule. Nobody has to judge tool by tool; they set policy by tier.

3. How the tiering is enforced at runtime

A tiering is paper until the runtime enforces it. The chain:

Tool declares its tier (R0-R5) → permission check (row-level scope: own / org) → policy gate (R5 blocked / R3-R4 confirmed / R0-R2 automatic) → human confirmation (executes only on approval) → write executes → side effect recorded (revocable) + audit chained

Using the open-source KeelBase implementation as the example, the chain is verifiable.

Repository: https://github.com/rain6fish/KeelBase

Declaration: every AI tool carries a riskLevel, and the MCP endpoint surfaces it in the tool declaration (_meta.keelbase) — visible to external clients before they call anything.
Gate: R5 is blocked outright (the response states plainly that the operation was blocked by security policy); R3/R4 return a confirmation marker and execute only after approval.
Audit: every execution lands on the audit hash chain; denied calls are recorded too — an authorization denial writes isError=true plus the reason list. Tamper-evident and traceable.
Revoke: side effects created by AI are recorded and can be revoked, including cross-system compensation.

The protocol conformance suite pins these semantics. Output from Server-NestJS/scripts/verify-protocol-conformance.mjs:

─ Tool risk tiers (protocol §4) ─
  ✓ RISK_STRATEGY table matches the vectors
  ✓ R1 (read) → auto / no confirmation
  ✓ R3 (business-sensitive write) → confirmation
  ✓ R4 (high-impact) → human_approval
  ✓ R5 (irreversible/external) → block
  ✓ Derivation: undeclared write tool → R3 confirmation
  ✓ Derivation: undeclared read tool → R1 auto

═══ Conformance: 34/34 passed (0s) ═══

Tampering, tier escalation, and confirmation bypass all get rejected here.

Closing

AI writing data isn't the problem. Tiering it, confirming it, and being able to trace it is what makes it shippable. Turn "do we dare let the AI act" into a rule you can execute, and it can move from assistant to doing real work.

If you're building agents, three questions worth asking about your own system:

Does your tool inventory contain writes with no execution policy at all — callable, so they run?
For a tool that declares no risk level, does it default to allowed, or to conservatively confirmed?
When a high-risk operation is stopped, did the model say "I can't do that", or did the execution layer actually refuse?

The third is the one that matters. If the answer is "the model refused", the boundary is still in the prompt, not on the execution path.

If you find a way to bypass a tiering rule or a gate, open an issue — I'm more interested in the failure cases than the successes.