booth

163 Commits 1 Branch 9 Tags

53 Commits

Include renames

Author	SHA1	Message	Date
vh	bb1e3cfcd7	fix(booth): templates were hot-reloading into a live service running older Python 19 of 25 live booths returned 500 with `UndefinedError: 'item_marks' is undefined`. Neither the old code nor the new code was broken — the service was running both at once. `booth.service` sets WorkingDirectory to this repo, so the repo IS the deployment root: no build step, no staging copy, the live service imports these files. Python is read once when the process starts. Jinja's FileSystemLoader re-reads a template on EVERY render. So the two halves of the service had different staleness rules, and editing booth.html deployed it instantly against Python from 22:03 that had never heard of the context the new markup wanted. The failure mode is worth naming precisely, because it is invisible to the suite by construction: the skew exists between a running process and the disk underneath it, so every test can pass against a tree that is simultaneously serving 500s. No amount of green catches this. The operator found it. Fixed at the source rather than with a reminder to restart. The template Environment is built here with auto_reload=False, so templates are cached at startup exactly like the Python, and there is ONE rule: nothing takes effect until you restart. The price is that template work needs a restart to see — that price is the entire point, and it is cheaper than a page of 500s while someone is reviewing. Building the Environment by hand means autoescape no longer comes from the Jinja2Templates constructor, so it is explicit and load-bearing: booth names, item names and mark text are all agent- or operator-authored strings that land in HTML. Verified escaped, not merely configured. Two tests hold the line — one on the snapshot property, one on the `dur` filter that is no longer incidental to the constructor. The environment is reachable at app.state.templates because a promise about the deployed service needs an assertion, and an assertion needs the env the app actually renders with. Also records the foot-gun in CLAUDE.md and persistent-memory: anyone editing this repo while the operator may be using the service is editing production. 244 tests. No version bump — the release tier for U2 is still the operator's call, and this rides with it.	2026-09-21 23:44:37 -07:00
vh	c7f9437a64	feat(marks): one primitive for operator judgment, so the loop stops running through chat Five mechanisms existed to get one question next to one artifact. Three of them were the same thing wearing different clothes, and the third of the three had no code at all: the operator picked winners out of a 270-image set and told the session in conversation. `sindra-finalists` is 86 items, every one captioned, with the selection encoded in the booth's NAME. A MARK is operator judgment attached to a target — the booth, or one item in it, addressed by the `rel` U1 established as item identity. Three shapes: pick — one of N options a session declared in advance (was: an ask) note — free text the operator volunteered (had nothing) flag — this one (had nothing) One file per booth, one read path, one place openness is computed, one slot beside the artifact. The storage shape is the operator's call (2026-09-21) and follows from U4: "does this booth still owe an answer?" gets asked per booth per sweep tick and per card per index render, so it has to be one read and not a walk of a booth holding 270 files. Marks are also not links.md — that is an O_APPEND content-hash log because 17 handles write it concurrently, whereas a booth's marks see one session and one operator, so locking the common path costs nothing. The 2026-09-09 pick semantics are preserved by NOT rewriting them: partial answers legal, a blank question lands in `unanswered`, `complete` false until every question has a pick, the only refusal a submission carrying nothing. `write_answer` split into the pure `build_answer` plus the storage that went away with the sidecar; `normalize_ask` untouched. Three findings worth naming, because each was caught by a gate rather than by reading the diff again: * The seam review found `inline.place` indexes asks by SUBSCRIPT — the only consumer in the service that does — so a frozen dataclass breaks it, and `inline.py` had been missing from the contract's scope entirely. * A retargeted test found a regression in the legacy importer: a malformed sidecar that renders "broken" today would have silently vanished on migration. It now imports carrying its reason. * A partially-answered pick counted as CLOSED on the index while the panel beside it rendered it "partial" — the two disagreed about one booth. Open is the reading U4 needs, and it is declared rather than smuggled in. `GET /b/<n>/marks.json` is new and load-bearing: sessions on other hosts polled `<stem>.answer.json` over HTTP, so removing the sidecar without it would have taken that capability away. `/b/<n>/asks` 308s to `/marks`. Legacy sidecars are imported, never deleted — four are live and unanswered. Also records the operator's deterministic-order directive as a cross-cutting v1 invariant, in ROADMAP.md with the per-collection rule table and as CLAUDE.md invariant 6. The Booth's job is comparison; an order that moves between renders does not crash, it misfiles the judgment. 242 tests. No version bump — a release tier for this is the operator's call.	2026-09-21 23:38:27 -07:00
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

Author

SHA1

Message

Date

vh

bb1e3cfcd7

fix(booth): templates were hot-reloading into a live service running older Python

19 of 25 live booths returned 500 with `UndefinedError: 'item_marks' is
undefined`. Neither the old code nor the new code was broken — the service was
running both at once.

`booth.service` sets WorkingDirectory to this repo, so the repo IS the
deployment root: no build step, no staging copy, the live service imports these
files. Python is read once when the process starts. Jinja's FileSystemLoader
re-reads a template on EVERY render. So the two halves of the service had
different staleness rules, and editing booth.html deployed it instantly against
Python from 22:03 that had never heard of the context the new markup wanted.

The failure mode is worth naming precisely, because it is invisible to the
suite by construction: the skew exists between a running process and the disk
underneath it, so every test can pass against a tree that is simultaneously
serving 500s. No amount of green catches this. The operator found it.

Fixed at the source rather than with a reminder to restart. The template
Environment is built here with auto_reload=False, so templates are cached at
startup exactly like the Python, and there is ONE rule: nothing takes effect
until you restart. The price is that template work needs a restart to see —
that price is the entire point, and it is cheaper than a page of 500s while
someone is reviewing.

Building the Environment by hand means autoescape no longer comes from the
Jinja2Templates constructor, so it is explicit and load-bearing: booth names,
item names and mark text are all agent- or operator-authored strings that land
in HTML. Verified escaped, not merely configured.

Two tests hold the line — one on the snapshot property, one on the `dur` filter
that is no longer incidental to the constructor. The environment is reachable at
app.state.templates because a promise about the deployed service needs an
assertion, and an assertion needs the env the app actually renders with.

Also records the foot-gun in CLAUDE.md and persistent-memory: anyone editing
this repo while the operator may be using the service is editing production.

244 tests. No version bump — the release tier for U2 is still the operator's
call, and this rides with it.

2026-09-21 23:44:37 -07:00

vh

c7f9437a64

feat(marks): one primitive for operator judgment, so the loop stops running through chat

Five mechanisms existed to get one question next to one artifact. Three of
them were the same thing wearing different clothes, and the third of the three
had no code at all: the operator picked winners out of a 270-image set and
told the session in conversation. `sindra-finalists` is 86 items, every one
captioned, with the selection encoded in the booth's NAME.

A MARK is operator judgment attached to a target — the booth, or one item in
it, addressed by the `rel` U1 established as item identity. Three shapes:

  pick — one of N options a session declared in advance   (was: an ask)
  note — free text the operator volunteered               (had nothing)
  flag — this one                                         (had nothing)

One file per booth, one read path, one place openness is computed, one slot
beside the artifact. The storage shape is the operator's call (2026-09-21) and
follows from U4: "does this booth still owe an answer?" gets asked per booth
per sweep tick and per card per index render, so it has to be one read and not
a walk of a booth holding 270 files. Marks are also not links.md — that is an
O_APPEND content-hash log because 17 handles write it concurrently, whereas a
booth's marks see one session and one operator, so locking the common path
costs nothing.

The 2026-09-09 pick semantics are preserved by NOT rewriting them: partial
answers legal, a blank question lands in `unanswered`, `complete` false until
every question has a pick, the only refusal a submission carrying nothing.
`write_answer` split into the pure `build_answer` plus the storage that went
away with the sidecar; `normalize_ask` untouched.

Three findings worth naming, because each was caught by a gate rather than by
reading the diff again:

  * The seam review found `inline.place` indexes asks by SUBSCRIPT — the only
    consumer in the service that does — so a frozen dataclass breaks it, and
    `inline.py` had been missing from the contract's scope entirely.
  * A retargeted test found a regression in the legacy importer: a malformed
    sidecar that renders "broken" today would have silently vanished on
    migration. It now imports carrying its reason.
  * A partially-answered pick counted as CLOSED on the index while the panel
    beside it rendered it "partial" — the two disagreed about one booth. Open
    is the reading U4 needs, and it is declared rather than smuggled in.

`GET /b/<n>/marks.json` is new and load-bearing: sessions on other hosts polled
`<stem>.answer.json` over HTTP, so removing the sidecar without it would have
taken that capability away. `/b/<n>/asks` 308s to `/marks`. Legacy sidecars are
imported, never deleted — four are live and unanswered.

Also records the operator's deterministic-order directive as a cross-cutting v1
invariant, in ROADMAP.md with the per-collection rule table and as CLAUDE.md
invariant 6. The Booth's job is comparison; an order that moves between renders
does not crash, it misfiles the judgment.

242 tests. No version bump — a release tier for this is the operator's call.

2026-09-21 23:38:27 -07:00

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