vh/booth

Files

T

vh 9272c9872e docs: the conventions a fresh session can't infer, and the state it can't reconstruct

The repo came out of eshpfi one day ago with neither piece of its house
furniture, so everything non-obvious about it lived in docstrings inside a
998-line app.py — which is a bad place to keep an invariant that breaks
silently on every fleet host when someone violates it.

CLAUDE.md carries the five that do exactly that:

  * links.py and asks.py are stdlib-only because scripts/booth imports them
    under the system python3 with no venv, so one third-party import breaks
    `booth ask` everywhere and fails in an agent's session, not in ours
  * the filesystem is the state, and booth_items()'s dotfile skip is why a
    per-booth dotfile is the right shape for new operator state
  * booth_items() is the only thing that classifies a file or resolves a
    caption (U1's INV-1) — the zoom-loses-the-annotation bug was three
    readers of one truth, not a rendering bug
  * moved names stay importable from booth.app, asserted by a test
  * sidecar writes are atomic; render_doc returns raw text on purpose

Plus the distinction that decided this session's storage call: links.md is
an append log because 17 handles write it concurrently, and marks have one
writer. Different problem, different shape — ask which you have first.

persistent-memory.md carries what CLAUDE.md is structurally unable to: the
dated decisions, the `.forever` prediction and its re-measure date, and the
foot-gun log. Two entries are load-bearing for the next unit — the settled
mark storage shape with the reasoning that picked it, and a measured
correction to U7's premise: every booth that actually needs navigation is
flat, so subfolder sections are worth shipping but are not the nav fix.

No version bump — docs and memory, both on the SemVer skip list.

2026-09-21 22:58:00 -07:00

8.5 KiB

Raw Blame History

Persistent memory — booth

Last updated: 2026-09-21

Always check for /tmp/booth-dev-handoff.md — if it exists and its Written: stamp is under 8 hours old, read it (it carries the in-flight handoff from the previous session), then delete it. Older than 8 hours: stale — delete it unread.

Repo purpose

The Booth is the fleet's operator-review surface: agents post work by making a folder under ~/booth-data, the operator looks at it and judges it in the browser, and the judgment gets back to the agent that posted it. It was built as a file-shuttle and is being converged, unit by unit, onto the review loop it turned out to actually be.

Current state / in-flight

As of 2026-09-21:

v1 is gated on seven units in ROADMAP.md, ordered by dependency: U1 → U2 → {U3, U4, U5} → U7, with U6 independent of all of them.
U1 (one item record) has landed at ce598b3 and is verified against its own invariants, not just its commit message: INV-1 holds (no classify / doc_kind / read_blurred / render_doc call survives in a route body), the zoom and doc templates render the caption they now receive, the re-exports are asserted by a test. 192 tests green, 0.1.15.
U2 (marks) is next, and its storage shape is settled (see the 2026-09-21 decision below). Not yet started: no contract written, no blast-radius pass run.
Next concrete step: graphify + grep blast-radius pass over booth.asks's surface and every ask / answer call-site (including scripts/booth), then author docs/contracts/u2_marks.contract.md. Full House Code Discipline — U2 is a new primitive with a CLI surface and 17 consuming handles, nowhere near surgical. The seam review is the load-bearing gate: U2's whole risk is that pick claims to preserve ask semantics and then drifts from them.
Open, operator's call: whether U6 (benches) runs in parallel with U2 or strictly after it. Nothing blocks on the answer; U6 touches different storage and a different surface, so it cannot be broken by U2.
Live service is active on :8090 (systemd --user), 25 booths.

Recent decisions

[2026-09-21] Marks are stored as one .marks.json per booth, atomic temp-file + os.replace, fcntl lock on the read-modify-write — operator decision, this session. Two alternatives were weighed and lost: a sidecar per item (<rel>.marks.json) and extending the existing <stem>.ask.json shape. Rationale, and the reason it is not links.md-shaped: (a) U4 makes "does this booth owe an answer?" a hot question — the sweep asks it per booth per tick and the index asks it per card per page load, so per-item sidecars turn it into a full walk of all 25 booths, one of which holds 270 files; (b) links.md is an O_APPEND content-hash log because 17 agent handles write it concurrently, whereas marks have exactly one writer (the operator, in one browser) and many readers — a different problem that must not inherit the append-log design; (c) .blurred / .pins / .forever already establish the per-booth dotfile as the house shape for operator state, and booth_items()'s dotfile skip means it costs nothing in counts, galleries or zips. Accepted cost: a corrupt .marks.json loses that booth's marks rather than one item's. Implementation deferred to U2 — tracked at ROADMAP.md U2 and by this entry.
[2026-09-21] U7's section premise is half wrong, and it is the half that matters — found by re-measuring ~/booth-data rather than trusting the IA doc. The IA says sections come from subfolders that already exist on disk; true, but every booth that actually needs navigation is flat: pancake-v3-full (270 items, 0 subfolders), pancake-v4-full (270, 0), sindra20-engines (98 items + 99 caption sidecars, 0), sindra-finalists (86 + 87, 0). Subfolders exist on exactly two booths — pewpew-ui-brief (7, nested to _ds/powerpellet-design-system-<uuid>/preview) and dfa-concepts (1) — and both are reports, the job where grid navigation matters least. So sections stay worth shipping and Item.section stays right, but they are not "most of the navigation fix": the rail, the filters and grid keyboard are all of it. Worth noting for whoever writes U7: sindra20-engines encodes its structure in the filename prefix (b2-s1-<subject>-<seed>), which is where a grouping heuristic would actually pay. The IA doc's claim about what sections buy needs a line struck — not yet edited.
[2026-09-21] sindra-finalists is U2's flag motivation caught in the act — 86 items, every one captioned, and the booth's entire name is "the ones the operator picked." That loop currently runs through chat, which is the defect flag closes. Evidence, not argument.
[2026-09-21] The information architecture and the v1 gate landed (726822b): docs/design/information-architecture.md names the single defect — one lifetime (24h from last touch) and one shape (a folder), serving five jobs with different lifetimes and different shapes — and ROADMAP.md gates v1 on seven units, each closing a measured defect rather than a wish. Both were written after a measurement pass over the live service, and the measurements are the load-bearing part.
[2026-09-21] The .forever diagnosis is a stated, falsifiable prediction. U4 (derived lifetime) predicts the kept-rate falls to the genuinely-durable booths. Re-measured today: 14 of 25 booths kept (56%), against the 54% the IA doc recorded. Re-count a fortnight after U4 lands. If it does not move, the diagnosis was wrong and the boolean was doing something else. Tracked in the IA doc's Booth section and by this entry.
[2026-09-21] Extracted from eshpfi into its own repo. The accreted service came over whole, tests included, so tests/test_booth.py (1581 lines) is the regression net the v1 rewrite is checked against.

Tried and abandoned

[2026-09-21] Five separate mechanisms to get one question next to one artifact — .forever, the link board, inline.py's placeholder DSL, wrap_verbatim_html's six regexes, and the floating amber asks chip plus /b/<n>/asks. Every one is a correct local fix to the same global mismatch, which is exactly why they accumulated without anyone making a bad call. The foot-gun is the sixth one: the next "just add a small thing for this case" reads as reasonable and is the pattern. The git log carries the signature — every feature ships, then takes 2–5 patches for cases the single shape did not anticipate. Check the ROADMAP gate before adding a mechanism.
[2026-09-21] Regex-injecting chrome into arbitrary author HTML (wrap_verbatim_html + _HEAD_CLOSE_RE, _HTML_OPEN_RE, _DOCTYPE_RE, _BODY_CLOSE_RE, _HTML_CLOSE_RE, _ICON_RE, and the doctype/charset ordering constraints they thread). It works today and is still live — but it is the single most fragile thing in the service and it is load-bearing for the operator's most important workflow. Slated for deletion at U3 in favour of a declared seam (/_booth/embed.js, mounted through a real DOM API), which costs an author one line and removes the whole class. Do not extend the regex set in the meantime; if a verbatim page breaks, that is an argument for U3, not for a seventh pattern.
[2026-09-21] A boolean escape hatch as the lifetime mechanism. .forever was added because a 24h TTL genuinely did not fit some booths — and then 56% of live booths ended up on it, which means it is not "ephemeral with an exception", it is two lifetimes wearing one lifetime's clothes, with the operator doing the sorting by hand. Replaced at U4 by lifetime derived from state (an open mark pins; viewing is activity; keep survives as an explicit reasoned pin rather than the only way to say "not yet").
[2026-09-21] Letting the link board absorb the announce job. booth link is an O_APPEND write with no identity and no stated rule, so re-announcing a bench appends a row instead of updating one, and a booth URL rots the moment its booth is swept — 145 of 211 rows (69%) pointed at nothing, and 22 were the same target re-posted (talk 5×, peedlar 4×). The rot is structural, not drift. The lesson that cost the most: enforcing the link rule without first giving the announce job a home (.booth.json provenance on the index, U5) just makes it homeless.