From ff209b33323406ddb6d5b0ed95216de3be5729d3 Mon Sep 17 00:00:00 2001 From: dayfine Date: Sat, 14 Nov 2026 01:35:49 -0800 Subject: [PATCH 1/2] lab/server: Slice 0 version-1 contracts, goldens and parser (#131) Freezes the JSON contracts of the pa-lab console daemon before anything writes or serves them: app state (Lab/state.json), save facts, console and save resources, requests, request records, refusals, events and event pages. A stdlib parser validates each kind with field-level errors, keeps unknown fields of open documents, and round-trips every golden. Legacy Lab/state twins pin the mapping Slice 1's app writer must honour. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_013VUubhHeYSMGSSDXZkKZss --- .github/workflows/agents-check.yml | 2 + AGENTS.md | 1 + lab/server/README.md | 112 + .../contracts/v1/app_state/future_fields.json | 57 + .../contracts/v1/app_state/no_program.json | 41 + .../contracts/v1/app_state/running_lab.json | 50 + .../contracts/v1/app_state/stopped_ui.json | 47 + .../available_agent_running.json | 71 + .../console_state/available_user_lease.json | 68 + .../v1/console_state/unavailable.json | 25 + .../v1/event/lease_changed_to_user.json | 23 + .../contracts/v1/event/program_failed.json | 14 + .../contracts/v1/event/request_failed.json | 22 + lab/server/contracts/v1/event/save.json | 36 + lab/server/contracts/v1/event/stopped_ui.json | 13 + lab/server/contracts/v1/event/video_lost.json | 12 + .../contracts/v1/event_page/after_1040.json | 64 + lab/server/contracts/v1/event_page/empty.json | 5 + lab/server/contracts/v1/invalid_cases.json | 2454 +++++++++++++++++ .../contracts/v1/legacy/no_program.state | 6 + .../contracts/v1/legacy/running_lab.state | 7 + .../contracts/v1/legacy/stopped_ui.state | 7 + .../contracts/v1/refusal/held_by_user.json | 9 + .../v1/refusal/invalid_arguments.json | 10 + .../contracts/v1/refusal/precheck_failed.json | 14 + .../contracts/v1/refusal/shot_timeout.json | 13 + .../contracts/v1/request/acquire_console.json | 11 + .../contracts/v1/request/cfr_batch.json | 15 + .../contracts/v1/request/run_program.json | 17 + .../v1/request_record/completed_run.json | 23 + .../v1/request_record/pending_stop.json | 12 + .../v1/request_record/refused_preflight.json | 25 + .../v1/save_fact/frlg_checkpoint.json | 18 + .../contracts/v1/save_fact/outside_story.json | 13 + .../contracts/v1/save_resource/known.json | 25 + .../v1/save_resource/stale_after_user.json | 25 + .../contracts/v1/save_resource/unknown.json | 8 + lab/server/pa_lab/__init__.py | 1 + lab/server/pa_lab/__main__.py | 54 + lab/server/pa_lab/contracts.py | 735 +++++ lab/server/pa_lab/legacy.py | 50 + lab/server/tests/__init__.py | 0 lab/server/tests/test_contracts.py | 165 ++ 43 files changed, 4380 insertions(+) create mode 100644 lab/server/README.md create mode 100644 lab/server/contracts/v1/app_state/future_fields.json create mode 100644 lab/server/contracts/v1/app_state/no_program.json create mode 100644 lab/server/contracts/v1/app_state/running_lab.json create mode 100644 lab/server/contracts/v1/app_state/stopped_ui.json create mode 100644 lab/server/contracts/v1/console_state/available_agent_running.json create mode 100644 lab/server/contracts/v1/console_state/available_user_lease.json create mode 100644 lab/server/contracts/v1/console_state/unavailable.json create mode 100644 lab/server/contracts/v1/event/lease_changed_to_user.json create mode 100644 lab/server/contracts/v1/event/program_failed.json create mode 100644 lab/server/contracts/v1/event/request_failed.json create mode 100644 lab/server/contracts/v1/event/save.json create mode 100644 lab/server/contracts/v1/event/stopped_ui.json create mode 100644 lab/server/contracts/v1/event/video_lost.json create mode 100644 lab/server/contracts/v1/event_page/after_1040.json create mode 100644 lab/server/contracts/v1/event_page/empty.json create mode 100644 lab/server/contracts/v1/invalid_cases.json create mode 100644 lab/server/contracts/v1/legacy/no_program.state create mode 100644 lab/server/contracts/v1/legacy/running_lab.state create mode 100644 lab/server/contracts/v1/legacy/stopped_ui.state create mode 100644 lab/server/contracts/v1/refusal/held_by_user.json create mode 100644 lab/server/contracts/v1/refusal/invalid_arguments.json create mode 100644 lab/server/contracts/v1/refusal/precheck_failed.json create mode 100644 lab/server/contracts/v1/refusal/shot_timeout.json create mode 100644 lab/server/contracts/v1/request/acquire_console.json create mode 100644 lab/server/contracts/v1/request/cfr_batch.json create mode 100644 lab/server/contracts/v1/request/run_program.json create mode 100644 lab/server/contracts/v1/request_record/completed_run.json create mode 100644 lab/server/contracts/v1/request_record/pending_stop.json create mode 100644 lab/server/contracts/v1/request_record/refused_preflight.json create mode 100644 lab/server/contracts/v1/save_fact/frlg_checkpoint.json create mode 100644 lab/server/contracts/v1/save_fact/outside_story.json create mode 100644 lab/server/contracts/v1/save_resource/known.json create mode 100644 lab/server/contracts/v1/save_resource/stale_after_user.json create mode 100644 lab/server/contracts/v1/save_resource/unknown.json create mode 100644 lab/server/pa_lab/__init__.py create mode 100644 lab/server/pa_lab/__main__.py create mode 100644 lab/server/pa_lab/contracts.py create mode 100644 lab/server/pa_lab/legacy.py create mode 100644 lab/server/tests/__init__.py create mode 100644 lab/server/tests/test_contracts.py diff --git a/.github/workflows/agents-check.yml b/.github/workflows/agents-check.yml index 4e0cc10420..25059c35a1 100644 --- a/.github/workflows/agents-check.yml +++ b/.github/workflows/agents-check.yml @@ -44,6 +44,8 @@ jobs: run: python3 -m unittest discover -s lab/scripts -p test_label_shots.py -v - name: Route review script tests run: python3 -m unittest discover -s lab/scripts -p test_review_route.py -v + - name: Lab server contract tests + run: python3 -m unittest discover -s lab/server/tests -t lab/server -v - name: Code health linter self-tests run: | python -m pip install -r devtools/code_health/requirements.txt diff --git a/AGENTS.md b/AGENTS.md index 921d268020..581968f028 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -64,6 +64,7 @@ There are two different checks, and neither replaces the other: | What | Where | Use | |---|---|---| +| Lab server (pa-lab console daemon, #131): version-1 contracts | [lab/server/](lab/server/README.md) | Slice 0: goldens + parser; `python3 -m pa_lab check app_state ` from `lab/server`. | | Lab control: lock, channel, CFR batches | [lab/control/](lab/control/README.md) (`lablock.sh`, `labctl.sh`, `cfrun.sh`) | `sh lab/control/lablock.sh status`; one train on the console. Old copy: `devtools/lab` on `lab/main`. | | Console B helpers | [lab/scripts/](lab/scripts/README.md) (`lc.sh`, `sel.sh`, `cfr.sh`, `env.sh`) | `sh lab/scripts/lc.sh state`; `printf ... \| sh lab/scripts/cfr.sh NAME`. | | CFR syntax and the HOME gotcha | [lab/scripts/README.md](lab/scripts/README.md#cfr-batch-syntax) | Start each batch with a `shot`; at HOME, `press A` before any stick. | diff --git a/lab/server/README.md b/lab/server/README.md new file mode 100644 index 0000000000..44dcbd5918 --- /dev/null +++ b/lab/server/README.md @@ -0,0 +1,112 @@ +# pa-lab console daemon (`lab/server`) + +The local server designed in `docs/design/Agent-Integration.md` (fork #131, branch +`design/agent-integration`). This directory is Slice 0 only: the version-1 contracts, golden +examples and a parser. There is no server, no network code and no app change here yet. + +| Path | What | +|---|---| +| `pa_lab/contracts.py` | Version-1 specs for every document kind, `parse` / `validate` / `dump` / `describe` | +| `pa_lab/legacy.py` | The legacy `Lab/state` key=value file and its mapping to `Lab/state.json` | +| `pa_lab/__main__.py` | `python3 -m pa_lab check `, `describe `, `kinds` | +| `contracts/v1//*.json` | Golden examples, one folder per kind; canonical JSON (2-space indent, `\n` at end) | +| `contracts/v1/legacy/*.state` | Legacy `Lab/state` twins of three `app_state` goldens (`stopped_ui` is the real lab-B file of 2026-11-14) | +| `contracts/v1/invalid_cases.json` | Documents that must fail: name, kind, input, expected field path and message | +| `tests/test_contracts.py` | Golden parse, round-trip, invalid-case and legacy-mapping tests | + +Stdlib only (Python 3.8+), so no venv yet; Slice 2 adds `requirements.txt` and a venv +(`~/.venvs/pa-lab`) for the MCP server. Run the tests from the repo root: + +```sh +python3 -m unittest discover -s lab/server/tests -t lab/server -v +``` + +Check a real file (from `lab/server`): + +```sh +python3 -m pa_lab check app_state "$HOME/Library/Application Support/SerialPrograms/Profiles/lab-B/Lab/state.json" +python3 -m pa_lab describe app_state # the full field tree of any kind +``` + +## Kinds and who writes them + +The daemon never edits an app-authored document. Its resources embed one whole +(`console_state.app`, `save_resource.fact`) and put their own fields beside it, so the authorship +boundary is the object boundary. + +| Kind | Writer | Where | +|---|---|---| +| `app_state` | app | `Lab/state.json`, rewritten atomically on every change and as a heartbeat | +| `save_fact` | app (a program that saved) | `Lab/save.json` | +| `console_state` | daemon | `console://B/state`: `app` + availability, lease, current refusals | +| `save_resource` | daemon | `console://B/save`: `known` / `stale` / `unknown`, reason, last fact | +| `request` | client | a mutating tool call (`acquire_console` ... `cfr_batch`) | +| `request_record` | daemon | request status and the stored result an exact retry gets back | +| `refusal` | daemon | a tool's error result, naming the failed check or field | +| `event` | daemon | one SQLite events row (and a JSONL export line) | +| `event_page` | daemon | the result of `next_events(after_seq)` | + +## Rules for every kind + +- **Version.** Every document has an integer `schema`; this reader supports `1`. A missing, + non-integer or unsupported version fails at `schema` before any other field is read. A + document embedded in another (`console_state.app`) carries its own `schema`. +- **Timestamps** are UTC strings with milliseconds and `Z`: `2026-11-14T06:10:12.124Z`. No + offsets, no epoch numbers. They round-trip as the exact string. +- **UUIDs** (`instance.id`, `request_id`) are lower-case `8-4-4-4-12`. +- **Required vs nullable.** "Required" means the key is present. A required key may still allow + `null` where the field tree says `| null`; `null` means "none" or "not known", never "ok". + Optional keys are omitted, not set to `null`, when a writer has nothing. +- **Unknown values.** Enums are closed within a version: a value the reader does not know fails + at that field (`video.signal: 'no_hdmi' is not one of ok, black, colour_bars, unknown`). + Observations that have no detector yet use the literal value `unknown`; a non-`unknown` + observation needs `observed_at` and `detector`. +- **Unknown fields.** Documents the app or daemon writes are *open*: a field the reader does not + know is kept verbatim, listed in `Parsed.unknown` and written back by `dump`, so diagnostics + survive a newer writer. Requests are *closed*: an unknown top-level key or tool argument is + refused, because requests are the daemon's input boundary. +- **Errors** name the field: `program.last_transition.request_id: required when source is lab`. + One parse reports every field error it found, except that a version error stops first. + +### Compatibility + +- Adding an optional field to an open object needs no version change; old readers keep it. +- Adding an enum value, adding a required field, removing, renaming or retyping a field, or + changing what a value means needs `schema: 2`, and the daemon keeps reading `1` until the app + stops writing it. A reader refuses versions it does not list; the daemon reports that as + `availability.reason: unsupported_schema`, not as a guess. + +## `app_state` (`Lab/state.json`) and the legacy `Lab/state` + +The app keeps writing the legacy file unchanged and writes `Lab/state.json` from the same state. +Every legacy field maps; only the owner token is reduced to a yes/no, so the token is not copied +into a second file. + +| Legacy `Lab/state` | `Lab/state.json` | +|---|---| +| `seq=fs012327` | `channel.last_request` (`null` before the first request) | +| `state=STOPPED\|RUNNING\|STOPPING\|NOT_READY\|NO_PROGRAM` | `program.state`, lower case; `no_program` exactly when `panel.kind` is `other` | +| `program=PokemonFRLG:AutoStory` | `panel.id` when `panel.kind` is `program` (legacy writes empty otherwise) | +| `controller=ready\|none\|` | `controller.state` `ready` / `not_connected` / `no_console` | +| `owner=` | `channel.owner_claimed` (bool); the token stays only in the legacy file | +| `error=` | `channel.last_error` (`null` when the last request succeeded) | +| `paused=