crossbar/docs/plans/v1/README.md

v1 implementation plan: leases, queueing, accounting

For the implementing model: do not work from this file. The owner gives you one task file at a time (01-… to 07-…). This file is the index for the owner and the reviewer.

Goal: PLAN.md §4–§7a. Every conversation gets a sticky lease on one host (chosen by free slots × weight when it starts), requests queue per (host, model) instead of overflowing a router, an operator can pin a route or drain a host, and SQLite keeps the leases and an accounting log that answers "which session used which host and model, for how long, at what cache-hit rate".

Architecture: five new packages — store (SQLite, modernc.org/sqlite), fingerprint (conversation key), choose (the scoring rule), limiter (per-(host, model) slots + bounded FIFO), lease (the sticky table, persisted through store) — and v1 versions of proxy, admin, config and cmd/crossbar. The proxy tees streamed responses through an SSE scanner to read the final usage/timings chunk; it never buffers or alters the stream.

How this plan was made: acceptance tests first, from PLAN.md; no reference implementation. Every given test file was compiled against a panic-only skeleton of the interfaces named in the tasks (go vet ./... clean), and nothing else was run. If a test turns out to be wrong, that is the owner's finding: stop and report as AGENTS.md says; do not edit it.

Tech stack: Go 1.26, stdlib, github.com/BurntSushi/toml v1.6.0, modernc.org/sqlite v1.59.0 (pure Go; go.sum given). No other module.

Global constraints

• Everything in AGENTS.md. Branch v1. One task, one fresh OpenCode session, one commit.
• Bodies are never logged or stored. Rows carry names, counts and timings only.
• Given files (tests, example.toml, cmd/fakeupstream/main.go, tools/smoke.sh, go.sum) are copied and never edited. Some replace v0 files of the same name; the task says so.

Tasks

#	File	Delivers	Tests that define it
01	01-store.md	internal/store: SQLite state + accounting	internal/store/store_test.go
02	02-fingerprint-config.md	internal/fingerprint; config gains db, lease_idle, retention, day suffix	fingerprint_test.go, config_v1_test.go
03	03-limiter-choose.md	internal/limiter, internal/choose	limiter_test.go, choose_test.go
04	04-lease.md	internal/lease: the sticky table	lease_test.go
05	05-proxy.md	proxy v1: leases, queue, SSE tee, accounting, header route	proxy_test.go (replaces v0's)
06	06-admin-main.md	admin v1 (pin/release/drain/usage/metrics), cmd/crossbar wiring	admin_test.go (replaces), start/stop check
07	07-smoke-readme.md	tools/smoke.sh v1 run, README update	make smoke

For the owner: running a task

tools/run-plan.sh docs/plans/v1          # from a clean checkout on master

For the reviewer: after task 07

1. git log --oneline master..v1: seven commits with the trailer.
2. Copied files byte-identical to _files/; git diff <merge-base>..v1 --stat -- PLAN.md AGENTS.md docs/plans empty.
3. make gate, make smoke.
4. Read every source file against its task. Probe outside the tests: a lease whose host is drained and unhealthy; lease_idle expiry while a request is in flight; a stream cut by the client mid-way (the accounting row must still be written, with the status it had); a body with "messages" that is not an array; two crossbars on the same db file; Prune while requests are being recorded.
5. Every .( type assertion in internal/ is the two-value form or on a value we constructed.
6. Findings under "Reviews" in docs/implementer-log.md, by fault (model / task / test).

Changes during the run

• 2026-09-25, task 01, first attempt: three given test files under _files/ were not gofmt-clean, and the gate's gofmt -l . walks every file, so the gate failed on files the implementer may not edit. Ornith diagnosed it (gofmt on its own code was clean) and did not touch them. Owner's fault (the compile check ran go vet, not gofmt, on the given files). Fixed by formatting the given files; the plan checklist now includes gofmt -l docs/ before handover. Ornith stopped correctly (a stopped row, code left in the tree, only the log committed); a second session was told where the first had stopped and finished steps 6–7 without starting over — the boxmaker precedent (M3a/19). The driver was then resumed from task 02.
• 2026-09-25, task 02: v0's given testdata/bad-unknown-key.toml used lease_idle as its unknown-key example, and v1 makes lease_idle a real key, so v0's TestBadFiles broke — the task did not hand over replacements for the two v0 given files (tip T19). Ornith changed the example to bogus_key in both files and logged it in Deviations; the content is right, but the files were protected and the rule was to stop. Owner's fault for the conflict; the model's deviation is noted. The corrected files now sit in _files/internal/config/ as the reference copies for the reviewer's byte-exact check.
• 2026-09-25, task 04: my TestPinAndUnpin asserted the pin event at exactly len-3 and the release event at len-1, but the task's own rules make acquires under a pin record events too, so a faithful implementation produces [new pin pin new new release] and the assertion cannot hold. Ornith spent its first ten minutes puzzling over exactly that. Test fault (mine): the assertion now checks order and content (a pin event naming beta, followed later by a release), not positions.