Skip to content

Two checks that were claiming more than they could know - #22

Merged
FlagshipDev merged 1 commit into
mainfrom
publish/2026-08-09-f158147
Aug 9, 2026
Merged

Two checks that were claiming more than they could know#22
FlagshipDev merged 1 commit into
mainfrom
publish/2026-08-09-f158147

Conversation

@FlagshipDev

Copy link
Copy Markdown
Contributor

Both found by auditing a live instance and a release that had just gone out, and both are the same
mistake in different clothes: a check whose oracle was a story the tree told itself.

The alarm the architecture guaranteed

hullwork status on a healthy deployment printed, permanently:

! N item(s) are ready to attempt and HULLWORK_FORGE_CODE_TOKEN is not set anywhere the
  dispatcher can see it, so nothing will ever pick them up

Every clause of it was false, and two independent defects produced it.

It asked the wrong process. The flag came from the environment of whichever process ran status,
which in the shipped deployment is the receiver — and DR-0005 requires the receiver not to hold that
credential. So the alarm was produced by the architecture working correctly and could not
distinguish the healthy state from the broken one: a dispatcher genuinely missing the token printed
the identical line. doctor had solved this and reports the same fact as unknown with where to
ask; this sentence asserted a consequence instead.

It also counted a different question from the one the dispatcher answers — two conditions against
eligible's six, so it counted an item belonging to an inactive project and then named a credential
as the reason nobody had picked it up. The fix is not a fifth condition on a second query: there is
no second query now. readiness_notes asks eligible, which is the dispatcher's own question.

With a live dispatcher the note now says the question cannot be answered from here, and where to ask
it. With no dispatcher alive the degradation is kept exactly as it was — that is the true positive,
it is the shape hullwork work itself runs in, and its exit code still has to be 1.

The surface that could agree with the pins about the wrong release

The documentation check compares docs/published-surface.json to the pins in the documents. It
catches both ordinary mistakes, and it compares the two halves to each other: nothing compared
either to the tag that was actually pushed, so the two of them agreeing on the previous release
was green.

That state is reachable by following the release procedure in the order it is written. The recorder,
given no argument, reads the pin — which at that step still names the previous release — so it
rewrites the file it already had. Forget the pins as well and every check passes while the registry
serves something newer.

The tree cannot distinguish that from a correct publication whose post-release steps are not done
yet. Same bytes. What separates them is a fact outside the tree: whether an image exists for the
version this tree claims to be, which is one anonymous request to the registry — public package, no
credential.

So: surface already records this version, fine. No image published for this version, fine, and that
exempts the whole bump-to-release window by a fact rather than by a flag anybody has to clear. Image
published and the surface records something else — fail, naming the published tag.

This makes main red for roughly half an hour after each release, between the image being published
and the post-release commit landing. That is accurate rather than unfortunate, and it is the alarm
whose absence let the silent state exist.

Verified

Both fixes were checked by reintroducing every defect they cover — eleven in all, eleven caught.

The second was also checked against the real registry by putting the tree into the silent state:
surface 0.1.0a7, pins 0.1.0a7, version 0.1.0a8, image 0.1.0a8 published. The existing
documentation check passed all 23 of its tests. The new one failed, naming the published tag and the
commands that fix it.

Signed-off-by: Javier Miralles Rancaño 68760931+FlagshipDev@users.noreply.github.com

Both found by auditing a live instance and a release that had just gone out, and both are the same
mistake in different clothes: a check whose oracle was a story the tree told itself.

## The alarm the architecture guaranteed

`hullwork status` on a healthy deployment printed, permanently:

    ! N item(s) are ready to attempt and HULLWORK_FORGE_CODE_TOKEN is not set anywhere the
      dispatcher can see it, so nothing will ever pick them up

Every clause of it was false, and two independent defects produced it.

It asked the wrong process. The flag came from the environment of whichever process ran `status`,
which in the shipped deployment is the receiver — and DR-0005 requires the receiver not to hold that
credential. So the alarm was produced by the architecture working correctly and could not
distinguish the healthy state from the broken one: a dispatcher genuinely missing the token printed
the identical line. `doctor` had solved this and reports the same fact as `unknown` with where to
ask; this sentence asserted a consequence instead.

It also counted a different question from the one the dispatcher answers — two conditions against
`eligible`'s six, so it counted an item belonging to an inactive project and then named a credential
as the reason nobody had picked it up. The fix is not a fifth condition on a second query: there is
no second query now. `readiness_notes` asks `eligible`, which is the dispatcher's own question.

With a live dispatcher the note now says the question cannot be answered from here, and where to ask
it. With no dispatcher alive the degradation is kept exactly as it was — that is the true positive,
it is the shape `hullwork work` itself runs in, and its exit code still has to be 1.

## The surface that could agree with the pins about the wrong release

The documentation check compares `docs/published-surface.json` to the pins in the documents. It
catches both ordinary mistakes, and it compares the two halves to each other: nothing compared
either to the tag that was actually pushed, so the two of them agreeing on the *previous* release
was green.

That state is reachable by following the release procedure in the order it is written. The recorder,
given no argument, reads the pin — which at that step still names the previous release — so it
rewrites the file it already had. Forget the pins as well and every check passes while the registry
serves something newer.

The tree cannot distinguish that from a correct publication whose post-release steps are not done
yet. Same bytes. What separates them is a fact outside the tree: whether an image exists for the
version this tree claims to be, which is one anonymous request to the registry — public package, no
credential.

So: surface already records this version, fine. No image published for this version, fine, and that
exempts the whole bump-to-release window by a fact rather than by a flag anybody has to clear. Image
published and the surface records something else — fail, naming the published tag.

This makes `main` red for roughly half an hour after each release, between the image being published
and the post-release commit landing. That is accurate rather than unfortunate, and it is the alarm
whose absence let the silent state exist.

## Verified

Both fixes were checked by reintroducing every defect they cover — eleven in all, eleven caught.

The second was also checked against the real registry by putting the tree into the silent state:
surface `0.1.0a7`, pins `0.1.0a7`, version `0.1.0a8`, image `0.1.0a8` published. The existing
documentation check passed all 23 of its tests. The new one failed, naming the published tag and the
commands that fix it.

Signed-off-by: Javier Miralles Rancaño <68760931+FlagshipDev@users.noreply.github.com>
@FlagshipDev
FlagshipDev merged commit 8647148 into main Aug 9, 2026
4 checks passed
@FlagshipDev
FlagshipDev deleted the publish/2026-08-09-f158147 branch August 9, 2026 19:45
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant