Arena Studio: one rig/arena selection shared across Run/Edit/Console (locked by default)

[mbreiser]

Problem

The arena/rig identity currently lives in three loosely-coupled places in arena_studio.html:

1. Run view / top bar — derived from the loaded protocol's rig: path (read-only display + provenance).
2. Console — its own arena dropdown in the caption (drives stream-frame geometry, the batch-ISP progress map, paste-frame validation, FicTrac framing). Defaults to the protocol's rig but is trivially easy to change with one click — including accidentally, which silently changes what geometry gets streamed to the hardware.
3. Edit view — Settings → Rig (Browse…/built-in dropdown), which edits the protocol document itself.

Redundant selection points invite drift: the Console can quietly disagree with the loaded protocol, and nothing surfaces the mismatch.

Proposal

• Single source of truth for the session's arena/rig, owned by the Studio shell (Studio.currentRig or similar), consumed by all three views. Loading a protocol sets it (from rig:); the Edit view's Settings→Rig continues to edit the document, and doing so updates the session rig.
• Locked by default: the selector (wherever it renders — likely once, in the top bar next to the device line) shows a 🔒 and requires an explicit unlock click before it can be changed, mirroring the read-only-in-Run philosophy. Rationale: changing the arena geometry mid-bench is a deliberate, rare act — one-click changes caused near-misses at the bench.
• Mismatch surfacing: if the user overrides the session rig away from the loaded protocol's rig, show a visible chip/warning ("bench arena ≠ protocol rig") rather than silently diverging.
• Console keeps reading the shared value (stream geometry, ISP map, paste validation, FicTrac) but loses its own independent selector.

Notes

• Today's console selector was added for standalone bench use before the embed existed; with all three views in one page it's now redundant.
• Related policy: docs/development/arena-studio-parity.md (Studio is the primary path).

[mbreiser]

Addendum (2026-07-03): ?rig= URL param + expanded rig I/O config — context so this is implementable in one session (from the #107 write-side session; user-requested scope).

A. ?rig=<key> — the session rig's URL mirror

Once the single session rig exists (this issue's core), mirror it in the URL so per-setup bookmarks work in all three modes — arena_studio.html?rig=cshl_g6_2x10 taped to each bench means a newcomer opens Run/Edit/Console already pointed at the right arena, before any protocol is chosen.

• Semantics: rig = the bench/session rig, never an override of the protocol. The protocol's rig: stays authoritative for the document. URL rig ≠ loaded protocol's rig → the mismatch chip this issue already proposes; never silently reconcile, never mutate the doc from a URL.
• Decode (read side): validate against configs/rigs/index.json → rigs[].name (all current names are slug-safe per the codec's KEY_RE), exactly the allowedKeys pattern initFromUrl already uses for p against protocols/index.json. Unknown key → warn + drop + scrubbed by the init canonical replace (all existing behavior).
• Encode (write side): extend encodeApp() in js/studio-url-state.js with a rig field (+ tests/test-studio-url-state.js). CLAUDE.md already states the rule: all shareable state flows through encodeApp + Studio.updateUrl — never hand-build location.search. Encode only an explicit user selection; omit when derived from the loaded protocol (clean-URL rule — a derived rig is redundant with ?p=).
• Precedence at load: ?p= protocol still populates the session rig as today; an explicit ?rig= wins for the session value and raises the mismatch chip if it disagrees with the protocol.
• Session-rig changes are Studio.updateUrl({ push: false }) (identity, not view navigation — same replace rule as doc changes).

B. Expanded rig config (G6): controller I/O roles + power-on defaults

The rig should also declare the arena controller's available I/O and their default states — applied at connect, overridable from the Console:

# addition to configs/rigs/*.yaml (format_version "1.0" schema)
io:
  dio:                      # 2 ports on the G6 controller
    - port: 0
      role: off             # off | in_trigger | out_programmable | out_debug_framescan
      default: 0            # 0|1 — outputs only
    - port: 1
      role: out_programmable
      default: 1
  ai:
    role: off               # off | in   (closed-loop analog input — untested, needs bench)
  ao:
    role: programmable      # programmable (YAML-driven, today's 0xA0 path) | frame_number
    default: 5.0            # volts at connect — IMPORTANT: some hardware expects 5 V idle, not 0

• Apply at connect: in the Studio's initFromController() flow (after the existing GETs), push the rig's I/O defaults — AO via Wire.encodeSetAnalogOut (0xA0), DO via encodeSetDigitalOut (0xAA), both from feat: G6 analog/digital-out protocol commands + designer field validation #126 — and log each applied default to the console trace.
• Console overrides: add Controller▾/Debug▾ menu items to view + override each port's role/state ad hoc (follow the .cmenu conventions in CLAUDE.md). Overrides are session-local; they never edit the rig YAML.
• Firmware-gated roles (schema lands now; wire-up when fw ships): out_debug_framescan (DIO wired to frame-scan timing — not yet implemented in fw), frame_number AO encoding (fw mode needed), in_trigger semantics, AI closed-loop (untested). Rigs can be authored once; the Studio greys out roles the connected firmware can't do, with a tooltip naming the dependency.
• Parser entry: parseRigYAMLText (js/protocol-yaml-v3.js) + a tolerant io: reader alongside deriveRigPlugins (js/plugin-registry.js) — missing block ⇒ everything off/0; never throw on partial input; unit tests next to the N12 rig suite.

One-session acceptance checklist

• Session rig single source of truth + 🔒 unlock + mismatch chip (this issue's core)
• ?rig= decode (registry-validated) populates the session rig in all 3 modes; encode via encodeApp only for explicit selections; codec tests extended
• io: block parsed tolerantly from rig YAML; defaults applied at connect + logged
• Console menu items to override AO/DO role + state live
• fw-gated roles visible but disabled, tooltip names the firmware dependency

🤖 Generated with Claude Code

[mbreiser]

Course-data pipeline — decisions (2026-07-03). Companion record to this issue's Session-1 scope: the reviewed build plan splits the work into Session 1 (this issue + firmware MAC) and Session 2 (course pipeline). Posted so the decisions are durable before code starts. The plan was verified claim-by-claim against the repo and interview-amended; items marked ⚠ are corrections that override earlier sketches.

Course model

• ONE shared course-data repo (new, e.g. reiserlab/cshl-2026-course-data), 7 fixed bench/laptop rigs, one shared fine-grained PAT.
• Instructor one-time setup per bench: PAT sign-in (must take the "also store in localStorage" option — sessionStorage-only evaporates when the tab closes), repo owner/name, direct-commit checkbox, bench id. Students never see/paste the token.
• Curriculum = pre-loaded matched SD cards + site-registry protocols (protocols/index.json, read-only, unchanged). Secondary but real: students modify a few patterns/protocols and run + commit their own experiments.

RIG-ID (namespaces all writes)

• ⚠ rig-id = instructor-set bench id (localStorage, e.g. bench03) — NOT a MAC slug and NOT the rig-config name: configs/rigs/ holds only 3 arena-TYPE configs shared across the 7 benches, so a name-derived id collides and breaks the "no two rigs ever write the same file" argument for direct commit.
• MAC is a cross-check, not identity: 0xC2 GET_CONTROLLER_INFO grows MAC bytes (firmware, Session 1; the JS decode at js/arena-wire-g6.js:570 is already tolerant), fetched at connect — NEW wiring in initFromController(), 0xC2 isn't fetched today — and compared against the roster; mismatch shows a warning chip.
• Unset bench id ⇒ course-repo auto-commits blocked with a clear notice; never fall back to a colliding name.

Repo layout

roster.yaml                                        combined course roster {id, name, rig_id, mac}
protocols/<rig-id>/<name>.yaml                     personal saves
protocols/<rig-id>/<name>_patterns/*.pat           personal modified patterns
protocols/shared/<name>.yaml (+ _patterns/)        promoted
runlogs/<rig-id>/<proto>__<exp>__<STAMP>__<run_id>.jsonl

STAMP is colon-free (a raw ISO : breaks git checkout on Windows clones). protocols/ is already in WRITABLE_PREFIXES; runlogs/ is the one addition (plus read access to roster.yaml).

Write mode

• Direct commit to the default branch, selected by a Settings checkbox ("commit directly to default branch", per the proposal doc) next to the new repo field; reiserlab/webDisplayTools keeps branch+PR as the default.
• ⚠ The direct orchestration is NEW code — today's only flow is create-branch → PUT → PR; direct = reqGetRepo (default-branch name) → PUT.

Run logging (bridge log = the canonical committed artifact)

• ⚠ Correction: bridge logging is NOT default-on today — the setLogging(true) block only runs when the protocol declares a fictrac plugin AND the bridge client exists; a dead bridge warns but the run proceeds unlogged.
• Session 2 makes it universal + gated: always connect + setLogging(true) at recorded-run start (any protocol), and add bridge-connected to the canRunExperiment gate so a dead bridge blocks recorded runs loudly. Console quick ops stay ungated.
• One .jsonl per run (the bridge already rotates on every log_control{enabled:true}, and the client replays it on socket open — ordering is safe). The browser injects one run_metadata log line (protocol sha, experimenter, genotype, rig-id, run_id, arena config) — no bridge change needed, write_inbound is generic.
• NEW log_export / log_export_result message pair (the protocol's first request/response) + raised websockets max_size (default is 1 MiB); exportLog() Promise in js/fictrac-bridge-client.js. On completion (not aborted): export + direct-commit to runlogs/<rig-id>/. GitHub failure → "saved locally only — on the bridge machine" (accurate: the gate guarantees the bridge was up). Telemetry decimation deferred — measure real file sizes first.
• js/run-log.js's JSON stays as-is (not wired into the auto-commit path).

Student pattern lifecycle

• Author in pattern_editor.html → NEW "push to course repo" button (Session 2; reuses js/studio-github.js request builders — PAT/repo/bench-id are same-origin localStorage, no new auth UI) → protocols/<rig-id>/<name>_patterns/.
• SD side for the course week: the existing Console upload (0x8D + 0x83 rename). A NEW blocking preflight in canRunExperiment refuses to start a recorded run when a pattern: name doesn't resolve in the SD-first picker, with the message naming that remedy. One-click repo→SD sync = named post-course follow-on; content-addressed SD names (proposal option b) also deferred past the course.

Promote-to-shared

• Direct commit, no PR. Hash-compare-before-overwrite on both the shared <name>.yaml and every _patterns/*.pat; mismatch blocks with "a different file already exists under this name".

Roster

• roster.yaml IS the course experimenter list ({id, name, rig_id, mac}, people.yaml conventions; configs/metadata/people.yaml itself untouched). At connect: match bench id → pre-fill experimenter + source the course datalist; MAC mismatch → warning chip.

Pickers + URL

• "Open from library…" (proposal v0, site registry) and "Open from course repo…" (live directory listing via the contents API — NEW array-aware handler; existing reqGetContents consumers assume single-file objects). .pat / large reads use the raw media type (Accept: application/vnd.github.raw; the contents API omits content for files >1 MB).
• ?repo=owner/name; with repo present, p = repo-relative path with a NEW validator (the existing SAFE_PATH_RE targets the document's rig: field and doesn't match repo paths). encodeApp grows a repo field; replace-not-push on identity changes, per the Represent website state in the URL for shareable sessions #107 rules.

Session split

• Session 1 = this issue (session rig + ?rig= + io: power-on defaults, per the addendum above) + the firmware MAC-in-0xC2 change + the initFromController() 0xC2 fetch. Addendum nit: the AO encoder export is encodeSetAoVoltage, not encodeSetAnalogOut. Bench-test on real hardware before declaring done.
• Session 2 = the pipeline above: studio-github binary encoder + runlogs/ prefix + direct-commit path; bench-id/repo settings; roster; course saves; universal logging + gates; blocking preflight; promote; repo previews; both pickers; ?repo=; pattern-editor push-to-repo.

Full reviewed plan (incl. verification checklist): ~/.claude/plans/adaptive-hopping-island.md. The proposal doc's open-questions section is updated in-repo with these answers.

🤖 Generated with Claude Code