DEV Community: Anthony Garces

Inside the Append-Only, Hash-Chained Journal

Anthony Garces — Mon, 28 Sep 2026 09:07:53 +0000

TL;DR: Ranex keeps verdict records in an append-only, hash-chained SQLite journal so ordinary rewrites are blocked and edited rows are detectable, while rollback and truncation remain an explicit open limit. Read how the kernel works.

Someone asks why a change was allowed out the door. You open the audit record and find a clean story. What stops that story from being cleaned up after the fact?

A record that can be quietly rewritten is not evidence of a decision. Ranex records verdict activity in an append-only hash-chained journal. The design does not turn a local database into an untouchable historical archive. It does give you a concrete way to detect a row edit and a concrete command to check the chain.

In this note

The record must resist a quiet rewrite
Two controls cover different paths
Check the journal you depend on
The limit is rollback and truncation

The record must resist a quiet rewrite

An append-only journal preserves the sequence of admitted events rather than a polished final summary. That matters when your question is not “what does the database say now?” but “what evidence and verdict existed when this decision happened?”

Ranex’s journal is a SQLite record. Ordinary updates and deletes are prohibited by SQLite triggers. Each journal row also carries a link into a hash chain, so a row has a relationship to the history before it. The operator command ranex journal verify recomputes that chain. Those facts provide a useful control: the normal application path cannot edit or delete a row, and an edit made around that normal path is not supposed to blend into the sequence unnoticed.

Do not reduce this to “there is a database.” A database can retain the latest story while losing the important question. When did the story change, and what did it replace? Append-only changes the shape of what the journal is for. The journal is a record to replay alongside the deterministic verdict path, not a mutable dashboard state that happens to contain audit-looking fields.

This is particularly useful when a worker produces a result you did not watch arrive. Ranex does not take the worker’s summary as proof; it reads the diff on disk and runs checks. The evidence, verdict, and journal give the operator something stronger than a completion message. They give the operator materials to inspect after the excitement has passed.

Two controls cover different paths

SQLite triggers and a hash chain are not duplicates. The triggers block ordinary rewrite attempts; the chain makes an out-of-band row edit visible when verification recomputes the links.

Imagine a program, a stray maintenance script, or an agent with access to the database trying to issue an ordinary update or delete. The SQLite triggers prohibit that normal operation. That is a direct guard where application behavior meets the journal. It helps keep “fix the record” from becoming a casual recovery move.

Now take a different route. An attacker edits the database file outside the normal path. A trigger cannot fire for a change that bypasses the SQL operation it protects. The hash chain is for that case. A changed row breaks the relationship with following rows, and ranex journal verify recomputes the chain for the operator. Verification is the important verb here. A chain nobody checks is only a claim about how rows were written.

There is no magic in the word hash. The value of the design is that it gives you a defined test against a defined class of edits. You can run the verifier instead of accepting an application’s self-description. You can ask whether the record still links as it should. If it does not, the journal has evidence of a problem rather than a quietly amended history.

The repository also says concurrent appenders are serialised before reading the previous link. That keeps append operations from racing into incompatible predecessor links. It is a consistency property for the chain. It is not a claim that the journal has solved every preservation problem, which brings us to the line that needs to stay visible.

Check the journal you depend on

You can apply the lesson before you use Ranex. Find the record your release process calls an audit trail, then ask whether it can tell an edit from an original event.

Does the normal application path prohibit updates and deletes of decision records?
Can an operator independently verify the relationship between successive records?
Does the record name the evidence, subject, and verdict it is preserving?
Would an edit outside the application leave a detectable break?
Who can copy, replace, or restore the record store?
Can a reviewer distinguish a current status from the sequence that produced it?

These questions are the reason the journal exists. Generated work can leave you with more activity than a person can remember. A future reviewer needs to connect a requirement, evidence, the exact artifact evaluated, and the verdict that allowed a next step. The journal is one part of retaining that connection. It does not decide whether the requirement was good; the approved flow graph is intended as the root of trust in the broader designed loop. It retains what the kernel saw and decided.

There is a natural boundary with signed evidence. Signatures establish something about who held a registered private key. The journal records the admitted sequence. Neither control replaces the other, and neither should be stretched into a claim it does not make.

The limit is rollback and truncation

The journal does not detect rollback or truncation. An internally consistent earlier prefix still verifies after later rows are removed.

That is the boundary named in the README’s known gaps. If later rows disappear and the remaining database ends at an older valid point, recomputing the retained chain succeeds. The verifier detects an edited row in the retained history; it does not know, by itself, that history was made shorter. Serialising appenders does not close this gap. Trigger protection does not close it either.

Keep the distinction sharp. “Tamper-evident for out-of-band row edits” is a useful claim. “Permanent history that detects every deletion” is not a claim Ranex makes. The repository’s Status section lists the append-only hash-chained journal as working today and names rollback or truncation as a known gap. The project remains pre-release.

That clarity is better for your incident response. If verification fails, you have a reason to investigate an altered chain. If it passes, you know the retained rows are internally consistent, not that no later history was removed. You can decide what additional retention or external anchoring your own risk requires without pretending the local journal already supplied it.

Questions people actually ask

How does a hash-chained journal detect tampering?

The Ranex journal links each row hash to the previous row, and journal verify recomputes the chain to expose an out-of-band row edit.

Can a hash-chained journal detect deleted entries?

The Ranex journal cannot detect rollback or truncation because an internally consistent earlier prefix still verifies after later rows are removed.

What stops ordinary journal updates and deletes?

Ranex uses SQLite triggers to prohibit ordinary updates and deletes, while the hash chain detects edits outside that normal path.

Try it. Break it. Tell me what broke. Read the Ranex repository, then inspect whether your own audit record can show a rewrite.

Disclosure: this post was drafted with AI assistance. Every factual claim traces to the repository’s README or slice records — the same fact gate the product enforces on code. It ships only after Anthony’s own review.

The Watchdog That Would Have Passed Every Test and Hung Anyway

Anthony Garces — Fri, 25 Sep 2026 09:00:16 +0000

TL;DR: A watchdog fixes a stall only when timeout errors are terminal and non-retryable; idle and absolute budgets cover different waits. That is the shape to hunt for after reading the Field Notes slice log.

You have a timeout. The test turns red when the provider goes silent. The build turns green when you add the watchdog. Then a real stalled turn sits there, your session stays busy, and somebody has to intervene by hand. A retryable timeout would have let the watchdog fire, let the criteria pass, and restarted the exact stall that caused the timeout.

In this note

The timeout that fixes nothing
Why one timeout cannot do two jobs
What to inspect in your own pipeline
The second hang hiding behind the first
Your next failure drill

That was the defect behind SLICE-012 in the Ranex harness fork. A stalled provider stream had no timeout, so its coordinator never settled and the active session stayed busy. The shipped change makes that stream reach a terminal state on its own. Good. The more useful part is the hole the tests could have missed.

The session would still hang anyway.

The timeout that fixes nothing

A timeout is only a fix when its failure path reaches a terminal state. If your retry policy recreates the condition that timed out, retrying it is a loop, not recovery.

Picture the order of events. A provider stream stops producing. The watchdog fires. The runner sees an error it is allowed to retry. It starts the stream again. The provider stalls again. The watchdog fires again. Your test can prove the timer fired. It can prove the retry happened. It can still miss the fact that the turn never ends.

SLICE-012 made the classification explicit: both watchdog failures are typed, non-retryable errors. That detail is load-bearing. The earlier prototype had avoided the retryability problem by accident. A pre-implementation review found that no requirement had said the timeout must be non-retryable, so the completed slice made the decision and required a test that proves it is not retried.

That is a small wording change with a large operational consequence. “Times out” is not enough. “Fails terminally, without retry” says what the system is allowed to do next.

If retry recreates the failure condition, retry is a hang with better logging.

If retry would only restart the stall, the failure class needs to say so. Your operator needs a terminal state, not a more energetic version of stuck.

Why one timeout cannot do two jobs

You need two thresholds when the waiting patterns differ by orders of magnitude. An idle deadline catches silence between chunks; an absolute budget limits the whole turn.

The slice wraps the stream with two separate controls. The idle deadline resets every time a chunk arrives. It answers: “Did the provider go quiet in the middle of a response?” The absolute budget races against the whole consumer. It answers: “Has this turn taken too long, even though activity continues?” Each one has to be proven without the other.

That independence matters. Feed chunks often enough and idle will never fire; only the absolute budget can stop an overlong turn. Disable idle and stall the stream; absolute must still cut it. One silent-stream fixture cannot prove both. It only proves whichever control fires first.

The first pull is deliberately untimed by idle. The records explain why: inter-chunk gaps run around 10–100ms, while a reasoning model can take minutes to its first token. One number cannot serve both distributions. An idle threshold tight enough for the gaps would cut the first response on every call.

There is a cost to that choice, and it is written down instead of tucked behind a pleasant name. A provider that accepts the connection and never sends a chunk is bounded only by the absolute budget. At the default, that can be up to 30 minutes. The record does not claim that setting is ideal. It names the limitation: a separate first-chunk budget, identified as the proper fix and left out of this slice.

Do not let one comforting timeout setting pretend it covers three different waits. First response, inter-chunk silence, and whole-turn duration need their own evidence. If you cannot show that evidence, say what remains unbounded.

What to inspect in your own pipeline

You can find this class of failure without adopting Ranex. Start where a streaming call, a retry policy, and a session state meet. The job is to make the broken path fail before you trust the repaired one.

Find every timeout and write down its failure class: retryable, non-retryable, interrupt, or something else.
For each retry, ask whether the next attempt changes the condition that failed. If it does not, prove the system settles instead of cycling.
Separate time to first token, gaps between chunks, and total work time. Do not reuse a threshold merely because it is nearby.
Make a stream send one chunk and then stall. Confirm the session reaches a terminal state without a person stopping it.
Make a healthy slow stream complete below the idle threshold and below the whole-turn budget. A watchdog that cuts legitimate work is not a watchdog you can trust.
Run the timeout while tool work is in flight. Check the actual tool state and settlement, not a log line that says cleanup happened.
Use a non-default timeout and prove behavior changes. Reading a configuration value back is not proof that it controls the running system.

There is no glamorous trick here. You are looking for the exit from failure, not the detection of failure. That distinction saves you from a green test whose only achievement is proving a timer owns a clock.

The second hang hiding behind the first

A watchdog failure is an error, not an interrupt. That difference left tool fibers dispatched during streaming uncleared, and the later settlement wait held the turn open forever.

This is the defect that showed up while building the fix. Cleanup had been tied to interrupts. The watchdog produced a typed error instead, so the cleanup did not run. The runner then waited for tool fibers that had not been cleared. The visible timeout existed; the terminal state did not.

The completed slice required a specific observable for this path: the tool fiber terminates and the tool is recorded as interrupted. That is stronger than a feeling that a tool was not stranded. It makes the question checkable after the fact.

That is also why a green test suite deserves a hard question. What did it actually exercise? In the slice record, the unsafe baseline had to hang a real provider stream inside the runner. Testing a timeout helper in isolation would have been decoration. The runner, the failure class, the retry behavior, the tool cleanup, and the terminal session state all had to meet in the same proof.

SLICE-012 closed on 2026-08-07 with all nine criteria met, landing as commit 23d6a5b4ee in anthonykewl20/ranex-harness. This is harness work, not a claim that Ranex is ready for use. Ranex is pre-release; much of the broader system is designed, not built. The watchdog is one shipped durability claim in the harness fork.

If you want the surrounding model for why the verdict must sit outside an agent’s own loop, read how the kernel works. The slice record itself is in the Ranex repository under docs/slices/done/.

Questions people actually ask

These answers explain timeout failures, terminal states, and the waits each budget covers.

Why can a watchdog timeout still leave a session hanging?

A retryable timeout restarts the same stall when the condition that timed out will recur after retry. The watchdog can fire while the turn still never reaches a terminal state.

Why use both idle and absolute timeouts?

An idle deadline detects a quiet mid-stream provider, while an absolute budget bounds the whole turn even when chunks keep arriving.

Does an idle timeout cover time to first token?

No. The first pull is deliberately untimed because inter-chunk gaps and reasoning-model time to first token have very different latency distributions. A connection that never sends is bounded by the absolute budget.

What happened to tool work when the watchdog failed?

The watchdog produced an error rather than an interrupt, so streaming tool fibers were not cleared and settlement could keep the turn open. The slice added coverage for that path.

Your next failure drill

Take one timeout in your pipeline this week. Do not start by making the timer shorter. Stall the real operation after it begins. Then follow the failure all the way through: retry decision, cleanup, settlement, and the state your operator sees.

Write the failure class down. Split thresholds that are serving different distributions. Name what remains unbounded.

Try it. Break it. Tell me what broke. If this record helps you find a test that passes while its failure loops forever, give the repository a GitHub star and send an honest critique. The critique is more useful than applause.

Ranex vs. GitHub Rulesets and Copilot Hooks: What’s Actually Different

Anthony Garces — Wed, 23 Sep 2026 09:05:05 +0000

TL;DR: Rulesets, editor hooks, and CI gates can control where work moves. Ranex asks what the evidence for that work must establish. Those boundaries can sit together. The accountability apparatus needs both a route and a record.

You already have rules around a push, a merge, or an editor session. Good. The question is not whether you should throw them away. The question is whether a green result carries the information you need about the artifact that reached that channel.

In this note

What channel controls are for
What an evidence control asks instead
How to use the boundaries together
Why pre-release status changes the choice

Channel controls decide where work can move

GitHub rulesets sit around repository actions such as push and merge. Editor hooks sit in an editor workflow. CI pipeline gates sit in the pipeline. Each can enforce the policy you configure at its own boundary.

That is worth having. A branch should not advance when required conditions for that branch are absent. An editor action can be stopped before it runs. A pipeline can stop before it publishes its next result. Those controls make authority visible at the channel where the action happens.

Keep the comparison boring because it is boring. These are different places to put a boundary. Your existing controls may be the right answer for your repository, your team, and the action you need to constrain.

But a channel rule does not answer every evidence question by itself. A pipeline can report a result. A merge policy can require that result. An editor hook can permit or refuse an action. You still need to ask what command ran, what claim it was meant to support, and what exact artifact it observed.

That is not a complaint about those controls. It is the normal limit of a boundary. A lock on a door decides who can enter; it does not describe what happened in the room. Your workflow needs the channel decision and a record that can answer the evidence question later.

Evidence controls decide what a claim must show

Ranex puts its boundary around the claim. Its kernel evaluates gate, evidence, subject, and approver as a pure function. The evidence is bound to a subject digest. A required claim without satisfying evidence is FAIL rather than a default or a skip.

This is a narrower question than “can this merge happen?” It is: can this record support this claim about this code? The README’s “Status” section says the same command run against a different commit proves nothing about this one. That is the evidence boundary in plain language.

Suppose a test job produces green output. The channel control can decide whether that output is required before merge. The evidence question remains open until you can state what the job ran, what it measured, and whether its record is bound to the code under judgment. A result with no stated proposition is hard to audit later.

The evidence boundary also separates production from approval. Ranex lists no self-approval as working behavior: whoever produced the evidence cannot approve it. That does not make a channel control less useful. It supplies a different question for a workflow where an agent can produce both the change and the report about the change.

Use the boundaries together

You can adopt the evidence question without adopting Ranex. Start with the controls you already use, then make each required result answerable.

Which channel is being controlled: push, merge, editor action, or pipeline stage?
What exact claim does the required check support?
What command is authorized to support that claim?
Which code digest did the command observe?
Who produced the evidence, and who is allowed to approve it?
What happens when the evidence is missing or belongs to older code?

That checklist does not ask you to abandon a familiar stack. It asks you to make the green light legible. Your ruleset can still protect the merge channel. Your hook can still protect the editor channel. Your pipeline can still coordinate work. The evidence record needs to carry its own meaning.

There is no trophy for replacing working controls. Composition is the point. Let a channel control stop an unauthorized transition. Let an evidence control refuse a claim that lacks the right proof. The first answers where an action may go; the second answers what the action established.

The status is not a replacement claim

Ranex is pre-release. The README says it is a kernel with a working verdict path and very little else. Subject-bound evidence, absence blocks, no self-approval, the journal, and the run-to-evaluate path are listed as working today. The full flow graph and scenario compilation are designed, not built.

Its limits are part of the comparison. Approver identity is unauthenticated: --approver is a plain string. Same-UID key theft remains open. The journal does not detect rollback or truncation. Those gaps mean you should read the status before treating any design goal as present capability.

So do not read this as a replacement pitch. Use the channel controls you trust. Ask the evidence question wherever agent-generated work raises the stakes. If Ranex earns a place later, it earns it by making that question executable, not by declaring your current setup inadequate.

Questions people actually ask

How does Ranex differ from GitHub rulesets?

GitHub rulesets govern repository channels such as push and merge, while Ranex evaluates evidence for a claim against a subject digest.

Can Ranex work with editor hooks and CI gates?

Ranex can sit beside editor hooks and CI gates because their channel controls and its evidence question address different boundaries.

Is Ranex ready to replace an existing governance stack?

Ranex is pre-release, so its README describes a working verdict path and known gaps rather than a replacement claim.

Try it. Break it. Tell me what broke. Read the MIT-licensed repository, then write down what one required check in your stack actually proves.

The First Real Delegation: An Agent, a Worktree, and a Judge With No Key

Anthony Garces — Mon, 21 Sep 2026 09:13:17 +0000

TL;DR: Run agent-written code without a signing key, measure it in a separate keyless process, and keep approval with another authority. This is the next entry after the Ranex slice log.

You delegated work to an agent, then watched it run code it had just written. Would you let that same process hold the key that signs the result? A real delegation is built around the answer “no.”

In this note

The dangerous moment after the agent edits the tree
The lesson: separate execution, measurement, and judgement
A checklist for your own delegated loop
What this delegation proved — and what it did not
Your next move

The dangerous moment after the agent edits the tree

The risk is not only that an agent writes the wrong code. The risk is that code it wrote gets to reach the authority that declares the work trustworthy.

A headless agent in a worktree feels contained until you follow the process tree. It can edit the repository. It can trigger the suite. The suite is code it may have changed minutes earlier. If the execute process carries a signing key, the boundary exists only in the story you tell about it.

SLICE-008 began with a blunt defect: there was no front door. A person had to connect dispatch, harness, emission file, and judgement by hand. The earlier gear-mesh proof used a model that did no work and hand-wrote its own evidence. That proved parts could turn. It did not prove that the kernel could judge work an agent actually produced.

There was a sharper failure underneath. The existing ranex run path read the signing key before the bound command spawned. The slice records that RISK-06 reproduced that command taking the key from the process environment. If an agent-controlled test hook can reach that key, it can produce a signature while the rest of the system looks tidy.

Do not file that concern away. Design it out of the execution phase.

The lesson: separate execution, measurement, and judgement

The practical split is direct: run the agent without a signing key, measure its committed work in a separate keyless invocation, then attest later. The judge produces a candidate with named missing claims, never a self-issued PASS.

ranex task delegate dispatches a worktree and starts the harness headless. Its environment is built from empty: a pinned PATH, a scratch HOME outside the worktree, bridge variables, one model-credential variable, an auto-approve flag, and a wall-clock bound. When the signing-key variable is present, delegation refuses before it spawns anything.

“Built from empty” means one concrete thing: the execution environment is deliberately assembled instead of inheriting whatever trust happened to be in the parent shell. That is a much better place to start asking what the worker can reach.

When the agent finishes, the kernel parses its emission and matches the worktree and commit against its own dispatch record. A missing emission blocks. A mismatch blocks. An empty delegation where the commit equals the base is refused rather than judged.

Next, the kernel runs the frozen suite against the emitted commit. The commit is materialised, sealed, and offline for that measurement. The invocation holds no key.

Only after that does a separate, later invocation sign the result. Untrusted code is not running at that time.

The worker can make a change. The measurement can describe the change. Neither action grants approval.

The task judge result is a journalled CANDIDATE naming its missing claims. The stamp stays a human’s and out of band. That distinction is the whole design, not a label applied at the end.

For the wider reason a separate check port matters, read the accountability apparatus. An accountability system needs an inspector outside the actor it inspects.

A checklist for your own delegated loop

You can audit this without adopting a kernel. Start with the process that executes agent-produced code, then trace every secret, timeout, artifact, and verdict out to its owner.

Start from an empty environment. Write down the exact variables and paths the worker receives. Treat inherited shell state as unreviewed input.
Refuse execution when a signing key is present. Do this before spawning the agent or its process tree, not after it has begun.
Inspect the live process tree. Do not accept a source-level assertion that a key was removed. Check what the child and parent can actually reach.
Bind a task to its worktree before work begins. Make the judge compare the emitted worktree and commit with a dispatch record it owns.
Measure a frozen suite against the emitted commit. Do not let a worker summary stand in for an independently observed result.
Bound the whole process group. A wall-clock limit must kill the group on a stall, not leave child processes behind.
Use a state short of approval. Candidate is an honest output when claims remain missing. A worker should not award itself PASS.

One dad-joke-sized warning: a timeout that kills only the parent is not a timeout. It is a process group hug with the interesting parts still running.

What this delegation proved — and what it did not

SLICE-008 proved an end-to-end delegated run against a real free model. It ended in a journalled CANDIDATE naming missing claims, with no PASS, and a reviewable diff.

It also tested the shapes that tend to become decoration. The execute phase refuses a signing key before spawn. The live process test checks that the delegated command cannot reach the key through environment, file path, or parent. A planted conftest.py may run and fail the suite, but it produces no signed record. Forged and missing emissions block before materialisation.

The wall-clock bound terminates a stalled run’s whole process group, records the timeout, and journals no candidate. The fork’s operator-facing command presents as ranex, while opencode’s MIT attribution remains in the tree.

Those are useful facts. They are not a claim that all delegation is safe.

RISK-06 stayed open when this slice closed. The model credential sat in a network-open loop, where it could be posted elsewhere. The record said to use a scoped, spend-limited key, and that the existing ranex run path still read the key before spawning. Recorded is not mitigated — until it is: SLICE-046 later closed RISK-06 by binding ranex run’s command inside the qualified confinement session, so the worker can no longer take the signing key. The controller that runs that session is still same-uid trusted infrastructure — see the gap list for what that still leaves open.

The slice also does not close merge collisions, verifiable separation, or gate quality. A weak gate can still accept plausible code. You own the target and the quality of the gate. The kernel cannot make either judgement disappear.

The source record lives in docs/slices/done/SLICE-008-first-delegation.md in the Ranex repository. Read it if you are designing this boundary. The failures are part of the useful material.

Questions people actually ask

These answers cover keyless measurement and the remaining model-credential risk.

Can a delegated agent expose its model API key?

The model credential remains in a network-open loop — use a scoped, spend-limited key. RISK-06, the risk that the worker could take the signing key, was open when SLICE-008 closed; SLICE-046 closed it later by binding ranex run inside the confinement session.

What does an environment built from empty protect against?

The delegated harness receives a deliberate environment rather than inherited trust, and delegation refuses to start when the signing-key variable is present.

Did SLICE-008 solve model credential exposure?

No. The credential still sits in a network-open loop, so use a scoped, spend-limited key. SLICE-008 left RISK-06 open for ranex run; SLICE-046 closed it later by binding the command inside the confinement session.

Your next move

Take one agent job that runs tests or scripts. Identify the secret that can authorise its result. Then inspect the live child and parent processes while the job runs. If that secret is reachable, split execution from measurement before you trust another green status.

Write down what remains open too. “Recorded, not mitigated” is not a failure of the notes. It is how the next person avoids mistaking a boundary for a finished fortress.

Try it. Break it. Tell me what broke. If this was useful, star the Ranex repository and leave an honest critique. A hard question is more valuable than a polite nod.

Absence Blocks: Why No Evidence Is a Fail, Never a Skip

Anthony Garces — Fri, 18 Sep 2026 09:04:21 +0000

TL;DR: A required claim without satisfying evidence must fail, because a skipped check is not proof; a fresh Ranex clone starts red for exactly that reason. Read how the kernel works.

Your dashboard is green, yet a job did not run. Do you know which one? If the answer lives in a log nobody reads, your green result is carrying more confidence than the evidence earned.

Ranex treats absence as a blocker. When a gate requires a claim and no satisfying evidence exists, the verdict is FAIL — not a default, not a skip, not a warning waiting for a tired person to scroll past.

In this note

A silent skip is not a pass
A fresh clone starts red
Make absence visible in your pipeline
Failure names the missing proof

A silent skip is not a pass

A check that did not run has established nothing. Treating that empty space as success turns missing work into a green light.

You know the shapes. A condition bypasses a job. A suite collects no tests and returns cleanly. A scanner stops early and leaves a warning below the fold. The summary says green because the system recorded an exit path, not because it recorded the evidence you needed. That is a failure mode, not an inconvenient edge case.

Ranex makes the missing piece explicit. A gate carries required claims. Evidence must satisfy those claims for the subject under judgment. If the required evidence is absent, evaluation returns FAIL. The rule is an invariant of the kernel, alongside subject-bound evidence and no self-approval — though approver identity is unauthenticated today, so that check compares unverified strings. A gate that cannot block is refused at construction, because a gate that cannot stop anything is decoration.

This is why absence and determinism belong together. A pure-function verdict gives the same answer for the same inputs. Absence blocks answers FAIL when an input cannot satisfy the rule. Without both, “same inputs” can still mean “missing evidence became permission.”

There is a cost. A fail-closed system will make you produce evidence before it lets you call the work done. That can feel fussy when you know the command would have passed. But the entire point is that the system does not accept what you know without a record it can evaluate.

A fresh clone starts red

A fresh Ranex clone fails gate evaluation because it has no evidence yet. That failure is correct: no record exists for the required tests-executed claim.

The README gives the operator path. Run the test suite with frozen dependencies, then ask the gate to evaluate the current subject. On a fresh clone, evaluation returns FAIL with a nonzero exit and names the missing claim. It does not create a cheerful initial state. It does not infer success from an empty evidence file. It tells you that nothing has been proven.

PYTHONPATH=src uv run --frozen python -m ranex.cli.main gate evaluate HEAD \
    --approver reviewer_alice

To produce evidence, the operator needs a signing identity whose private key lives outside the repository. The committed keyring contains public halves, not private keys. After deliberate dependency provisioning, ranex run records the observed command result and subject digest; evaluation then judges that evidence against the gate. The steps matter because the verdict is not an applause button for a command. It is a judgment about whether the bound evidence satisfies the required claim for this subject.

Fresh-clone failure is a fast test of your own mental model. If a system can announce PASS before any relevant evidence exists, what did PASS mean? It meant the system had another rule, even if nobody wrote it down. Ranex writes its rule down in behavior: no satisfying evidence, no pass.

Make absence visible in your pipeline

You do not need to adopt a kernel to look for this fault line. Pick a recent green deployment and inspect the evidence path rather than the badge.

List every claim the release depends on, not only every job name.
For each claim, identify the record that satisfies it and the exact subject it covers.
Make a missing result fail rather than disappear into a default branch.
Make skipped, errored, and missing test outcomes visible as distinct states.
Change the tree and confirm earlier evidence no longer satisfies the new subject.
Ask whether an operator can tell the difference between unfinished work and a rejected record.

That last distinction matters. A record that fails verification is not reported as “no evidence.” Ranex reports it as refused and includes a reason. Missing evidence means no satisfying record exists. Refused evidence means a record arrived but did not clear verification. An unfinished task and an attack are different events; hiding them under the same empty label destroys useful information.

Staleness is absence in another form. Evidence is bound to a subject digest, so the same command on a different commit proves nothing about the current one. Once the tree moves past the digest that evidence covered, it stops satisfying the claim. That is not the system being difficult. It is the system refusing to let yesterday’s proof stand in for today’s code.

Failure names the missing proof

A useful FAIL tells you which required proof is missing or refused. It does not pretend that all failures are identical, and it does not claim a guarantee it lacks.

The repository’s Status section lists absence blocks as working today and says the project is pre-release. The full flow-graph and scenario-compilation picture is designed rather than built. Keep that boundary in view. The working claim here is smaller: the verdict path fails when a required claim has no satisfying evidence.

That small claim changes the conversation during a release. Instead of “the pipeline was green,” you can ask “which evidence satisfied this claim for this commit?” If there is no answer, you do not need a debate about whether the omission feels safe. The gate already has the right response.

Go to the last build you trusted because it was quiet. Find one claim it was supposed to establish. Then remove its evidence in a disposable copy of the process. If the release still looks green, you found the work to do.

Questions people actually ask

What does absence blocks mean in CI?

Ranex treats a required claim without satisfying evidence as FAIL, never as a default or a skip.

Why does a fresh Ranex clone fail evaluation?

A fresh Ranex clone has no evidence for the required tests-executed claim, so gate evaluation correctly returns FAIL with a nonzero exit.

Is refused evidence the same as missing evidence?

Ranex reports a record that fails verification as refused with a reason, while missing evidence means no satisfying record exists.

Try it. Break it. Tell me what broke. Read the Ranex repository, then make one required check absent in a safe copy of your own pipeline.

I Forked My Agent Harness So It Couldn’t Grade Its Own Homework

Anthony Garces — Wed, 16 Sep 2026 09:02:16 +0000

TL;DR: An agent harness cannot independently approve work when it controls both the artifact and the success path; move “done” outside the loop. This is one record from the Ranex slice log.

Your agent finished the task. The harness says it is done. Who, exactly, was allowed to make that call? That question is the next layer under every green check you got this week: the moment the harness had to stop grading its own homework.

In this note

The problem hiding inside a successful run
The lesson: move “done” outside the loop
A checklist for finding self-grading in your pipeline
What was actually proven in this slice
Your next move

The problem hiding inside a successful run

A check bolted around an agent is not independent if the agent’s harness can still author the route to success. You need a different actor, with its own record, to decide what the emitted work means.

You know the shape. A task starts. An agent edits files. A wrapper collects a summary, a commit, a test result, or all three. Then that same wrapper turns around and announces success.

That is not a tiny trust gap — it is the whole gap.

The agent does not need bad intent for this to fail. The harness can be wrong, incomplete, configured too broadly, or simply allowed to load something you did not expect. If its output is both the evidence and the verdict, there is no independent place to ask the rude question: Did this task produce what the dispatch actually asked for?

Ranex is pre-release. It is a kernel with a working verdict path and very little else. But this boundary is built because a useful system needs to make that rude question executable, not ceremonial.

I did not get to skip this by calling the surrounding code a harness. Names do not create separation. Authority does.

The lesson: move “done” outside the loop

The fix is structural: let the harness produce work and references, then let the kernel cross-check them against a record it owns. The harness can emit evidence; it cannot emit a gate, a merge, a stamp, or an approver.

For SLICE-007, Ranex forked opencode at v1.18.11, commit 012c2f57. The fork was trimmed to a defined keep-set. Its plugin surface was locked to compiled-in built-ins. It refuses to start when the required bridge is missing or unbound.

Those details sound operational. They are the point.

A harness that can take configuration or npm plugin paths can change what is running around the work. A harness that starts without its bridge can run unobserved. You do not repair either condition by asking the agent to be more careful.

Here is the deal: the actor that performs the work should not own the meaning of its own evidence.

The kernel gained task dispatch and task judge. At dispatch, it records the task-to-worktree relationship in an append-only, hash-chained journal. The harness works in that worktree, commits, and emits references. Then the kernel reads the committed worktree itself, compares the emitted references with its own dispatch record, materialises the commit, and evaluates the evidence.

The resulting journal entry is CANDIDATE. Never PASS.

A candidate is work ready to be judged. It is not permission granted by the worker that made it.

The approval stamp stays human and out of band. That can feel slower than letting an agent complete the sentence with its own praise. Good. A gate exists to make an important transition harder to fake.

If you want the broader shape of the boundary, the kernel topology explains why workers return a diff while the check port produces the only verdict that counts.

A checklist for finding self-grading in your pipeline

You can find the dangerous shapes without adopting Ranex. Follow a task from dispatch to the word “done,” and mark every place one process supplies both the artifact and its interpretation.

One wrapper owns task creation and completion. Hunt for a task identifier created by the same process that later marks it complete.
The worker reports the commit it wants judged. Check whether an independent process reads the worktree or commit itself and compares it with a dispatch record.
Plugins can arrive through configuration or a package path. List what can load into your harness at runtime. If the list is open, treat that as authority entering through a side door.
The harness can run without its observer. Remove or unbind the bridge in a disposable environment. Does startup refuse, or does work continue without the boundary?
A summary becomes a verdict. Separate “the worker says tests ran” from an independently measured result against the committed subject.
The word PASS appears before a person or separate authority acts. Replace it with a state that says what it is: candidate, pending, refused, or failed.

Do not settle for a diagram where these responsibilities have different labels. Ask which process can write each record and which process reads the artifact from disk. The answers matter more than the labels.

What was actually proven in this slice

SLICE-007 proved the path end to end: dispatch, worker loop, hooks, kernel judgement, evidence, and a journalled CANDIDATE. The gear-mesh end-to-end test ran that loop using a deterministic in-fork model with zero credentials.

That proof is narrow on purpose. It does not claim delegation, clean-room orchestration, confinement, authenticated approval, or a finished product. The slice record says those boundaries remain outside its closure.

It also does not turn an emitted candidate into a universal claim of correctness. Ranex judges work by evidence and executable checks, and it cannot decide whether the target itself was the right target. The owner still owns that judgement.

The close is recorded in docs/adr/ADR-008-fork-opencode-and-bridge-to-the-kernel.md. The slice record is in docs/slices/done/ in the Ranex repository. The fork retained opencode’s MIT attribution. That is one small line with a large habit behind it: say what you used, say what you changed, and do not borrow credit with the code.

Attribution compounds. Especially in a system built to distinguish a claim from its proof.

Questions people actually ask

These answers explain how a harness can be kept from approving its own work.

Why is an agent harness grading itself a problem?

When the same actor can produce work, shape the success path, and declare completion, the check does not independently establish the claim.

How can an AI agent harness be stopped from approving its own work?

The harness can be stopped by letting it produce work and references while a separate kernel cross-checks them against a record it owns.

Does the kernel issue PASS for harness work?

No. The kernel cross-checks the dispatch record, materialises the committed work, and journals CANDIDATE. A human stamp remains out of band.

Your next move

Pick one agent task from this week. Trace its task ID, its worktree or branch, its commit, its evidence, and its final status. Then ask whether the actor that changed the files also had a path to write the final status.

If the answer is yes, do not call the task done yet. Make a separate authority read the committed artifact and compare it with a record it created before the work began.

Try it. Break it. Tell me what broke. If this helps, star the Ranex repository — then leave an honest critique. The critique is more useful than applause.

A Report Is Not the Artifact

Anthony Garces — Mon, 14 Sep 2026 09:35:49 +0000

TL;DR: A report tells you what a session says happened. The artifact on disk and a fresh rerun tell you what you can check. The parent slice log is where the distinction was recorded.

Your agent says the gate passed. Before you approve it, can you point to the artifact and rerun the command without the agent in the room? If not, you have a description of evidence, not evidence you can independently inspect.

In this note

A report is self-description
The artifact is where the claim meets reality
Approval does not create an observation
Make your pipeline answerable
Rerun before you rely on it

A report is self-description

A session report is useful for navigation. It is not the same thing as the files, command, and output it describes.

That sounds obvious until the report is green and the review queue is long. A worker says it changed a fixture, ran a suite, and saw a pass. A reviewer reads that sentence and gives it a second approval. The words become more official, but nobody has created another observation of the work.

Ranex is built around a smaller rule: read the diff on disk; discard the worker summary; run the checks. The rule is not distrust for its own sake. It gives a later reviewer something that exists outside the session which made the claim. A summary can be wrong, stale, incomplete, or written before the final artifact existed. The artifact gives you a place to ask again.

SLICE-011 says the supervisor reran every gate against the worktree on disk and calls the session summary discarded self-report. That wording is worth borrowing for your own pipeline. A report is a claim about a run. It does not get promoted to evidence just because it is formatted cleanly.

The artifact is where the claim meets reality

The artifact lets you test the claim again, using the command that is supposed to support it.

That is the transferable rule. Check out the exact worktree or commit. Read the actual diff. Run the declared command. Preserve its output where another person can retrieve it. When the behavior has a failure mode, force that path too. Each step turns a statement into something a later person can challenge.

A report can still be retained. It can name the command, commit, environment, artifact digest, and outcome so you know what to reproduce. Its proper job is a map, not a substitute for the terrain.

This matters most for concurrency, timing, process cleanup, or shared state. Those failures can disappear in a clean session and return when the same artifact is run again. It also matters for ordinary build work: a report that describes a test without preserving the exact subject has asked you to trust memory at the moment you need measurement.

Approval does not create an observation

Two people approving one report have read one observation twice. They have not independently verified the artifact.

That is not a criticism of review. Review can catch a bad instruction, a mistaken assumption, or a missing case. But no amount of careful reading can make an unrerun report answer a command it never ran.

The incident narrative belongs in How a 12% Flaky Test Suite Got Approved Twice: the suite was reported stable, approved by two reviewers, and then a rerun against disk found two failures in sixteen full-suite runs. This note keeps the principle: approvals are readers; the artifact is the thing that can be observed again.

Use that distinction when someone proposes “another sign-off” as the fix for uncertain evidence. Ask what new observation the sign-off adds. If the answer is none, schedule a rerun or a fresh measurement instead.

Make your pipeline answerable

You do not need a governance kernel to make reports earn their authority. Give every important result a route back to its artifact.

Record the immutable subject: a commit, build digest, or other exact artifact identity.
Record the exact command and the inputs it used, not a paraphrase such as “tests passed.”
Make the artifact available to the person who approves the result.
Rerun blocking checks outside the producing session before using them to merge, deploy, or certify a control.
Force a relevant refusal or negative path and confirm the check can distinguish it from success.
Keep stderr and other diagnostics that explain a failure instead of retaining only a green summary.

These are not ceremonies to add after the real work. They are how you discover whether the work was real before your pipeline gives it teeth.

Questions people actually ask

These questions keep a report in its proper role: a map back to a checkable artifact.

Why is a session report not evidence by itself?

A session report is self-description from the run that produced it. Ranex treats the worktree and a rerun of the recorded command as evidence that can contradict that description.

What should a reviewer verify instead of trusting a report?

A reviewer should inspect the artifact on disk, rerun the exact gate command, force the relevant failure path, and preserve the result outside the producing session.

Can two approvals make one report independently verified?

No. Ranex learned that two reviewers can approve the same self-description; approval adds readers, not a new observation of the artifact.

What did SLICE-011 prove about reports and artifacts?

SLICE-011 proved that rerunning every gate against the worktree on disk found two failures in sixteen full-suite runs after the suite had been reported stable and approved.

Rerun before you rely on it

Pick one report that can block a release or approve an agent change. Locate the artifact it claims to describe. Rerun its exact command against that artifact. Then make the command fail on purpose and verify that the report would not hide it.

Ranex is pre-release. The lesson does not depend on waiting for it: a report is a useful map, and the artifact is still the ground.

Try it. Break it. Tell me what broke.

Nine Defects, Zero Unit Tests: Drive Your Tool Like a Stranger

Anthony Garces — Fri, 11 Sep 2026 09:06:14 +0000

TL;DR: Unit tests missed nine CLI journey defects; run the tool from zero state, using only its published instructions. The parent slice log is a reminder to test the artifact people actually touch.

Your command works on your machine, your unit tests are green, and a new operator still cannot get through the first run. Can Ranex gate Ranex for real?

In this note

The CLI is where your system becomes real
Nine defects appeared only in the journey
Drive these shapes like a new operator
Approval reduces hidden change. It cannot make code truthful.
Run your own first-day test

Your tool lives at its CLI surface. That is where paths, locks, machines, empty state, instructions, and human assumptions collide.

SLICE-006 found nine defects by driving the Ranex CLI as a person does. None came from a unit test. That is not an argument against unit tests. It is an argument against asking them to prove a journey they never take.

The CLI is where your system becomes real

Your tool’s real failure modes live where a person invokes it. A unit test can prove a component; it cannot automatically prove that setup, documentation, state, and the command path join into a usable and truthful run.

Ranex had a specific problem. It materialises committed blobs to observe the subject tree. That is the right subject, but ignored directories such as .venv and node_modules are not in that tree. The bound test command needed dependencies and a resolver that the observed party could not choose from an ambient writable path.

So the question became practical: can Ranex gate Ranex for real?

The answer built in SLICE-006 has four deliberate steps. deps fetch derives the lock clean under pinned inputs and byte-compares it with the committed lock. Only SHA-256-addressed wheels enter the store. deps approve records the named package delta an approver accepted. Before anything runs, a fresh environment is assembled from the verified store entries and made read-only. Then run executes sealed and offline.

The gate command remains the catalog-bound uv run pytest -q. The environment is assembled from verified store entries, made read-only before spawn, and set so the command cannot sync, build, or fetch.

That is a dependency process, not a truth machine. A hash tells you which bytes arrived. Approval tells you which package change a person accepted. Neither tells you that dependency code will behave honestly once it runs.

Nine defects appeared only in the journey

Nine defects were found by driving the CLI as a person does, and none by a unit test. They appeared at the joins: real locks, cold-start state, operator instructions, CI, and the fresh repository used for observation.

The first defect is a familiar one. Plain uv run pytest -q re-locked and rewrote uv.lock. In this system, that lock is a trust root. After a clean re-lock, the rewrite silently dropped the resolution epoch block. Then deps fetch refused the committed lock against its own clean derivation.

The fix had two parts. The gated run sets UV_FROZEN=1, while the repository’s own commands use uv run --frozen. The difference is not cosmetic. The gated argv must stay exactly as the catalog binds it.

Other journey failures had the same practical flavor. A real lock held one package at several versions, and the parser rejected it as corruption. A check for a fabricated hash was passing for the wrong reason because the resolution epoch was omitted. CI was also invoking uv unfrozen, silently mutating the same trust root where it would be hardest to notice.

Then the cold-start journey caught product-facing defects. keygen told a first-time operator to create an invalid keyring. The README walkthrough had rotted: it omitted the fetch and approval steps, failed to name installation of the pinned resolver, and described a requirement that had been removed. Another journey re-entered itself inside the materialised sample because its recursion guard lived in an environment that the sample deliberately built from empty.

None of those defects is a tiny detail to the person blocked by it. The tool either works from zero state or it does not.

Drive these shapes like a new operator

Test the command surface as a stranger with no warm cache, no hidden setup, and no memory of why the tool works. The checklist is not “add more end-to-end tests.” It is a list of states your unit suite is built to avoid.

Start from zero state: no generated keyring, no provisioned store, no prior approval, no warm cache.
Follow the README command by command. Confirm every command it requires is present, ordered, and still names current behavior.
Run with the real committed lock and manifest, then deliberately alter a package, graph edge, URL, or hash and require byte comparison to refuse.
Use the pinned resolver path and prove a user-writable resolver is rejected.
Observe the dependency run offline. A network attempt must deny and produce no evidence.
Exercise the tool in CI, where a separate command spelling can rewrite a trust root without a developer noticing.
Run inside every clean-room or materialised repository shape the tool creates for itself.
Force an ordinary success path too. A refusal-only test can pass because the command never ran.

The last item is non-negotiable. SLICE-006 records an actual dependency-bearing execution that provisions once, reuses the store without downloads, runs offline, signs evidence, and evaluates PASS. A system that only proves its refusals is an outage wearing responsible clothes.

You do not need a large product to borrow this method. Take one onboarding command. Use a fresh environment. Follow your own docs without filling gaps from memory. Every place you have to “just know” something is a candidate defect.

Approval reduces hidden change. It cannot make code truthful.

An approved, hash-correct wheel can still choose its own exit code. SLICE-006 demonstrates this with tests/security/test_slice006_approved_wheel_can_lie.py, where an approved wheel forces a passing verdict.

That test is labelled not caught. It should be. Calling integrity proof would be a lie.

Python makes the route concrete through installed pytest11 entry points, but the boundary is larger than one plugin mechanism. Direct imports also execute dependency code. The dependency is part of the trusted computing base for that run.

This is why an accountability apparatus needs its limits stated plainly. You can reduce hidden change with a clean derivation, pinned inputs, SHA-256-addressed wheels, a reviewable package delta, and sealed offline execution. You cannot derive truthful behavior from a package hash.

Ranex is pre-release. This slice closes a runnable self-gate for its Python dependency path. Other ecosystems need their own manifest, lock, and artifact policies. No generic abstraction is claimed here.

Also, the lock story is worth keeping in your operating memory. A lockfile is not boring generated clutter when it decides what code enters a measured run. Plain uv run rewrote uv.lock and silently dropped the resolution epoch once. The later refusal was the control doing its job, not the control being inconvenient.

Questions people actually ask

These answers cover CLI testing from zero state and the limits of unit tests.

What does Ranex gates Ranex mean?

Ranex provisions and runs its own committed suite sealed and offline, then evaluates the signed evidence against the gate.

What does end-to-end CLI testing catch that unit tests miss?

End-to-end CLI testing catches defects in real operator journeys across command setup, lock handling, documentation, cold-start state, and the materialised repository boundary.

Can an approved hash-correct dependency force a passing verdict?

Yes. The SLICE-006 security test demonstrates an approved, hash-correct wheel forcing a passing verdict. Approval reduces hidden change; it cannot make third-party code truthful.

Run your own first-day test

Pick the most consequential command your users run. Clear the state it is meant to create. Open the docs. Execute only what they say. Watch every file it reads, every tool it resolves, every network call it attempts, and every trust root it can rewrite.

Then preserve the journey. Put the defect reproduction beside the code, not only in a ticket. The source records for this work are in the Ranex repository, under docs/slices/done/.

Try it. Break it. Tell me what broke. If the journey catches something your unit suite missed, star the repository and send an honest critique. That is the result worth keeping.

Uptime Kuma: Why HTTP 200 Can Hide a Broken App

Anthony Garces — Thu, 10 Sep 2026 10:14:02 +0000

Uptime Kuma can show UP while your endpoint reports a failed dependency. If the endpoint still answers HTTP 200, add a check for the specific response field that matters. A broad keyword such as ok can miss the failure too.

The example below uses four small test responses and records what 12 real Uptime Kuma monitors reported. Use it before trusting the green badge on a self-hosted app or a service you just shipped.

Source checks and local experiment: September 9, 2026. Tested with Uptime Kuma 2.5.3. The responses are synthetic; no production database was disconnected.

The quick fix: For the example response below, select HTTP(s) – JSON Query, set the query to checks.database, the condition to ==, and the expected value to ok. Then deliberately return down and confirm the monitor changes state. Test delivery to your notification channel separately.

See the recorded results · Configure the monitor · Run the lab · Check the alert path · FAQ

HTTP 200 and a broken dependency can coexist

An accepted HTTP status tells you that the response passed your status-code rule. It does not establish that the database, queue, or feature behind that endpoint works.

Here is the deliberately broken response used in the lab. It arrives with HTTP 200:

{
  "status": "ok",
  "checks": {
    "database": "down"
  }
}

A status-only check accepts it. A keyword check for ok also accepts it because that text still appears in the top-level field. The database-specific query rejects it.

These are the observed states from Uptime Kuma 2.5.3. Every fixture in this table returns HTTP 200. Each monitor used zero retries and accepted only status 200.

Response fixture	HTTP status check	Keyword: ok	JSON: checks.database == ok
Healthy database field	UP	UP	UP
Database field says down	UP	UP	DOWN
Database field is missing	UP	UP	DOWN
HTML sign-in page	UP	DOWN	DOWN

Download the lab and recorded JSON results to inspect the exact response bodies, timestamps, configuration, and monitor messages. The HTML fixture directly returns a sign-in page; this experiment does not simulate a redirect or an expired session.

Each monitor followed its configured rule. The broad rules simply allowed this broken response to pass.

Why use Uptime Kuma for this check?

Uptime Kuma is a self-hosted monitoring app whose documented monitor types include HTTP, keyword matching, and JSON queries. The pinned release uses the MIT license. You can inspect both the project README and license on GitHub.

You can point all three monitor types at the same endpoint and compare the results. Start with your existing instance or a disposable local installation. This guide focuses on choosing the check; use the official installation guide for deployment instructions.

If you are still deciding whether to operate another service, use our six checks before adopting a repository. Hosting the monitor also means owning its availability and maintenance.

Conceptual illustration created with AI: a responding server, a useful response, and a delivered alert are separate things to verify. This is not an Uptime Kuma screenshot.

Configure a JSON query for the field you need

For this test response, check whether checks.database equals ok. Set it through the JSON query monitor rather than searching the whole response for the word ok.

Start the fixture from the download with python3 fixture.py. On the Linux host-network setup described in its README, create this monitor:

Setting	Lab value
Monitor type	HTTP(s) – JSON Query
URL	`http://127.0.0.1:8765/healthy`
Method / accepted status	GET / 200
JSON query	`checks.database`
Condition	`==`
Expected value	`ok` (no quotation marks)
Interval / retry interval	20 seconds / 20 seconds
Retries / timeout / maximum redirects	0 / 5 seconds / 0

The versioned editor source shows the query, condition, and expected-value inputs. Labels can change across versions. These are demonstration settings, not universal production defaults.

Save the monitor and wait for a heartbeat against /healthy. It should report UP.
Change only the URL path to /broken. Wait for a new heartbeat. The recorded result is DOWN.
Repeat with /missing, then /login. Both were DOWN in the recorded run.
Restore /healthy and confirm recovery in your instance. Record the observation in the included worksheet.

If Kuma runs in an ordinary Docker bridge network, its 127.0.0.1 is the container itself. Follow the download’s Linux host-network example or choose an address reachable from your Kuma deployment. A connection failure caused by the wrong address is a different test.

When keyword monitoring helps, and when it misses

A keyword check helps when the response has a distinctive success marker. It is too broad when the same marker also appears in an error response.

In the pinned implementation, keyword matching checks whether the response contains the configured text. The invert option reverses that condition. A JSON query evaluates the selected expression and comparison instead. See the monitor implementation.

For an HTML page, choose text tied to the expected result and test an error page that keeps the usual navigation and footer. For a structured API response, select the field whose value changes when the dependency fails. Avoid treating a generic page title or the word ok anywhere in the body as proof of the whole app.

The field still needs to mean something. A hard-coded "database": "ok" is just another green badge. In your own service, define what the endpoint must actually observe before it returns that value, and make that observation fail in a controlled test.

Run the same failure lab yourself

The download contains the fixture server, a dependency-free Python check, a script that creates the real Kuma monitors, both recorded result files, and an acceptance worksheet.

Download the Uptime Kuma HTTP 200 lab ZIP. Extract it and open the uptime-kuma-lab directory in a terminal:

python3 check-fixture.py

That command exercises the HTTP responses with independent Python checks. To reproduce the actual Uptime Kuma results, follow the README’s disposable Docker setup and run run-kuma.cjs inside that container. The download distinguishes the two runs explicitly.

The Kuma run used release 2.5.3, Node 22.22.3, SQLite storage, Linux host networking, and the pinned Docker image digest recorded in the README. It created 12 monitors and checked their first observed heartbeat states. It did not measure detection latency, exercise a real database, or send external notifications.

Use the worksheet to record recovery and alert delivery in your deployment. Those cells are blank because this experiment did not test them.

Verify the alert reaches someone

A DOWN state is only one step in the operational test. Attach your intended notification channel to the monitor and check that a controlled failure reaches the person who must respond.

Use a disposable endpoint or a planned test window. Record the healthy response and the expected failure before changing anything.
Trigger the failure. Confirm that the monitor reaches DOWN after your configured retries, then confirm receipt in the attached channel.
Restore the response. Confirm the monitor recovers and inspect the recovery notification if your channel is configured to send it.
Record who received the alert and when. Separately decide how you will notice if the monitor’s own host becomes unavailable.

For production, choose intervals, retries, and timeouts around the service’s response time and the interruption your team can tolerate. This lab’s zero-retry setting makes the example easy to inspect; it is not a paging policy.

Checking one response field does not prove that a user can sign in, save a document, or complete a purchase. Where that workflow matters, add a separate test that performs it with safe test data. Define the expected outcome before running the test. The painted bullseye failure mode has the same problem: the success rule is too easy to satisfy.

Questions about Uptime Kuma HTTP and JSON checks

Why does Uptime Kuma show UP when my app is broken?

Your monitor may be checking an HTTP status that the broken response still satisfies. In this lab, every fixture returned 200. Add a condition tied to the response field or user outcome you need, then verify it with a controlled failure.

What JSON query should I use for a database health field?

For this guide’s response shape, use checks.database, condition ==, and expected value ok without quotation marks. Adapt the field and value to your actual response, and test healthy, failed, and missing-field cases.

Does a keyword check for ok prove that an API is healthy?

No. In the recorded lab, the broken response kept a top-level status of ok while its database field said down. The keyword monitor stayed UP. Use a more specific marker or a query for the relevant field.

Did this lab test notifications or a real database outage?

No. It tested 12 real Uptime Kuma monitors against four synthetic HTTP responses. External notification delivery, recovery, real dependency failures, and complete user workflows require separate checks.

Start with one monitor you already rely on. Write down what its green state should prove, then give it a response that violates that promise. Keep the response and the observed result so the next person can repeat the check.

Disclosure: this article and its illustrations were prepared with AI assistance. The local experiment was executed during preparation; the exact scripts and outputs are in the download. Ranex publishes this guide for developers who want verifiable checks. No affiliation with the Uptime Kuma project is claimed.

Your SQLite backup says OK. Two rows are missing.

Anthony Garces — Wed, 09 Sep 2026 10:14:56 +0000

A SQLite backup can pass PRAGMA integrity_check and still be missing records you committed.

The attached lab produces exactly that result. The live database has three rows. A copy of its main file has one row, and SQLite reports ok for both.

If your backup job copies an app.db file while the application is running, check which journal mode it uses. With write-ahead logging, committed changes can still be in the WAL file.

Download the SQLite backup and restore kit (ZIP). It includes a repeatable failure test, a backup utility, and the recorded results. Python 3.11 or newer with its standard sqlite3 module is enough. The lab runs offline with Python’s standard library.

The file was readable. The recent records were absent.

The fixture first wrote one row to the main database. It then enabled WAL mode, disabled automatic checkpointing for the test, and committed two more rows while keeping the connection open. No writes occurred during either copy.

Database checked	Integrity result	Rows found
Live source	`ok`	3
Main-file-only copy	`ok`	1
Restored copy made with the backup utility	`ok`	3

Illustration of the recorded SQLite test. The source kept all three rows; the main-file copy omitted the two committed through WAL. Select the image to view it full size.

The run used Python 3.14.7 and SQLite 3.53.1 on Linux on September 8, 2026. The kit’s result.json includes the actual row IDs and contents, not just the counts.

Nothing in this example required a damaged file. The copy was structurally sound and old. An integrity check cannot tell you that an application record should have been there.

Where the two rows went

SQLite’s WAL documentation explains that writes can be committed to a separate log before a checkpoint moves them into the main database. The main file alone can therefore leave out committed work.

The online backup API reads through SQLite to produce a database snapshot. The included utility calls that API through Python’s Connection.backup method.

That is also why the test keeps the source connection open. Closing the last connection can change the WAL state. A demo that closes everything before copying can accidentally remove the condition it was supposed to test.

Run the failure test first

Extract the kit and read the two Python files. From that directory, run:

python3 run-lab.py

The script creates disposable databases. It makes the incomplete file copy, runs the backup utility, restores that backup to another path, and opens the restored database through a separate connection. It compares the restored rows with the source records.

It also checks that the utility refuses an existing destination, rejects a missing source, rejects an invalid database, and cleans up its temporary files. Your application’s database is not used by this lab.

Make a backup you can inspect

For a database you choose, the separate utility takes a source path and a new destination:

mkdir -p backups
python3 sqlite-backup.py app.db backups/app-snapshot.db

The destination directory must exist. The script refuses to replace an existing file, so use a new name for the next backup.

It opens the source through SQLite in read-only mode, writes to a temporary file, runs an integrity check, and publishes the destination after those steps succeed. The output contains its size and a SHA-256 checksum. That checksum can help you check a later transfer; it does not establish that every application record is present.

The final publication step uses a same-directory hard link. Use a filesystem that supports that operation. If it does not, the script fails without an overwrite fallback. The default backup progress limit is 30 seconds; --timeout 120 allows a longer backup. The later integrity scan is outside that progress limit.

Check something your application cares about

After restoring to a separate location, find a recent record whose ID and content you know. Check a relationship or attachment that the application needs. For the tiny lab, the expected rows are fixed before either copy runs. In your system, decide what must survive before judging the restore.

The utility copies the main SQLite database only. Separately attached databases, uploaded files, configuration, and keys need their own handling. If your application documents a backup procedure, follow it. A generic database copy cannot replace application-specific recovery steps.

This kit does not provide retention, off-site storage, encryption, or a scheduled backup service. The test also does not simulate writers changing the database during backup, disk failure, or a power cut.

Take one backup your current job has already produced. Restore it away from production and check a recent record. If the file opens but the record is missing, your backup check has found work worth doing.

The Gitea upgrade guide has a worksheet for recording recovery checks before a rollout. More runnable resources are collected at Open Source.

Research, code, and editing used AI assistance. This article reports the attached controlled test. The original kit code is available under the MIT license.

FAQ

Can a SQLite backup pass integrity_check and still miss data?

Yes. In this controlled WAL test, a main-file-only copy passed integrity_check but contained one of three committed rows. Structural integrity did not establish that the copy included the recent writes.

What does the included backup utility copy?

It uses the SQLite backup API to copy the main database into a new file. It does not copy attached databases, application uploads, configuration, or encryption keys.

Will the backup script overwrite an existing backup?

No. It refuses an existing destination. The lab checks that a second run fails without changing the first backup.

Does the lab prove my application can recover?

No. It checks a small SQLite fixture. Restore your own backup separately, verify recent application records, and follow the application's supported recovery procedure.

No Self-Approval: The One Rule That Survives Perfect AI

Anthony Garces — Wed, 09 Sep 2026 09:19:01 +0000

TL;DR: If the same actor produces the evidence and approves it, you do not have verification. You have agreement. The accountability apparatus starts outside the worker.

Your agent hands over a diff, a test it wrote, and a green summary. You are tired, the deadline is loud, and every line looks plausible. Who is left to say the proof counts?

In this note

Why production and approval must split
How a test stops becoming a moving target
A separation-of-duties checklist
What the current limit is

The producer cannot approve its own proof

That is the rule. Whoever produced evidence cannot approve it. The README calls it one of the rules that makes a verdict trustworthy, and the reason is not subtle: one actor can write code, write the test around that code, and declare success. The target then follows the dart.

Picture the merge you need to ship. An agent chooses the behavior, changes the implementation, changes the assertion, runs the command, and reports green. Nothing in that chain required a lie. The agent can be sincere. The result can still establish nothing beyond internal consistency.

That is the third failure described in the README’s “The problem” section: the person making the change gets to paint the bullseye afterward. A green check is only useful when the thing it measured was not arranged by the party being measured.

Competence does not dissolve a conflict of interest. A stronger model changes the quality of the work. It does not turn self-approval into independent approval. Give the producer perfect recall, flawless code generation, and a complete map of your repository — the boundary still matters because the roles did not change.

This is why the rule survives the fantasy of perfect AI. The question is not whether a producer is clever enough to check itself. The question is whether your release process asks it to be the witness, the judge, and the beneficiary of the same claim. Would you accept that shape from a person?

Freeze the target before the work starts

Separation cannot begin at the final approval button. It has to reach back to the test. Ranex describes tests frozen before BUILD, generated in COMPILE, digested, and read-only to implementers. A test file changed by the implementation diff fails the gate.

That gives you a sequence worth copying even if you never run Ranex:

State the behavior before the implementation begins.
Turn that behavior into an executable test before the producer can shape it.
Show that the test fails against the pre-implementation tree.
Keep the implementer from authoring or judging that test.
Let a separate approval step decide whether the resulting evidence counts.

The red-then-green step matters. A test that already passes before the behavior exists is not a target. It is an alibi. The no-self-approval rule matters beside it. A producer who can rewrite the test until it passes has moved the target even if the final command is real.

The intended build loop draws the boundary again. A worker returns a diff. The kernel reads the diff on disk and runs checks; the worker summary is discarded. Workers do not merge. The README is explicit that models can propose, criticize, or translate, but cannot pass a gate.

That full governed loop is designed, not built. Ranex is pre-release. What works today includes the narrower kernel rule: evaluation is a pure function of gate, evidence, subject, and approver, and no self-approval is listed as working behavior. Keep that distinction intact. A design is not evidence just because it is a good design.

Check the separation before you trust green

You do not need to replace your stack to ask this question. Take a recent agent-assisted change and trace the roles, not the tools.

Who produced the evidence for the claim?
Who approved that evidence?
Could the implementer author or edit the test that judged the change?
Did the test fail before the implementation existed?
Did someone inspect the artifact on disk rather than accept the worker summary?
Can the producer publish the result without a separate decision?

If one actor owns every answer, your process has a green light but no independent basis for it. That is not an accusation. It is a missing control. You can fix it with role separation, frozen tests, and a reviewer who has authority to refuse the claim.

Do this with agent sessions too. “Different prompt” is not a different approver when the same session can revise the evidence until it likes the result. Name the producer. Name the approver. Preserve the boundary.

The current limit is identity, not the rule

Here is the part you should not skip. Ranex compares producer and approver values, but the approver identity is unauthenticated today. --approver is a plain string. A producer can name someone else as the approver.

Evidence signing establishes that the holder of a registered private key signed an evidence record. It does not establish who approved it. The no-self-approval comparison therefore works on unauthenticated strings. The README lists that as a known gap, plainly.

So do not turn this post into a larger claim than the repository supports. The working rule blocks matching producer and approver values. It does not solve identity. The stamp stays a human’s, out of band, in the intended loop — and authenticating that human remains unfinished work.

That stated limit is useful to you. It tells you where to inspect your own process next: a separation rule without trustworthy identities has a hole at the label. Keep the rule. Do not pretend the label closes the hole.

The separate approver protects a bounded claim, not a promise that everything is right. A gate verdict has its own narrow meaning — and that is why the approval boundary matters.

Questions people actually ask

What is the no-self-approval rule?

Ranex no-self-approval means whoever produced evidence cannot approve it.

Why does no self-approval still matter with better AI?

Separation of duties still separates production from approval when the producer is more capable.

Is approver identity authenticated in Ranex today?

Ranex does not authenticate approver identity today because --approver is a plain string.

Try it. Break it. Tell me what broke. Read the MIT-licensed repository, then trace one change through your own approval path.

uv locked vs frozen: the missing dependency test

Anthony Garces — Tue, 08 Sep 2026 12:58:32 +0000

You add a dependency to pyproject.toml. CI runs uv sync --frozen, exits successfully, and the package is still missing.

There is a small, reproducible reason for that. --frozen uses the lockfile you already have. It skips the check that would tell you the manifest has changed.

If your CI requirement is “the checked-in lockfile must match this project,” use uv sync --locked. In the test below, that command caught the mismatch.

Download the uv lockfile lab (ZIP). It includes the script, recorded output, and an MIT license. You need Python 3.11 or newer, uv, and access to PyPI. You do not need Ranex.

The failure, in five commands

The lab started with a project that had no dependencies and generated its lockfile. It then added idna==3.10 to the manifest without updating that lockfile.

Command	Exit code	What the lab observed
`uv lock`	0	Created the original lockfile before the manifest edit.
`uv sync --locked`	1	Rejected the stale lockfile. Its bytes did not change.
`uv sync --frozen`	0	Accepted the old lockfile. The new dependency was absent.
`uv sync`	0	Updated the lockfile and installed idna 3.10.
`uv lock --check`	0	Accepted the refreshed lockfile.

The run used uv 0.11.26 and Python 3.14.7 on Linux on September 8, 2026. These are the versions tested. The download keeps the exact command arguments, exit codes, and lockfile hashes in result.json.

Run it without touching your repository

Extract the kit, read run-lab.py, and run it from the extracted directory:

python3 run-lab.py

The script makes its own temporary project and cache. It uses your current Python interpreter, downloads idna from PyPI into a temporary virtual environment, and removes the lab files when it exits. It does not inherit your private index settings or UV_* environment overrides.

Look for these two fields in the output:

"idna_present_after_frozen": false,
"idna_version_after_sync": "3.10"

The script checks the installed package separately from uv’s exit status. That is how it catches the successful sync with a missing dependency.

There is one detail worth keeping if you adapt the test: inspect the virtual environment’s Python directly. An ordinary uv run can update the lockfile and environment before running your check, which would change the condition you meant to inspect.

Why both flags exist

The official uv documentation distinguishes checking a lockfile from using one. --locked raises an error when the lockfile needs an update. --frozen skips that freshness check. Neither command promises to do the other’s job.

A frozen install can be intentional when a workflow is meant to consume an already approved lockfile. The trouble starts when you treat its success as evidence that the current manifest and lockfile agree. That was never the check you asked it to run.

Fix the mismatch before changing the CI flag

For a project where the dependency edit is intentional, update the lockfile locally and review the change:

uv lock
git diff -- pyproject.toml uv.lock
uv sync --locked

Commit the manifest and lockfile together. Once CI has checked out that commit and installed your chosen Python and uv versions, make uv sync --locked a step that must succeed before the application tests run.

If you only need to validate the lockfile, uv lock --check is the smaller command. It does not replace running the application tests or checking what ends up in a built container.

Do not replace a failing locked sync with a frozen sync just to clear the failure. First check whether the dependency edit was intended and whether the corresponding lockfile change was committed.

What this test covers

This is one project with one newly declared dependency. It does not test every uv release, workspaces, optional groups, private indexes, or your build image. The timings in the raw output are incidental; this is not a speed comparison.

The useful check to take back to your repository is simple: add a dependency without refreshing the lockfile on a throwaway branch. Does your required CI job reject the mismatch? Check that before assuming a green install tested it.

For a broader dependency decision, use the repository evaluation guide. More practical resources live at Open Source.

Research, code, and editing used AI assistance. Results come from the attached local run. The kit is free to use under its MIT license.

FAQ

What is the difference between uv locked and frozen?

In this lab, --locked rejected the stale lockfile. --frozen used the existing lockfile without checking whether it matched the edited project manifest.

How do I fix a stale uv lockfile?

Review the dependency change, run uv lock, inspect the diff, and commit pyproject.toml and uv.lock together. Then rerun uv sync --locked and your application tests.

Does the lab change my project?

No. It creates a temporary project, virtual environment, and cache, then removes them on exit. It requires Python 3.11 or newer, uv, and network access to PyPI.