Skip to content

bench(lab): read where a repository stands, and answer with it - #299

Merged
luuuc merged 2 commits into
mainfrom
lab/09-02-where-a-repository-stands
Aug 19, 2026
Merged

bench(lab): read where a repository stands, and answer with it#299
luuuc merged 2 commits into
mainfrom
lab/09-02-where-a-repository-stands

Conversation

@luuuc

@luuuc luuuc commented Aug 19, 2026

Copy link
Copy Markdown
Owner

Stacked on #298. Review that one first; this PR's diff is only its own changes.

Problem

A repository's position lives in the operator's head. sense-lab status answers where a campaign stands; nothing answers the question a crank has to answer before it does anything — what is the next phase for this repository, and how many authoring cycles has it already spent.

The old driver answered it with a JSON map of repository to phase, edited by whoever was debugging. That is a decision anyone can change by hand, which made it the one number in the system with no evidence behind it.

Summary

Position is a function of two inputs, and which input a fact comes from is the whole design.

The run tree holds which artifacts exist and the authoring cycle — already a directory name under <campaign>/<repo>/<cycle>/. Derived every time, never stored: a counter beside the fact it counts is a counter that drifts from it.

The attempt records hold the verdict, the table that rejected it and the anchor. Recorded once and never re-derived, because no amount of reading a tree recovers a judgment. One file per attempt, written with O_EXCL — append-only as a convention survives until a bad night, and append-only as an open flag survives the bad night.

Out of the two comes a standing, and the standing is an exit code, because this command belongs in a loop.

Code Means
0 there is a phase to run
2 -show: a position was printed and nothing was done
3 finished: the repository reached the board
4 parked at the authoring ceiling
5 waiting on a human: a PAY nothing will spend on its own
6 refused: the last verdict is not one its phase can emit
7 refused: the verdict is usable and the artifact it owed is not there

Four and five are the two most worth telling apart: one is the method failing on this repository, the other is the method succeeding and waiting on a wallet. Six and seven are diagnosed differently too — an agent that misbehaved, against an agent that died.

-show stops at the announcement, which is the point before an admission writes anything, so it is a preview of what is about to happen rather than a second reading of the same inputs.

Changes

  • lab/internal/position: the attempt record and the reader, with a committed fixture campaign carrying one repository of each shape — mid-cycle with two rejections carried, parked at the ceiling, waiting at a PAY, and one that banked a cycle and re-entered
  • lab/internal/cli/repocmd.go: the standing, the codes, and -show
  • lab/README.md: the code table, and what is derived against what is recorded

sense-lab status is untouched: it stays campaign-wide, and there is no board across repositories here.

Test plan

  • make ci green: coverage floor with no new exception, zero complexity suppressions, lint clean
  • new files hold 96.4% and 98.2% line coverage, every function covered
  • ten mutations that the first draft of the tests let through are now killed, each verified by making the mutation and watching a named test fail: dropping the graph-order sort, checking the phase directory instead of the artifact it owed, treating any banked cycle as a finished repository, keeping only the last rejection instead of all of them, treating a file named like a cycle as a cycle, never assigning the reached phase or the last verdict, letting the count to the ceiling go negative, and dropping the anchor from the record
  • every exit code in the table is asserted, and the loop is asserted to stop on each of the four states that must stop it

luuuc added 2 commits August 19, 2026 09:37
…icts

A repository's position lived in the operator's head. The old driver held it in
a JSON map of repository to phase, edited by whoever was debugging, which made
it the one number in the system with no evidence behind it.

It is now a function of two inputs, and which input a fact comes from is the
whole design. The run tree holds which artifacts exist and the authoring cycle,
which is already a directory name: those are derived every time and never
stored, so there is no counter to drift from the thing it counts. The attempt
records hold the verdict, the table that rejected it and the anchor: a judgment
is not recoverable by reading a tree, so it is recorded once and never
rewritten.

An attempt is one file, written with O_EXCL. Append-only as a convention
survives until a bad night; append-only as an open flag survives the bad night.

Out of the two comes a standing. A park and a PAY are the two most worth telling
apart — one is the method failing on this repository, the other is the method
succeeding and waiting on a wallet — and so are the two refusals: a verdict its
phase cannot emit is an agent that misbehaved, and a usable verdict with no
artifact is an agent that died.

The fixture tree is copied from the jellyfin campaign's layout and carries one
repository of each shape it takes.
`sense-lab repo <id>` now prints where the repository stands and exits with the
code that carries it. The codes are this command's API rather than a display,
because it belongs in a loop:

    while sense-lab repo <id>; do :; done

That loop stops on a park, on a PAY and on either refusal instead of spinning on
any of them, and `-show` never returns 0 so it cannot be dropped into it.

`-show` stops at the announcement, which is the point before an admission writes
anything, so it is a preview of what is about to happen rather than a second
reading of the same inputs.
@luuuc luuuc mentioned this pull request Aug 19, 2026
@luuuc
luuuc deleted the branch main August 19, 2026 15:47
@luuuc luuuc closed this Aug 19, 2026
@luuuc luuuc reopened this Aug 19, 2026
@luuuc
luuuc changed the base branch from lab/09-01-admit-a-repository to main August 19, 2026 15:48
@luuuc

luuuc commented Aug 19, 2026

Copy link
Copy Markdown
Owner Author

reopening so CI runs against main

@luuuc luuuc closed this Aug 19, 2026
@luuuc luuuc reopened this Aug 19, 2026
@luuuc
luuuc merged commit 007e15d into main Aug 19, 2026
8 of 12 checks passed
@luuuc
luuuc deleted the lab/09-02-where-a-repository-stands branch August 19, 2026 16:40
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