feat(spec): versioned wire-contract spec (v1 as-is + v2 target)#25
Merged
Conversation
Formalize the firmware wire contract as JSON Schema 2020-12 under spec/: v1 pins current 1.x behavior verbatim (transport divergences documented, frozen after merge), v2 defines the unified target contract (envelope on every reply, stable error codes, protocol handshake field). Fixtures are golden replies validated by Ajv in CI; spec/scripts/capture_fixtures.py re-captures them from a live device. Bump CI to Node 26 and replace corepack (unbundled since Node 25) with pnpm/action-setup. Refs #18 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01SBnenzHAV3VVAF8b8hpwkT
Replaces the source-derived v1 fixtures with actual 1.x firmware output captured over HTTP (spoolid.local) and USB serial, per transport variant. wifiSsid values are redacted; everything else is verbatim device output. Refs #18 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01SBnenzHAV3VVAF8b8hpwkT
Collaborator
Author
|
v1 fixtures re-captured from a live device (HTTP via spoolid.local + USB serial): spec/status/config both transports, read ok + err-no-tag, dump (real tag: uid 1018EF5F). wifiSsid redacted. Write-path fixtures (write/configset/db/ota replies) stay source-derived — capture is read-only by design, no tag writes or flash ops. validate.mjs green. Both checklist items done. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
PR1 of #18 — the wire contract becomes a first-class, versioned artifact. No behavior change.
spec/v1/— frozen snapshot of what 1.x firmware actually speaks: 17 JSON Schemas (2020-12),PROTOCOL.mdwith the transport-divergence table (HTTP GETs lackok,dump/otaabortserial-only,dbbeginsizeignored, DB POST always acks), fixtures authored fromweb_server.cpp/serial_proto.cppsource. Errata-only after merge.spec/v2/— the unified target contract:okenvelope on every reply,{ok,error,code}errors with a stable code enum,protocol: 2handshake,GET /api/dump,readgainsserial,dbdataackswritten. Implemented by PR2 (feat!:).spec/ts/— Ajv validator (pnpm --dir spec/ts validate): schema-compile lint + every fixture validated + repo-rootmaterial_database.jsonchecked. Verified red on bad fixture and broken$ref.spec/scripts/capture_fixtures.py— re-captures fixtures from a live device (HTTP + serial), so the spec is pinned to reality, not folklore.specjob;spec/**added to web/desktop filters; Node 22 → 26 everywhere;corepack enable→pnpm/action-setup@v4(corepack unbundled since Node 25)..gitignoreentries from the abandonedtools/gen_spec.pyattempt.Before merge
python spec/scripts/capture_fixtures.py --version v1 --host <ip> --port <serial>(current fixtures are source-derived; capture is the machine proof)pnpm --dir spec/ts validategreen after captureVerification
node spec/ts/scripts/validate.mjs→spec OK: schemas compile, fixtures + material_database.json validate$ref→ clean compile FAIL, no crashPart of #18. Next: PR2 firmware v2 (
api_corerefactor + native contract test).🤖 Generated with Claude Code
https://claude.ai/code/session_01SBnenzHAV3VVAF8b8hpwkT