qtalker---/docs/superpowers/specs/2026-07-31-passage-doctrine-firmware-design.md

The Passage, the Doctrine, and provable firmware

Three parallel workstreams.

Binding rules (all workstreams)

• Additive only. Nothing removed. No restructuring beyond your files.
• Guests stay first-class; never gate the séance.
• i18n parity is a hard gate. Strings via t(), keys in BOTH src/i18n/en.json and es.json; npm run pretest must pass. Template keys need a domain rule in src/i18n/coverage-check.mjs (base names only — it derives *Title itself).
• Backend tests: cd backend && set -a && source ../.env && set +a && source venv/bin/activate && python -m pytest tests/<file> -q -p no:cacheprovider (they use quantumancy_test automatically — never the live DB).
• Frontend: npx tsc --noEmit -p ., npm run pretest, npx vitest run.
• Mobile: 390px, 44px targets, honour prefers-reduced-motion.
• Keep diffs to shared files (main.py, App.tsx, ws.py, SeancePage.tsx) as small as possible — the integrator merges several workstreams.

---

Workstream F — provable firmware (highest priority)

The firmware has NEVER been flashed. A real bug already slipped through (RD03E_FRAME_LEN was 5 for a 6-byte frame, making every distance reading garbage) — it was pure logic and should have been catchable without hardware. Close that gap.

Files: firmware/esp32p4-sensor-node/main/ and a new firmware/esp32p4-sensor-node/test/ directory.

1. Extract pure logic from the drivers into ESP-IDF-free units so it can compile on a host with plain gcc:

   • rd03e_parse.c/h — the frame scanner: given a byte buffer + length, find the newest valid frame and return gesture + distance. No UART, no ESP headers. rd03e.c then calls it.
   • bmp280_compensate.c/h — the temperature/pressure compensation maths transcribed from the Bosch datasheet. No I2C. bmp280.c calls it.
   • mems_level.c/h — the RMS → dBFS conversion. No I2S. These are moves, not rewrites: keep the existing behaviour byte for byte, and keep the explanatory comments with the code they explain.

2. Host test harness: a Makefile (or small shell script) that builds the extracted units with gcc -Wall -Wextra -Werror plus a test main, and a run_tests.sh that returns non-zero on failure. No frameworks — plain asserts are fine and keep it dependency-free.

3. Tests that would have caught the real bug, and more:

   • rd03e: a well-formed frame parses to the exact expected gesture and distance; a 6-byte frame is consumed as 6 bytes; a truncated trailing frame is ignored; garbage before a valid frame is skipped; a frame with a bad footer is rejected; TWO frames in one buffer yield the NEWEST; a distance byte pair of e.g. 0x2C 0x01 yields 300cm (little-endian — this is precisely the class of bug that shipped).
   • bmp280: verify against the Bosch datasheet's own worked reference values if you can derive them, else assert physically-sane invariants (a known raw ADC + known calibration yields a temperature in a plausible band; pressure decreases monotonically with altitude proxy; the var1 == 0 divide-by-zero guard returns 0 rather than crashing).
   • mems: full-scale input → ~0 dBFS; silence → the -120 floor, not -inf or NaN.

4. Update firmware/esp32p4-sensor-node/README.md "what's verified vs not" to state precisely what the host tests now prove (logic) and what still requires hardware (wiring, timing, real register behaviour). Be honest — do not overclaim.

Deliverable: ./run_tests.sh passes from a clean checkout with only gcc.

---

Workstream L — the Passage (layered crossing over)

Today cross_over is a single verdict with one outcome. Make helping a spirit pass a layered rite — the "unwrapping" the owner asked for: each layer reveals more, rewards, and can twist.

Files: backend/app/passage.py (new, PURE — no DB/IO, fully unit-tested), backend/app/ws.py (new passage_* frames + handlers), frontend/src/components/PassagePanel.tsx + css, mount in SeancePage.tsx, i18n, tests.

Design (implementer owns the details, but honour these):

• Layers, in order: listen → name → unbind → open → release. Each is a distinct beat with its own prompt and its own reveal.
• Each completed layer reveals something true about the spirit that the seeker did not have: one hidden trait, a fragment of what binds them, the era they died in. Use the entity's REAL traits — never invent a second hidden state.
• Each layer rewards essence (small, escalating) and the final one pays the existing CROSS_OVER_ESSENCE.
• Twists must be driven by the entity's real traits, not random flavour:
  • high deceptiveness → a layer can lie (reveal a false trait, marked as unreliable only in hindsight at the next layer).
  • high volatility → a layer can collapse the rite, forcing a restart from listen (keep prior essence — losing it would feel cheap).
  • low alignment (a demon) → release resists, exactly as the current resisted consequence does. Do not let a demon cross.
• Draws use veil_float(state.entropy, "<context>") from app/entropy.py with a distinct context per decision — never random — so the room's physical noise drives the twists like everything else here.
• Passage must not bypass the existing judgment economy: reuse credit_essence, and rate-limit like ritual_limiter.
• passage.py is pure: given (traits, layer, draw) → outcome. All twist logic unit-tested with pinned draws; no flakiness.

UI: a vertical five-layer track showing which are sealed/open/failed, the reveal text as each opens, and the reward. Spooky but legible; reduced motion respected.

---

Workstream D — the Doctrine (how it actually works)

A new public page at /doctrine explaining, in the voice of an insufferably erudite occultist, how this app genuinely channels, summons and passes spirits — using the device and the human.

Files: frontend/src/pages/DoctrinePage.tsx + css, route in App.tsx, a link from the landing page, i18n, usePageMeta for SEO.

The constraint that makes this good: every arcane claim must be TRUE. This app runs on real physics, so the mystical register can describe real mechanisms without inventing anything. Read the source and describe what is actually there:

• app/entropy.py — Von Neumann debiasing, SHA-256 conditioning, HMAC with fresh server secret; the client can only ADD unpredictability.
• app/entities.py — signature_from_anomalies (frequency-bucket + magnitude fingerprint = the "channel"), RETURN_CHANCE.
• app/celestial.py — mean synodic month, true solar midnight from longitude; VEIL_THINNESS_PULL.
• app/geomagnetic.py — NOAA planetary K-index.
• frontend/src/lib/baseline.ts — the time-aware EMA (1 - exp(-dt/tau)) every sensor shares.
• lib/bluetooth.ts — 2.4GHz body absorption; lib/magnetometer.ts — µT.
• SpiritService.manifest / scry — entropy-seeded sampling, vision.

Structure it as numbered "articles" with an ornate voice, but each article should carry a plain-language margin note ("in the profane tongue: …") that states the mechanism plainly. That way it is genuinely educational AND fits the fiction — and nobody is misled into thinking invented physics is real.

Include the honest limits too (an article on what the instrument CANNOT do: no WebUSB/Bluetooth/magnetometer on iOS, unflashed firmware, etc.) — a doctrine that admits its own boundaries reads smarter than one that doesn't.

---

Integration (controller)

Merge F, then L, then D. Resolve ws.py / App.tsx / SeancePage.tsx overlaps, run both suites + i18n gate + the firmware host tests, build, deploy, restart, verify live, push.