K230 · public project snapshot
Follow each change from proposal to evidence. The lanes reflect committed work at this revision, not a live agent feed. A checked task, landed source, archived plan, and verified device behavior are different claims.
A committed proposal. Work and proof have not started in this snapshot.
Consume the separate static splash-to-Linux repair result as a prerequisite and record its before/after physical evidence; verify the prior wrapped/color-swapped first-modeset case is absent before…
When a slow interaction is reported, measure that workload; deferred drawer/keyboard timing is not a blocker on accepted UX.
Confirm the known-good image hash, serial device, J3 data cable, J2 console cable, and host USB logging commands.
Under the reserved board lock, install the built kernel to /boot
Implementation or investigation is underway; acceptance remains open.
On the reserved board, run
The operator's judgement on glass that the Clock and each restyled
(new) Under a board reservation, run
Install the built Image/k230-tdisplay.dtb to /boot and reboot (a DT/kernel change does not take effect from a system activation alone). Record cat /proc/asound/cards, dmesg | grep -iE…
Extend the same driver's stop path
Establish physical CPU0's CSR.MHARTID and a usable distinct
Review the next unchecked task in the linked task list
BLOCKED on 3.2. Ground a region that remains reserved from
Hardware. Find and remove the transient 1-4-frame scanout glitches of the stage-1 image during early userspace (filmed 2026-10-12 at kernel ~17 s and ~27 s in all three splash boots…
Reproduce rotated/unrotated, ARGB8888/RGB565 baselines, then capture
Resume the queued Qt Quick cross-build after integrated-shell builds, inspect target closure/QML configuration, then measure the plain app on the board before a Quickshell trial.
Resolve target format and presentation costs, then repeat paired GPU-versus-Pixman acceptance on the board before any default change.
Source or tasks advanced; the named review or evidence gate still matters.
The OpenSpec change closed. This does not certify unrelated device features.
Accepted static-theme parent closed at 25/25. Matching consumers are installed and ordinary startup verified. Background/video successor retains its scope.
Review the archived record and cited scope
Complete for accepted portrait HDMI fill and Home/All Apps/Settings targets. Landscape/density/Wi-Fi/theme/dock follow-ups remain with the landscape proposal.
Accepted installed shell is closed. Side-edge Back/general ownership and numerical motion tooling remain in the existing successor; other theme source requirements remain in their own proposals.
Closed. Landscape HDMI and the keyboard-case landscape panel both work; Home and Drawer keep native icon size with more columns, Wi-Fi and the theme chooser reflow, and the dock grows to six slots on wide screens. The dock shrink path and the 1232x568 dock are host-only.
Review the archived record and cited scope
Closed on operator acceptance; see evidence for waived captures and retained limits.
Closed on operator acceptance; see evidence for waived captures and retained limits.
Closed on operator acceptance; see evidence for waived captures and retained limits.
Complete; operator accepts Home interactions and right-click New Window. Physical daylight, fresh-install and reboot-layout limits remain explicit in the spec.
Review the archived record and cited scope
Closed on operator acceptance; see evidence for waived captures and retained limits.
Review the archived record and cited scope
Review the archived record and cited scope
Review the archived record and cited scope
Review the archived record and cited scope
Review the archived record and cited scope
Review the archived record and cited scope
Review the archived record and cited scope
Review the archived record and cited scope
Review the archived record and cited scope
Review the archived record and cited scope
Closed with explicit performance acceptance and selected system/QEMU integration proof. No further performance optimization is selected.
Review the archived record and cited scope
Review the archived record and cited scope
Review the archived record and cited scope
Review the archived record and cited scope
Closed on operator acceptance; see evidence for waived captures and retained limits.
Review the archived record and cited scope
Review the archived record and cited scope
Review the archived record and cited scope
(parent 2.3, verbatim) Run the capture tool on the reserved board across a
Closed with every task complete. Installed as system 298a2bf6 (Rust hl4bca4g); operator accepted the visible apply (28-42 ms tap-to-shown) and real-finger picker motion on both rows. The helper's durable activation (149-179 ms) is recorded, not claimed under 150 ms.
Review the archived record and cited scope
Review the archived record and cited scope
Review the archived record and cited scope
Closed. Vectors run through runtime-gated Pixman on the installed mainline ordinary system; card budgets still fail unchanged and no extension beyond V is used by default. A physical return to the earlier image was not exercised (read-only route check only).
Add shared state IDs/copy keys and visible recovery mapping without moving video/card lifecycle ownership. Verify with python3 tests/test_launcher_navigation.py && python3 tests/test_window_catalog.py…
Review the completed analysis and pursue its existing theme-motion, card/keyboard and theme-consumer owners. Landscape remains separate.
Complete: automatic switching and navigation accepted. Settings reboot scope canceled; landscape remains in its separate proposal. Precise latency measurement is deferred.
Review the archived record and cited scope
Review the archived record and cited scope
Review the archived record and cited scope
Review the archived record and cited scope
Review the archived record and cited scope
Review the archived record and cited scope
Confirm the URL serves the site. Verify by fetching https://knewter.github.io/tdisplay-k230/ and finding the unverified count in it
Review the archived record and cited scope
Archived after matching normal artifacts, ordinary autoboot, physical power-swap recovery and accepted Home/Apps/Overview/Terminal navigation.
Scoped theme coverage and native dark/light rollback are complete; continue broader theme-picker, persistent deployment and shell polish in their owning proposals.
Functional live-card UI accepted. Performance acceptance and selected system/non-fixture QEMU integration gates are closed in 2026-10-10-the-card-deck-still-misses-its-frame-budget.
Review the archived record and cited scope
Volume UI/backend accepted and archived; headphone listening remains open in audio task 5.6.
Review the archived record and cited scope
Completed: repeated edge turns, new-page drops, interior fling and redesigned native widgets verified.
Completed: folder create, join, rename, member extraction, dock placement and widget picker verified.
Accepted and archived; no remaining Wi-Fi Settings work.
Complete: operator accepted ordinary/video card behavior; unperformed timing preserved in Planned interaction-jank followup.
Completed: operator accepted continuous real-finger card interaction; existing probe collection and restoration evidence retained.
Closed on operator acceptance; see evidence for waived captures and retained limits.
Closed on operator acceptance; see evidence for waived captures and retained limits.
Closed on operator acceptance; see evidence for waived captures and retained limits.
Review the archived record and cited scope
Review the archived record and cited scope
Review the archived record and cited scope
Archived after matching-system installation and operator acceptance of the rounded cards.
Review the archived record and cited scope
Review the archived record and cited scope
Review the archived record and cited scope
Review the archived record and cited scope
Review the archived record and cited scope
Review the archived record and cited scope
Review the archived record and cited scope
Review the archived record and cited scope
Review the archived record and cited scope
Review the archived record and cited scope
Review the archived record and cited scope
Review the archived record and cited scope
Review the archived record and cited scope
Review the archived record and cited scope
Review the archived record and cited scope
Review the archived record and cited scope
Review the archived record and cited scope
Power the board with a known-good data cable and capture the console. Verify by committing docs/evidence/stage1-from-source.txt containing the PMU Major Msg: training sequence and U-Boot 2022.10 from a…
Review the archived record and cited scope
Draft proposal · Planned
Snapshot 5836ef1d113d · 2026-10-17 08:22 UTC
Next gateConsume the separate static splash-to-Linux repair result as a prerequisite and record its before/after physical evidence; verify the prior wrapped/color-swapped first-modeset case is absent before…
KEEP, QUEUED behind the current shell, theme, and power-key work, per the
user’s “stale as suggested” decision on docs/closeout/stale-triage.md. No
task here is being actively picked up while that work is in flight; see the
“Decisions” section of the triage doc.
The current splash handoff preserves a static image into Linux, but the first Sway modeset still produces incorrect physical geometry and colors. Once that blocking defect is fixed, a computational Game of Life gives the boot display a small, meaningful workload and a visible transition into the shell without promising uninterrupted animation during kernel startup.
runtime/boot-game-of-life: A deterministic shared boot animation with bounded state handoff and touch interaction.The change affects the source-built vendor-derived U-Boot display path, Linux early userspace or kernel handoff, reserved RAM ownership, and optionally the Wayland shell. It must not depend on the unproven second RISC-V core. The host can test the pure C engine and deterministic images; the physical board is required for panel handoff, touch, RAM reservation, and boot timing evidence. Host checks establish only their stated software claims; physical handoff and touch tasks require separately recorded board evidence.
The latest splash handoff evidence shows that stage 1 can keep a static logo
visible to the Linux prompt, while the first Sway modeset still has physical
wrap and color defects. Read-only VO/DSI comparison is now possible, but the
observed register difference does not establish the cause. See
docs/evidence/boot-splash-handoff.md. This proposal therefore treats the
static handoff repair as a prerequisite rather than hiding it inside the
animation work.
Goals:
Non-Goals:
Use a small versioned state record in reserved RAM. The record is owned by the boot display contract and has a magic value, ABI version, byte length, boot-instance marker, generation, seed, dimensions, and checksum. It carries only same-boot transient state and is invalidated on incompatible version or bad checksum. The exact reserved address must come from the existing memory map; no new unverified RAM claim is accepted.
Share rules and frame encoding, not platform display code. The C engine owns cell updates, deterministic seed expansion, glider insertion, and a compact frame representation. U-Boot and Linux retain their existing panel/VO and DRM renderers. This separates simulation correctness from the unresolved physical handoff registers.
Stop and restart around ownership boundaries. U-Boot may render successive frames while it owns the panel. It stops before Linux takes control; Linux may resume from the record after its display path is ready. The design records the pause instead of adding unsafe concurrent writers or claiming seamless motion.
Use deterministic defaults. A fixed build-time pattern and seed make host images and recovery boots comparable. Any user interaction is transient and same-boot only; it never changes the fresh-home defaults.
Treat touch in layers. Linux touch dropping a glider is the first required interaction. U-Boot touch is an optional later investigation that may require porting Goodix input into U-Boot using the existing Linux driver as a reference, with separate evidence and no dependency on it. Wayland continuation is optional and must preserve the existing shell controls.
First repair and verify the static splash handoff. Then add the host-tested engine and state ABI behind a disabled or opt-in image path, verify deterministic frames without hardware, and only then run the board experiment. Rollback is removing the animation path and restoring the current static/no-logo boot; no home data or persistent user state is involved.
Queued by user decision (2026-09-28): this whole change stays open but
unstarted behind the current shell, theme, and power-key work — see
Status (2026-09-28) in proposal.md. No task below is deferred
individually; the entire change is sequenced after that work lands.
cc -std=c11 -Wall -Wextra -Werror -I src tests/test_game_of_life.c src/game_of_life.c -o /tmp/test-game-of-life && /tmp/test-game-of-life and retain the test output under docs/evidence/game-of-life/host-engine.txt.tools/check-boot-life-memory.py to decompile the DTB with dtc, read the reserved-memory node, collect U-Boot load/relocation addresses and kernel/initrd ranges, and reject overlapping intervals; verify its report in docs/evidence/game-of-life/memory-map.txt.nix build --no-link --print-out-paths .#uboot-k230 --option max-jobs 1 --option cores 1 and retain a state dump under docs/evidence/game-of-life/uboot-state-host.txt; physical U-Boot rendering remains a separate board check.openspec validate --type change the-boot-shows-a-computational-game-of-life --strict; verify all three outputs are attached to the evidence directory and that no physical U-Boot or touch task is marked complete without board evidence.Provides a deterministic computational boot animation that can hand a bounded simulation state from stage 1 to Linux and optionally continue in the shell.
Stage 1 and Linux SHALL use the same portable C simulation rules and a versioned state layout. A fresh boot SHALL render the same default pattern for the same build and seed. Transient state MAY be carried between owners during one boot, but the system SHALL NOT store the simulation or seed in a home directory or use it as a cross-boot backup.
The Game of Life feature SHALL remain disabled or non-accepted until the known static splash-to-Linux handoff has correct physical geometry and colors. The feature SHALL document that U-Boot-to-Linux ownership can include a visible pause while Linux initializes; it SHALL NOT promise uninterrupted motion during kernel boot.
After Linux owns a working touch-enabled renderer, a touch at a valid board location SHALL add a glider or equivalent documented pattern and SHALL leave the simulation usable when the touch device is absent. Physical touch proof is UNVERIFIED until recorded on the board.
U-Boot MAY accept touch input through a separately investigated port into U-Boot, using the existing Linux Goodix driver as a reference, only as an explicit optional path. It SHALL not be required for the shared state contract, Linux handoff, or acceptance of the default animation.
A Wayland continuation MAY animate the simulation after Sway starts, but it SHALL use the existing shell ownership and SHALL not hide Apps, Keyboard, Windows/Home, System, or recovery controls. The continuation SHALL be independently labelled from stage-1 and early-Linux evidence.
Draft proposal · Planned
Snapshot 5836ef1d113d · 2026-10-17 08:22 UTC
Next gateWhen a slow interaction is reported, measure that workload; deferred drawer/keyboard timing is not a blocker on accepted UX.
The operator accepts the drawer, keyboard and ordinary-card behavior, but unrelated unperformed performance measurements keep their proposals open. Investigate reported slow interactions when they arise, while preserving the exact deferred checks.
None.
runtime/shell: report drawer frame cost and ground reported slow interaction
analysis in measured installed-board results. The drawer timing requirement is
transferred here before its parent’s archive; it is not dropped.Userspace Rust shell/compositor instrumentation and evidence only. No kernel, boot, device tree or radio work. This is planned backlog, not active optimization.
The operator said the drawer seems fine and asked to spend performance effort when slow behavior arises. Keyboard gestures and ordinary-card/video behavior are also accepted. The archived functional closeouts must not claim measurements they never performed.
Preserve pending quantitative obligations without tying accepted UX to a new benchmark campaign. Do not reopen accepted navigation or optimize speculatively.
Userspace: retain existing bounded timing instrumentation. Start with the
reported route/workload and exact installed Rust/compositor/system identities.
For drawer sustained scrolling, read K230_DRAWER_FRAME ms= from the process
journal; compare it with the review’s unverified 17.3–34.6 ms estimate and ~20 ms
target. Client paint timing alone is not a presentation or finger-latency result.
For keyboard show/hold/reverse/hide, use installed compositor instrumentation
and the already-defined shell responsiveness budgets; preserve failures as
failures. Static images do not demonstrate motion timing.
For ordinary cards, retain the sub-400ms entry-animation and sub-100ms touch-ack targets from the-card-shell-has-no-video-special-case task 5.1. The earlier per-event subprocess injector did not establish either target. Use real contact with instrumentation or a held uinput device, record installed identities, and distinguish input acknowledgement, presentation and optical latency.
Conditional optimization: if a measured drawer bottleneck justifies it, propose
scroll-direction damage-limited blitting from docs/design/app-drawer-review.md
section 6, with measured before/after proof. Otherwise document that no change
was justified. Reject unconditional tuning merely to empty a checklist.
A retained estimate could be mistaken for proof → mark quantitative claims UNVERIFIED and record exact workload, identity and limitations with results.
Land this successor before archiving its parents. Keep it planned until a slow interaction is reported or the user specifically requests measurements. Reserve board/build resources only when actually executing its tasks. Any code change gets its own qualified candidate and recovery path.
docs/evidence/interaction-jank/. Proof: the named report and python3 tools/console.py /dev/ttyACM0 --wait=3 'readlink -f /run/current-system' under the board reservation. Do not start solely to reconfirm accepted UX.K230_DRAWER_FRAME ms= with python3 tools/console.py /dev/ttyACM0 --wait=3 'journalctl -u shell-ui --since "2 minutes ago" --no-pager | rg K230_DRAWER_FRAME'; commit the sustained workload and samples, compare the 17.3–34.6 ms estimate and ~20 ms target. This is render-cost measurement, not inferred presentation timing.docs/design/app-drawer-review.md section 6; otherwise record why it is unnecessary. Proof: the recorded measured decision and openspec validate --all --strict. This preserves parent 5.4 without claiming an optimization already happened.docs/evidence/interaction-jank/. Use python3 tools/console.py /dev/ttyACM0 --wait=3 for the documented installed probe; static images cannot establish timing. Keep open until actual measurements exist.evemu-event process spawns; record concrete instrumentation command, exact identities and samples under docs/evidence/interaction-jank/. Existing qualitative acceptance is not measured performance. Keep both targets UNVERIFIED until actual samples establish them.openspec validate the-shell-profiles-reported-interaction-jank --strict, commit measured results/decision, push and inspect matching CI/Pages; archive only once performed measurements and conditional disposition are committed. Parent UX acceptance is not this proposal’s performance proof.Whenever the app drawer route renders a frame, the userspace shell SHALL be able to report that frame’s render duration in milliseconds through its existing log/journal output, at a bounded rate that does not flood the journal during sustained scroll or fling. The 17.3–34.6 ms estimate and ~20 ms target SHALL remain unmeasured until a recorded installed-board workload grounds them.
K230_DRAWER_FRAME ms= line appears at least once every few hundred milliseconds, reporting that frame’s own render durationWhen investigating a reported slow interaction, the userspace shell’s analysis SHALL name the workload and installed identities and compare measured results with the applicable existing shell responsiveness budgets. Keyboard visibility, held/reversed drag and release settlement, and ordinary-card sub-400ms entry and sub-100ms touch acknowledgement SHALL remain pending measurement; static captures and qualitative acceptance SHALL NOT substitute for those results. A failed budget SHALL remain a failed budget. Drawer damage-limited blitting SHALL be proposed only if measurement justifies that next change.
Draft proposal · Planned
Snapshot 5836ef1d113d · 2026-10-17 08:22 UTC
Next gateConfirm the known-good image hash, serial device, J3 data cable, J2 console cable, and host USB logging commands.
KEEP, per the user’s “stale as suggested” decision on
docs/closeout/stale-triage.md. Schedule one short board session for task
group 2 (the two power-cycle observations over J3: card removed, and
SW3/BOOT0 held). The optional destructive card-corruption test in task group
3 is skipped for now — see the note on that task group below; it is not
withdrawn, only deferred, and remains conditional on task group 2’s result if
it is picked up later.
The completed U-Boot UMS change proves that a running stage 1 can expose the SD card over USB. It does not prove the independent BootROM recovery path used when the card has no bootable stage 1. The original proposal carried those unperformed tests alongside completed UMS work; this successor keeps the recovery promise explicit and testable without implying that UMS evidence is BootROM evidence.
k230_flash tool by writing
a disposable deliberately nonbootable-stage1 card and verify that the board
boots afterward. An unsafe or unattempted write remains incomplete; it is
not converted into a success claim. If entry does not work, document the
observed limit and retain the card-reader and UMS recovery procedures.image/boot-chain requirement and evidence links after the
hardware result. Never remove an UNVERIFIED marker before the corresponding
observation exists.image/boot-chain — separates observed BootROM recovery from the already
proven U-Boot UMS path and records the exact recovery procedure or failure.Hardware-only characterization, evidence files, and OpenSpec grounding. No firmware, kernel, flake, or automatic boot behavior changes are required before an observed recovery path justifies them.
The negative-result boundary is explicit: absence of a device is a grounded limitation only after both power-cycle tests are captured; a missing or unsafe write leaves recovery verification incomplete.
The board’s data connector J3 is the U-Boot UMS connector. The charging
connector J2 carries the CH342 console bridge. Existing UMS evidence identifies
VID 29f1, PID 0230, but that is evidence from a running U-Boot gadget and
cannot establish what the BootROM does before stage 1. SW3 is wired to BOOT0.
No BootROM test is currently claimed.
Goals:
Non-Goals:
lsusb, kernel hotplug logs, serial output, and timestamps together../tools/console.py /dev/ttyACM0 --wait=3 "uname -a" for the running-system baseline, power off, remove the TF card, power through J3, and capture lsusb -d 29f1:0230 -v, dmesg --since ..., and serial output; record whether a BootROM device appears.lsusb -d 29f1:0230 -v, dmesg --since ..., and passive serial capture; record whether a BootROM device appears.Deferred by user decision (2026-09-28): the optional destructive
card-corruption test below is skipped for now — see Status (2026-09-28) in
proposal.md and the “Decisions” section of docs/closeout/stale-triage.md.
Task group 2 (the board session) remains authorized; this group stays open
and conditional, not ticked, and is not scheduled alongside it.
k230_flash source/tool version and inspect its help and target-selection behavior.docs/evidence/ without rewriting failed attempts into success.image/boot-chain requirement grounding and preserve an explicit limitation when BootROM recovery is unavailable.openspec validate --all and the site/docs checks; review that UMS and BootROM claims remain distinct.Whether this board can be recovered over USB with no bootloader on the card SHALL be established by observation and written down, including no-card entry, SW3/BOOT0 entry, host enumeration, and the tool or explicit reason recovery is unavailable. The result SHALL distinguish BootROM recovery from U-Boot UMS and shall not claim success from UMS evidence alone.
Grounding for the test target: docs/uboot-ums.md §5 describes Canaan’s
do_k230_dfu() path and the kendryte/k230_flash_py host tool; the schematic
places SW3 between BOOT0 and ground. These sources identify what must be tested
but do not establish that this board enters BootROM recovery.
k230_flash procedure writes the known-good image onto a disposable card whose stage 1 was deliberately made nonbootable and a later boot verifies the result; an unsafe or unattempted write leaves this scenario incomplete and is recorded as suchDraft proposal · Planned
Snapshot 5836ef1d113d · 2026-10-17 08:22 UTC
Next gateUnder the reserved board lock, install the built kernel to /boot
the-handheld-talks-bluetooth enabled the kernel Bluetooth stack
(CONFIG_BT, CONFIG_BT_HCIBTUSB, CONFIG_BT_HCIBTUSB_RTL) and BlueZ
(hardware.bluetooth.enable), with every task proven except one: task 4.1,
plugging in a real USB Bluetooth dongle and confirming lsusb,
bluetoothctl show, bluetoothctl scan on and btmgmt info all report a
live controller. That task cannot be performed because this project does
not currently own a USB Bluetooth dongle. docs/research/bluetooth-onboard.md
independently confirms this board has no on-board Bluetooth radio of any
kind — the RTL8188F Wi-Fi chip on this board is a Wi-Fi-only part, not the
combo RTL8723D, and the optional nRF52840 accessory base offers BLE only
through a proprietary bridge, not a Linux HCI controller — so a USB dongle
is the only path to Bluetooth on this hardware, not one option among
several.
This is a scope split, not new work: it exists so the-handheld-talks-bluetooth
can close on its own finished software scope (kernel config + BlueZ, both
already build-proven) without silently dropping the one requirement that
needs hardware this project does not yet have. Nothing here is authorized
to run yet — this proposal stages the successor and its preserved task so a
future coordinator with a dongle in hand can execute it and archive this
change, and so the parent can be archived once this split is authorized.
the-handheld-talks-bluetooth task 4.1: install
the built kernel, reboot, plug in a USB Bluetooth dongle, and confirm
lsusb, bluetoothctl show, bluetoothctl scan on (10 s) and
btmgmt info all report a live, powered controller. Commit sanitized
console output (no MAC addresses or SSIDs of nearby devices) under
docs/evidence/bluetooth/.docs/evidence/backlight-bluetooth-rtc-board-test-plan.md section 3,
including its documented LILYGO-quirk failure mode (dongle enumerates on
USB but btmgmt info never reaches powered/running) and its remedy
(LILYGO’s 0056/0057-bluetooth-btusb-*.patch quirks, not ported
speculatively per the-handheld-talks-bluetooth’s design.md decision 1).<!-- UNVERIFIED --> marker on radio/bluetooth’s “The
kernel and BlueZ can drive a USB Bluetooth controller” requirement once
the board test passes, or restate the requirement against what was
actually observed if the quirk patches turn out to be needed.Non-goals: re-doing any of the kernel/NixOS/BlueZ work the-handheld-talks-bluetooth
already did and proved by build — this change touches no Kconfig, no Nix
module, and no device tree. A Settings status row remains out of scope here
too, per that change’s own “Bluetooth status is not yet in the shell UI”
requirement, unchanged.
radio/bluetooth: resolves the <!-- UNVERIFIED --> marker on “The
kernel and BlueZ can drive a USB Bluetooth controller” with an actual
board observation against a physical dongle, once one is available.No source changes. This is a board-verification-only change: it needs a
USB Bluetooth dongle (LILYGO’s bundled kit ships a CSR8510-clone,
0a12:0001, but any HCI-compliant USB dongle proves the same requirement)
and the reserved board/serial port. the-handheld-talks-bluetooth remains
open, with task 4.1 pointing here, until a coordinator authorizes this
split; only then does the parent archive its finished kernel/BlueZ scope
and this change carries the remaining hardware gate forward.
the-handheld-talks-bluetooth finished and build-proved everything except
one hardware-only gate: a real USB Bluetooth dongle plugged into the board.
This project does not own one, and docs/research/bluetooth-onboard.md
already established this board has no on-board Bluetooth radio at all (the
Wi-Fi part is the Wi-Fi-only RTL8188F, not the combo RTL8723D, and the
nRF52840 accessory base’s BLE is a proprietary bridge, not a Linux HCI
controller). A dongle is therefore the only way this capability can ever be
observed on this hardware, not a nice-to-have verification path among
several. See the-handheld-talks-bluetooth/design.md for the kernel/BlueZ
decisions this change does not revisit.
Goals: get a real, HCI-compliant USB Bluetooth dongle onto the board and
resolve the <!-- UNVERIFIED --> marker on radio/bluetooth’s controller
requirement with an actual lsusb/bluetoothctl/btmgmt observation.
Non-Goals: any kernel, NixOS or device-tree change (none is needed; the
parent already did this work and proved it by build); a Settings UI status
row (explicitly out of scope in the parent, unchanged here); porting
LILYGO’s 0056/0057 btusb quirk patches speculatively — only if the
board test actually exhibits the quirk.
docs/evidence/backlight-bluetooth-rtc-board-test-plan.md section 3,
including its documented LILYGO-quirk failure signature, rather than
inventing a new procedure.Not applicable — no source or schema changes.
0a12:0001) hits the
LILYGO-quirk failure mode on this specific board is unknown until task 1
runs; if it does, porting the two named quirk patches is a further
follow-up, not part of this change’s own task list.the-handheld-talks-bluetooth task 4.1)/boot
and reboot (a Kconfig-only kernel change does not take effect from a
plain system activation). Confirm the new kernel is running before
judging anything below:
flock -w 120 /tmp/k230-board.lock python3 tools/console.py /dev/ttyACM0 --wait=3 "uname -a".0a12:0001; any HCI-compliant dongle proves the same requirement).
Run, over the reserved serial console:
python3 tools/console.py /dev/ttyACM0 --wait=2 "lsusb",
python3 tools/console.py /dev/ttyACM0 --wait=3 "bluetoothctl show",
python3 tools/console.py /dev/ttyACM0 --wait=12 "bluetoothctl scan on",
python3 tools/console.py /dev/ttyACM0 --wait=3 "btmgmt info".
Follow docs/evidence/backlight-bluetooth-rtc-board-test-plan.md
section 3 for expected output and failure signatures, including the
LILYGO-quirk failure mode (dongle enumerates but never reaches
powered/running).docs/evidence/bluetooth/, naming which of the
documented outcomes was observed. If the LILYGO quirk is hit, record
it and treat porting 0056/0057-bluetooth-btusb-*.patch as a
further follow-up rather than blocking this task’s own recording of
what was actually observed.radio/bluetooth’s “The kernel and BlueZ can drive a USB
Bluetooth controller” requirement: resolve its <!-- UNVERIFIED -->
marker against the board observation from task group 1, or restate it
to match what was actually observed if a quirk patch was needed.openspec validate the-handheld-pairs-over-a-usb-bluetooth-dongle --strict
and python3 scripts/render_work_board.py > /dev/null, then archive
and sync the radio/bluetooth delta, commit and push.Proof: the committed console transcript under docs/evidence/bluetooth/ is
the only evidence this change can produce; there is no host or QEMU
substitute (QEMU’s k230 machine models no USB host controller at all).
The system SHALL build the Bluetooth core (CONFIG_BT) and the USB HCI
driver (CONFIG_BT_HCIBTUSB) into the kernel, with Realtek protocol
support (CONFIG_BT_HCIBTUSB_RTL) for the CSR8510-clone dongle
(0a12:0001) this project’s accessory kit bundles, and SHALL run BlueZ via
hardware.bluetooth.enable. No device-tree change is required.
Grounding: net/bluetooth/Kconfig and drivers/bluetooth/Kconfig in the
pinned Xuantie kernel tree already carry BT, BT_HCIBTUSB and
BT_HCIBTUSB_RTL with no K230-specific blocker; nix/kernel.nix’s
structuredExtraConfig now sets these symbols, proven by
nix build .#kernel. Both DWC2 USB controllers are already
status = "okay" in nix/dts/k230-tdisplay.dts; USB Bluetooth binds on
the USB bus, not a device-tree node.
lsusb shows the device and bluetoothctl show reports a
controllerbluetoothctl scan on with a controller presentbtmgmt info is checkedbtmgmt info with the dongle attachedDraft proposal · In progress
Snapshot 5836ef1d113d · 2026-10-17 08:22 UTC
Next gateOn the reserved board, run
A person choosing a background today gets exactly one placement (a centered
cover-crop) and exactly one media kind (a still image) — regardless of what
the active theme or their own overlay would actually look like fit,
letterboxed, or as a muted video. the-shell-loads-omarchy-themes’s own
task 4.1 asked for “crop/fit/fill/center/solid choices” and “user overlays,”
and task 4.3 asked for “bounded muted video backgrounds”; neither shipped.
nix/rust-shell-client/src/background_decode.rs already implements
FitMode::Crop/Fit/Center, but every call site
(theme_thumbnails.rs, main.rs, theme_ui.rs) hardcodes FitMode::Crop
— nothing lets a person choose, Fill/Solid don’t exist at all, and there
is no video decode path (the module’s own doc comment says so outright).
This is a scope split under AGENTS.md’s “Close OpenSpec changes
deliberately”: the-shell-loads-omarchy-themes is otherwise close to done
(the closeout audit dated 2026-09-28 found the coordinator, activation,
transaction, keyboard and app-appearance adapters implemented and
host-tested, with the daily-use dark/light/community theme cases already
proved on the board). Background presentation is real, separable,
substantially-sized feature work — not a rounding error, and not something
that should either block that change’s remaining board gates or tempt
someone into ticking 4.1/4.3 against partial delivery.
background_decode.rs’s existing place() with two more
variants: Fill (cover the full canvas without preserving aspect ratio —
distinct from Crop, which preserves it) and Solid (an explicit flat
color, for a theme or a person who wants no image at all). Crop/Fit/
Center are unchanged.tools/theme_preferences.py already persists a background choice
(source-relative, hash-keyed, bounded). No new palette format, no new
activation path, no new build slot.theme_activate.py already bounds a theme’s own
MAX_ASSET/MAX_TOTAL staged assets, discovered alongside a theme’s
bundled choices rather than replacing them.Crop
fallback on any decode failure, and reduced-motion behavior (no video
autoplay when the system’s reduced-motion setting is active — the same
flag protocol.rs/service_ui.rs already thread through for animation
duration). Performance is a physical gate: this proposal does not enable
video by default until the reserved-board workload (task group 3 below)
passes the existing card CPU/frame budgets.Non-goals: a general-purpose image editor or crop tool (fit modes are a
fixed enum, not a draggable crop rectangle); animated GIF backgrounds
(STILLS already excludes them from theme_activate.py’s asset
recognition; out of scope here); changing what counts as a still versus a
video (tools/theme_activate.py’s existing STILLS/VIDEOS suffix sets
are reused unchanged); redesigning the chooser UI itself
(nix/rust-shell-client/src/theme_ui.rs’s carousel and tap-to-apply model,
from the sibling change, are unchanged — this only adds a fit-mode/overlay
affordance to the existing background row).
None. This targets the same runtime/shell-themes capability
the-shell-loads-omarchy-themes already proposed. Neither change has
archived, so openspec/specs/runtime/shell-themes/ does not exist yet;
this change’s own delta therefore also uses ADDED Requirements, scoped to
exactly the fit-mode/overlay/video scope this proposal implements, rather
than restating the parent’s broader requirement. Whichever of the sibling
proposals for this capability archives first fixes the base spec; the
others then sync against it normally.
nix/rust-shell-client/src/background_decode.rs (new FitMode variants,
video decode path), theme_carousel.rs/theme_ui.rs/main.rs (fit-mode
selection wiring, all three currently hardcode Crop), tools/theme_activate.py
(overlay staging, video format diagnostics surfaced in the compatibility
report), tools/theme_preferences.py (persist a fit-mode choice alongside
the existing background choice), and a new nix build .#handheld-wallpaper
isolated output for the video decode path specifically, so it can be built
and evaluated for cost independently of the rest of the theme package.
Host-provable: fit-mode placement math, overlay staging/bounds, and video
format diagnostics all need no board. Whether video playback actually meets
this project’s existing card CPU/frame budgets, and whether any fit mode
reads correctly on the panel, still needs the reserved board — this
proposal does not claim that gate closed by construction, and does not
enable video backgrounds by default until it passes.
background_decode.rs already has a FitMode enum with Crop, Fit and
Center variants and a working place() function for each, built while
implementing bundled-theme background support. It was never wired to a
user-facing choice: theme_thumbnails.rs, main.rs and theme_ui.rs each
call render/render_uncached with FitMode::Crop hardcoded. Video
backgrounds were scoped in the original the-shell-loads-omarchy-themes
proposal (task 4.3) but never started — the module’s own doc comment
states plainly that it does not decode video.
Crop,
Fit, Center, and two new modes: Fill, Solid), and that choice
persists the same way the background choice itself already does.Fill stretches the source to exactly cover the canvas without
preserving aspect ratio (distinct from Crop’s aspect-preserving cover
and Fit’s aspect-preserving letterbox). Solid ignores the source
entirely and paints a single resolved color (from the active theme’s own
palette, or an explicit choice) — useful for a person who wants a
background role satisfied with no image at all, and as the documented
fallback if a chosen image or video becomes unavailable.theme_preferences.py’s
existing bounded, hash-keyed, per-source store (MAX_CHOICES = 256) —
this proposal only widens what one entry can record, not the storage
model.background_decode.rs, built as its own isolated flake output
(handheld-wallpaper) precisely so its cost (decoder linkage, memory,
CPU) can be measured and gated independently of the rest of the theme
package, per this project’s own “Performance remains a physical gate”
convention (the-shell-loads-omarchy-themes task 4.3’s own wording).
Decode failures (recognized suffix, undecodable content; corrupt
container; codec this project does not carry) are named diagnostics in
the compatibility report, not crashes, and fall back to a still frame or
Crop of the theme’s own paired still, per the parent task’s own
“still fallback” requirement.reduced_motion_enabled in
main.rs; existing surface-visibility bookkeeping for the wallpaper
layer) rather than inventing new ones.docs/evidence/omarchy-themes/background-workload-host.md
and tools/handheld-theme-trial.py --workload backgrounds’s existing
video arm, which today reports “the installed Rust wallpaper client…
still rejects video”) passes the same card CPU/frame budgets the rest of
this project holds itself to.tools/theme_sources.py) that task 1.4 of the parent change already hit
a real bug in once (a build-time sibling file inside a theme’s own
directory silently changing every generation identity). Any new staged
path added here must live outside a theme’s own content-hashed tree, the
same lesson that bug already taught.None — additive. Existing generations with no recorded fit-mode choice
default to today’s behavior (Crop), so nothing already committed changes
appearance.
Solid always paints the active generation’s resolved background
palette role — the same role RendererCache::draw_wallpaper already uses
as a theme’s base colour — so a dark theme gets its dark base and a light
theme its light base with nothing for a person to configure, it needs no
new persisted value (the generation’s report.json already carries the
palette), and it works for a theme that ships no background asset at all.
background_decode::FitMode::Solid takes a resolved RGBA colour; the shell
resolves it in appearance::generation_wallpaper_fit. Rejected: an
explicit per-person colour (a picker plus a new stored, validated colour
for a case the palette already answers; it can be added later as another
FitMode argument without changing the stored fit name) and the accent
role (reads as a highlight, not a backdrop; poor contrast under icons).Fill is a stretch, not a cover-crop. The proposal and this document
define Fill as aspect-distorting and Crop as the aspect-preserving
cover; the spec delta’s first draft described fill as cover-and-crop,
which is crop. The delta now says what Fill does here (stretch, no
crop, no letterbox).background-selections.json as an optional fits table
keyed the same way (crop, the default, is never stored; version stays 1
and files written before this change read as crop). It is not keyed per
individual background image: the existing store has one entry per source
and the chooser applies one placement to the active background.report.json), added to the identity hash only when
it is not crop, so every existing generation keeps its identity. The
wallpaper background.cache is the Crop decode, so it is only built for
crop; another mode is a cache miss and a full decode. The shell reads
fit_mode from the generation’s report.json (absent means crop).ThemeRequest::Fit, a preview-then-activate pair
like a background change, through the existing helper protocol
(--fit/"fit").~/.config/omarchy/backgrounds, --overlays to override), are staged
into the generation as backgrounds/user-<name> so the existing selection,
preference and Rust loader paths accept them unchanged, and are bounded:
regular files only (no symlinks), STILLS | VIDEOS suffixes, a safe file
name, each at most MAX_ASSET, at most 32 files and MAX_TOTAL / 2 bytes
together. A bad overlay is a line in the report’s unknown list, never a
failed activation; a name that collides with a theme’s own asset loses to
the theme. They stay out of the theme’s content-hashed tree; the staged set
enters the generation identity as a stat-only fingerprint (name, size,
mtime), added only when overlays exist.All tasks are initially open. Commands naming new tools, tests or flake
outputs below are planned interfaces, to be added by that task before
invocation; they are not claims those interfaces exist or have passed
today. Host, cross-build and physical proof are separate. Store committed
results under docs/evidence/omarchy-themes/ with revisions, commands and
limitations, per this project’s own convention.
FitMode::Fill/FitMode::Solid to
background_decode.rs::place() alongside the existing Crop/Fit/
Center; Solid takes a resolved RGBA color and ignores the source
image entirely. Verify with new cargo test --offline --lib background_decode cases covering aspect-distorting fill and a solid-color
canvas at several sizes.
Proof (host, 2026-10-16): cargo test --offline --manifest-path nix/rust-shell-client/Cargo.toml --test background_decode_module — 11
passed, including fill_stretches_without_letterbox_or_crop_and_differs_from_crop,
solid_paints_one_colour_and_never_opens_the_source (four sizes up to
568x1232, missing source file, bound and cache-key checks) and
fit_mode_names_round_trip_and_cycle. (The module’s tests live in
tests/background_decode_module.rs, not --lib.)theme_carousel.rs/
theme_ui.rs/main.rs (today all three hardcode FitMode::Crop) through
to render/render_uncached, and persist it in
tools/theme_preferences.py’s existing bounded per-source store
(extend, do not replace, its schema). Verify with
cargo test --offline --lib theme_ui and
python3 -m unittest tests.test_theme_preferences.
Proof (host, 2026-10-16): cargo test --offline --lib theme_ui — 46
passed (cycle fit preview-then-activate, failure keeps the old fit, theme or
background tap supersedes a fit change, heading hit target, report.json
read-back, FIT_NAMES pinned to FitMode::NAMES); --test theme_catalog_module 7 passed (the Fit request sends fit through the
helper socket in both steps; an unknown mode never reaches it); --test appearance_module 15 passed (generation_wallpaper_fit); python3 -m unittest tests.test_theme_preferences — 15 passed (fit remembered per
source, changes the generation, crop identity unchanged, rollback with a
rejected ack, corrupt fits fails closed, pre-fit files read as crop);
tests.test_theme_catalog and tests.test_theme_helper_daemon also pass
with --fit/--overlays. Full run: cargo test --offline --manifest-path nix/rust-shell-client/Cargo.toml --no-fail-fast — every target ok,
including responsive_pixel_identity (portrait renders byte-identical).
Host evidence: docs/evidence/omarchy-themes/background-fit-modes-host/
(one dark and one light theme, all five modes). Not a panel capture.design.md (does Solid derive from
the active palette or take an explicit color) and implement accordingly.
Decided 2026-10-16: Solid takes the active generation’s resolved
background palette role; no picker. Recorded in design.md (“Resolved
Questions”); verified by the appearance_module and
background_decode_module tests above.Proof: the named host/cargo tests above. No device claim.
tools/theme_activate.py, bounded and discovered the same way a theme’s
own assets already are (reuse MAX_ASSET/MAX_TOTAL, STILLS/VIDEOS
suffix sets); an overlay lives outside any theme’s own content-hashed
tree (see design.md’s own risk note on generation-identity hashing).
Verify with python3 -m unittest tests.test_omarchy_theme_activation
(new cases for overlay staging/bounds/rejection).
Proof (host, 2026-10-16): python3 -m unittest tests.test_omarchy_theme_activation — 21 passed, including the new
UserOverlays cases: listing/staging/selection beside a theme’s own,
outside the hashed theme tree, an edit or addition makes a new generation,
unsupported/unsafe/oversized/symlinked/non-regular rejection without failing
activation, count and total bounds, theme-name collision, symlinked
directory ignored, remembered overlay choice and its removal diagnostic.background_decode.rs behind
its own isolated flake output, nix build .#handheld-wallpaper; format
diagnostics for a recognized-suffix-but-undecodable file surface as a
named compatibility-report entry, never a crash. Verify with
cargo test --offline for the new decode module and
nix build .#handheld-wallpaper --no-link --print-out-paths.
Reconciled 2026-10-17 (audit: docs/evidence/omarchy-themes/background-video-audit.md).
The decode already shipped in 68badde1 as video_wallpaper.rs (not
background_decode.rs). Added: the handheld-wallpaper output
(nix/handheld-wallpaper.nix) — the minimal ffmpeg/ffprobe pair the decoder
child runs, NOT a separate Rust crate (the decode module shares the shell
crate’s types; the audit explains why) — and the named report entry
(theme_activate.video_diagnostic, a line in the report’s unavailable
list using the decoder’s own category, for theme assets and user overlays).
Proof (host, 2026-10-17): cargo test --offline --manifest-path nix/rust-shell-client/Cargo.toml --tests — all targets ok (lib 575, bin 23,
appearance_module 16, new video_wallpaper_module 5); python3 -m unittest tests.test_omarchy_theme_activation — 21 ok; python3 tests/test_handheld_theme_backgrounds.py --video — 11 run, 3 board-only
skips; flock /tmp/k230-nix-build.lock nix build .#handheld-wallpaper --no-link --print-out-paths --max-jobs 1 --cores 4 -> /nix/store/fg79cz66dpqhrhm6xf0rcjy3h5c0wqz5-handheld-wallpaper
(cross-build only; decodes nothing). Codec check at report time runs only
when the helper’s environment names an absolute K230_WALLPAPER_FFPROBE
play time names the same category.reduced_motion_enabled), plus a still-frame or FitMode::Crop
fallback of the theme’s own paired still on any decode failure. Verify
with a new tests/test_handheld_theme_backgrounds.py --video (the file
this scope’s parent task named but never created) covering lifecycle,
pause/resume, reduced-motion and every failure case named above.
Audited 2026-10-17: the behaviours already existed (video_visibility.rs,
main.rs, video_wallpaper.rs); added the single should_decode
predicate at all five gates, appearance::fallback_still, the stand-in
decoder lifecycle/failure tests and the test file. Proof (host,
2026-10-17): python3 tests/test_handheld_theme_backgrounds.py --video —
OK (11 run, 3 skipped): decoder start/stop/restart reaps the child, every
failure category, the pause predicate, the still fallback, a real host-ffmpeg
decode of two distinct frames, and the compatibility-report cases. The three
skips are board-only and stay under 3.3: the compositor’s real cover signal
end to end, the live reduced-motion setting (read once at shell start;Proof: the named host/cargo tests and the isolated handheld-wallpaper
build. Video suffix recognition or a first frame is not playback/
performance acceptance.
nix build .#nixosConfigurations.k230-coherent-shell.config.system.build.toplevel)
before any board time; record exact closure and source identities.
Done 2026-10-16 (host build, after the board runs): master 64481159 →
zjdyp4mv…-nixos-system-…, 1183 paths; see
docs/evidence/omarchy-themes/background-fit-modes-board/full-closure-2026-10-16.md.grim captures for at least one dark
and one light theme.
Done 2026-10-16 with injected input on HDMI: all five modes on retro-82
(dark) and catppuccin-latte (light), each captured by grim on Home, plus a
shell-restart persistence check (docs/evidence/omarchy-themes/background-fit-modes-board/README.md).tools/handheld-theme-trial.py --workload backgrounds against a paired
static and video background; record combined CPU, RSS, decode/
presentation cost and card input/frame budgets, and covered-media pause
and restoration. Compare against this project’s existing card CPU/frame
budgets (the same gate the-shell-swaps-themes-without-a-python-stall
holds itself to). Do not enable video by default in nix/shell.nix until
this passes.docs/evidence/theme-picker/background-selection/README.md
already proved for a bundled choice.
Done 2026-10-16 with injected input on HDMI. The overlay staged as
user-overlay-test.png, applied from the chooser and survived a
shell-ui/theme-helper restart; a symlink and a .txt file were reported
under unknown. The over-256 MiB case was host-only (same README).Proof: the exact recorded build invocation and reserved-board commands above, with committed native captures and the workload’s own sanitized result. No flash or full-image readback is inherently required by this userspace feature.
python3 scripts/build_site.py.openspec validate --all --strict, then inspect the resulting master/CI/Pages revision. Keep this
change open if any required consumer or hardware proof is missing.Proof: openspec validate --all --strict and python3 scripts/build_site.py,
followed by exact-revision CI and published URL inspection.
The system SHALL support crop, fit, center, fill, and solid
background placement modes, selectable the same way the existing modes
already are. fill SHALL stretch the image to exactly cover the panel, ignoring its
aspect ratio, with no letterbox and no crop (crop is the
aspect-preserving cover). solid SHALL show a plain fill color drawn from the active
generation’s resolved background/base palette role for a theme that ships
no background asset. A person SHALL be able to choose a background image
from outside the active theme’s own asset set, bounded the same way an
in-theme background already is (size limit, supported-format check, no path
escape).
fill for a background whose aspect ratio does
not match the panelsolidThe system SHALL play a video-suffixed background from a theme’s own
backgrounds/ directory, muted, bounded, and reusing the same decode path
already justified for another wallpaper surface. It SHALL distinguish an
unsupported codec from a missing or corrupt asset, pause decoding when the
background is fully covered or reduced motion is enabled, and show a still
fallback (the theme’s own preview image, or its first still background)
in either case rather than a blank surface. This inherits the existing
card CPU/frame budgets as a physical performance gate; it is not claimed
closed by a host test alone.
backgrounds/ directory contains
a supported video-suffixed fileDraft proposal · In progress
Snapshot 5836ef1d113d · 2026-10-17 08:22 UTC
Next gateThe operator's judgement on glass that the Clock and each restyled
The shell looks assembled, not designed. The operator said the Home Clock
“could use a redesign” and that its text was too small. The panel captures
under docs/evidence/coherent-shell/accessibility-scale/board/ and
docs/evidence/home-widgets/clock-date/ show the same few problems on every
surface:
board/22) every link,
value and heading action is the same orange: Done, Vision, Themes, the
Wi-Fi arrow. Nothing says which one matters. On the Clock the tracked date
took the accent, while the time, the part that changes, had none.board/23) the
chosen text size is a grey tile with orange text; the other three look
almost the same.render.rs. Section labels are muted body text,
the Battery widget uses tracked capitals, the Clock used tracked capitals
and Settings uses sentence case. A person cannot learn what size or case
means “label”.The Clock is the first and most visible instance, and this change restyles it. The rest becomes a stated visual language so later work lands consistently.
design.md.VisualStyle/AppearanceSnapshot.Host renders prove the layout and the theme behaviour. The restyle’s real
test is the operator’s look at the glass over the wallpaper, so group 5 stays
open until native grim captures and the operator’s judgement exist. QEMU
does not apply.
Layer: userspace only. The work is in nix/rust-shell-client/src/render.rs
(Cairo and Pango on Pixman, CPU rendering on the K230’s 1.6 GHz core) and,
for the card shell, nix/card-shell/. No kernel, device tree or image-level
change.
The panel is a 4.1” AMOLED, 1232x568 landscape (568x1232 portrait), about
2.07 px/dp. Touch targets are at least 99 px. Secondary text is at least
about 26 px (12.5 dp) at 100%. The Vision page offers four text steps and a
high-contrast mode. Home widgets cancel the step in paint_widget_card,
except for the Clock date, which follows it.
Fonts already on the image: DejaVu Sans (FONT_FAMILY) and Inter
(CLOCK_FONT_FAMILY, the static collection with Thin to Black weights).
The shell is a dark glass handheld seen mostly over a wallpaper. It should look like one instrument: quiet surfaces, large clear numerals, and a single bright colour used only for what is live or chosen. Three ideas carry it.
docs/design/clock-widget-research.md (#9) is one accent, used once.bubble_lines is the
one source of this geometry for the painter and the clearance test.hero_glow_run): the hour, a colon at 60% opacity, the minute. Inter
Light, not Thin, because the Thin weight’s hairlines vanish over a
photograph even with the halo.the-clock-widget-date-is-readable. The tracking flag is
gone, since there is no tracking left to drop.draw_layout_halo (8 samples), now also around the accent
minute. Nothing new is drawn per frame, and the clock still redraws once a
minute.Type scale, five roles. Sizes are design pixels at 100%, before the Vision step.
| Role | Size | Face and weight | Used for |
|---|---|---|---|
| Display | 60 to 180, from the cell | Inter Heavy or Light | Clock, temperature, battery percent |
| Title | 40 | Inter Bold | Settings, Notifications, Vision |
| Body | 30 | DejaVu Sans | Row values, search text |
| Label | 26 | DejaVu Sans, Bold when it names a group | Row names, section labels |
| Caption | 26 floor | DejaVu Sans | Hints and secondary lines |
There is no size below 26. Section labels use sentence case; tracked capitals go away, and the Battery details grid labels (“CURRENT”) switch to Label.
Spacing rhythm. Multiples of 8 px: 8 inside a row, 16 between rows,
24 around a card’s content, 32 between groups. Cards keep a 99 px minimum
touch height. The existing visual_inset and layout step scaling stay the
only way to apply the Vision step.
Three card treatments, by job.
One accent rule. Per surface, the accent marks at most the current choice and one primary action. Links, “Done” and “Close” use the foreground colour with a chevron. The theme still supplies both colours; on a theme whose accent has low contrast against the card, the renderer already falls back to the foreground colour.
One icon style. A 3 px round-capped stroke, monochrome in the foreground colour, drawn as vectors (like the Shade’s brightness and volume glyphs today), 48 px square for rows and 64 px in the drawer. Settings rows get a leading glyph. Theme icons for apps are unchanged.
Home widgets and the dock. Widgets keep “no card, halo for contrast” and adopt the Display role. The dock takes the Control treatment instead of its own heavier slab, so it shares edges with the Shade and Settings.
tests/responsive_pixel_identity.rs
passed with its baselines unchanged, so the first slice
needs no baseline update. Later slices will change Settings and Vision
pixels, and each must update the baseline deliberately and say so.the-clock-widget-date-is-readable change states a 26 px floor. The
new 32 px floor satisfies it, so both can land in either order.cargo test --offline --manifest-path nix/rust-shell-client/Cargo.toml --lib clock_date (the date’s size, width and clearance against
bubble_lines, at 100/130/160/200%) and --tests (including
responsive_pixel_identity). Host class.
Done 2026-10-16 (host): 569 lib tests and all integration targets passed.docs/evidence/clock-restyle/. Host class, from
examples/render_clock_styles_evidence.rs.
Done 2026-10-16 (host).cargo run --offline --manifest-path nix/rust-shell-client/Cargo.toml --example render_clock_styles_evidence
after adding a portrait size. Host class.
Done 2026-10-17 (host): CLOCK_SIZE=portrait;
docs/evidence/clock-restyle/host-portrait-steps.png.host-retro82-wallpaper.png and
host-latte.png in docs/evidence/clock-restyle/. Latte is legible. Over
the retro-82 vinyl the Bubble and Thin minutes read through the halo, but
the dot-matrix minute over the orange label was weak.
Done 2026-10-17 (host): each lit dot now has a crisp ring in the halo
colour. The re-rendered sheets show the dot-matrix minute legible over
the label at every step. The analog ticks remain faint there; the hands
read.render.rs and move the Settings, Vision and Shade text onto them.
Update tests/responsive_pixel_identity.rs baselines deliberately and say
so in the commit. Verify with cargo test --offline --manifest-path nix/rust-shell-client/Cargo.toml --tests. Host class.
Done 2026-10-16 (host): roles and rhythm are TYPE_*/SPACE_* in
render.rs; Settings, the Vision page and the Shade use one layout at
every step; all eight test targets pass and the settings-*.png
baselines were updated in the Settings commit. Renders at four steps in
both orientations are in docs/evidence/type-roles/.docs/evidence/battery-details-type/.paint_card with CardJob::Chosen. The chosen
text-size step is a pill. Renders in catppuccin and catppuccin-latte are
in docs/evidence/card-jobs/.CardJob::Control is applied to the Settings rows,
Reboot/Power off, the Shade’s Keyboard toggle, the drawer search and
the dock. The Wi‑Fi pages, the Help buttons and the theme carousel are
not converted. See docs/evidence/card-jobs/.the_accent_marks_only_the_current_choice_on_settings_vision_and_the_shade
counts the accent groups: Settings 0, Vision 1, Shade 1, in both
orientations.glyph.rs provides eleven glyphs, which replace the
filled sun, speaker and search shapes. Settings rows, the power cards and
the Shade toggle get a leading glyph. That glyph is sized to the label
line rather than a fixed 48 px, so it grows with the text step without
cutting off values. Tests and renders are in
docs/evidence/stroked-icons/.grim captures of Home, the drawer, the Shade, Settings and
the Vision page at 100% and 200% on the landscape panel, with the vinyl
wallpaper, after the coordinator deploys the closure. Board class.
Progress 2026-10-16: Home (the restyled Clock) at 100%, 160% and 200% is
in docs/evidence/clock-restyle/board-panel-*-home.png.
Progress 2026-10-16: Settings, Vision and the Shade on the type roles
(2.1) at 100%, 160% and 200% on the HDMI output (1280x800, the only
active output) are in docs/evidence/type-roles/board-hdmi-*.png. Panel
captures of those surfaces and of the drawer remain.
Done 2026-10-17: native captures of Home, the drawer, Settings, the Vision
page and the Shade at 100% and 200% on DSI-1 (1232x568), retro-82 with
the vinyl wallpaper, from caaf4ff4, are in
docs/evidence/visual-language-panel/.Every Clock widget style SHALL draw the hour in the active theme’s foreground colour and the minute in its accent colour. It SHALL take both colours from the theme and SHALL keep the existing halo so the time reads over any wallpaper. It SHALL NOT use the accent for any other element of the Clock except the analog style’s minute hand.
Every Clock widget style SHALL draw its date as one line of mixed-case text (for example “Fri, Oct 16”) in the foreground colour, at no less than 32 px at the 100% text step. The size SHALL grow with the Vision text step. The date SHALL fit the cell without ellipsizing, and the time SHALL NOT overlap it.
Home widgets, the dock, the drawer, the Shade, Settings and the Vision page SHALL draw text from one type scale of five roles (Display, Title, Body, Label and Caption) with no text below 26 px at the 100% step, spaced on an 8 px rhythm. They SHALL use three card treatments by job (group, control and chosen) and one icon style. They SHALL take every colour from the active theme, and SHALL reflow without clipping, ellipsizing or overlapping at all four text steps and in high contrast, in both orientations.
Draft proposal · In progress
Snapshot 5836ef1d113d · 2026-10-17 08:22 UTC
Next gate(new) Under a board reservation, run
A 2026-09-28 audit of the-handheld-presents-a-coherent-shell (30 open tasks)
found that most of its host-scope tasks are already implemented — the actual
build went through nix/rust-shell-client/nix/card-shell rather than
growing nix/touch-launcher --serve as the change’s own cited test commands
assumed, and has substantial host/QEMU evidence under
docs/evidence/coherent-shell/. Three tasks, though, are genuinely
unimplemented and do not depend on the board:
the-shell-behaves-as-one-coherent-system slice E
(docs/evidence/coherent-shell/overlay-bottom-escape-qemu/). That change’s
own proposal.md says so explicitly: “The general side-edge contextual
Back mechanism for shell sheet/Settings/shade/drawer/keyboard ->
the-handheld-presents-a-coherent-shell tasks 2.2 and 4.4, still open;
slice E’s bottom-edge escape and dismiss-direction fix are bounded,
narrower fixes that do not complete those tasks.” Task 4.4’s broader touch
ownership arbitration (bottom Home/drawer, top shade, side Back, keyboard,
deck, app content) depends on the same missing side-edge mechanism.tools/shell-motion-trace.py and
tests/test_shell_motion.py do not exist on disk; the parent’s own tasks.md
preamble already calls them “interfaces to create, not current proof.”This is a scope-split successor, per AGENTS.md’s “close deliberately”
rule: it carries these three tasks and their requirement scope unchanged, so
the parent can close its other 27 tasks (22 done, 5 physical-board) without
waiting on this open-ended design/implementation work.
Status: authorized 2026-09-28. The user authorized this split on
2026-09-28 (“yes a-d and f”). Tasks 2.2, 4.4, and 4.5 are now ticked
[x] ... MOVED, NOT PERFORMED HERE in the parent’s tasks.md, and the
parent’s runtime/handheld-shell-design spec delta has been narrowed to
drop the corresponding requirement scope, in the same commit that makes
this change active. This change’s own tasks below are unchanged by that
authorization — none of them are done yet, only unblocked to proceed.
tools/shell-motion-trace.py (host self-test and
--board modes) and tests/test_shell_motion.py, producing touch-to-commit,
frame-done, and output-presented trace IDs, reduced-motion parity, and
process CPU/memory sampling against declared p95/p99 budgets.the-shell-behaves-as-one-coherent-system slice E.Host work only for the design/implementation tasks below. Two new physical
acceptance tasks (side-edge Back feel, and running the trace tool’s --board
mode) need a reserved board and are left open pending that reservation.
runtime/handheld-shell-design: narrows two requirements the parent already
added (Shade and contextual Back preserve the task, Gesture ownership and feedback are explicit) with the concrete side-edge mechanism and ownership
arbitration they described but that were not yet implemented, and adds a new
requirement for declared, measured motion budgets. Because the parent’s own
delta for this capability is not yet archived, this successor’s delta targets
the same not-yet-existing capability additively, the same pattern
the-shell-offers-quick-toggles-and-vision-options already uses for
runtime/notification-center/runtime/device-settings.Userspace only: nix/rust-shell-client/src/service_ui.rs (edge arbitration,
side Back), nix/card-shell/adapter.c/route.c (compositor-side edge
recognizers, alongside the existing bottom-edge/overlay-escape recognizers),
and new tools/shell-motion-trace.py / tests/test_shell_motion.py. No
kernel, device-tree, stage-1, or radio change.
nix/card-shell/adapter.c already claims the bottom edge band for
cs_begin_entry/cs_edge_down even while a Rust overlay is mapped (the
bottom-edge overlay-escape fix, the-shell-behaves-as-one-coherent-system
slice E), and nix/rust-shell-client/src/service_ui.rs already shares
OVERLAY_DISMISS_ZONE_Y/OVERLAY_DISMISS_DY between Shade and Settings for
their own top-anchored downward-dismiss gesture. Neither of those is a
side-edge gesture, and neither defines a general touch-ownership arbiter
across bottom/top/side/keyboard/deck/app-content — they are point fixes for
one reported bug (swiping up from inside Settings did nothing).
Goals: a qualified side-edge inward swipe that dismisses the topmost shell
context; one arbitration point (compositor-side, alongside the existing
bottom-edge recognizers) that decides which surface owns a touch at down;
a host-testable motion-trace tool with declared budgets, mirroring the
pattern tools/card-shell-benchmark.py already established for card-shell
cost work.
Non-Goals: replacing the bottom-edge overlay escape; a universal synthetic Back keypress into arbitrary app content; any board work (separate tasks below).
nix/card-shell/adapter.c); the side edge is claimed there,
alongside the existing bottom-edge cs_begin_entry/cs_edge_down
recognizers, using the same Route::Hide signal
(card_shell_launch_surface, already accepting "hide" per slice E) to
tell a mapped Rust overlay to dismiss. This keeps one touch-ownership
authority instead of splitting arbitration between the compositor and the
Rust client.tools/shell-motion-trace.py --self-test proves the trace ID schema and budget-reporting format without
a board (mirrors tools/card-shell-benchmark.py --self-test); --board
mode is a separate, later task once a board reservation is available.Implement side Back and ownership arbitration host-side, land host/QEMU fixtures, then implement the trace tool and its self-test. Board acceptance for both stays open until a reservation is available. No stage 1, kernel, or device tree change.
This change was split from the-handheld-presents-a-coherent-shell (tasks
2.2, 4.4, and 4.5). The user authorized this split on 2026-09-28 (“yes a-d
and f”); the parent’s own tasks 2.2/4.4/4.5 are now ticked [x] ... MOVED, NOT PERFORMED HERE and cross-reference this file. Task IDs here are
renumbered for this change’s own groups; each task names its parent task ID
for traceability. Two new board tasks (1.3, 2.2) are added since the
parent’s existing group-5 physical tasks predate this mechanism and do not
cover it. None of the tasks below are done yet; authorization only removes
the blocker on starting them.
nix/card-shell/adapter.c. Verify with a new host/native fixture
(tests/test_card_shell_route.py extension or equivalent) exercising:
side-edge dismiss order (sheet, then Settings/shade/drawer, then keyboard),
no synthesized Back keypress reaching app content, and no interference with
the existing bottom-edge escape.
Progress 2026-10-16 (host only, branch side-edge-back): adapter.c now
claims a side band as a weak EDGE_BACK origin and fires a release-decided
inward swipe through side_back_fire() (overlay: card_shell_launch_surface ("hide"); keyboard: keyboard_signal("hide"); no seat key event).
python3 tests/test_card_shell_route.py (4/4) pins the dismiss order, the
recognizer and the no-key-synthesis check, and nix build .#card-shell
compiles the adapter. Still open: the long-press sheet lives on the Rust
Home surface, which reports nothing to the compositor, so sheet_open() is a
stub returning false and the sheet step of the order is not reachable on a
device. It needs a Home-surface signal plus a Rust route; keep this task
open until that exists.
Progress 2026-10-16 (later): the menu is on the Rust overlay layer, so
the adapter now sends back for the overlay step. The Rust client closes
the long-press app menu first, and otherwise hides. Host: cargo test
(incl. side_back_line_is_its_own_request_not_a_route) and
python3 tests/test_card_shell_route.py (4/4) passed. Board, injected
pointer on the panel: side Back closed the menu and left the drawer open,
then closed the drawer
(docs/evidence/coherent-shell/side-edge-back/board-2026-10-16-injected.md,
“Long-press menu before the drawer”).card_shell_touch_owner() in
nix/card-shell/route.c is the one touch-down decision (keyboard hit, then
bottom Home, top shade, qualified side Back, deck, app) and input_down
asks it before beginning a side-Back origin; the existing bottom and top
branches keep their code paths and the fixture pins that the arbiter agrees
with them. python3 tests/test_card_shell_route.py passed 4/4 including
test_side_edge_back_and_touch_ownership at 568x1232 and 1280x800 (cases:
side-qualified, app-scroll-conflict, bottom-qualified, top-qualified,
keyboard-inset, off-output). This is a policy check, not a touch on glass.python3 tools/capture-feature.py side-edge-back --provenance real-touch --duration 30 --description 'Side-edge contextual Back on glass' --output-dir docs/evidence/coherent-shell/side-edge-back. Keep open until
committed.
Progress 2026-10-16, injected mouse on HDMI, not real touch
(docs/evidence/coherent-shell/side-edge-back/board-2026-10-16-injected.md):
target=2).b3c44dd0 (same evidence file, “Keyboard target after
the popup fix”):target=2), then dismissed the keyboard
(target=3).target=2).
Still open: real-finger feel and the drawer case.
Result 2026-10-16 (operator, real finger on the landscape panel): “back works fine”.
The operator was asked to long-press in the drawer and swipe in from the side,
and this covers the drawer case. No recording was made (the camera
requirement was waived; the operator’s word is the evidence). The operator
reported no accidental app Back and no conflict with the bottom edge.tools/shell-motion-trace.py (touch->scene
damage->commit->frame-done->output-presented trace IDs, reduced-motion
parity, process CPU/memory sampling, declared board p95/p99 budgets) and
tests/test_shell_motion.py. Verify with
python3 tools/shell-motion-trace.py --self-test and
python3 tests/test_shell_motion.py --case trace-order --case reduced-motion
(host trace schema, not panel presentation).
Done 2026-10-16, host only: both commands passed
(tools/shell-motion-trace.py --self-test printed self-test PASS;
tests/test_shell_motion.py --case trace-order --case reduced-motion printed
PASS for each). Budgets are declared in the tool: input-to-present p95 at
two and p99 at three nominal 52.19 Hz output intervals, the same bounds for
frame interval, zero blank frames, and 64 MiB RSS growth; CPU is sampled and
reported with no budget. The card-shell console already emits only input,
submit (commit) and present rows, so --log reports scene_damage and
frame_done as unobserved; emitting them with trace IDs is compositor work
that task 2.2 depends on. python3 tools/shell-motion-trace.py --board --output docs/evidence/coherent-shell/motion.json, correlating input->scene
commit->output presentation with camera-visible movement; report p50/p95/p99,
blank/missed frames, CPU/RSS, renderer and actual cadence. Record failed
budgets honestly. Keep open until committed.openspec validate the-shell-gets-side-edge-back-and-motion-trace --strict. Passed
2026-09-28 on close/shell-umbrella.An inward touch gesture from a qualified side edge SHALL dismiss the topmost shell context in order: an open long-press context sheet; then Settings, shade, or drawer; then the on-screen keyboard when it owns input focus. The gesture SHALL NOT synthesize a Back/Escape/Alt-Left keypress into arbitrary Wayland application content. This is separate from and does not replace the existing bottom-edge overlay-escape recognizer, which remains for bottom-edge swipes reaching the overview or switching apps from a mapped overlay.
A single compositor-side arbiter SHALL decide, at touch-down, which of bottom Home/drawer, top shade, side Back, keyboard, deck, or app content owns a contact, using measured hit regions. Ordinary app scrolling and text selection SHALL remain with the app outside every qualified edge region. A keyboard region in its reserved lower area SHALL win over a Home/drawer gesture there.
The shell SHALL produce a touch-to-scene-damage, damage-to-commit, commit-to-frame-done, and frame-done-to-output-presented trace with stable IDs correlating one accepted touch through to panel presentation, plus process CPU/memory sampling. Declared p95/p99 input-to-present, frame interval, and blank/missed-frame budgets SHALL be checked against this trace, and a failed budget SHALL be reported honestly rather than omitted. Reduced motion SHALL preserve the same trace stages with shorter settling.
Draft proposal · In progress
Snapshot 5836ef1d113d · 2026-10-17 08:22 UTC
Next gateInstall the built Image/k230-tdisplay.dtb to /boot and reboot (a DT/kernel change does not take effect from a system activation alone). Record cat /proc/asound/cards, dmesg | grep -iE…
A person cannot currently hear anything the handheld plays without plugging
in headphones. The device tree enables only the SoC’s internal Inno codec
(nix/dts/k230-tdisplay.dts’s sound node), and nothing on this board has
ever exercised even that path with a userspace tool — there is no committed
boot log, aplay run, or /proc/asound/cards capture anywhere in this
repository before this change. LILYGO’s own firmware README advertises a
“MAX98357A external I2S amplifier and audio route switching” for this board
family, which is the closest thing to a built-in loudspeaker this hardware
offers.
Investigating that claim (docs/evidence/max98357a-speaker.md) found a
firmer answer than “which board holds the amp”: LILYGO’s own hardware map
(k230_bsp/docs/HARDWARE_PINMAP.md in Xinyuan-LilyGO/T-Display-K230) puts
the MAX98357A on a third, separate, optional add-on board (“nRF52840
BLE / Audio / Sensor Base Board”) — not the main T-Display-K230 board this
project has, and not the nRF9151 keyboard base either. Whether that add-on
is physically present here is unrecorded and UNVERIFIED. This proposal
therefore does the software work that is correct regardless of the answer —
the Inno codec keeps working exactly as it does today, and a real,
kernel-level route to the external amp becomes available and testable — and
states plainly what remains unproven: physical amp presence and the actual
FPIOA pin muxing for its I2S signals.
system/audio capability describing what this board’s audio output
actually does: the Inno codec as the default line-out/headphone path, and
an opt-in external-I2S route for an attached MAX98357A amplifier.nix/patches/canaan-audio-external-i2s-switch.patch) that adds an
“External I2S Output Switch” ALSA control to the existing
canaan,k230-audio-inno machine driver, exposing a register-level route
already present in the pinned kernel’s own audio_i2s_enable_audio_codec()
(sound/soc/canaan/canaan_k230_audio.c:50-59) but previously hardcoded to
the internal codec. This is a direct, byte-context-verified port of
LILYGO’s own 0059-asoc-canaan-add-external-i2s-output-switch.patch.nix/dts/k230-tdisplay.dts via gpio-line-names
on the already-enabled gpio1_ports controller — descriptive only, no
driver claims the line, matching how LILYGO’s own launcher controls the
same enable pin directly from userspace via libgpiod.k230-speaker-test operator helper (nix/k230-speaker-test.nix,
alsa-utils + libgpiod) that reports ALSA/GPIO state, and drives each
route with a 440 Hz test tone, restoring the Inno default afterward.canaan,external-i2s-output-default property is set, so a board with no
amp attached at all still boots exactly as before.Non-goals: Adding a maxim,max98357a ALSA codec device-tree node
(rejected — see docs/evidence/max98357a-speaker.md: it would claim
GPIO34 exclusively via devm_gpiod_get, conflicting with the userspace
helper, and nothing wires it into any dai-link for its DAPM power sequencing
to do anything). Adding a second ALSA sound card (rejected — the existing
machine driver already owns the sole physical I2S/SAI peripheral;
LILYGO’s own design does not do this either). Muxing GPIO32/33/35 to their
I2S alternate function in U-Boot/stage 1 (this SoC’s FPIOA table is a
stage-1 concern outside the Linux device tree; see the same evidence file).
Confirming whether the nRF52840 audio add-on is physically attached to this
project’s board (a board observation this proposal cannot make from source
alone).
system/audio: what the board’s audio output does today (Inno codec
default) and the opt-in external-I2S route a MAX98357A amplifier can use,
with the physical-amp and pin-muxing gaps stated as open, not assumed.None. system/kernel already covers “kernel carries patches, recorded with
origin and reason” generically; this proposal adds one such patch but does
not change that capability’s requirements.
nix/dts/k230-tdisplay.dts, nix/kernel.nix, nix/patches/canaan-audio- external-i2s-switch.patch (new), nix/k230-speaker-test.nix (new),
nix/hardware.nix (new packages). The kernel derivation rebuilds because its
source patch set changed. A device-tree-only or kernel-only change like this
does not take effect through a plain system activation — it needs the
built Image/k230-tdisplay.dtb installed to the board’s /boot partition
and a reboot, per .skills/k230-spec-change/SKILL.md’s DT-push note. No task
here claims board proof; every hardware-observable requirement in the new
spec is marked <!-- UNVERIFIED --> and stays open until a board test is
run.
On 2026-10-01 the user explicitly transferred the unperformed line-out/headphone listening test from the completed volume UI change into task 5.6 here. This proposal now owns confirming that Settings slider levels and mute correspond to audible output through the Inno codec via PipeWire. The connected headphone/line-out and listening observation remain UNVERIFIED. The user confirms there is no external audio add-on; external-amplifier validation is deferred and must not block this independent headphone test.
docs/evidence/max98357a-speaker.md has the full research trail and every
citation this design relies on. This file states the decisions and what was
rejected.
The board today has exactly one working audio path recorded anywhere in this
repo: nix/dts/k230-tdisplay.dts’s sound node, compatible = "canaan,k230-audio-inno", wired to &i2s and &inno_codec. It has never
been exercised by a userspace tool — no aplay, no /proc/asound/cards
capture, nothing. LILYGO’s public README lists “MAX98357A external I2S
amplifier and audio route switching” as included hardware support.
nix/dts/k230-tdisplay.dts)Decision: document the four MAX98357A pins via gpio-line-names on the
existing, always-enabled gpio1_ports controller. Add no new device node,
and leave canaan,external-i2s-output-default unset on the sound node so
the Inno codec stays the boot-time default.
Why not a maxim,max98357a codec node: sound/soc/codecs/max98357a.c
(CONFIG_SND_SOC_MAX98357A) exists in the pinned kernel tree and would
probe cleanly on a sdmode-gpios property. Rejected because:
devm_gpiod_get() on sdmode-gpios, which requests the
GPIO line for the lifetime of the driver. nix/k230-speaker-test.nix
(and LILYGO’s own launcher, ui_hardware.c:1655-1731) needs to toggle
the identical line from userspace via libgpiod; the kernel’s exclusive
request and a userspace gpioset on the same offset cannot coexist.canaan_k230_dailink (see Layer 2 below for why not), so the widget
would never power on regardless of what userspace asks for — a DT node
that looks like support while doing nothing.Why not FPIOA pin muxing here: confirmed by reading this kernel tree
directly (not inferred) that no pinctrl-k230 driver, k230-fpioa binding,
or pinctrl/fpioa node exists anywhere in k230.dtsi or any shipped
board .dts. docs/dts-evidence.md already established this for our board;
this change re-confirmed it holds for LILYGO’s referenced k230.dtsi too
(same shared file). FPIOA muxing on this SoC is a stage-1 (U-Boot)
responsibility this project’s taxonomy places outside system/kernel and
outside the Linux device tree entirely. GPIO32/33/35’s actual alternate
function on this board is therefore left as an open, explicitly named gap
rather than asserted.
nix/patches/canaan-audio-external-i2s-switch.patch)Decision: port LILYGO’s 0059-asoc-canaan-add-external-i2s-output- switch.patch (commit 37b66b38) onto sound/soc/canaan/canaan_k230_inno.c,
almost unchanged. Verified this file is byte-identical, at every hunk
context 0059 touches, between our pinned tree
(ruyisdk/linux-xuantie-kernel@7d4e1f4) and whatever LILYGO’s fork carries,
because it is generic Canaan SDK code neither fork’s panel/display work ever
touched. patch -p1 applied cleanly against a fresh copy of the file from
the unpacked linux-xuantie-k230-src store path.
Why this is correct and not a workaround: the route is not invented —
audio_i2s_enable_audio_codec() (sound/soc/canaan/canaan_k230_audio.c: 50-59, EXPORT_SYMBOL_GPL) already exists in this exact kernel and already
flips a real register bit (audio_in_pdm_conf_0.audio_codec_bypass) in the
canaan,k230-audio peripheral (k230.dtsi:644, audio@0x9140f400). The
unpatched driver just calls it with a hardcoded true at probe and never
again. This patch adds: a bool external_i2s_output field, a
SOC_SINGLE_BOOL_EXT control named "External I2S Output Switch" (same
name LILYGO’s own launcher already drives via amixer -q cset), a
k230_inno_apply_output_route() helper that re-asserts the chosen route,
called both at probe and (new, beyond 0059) at every stream startup() so a
route selected with no active stream survives a SAI clock suspend/resume,
and of_property_read_bool(np, "canaan,external-i2s-output-default") to let
a board default to the external route — which ours deliberately does not
set.
Why not a second ALSA card (simple-audio-card/audio-graph-card):
both exist in this kernel (sound/soc/generic/). Rejected because the SoC
has exactly one physical SAI/I2S peripheral, and canaan,k230-audio-inno
already claims it as canaan_k230_dailink’s sole cpu/platform node via
canaan,k230-i2s-controller. A second card pointed at the same &i2s node
would either conflict over the platform device or require rewriting the
existing machine driver to expose multiple dai-links — more invasive than
“smallest correct change,” and LILYGO’s own design (confirmed by the 0058
commit message) explicitly avoids this too: “not registered as a second
ALSA sound card… the external amp listens to the same I2S stream.”
Kernel config: no new CONFIG_SND_* symbol was needed.
CONFIG_SND_SOC_CANAAN_K230_INNO=y and CONFIG_SND_SOC_CANAAN_K230_AUDIO=y
were already set in arch/riscv/configs/k230_defconfig (lines 300-301) —
the driver we patch was already built in.
nix/k230-speaker-test.nix, nix/hardware.nix)Decision: a single writeShellScriptBin wrapping alsa-utils
(amixer, aplay, speaker-test) and libgpiod (gpioset, gpioget,
gpiodetect, gpioinfo). status/internal/external subcommands. GPIO34
is held active via gpioset --mode=signal ... &, released with kill —
this is the libgpiod v2 pattern for holding a line across an external
command; it is UNVERIFIED against the exact libgpiod version this flake
pins (no board or built closure has run it yet). This kernel has no
CONFIG_GPIO_SYSFS (removed from the Kconfig entirely), so the character
device is the only interface available regardless.
Why not a persistent systemd service holding the GPIO: rejected for this change. A held line only during an explicit test avoids leaving the amplifier powered by default on a board that may not even have one attached, and matches the task’s ask for a narrow operator helper rather than a standing audio-routing policy. Standing policy (e.g. auto-switching on a jack-detect signal) is future work once the physical amp’s presence and pin muxing are confirmed.
Considered treating the LILYGO README’s inclusion of “MAX98357A… audio
route switching” as evidence this project’s specific board has the
add-on. Rejected once k230_bsp/docs/HARDWARE_PINMAP.md was read in full:
that same document places the part on a named optional add-on, separately
purchasable from the main board, and CHANGELOG.MD groups it with other
add-on presets (nRF52840, nRF9151, LoRa). A README feature list describing
the product family is not a photograph of this board’s PCB. Per
.skills/k230-spec-change/SKILL.md’s grounding order, this stays
<!-- UNVERIFIED --> rather than becoming a confident requirement.
On 2026-10-01 the user explicitly transferred the unperformed line-out/headphone listening test from the completed volume UI change into task 5.6 here. This proposal now owns confirming that Settings slider levels and mute correspond to audible output through the Inno codec via PipeWire. The connected headphone/line-out and listening observation remain UNVERIFIED. The user confirms there is no external audio add-on; external-amplifier validation is deferred and must not block this independent headphone test.
All tasks below name the narrowest real command that proves them. Host
build and QEMU boot are one evidence class; a console transcript or
recording from the physical board is a different one, and no task here
claims the second from the first. Store board evidence under
docs/evidence/max98357a-speaker/ with commands, timestamps and limits.
Xinyuan-LilyGO/T-Display-K230 (k230_bsp/docs/HARDWARE_PINMAP.md, README.MD, CHANGELOG.MD, patches 0058/0059, ui_hardware.c/ui_audio.c) via gh api and record pins, enable GPIO, board placement and route-switch mechanism with file/line citations. Recorded in docs/evidence/max98357a-speaker.md.linux-xuantie-k230-src store path from nix/kernel-src.nix) for sound/soc/canaan/canaan_k230_{inno,audio}.c, confirm CONFIG_SND_SOC_MAX98357A/CONFIG_SND_SIMPLE_CARD/CONFIG_SND_AUDIO_GRAPH_CARD availability, confirm no pinctrl-k230/FPIOA driver exists, and confirm canaan_k230_inno.c’s pre-patch state matches LILYGO’s 0059 hunk context byte-for-byte.Proof: docs/evidence/max98357a-speaker.md, citing file paths and, where applicable, line numbers or commit hashes.
nix/patches/canaan-audio-external-i2s-switch.patch (ported from LILYGO’s 0059) and wire it into nix/kernel.nix’s patch list with a comment explaining provenance and why it applies unmodified.nix build .#kernel --max-jobs 1 --cores 6 --no-link --print-out-paths -> /nix/store/ix67lsrfp2y1d6dcb4q5mg1b2aa6snhl-linux-riscv64-unknown-linux-gnu-6.6.36-xuantie. Host cross-build proof only; does not prove the module binds on hardware.dmesg | grep -iE 'canaan-k230-snd-inno|External I2S' on the board after a /boot install and reboot.
Done from the 2026-10-01 boot-verification console transcript: canaan-k230-snd-inno sound: External I2S output disabled by default at 5.3 s, and the control reads off (docs/evidence/max98357a-speaker/board-2026-10-01.md).Proof for 2.1/2.2a: the patch applies (patch -p1 --dry-run verified against the unpacked pinned source during development) and nix build .#kernel succeeds — done, host-only. Proof for 2.2b is a board task: a QEMU boot does not model this SoC’s audio peripheral (.skills/k230-spec-change/SKILL.md’s QEMU-proof table), so only a board dmesg capture proves the module bound with the new control present.
gpio-line-names for GPIO32/33/34/35 to &gpio1_ports in nix/dts/k230-tdisplay.dts, with the UNVERIFIED-FPIOA-muxing note inline. Leave canaan,external-i2s-output-default unset.nix build .#deviceTree --no-link --print-out-paths -> /nix/store/mwmnah2mh77zncj83r5kcp2q8yn6k7kd-k230-tdisplay.dtb. Decompiled with dtc -I dtb -O dts and confirmed the gpio-line-names property lands on gpio1_ports exactly as written.Proof: nix build .#deviceTree — done, host-only. This proves the DTB compiles; it does not prove the named GPIO lines exist as such at runtime on the board (that needs gpioinfo gpiochip1 on hardware, task 5.2).
nix/k230-speaker-test.nix (status/internal/external subcommands) and install it plus alsa-utils/libgpiod in nix/hardware.nix’s environment.systemPackages, each with a recorded reason per that file’s existing convention.nix build .#nixosConfigurations.k230-coherent-shell.config.system.build.toplevel --max-jobs 1 --cores 6 --no-link --print-out-paths -> /nix/store/lfq1j4rb9a1pmbqy3q56vh26j9054hqa-nixos-system-nixos-26.11.20260919.20b1ddd. k230-speaker-test.drv and alsa-utils/libgpiod both built as part of .#sdImage-coherent.k230-speaker-test status on the board.
2026-10-01 run (console transcript): it exited 0, but its gpioinfo gpiochip1 failed under libgpiod 2.2.4 (cannot find line 'gpiochip1') and amixer controls errored. Still open: switch the script to libgpiod 2.x syntax and re-run (docs/evidence/max98357a-speaker/board-2026-10-01.md).
2026-10-16: the script now uses the libgpiod 2 forms and amixer -c 0, checked by hand on the board (board-2026-10-16-libgpiod2.md). Still open: the installed script’s status run.
2026-10-16 15:28 UTC: the installed script’s status exited 0 and printed the cards, the route control (off) and SDMODE line 2 with no errors (docs/evidence/max98357a-speaker/board-2026-10-16-installed-status.md).Proof for 4.1/4.2a: the toplevel closure and SD image build, and the script package builds — done, host-only. Proof for 4.2b is a board task — the script’s gpioset --mode=signal usage is explicitly UNVERIFIED against the flake’s actual pinned libgpiod version (design.md), so the first board run is also the first real test of that assumption.
5.1 Install the built Image/k230-tdisplay.dtb to /boot and reboot (a DT/kernel change does not take effect from a system activation alone). Record cat /proc/asound/cards, dmesg | grep -iE 'max98357|i2s|inno|asoc', aplay -l.
5.2 Run k230-speaker-test status and gpioinfo gpiochip1 to confirm the named GPIO lines and the presence (or absence) of the “External I2S Output Switch” control.
2026-10-16: present; the installed status (which runs gpioinfo -c gpiochip1 2) shows SDMODE line 2 as an output and the control as off (board-2026-10-16-installed-status.md). The line is unnamed in the mainline DT; it is identified by offset.
5.3 Run k230-speaker-test internal and have the operator confirm audibly whether the Inno line-out/headphone path still works exactly as before this change (regression check — this change must not break it).
5.4 Run k230-speaker-test external and have the operator listen for the MAX98357A speaker, or record with a microphone near the board if no operator is present (per docs/evidence/use-the-camera-not-the-user.md-style discipline: do not infer a hardware result from a host-only check). Record which of the three failure modes below was observed, if any.
5.5 Determine and record whether the nRF52840 audio/sensor add-on board is physically attached to this hardware at all. Absent it, tasks 5.4’s success criterion cannot be met regardless of software correctness, and that is the expected, honest outcome to record — not a bug in this change.
5.6 Transferred headphone/line-out listening acceptance from the-handheld-controls-volume task 9.2, explicitly authorized by the user on 2026-10-01. With headphones or line-out connected, play a known tone/clip through the Inno codec’s PipeWire sink, drag the Settings volume slider through several levels and zero/mute, and confirm by listening that audible level follows the control and mute is silent. Operator command: flock /tmp/k230-board.lock python3 tools/console.py /dev/ttyACM0 --wait=3 'k230-speaker-test status'; record the actual playback command, installed system, timestamp, attached output and listener’s observations under docs/evidence/max98357a-speaker/. Use PipeWire playback for the slider portion, not an exclusive direct-ALSA tone that bypasses it. The prior 15 board UI/backend checks are not audible proof. Keep UNVERIFIED until a listening observation is committed; no external audio add-on is required for this headphone test.
Proof: a committed console transcript/recording under docs/evidence/max98357a-speaker/, naming exactly which of these outcomes was observed:
aplay -l/cat /proc/asound/cards show only CANAAN-K230-I2S; k230-speaker-test external runs without error but nothing audible plays even with a working GPIO/route, because there is no amplifier on the other end of the pins. Expected if 5.5 finds no add-on.amixer cget reflects the new value) and GPIO34 reads back high, but GPIO32/33/35 never carry an I2S signal because U-Boot left them as plain GPIO — the open gap in docs/evidence/max98357a-speaker.md.external, and the headphone/line-out path unaffected on internal. This is the only outcome that would let 5.4/5.5 be ticked as fully passing.openspec validate --strict the-handheld-plays-through-its-speaker and python3 scripts/render_work_board.py > /dev/null.Proof: openspec validate --strict and render_work_board.py exit 0. Neither substitutes for the board evidence group 5 names.
Define what this board’s audio output actually does: the always-available Inno codec line-out/headphone path, and the opt-in route to an external MAX98357A amplifier that some, but not necessarily this, board carries.
Grounding: nix/dts/k230-tdisplay.dts’s sound node, compatible = "canaan,k230-audio-inno", unchanged by this proposal except that
canaan,external-i2s-output-default is deliberately left unset. Kernel-side,
sound/soc/canaan/canaan_k230_inno.c’s probe path now calls
k230_inno_apply_output_route() with external_i2s_output initialized from
that (absent) property, which evaluates to the same
audio_i2s_enable_audio_codec(true) call the unpatched driver made
unconditionally.
audio route, matching pre-change behavior, on any board regardless of whether a MAX98357A amplifier is attached.
/proc/asound/cards shows the CANAAN-K230-I2S card and audio played on it reaches the Inno codec’s line-out/headphone path, exactly as before this changeGrounding: nix/patches/canaan-audio-external-i2s-switch.patch, a port of
Xinyuan-LilyGO/T-Display-K230 commit 37b66b38
(“0059-asoc-canaan-add-external-i2s-output-switch.patch”), verified to apply
cleanly against sound/soc/canaan/canaan_k230_inno.c in the pinned kernel
source (nix/kernel-src.nix, ruyisdk/linux-xuantie-kernel@7d4e1f4). The
underlying register mux, audio_i2s_enable_audio_codec(), is vendor source
at sound/soc/canaan/canaan_k230_audio.c:50-59, read directly, not inferred
from a datasheet.
I2S Output Switch” that, when set, stops feeding the Inno codec and drives the raw I2S signal onto GPIO32 (BCLK), GPIO33 (LRCK) and GPIO35 (DOUT) instead, and SHALL restore the Inno codec route when the control is cleared.
amixer -q cset name='External I2S Output Switch' 1amixer -q cset name='External I2S Output Switch' 0Grounding: k230_bsp/docs/HARDWARE_PINMAP.md (Xinyuan-LilyGO/
T-Display-K230), “Shutdown control, GPIO34, high enables the amplifier, low
shuts it down”, independently confirmed by ui_hardware.c:68
(AMP_SHUTDOWN_GPIO 34) and ui_hardware.c:1655-1731’s libgpiod-based
implementation. GPIO34 is bank 1 offset 2
(k230.dtsi:415-421, gpio1_ports).
GPIO34 exclusively. gpio-line-names on gpio1_ports SHALL document the
line for discoverability without requesting it, so a userspace helper using
libgpiod can request and release the line at will.
k230-speaker-test externalgpiochip1, offset 2) via libgpiod, drives it high for the duration of the test, and releases it afterward, with no kernel driver reporting the line already busyGrounding: k230_bsp/docs/HARDWARE_PINMAP.md places the MAX98357A on the
optional “nRF52840 BLE / Audio / Sensor Base Board”, separate from the main
T-Display-K230 board and from the nRF9151 keyboard base; nothing in this
repository has recorded that add-on’s presence before this change. Separately,
docs/dts-evidence.md and this change’s own re-reading of the pinned kernel
tree confirm no pinctrl/FPIOA driver exists in the Linux device tree, so
GPIO32/33/35’s alternate-function muxing is a stage-1 (U-Boot) fact this
project cannot currently read or set from Linux.
not an inference from a README or a schematic for a different SKU, whether the MAX98357A add-on is physically present, and whether GPIO32/33/35 carry an I2S signal when the external route is selected.
k230-speaker-test status, k230-speaker-test external with a listening operator or a nearby microphone recording)Draft proposal · In progress
Snapshot 5836ef1d113d · 2026-10-17 08:22 UTC
Next gateExtend the same driver's stop path
Right now every background job on the handheld — Wi-Fi association, a video
decode helper, the Python theme helper, a udev-triggered script — competes
with the Sway compositor for the same single Linux hart, and a person notices
it as the shell stuttering. The board’s second physical core, CPU0, has sat
in wfi since BootROM released CPU1 into Linux
(board/canaan/common/k230_img.c:276-285). the-system-runs-on-both-cores
proposed to close that gap by letting Linux itself schedule ordinary
processes on CPU0 (SMP). After two rounds of board-grounded investigation
(docs/research/second-core-feasibility.md,
docs/closeout/second-core-plan.md), the user has now decided, on
2026-09-28, to stop pursuing that outcome and to formally redirect the
second-core project to a coprocessor (AMP) model instead: Linux keeps its one
hart, and CPU0 runs a separately loaded, explicitly managed program that
Linux talks to over shared memory, coordinated by hand, not by the scheduler.
This proposal records that redirection as the accepted plan.
The decision rests on three board-grounded facts, all already established by the prior investigation and not reopened here:
CSR.MHARTID = 0.
docs/evidence/second-core/cpu0-identity-physical-trial.md measured
CPU0_SPL_IDENTITY mhartid=0x0 on physical CPU0 directly, and pinned
OpenSBI source traces the CPU1-side Boot HART ID : 0 banner to the same
CSR (sbi_init.c:534,394,169, riscv_asm.h:166). OpenSBI’s hart table,
its warm-entry scratch/stack selection, and its HSM/IPI targeting all
resolve through CSR_MHARTID as a unique key
(platform/generic/platform.c:95-132, sbi_scratch.c:24-32,
firmware/fw_base.S:441-462, sbi_hsm.c:300-361); a duplicate ID breaks
all of them before interrupts or coherency are even reached. No document in
hand — not the TRM, not the pinned vendor overlay, not the public SDK —
supplies a second per-core identity signal to fix this.dma-noncoherent property
(arch/riscv/boot/dts/canaan/k230.dtsi:207) is about DMA, not CPU-to-CPU
access. The vendor’s own working AMP driver
(k230-amp.c) flushes shared buffers by hand around every access, and this
project’s own heartbeat payload (tools/small-core-heartbeat.S:25-28)
issues the pinned l2cache.ciall encoding after every write for the same
reason. A working system’s own hand-flushing is adverse evidence against
implicit coherency, not proof of an incidental one.the-system-enables-proven-c908-extensions (modifying system/kernel)
makes the ordinary kernel and Pixman RVV-by-default. Linux’s scheduler has
no notion of “this hart lacks an extension the running binary needs” — a
migrated vector instruction on CPU0 traps, it does not fall back. SMP would
need a scalar-everywhere kernel and userspace image before any workload
became migratable, which throws away the vector work this project already
proved.None of this is new: docs/closeout/second-core-plan.md’s own
“Recommendation” section already reaches “AMP/heartbeat-style offload is the
practical route.” What changes here is that the choice is now the user’s
formal decision rather than an open question, and this proposal turns it
into an enforceable, staged plan the way the-system-runs-on-both-cores did
for SMP.
k230_sdk has a K230 remoteproc or mailbox driver
(confirmed by reading the pinned kernel source; see design.md), and the
vendor’s own k230-amp.c is a raw misc-device loader/reset driver, not a
remoteproc/rpmsg consumer — its release sequence (write CPU0’s
reset-vector register, then the RMU CPU0_RST_CTL sequence) is reusable
knowledge, not reusable code.tools/small-core-heartbeat.{S,ld}) as the first firmware
step, over Zephyr, FreeRTOS, or the vendor’s RT-Smart, on build-complexity
and evidence grounds (design.md).BOARD-GATED and AUTHORIZATION-REQUIRED and depends on a
current fallback recovery route being available, per AGENTS.md.2026-09-28 addendum, operator decision on recovery: the external
SD-card-reader recovery rehearsal named below (stage 1) is waived. The
user: “we can easily fix the sd card damn. don’t worry about recovery we’ve
literally done that fine already before. i don’t want to do a heartbeat
test on a spare card.” No task in this change or its two parents may
require a separate spare/disposable card; every board step here runs on the
normal card. Recovery, if a step fails or hangs, is by the already-proven
U-Boot one-shot boot from boot-prev or ums/flash reimaging
(docs/uboot-ums.md, docs/evidence/card-shell/bottom-band-flicker/ kernel-patch-boot-panic.md) — not by a rehearsed external-reader restore.
Explicit user authorization at the time of the write is still required for
every task that writes a CPU0 reset, vector, or reset-controller register;
that marker is unchanged. See docs/closeout/second-core-plan.md’s own
2026-09-28 addendum for the same decision recorded against its “next 3
concrete steps.”
Non-goals, named explicitly per .skills/k230-spec-change/SKILL.md’s
proposal rule: this change does not add cpu@1 to any device tree, does not
pursue Linux SMP in any form, does not bring up the vendor RT-Smart image,
does not pick a K230 mailbox hardware driver (its register layout is
unread), does not decide LoRa, battery/charger, or keyboard-base peripheral
ownership, and does not give CPU0 the ability to reset CPU1 or Linux
automatically — a detected hang is recorded, not acted on, in this change.
Both the-system-runs-on-both-cores and
the-small-core-runs-a-recoverable-heartbeat remain open. Per AGENTS.md,
this proposal does not archive or withdraw either one; it adds a dated note
to each recording how this change relates to it, and leaves every task
unticked. The user confirms before either parent change is archived,
withdrawn, or otherwise closed.
the-system-runs-on-both-cores. Its stage-a read-only board probes
(tasks 1.1-1.6, already complete) and its recovery-rehearsal requirement
(tasks 2.1/2.2, still open) are exactly the right foundation and are
carried into this change’s own task list as the same rehearsal, not
duplicated work. Its SMP-specific stages — the OpenSBI/DT hart-release
experiment (task 3.1/3.2), the pre-Linux coherency validation gating a
Linux-shared boot (task 4.1), and ISA-aware SMP scheduling (task 5.1) —
are obsoleted by this redirect: they exist only to make Linux itself treat
CPU0 as a peer hart, which is no longer the goal. They are recorded as
superseded, not deleted, not ticked, and the change stays open per
AGENTS.md’s “keep incomplete changes open” rule until the user authorizes
archiving it (likely alongside a decision to withdraw the SMP-specific
requirement from system/second-core-readiness in a later, separate
change once this AMP work is itself landed).the-small-core-runs-a-recoverable-heartbeat. Its “Linux SMP is not an
acceptance path” framing is now moot, because Linux SMP is no longer the
target of any change — what this proposal wants is exactly the kind of
independent physical execution that change already proved on the host and
partially rehearsed. Its ready payload and host evidence
(tools/small-core-heartbeat.{S,ld}, docs/evidence/second-core/heartbeat-host.md)
and its board-gated tasks 3.1 (recovery rehearsal, now waived per the
2026-09-28 addendum above) then 3.2 (release and observe) are resequenced
as this change’s own stage-1 and stage-2 tasks, in that same order. Its coexistence stage (task family 4: patch the CPU0 SPL
parking loop to run a heartbeat unconditionally after every boot) is
not reused as designed: design.md explains that a proper
remoteproc-shaped driver lets Linux start and stop CPU0 on demand once
booted, which needs no stage-1/SPL change at all and is both more flexible
and lower-risk than making CPU0 run unconditionally on every boot. That
proposal’s task family 4 is recorded as superseded by this change’s stage-4
task, not deleted.None.
system/second-core-readiness: turns the existing “a separate AMP path
SHALL additionally define its firmware image, reserved memory, cache
maintenance, mailbox protocol, and exclusive peripheral ownership” clause
from a one-line placeholder into the actual staged, evidence-gated AMP
bring-up plan, its authorization/recovery gate, its cache-maintenance
contract, and the requirement that AMP execution not be read as Linux SMP
or as an unreviewed peripheral-ownership grant.No boot image bytes change in this proposal. The existing heartbeat payload
and its host tooling are extended, not replaced. This proposal’s own tasks
are source/documentation/design work plus, further out, board-gated
hardware-writing steps that require the user’s explicit authorization before
any register is written, exactly as AGENTS.md requires. The external-reader
recovery rehearsal the two parent changes originally required is waived per
the 2026-09-28 addendum above; the proven fallback recovery routes (U-Boot
one-shot from boot-prev, ums/flash reimaging) stand in its place.
See proposal.md, docs/closeout/second-core-plan.md, and
docs/research/second-core-feasibility.md for the full audit trail behind
the SMP-to-AMP redirect. This document covers only the AMP architecture
itself: what runs where, which registers and memory regions are involved,
what firmware to run first, and how each step is proved.
Layer map for this change, per .skills/k230-spec-change/SKILL.md’s design
rule (“name the layer”):
canaan,k230-sysctl-reset reset controller.remoteproc driver; no existing driver
is modified.tools/small-core-heartbeat.{S,ld} already is, extended incrementally.
Not RT-Smart, not Zephyr, not FreeRTOS, for this first step (see below).uboot-k230-cpu0-identity-probe / stage1-cpu0-identity-probe
(flake.nix:275-278).Goals: decide the Linux-side driver shape, the firmware choice, the cache-maintenance contract, the recovery/authorization gate, and the first workload, each with a citation to vendor source, the TRM, in-tree kernel documentation, or an external reference; stage the work so early tasks need no board and no register write.
Non-Goals: implementing any of the drivers or firmware described here (this is a proposal); choosing the K230 mailbox hardware driver (its register layout has not been read into this project); deciding LoRa, battery/charger, or keyboard-base ownership; giving CPU0 any ability to reset CPU1 or Linux automatically; bringing up RT-Smart.
Does the vendor kernel or SDK already have one? No. A direct read of the
pinned kernel source (/nix/store/hn11x8zd5linl193d8q0k9k99b46zqbm-linux-xuantie-k230-src,
pinned by nix/kernel-src.nix from ruyisdk/linux-xuantie-kernel) found:
*k230*mailbox*, *k230*rproc*, or *k230*remoteproc*
anywhere in the tree, and no "k230" or "canaan" string in
drivers/mailbox/, drivers/remoteproc/, drivers/rpmsg/, or
drivers/watchdog/.drivers/misc/canaan/ exists but only holds ai2d, gnne, and mmz —
the AI-accelerator and memory-zone helpers, nothing inter-core.mailbox or reserved-memory/rpmsg/remoteproc property anywhere in
arch/riscv/boot/dts/canaan/k230.dtsi.k230-amp.c / amp_test.c
(https://github.com/kendryte/k230_sdk/blob/main/src/little/linux/drivers/misc/canaan/k230-amp.c,
reviewed in docs/research/second-core-feasibility.md, “Vendor AMP source
establishes a release contract, not SMP support”) is a raw misc-device
driver: open("/dev/k230-amp"), map a DT-selected region, load an
RT-Smart image, flush it from the calling CPU’s cache by hand, write the
CPU1 reset-vector register, then the CPU1_RST_CTL sequence — an ioctl
loader, not a remoteproc_ops implementation. It creates no
struct rproc, no virtio device, no resource table. Its release sequence
is exactly the primitive this design reuses; its code is not, because it
hardcodes vendor addresses and gives Linux no generic start/stop/status
interface.By contrast, this exact pinned kernel tree already carries, unmodified from
mainline, a same-vintage T-Head sibling SoC’s mailbox and rpmsg drivers —
drivers/mailbox/th1520-mailbox.c (XuanTie TH1520, Alibaba, 2024) and
drivers/rpmsg/th1520_rpmsg.c — as an architectural precedent, though
neither is wired into any device tree in this tree and TH1520’s mailbox
register layout is not K230’s. There is no TH1520 remoteproc driver in this
tree either; th1520_rpmsg.c implements its own lightweight rpmsg-over-mailbox
client directly (virtio-based, but not via drivers/remoteproc/), which is
a second usable pattern if a full remoteproc load/boot lifecycle turns out
to be unnecessary for a firmware image Linux never actually loads from disk
in the first version (see Decision 5).
Mainline update (2026-10-12): the binding text below is superseded. The
daily kernel is mainline v7.3-rc5 (nix/kernel-mainline-src.nix), not the
vendor 6.6 tree. On mainline the controller is rst: reset-controller@91101000,
compatible = "canaan,k230-rst", #reset-cells = <1>, consumed as
resets = <&rst RST_CPU0> (canaan,k230-rst.h); the vendor four-cell form,
sysctl_reset, canaan-k230-reset.h and the K230_RESET_* macros named in
the next bullets do not exist there. reset-k230.c supports only .reset (a
pulse) for RST_CPU0; assert/deassert return -EOPNOTSUPP, and the TRM’s
cpu0_reset_req is a self-clearing W1T bit, so there is no held reset to
assert. Start is therefore vector write plus reset_control_reset(); stop is
an open task 5.2 question. There is no sysctl_boot node; the vector register
0x91102100 lies outside the sysclk window (0x91102000+0x40) and is
mapped privately by the new node’s own reg. RST_CPU1 is the core Linux runs
on and must never be requested. Full citations:
docs/evidence/second-core/mainline-reset-binding-decision.md. The vendor-tree
analysis below is kept as the origin of the register facts and still describes
the vendor kernel the shipped image boots.
Reset control and the vector registers. The TRM- and source-grounded
register facts already collected in
docs/research/second-core-feasibility.md and
docs/evidence/second-core/ map directly onto Linux abstractions already
present in the pinned kernel, which this driver should use instead of a raw
ioremap the way the vendor driver does:
sysctl_reset) is at 0x91101000, declared in
k230.dtsi:233-241 as compatible = "canaan,k230-sysctl-reset". It is
already bound by drivers/reset/reset-k230.c, which registers a generic
reset_controller_dev (k230_reset_probe, reset_controller_register)
over this exact block and is already exercised by Linux today: its own
k230_restart() restart-notifier writes to this address range
(SYSCTL_BOOT_BASE_ADDR + CPU0_RST_CTL at drivers/reset/reset-k230.c:311-323,
though that offset — 0x60 inside sysctl_boot, not the CPU0 reset-request
bit — is a whole-system restart path and should not be confused with the
per-core CPU0_RST_CTL/CPU1_RST_CTL request bits described next; this is
named only to show the register block is not a new, untouched surface).
The reset lines this design needs are already named in
include/dt-bindings/reset/canaan-k230-reset.h:
K230_RESET_CPU0_REG_OFFSET 0x4 / K230_RESET_CPU1_REG_OFFSET 0xc
(matching the TRM’s CPU0_RST_CTL/CPU1_RST_CTL at 0x91101004/0x9110100c,
section 2.1.4), each K230_RESET_TYPE_CPU, done bit 12, assert bit 0, plus
a separate K230_RESET_CPU0_FLUSH_REG_OFFSET 0x4 / ..._ASSERT_BIT 4 pair
for the documented L2-flush-request bit. A K230 remoteproc driver should
request its reset line the ordinary way —
resets = <&sysctl_reset 0x4 0 12 0>; in DT, consumed with
devm_reset_control_get_exclusive() and reset_control_assert()/
deassert() — instead of a second, competing raw MMIO mapping of the same
physical registers the reset-controller driver already owns.sysctl_boot at 0x91102000 (k230.dtsi:244-247) is declared only
compatible = "simple-bus", with no children and no driver claiming it —
it is free for a new consumer. This is where the CPU reset-vector
registers live: pinned U-Boot’s boot_baremetal path
(arch/riscv/cpu/k230/cpu.c:125-160) writes CPU0’s vector at
0x91102100 and asserts/deasserts CPU0_RST_CTL at 0x91101004; the
2026-09-26 stage-1 audit separately records CPU1’s vector write at
0x91102104. No existing Linux binding names this register; the
remoteproc driver either ioremaps this one small range itself (as the
restart driver already does for its own purposes in the same block) or a
small syscon/regmap wrapper node is added first. Which of those is worth a
separate node is an open, small design decision left to the implementing
task, not resolved here. The exact width and side effects of a write to
the vector register beyond what boot_baremetal already performs are not
independently reconfirmed by this change — this design reuses the
pinned, already-executed sequence rather than deriving a new one.nix/dts/k230-tdisplay.dts:47-57 already carries a
precedent reserved-memory node with no-map for the splash framebuffer.
The AMP carveout for CPU0’s firmware and its shared ring follows the same
pattern, sized and placed to (a) sit inside the live 1 GiB DRAM window
Linux otherwise manages (docs/evidence/second-core/heartbeat-host.md
records 0x00000000..0x3fffffff with only the framebuffer reserved at
0x10000000..0x103fffff) and (b) not silently overlap the heartbeat’s
already-used 0x07000000..0x07004fff scratch range, which sits inside
that same normal DRAM window and is therefore ordinary allocatable RAM to
Linux today, not a hardware-reserved region. A reserved-memory/no-map
node is mandatory before any Linux-coexistence step reuses that or any
other address, exactly as the heartbeat change’s own task 4.1 already
required.drivers/remoteproc/remoteproc_core.c, remoteproc_virtio.c,
drivers/rpmsg/virtio_rpmsg_bus.c, documented in-tree at
Documentation/staging/remoteproc.rst and Documentation/staging/rpmsg.rst
(“the remoteproc framework allows different platforms/architectures to
control (power on, load firmware, power off) those remote processors…
this framework also adds rpmsg virtio devices”). The resource-table
convention itself (a .resource_table ELF section describing vdevs,
vrings, and carveouts, parsed by remoteproc_elf_loader.c) is the OpenAMP
project’s own format
(https://github.com/OpenAMP/open-amp/blob/main/lib/include/openamp/remoteproc.h;
https://openamp.readthedocs.io/en/v2025.10.0/lopper/specification/source/chapter5-remoteproc.html) —
a firmware image only needs to embed that table once it actually speaks
virtio/rpmsg, which step zero (Decision 5) deliberately defers.mailbox driver or DT node exists for K230 in the pinned kernels
(verified above; mainline also has only the reset-controller’s RST_MAILBOX
entry). The earlier text of this design said the layout was unread and
placed it in TRM section 2.4; section 2.4 is the interrupt table, and the
mailbox is section 2.9, base 0x9110_4000.
docs/research/second-core-feasibility.md (“TRM mailbox register map”)
now records the map: four interrupt-count groups per direction
(SET/CLEAR/STATUS/ERR/EN), 128 one-bit interlock registers at
0xA0-0x29C, and the interrupt sources MB_CPU12CPU0_0/1 (93, 94) and
MB_CPU02CPU1_0/1 (95, 96). The group-to-interrupt-line mapping, the lock
acquire semantics and CPU0-side PLIC routing remain UNVERIFIED, so no
mailbox driver or firmware is written against it by this change.
th1520-mailbox.c is a naming cross-check only.Because of that gap, this design avoids a hardware-mailbox dependency for
the steps it actually proposes (Decisions 5-6): Linux’s own mailbox
framework (drivers/mailbox/mailbox.c) already supports a polling
completion mode (txdone_poll) for controllers with no interrupt-driven
acknowledgement, so a “mailbox” backed purely by a status word in the same
non-cacheable shared region can drive the standard virtio_rpmsg_bus/
remoteproc_virtio stack unmodified, without touching the real K230
mailbox IP until its registers are separately read and a task exists to
write a real driver for it.
| Option | K230/C908 support today | Nix cross build complexity | Verdict |
|---|---|---|---|
| Bare-metal (extend the heartbeat) | Physically proved on 2026-10-12: tools/small-core-heartbeat.{S,ld} runs on CPU0 via boot_baremetal 0 while CPU1 holds the U-Boot prompt (docs/evidence/second-core/heartbeat-physical-2026-10-12/README.md). Earlier text here claimed this before any run; the only prior physical CPU0 evidence was the SPL identity probe (docs/evidence/second-core/cpu0-identity-physical-trial.md). | Smallest possible: tools/test-small-core-heartbeat.sh invokes host clang/lld directly (--target=riscv64-unknown-elf), no nixpkgs cross toolchain package, no OS tree to build. | Recommended first step. |
| Zephyr | No K230 or C908 board/SoC support. A 2025-era PR adds T-Head C906 support for Sophgo’s Milk-V Duo (CV1800B/SG2002, PR #69594) — different vendor, different core, and even that support needed a Zephyr timer-driver change (mtime-is-32bits) for a T-Head core lacking a standard 64-bit MTIME. No public evidence of C908 or K230 work. | Would require writing a whole new SoC+board port (Kconfig, devicetree bindings, CLINT/PLIC quirks, boot code) from nothing, then getting Zephyr’s own build system working inside this project’s Nix cross environment — a multi-week, uncertain undertaking. | Not recommended as a first step; revisit only if a later workload needs Zephyr’s driver/RTOS ecosystem specifically. |
| FreeRTOS | Generic RV32I/RV64I + CLINT port exists upstream (FreeRTOS/Source/Portable/.../RISC-V, configCLINT_BASE_ADDRESS), but no K230 BSP. | Buildable with the same lightweight clang/lld approach as the heartbeat (FreeRTOS’s RISC-V port is a handful of C/asm files, not a full OS tree), but still needs a hand-written CLINT tick-timer and trap-vector port validated against K230’s actual CLINT wiring (k230.dtsi:255-259, wired only to cpu0_intc today). | Medium effort; worth it only once a workload needs preemptive multitasking on CPU0, which none of the current candidates (Decision 5/6) do. |
| RT-Smart (vendor’s own choice) | Fully supported — it is the vendor’s shipped big-core RTOS — but this project carries no RT-Smart payload today, and the vendor’s own AMP driver (k230-amp.c) demonstrates only a boot-loader/cache-flush contract, not an rpmsg/mailbox IPC contract to reuse. | Largest lift: a second, independent OS source tree with its own toolchain assumptions, no existing Nix packaging in this repo, and no build precedent to extend (unlike the heartbeat’s plain clang/lld invocation). | Not recommended as a first step; would only be reconsidered if a workload specifically needed RT-Smart’s own driver ecosystem (e.g. its NPU/DSP support), which none of the current candidates do. |
Recommendation: extend tools/small-core-heartbeat.{S,ld} into the
step-zero firmware (Decision 5) directly. It is the only option with
existing physical proof on this board, and its build has effectively zero
Nix cross complexity because it never enters the nixpkgs riscv64 cross
toolchain at all.
No document in hand states a CPU0/CPU1 cache-coherency contract (Decision 1
above, and docs/research/second-core-feasibility.md, “What the vendor
register map proves—and does not”). Until one exists, every shared buffer
between CPU0 and Linux SHALL follow the same discipline this project’s own
heartbeat probe already uses and the vendor’s own AMP driver independently
converges on:
no-map and mapped non-cacheable on the Linux
side — matching the existing reserved-memory/no-map precedent
(nix/dts/k230-tdisplay.dts:47-57) and this SoC’s existing, broader
dma-noncoherent; property at the soc node
(k230.dtsi:207, also present per-controller at :346 and :360) —
i.e. Linux already treats this SoC’s bus masters as non-coherent for DMA
purposes; extending that same non-coherent assumption to the CPU0 shared
ring is a familiar contract on this board, not a new one. virtio_ring.c
already conditions its barriers (dma_wmb()/dma_rmb() vs. plain
wmb()/rmb()) on the transport’s declared coherence, so a
dma-noncoherent virtio transport is a supported, not exotic, case.l2cache.ciall encoding U-Boot’s cache.c:158-161 already
defines and the heartbeat firmware already issues
(tools/small-core-heartbeat.S:25-28, .word 0x0170000b), plus a
fence rw, rw before it. This is CPU0’s private-L2 flush; it says
nothing about Linux’s own cache state and does not replace step 1.reserved-memory child with an explicit no-map; nothing shares a page
between a cacheable Linux allocation and CPU0-visible state.Every task that writes CPU0’s reset, vector, or reset-controller register
needs the board operator’s explicit authorization, per AGENTS.md, at the
time it runs. 2026-09-28 update: the external SD-card-reader restore
rehearsal both parent changes originally required
(the-system-runs-on-both-cores task 2.1/2.2,
docs/closeout/second-core-plan.md’s step 1) is waived by the operator’s
decision the same day: “we can easily fix the sd card damn. don’t worry
about recovery we’ve literally done that fine already before. i don’t want
to do a heartbeat test on a spare card.” No task in this change or its two
parents may require a separate spare/disposable card; every board step runs
on the normal card. Recovery, if a release write fails or hangs, is by the
already-proven U-Boot one-shot boot from boot-prev or ums/flash
reimaging (Task 2 below) — an AMP release writes the exact same
CPU0_RST_CTL/vector registers a Linux SMP release would have, and those
fallback routes already cover a hung or misbehaving board.
Resetting a crashed coprocessor without rebooting Linux. Because CPU0’s
reset-controller line (RST_CPU0, RMU offset 0x4) is
independent of CPU1’s (RST_CPU1, offset 0xc) in the same RMU block (TRM
section 2.1.4), a Linux-side reset_control_reset() pulse on the CPU0 line
alone (the only operation mainline supports for it; see the mainline update
in Decision 1) should not touch CPU1/Linux execution. This is a reasonable
inference from the register map, not yet a board-proved claim: the TRM’s
CPU power-flow text also requires “a completed NOC low-power handshake
before a power transition” (section 2.3.3), which this design has not
tested for CPU0 alone. A bounded board task (Task 5.3 below) proves or
disproves “CPU0 can be reset and restarted while Linux keeps running and
stays responsive” before this design’s recovery story is trusted beyond a
successful full-board reset.
A hardware watchdog already exists in QEMU’s model but has no Linux driver
here. QEMU’s k230 machine documents two K230 watchdog-timer instances
among its modeled devices, and the pinned kernel has no K230 watchdog driver
(drivers/watchdog/ search, Decision 1). If K230 silicon has a standalone
WDT peripheral independent of CPU0/CPU1, a plain watchdog driver detecting
“Linux stopped petting the dog” would be a simpler, lower-risk answer to
“has Linux hung” than routing that question through CPU0 at all — that is a
different, smaller capability with no coprocessor involved, and this
proposal does not claim CPU0 is the only or best way to detect a hang. What
CPU0 can add beyond a hardware WDT is choosing how to react (see Decision
6) rather than only forcing a blind full reset; that is the value this
change actually proposes.
Before any peripheral or workload decision, this design’s first Linux-coexistence firmware slice reuses the heartbeat’s proven layout — scalar RV64, no runtime, one bounded loop — extended with a small request/response ring in the same style of dedicated scratch pages the heartbeat already uses, instead of a monotonic counter:
l2cache.ciall before returning to the poll
loop — the same discipline as Decision 3.remoteproc/virtio_rpmsg_bus
skeleton is layered on top later (Decision 1’s “resource table” note),
this ring is a plausible seed for its vring backing store, but step zero
itself does not commit to the full virtio/rpmsg stack — it only proves the
memory/cache contract and the release/observe/recover loop end to end with
two-way traffic instead of the heartbeat’s one-way counter.tools/small-core-echo.{S,ld}: slot page at
PAYLOAD_BASE + 0x2000, a request line, per-sequence response lines
indexed by req_seq & 7, a status line with a separate slow heartbeat, a
fence plus l2cache.ciall before every request read and after every
write, and no long delay in the poll loop (the heartbeat’s uncached
~2.5 s delay would otherwise be the response latency). Layout and limits
are in the .S header and docs/evidence/second-core/echo-runbook.md.This is deliberately the smallest possible extension of already-proved work, matching this project’s evidence-first discipline: prove the mechanism before committing to a peripheral or a driver framework.
Evaluated against value, independence, and I/O ownership conflict with
Linux (docs/research/board-capability-inventory.md):
| Candidate | Value | Independence | I/O ownership conflict |
|---|---|---|---|
| Keyboard-base scanning (TCA8418/XL9555) | High, but only once the accessory exists — the user’s base has no connector hardware yet, so nothing can be tested on real hardware regardless of SMP/AMP. | Needs an I2C bus CPU0 does not currently have any wiring or driver for. | Shares the I2C4-alt bus with the charger/fuel-gauge/AHT20 parts (board-capability-inventory.md row 129’s noted “shared UART3 conflict”); contested even once hardware exists. |
| LoRa timing (SX1262/LR2021 over SPI0) | Medium — a real headline feature, but niche. | Needs SPI0, which the DT currently disables entirely (status = "disabled" on all three SPI controllers). | This project’s own roadmap already plans to give Linux spidev ownership of SPI0 for RadioLib (board-capability-inventory.md, “Effort M”, already CONFIG_SPI_SPIDEV=y/CONFIG_SPI_DW_MMIO=y in the pinned defconfig) — handing the same bus to CPU0 would preempt a Linux feature already in motion, not a vacant one. |
| Battery/charger monitoring (BQ25896/BQ27220) | Very high — “the single most-requested handheld capability” per the same inventory — but for exactly that reason Linux is the more likely long-term owner: the charger driver (bq25890_charger.c) already covers the exact chip ID in the pinned kernel, and only the fuel-gauge driver is missing. | Same I2C4-alt bus as the keyboard-base parts; register writes there are explicitly flagged risky in existing research. | Would contest Linux’s own probable near-term ownership of the same bus and chips. |
| Hardware watchdog / heartbeat monitor | Real safety value: detect a hung Linux hart and preserve a fault record across a reset, independent of any accessory. | Touches no shared bus and no peripheral Linux wants — only the RMU/vector registers already in scope for this change and a private reserved-memory region. Directly extends already-proved, already-evidenced work. | None. |
Recommendation: the watchdog/heartbeat monitor, built directly on step
zero’s ring. CPU0 watches a liveness counter Linux increments on a timer; if
it stops advancing within a budget, CPU0 writes a fault record (last-seen
counter value, a timestamp source, whatever minimal state fits) into a
second reserved page and keeps running, taking no reset action of its
own. Reading that record after a manual recovery is the acceptance
criterion for this change. Explicitly out of scope for this change:
CPU0 asserting CPU1’s or the whole board’s reset automatically. That is a
materially larger hazard — a false-positive reset of a live Linux system —
and needs its own proposal, its own authorization, and its own repeated
board evidence once detection alone is proved, matching this project’s
existing discipline of not promising a capability before its narrower
prerequisite is proved (the-system-enables-proven-c908-extensions’s
acceptance-before-performance rule).
| Step | Host build | QEMU | Board trace |
|---|---|---|---|
| 1. Recovery route | — | — | Waived 2026-09-28 (operator decision, see Section 4): fallback is the proven U-Boot one-shot/ums/reimaging routes, on the normal card, not a rehearsed external-reader restore |
| 2. Step-zero echo/ping firmware | Required: disassembly/footprint/no-V check, extending tools/test-small-core-heartbeat.sh’s method | Available, 2026-10-12: -M k230 -bios none -device loader,file=BIN,addr=0x7000000,cpu-num=0 runs a standalone image on the single modeled C908 hart (no -kernel; direct boot demands OpenSBI and a DTB). The poll/echo state machine is exercised there by tools/small-core-qemu-probe.py; transcript in docs/evidence/second-core/qemu-standalone-cpu0.md. The model has no cache behavior and no CPU release, so it proves logic only | Required: boot_baremetal 0 release and readback, with explicit authorization at the time and a fallback recovery route confirmed |
| 3. Reserved memory + read-only driver skeleton | Required: nix build .#deviceTree; kernel module builds | Not applicable (no execution claim) | Not applicable |
| 4. Linux-driven CPU0 start/stop | Required: driver builds against the pinned kernel | Not applicable (QEMU’s k230 machine does not model RMU/reset-control registers or per-core release) | Required: release, echo round-trip, and stop-without-reboot, with explicit authorization at the time and a fallback recovery route confirmed |
| 5. Watchdog detection | Required: host fixture for the fault-record format | Not applicable | Required: a deliberately frozen liveness counter is detected and recorded, then read back after a manual recovery |
A QEMU result never substitutes for a board trace on any step that claims
CPU0 actually executed, matching .skills/k230-spec-change/SKILL.md’s
existing rule that QEMU’s k230 machine “models none” of this board’s real
peripherals; the possible exception noted above is a standalone CPU0 image
with no peripheral claim at all, and only once confirmed.
devm_reset_control_get_exclusive() against the existing
canaan,k230-sysctl-reset binding instead of a second raw ioremap of
the same physical registers (Decision 1).Land this proposal, then work strictly in the staged order in tasks.md:
source/register grounding first (no board), then the inherited recovery
rehearsal (board, read/verify only), then step-zero firmware (host, then
board), then the reserved-memory and driver skeleton (host/cross-build
only), then the Linux-driven start/stop (board, first register-writing
Linux code), then the watchdog (board). Each stage’s board task is blocked
on the previous stage’s evidence being committed, exactly as both parent
changes already practiced. No normal image or boot behavior changes until a
later, separate change proposes making any of this default-on.
docs/research/second-core-feasibility.md
citing the exact TRM page/section, reviewed against the existing
th1520-mailbox.c layout only as a naming cross-check, not a register
source (source/document proof, no board or code).
DONE 2026-10-12 (document proof). The TRM does publish the map, in
section 2.9 Mailbox (not 2.4, which is the interrupt table): base
0x9110_4000, interrupt-count groups, 128 interlock registers, sources
93-96. Recorded in docs/research/second-core-feasibility.md (“TRM
mailbox register map”), with the file hash, PDF pages and the UNVERIFIED
items (group-to-line routing, lock semantics, CPU0 PLIC wiring). No driver
written against it.resets = <&sysctl_reset 0x4 0 12 0>; against
sysctl_reset@91101000 (canaan,k230-sysctl-reset,
include/dt-bindings/reset/canaan-k230-reset.h
K230_RESET_CPU0_* macros), and decide whether the CPU0 vector register
at sysctl_boot@91102000 offset 0x100 gets its own small syscon node or
a private ioremap in the new driver, citing the precedent
(drivers/reset/reset-k230.c’s own ioremap of the same block for its
restart path) either way. Verify with a committed decision note under
docs/evidence/second-core/ and openspec validate the-small-core-runs-as-a-coprocessor --strict (document proof, no board
or code).
DONE 2026-10-12 (document proof). Superseded for the mainline kernel: the
vendor-tree binding named above does not exist there. Decision:
resets = <&rst RST_CPU0>, .reset-only (pulse; assert/deassert are
-EOPNOTSUPP), vector at 0x91102100 mapped privately from the node’s
own reg (no syscon), never request RST_CPU1. Note and citations:
docs/evidence/second-core/mainline-reset-binding-decision.md. Verified
with openspec validate the-small-core-runs-as-a-coprocessor --strict.k230 machine (single modeled core,
described as “the little core (c908)”) can boot a standalone,
Linux-free CPU0 firmware image directly, without the normal boot chain,
as a possible QEMU evidence class for step 2. Record the exact invocation
tried and its result, including a firm “no” if the machine cannot be
targeted that way. Verify with the committed transcript under
docs/evidence/second-core/ (host/QEMU proof only; this task makes no
board claim).
DONE 2026-10-12 (QEMU proof only). A standalone image boots with
-M k230 -bios none -device loader,...,cpu-num=0; -kernel paths are
refused. One modeled hart; no CPU release or cache model. Transcript:
docs/evidence/second-core/qemu-standalone-cpu0.md.docs/closeout/second-core-plan.md’s step 1, and left open by
the-system-runs-on-both-cores tasks 2.1/2.2, is waived by the operator’s
2026-09-28 decision: “we can easily fix the sd card damn. don’t worry
about recovery we’ve literally done that fine already before. i don’t
want to do a heartbeat test on a spare card.” No disposable/spare card is
required for any heartbeat or coprocessor board step in this change or
either parent; every board step runs on the normal card. The fallback
recovery route for a failed or hung release is the already-proven U-Boot
one-shot boot from boot-prev
(docs/evidence/card-shell/bottom-band-flicker/kernel-patch-boot-panic.md)
or ums/flash reimaging (docs/uboot-ums.md) — not a rehearsed
external-reader restore. This does not waive per-write authorization:
each board step that writes a CPU0 reset, vector, or reset-controller
register still needs the user’s explicit authorization at the time it
runs (see tasks 3.3, 5.1, 6.2 below).tools/small-core-heartbeat.{S,ld} (or a sibling file
under tools/) into a scalar RV64 payload that polls a request slot in
its scratch pages, echoes it into a response slot, and issues the pinned
l2cache.ciall encoding after every write, with a host check for entry
point, footprint, absence of V instructions, and the new poll/echo
instruction sequence. Verify with a new
bash tools/test-small-core-coprocessor-echo.sh (host binary proof, no
board), following the existing test-small-core-heartbeat.sh method.
DONE 2026-10-12 (host binary proof, no board). tools/small-core-echo.{S,ld}
(224 bytes, load address a single linker constant, slot layout in the .S
header) and bash tools/test-small-core-coprocessor-echo.sh: PASS.docs/evidence/second-core/qemu-standalone-cpu0.md
(tools/small-core-qemu-probe.py).boot_baremetal 0 sequence exactly as
the heartbeat runbook already does, write at least three distinct request
values from the U-Boot prompt, and read back three correct, freshly
produced responses (not a stale cached value), then restore normal boot.
Runs on the normal card; recovery, if needed, is by the fallback routes
named in task 2.1 (no disposable card). Verify with a timestamped board
transcript committed under docs/evidence/second-core/ (physical CPU0
execution proof; any hang, static response, or wrong echo fails this task).
Procedure, expected cells and payload hash/CRC: docs/evidence/second-core/echo-runbook.md.
DONE 2026-10-12 (physical board, serial transcripts; operator “Yes, go”):
four distinct requests answered correctly by CPU0 (11111112/eeeeeeee,
deadbef0/21524110, 00000000/00000000, 12345679/edcba987), each line
read once after its request, never-requested line’s rsp_seq 0, counters
served=4 last_seq=4, CPU1 prompt alive, Linux restored. Required the
--evict cache workaround (U-Boot has no dcache command; without it
release 2 was 0/4, inconclusive). Evidence:
docs/evidence/second-core/echo-physical-2026-10-12/README.md. 4.1 Add a reserved-memory/no-map node for the CPU0 firmware image
and its shared ring to the experimental device tree, sized and placed to
avoid the live 1 GiB DRAM window’s existing framebuffer reservation and
to formally reserve the heartbeat/echo scratch range from ordinary Linux
allocation, following the precedent at nix/dts/k230-tdisplay.dts:47-57.
Verify with nix build .#deviceTree and a decompiled reserved-memory
node check (DT build proof, not board).
DONE 2026-10-12 (DT build proof): on the mainline tree, not the vendor
.#deviceTree (per the binding decision): opt-in
.#deviceTreeMainlineDrmHotplugCpu0 carries cpu0-firmware@7000000
(1 MiB, no-map) and remoteproc@91102100; decompiled and checked; the
daily tree’s derivation is unchanged. Evidence: docs/evidence/second-core/remoteproc-skeleton-build.md.
4.2 (Mainline binding per docs/evidence/second-core/mainline-reset-binding-decision.md: &rst/RST_CPU0, own reg for 0x91102100, needs CONFIG_REMOTEPROC.) Write a minimal K230 remoteproc driver skeleton: it binds to a new
DT node, requests the CPU0 line from &sysctl_reset via
devm_reset_control_get_exclusive(), maps the reserved region from task
4.1, and exposes read-only status (whether the reset-controller reports
CPU0 held in reset) through the standard remoteproc sysfs/state
interface. It performs no reset, vector, or power write in this task.
Verify with a kernel module build against the pinned kernel tree and a
host-side checkpatch.pl/build-log proof (cross-build proof, not board).
DONE 2026-10-12 (cross-build proof): nix/patches/mainline/k230_cpu0_rproc.c
built in-tree as a module by .#kernelMainlineDrmRproc (daily kernel plus
CONFIG_REMOTEPROC); checkpatch --strict clean; refuses any reset but
RST_CPU0; links no reset write. Reset “held” status is reported as
reset_control_status()’s code (reset-k230.c has no .status). Evidence: docs/evidence/second-core/remoteproc-skeleton-build.md.
4.3 Cite, in the driver’s kernel-doc or a comment, why no mailbox
hardware is used yet (task 1.1’s TRM gap) and how the poll-mode
txdone_poll mailbox path is expected to attach once a firmware image
actually speaks virtio/rpmsg (design.md Decision 1/5). Verify with
openspec validate the-small-core-runs-as-a-coprocessor --strict
(document-consistency proof).
DONE 2026-10-12: the driver’s header comment; openspec validate --strict
passes. Evidence: docs/evidence/second-core/remoteproc-skeleton-build.md.
sysctl_boot+0x100, then
reset_control_deassert() on the CPU0 line) with the echo firmware from
task 3 loaded into the reserved region from task 4.1, triggered from
Linux userspace (e.g. the standard remoteproc state sysfs attribute),
and prove a request/response round trip with Linux fully booted and the
shell responsive. Runs on the normal card; recovery, if needed, is by the
fallback routes named in task 2.1 (no disposable card). Verify with a
board console transcript and Linux dmesg/sysfs capture committed under
docs/evidence/second-core/ (physical Linux-coexistence proof).
DONE 2026-10-12 (physical board, one serial session plus a native grim
capture; operator “yeah go for it”; one-off boot of the trial kernel/DT,
installed default unchanged and restored): echo start on
remoteproc0 loaded small-core-echo.bin (224 bytes), wrote
0x07000000 to the vector and pulsed RST_CPU0 with
reset_control_reset() (the binding decision supersedes deassert:
CPU0 has only a pulse). 1010 of 1010 requests answered correctly through
the driver’s cpu0_echo attribute (latency 66-264 us, poll-granular),
with systemd running, shell/seatd active, sway IPC answering and a
grim frame captured after the start and again after a 45 s hold. No camera; the Svpbmt NC mapping
is inferred from config, not inspected. Evidence:
docs/evidence/second-core/linux-start-2026-10-12/README.md.reset_control_assert() on the CPU0 line only) and prove CPU0 parks
again without a board reset, with Linux still running and the shell still
responsive throughout. Verify with the same transcript style as 5.1,
showing the stop, a repeated start, and a final stop (physical proof of
restart-without-reboot).docs/evidence/second-core/ (physical
detection proof). Non-goal, not a task in this change: CPU0 asserting
any reset automatically in response to a detected stall.Grounding: docs/evidence/second-core/README.md records the decision
against each prerequisite; docs/research/second-core-feasibility.md traces
the pinned firmware/kernel and vendor AMP sources. design.md in
the-small-core-runs-as-a-coprocessor traces the pinned kernel’s absence of
a K230 remoteproc/mailbox driver, the reset-controller binding (mainline
canaan,k230-rst; the vendor canaan,k230-sysctl-reset form was superseded,
see docs/evidence/second-core/mainline-reset-binding-decision.md), and the
TRM section 2.9 mailbox register map with its unresolved routing and lock
semantics.
Before a later change may release a second core for Linux SMP, it SHALL
have source- or board-grounded evidence for the second hart ID and
reset/vector protocol, OpenSBI domain/HSM behavior, local timer and
IPI/PLIC routes, CPU ISA and cache description, and a CPU-to-CPU
shared-memory coherency contract. This SMP path remains blocked: both
physical cores have been directly measured reading CSR.MHARTID = 0
(docs/evidence/second-core/cpu0-identity-physical-trial.md), which breaks
OpenSBI’s hart table, warm-entry scratch/stack selection, and HSM/IPI
targeting before interrupt routing or coherency are even reached, and no
document in hand supplies a second per-core identity signal to fix it.
A separate AMP (coprocessor) path SHALL instead:
canaan,k230-rst binding
(resets = <&rst RST_CPU0>, drivers/reset/reset-k230.c,
include/dt-bindings/reset/canaan,k230-rst.h) rather than a redundant raw
MMIO mapping of the same registers. CPU0 supports only .reset (a pulse)
there, so a start is the CPU0 vector write at 0x91102100 (the address the
pinned boot_baremetal sequence already uses,
arch/riscv/cpu/k230/cpu.c:125-160) followed by reset_control_reset().
The vector register is mapped privately from the driver’s own DT reg,
and the driver SHALL never request RST_CPU1. A stop mechanism is not
fixed by this requirement; it is decided under the stop task. (The vendor
tree’s canaan,k230-sysctl-reset four-cell binding and
K230_RESET_CPU0_* macros named in the original text do not exist on the
mainline kernel and are superseded.)no-map
reserved-memory device-tree node, following the existing splash
framebuffer precedent (nix/dts/k230-tdisplay.dts:47-57), and map that
region non-cacheably on the Linux side rather than sharing a cacheable
page between CPU0 and Linux.docs/research/second-core-feasibility.md) has
its interrupt routing and lock semantics confirmed on the board; a
poll-mode software doorbell in the same non-cacheable region MAY stand in
for it.Grounding: docs/closeout/second-core-plan.md’s recommendation and “Next 3
concrete steps”; the-small-core-runs-as-a-coprocessor/design.md’s staged
decisions and evidence-class table; tools/small-core-heartbeat.{S,ld} and
docs/evidence/second-core/heartbeat-*.md as the already-proved foundation.
The external-reader recovery rehearsal this stage list originally named is
waived by the operator’s 2026-09-28 decision (see the requirement below).
The project SHALL stage CPU0 coprocessor bring-up as: source/register grounding, confirming a current fallback recovery route, a step-zero polling-ring firmware proof, a reserved-memory carveout with a read-only driver skeleton, Linux-driven runtime start/stop, and only then a first workload. It SHALL NOT skip a stage’s committed evidence to reach a later one, and it SHALL NOT write a CPU0 reset, vector, or reset-controller register without the operator’s explicit authorization at the time, per the requirement below.
Grounding: no TRM or vendor SDK document states a CPU0/CPU1 cache-coherency
contract; the vendor k230-amp.c driver and this project’s own
tools/small-core-heartbeat.S:25-28 both flush by hand rather than rely on
implicit coherency; the SoC’s dma-noncoherent; property already applies at
the DT soc node (k230.dtsi:207).
Any memory region shared between CPU0 firmware and Linux SHALL be a
no-map reserved-memory region mapped non-cacheably on the Linux side.
CPU0 firmware SHALL issue the pinned L2 cache-maintenance instruction after
any write it intends Linux to observe, and neither side SHALL infer
freshness from a second read of a location it may already hold cached.
Grounding: pinned U-Boot arch/riscv/cpu/k230/cpu.c:125-160 defines
CPU0’s reset/vector writes; nix/stage1.nix:176-180 puts SPL at raw
SD-card offsets. docs/evidence/card-shell/bottom-band-flicker/ kernel-patch-boot-panic.md records a proven U-Boot one-shot recovery from
a bad boot, and docs/uboot-ums.md documents the ums/flash reimaging
route; both remain reachable without an external card reader or a
spare/disposable card.
Before any change writes a CPU0 reset, power, reset-vector, or
reset-controller register, the board operator SHALL hold explicit user
authorization for that specific session. No task SHALL require a separate
spare or disposable card; every board step in this bring-up SHALL run on
the normal card. If a release, stop, or restart write fails or hangs the
board, the operator SHALL recover using the already-proven U-Boot one-shot
boot from boot-prev or ums/flash reimaging, and SHALL record the
outcome of a failed or hung release separately from a successful one.
ums/flash reimaging route, on the normal card, and records the outcome
separately from the attempt’s own resultGrounding: the pinned stage-1 release path starts a separate physical core
under explicit software control, not a Linux-addressable hart; the vendor
k230-amp.c path requires a separate payload and cache-managed memory, not
Linux scheduling.
docs/research/board-capability-inventory.md records overlapping or
Linux-planned ownership for the LoRa SPI bus and the charger/fuel-gauge I2C
bus, and that the keyboard-base accessory has no connector hardware on the
board yet.
The project SHALL identify any CPU0 execution as independent physical execution under stage 1 or Linux control. It SHALL NOT claim a second Linux CPU, cache-coherent shared memory beyond the explicit contract above, working general interrupts, or safe general scheduling from that observation. It SHALL NOT wire a peripheral bus to CPU0 that is already planned or contested for Linux ownership without a separate, explicit ownership decision recorded against that peripheral’s own capability, and it SHALL NOT claim readiness for an accessory that has no hardware present on the board.
Draft proposal · In progress
Snapshot 5836ef1d113d · 2026-10-17 08:22 UTC
Next gateEstablish physical CPU0's CSR.MHARTID and a usable distinct
2026-09-28 scope decision — Linux SMP redirected to AMP, this change stays
open. The user has now formally decided against the Linux SMP outcome
this change describes and redirected the second-core project to a
coprocessor (AMP) model instead; see
the-small-core-runs-as-a-coprocessor/proposal.md for the decision and its
grounding. This change is not archived or withdrawn by that decision —
per AGENTS.md, only the user’s explicit confirmation closes it, and every
task below stays exactly as ticked or unticked as it was. What changes is
which of its stages remain live work: stage (a)‘s read-only board probes
(tasks 1.1-1.6, complete) and the recovery rehearsal (tasks 2.1/2.2, still
open) are the shared foundation and are carried into the new change’s own
task list rather than duplicated. Stage (b)‘s OpenSBI/DT hart-release
experiment (tasks 3.1/3.2), stage (c)‘s pre-Linux-shared-boot coherency
validation (task 4.1), and stage (d)‘s ISA-aware SMP scheduling
(task 5.1) are recorded as superseded: they exist only to make Linux itself
address CPU0 as a peer hart, which is no longer the goal. They are not
deleted, not ticked, and not claimed done — they remain honestly open,
pending the user’s decision on whether to archive this change once the AMP
work has landed.
2026-09-26 source correction. Pinned stage 1 boots Linux on physical
CPU1 (the large, RVV-capable core):
board/canaan/common/k230_img.c:276-285 releases CPU1 from CPU0, then
parks CPU0. The extra Linux CPU sought here is physical CPU0. The current
device-tree cpu@0 and OpenSBI hart 0 name Linux’s logical hart, not the
physical CPU0. This proposal remains the Linux SMP objective: both physical
cores must appear as Linux CPUs and ordinary scalar processes must be
schedulable on either. The separate CPU0 heartbeat/AMP proposal is suspended;
it does not satisfy this objective.
The K230 QEMU board author
reports that both physical cores read mhartid=0; the Linux DTS author
reports that physical CPU1 reads 0 and that inter-core coherence is unknown.
Those are firsthand reports, not measurements on this board. In pinned
OpenSBI 1.4, platform/generic/platform.c:95-132 reads DT reg for each
hart, while lib/sbi/sbi_scratch.c:24-32 returns the first table entry for
a given hart ID and include/sbi/riscv_asm.h:166 reads CSR_MHARTID for
the current hart. If the duplicate ID is confirmed, adding cpu@1 cannot
work: a K230-specific identity scheme must first be proven end-to-end in
OpenSBI, its HSM/IPI/timer paths, and Linux’s CPU entry path. The normal
boot image remains unchanged while this is investigated.
Right now every background job — Wi-Fi association, a video decode helper, a Python theme helper, a udev-triggered script — competes with the Sway compositor for the same single hart. A person notices this as the shell stuttering while the theme helper regenerates a wallpaper cache, or a decode helper stealing frames from the compositor during a card animation. A second usable hart would let that background work run without taking cycles from the thing being looked at.
Be honest about what that second hart actually is. docs/evidence/cpu-readiness.txt
records the current Linux hart reporting RVV and a 256 KiB L2; the K230 TRM
section 1.3.2 assigns exactly that RVV/256 KiB profile to the 1.6 GHz CPU1.
Pinned stage-1 release source and the live ISA/cache observation establish
that Linux runs on physical CPU1, although this board’s mhartid value has
not been measured in M-mode. The second core is the 800 MHz little core,
not a matching twin of the one running the shell today. Plain-terms benefit:
a background core for decode assistance, network/SDIO servicing, Python
helpers and the theme helper, run at half the clock of the compositor’s core
and — per the TRM’s CPU0/CPU1 split — without a vector unit. It is a place to
put work that should not stall the display, not a second compositor engine
and not a path to double interactive throughput.
That last property is also the main hazard. This project’s kernel now
carries an RVV path by default (the-system-enables-proven-c908-extensions,
modifying system/kernel: “the ordinary system uses physically proved
vectors”). A kernel built with V compiles vector instructions into library
and userspace code paths that assume the executing hart has RVV. RISC-V does
not require every hart in an SMP system to share the same instruction-set
extensions, and this SoC’s own two cores do not: CPU1 has RVV 1.0, CPU0 does
not (K230 TRM section 1.3.2; docs/research/second-core-feasibility.md).
Linux’s generic scheduler has no built-in concept of “this hart lacks an
extension the running binary needs” — a task or library call that uses a
vector instruction, migrated onto a hart without RVV, takes an illegal-
instruction trap, not a graceful fallback. Any SMP plan for this board is
therefore a heterogeneous-ISA scheduling problem before it is a throughput
problem.
The normal boot image does not add a cpu@1 node, write a reset or power
register, or change OpenSBI, U-Boot, or the kernel. A separately selected,
default-off SPL diagnostic has been built on the host and packaged for a
possible board trial; it is not installed. This change records a staged, evidence-gated
plan and the decision-quality bar each stage must clear before the next one
is attempted, matching .skills/k230-spec-change/SKILL.md’s grounding order
and docs/research/second-core-feasibility.md’s “minimal recoverable
experiment” and “passive handoff audit” sections:
tools/second-core-readiness.sh) to add the two documented read-only RMU/
PWR register reads (0x9110100c, 0x91103018, 0x9110301c — TRM sections
2.1.4 and 2.3.4) taken with a proven read-only MMIO method, and record
whether the kernel exposes an OpenSBI HSM hart-status query without a
Linux CPU up/down transition. Cross-check /proc/cpuinfo’s misa/uarch
and the live L2 size against the TRM’s CPU0/CPU1 table to sharpen, not
replace, the existing inference.mhartid, its known CPU0 reset vector/release controls, and
per-core PLIC/ACLINT or other usable IPI/timer routing. If the two
physical cores share mhartid=0, prove an alternate unique logical
identity from early M-mode through OpenSBI HSM, IPI, timer and Linux CPU
entry; DT reg = <1> alone is insufficient. Only then prepare a guarded
CPU0 release and two-CPU Linux DT. This stage is the first one that may
write a reset register and requires the recovery rehearsal below.None.
system/second-core-readiness: records the staged evidence-gated bring-up
plan itself — what each stage requires before the next may start, which
stages write hardware state, and the heterogeneous-ISA scheduling
constraint — as requirements the project is held to, not only a readiness
snapshot.The existing read-only collector has host fixtures and a partial board
capture; two PWR reads returned EPERM and remain unproven. This change also
adds a default-off uboot-k230-cpu0-identity-probe and a BootROM-loadable
stage1-cpu0-identity-probe package. Its source and host build evidence
are in docs/evidence/second-core/; the ordinary U-Boot and stage-1
derivations are unchanged. No experimental SPL has been installed, no CPU0
CSR has been measured on the board, and no second Linux CPU is enabled.
The physical trial awaits the current card’s verified raw-stage-1 backup
and external reader recovery route, then a board-operator session. Later
OpenSBI, DT and kernel work awaits identity, interrupt and coherency proof.
Current direction (2026-09-26): Linux SMP on physical CPU1 + CPU0. Pinned U-Boot source releases physical CPU1 to the U-Boot/OpenSBI/Linux chain and parks CPU0. The older CPU1-release options below describe the opposite boot arrangement and are retained as historical design exploration, not choices for this board’s current boot chain. The current target is to re-enter physical CPU0 into OpenSBI as a distinct Linux CPU. No separate heartbeat or AMP payload is an acceptance path for this change.
The immediate firmware obstacle is a possible duplicate CSR.MHARTID=0
on both physical cores (firsthand QEMU K230 author report, not yet measured
here). OpenSBI 1.4 generic reads DT CPU reg into a hart table, but its
hart-ID lookup returns the first matching entry; its current-hart helper
reads the CSR directly. A second DT node therefore cannot create a second
working SBI hart if IDs collide. Before implementation, establish whether
the K230 has another per-core identity, or whether an early M-mode
CPU0-specific entry can carry a virtual ID consistently through every
OpenSBI HSM, IPI, timer and Linux handoff. The CPU0 reset vector and
control writes are already present in pinned U-Boot
arch/riscv/cpu/k230/cpu.c:125-160; their existence does not close the
identity or interrupt route.
CPU0/CPU1 cache coherence is likewise unproven, and the vendor AMP path flushes shared buffers explicitly. A Linux SMP boot shares locks and page tables immediately, so a pre-Linux atomic/cache diagnostic or a Canaan coherency contract must precede that boot. For first SMP proof, use a scalar common ISA image with RVV disabled in kernel and userspace; do not rely on affinity to protect arbitrary migratable processes. No default image bytes change until these gates are satisfied.
Current recovery gate. The narrow CPU0 identity diagnostic patches
U-Boot SPL, which occupies raw SD-card offsets 1 MiB and 1.5 MiB
(nix/stage1.nix:176-180). A bad SPL can prevent U-Boot itself from
starting, so U-Boot one-shot boot and ums are not sufficient recovery
routes for this experiment. Before flashing an experimental SPL, preserve a
verified known-good card or a verified raw-stage-1 backup and confirm an
external card-reader write/restore route. The board operator must control
the serial/card session. If a later diagnostic only runs from RAM with
unchanged SPL/card bytes, use the existing U-Boot one-shot recovery path
for that session; a second physical card is not inherently required by a
RAM-only readout. The per-session recovery check remains mandatory for
any hardware-writing experiment.
See proposal.md and docs/research/second-core-feasibility.md (the full
source and boot-record audit this design continues), and the existing
openspec/specs/system/second-core-readiness/spec.md capability, which this
change modifies rather than replaces.
Established facts, all source- or board-grounded:
docs/evidence/cpu-readiness.txt and docs/evidence/second-core/* record
the current Linux hart reporting RVV and a 256 KiB L2, possible/
present/online all 0 (i.e. only hart 0 exists in this handoff), a live
device tree with only cpu@0, CONFIG_SMP=y/NR_CPUS=64 compiled in but
unused, and an OpenSBI banner reporting Platform HART Count : 1,
Domain0 HARTs : 0*, Platform HSM Device : ---.arch/riscv/boot/dts/canaan/k230.dtsi:28-69)
describes one CPU; its PLIC (:210-218) and CLINT (:255-259) reference
only that CPU’s interrupt controller.CPU1_RST_CTL at
0x9110100c (reset value 0x00002001; bit 0 cpu1_reset_req; bit 4 L2
flush request; bits 12-13 write-one-to-clear reset-done flags) and PWR
CPU1 control/status at 0x91103018/0x9110301c — but no CPU1 reset
vector, physical hart ID, PLIC context mapping, ACLINT wiring, SBI HSM
implementation, or CPU0/CPU1 cache-coherency contract.k230-amp.c driver is direct evidence of a working CPU1
release: it maps a reserved region, writes an RT-Smart image back from
cache, programs a CPU1 reset-vector register, and performs the
CPU1_RST_CTL writes — under an AMP contract (separate firmware image,
explicit shared-buffer cache maintenance, exclusive peripheral ownership),
not a Linux SMP one.the-system-enables-proven-c908-extensions (system/kernel, modified)
makes the ordinary kernel and Pixman RVV-by-default with a physically
proved fallback. That is the concrete reason a naive second Linux hart is
dangerous now: today every hart Linux schedules onto is CPU1-shaped, so
vector code paths never meet a hart that lacks V. A second hart that is
physically CPU0 breaks that invariant silently unless scheduling accounts
for it.Goals: record the staged, evidence-gated plan as enforceable requirements; state honestly which physical core the second hart probably is and what kind of workload it plausibly helps; specify the two hart- release mechanism options and what each needs before it can be chosen; name the authorization and recovery gate every hardware-writing stage must clear.
Non-Goals: adding cpu@1 to any device tree in this change; writing to
CPU1_RST_CTL, the PWR CPU1 registers, or any reset-vector register in this
change; choosing between the OpenSBI-platform-start and U-Boot-spin-table
release mechanisms (an open decision for stage (b)); bringing up the vendor
RT-Smart AMP payload (a different project with a different boundary, per
docs/research/second-core-feasibility.md “Vendor AMP source establishes a
release contract, not SMP support”); promising a performance number before
correctness and coherency are proven, matching the acceptance discipline
the-system-enables-proven-c908-extensions already established for RVV.
Layer: tools/ read-only collection, no kernel/DT/firmware change
(stage a). tools/second-core-readiness.sh already collects CPU
possible/present/online, the live cpus DT subtree, PLIC/CLINT
interrupts-extended, /proc/cpuinfo, and SBI/SMP kernel log lines,
entirely from files under /sys and /proc — no MMIO, no ecall, no CPU
state change. This design adds two more read-only fields to that same
script family, gated the same way the research doc already gates them:
0x9110100c (CPU1_RST_CTL), 0x91103018
and 0x9110301c (PWR CPU1 control/status), using only the operator’s
already-proven read-only MMIO method (/dev/mem opened read-only,
or a devmem2-style tool’s read path). No read-modify-write, no clear
of the W1C reset-done bits, no probe of adjacent registers. A reset
register read is informational only: it can show whether CPU1 is
currently held in reset, which is a fact worth having (it would falsify
“Linux already runs on CPU1” if CPU1 reads as still fully asserted while
Linux runs on the only enumerated hart) but it cannot itself establish
hart identity or a release protocol.<!-- UNVERIFIED -->, not inferred as absent capability —
Platform HSM Device : --- in the OpenSBI banner is already documented
as informational, not an acceptance test
(docs/research/second-core-feasibility.md, “OpenSBI and SMP
barriers”).
The alternative — skipping straight to a DT edit because the silicon
datasheet says two cores exist — is exactly what the existing
second-core-readiness capability already forbids (“A second-core
decision distinguishes handoff evidence from silicon capability”).Layer: OpenSBI platform + device tree, hart-release mechanism (stage b, not implemented by this change). Two candidate mechanisms, neither selected:
platform/generic/platform.c in the vendor SDK) counts harts
from /cpus; a K230-specific platform module would perform the
CPU1_RST_CTL deassertion and program the CPU1 reset vector itself,
inside hsm_start, the same shape as the vendor k230-amp.c driver’s
writes but issued by firmware instead of a Linux driver, and gated by a
verified physical hart ID and reset vector address this change does not
yet have. This keeps the release inside the firmware layer Linux
already trusts for HSM, at the cost of a K230-specific OpenSBI patch
this project would carry and maintain.CPU1_RST_CTL writes earlier, publishing a
riscv,spin-table cpu-release-addr the way non-HSM RISC-V platforms
do, then handing OpenSBI a device tree describing an already-parked
hart. This avoids an OpenSBI platform patch but requires U-Boot on this
board to gain the same CPU1-specific register knowledge, and it commits
to spin-table rather than HSM semantics for the second hart.
Both need the same missing prerequisite: a documented (Canaan-stated or
read-only-register-derived) physical hart ID, reset-vector address, and
PLIC/ACLINT context for CPU1. Per the existing capability’s requirement
(“Bring-up is gated by firmware, interrupt, and coherency evidence”),
this change does not pick one; a later change picks one once stage (a)
and a vendor statement or shipped source close that gap.Layer: kernel/firmware coherency validation (stage c, not implemented
by this change). Before any Linux shared-memory use of a second hart,
run an atomics/litmus-style stress (concurrent load-reserve/store-
conditional or AMO stress from both harts against shared cache lines) and
a timer/IPI stress (repeated cross-hart IPI and ACLINT timer delivery
under load). Neither the TRM nor the vendor SDK documents a CPU0/CPU1
cache-coherency or atomic-sharing contract; the DT’s dma-noncoherent
property is documented as concerning DMA only, not CPU-to-CPU coherence.
This stage is where that gap gets an empirical answer instead of staying
an assumption.
Layer: kernel scheduler, ISA-aware constraint (stage d, not implemented by this change). Once (a)-(c) pass, Linux SMP scheduling is enabled only alongside one of:
sched_setaffinity/cpuset) that pins every task
whose code path can execute a vector instruction to the RVV-capable
hart, enforced at the point those tasks are spawned (systemd unit
CPUAffinity=, or an equivalent cgroup/cpuset default) rather than
left to voluntary opt-in.hwprobe capability
per-hart instead of system-wide, so a task that checks vector
capability before using it (the same discipline
the-system-enables-proven-c908-extensions already requires of Pixman)
gets a correct per-hart answer instead of one that is only true for the
hart it happened to probe on.
A blanket nosmt-style exclusion is the fallback if neither is ready:
keep the second hart present but not eligible for the general scheduler,
using it only for explicitly pinned, known-scalar workloads (network
servicing, non-vector decode helpers, the theme helper) until affinity or
per-hart hwprobe exists.the-system-enables-proven-c908-extensions’s six-run card-cost
discipline).The read-only collector, pinned-source audit, and default-off CPU0 SPL
identity diagnostic are implemented. Its BootROM-loadable package was
built on the host; the ordinary stage-1 derivation remains identical.
docs/evidence/second-core/cpu0-identity-trial.md gives a bounded trial
and restore recipe. Board identity, interrupt and coherency gates remain
open. The physical trial is deferred until the current card’s raw-stage-1
backup and external-reader route are verified; the trial does not itself
enable Linux SMP. Subsequent OpenSBI/DT/kernel work follows only after the
named physical evidence is committed. Authorization for routine host work
is already supplied by the user; the single-board operator coordinates
the serial/card session and enforces the recovery gate.
Note, 2026-09-28 (redirected, not archived): the user has formally
redirected the second-core project to AMP; see
openspec/changes/the-small-core-runs-as-a-coprocessor/, citing
docs/closeout/second-core-plan.md. Section 1 (complete) is unaffected.
Section 2 (recovery rehearsal) is carried into that change’s own task list
as the same work item, and is itself now waived by a further 2026-09-28
operator decision (see task 2.1’s own note below) — no external-reader
rehearsal or spare/disposable card is required anywhere in this project’s
second-core work; the fallback is the proven U-Boot one-shot/ums/
reimaging recovery routes. Sections 3, 4, and 5 are formally WITHDRAWN
per that same redirect decision — they exist solely to make Linux treat
CPU0 as a peer SBI hart for SMP, which is no longer pursued — and are left
exactly as unticked as they were, not archived away silently; this change
stays open per AGENTS.md until the user confirms its archival.
0x9110100c
CPU1_RST_CTL, 0x91103018/0x9110301c PWR CPU1 control/status) to
tools/second-core-readiness.sh, reading only, never clearing the W1C
reset-done bits, plus a matching host fixture case. Verify with
sh tools/test-second-core-readiness.sh (host script-fixture proof, no
board).<!-- UNVERIFIED --> — against the exact pinned revision.
Verify with rg -n "sbi_hsm|hart_status|debugfs" /nix/store/hn11x8zd5linl193d8q0k9k99b46zqbm-linux-xuantie-k230-src/arch/riscv (pinned-source audit, not board or emulated proof)./dev/mem write, no
read-modify-write), run the extended collector from 1.1 and record the
three register values plus a fresh misa/uarch/L2-size cross-check
against the TRM’s CPU0/CPU1 table. Verify with the board console capture
committed to docs/evidence/second-core/live-handoff-v2.txt (board
physical read-only observation). Needs the operator to hold
/dev/ttyACM0 for one session; no reset or reflash.
Closed 2026-09-28 on audit: docs/evidence/second-core/live-handoff-v2.txt
(captured 2026-09-27T03:32:04Z) records cpu1_rst_ctl=0x00013000 and
both PWR fields as <unavailable:EPERM> — recorded, not inferred, per the
read-only-probe requirement — plus isa=rv64imafdcv... and a 256K L2,
cross-checked against the TRM’s CPU1 profile in the same file. The earlier
live-handoff-v2-partial.txt documents the pre-fix EPERM abort this run
superseded. No MMIO write occurred in either run.docs/evidence/second-core/README.md’s decision table with
the 1.3 result, stating explicitly whether the new register/ISA evidence
corroborates or falsifies “Linux already runs on physical CPU1.” Verify
with openspec validate the-system-runs-on-both-cores --strict after the
edit (documentation-consistency proof, not new physical evidence).
Closed 2026-09-28 on audit: docs/evidence/second-core/README.md’s
“2026-09-26 read-only continuation” section and table already state the
CPU1 reset-control read is “consistent with physical CPU1 released” and
the live ISA/cache reading “corroborates the physical big-core handoff”;
it does not claim the PWR reads. openspec validate the-system-runs-on-both-cores --strict
re-run clean during this audit (see report).nix build .#uboot-k230-cpu0-identity-probe --no-link --print-out-paths --max-jobs 1 --cores 4,
nix build .#stage1-cpu0-identity-probe --no-link --print-out-paths --max-jobs 1 --cores 4,
nix eval --raw .#uboot-k230.drvPath,
nix eval --raw .#stage1-packaging.drvPath, and cmp of packaged U-Boot
proper against normal. Results and exact paths/hashes are in
docs/evidence/second-core/spl-cpu0-identity-host-build.md and
docs/evidence/second-core/cpu0-identity-trial.md. This is host build
proof only; it does not close 1.3, 3.1, or any Linux SMP gate.docs/evidence/second-core/cpu0-identity-physical-trial.md
(physical board proof of CPU0’s sampled CSRs). The pinned OpenSBI
sbi_init.c and riscv_asm.h source chain also establishes that the
CPU1-side Boot HART ID : 0 comes from CSR.MHARTID. The external-reader
restoration rehearsal and all Linux SMP gates remain open.cpu0-identity-physical-trial.md
proves a same-session on-board dd restore from a verified backup (works
only if U-Boot still runs well enough for Linux to read the card), and
cpu0-identity-trial.md’s “Prepared external-reader procedure” is
written but was never run. Waived by a further 2026-09-28 operator
decision (recorded in the-small-core-runs-as-a-coprocessor’s own
proposal.md/design.md/tasks.md addenda and docs/closeout/second-core- plan.md’s addendum): the user said “we can easily fix the sd card damn.
don’t worry about recovery we’ve literally done that fine already
before. i don’t want to do a heartbeat test on a spare card.” No task in
this project’s second-core work may require a separate spare/disposable
card; the fallback recovery for any future register-writing board step is
the already-proven U-Boot one-shot boot from boot-prev or ums/flash
reimaging, on the normal card. This does not waive per-write
authorization: any later register-writing task still needs the user’s
explicit authorization at the time it runs.ums as an
additional route only while U-Boot is reachable (docs/uboot-ums.md).
Audited 2026-09-28: host portion re-run clean (python3 -m unittest discover -s tests -p test_ums_target.py → 16 tests OK) but the task’s own
physical-card-identity/backup requirement was never recorded, since 2.1’s
external-reader rehearsal was never run. Waived by the same 2026-09-28
operator decision as 2.1: the external-reader route is no longer
required; ums and U-Boot one-shot/reimaging remain the fallback,
reachable on the normal card without a separate rehearsal.WITHDRAWN 2026-09-28 per the user’s formal redirect of the second-core
project from SMP to AMP (the-small-core-runs-as-a-coprocessor, citing
docs/closeout/second-core-plan.md’s recommendation): this stage exists
solely to make Linux treat CPU0 as a peer SBI hart, which is no longer
pursued. Left unticked, not archived away, per AGENTS.md.
CSR.MHARTID and a usable distinct
logical hart identity. Pinned stage-1 source already gives CPU0’s reset
vector/control addresses (arch/riscv/cpu/k230/cpu.c:125-160); now audit
an early M-mode identity source, OpenSBI’s scratch/HSM/IPI/timer paths,
Linux’s CPU entry, and physical CPU0’s PLIC/ACLINT or other interrupt
routing. A controlled startup diagnostic may read CPU0 registers but is
not a second-program feature. If both cores read mhartid=0, a DT-only
cpu@1 is rejected. Record pinned source and any physical measurement
under docs/research/second-core-feasibility.md and
docs/evidence/second-core/; leave this task open until all paths are
grounded.
Audited 2026-09-28: partially grounded, left open per its own text. The
physical measurement half is done — mhartid=0x0 is now a first-hand
CPU0 SPL reading (cpu0-identity-physical-trial.md), and the CPU1-side
Boot HART ID : 0 is traced to the same CSR through pinned OpenSBI source
(docs/research/second-core-feasibility.md, “2026-09-27 physical CPU0
identity measurement”). The distinct-logical-identity half is not: the
2026-09-26 audit in that same doc greps the pinned U-Boot/OpenSBI overlays
for another physical core-ID CSR and finds none defined. No design or
vendor source establishes a working virtual-ID scheme, so this remains
blocked on a result nobody has yet — not on a board session.Platform HART Count : 2, Linux
smp: Brought up 1 node, 2 CPUs, and timer/IPI tests. A failed route
leaves this unticked. Requires the board operator’s coordinated session
and the recovery requirement in the delta spec.
Audited 2026-09-28: still open, blocked on 3.1 and 4.1, no new evidence.
Writes a reset/power/vector register; per AGENTS.md this needs explicit
user authorization for the board session in addition to being blocked.WITHDRAWN 2026-09-28, same reason and citation as section 3.
docs/evidence/second-core/; no host or QEMU result satisfies this.
Audited 2026-09-28: still open, no new evidence. No Canaan coherency
statement has surfaced; the bounded pre-Linux diagnostic itself has not
been designed or run. Requires explicit user authorization: it is a
hardware-writing, board-exclusive diagnostic gating 3.2.WITHDRAWN 2026-09-28, same reason and citation as section 3.
sched_getcpu/affinity, /sys/devices/system/cpu/{possible,present,online},
per-CPU timers, and repeated runs in a board transcript. Restoring RVV
requires a separately proved per-hart scheduling/userspace contract.
Audited 2026-09-28: still open, blocked on 3.2/4.1, no new evidence.Grounding: docs/research/second-core-feasibility.md’s “minimal recoverable experiment” and “passive handoff audit” sections define the ordering this requirement records; docs/evidence/second-core/README.md records that today’s readiness investigation is complete while second-core enablement is not.
The project SHALL stage Linux SMP bring-up as read-only board/source probes, a pre-Linux CPU0/CPU1 coherency and identity diagnostic, a guarded OpenSBI-plus-device-tree hart-release experiment, and common-ISA Linux scheduling. Linux currently runs on physical CPU1; the target is physical CPU0. It SHALL NOT boot a shared Linux kernel on both cores before identity, interrupt/timer routing, and shared-memory coherence are grounded. Read-only probes SHALL NOT write MMIO, invoke a reset/power/mailbox/HSM operation, or change CPU online state. Only the guarded diagnostics and release phase SHALL write a reset or power register, after the recovery prerequisite below is met. A separate CPU0 payload does not meet this requirement.
cpu@1 node, a reset-register write, or SMP scheduling before the preceding phase’s board evidence is committedGrounding: the K230 TRM section 1.3.2 assigns RVV 1.0 to CPU1 only; the-system-enables-proven-c908-extensions (modifying system/kernel) makes the ordinary kernel and Pixman RVV-by-default with a runtime capability gate. docs/evidence/cpu-readiness.txt records the current single Linux hart reporting RVV; if the second hart is the non-RVV core, as the current inference suggests, a kernel built with V compiles instructions that trap on a hart lacking that extension.
For initial Linux SMP scheduling, the project SHALL use a scalar common-ISA kernel and userspace image with RVV execution disabled so ordinary unpinned processes can run on either physical core. It SHALL NOT enable unconstrained scheduling across two harts while the kernel or userspace may execute RVV on the non-RVV CPU0. A later RVV-capable image requires a proven per-hart scheduling and userspace capability contract; affinity for selected processes alone is insufficient for the ordinary migratable workload.
Grounding: pinned U-Boot arch/riscv/cpu/k230/cpu.c:125-160 defines CPU0 reset/vector writes and nix/stage1.nix:176-180 puts SPL at raw SD-card offsets. docs/evidence/card-shell/bottom-band-flicker/kernel-patch-boot-panic.md records a U-Boot one-shot recovery for a Linux boot failure, while docs/uboot-ums.md documents external card-reader and U-Boot ums routes.
Before any change writes a CPU0 reset, power, or reset-vector register, the board operator SHALL have the user’s explicit authorization for that session. Recovery, if a write fails or hangs the board, SHALL use the already-proven U-Boot one-shot boot from boot-prev or ums/flash reimaging, on the normal card; no separate spare or disposable card SHALL be required.
ums/flash reimaging route and records the outcome separately from the release attempt’s own resultDraft proposal · In progress
Snapshot 5836ef1d113d · 2026-10-17 08:22 UTC
Next gateReview the next unchecked task in the linked task list
Away from Wi-Fi, the handheld cannot tell a person whether there is cell coverage. It cannot receive a text message, and it cannot say where it is. The keyboard base already carries a cellular and GNSS modem, a Nordic nRF9151 running LILYGO’s build of Nordic’s Serial LTE Modem firmware. Linux never powers it or talks to it, so none of this works.
There is also a cost to leaving it unmanaged. The vendor firmware is built to
attach to the network on its own as soon as it is powered (CONFIG_SM_AUTO_CONNECT=y
in serial_modem_k230/k230_serial_modem.conf). Using the modem therefore has
to start from a deliberate “off until the person turns it on”.
The modem talks AT commands over one UART with no flow control and no wake
line (the firmware overlay: “The K230 board does not route RTS/CTS or DTR/RI”).
That UART is the K230’s UART3. This board’s second console bridge channel is
also wired to UART3, on different pads (docs/dts-evidence.md: IO50/51 =
UART3, CH342 channel 1). Only one pad group can carry UART3, and this proposal
says plainly which loses. Under the mainline kernel the Linux console is UART0
on IO38/39 (CH342 channel 0), and nothing in this repository uses channel 1. So
the modem takes UART3, channel 1 goes quiet, and the console that tools/
uses is unaffected.
Probe first, read-only. With the modem powered through its enable line, record:
No firmware is changed.
Device tree. Mux IO28/29 to UART3, release IO50/51 from UART3, enable
uart3, and name the modem’s enable line.
One modem owner. A small k230-modem system service is the only
process that opens the modem’s UART:
Its state goes to a small file under /run and its commands come through a
local socket, so the shell never speaks AT.
Location. GNSS NMEA from the modem feeds gpsd, so any location-aware
program can use it.
Shell use.
Off by default. The modem stays unpowered at boot until the person turns Cellular or Location on. That choice persists in system state.
CONFIG_SM_PPP=n and CONFIG_SM_CMUX=n, so Linux cannot get a network
interface from it. Data needs a reflash over SWD, from pads inside the base,
to a PPP+CMUX build. That reflash is a successor proposal, not part of this
one.the-keyboard-base-types-lights-and-reports-its-battery).radio/cellular: the modem’s power, link, SIM, registration status and SMS,
owned by one Linux service.radio/gnss: location from the modem’s GNSS through gpsd, off unless
asked for.runtime/notification-center:
runtime/device-settings: Cellular and Location pages, shown only when the
modem is present.SERIAL_8250_DW already drives the UARTs.k230-modem service and its options;gpsd;ttyS3./dev/ttyACM1 on the bench host) no
longer carries UART3. Channel 0, the console, is unchanged. This must be
re-checked on the first boot of the new device tree.Sources read for this design:
Xinyuan-LilyGO/T-Display-K230-nRF9151:
README.MD;docs/AT_COMMANDS.MD;docs/FLASH_PYOCD.MD;serial_modem_k230/k230_serial_modem.conf and .overlay;k230_at_probe.sh;bsp-patches/.Xinyuan-LilyGO/T-Display-K230 at tree 4a87c53c:
k230_bsp/docs/HARDWARE_PINMAP.md.docs/dts-evidence.md, the FPIOA table from the board’s own RT-Smart
configuration;docs/research/board-capability-inventory.md, the UART3 conflict;nix/dts/k230-tdisplay-mainline.dts, where the console is serial0 = &uart0.Wiring.
Firmware.
Nordic Serial LTE Modem from NCS v3.4.0, LILYGO profile serial_modem_k230.
The vendor source names modem firmware mfw_nrf91x1_2.0.4; the unit
probed on 2026-10-13 reports mfw_nrf91x1_2.0.3 (AT+CGMR) under Serial
LTE Modem 2.9.0 (AT#XSLMVER; AT#XSMVER answers ERROR). See
docs/evidence/nrf9151/probe/. Its configuration:
| Setting | Value |
|---|---|
CONFIG_SM_AUTO_CONNECT | y, system mode "1,1,1,0" (LTE-M, NB-IoT and GNSS) |
CONFIG_SM_SMS | y |
CONFIG_SM_GNSS | y, with NMEA URCs on by default |
CONFIG_SM_PPP | n |
CONFIG_SM_CMUX | n |
LILYGO adds AT#XNMEA=<0|1>, which gives #XGNSSNMEA: URCs, and
AT#XK230LED.
Vendor recipes (AT_COMMANDS.MD):
AT+CFUN=1, AT%XSIM?, AT+CPIN?. Expect %XSIM: 1 and
+CPIN: READY.AT#XNMEA=1, AT%XSYSTEMMODE=0,0,1,0, AT+CFUN=31,
AT#XGNSS=1,0,0,0. That is GNSS-only, with LTE off.UART3 pads. UART3 is available on IO50/51 (wired to CH342 channel 1) and
IO28/29 (wired to the nRF). LILYGO’s own kernel patch 0061 forces IO50/51
back to GPIO for this reason.
| Pad | Bank line |
|---|---|
| IO2 | gpio0 2 |
| IO28 | gpio0 28 |
| IO29 | gpio0 29 |
| IO50 | gpio1 18 |
| IO51 | gpio1 19 |
Goals:
Non-goals: see the proposal. In particular, no mobile data and no firmware changes.
The pinctrl node (shared with the keyboard-base change) gets three states:
| Pads | State | Effect |
|---|---|---|
| IO28/29 | UART3 | The modem link. |
| IO50/51 | GPIO input | Channel 1 is quiet and cannot back-drive. |
| IO2 | GPIO output, default low | The modem’s enable line. |
&uart3 is enabled with uart3 and the IO28/29 state as its pinctrl default.
The console stays UART0 on IO38/39.
Rejected:
k230-modem is a Rust system service, built with the same toolchain as the
shell client. It is the only process that opens /dev/ttyS3 or the enable
line.
It requests gpio0 2 through the GPIO character device.
It runs a line-oriented AT state machine. Every command has a timeout and one command is in flight at a time. URCs are parsed between commands.
It publishes /run/k230/modem/state.json, written atomically:
| Field | Contents |
|---|---|
power | modem power |
sim | SIM state |
registration | registration state |
operator | network operator |
rat | access technology |
rsrp / bars | signal |
gnss | location state |
last_error | most recent error |
It accepts newline-delimited commands on /run/k230/modem/control, a socket
restricted to the shell user’s group: power on|off, pin <digits>,
gnss on|off, sms send <number> with the body on stdin, and status.
k230-modemctl is the command-line client.
The shell reads the state file and writes commands to the socket. No other code speaks AT.
Rejected:
CFUN.At boot the enable line is driven low and the service reports off.
“Cellular on” or “Location on”, persisted in /var/lib/k230/modem/settings.json,
powers the modem.
Because the firmware auto-connects, power on means:
AT+CFUN?;Location-only issues the vendor’s GNSS-only recipe immediately, so LTE never
attaches. Power off sends AT+CFUN=0, waits for OK with a timeout, then
drives the enable line low.
A PIN reaches the service only over the control socket. It is sent once as
AT+CPIN= and is never logged, written to state or the journal, or persisted.
The AT trace redacts that command’s argument. This follows AGENTS.md: secrets
are never committed and pass only through the designated protected path. Here
that path is the socket, and nothing is stored.
AT+CMGF=1. AT+CNMI routes new
messages as +CMT URCs./var/lib/k230/modem/sms.jsonl, with the last 200 messages, readable only by
the shell user. The person can clear it from Settings.AT+CMGS.gpsd (userspace, Nix)The service writes #XGNSSNMEA: payloads, stripped of the prefix, to a pty at
/run/k230/modem/nmea. gpsd is started on demand against that pty, so any
gpsd client works.
GNSS and LTE share one radio. On the nRF91, GNSS runs only while LTE is idle, or with LTE off:
1,1,1,0 with AT#XGNSS, and
accepts slower or interrupted fixes. The UI says “searching” honestly rather
than inventing a position.No position is written to disk by the service.
Rejected:
gpsd is the established interface, and maps and
CLI tools already speak it.FLASH_PYOCD.MD), then pppd over a CMUX channel. That needs
the SWD pads and a recovery story, so it is a successor proposal. Option (b)
is the firmware’s socket and HTTP AT commands. That is not a Linux network
interface, and it is rejected for general data.AT+CCLK?) when NTP is unreachable. It is small, but it
touches system/rtc policy and is better proposed with the RTC work.AT#XNMEA) or lower the rate.Evidence classes are named per task: host (build or unit test against a fake or recorded AT transcript), board-read (a command on the running board), camera, operator, and radio (a real network or sky event). Host results never tick a board or radio task.
Committed evidence never contains any of the following. They are replaced
with <redacted> and the redaction is noted:
1.1 Write tools/nrf9151-probe.sh. It records IO2’s level and the IOMUX
words for IO2/IO28/IO29/IO50/IO51, then drives IO2 high. For the probe
only, it switches IO28/29 to UART3 through a runtime path, recorded in the
script. It then sends only queries:
AT, AT+CGMR and the firmware’s version command;AT+CFUN?;AT+CFUN=1, then AT%XSIM?, AT+CPIN?, AT+CEREG?, AT+COPS?
and AT+CESQ;AT+CFUN=0 and IO2 low.It prints how long the firmware takes after power-on to issue its own
network attach. Proof (host): bash -n plus a review that the script
writes no non-volatile modem setting. The device tree (2.1) already muxes UART3, so
the script reads the mux instead of switching it. It ends in AT+CFUN=4
rather than AT+CFUN=0, which stores network context to flash on the
nRF91. Board run: docs/evidence/nrf9151/probe/.
1.2 Run it on the board, holding flock /tmp/k230-board.lock, and
commit the redacted output to docs/evidence/nrf9151/probe/. Also commit
the operator’s notes on the fitted antennas and SIM, with a camera frame
of the base’s antenna connectors if visible.
1.3 With GNSS on, using the vendor recipe for 60 s, measure the NMEA URC
byte rate against 115200 baud and record any framing errors from
/proc/tty/driver/serial. Proof (board-read).
2.1 Add the IO28/29 UART3, IO50/51 GPIO-input and IO2 GPIO states to the
shared pinctrl node, enable &uart3, and name IO2’s line nrf9151-enable.
Proof (host): nix build .#deviceTreeMainlineDrm.
2.2 Push the DTB with
tools/push-file.py --src <dtb> --dest /boot/k230-tdisplay.dtb --reboot.
Record:
/dev/ttyS3 present;AT answered through microcom with IO2 high;Proof (board-read): docs/evidence/nrf9151/uart/.
3.1 Write k230-modem and k230-modemctl in Rust, covering:
state.json;Proof (host): cargo test against recorded transcripts. The
transcripts include no SIM, PIN-required, a wrong PIN, registered, a
timeout, an inbound +CMT, a multi-part SMS, and an NMEA burst. A test
asserts that the PIN never appears in any log or state output.
Done (host): nix/k230-modem/ with cargo test --offline (37 tests;
tests/transcripts.rs). Only the no-SIM transcript is recorded (the board
probe log); the others are synthetic, from the Nordic SLM and 3GPP
27.007/27.005 formats, and say so in the file. Text-mode SMS and the
#XGNSSNMEA: payload quoting stay UNVERIFIED until the board runs them.
3.2 Add the NixOS module: the service, its group, /var/lib/k230/modem,
gpsd started on demand against the pty, and a udev rule tagging ttyS3
ID_MM_DEVICE_IGNORE. Defaults are Cellular off and Location off. Proof
(host):
nix build .#nixosConfigurations.k230-mainline-drm-shell-landscape.config.system.build.toplevel.
Done (host): nix/modem.nix (option k230.modem.enable, default on; the
modem stays off until Cellular or Location is turned on). The landscape
toplevel builds.
3.3 Install on the board. Record:
off (board-read);k230-modemctl power on, then status without a SIM or with one, per
1.2 (board-read);k230-modemctl power off returning the enable line low (board-read);/dev/ttyS3 (board-read).Proof: docs/evidence/nrf9151/service/.
Done 2026-10-14 without a SIM: enable out lo and power: off after boot;
power on gave Ready in 1 s and sim: absent; power off returned
out lo; an unprivileged dialout opener got EBUSY. The first image set
4098 baud (glibc 2.42 speed_t), fixed in the same branch; see the README.
These tasks need a SIM and an LTE antenna. They stay open until both are fitted.
bars agreeing with AT+CESQ. Proof (radio).grep -r <digits> over the journal and /var/lib/k230, which must find
nothing. The digits are never written into evidence; the grep is run with
the PIN from a protected file and only its exit status is recorded. Proof
(board-read).k230-modemctl.
The operator confirms delivery. Proof (radio + operator).These tasks need a GNSS antenna and sky view.
gpspipe -w fix class. The operator confirms the position is within
100 m of their known location; coordinates are not committed. Proof
(radio + operator)./var and the journal for coordinate
patterns, which must find nothing. Proof (board-read).cargo test in nix/rust-shell-client, plus host renders from fake state
files at 568x1232 and 1232x568.grim: the shade indicators, both
Settings pages, and an SMS preview and history entry. Record the operator
turning Location on through Settings and the choice surviving a reboot.
Proof (board-read + operator): docs/evidence/nrf9151/shell/.openspec validate the-nrf9151-gives-the-handheld-cellular-sms-and-location --strict
and python3 tools/blob-scan.py --no-vendor. Merge, push, and check CI and
the published spec pages. Archive only when every task has its named proof.
Mobile data stays in a successor proposal.Let the handheld use the keyboard base’s nRF9151 for cellular status, SIM handling and SMS, through one Linux service that owns the modem’s power and AT link, with the modem off until a person turns it on.
The system SHALL carry the modem’s AT link on UART3 over IO28/29 and SHALL leave IO50/51 as quiet GPIO inputs. The Linux console on UART0 (CH342 channel 0) SHALL keep working: boot messages and login on the same port as before. CH342 channel 1 SHALL be documented as carrying nothing.
/dev/ttyS3 existsOn every boot the system SHALL hold the modem unpowered until a person turns Cellular or Location on. That choice SHALL persist across reboots in system state. Turning both off SHALL put the modem into minimum function and then remove its power.
offExactly one system service SHALL open the modem’s UART and its enable line. Every other component, including the shell, SHALL read the modem’s state from the service’s published state and send requests through its local control socket, never AT commands. The service SHALL keep one AT command in flight at a time, apply a timeout to each, and handle unsolicited results between commands.
/dev/ttyS3 while the service runsWith Cellular on, the service SHALL report SIM state (absent, PIN required, ready, locked), registration state, operator name, access technology (LTE-M or NB-IoT) and signal strength, updated within 30 seconds of a change.
A SIM PIN SHALL reach the modem only through the control socket. It SHALL NOT appear in the journal, the AT trace, the state file, settings, or any committed evidence. The service SHALL NOT retry a rejected PIN on its own.
/var/lib/k230 for the digits finds nothingWith Cellular on and registered, an incoming SMS SHALL be stored in a bounded, user-readable store that a person can clear, and SHALL be raised as a shell notification. A person SHALL be able to send an SMS with k230-modemctl sms send <number>, with the result reported as sent or failed.
k230-modemctl sms send to a test number with a short bodyGive the handheld a location from the keyboard base’s nRF9151 GNSS receiver, through gpsd, only while a person has Location turned on.
With Location on, the system SHALL feed the modem’s NMEA output to gpsd, so that a gpsd client reports the receiver’s state: no fix, then 2D or 3D fix with position and time. With Location off, GNSS SHALL be stopped and gpsd SHALL report no device.
gpspipe -w reports a 3D fix whose position is consistent with the operator’s known location to within 100 mgpsd reports no fix, and nothing presents a stale or invented positionWith both Cellular and Location on, the system SHALL keep the cellular registration and run GNSS when the modem allows it. It SHALL report “searching” while no fix is available, rather than turning Cellular off on its own.
The modem service and gpsd SHALL NOT write positions to persistent storage or the journal. Recording a track is left to a client the person runs.
/var and no journal entry contains a latitude or longitude from that sessionWhen the keyboard base’s modem has answered at least once since the image was installed, Settings SHALL offer:
Every switch SHALL take effect through the modem service and persist across reboots. Without the modem, Settings SHALL NOT show these pages.
An SMS received by the modem service SHALL appear as a notification whose source is the sender’s number. Following the existing privacy default, the preview SHALL hide the body. Opening the notification in history SHALL show the full text.
While Cellular is on, the shade SHALL show a signal indicator matching the service’s reported bars, or no service. While Location is on, the shade SHALL show a location indicator that distinguishes searching from a fix. While both are off, the shade SHALL show neither.
gpsd reports oneDraft proposal · In progress
Snapshot 5836ef1d113d · 2026-10-17 08:22 UTC
Next gateBLOCKED on 3.2. Ground a region that remains reserved from
2026-09-28 scope decision — the underlying goal changed, this change
stays open, un-archived, and un-implemented. The user has now formally
decided the second-core project is a coprocessor (AMP), not Linux SMP; see
the-small-core-runs-as-a-coprocessor/proposal.md. That decision makes the
2026-09-26 suspension’s reason moot — Linux SMP is no longer the target
of any change, so “this proposal doesn’t deliver Linux SMP” is no longer a
reason to hold it — but it does not by itself un-suspend, implement, or
archive this proposal: per AGENTS.md, only the user’s explicit confirmation
does that, and no task below is ticked or run by this note. What actually
happens is that this proposal’s ready, physically-proved foundation (its
host-built payload, tools/small-core-heartbeat.{S,ld}, and its board-gated
tasks 3.1 then 3.2) is resequenced as the-small-core-runs-as-a-coprocessor’s
own stage-1 (recovery rehearsal) and stage-2/3 (echo/ping firmware) tasks,
in that same order — recovery rehearsal first, then the board release. This
proposal’s coexistence stage (task family 4: patch the CPU0 SPL parking
loop to run the heartbeat unconditionally after every boot) is not
reused as designed: the new change’s design.md explains why a
remoteproc-shaped Linux driver that starts and stops CPU0 on demand, once
booted, is simpler and lower-risk than making CPU0 run unconditionally on
every boot via a stage-1/SPL patch. Task family 4 is recorded as superseded
by that change’s own reserved-memory/runtime-start-stop stages, not deleted
and not ticked here.
Suspended 2026-09-26 after user scope correction. The requested feature
is Linux SMP with both physical cores addressable by one kernel and ordinary
processes schedulable on either. A CPU0 heartbeat or AMP payload does not
meet that request. This proposal and its unchecked tasks remain for history;
do not implement or treat them as a substitute for
the-system-runs-on-both-cores.
The handheld currently runs all Linux work on the large physical core, so no
background work can use the small core. Before promising shared Linux
scheduling, an operator needs a recoverable proof that the small core can
execute an independently loaded program while the large core remains under
stage-1 control. The pinned U-Boot source supplies a physical CPU0 reset
vector/release path, while first-hand K230 developer reports say both cores
may report mhartid 0; the ordinary two-hart Linux path is therefore unsafe
to assume.
boot_baremetal 0
release with the large core at the U-Boot prompt, then observe a changing
heartbeat from the small core. Capture the console transcript and restore
the normal boot path.None.
system/second-core-readiness: add a recoverable, explicitly bounded
physical CPU0 execution proof and distinguish it from shared Linux SMP.The first stage covers a standalone test payload, host inspection tool, narrow operator runbook and committed board evidence. The second stage changes SPL and reserves an observation region in the experimental device tree; it does not alter the normal installed image until physically proved. Both stages need the physical board, the exclusive console, a disposable rollback card, and a rehearsed recovery path. Host preparation does not need the board.
See proposal.md and docs/research/second-core-feasibility.md. The pinned
U-Boot overlay runs the normal Linux boot on physical CPU1 and exposes
boot_baremetal 0, which sets the physical CPU0 vector at 0x91102100 and
uses CPU0_RST_CTL at 0x91101004. Reports that both cores expose hart ID 0
make a guessed second Linux CPU node especially unsafe. The existing
the-system-runs-on-both-cores proposal remains the separate Linux SMP path
and retains its gates.
Goals: first prove a tiny independent CPU0 payload while the large-core U-Boot prompt remains responsive; then prove a separately gated CPU0 heartbeat continues while CPU1 runs Linux. Make payload bytes, load/output locations, boot images, timestamps, and observations reviewable.
Non-Goals: Linux SMP, booting RT-Smart, inter-core interrupts, coherent shared memory, useful task offload, or video improvement.
boot_baremetal 0 command. It already contains the physical CPU0 vector
and reset sequence, so the probe does not add a kernel /dev/mem writer
or alter the normal boot image. A CPU1-targeted vendor AMP driver is
rejected: Linux is already on physical CPU1 in this image.boot_baremetal. Run the command only
with the board operator’s exclusive console and a disposable rollback
card. Stop at the first hang or unexpected value; capture the recovery
transcript separately.k230_img.c:276-285 WFI loop in
an experimental SPL to update a reserved heartbeat at low duty cycle
after releasing physical CPU1. This avoids a second CPU0 reset from a
running Linux system and preserves CPU1’s normal boot path. The
experimental device tree excludes the exact output region from Linux
allocation, and a read-only Linux probe uses a documented uncached or
cache-maintained view. A normal image is not replaced until a disposable
card boots and rolls back successfully. An alternative Linux /dev/mem
writer to release CPU0 is rejected because the big-core PWR registers
already return EPERM, because it would reset the parked core without
restoring SPL context, and because it bypasses stage-1 ownership.Land this proposal first. Prepare and inspect the payload on the host. After the source and recovery gates pass, perform the U-Boot physical test on a disposable card and commit the evidence. Only then build the experimental SPL and DT reservation and test Linux coexistence on a rollback card. Return to the normal card/boot and record its Linux CPU mask. Keep this change open if either physical proof is unavailable.
Audited 2026-09-28. This change is suspended per proposal.md’s
2026-09-26 note: the requested outcome is Linux SMP
(the-system-runs-on-both-cores), and a CPU0 heartbeat/AMP payload is not a
substitute for it. Tasks 1.1/1.2/2.1/2.2 are ticked below because their host
evidence exists and was independently reproduced during this audit
(impl/small-core-heartbeat-20260926 at 4e6be10d, cherry-picked onto
close/second-core). Tasks 3.1 onward are board-gated and suspended: do
not run them without a new decision that un-suspends this proposal, even
though the runbook and payload for 3.1/3.2 are otherwise ready.
Note, 2026-09-28 (resequenced, not archived or implemented): the user
has formally chosen AMP for the second-core project; see
openspec/changes/the-small-core-runs-as-a-coprocessor/. Tasks 1.1/1.2/2.1/2.2
(complete) and 3.1/3.2 (board-gated, ready) are carried into that change’s
own stage-1/stage-2/stage-3 tasks in the same order — recovery rehearsal,
then the board release. Task family 4 (patch the CPU0 SPL parking loop for
unconditional coexistence) is recorded as superseded by that change’s
Linux-driven runtime start/stop design instead. Nothing here is ticked,
archived, or run by this note; the change stays open per AGENTS.md until the
user confirms otherwise.
rg -n 'CONFIG_LINUX_RUN_CORE_ID|boot_baremetal|cpu0_hart_rstvec' /nix/store/g58y0fnasf1gapxjnjmbdnmg6zs58yhs-source/buildroot-overlay/boot/uboot/u-boot-2022.10-overlay/{board/canaan/common,arch/riscv/cpu/k230} (pinned-source proof).openspec validate the-small-core-runs-a-recoverable-heartbeat --strict (source/document
proof, no board claim).bash tools/test-small-core-heartbeat.sh (host binary proof, not board).openspec validate the-small-core-runs-a-recoverable-heartbeat --strict
(document proof, not board).docs/evidence/second-core/. Waived by the operator’s 2026-09-28
decision (recorded in the-small-core-runs-as-a-coprocessor’s own
addenda and docs/closeout/second-core-plan.md’s addendum): “we can
easily fix the sd card damn. don’t worry about recovery we’ve literally
done that fine already before. i don’t want to do a heartbeat test on a
spare card.” No disposable/spare card is required; recovery, if needed,
is by the already-proven U-Boot one-shot boot from boot-prev or
ums/flash reimaging, on the normal card. This whole change remains
suspended in favor of the AMP successor (see the note at the top of this
file); this task is not being run here.boot_baremetal 0 sequence, and
observe at least three increasing output values while the CPU1 U-Boot
prompt responds; then restore normal boot and record Linux CPU masks.
Recovery, if needed, is by the fallback routes named in task 3.1 (no
disposable card). Verify with the exact U-Boot command and timestamped
board transcript committed under docs/evidence/second-core/ (physical
CPU0 execution proof; any hang or static output fails this task).
Performed 2026-10-12 on the normal card, after the operator chose
“Yes, go” for releasing CPU0 once the payload was ready
(docs/evidence/second-core/heartbeat-physical-2026-10-12/README.md).
boot_baremetal 0 0x7000000 0x5000 after a passing bdinfo/size/CRC
check. The first release, read 1.2 s apart, gave 1, 1, 2 and failed. The
second, read 5 s apart (the runbook asks for at least 1 s), gave 2, 4, 6
with the CPU1 prompt alive, plus mhartid=0x0 and
misa=0x800000000094112f written by the payload. Linux was restored by
reset: online=0, nproc 1, system 298a2bf6…. Serial transcript only.nix build .#deviceTree and a
decompiled reserved-memory node check (DT build proof, not board).nix build .#stage1 and the narrow host
observer fixture (cross-build/host proof, not board)./dev/ttyACM0
console transcript and normal-boot hash/CPU-mask checks committed under
docs/evidence/second-core/ (physical coexistence proof).Grounding: the pinned k230_linux_sdk U-Boot overlay at revision
1104236db4d1e47873bd68924f912747b820228c,
arch/riscv/cpu/k230/cpu.c:125-160, provides boot_baremetal 0 and writes
physical CPU0’s reset vector at 0x91102100; docs/research/second-core-feasibility.md
records its limits. The output memory and coexistence behavior remain
<!-- UNVERIFIED --> until board evidence exists.
The project SHALL provide a scalar test payload and a readback procedure that
allow an operator to tell from the console whether physical CPU0 executed
while physical CPU1 remained at the stage-1 prompt. Before the release, the
payload address and output location SHALL be checked against stage-1 memory
use, and a proven fallback recovery route (the U-Boot one-shot boot or
ums/flash reimaging) SHALL be available on the normal card; no separate
disposable or spare card SHALL be required. The experiment SHALL record
the release command, repeated observations, and recovery outcome as physical
evidence. A host build or QEMU run SHALL NOT be counted as physical proof.
ums/flash reimaging) is used, and no Linux-coexistence
claim is madeGrounding: the pinned stage-1 source at
board/canaan/common/k230_img.c:276-285 releases physical CPU1 into U-Boot
and parks physical CPU0 in an endless wfi. The continued heartbeat and
Linux readback are <!-- UNVERIFIED --> until the board transcript exists.
Only after the stage-1 prompt heartbeat is physically proved, an experimental stage-1 build SHALL let physical CPU0 update a reserved heartbeat location while physical CPU1 continues into the normal Linux boot. The system SHALL exclude that location from Linux allocation and expose a read-only observation method with an explicit cache-maintenance or uncached-memory contract. The operator SHALL record repeated changing values alongside a responsive Linux console and shell, then restore the known-good stage 1.
ums/flash reimaging) is used without claiming
useful offload or Linux SMPGrounding: the pinned U-Boot release path starts a separate physical core;
the vendor k230-amp.c path requires a separate payload and cache-managed
memory. The K230 Linux DTS review
reports physical CPU1 mhartid 0; a further first-hand developer report says
both physical cores report 0, pending confirmation on this board.
The project SHALL identify the heartbeat as independent physical CPU0 execution under stage 1. It SHALL NOT claim a second Linux CPU, cache-coherent shared memory, working interrupts, timer delivery, video offload, or safe general scheduling from that observation. Those claims require separate physical tests and an ownership/cache-maintenance protocol.
Draft proposal · In progress
Snapshot 5836ef1d113d · 2026-10-17 08:22 UTC
Next gateHardware. Find and remove the transient 1-4-frame scanout glitches of the stage-1 image during early userspace (filmed 2026-10-12 at kernel ~17 s and ~27 s in all three splash boots…
The board’s daily system is now the mainline-kernel k230-mainline-drm-shell
(flake.nix:238), and on it the glass is dark from power-on until the shell
draws. the-screen-lights-before-linux built and photographed the stage 1
splash on the vendor kernel, but its Linux handoff was never made to hold on
the card the board runs today, so the daily image deliberately ships without
the splash: the coherent shell sets k230.panelConsole = true
(flake.nix:130-134), splashImage is then null (flake.nix:84) and
nix/sd-image.nix:86-88 leaves logo.xrgb off the boot partition.
On 2026-10-11 the operator chose to close that change with a successor
rather than carry its unperformed hardware tasks. This change holds exactly
those tasks, plus the work the mainline kernel adds: its device tree has no
reserved-memory or framebuffer node (task 3.5 of the predecessor added one
only to the vendor nix/dts/k230-tdisplay.dts), and its panel/DRM driver has
not been shown to leave a stage 1 image alone.
k230.panelConsole = false is built and its boot partition
carries logo.xrgb.panelConsole = true image inspection (6.1) if it was not performed there.Non-goals. Plymouth (task 5.2 of the predecessor was not taken; the measurement selected the minimal DRM owner). Boot animation. Changing the stage 1 splash port, which the predecessor already delivered and archived. Any claim that a host build, QEMU run or injected event satisfies a task that says Hardware.
Needs the physical board for every hardware task. The device-tree and
image tasks are laptop claims. Recovery stays as it was: a second card with
the last known-good image, and docs/uboot-ums.md for flashing in place.
None yet. The requirements this change must satisfy are the ones
the-screen-lights-before-linux archived into display/boot-splash and
image/boot-chain; their UNVERIFIED markers point here. A delta is added
when a hardware result restates one.
nix/dts/k230-tdisplay-mainline-drm-common.dtsi (a reserved-memory node fed
from the flake’s splash-address constant), the mainline kernel patch set in
nix/ (panel and DRM handoff), flake.nix and nix/panel-console.nix
(the selected default), and new evidence under docs/evidence/.
Layers: stage 1 (done, archived with the predecessor), kernel (mainline
panel/DRM driver, not yet shown to preserve a lit panel), device tree
(mainline DT lacks the splash reservation), Nix (image selection), userspace
(the minimal DRM owner k230-drm-splash, already in the closure).
The predecessor proved, on the vendor kernel and mostly on warm resets over USB, that stage 1 lights the panel and that the opt-in preservation patches carry it to the shell. It did not perform the second-card power-on procedure, and it never ran against the mainline kernel the board uses now.
tasks.md; the proof for each is
unchanged, so nothing is relaxed by moving it.reserved-memory node the
mainline kernel may allocate the splash buffer, so no handoff task is
meaningful before it. The node takes reg from the same flake constant as
U-Boot’s Kconfig symbol.docs/evidence/kernel-patches.md) do not apply to the mainline driver;
the handoff gate must be satisfied by whatever the mainline panel/DRM tree
carries, and recorded there with a drop condition.k230.panelConsole stays true
for the daily shell until the film in the power-on task shows no dark
frame; the false image is built and flashed to a second card first.docs/evidence/boot-splash-owner.md), so the DRM owner was selected.Corrupted scanout after the Linux handoff is the defect that forced
panelConsole = true; it has not been reproduced or fixed on mainline. A
false image may show it, which is why the second-card rule applies.
Carried from the-screen-lights-before-linux (archived 2026-10-11 by an
operator-authorized scope split). Tasks marked “Moved from” keep their
original text and proof commands verbatim after the prefix. Nothing here is
ticked: none was performed. Hardware tasks take the board and its serial
port for one operator at a time and are proven by a photograph, film or
console capture committed under docs/evidence/; a host build, QEMU run or
injected event does not satisfy them.
reserved-memory framebuffer node for the splash buffer to the mainline device tree (nix/dts/k230-tdisplay-mainline-drm-common.dtsi or the file that the hotplug tree includes), with reg taken from the same flake constant as U-Boot’s splash Kconfig symbol, as task 3.5 did for nix/dts/k230-tdisplay.dts. Verify with nix build .#mainlineDrmHotplugDeviceTreeNormalName and fdtget on the resulting DTB printing the chosen address and size under /reserved-memory — laptop claim
Done 2026-10-12: node added to k230-tdisplay-mainline-drm-common.dtsi, flags passed in nix/device-tree-mainline-drm.nix; fdtget on the built DTB prints 0 10000000 0 400000 and no-map under /reserved-memory. Evidence: docs/evidence/mainline-boot-splash/README.md.docs/evidence/kernel-patches.md. Verify with the mainline kernel nix build of the attribute .#sdImage uses — laptop claim
Done 2026-10-12 (source and build only): the mainline driver already carries the handoff; no patch. The kernel build of the .#sdImage attribute succeeded. Recorded in docs/evidence/kernel-patches.md (Mainline section). Whether no fbdev client appears on glass remains hardware gate 2.3.k230.panelConsole = false on the mainline shell (an extendModules target or the flipped default) whose boot partition carries logo.xrgb (2 799 104 bytes) and whose bootargs.txt lacks console=tty0. Verify with nix build of that image and docs/evidence/splash-close-sdimage/inspect-image.py adapted to expect the logo — laptop claim
Done 2026-10-12: .#sdImage-mainline-splash built; docs/evidence/mainline-boot-splash/inspect-image.py PASS (inspect.json).Each task below is the predecessor’s own, in the same order it had there;
the second-card rule applies to every one: flash a second card and keep the
known-good one. docs/uboot-ums.md is the in-place flashing and recovery path.
Run them on the image from 1.3.
the-screen-lights-before-linux 3.6: 3.6 Hardware. Flash a second card, keep the known-good one, take the board, and boot. Verify by committing a photograph of the splash on the glass and a ./tools/capture-boot.py capture in which the moment of the photograph precedes Starting kernel, both under docs/evidence/ and referenced from docs/evidence/boot-splash.md — hardware claim
Done 2026-10-12 (warm reboot, in place on the board’s one card; the operator answered “In place is fine” and “Warm reboot is enough” — no second card, no cold power-on): splash-at-uboot-before-kernel.jpg at session t = 17.99 s, 8 s before bootm and Starting kernel, in idle-kernel-serial-excerpt.txt (captured by tools/splash-uboot-session.py, not capture-boot.py). Evidence: docs/evidence/mainline-boot-splash/board/README.md, pointer in docs/evidence/boot-splash.md.the-screen-lights-before-linux 3.7: 3.7 Hardware. Measure the U-Boot-lit image with tools/panel-measure.py exactly as dsi-hsfreqrange-hardcoded.md measured the Linux one. If it rolls or is dark, fall back to LILYGO’s full table (39.6 MHz / 0x96) to prove the path, then change one parameter at a time until our mode is stable, recording each step. Verify by committing the measurement table to docs/evidence/boot-splash.md with motion figures at or below the 0x87 row of the earlier document, and releasing the board — hardware claim
Done 2026-10-12: U-Boot target at K230#, 1050 frames: motion std 0.01 px, span 0.10, frame-to-frame max 0.06, brightness 100..100% (0x87 run 2: 0.02 / 0.09 / 0.04), below a static control’s 0.02 / 0.15 / 0.14; live-panel check by mw.l into the splash buffer. Deviation: camera-pixel strip (camera-px-motion.py) because only two ArUco markers are in the current camera frame — the same unregistered method as the 0x87 rows. Evidence: docs/evidence/mainline-boot-splash/board/README.md.the-screen-lights-before-linux 4.3: 4.3 Hardware. Boot the new kernel on the card from 3.6 and leave the board at the serial prompt with nothing opening the display. Verify by committing a capture to docs/evidence/boot-splash-handoff.md showing /proc/device-tree/chosen carrying the flag, the driver’s “stage 1 splash: leaving fbdev unset” message, no panel prepare/init sequence before a DRM client starts, ls /dev/fb0 failing, and a photograph of the splash still on the glass at the prompt. The panel driver’s “left as stage 1 set it” line belongs to the first DRM modeset in 4.4, not the idle-kernel phase — hardware claim
Done 2026-10-12 (warm reboot): candidate kernel with systemd.mask= shell, seatd and k230-drm-splash; flag present, “leaving fbdev unset”, no panel prepare line, /dev/fb0 absent, no /dev/dri holder; splash-at-idle-kernel-prompt.jpg during a 90 s hold. Evidence: docs/evidence/mainline-boot-splash/board/README.md, pointer in docs/evidence/boot-splash-handoff.md.the-screen-lights-before-linux 5.4: 5.4 Hardware. Film a complete boot from power-on to the owner’s last frame — and, if the-screen-runs-a-shell-not-a-console has landed, to the compositor’s first frame. Verify by committing the frame timings to docs/evidence/boot-splash-handoff.md showing no dark frame between the splash appearing and the last frame filmed, and the first Linux frame indistinguishable from the last stage 1 frame. Release the board — hardware claim
Done 2026-10-12 on warm reboots, not from power-on (operator: “Warm reboot is enough”): film1 logo 16.37-80.93 s, compositor first frame 80.97 s; film7 (installed autoboot) logo 42.43-121.93 s, compositor 121.97 s; no intermediate frame; Linux’s splash owner takeover invisible. 1-4-frame scanout glitches in early userspace were filmed in every splash boot (not dark frames) and are task 4.1. Evidence: docs/evidence/mainline-boot-splash/board/README.md, pointer in docs/evidence/boot-splash-handoff.md.k230.panelConsole = false (removing the explicit true at flake.nix:130-134) and restate the display/boot-splash requirement “The splash and the panel console are a build-time choice” to what was measured, resolving its UNVERIFIED marker. Verify with openspec validate the-mainline-kernel-keeps-the-boot-splash --strict and the nix eval of both option states — laptop claim. If a gate fails, record the failure under docs/evidence/ and leave the default true.
Done 2026-10-12: k230-mainline-drm-shell (the sdImage system) sets k230.panelConsole = mkForce false; the vendor-kernel k230 keeps its explicit true (its handoff was not re-proven), so the line at flake.nix:130-134 stays. k230-mainline-drm-shell-splash is now an alias. nix eval: false / false / true (k230) / true (k230-console); kernelMainlineDrmShellBootFiles builds byte-identical boot files to the installed splash bundle. Requirement restated in specs/display/boot-splash/spec.md; openspec validate --strict passes. The board runs it as the installed default (ordinary-runtime.json).docs/evidence/mainline-boot-splash/board/README.md “Transient scanout glitches”). Verify by a filmed warm reboot of the default image with no such frame between the splash appearing and the compositor’s first frame, with the film timed against kernel time to +-0.1 s, committed under docs/evidence/ — hardware claimProves group 1. nix build .#mainlineDrmHotplugDeviceTreeNormalName and the image build, laptop claims. Proves group 2. The photograph, film and captures named in each task, hardware claims.
The system SHALL offer two configurations and default to the first: a boot
that shows the splash and puts no console on the panel, and a boot that
lights the panel from the kernel and shows the framebuffer console on it as
the-screen-comes-up-under-linux left it. Selecting the second SHALL be one
option in the NixOS configuration, and SHALL be what a person reaches for
when the panel path itself is being debugged.
Grounding: the daily mainline system k230-mainline-drm-shell sets
k230.panelConsole = false (flake.nix), so sdImage and
kernelMainlineDrmShellBootFiles carry logo.xrgb and bootargs without
console=tty0; nix eval gives false for it and true for the
vendor-kernel k230 and k230-console
(docs/evidence/mainline-boot-splash/board/README.md). That system,
kc3iyr4c…, is installed on the board and was filmed on warm reboots showing
the splash from stage 1 to the compositor’s first frame with no kernel text on
the panel (same README). The console configuration remains the
panelConsole = true option, photographed in
docs/evidence/panel-photos/05-console-on-panel.jpg.
The device tree stage 1 loads for the daily system SHALL reserve the splash buffer’s address range from the kernel’s allocator, with the address and size taken from the same flake constant that configures stage 1’s splash symbol, so that a stage 1 image survives until a display client replaces it.
Grounding: nix/dts/k230-tdisplay-mainline-drm-common.dtsi carries
framebuffer@10000000 (0x400000, no-map) from the flake’s splash
constants (task 1.1, docs/evidence/mainline-boot-splash/README.md). On the
board (docs/evidence/mainline-boot-splash/board/README.md, 2026-10-12, warm
reboots): the kernel logs reserved mem: 0x10000000..0x103fffff nomap framebuffer@10000000, an idle kernel with no DRM client keeps the logo on the
glass for a 90 s hold, and two filmed boots show the logo until the
compositor’s first frame. Transient 1-4-frame scanout glitches during early
userspace (same README) recover without leaving a changed image; their cause
is open as task 4.1.
/reserved-memoryreg equals stage 1’s splash address and size is presentdocs/evidence/Draft proposal · In progress
Snapshot 5836ef1d113d · 2026-10-17 08:22 UTC
Next gateReproduce rotated/unrotated, ARGB8888/RGB565 baselines, then capture
The HDMI shell visibly lags and the operator cannot reliably leave an open app with a finger gesture. Physical-board traces locate a major rendering problem: 1920×1080 portrait composition builds frames in 442 ms median, versus 15 ms unrotated with the same pixel format; see the board trial.
Non-goals: landscape as a workaround for the portrait monitor; lower resolution as the accepted result; a replacement shell toolkit; a general GPU rewrite; second-core bring-up; hardware acceleration without a demonstrated gain.
None.
runtime/shell: responsive portrait HDMI composition and physical app-edge
gesture acceptance, with explicit performance and correctness gates.Userspace Sway/wlroots/Pixman integration, compositor tests, Nix package/default selection, trace tooling and committed evidence. A GPU candidate may also need the existing access boundary; any new kernel scope needs a separate proposal. Host pixel tests can proceed independently. Final performance, gesture and panel-regression acceptance require the single reserved physical board.
This follows the-shell-adapts-to-output-resolution and complements
the-card-deck-still-misses-its-frame-budget; it does not close their unchecked
tasks or declare HDMI hotplug/trackpad acceptance complete.
See proposal and the committed HDMI board trial. The active userspace stack is Sway/wlroots/Pixman, logical 1080×1920 on a 1920×1080 monitor with transform 90. Median frame-build CPU time is 441.84 ms in ARGB8888; normal-transform ARGB8888 is 15.29 ms. RGB565 alone does not fix the rotated case. The existing scaled mirror cache requires RGB565 and a normal output transform, so the ARGB8888 comparison avoids that confound. Orientation still changes scene geometry/damage; the comparison is not a pixel-identical microbenchmark.
Goals: remove repeated expensive quarter-turn sampling, preserve real client updates and portrait layout, and demonstrate physical gesture responsiveness. Changes belong in userspace rendering/input and Nix selection. Kernel changes are not assumed. Unsupported formats/transforms retain the existing correct fallback, with a reason in bounded telemetry.
Non-goals: assuming the earlier full-scene GPU rejection also rejects a narrow rotation operation, or assuming a narrow GPU operation will win. The winning path must meet pixel, lifetime, performance and recovery gates.
Capture renderer stacks and subdivision timings during the existing paired
gesture workload. If perf sampling is unavailable, use bounded stage counters
and an on-board quarter-turn microbenchmark. Record CPU frequency/governor,
format, transform, renderer identity, dimensions and app count. Avoid attributing
all frame-build time to a routine from the existing coarse trace alone.
The first software candidate is tiled quarter-turn copying in the Pixman renderer: pre-rotate a source image, then scale/composite without a quarter-turn affine sampler. Copying on each relevant draw is initially acceptable if measured cost wins; reuse must explicitly invalidate on texture damage/updates and never retain stale shared-memory client pixels. If profiling instead favors composing an unrotated logical frame and rotating once, use that bounded alternative and document memory/damage costs. Preserve sampling coordinates, clipping and alpha.
A GPU candidate is limited to the expensive copy/rotation boundary and must count upload, download, synchronization and fallback costs. Prefer the simplest candidate that passes the measured budget. Do not bypass the existing device access/isolation rules. If all candidates fail, keep the change open with traces.
Compare baseline and candidate pixels for asymmetric images, crop, scale, quarter turns, opacity, rounded clips, damage and both relevant output formats. Use live changing clients as well as static Foot windows: frame callbacks, presentation feedback, buffer release and texture updates must remain correct. Do not quietly hide wallpaper, remove rounded corners or freeze cards to win.
The injected bottom-edge swipe succeeded; this does not prove glass input. Capture contact origin, normalized/output coordinates, event timestamps and the route rejection reason while an ordinary app is open. Check stale output geometry, touch-to-pointer ownership and edge-band scaling before changing recognition. Fix only the proved boundary, then verify top/bottom gestures, app touches and keyboard/shade coexistence with a real finger. Absolute-touch and opt-in trackpad input are distinct modes; this change does not complete the trackpad proposal.
For one and two ordinary Foot cards at full portrait HDMI resolution, require p95 frame-build CPU time at most 33.3 ms and p95 contact-to-present time at most 100 ms, using at least 24 drags per workload. These are proposed acceptance targets, currently UNVERIFIED. Preserve event clock provenance and per-run thermal/frequency context; an injected trace proves only injected latency.
Land the proposal early. Add an opt-in candidate compositor build; run host pixel/lifecycle tests, then a reserved board comparison against the exact baseline. Only after those pass, select the candidate through repository Nix defaults, build/install the integrated image and repeat representative app/gesture checks. Preserve normal panel boot and verify a reboot into it. Commit public evidence, push master and inspect the exact Pages deployment before archival.
New harness and test commands below are implementation deliverables, not already-existing proof. Every physical command requires the sole board reservation. Public traces must omit network/device secrets.
tools/hdmi-shell-performance.py with strict trace parsing,
explicit injected/physical labels, output-state restoration and bounded board
capture. Verify fixtures reject missing frames and mixed identities with
python3 tools/hdmi-shell-performance.py --self-test (host-only).
Eleven parser/dispatch fixtures and nine mocked capture fixtures pass; see
docs/evidence/hdmi-shell-performance/recovered-harness-check.txt. Physical
execution remains in the unchecked board tasks below.python3 tools/hdmi-shell-performance.py --capture --variant baseline --output docs/evidence/hdmi-shell-performance/baseline.python3 tests/test_pixman_quarter_turn.py (new host test deliverable).card-shell-hdmi-trial through the pinned board package graph,
leaving the existing default available. Verify nix build .#card-shell-hdmi-trial
(cross-build proof only). Result and exact store paths:
docs/evidence/hdmi-shell-performance/cross-build.json.python3 tools/hdmi-shell-performance.py --check-scene --variant candidate --output docs/evidence/hdmi-shell-performance/scene
(new host/headless harness mode; explicitly not physical acceptance).python3 tools/hdmi-shell-performance.py --capture --input physical --variant candidate --output docs/evidence/hdmi-shell-performance/physical-routing
with operator-confirmed contact during the capture.python3 tools/hdmi-shell-performance.py --compare --baseline docs/evidence/hdmi-shell-performance/baseline --candidate docs/evidence/hdmi-shell-performance/candidate.nix build .#nixosConfigurations.k230.config.system.build.toplevel (build proof).python3 tools/console.py /dev/ttyACM0 --wait=3 'systemctl is-active shell shell-ui'
together with the committed HDMI/panel physical observation and image identity.python3 tools/blob-scan.py --no-vendor, then the matching Pages deployment.openspec validate the-portrait-hdmi-shell-keeps-up-with-touch --strict
immediately before syncing/archive, then inspect the deployed revision.The system-owned shell SHALL preserve full-resolution portrait HDMI layout,
live app contents, backgrounds, alpha and rounded cards while keeping p95
frame-build CPU time at or below 33.3 ms and p95 contact-to-present time at or
below 100 ms for one- and two-Foot-card workloads of at least 24 drags each.
Results SHALL identify format, transform, resolution, runtime revision and input
evidence class. Injected input SHALL NOT be represented as real-glass acceptance.
Grounding for the current failure: docs/evidence/shell-responsive/board/README.md.
The system-owned shell SHALL recognize a real bottom-edge swipe from an ordinary
app into the live overview at the portrait HDMI size. It SHALL preserve ordinary
app touch input away from reserved gesture edges and retain usable keyboard and
shade dismissal. Required proof SHALL pair physical contact/route observations
with operator confirmation, rather than substitute compositor IPC injection.
Grounding for the current failure: docs/evidence/shell-responsive/board/README.md.
Draft proposal · In progress
Snapshot 5836ef1d113d · 2026-10-17 08:22 UTC
Next gateResume the queued Qt Quick cross-build after integrated-shell builds, inspect target closure/QML configuration, then measure the plain app on the board before a Quickshell trial.
PARKED, per the user’s “stale as suggested” decision on
docs/closeout/stale-triage.md. Keep this change open — it is not
abandoned and no decision for or against Qt Quick apps has been reached —
but stop investing further build slots or work in it for now. The
interrupted nix build .#qtquick-software-probe state (28/40 required
derivations cached, cleanly interrupted rather than failed) stays documented
exactly as recorded in docs/evidence/qtquick/minimal-probe-prebuild.md;
that record is not to be re-derived or built further under this decision.
We cannot yet tell whether Qt Quick apps or a Quickshell UI would feel responsive on this handheld. Source research identifies a CPU-rendered route, but a working desktop example does not establish the device’s memory, touch, frame cost or recovery behavior.
Non-goals: Replacing Sway or the live-card compositor, porting the full Omarchy shell, enabling software GL, adding a VG-Lite/Qt graphics bridge, integrating Qt Multimedia or Qt Virtual Keyboard, or changing the default image/session before an adoption decision. This is an evaluation, not a promise of smooth Qt applications generally.
runtime/qtquick-validation: reproducible, opt-in toolkit trials with verified rendering identity, comparable cost measurements, input/recovery observations and bounded adoption decisions.None. The normal shell contract is retained.
Nix probe packages, tiny userspace fixtures, a bounded trial/analysis tool, and committed evidence under docs/evidence/qtquick/. The source assessment is docs/research/quickshell-qtquick-feasibility.md. Host fixture checks and cross-builds can proceed without the board, using the shared build slot. Rendering, latency, real touch, keyboard interaction and restoration require an exclusive board reservation. No stage-1, kernel, device-tree, radio or flash change is presumed.
The pinned source assessment in docs/research/quickshell-qtquick-feasibility.md identifies Qt’s software scene graph as a plausible route under the existing Sway/Pixman session. It does not establish a working RISC-V Qt closure, Wayland client buffers, QML execution mode or device cost. Current card workloads already miss CPU/tracking targets; a weak baseline cannot certify a new toolkit.
Layers: Nix and userspace. The trial runs as clients of the normal compositor. It requires neither a kernel experiment nor a change of persistent boot selection.
Goals: Answer whether ordinary simple Qt Quick apps and then simple Quickshell surfaces are usable, with repeatable package identities, direct-touch observations and comparable costs. Distinguish buildability, rendering correctness, feasibility and suitability for production.
Non-goals: A Qt rewrite, full Omarchy runtime, media/codec acceleration, blanket Qt module certification, new notification daemon, or interpreting a host screenshot as physical proof.
Two sequential probes, one baseline. First build qtquick-software-probe: Qt Base/Declarative/Wayland with primitive text/images, bounded scrolling, tap feedback, editable text and reversible position/opacity animation. Use an equivalent small SHM fixture with the same viewport/content/motion/input script. Only a successful Qt prerequisite permits the separate minimal quickshell-software-probe. A full shell transplant was rejected because it confounds toolkit, effects, desktop services and compositor integration.
Make the actual renderer observable. The trial pins QT_QPA_PLATFORM=wayland, QT_QUICK_BACKEND=software, and QSG_INFO=1, clears inherited RHI forcing for the child, and records effective environment, Qt backend logs, mapped runtime libraries, buffer type/format and presented pixels. Unexpected GL/Vulkan rendering fails the software-route gate. Incidental graphics libraries in a closure are recorded, not treated as proof of hardware use. Keep integer display scaling. A shader/effect negative-control fixture must show the documented unsupported behavior, with a separate simple software-safe replacement; silently missing art cannot pass a feature check.
Pin and measure the build. Use the repository’s pinned Qt packages and exact Quickshell source/Qt ABI. Record cross/native tool separation, configure summaries, QV4 execution mode and QML cache/AOT settings; compare forced interpreter only if the pinned build supports that distinction. Record build duration, unique store closure bytes and incremental closure relative to the normal image. No RISC-V JIT claim is inferred from general Qt documentation. Only opt-in flake outputs are added; normal system dependencies stay unchanged during evaluation.
Freeze a trial manifest before measuring. Record package/system/compositor/Pixman identities, boot ID, panel mode, viewport, scale, workloads, repeats, thermal/frequency samples and budget version. Use three alternating matched pairs per toolkit, 30-second idle and active phases, and at least 24 scripted scroll/drag interactions per active arm. Retain per-run results, not only a pooled favorable percentile. Record cold-after-boot and warm startup separately; process restart is not a cold cache claim. Kernel page-cache flushing is unnecessary.
Separate feasibility gates from production budgets. Functional prerequisite gates are correct pixels, positively identified software/SHM path, usable scroll/tap/text entry/focus, bounded process lifetime, successful restoration, complete measurements and no failure of a previously passing baseline control. Initial proposed trial ceilings, not observed limits, are startup to first presentation at most 5 seconds per run, incremental active-session memory at most 128 MiB, and idle added client CPU at most 2% of one core averaged over 30 seconds. Freeze these in the manifest before trial; changing them requires a versioned rationale, never retroactive PASS.
Compare combined client-plus-Sway CPU and latency against the matched fixture. Report any regression greater than 10% with absolute values and variability; a failed or noisy baseline is INCONCLUSIVE for that comparison. Keep the existing card budget suite and thresholds unchanged (tools/card-shell-benchmark.py), including 16.667 ms p95 frame CPU and 33.334 ms p95 tracking interval. The diagnostic’s 128 MiB ceiling does not relax the card feature’s 64 MiB memory budget. A passing minimal-app prerequisite can justify measuring a Quickshell panel, but cannot justify adopting a production shell while card budgets fail. A frame callback or submit timestamp is not an optical input-to-photon measurement; report measurement boundaries exactly.
Constrain the Quickshell experiment. Reuse the same Qt build and a minimal QML panel with no screencopy, Hyprland, X11, multimedia, notification-server or unrelated services. Verify effective CMake flags (SCREENCOPY=OFF gates the GPU buffer path) and runtime protocols. Test layer-shell anchors, nonexclusive geometry, input region, bounded focus acquisition and release, repeated show/hide and process exit. Test coexistence with keyboard and shell edge gestures. This proves a layer-shell client, not compositor ownership of live cards.
Independent restoration and evidence. Reserve the board and reuse established root watchdog/session patterns, scoped to the transient probe processes. Arm a fixed deadline before any focus or scene changes; kill only owned process groups and release their surfaces on timeout/cancellation/SSH loss. Observe the original normal compositor identity and reachable Terminal/keyboard after every trial. Native capture, physical camera, real finger, injected input and host fixture results remain labeled separately. Public results contain fixed-schema measurements and reviewed media, not raw process environment, desktop titles or network details.
Land this plan, implement host fixtures/manifest/analyzer and separate probe packages, then take the board only after host guards pass. Record the Qt result before opening the Quickshell gate. Publish an apps decision and a shell-surfaces decision, each linked to its evidence. Adoption needs a separate implementation decision/proposal; these packages never become normal defaults merely because they build. If an earlier gate fails, keep dependent tasks explicitly unperformed and the proposal open; do not tick tests or archive by implication.
The probe outputs, analyzer and trial commands below are planned interfaces,
not existing tools or completed checks. Each owning task adds its interface
before invoking it. Evidence belongs in docs/evidence/qtquick/ with exact
source/store identities and explicit host, injected-input and physical labels.
Parked by user decision (2026-09-28): stop investing further build slots
or work in this change for now — see Status (2026-09-28) in
proposal.md. Task 1.1 below stays unticked and its interrupted build state
(28/40 derivations, cleanly interrupted) remains documented exactly as-is in
docs/evidence/qtquick/minimal-probe-prebuild.md; do not resume the build
under this decision.
nix build .#qtquick-software-probe --max-jobs 1 --cores 4 --no-link --print-out-paths. Retain configure/QV4/cache mode, build time, Qt/Wayland identities and nix path-info -rsS PROBE_OUT; a failed build is retained, not a physical result.nix build .#qtquick-shm-baseline --max-jobs 1 --cores 4 --no-link --print-out-paths and host scene/output fixtures with python3 tests/test_qtquick_probe_scene.py.Proof: the two narrow build commands and host fixture check above. No normal-image integration or board claim.
python3 tools/qtquick-trial.py --self-test.python3 tests/test_qtquick_trial_recovery.py. Document exact operator commands and required board lock.python3 tools/qtquick-trial.py prepare --qt PROBE_OUT --baseline BASELINE_OUT --output NEW_MANIFEST rejects missing or mismatched artifacts and records workload/budget version.Proof: the named self-test, recovery tests and prepare command. Host recovery simulation is not physical restoration proof.
python3 tools/qtquick-trial.py board --manifest MANIFEST --stage qt --output NEW_EVIDENCE_DIR; commit backend/SHM identity, native captures, three matched pairs, startup/CPU/session-memory/presentation/input results and normal-session restoration. Use concrete paths in the evidence record and retain failures.python3 tools/qtquick-trial.py decide --stage qt --evidence NEW_EVIDENCE_DIR; retain each pass/fail/incomplete criterion and a separate production-budget result. Do not start the Quickshell board stage unless the prerequisite passes.Proof: exact recorded board and decision commands plus real-glass checklist/media. No camera or host fixture can substitute for measured compositor presentation, and no timestamp is labeled optical latency without optical proof.
nix build .#quickshell-software-probe --max-jobs 1 --cores 4 --no-link --print-out-paths, record feature summary and incremental closure size.python3 tools/qtquick-trial.py board --manifest MANIFEST --stage quickshell --output NEW_EVIDENCE_DIR under a fresh board reservation; retain layer-shell/backend proof, matched measurements and physical input-region/focus/keyboard/edge-gesture/show-hide/exit/restoration observations.python3 tools/qtquick-trial.py decide --stage quickshell --evidence NEW_EVIDENCE_DIR and commit the app-versus-shell recommendation with explicit module/effect limits. A simple panel cannot certify full Omarchy or live-card composition.Proof: narrow package build, concrete board trial and decision invocations. If the prerequisite fails, these tasks remain unperformed/open; do not mark them successful because the gate was evaluated.
python3 scripts/build_site.py and inspect the exact published revision.openspec validate --all --strict; archive/sync only once all required execution and recovery proof exists, preserving any proposed adoption as a separate explicitly scoped change. Keep the proposal open if a dependent stage was not performed.Proof: site build, strict validation, reviewed evidence and exact-revision CI/deployment. This change does not add a default Qt/Quickshell session.
Provide reproducible, opt-in Qt Quick and Quickshell trials so toolkit choices for the handheld are based on observable rendering, input, cost and recovery evidence.
The system SHALL offer an opt-in Qt Quick Wayland probe with software rendering, basic touch UI and exact package/runtime identity reporting. It SHALL distinguish cross-build success, host rendering and physical rendering; unsupported effects MUST be identifiable rather than silently accepted.
The trial SHALL preserve per-run startup, client and compositor CPU, session memory, presentation/input timing, closure size and workload identities for matched baseline and candidate runs. Budgets and repeat count MUST be fixed before execution. Missing samples, changed identities or untrustworthy baselines SHALL remain incomplete; existing card budgets MUST NOT be relaxed to certify the toolkit.
The system SHALL permit a minimal Quickshell layer-shell trial only after the declared Qt prerequisite passes. The trial SHALL verify its software renderer, focus, input regions, repeated visibility changes and coexistence with the keyboard and shell gestures. It MUST NOT imply that a panel is a compositor, or that a full Omarchy configuration is supported.
The trial SHALL run within an independently bounded lifetime, preserve the known normal session, and record its restoration after success, failure or cancellation. Real finger observations, injected inputs, native captures and host checks MUST remain distinct evidence classes. Final recommendations SHALL separately assess Qt Quick apps and Quickshell shell surfaces with remaining limitations.
Draft proposal · In progress
Snapshot 5836ef1d113d · 2026-10-17 08:22 UTC
Next gateResolve target format and presentation costs, then repeat paired GPU-versus-Pixman acceptance on the board before any default change.
The handheld shell still draws through Pixman on its single online Linux CPU. We need to establish whether its GPU can reduce real shell rendering cost while preserving working touch controls and display output.
The validated VG-Lite path used private buffers, not Sway’s render pass. Its full-panel elapsed time was comparable to Pixman, so it does not justify a compositor rewrite on wall time alone. The committed validation record limits the result to RGB565, one premultiplied-alpha case, and private dma-buf import; it explicitly leaves live compositor integration unproven (docs/evidence/gpu-validation/README.md).
The three-round CPU transcript at docs/evidence/gpu-validation/cpu-timing-pass.txt may justify an experiment because panel-size GPU work used far less process CPU. It cannot establish system-wide offload: process CPU includes user and system time charged to the process; it excludes other processes, separately accounted interrupt work, and whole-device cost.
begin_buffer_pass; it does not open a second DRM client or create a competing scanout path.runtime/gpu-composition-trial: An opt-in actual Sway/wlroots renderer experiment with per-frame coherent fallback and board-evidence gates.None.
This requires a maintained local fork of pinned wlroots 0.20.2 and an opt-in Sway package linked to it. It touches renderer, texture and render-pass code, not a desktop client. It does not alter stage 1, device tree, normal Sway, video decoder selection, or DRM ownership policy.
Physical-board trials are required for live composition, cache ownership, scanout, interaction and performance acceptance. Host builds and operation tests can proceed independently while the coordinator reserves the board. General GPU support and changing the default renderer are non-goals.
The physical probe established exact private RGB565 composition using VG_LITE_BGR565, one premultiplied-alpha result, and private dumb-buffer dma-buf import. The committed record at docs/evidence/gpu-validation/README.md also records that this is not live compositor or scanout proof. Three CPU-timing rounds are committed at docs/evidence/gpu-validation/cpu-timing-pass.txt: at 568x1232, GPU finish used about 0.10 ms process CPU versus Pixman’s 1.70 ms while wall time was about 1.97 ms versus 1.78 ms. Process CPU includes user and system time charged to the process; it does not measure other processes, separately accounted interrupt work, or whole-device cost.
The current shell explicitly selects Pixman in nix/shell.nix and uses Sway with wlroots 0.20. The pinned wlroots source creates the output buffer in types/output/render.c:wlr_output_begin_render_pass, passes it to wlr_renderer_begin_buffer_pass, and commits the result from types/scene/wlr_scene.c. Scene rendering emits rectangles and textures through wlr_render_pass_add_rect and wlr_render_pass_add_texture in that file. The renderer and render-pass vtables are unstable compiled interfaces in include/wlr/render/interface.h; operation options, clipping, blend, filter, color and explicit-sync fields are in include/wlr/render/pass.h.
Goals:
wlr_renderer backend under the existing Sway scene and DRM backend.Non-Goals:
wlroots has no runtime loadable renderer plug-in interface: the renderer and render-pass vtables are compiled interfaces. The experiment therefore needs a local fork of pinned 0.20.2, adding a VG-Lite struct wlr_renderer_impl, struct wlr_texture_impl, and struct wlr_render_pass_impl, plus an opt-in Sway package built against that fork. Calling a separate painter “the renderer” would not exercise the Sway scene path and is insufficient.
The default package keeps WLR_RENDERER=pixman. The opt-in package may select the fork’s VG-Lite renderer only after host and board gates pass. It must not expose /dev/vg_lite to ordinary Wayland clients.
Sway and its existing wlroots DRM backend retain DRM master, output selection, swapchain allocation, and commit ownership. For every frame, wlr_output_begin_render_pass supplies the destination struct wlr_buffer. The VG-Lite backend may obtain dma-buf attributes with wlr_buffer_get_dmabuf and import that specific output buffer; it does not open a card node, allocate an independent scanout buffer, modeset, or commit. It returns after wlr_render_pass_submit, so the existing owner continues the normal commit path.
The forked render pass records immutable copies of each add_rect and add_texture operation until submit. At submit it selects one path:
No command is sent to VG-Lite before path selection. This avoids a frame where one unsupported texture, clip, or blend leaves an incomplete GPU buffer that Pixman then tries to repair. A failure after GPU work starts fails submit, lets wlroots discard the frame/damage ring as it already does, and forces the next frame to Pixman; it must not commit a partial buffer.
The initial VG-Lite eligibility table must be implemented and tested before a board session:
| wlroots render-pass input | Initial experimental handling |
|---|---|
| Destination | Only the wlroots-provided dma-buf proved to have a DRM format / VG-Lite mapping. The board result points to DRM RGB565 memory with VG_LITE_BGR565; every plane, stride and modifier must be checked. |
add_rect | Opaque and premultiplied rects after exact color conversion, with the supplied clip region. Unsupported color/clip makes the whole pass Pixman. |
add_texture | First establish wlr_texture_from_buffer and exact WL_SHM XRGB/ARGB mapping. Conversion/upload into a VG-Lite source allocation is permitted only after samples prove it. Arbitrary dma-buf textures, modifiers and YUV cause whole-pass Pixman replay. |
| Scaling / transform | Nearest scale only after source/destination and bounds tests. Bilinear, non-identity output transforms and unsupported source boxes cause replay. |
| Blend | Only observed premultiplied SRC_OVER and NONE, once matched to wlroots’ premultiplied wlr_render_color contract. Any mismatch causes replay. |
| Clip / damage | Translate every pixman clip only after region tests. Until then, any nontrivial clip or partial damage makes the entire pass Pixman. Full-frame GPU redraw may be enabled only after preservation of undamaged output is proved. |
| Color / synchronization | Transfer functions, primaries, YCbCr fields, timeline waits/signals, and unproved cache transitions cause replay. |
The table reflects fields actually carried by wlr_render_texture_options and wlr_render_rect_options, not a claimed VG-Lite feature set. types/scene/wlr_scene.c supplies damage-driven background and scene operations, so treating damage as ignorable would be incorrect.
The vendor library directly opens /dev/vg_lite; the normal shell and its
clients share one UID. Giving that UID device access would violate the client
boundary. A separate root-owned diagnostic Sway may use the same DRM backend
with a fixed no-exec/no-bar/no-Xwayland configuration, disabled swaybg/swaynag,
root-private IPC and externally launched unprivileged Wayland probes. Only its
Wayland socket is shared. Transient cgroup lifetime, a pre-armed recovery timer,
and verified restoration of the normal shell bound the trial. It is sufficient
only to investigate actual scene passes; it does not replace normal-session
access or interaction requirements. The normal-service source implementation now uses a root socket broker granting
only the authenticated systemd MainPID a CLOEXEC descriptor, with non-dumpability,
Yama startup protection, child fd revocation and DONTFORK mappings; see
docs/research/vglite-service-access.md. Its opt-in defaults false and its
privileged integration/physical acceptance remain open. Source analysis and the required privileged
credential test are in docs/research/vglite-diagnostic-access.md.
The sole submission thread calls vg_lite_finish before a successful VG-Lite submit. The fork must prove C908 cache clean/invalidate direction for the imported target and CPU-uploaded source, and identify how wlroots/DRM consumes the buffer and whether source timeline fields can be honored. Until that proof, it uses synchronous completion and rejects operations with timeline fields rather than claiming a fence.
Ship no changed default. Build the fork and experimental Sway separately, run only board-coordinated trials, retain per-pass fallback logs and evidence, then either remove the experiment or open a separate default-change proposal after all readiness gates pass.
wlr_renderer_impl, texture implementation, and record/replay wlr_render_pass_impl; build an opt-in Sway against that fork while normal Sway remains Pixman.begin_buffer_pass, accept only the output wlr_buffer supplied by the existing DRM backend; implement checked dma-buf import and prove no renderer code opens DRM, becomes master, modesets or commits.add_rect and add_texture options without GPU submission, then choose all-VG-Lite or full-Pixman replay at submit; verify failures do not commit a partial frame.Host proof for group 1: nix build .#shell-compositor-vglite --no-link --print-out-paths
and WLROOTS_SOURCE=<pinned-wlroots-0.20.2> VGLITE_SOURCE=<pinned-sdk-vg_lite> tools/test-vglite-renderer.sh.
Source/host evidence: docs/evidence/vglite-renderer-host.md. No physical claim.
2.1 Establish target format, plane, stride and modifier handling. Start with demonstrated DRM RGB565 / VG_LITE_BGR565; reject every unproved format or modifier.
2.2 Establish wlr_texture_from_buffer source ownership and exact WL_SHM XRGB/ARGB conversion/upload. Add sampled texture, nearest-scale, source-box and bounds tests; route arbitrary dma-buf, YUV and unproved input formats to full-pass Pixman replay.
2.3 Implement and test premultiplied SRC_OVER, NONE, pixman clip translation, and damage behavior against pinned wlroots render-pass fields. Use Pixman for unsupported clip, transform, filter, color or partial-damage cases until proven.
2.4 Serialize VG-Lite submission, call vg_lite_finish, prove C908 cache ownership in each CPU/GPU direction, and determine whether wlroots timeline fields can be honored. Reject timeline operations until then.
2.5 Establish compositor-only VG-Lite device access for the normal shell service without exposing the vendor API to ordinary clients sharing its UID. The separate root scene diagnostic does not satisfy this gate. Source implementation and host tests: docs/research/vglite-service-access.md and docs/evidence/vglite-service-access-host.md; actual privileged broker/service and board device proof remain open.
Host operation proof: the same sanitizer-backed renderer test above, comparing
against the pinned wlroots Pixman pass. Physical format/cache proof remains a
separate board gate, recorded in docs/evidence/vglite-renderer-host.md.
openspec validate the-shell-trials-vglite-composition --strict and ./tools/blob-scan.py --no-vendor.Diagnostic access analysis and bounded harness: docs/research/vglite-diagnostic-access.md. Host lifecycle check: python3 tests/vglite/test_root_trial.py. Actual privileged credential isolation is a separate prerequisite: python3 tests/vglite/check_root_trial_credentials.py --user shell as root; exit 77 is not proof.
Board scene trials and fixed-schema decisions: docs/evidence/vglite-scene-board/README.md.
The instrumented trial produced zero GPU frames and 224 Pixman replays; normal
shell recovery passed. Ordinary color metadata and 1136-byte target stride
were observed rejection reasons. Source/host default-color handling is now
tested separately. The later padded-buffer trial in
docs/evidence/vglite-scene-board/padded/README.md completes 3.1: 196 actual GPU
frames with zero replays, versus 576 replays when explicitly forced to Pixman
on the same allocation. Captures reveal an RGB565 color-step mismatch;
format/cache correctness, normal-service access, and matched performance/
interaction gates remain open.
The RGB565 upload correction in
docs/evidence/vglite-scene-board/color-upload/README.md now matches the actual
parent/child scene palettes against forced Pixman without tolerance. The board
records 182 GPU frames with no replays and successful normal-shell restoration.
This resolves that observed color discrepancy; remaining format/scale/cache,
normal-service, control and performance gates in groups 2–3 stay open.
The system SHALL keep the current Pixman Sway session as the default. An experimental session SHALL be a Sway package built against a local wlroots renderer fork and SHALL receive the real wlroots scene render passes; a separate Wayland client or private-buffer painter does not meet this requirement.
The experimental renderer SHALL use only the struct wlr_buffer supplied by the existing wlroots output path for its render pass. Sway’s existing wlroots DRM backend SHALL remain the sole DRM master, swapchain allocator and scanout committer.
The experimental renderer SHALL record a complete render pass before submitting GPU work. If target format, texture import, clipping, blending, transform, damage, color conversion, synchronization or cache requirements are not supported, it SHALL replay the complete pass through Pixman into the same wlroots-provided buffer.
The project SHALL not make the experiment default until board evidence proves actual Sway render-pass use, exact target/source formats, clipping and blend semantics used by the shell, damage correctness, completion/cache ownership, stable interaction, and a repeatable benefit compared with the same Pixman scene. Process CPU evidence SHALL state that it includes user and system time charged to the process, and excludes other processes, separately accounted interrupt work and whole-device cost.
Archived change · Archived
Snapshot 5836ef1d113d · 2026-10-17 08:22 UTC
Closed recordAccepted static-theme parent closed at 25/25. Matching consumers are installed and ordinary startup verified. Background/video successor retains its scope.
A person cannot currently clone an Omarchy theme and use its complete appearance on the handheld. Hardcoded colors and independently styled clients would make the proposed card shell inconsistent and force theme authors to maintain a second format.
themes/ collection. No conversion, fork, manifest injection, or edits inside the checkout are required.the-background-chooser-supports-fill-solid-and-video; this change retains still-image crop selection and memory.Non-goals: Installing Omarchy/Arch, replacing Sway with Hyprland/Quickshell, executing theme scripts or Lua, adopting Omarchy’s desktop navigation, adding a lock screen, RGB keyboard hardware or haptics, promising themes for apps we do not ship, or claiming every arbitrary video codec runs smoothly on this board. Absent surfaces and hardware remain explicit in the compatibility report, with their data preserved.
runtime/shell-themes: unchanged Omarchy theme sources, complete appearance resolution, coordinated activation, background selection, reproducible defaults, and honest compatibility reporting.None. This adds appearance behavior without changing the existing shell navigation or sibling card/design contracts.
Userspace theme loader and adapters, launcher icon resolution, card renderer tokens, settings/notification clients, keyboard/app configuration, wallpaper lifecycle, Nix defaults, and later feature evidence. The pinned upstream survey is in docs/research/omarchy-quattro-theme-compatibility.md. Parser, fixture, rendering, and failure tests can run on the host; cross-builds use the existing sole build slot. Readability, touch selection, motion cost, reboot persistence, and recovery require the reserved physical board. This proposal ships no theme implementation and proves no board behavior.
The operator accepted implemented behavior and explicitly waived further proof collection. This closes the revised physical-evidence disposition tasks, with missing recordings, costs and individual boot cases still UNVERIFIED. It does not waive actual consumer implementation gaps. The closeout record preserves the acceptance and superseded requests.
See proposal.md for motivation and docs/research/omarchy-quattro-theme-compatibility.md for pinned upstream sources. Quattro’s current theme format includes data beyond its palette. Our Sway/Pixman shell and in-flight card, Settings, notification and icon work need a common appearance interface. No theme importer exists yet. Layers: userspace and Nix; no stage-1, kernel or device-tree changes.
Goals: Direct unchanged-clone use, complete data preservation, explicit surface mappings, bounded portrait rendering, reproducible defaults and recoverable live switching.
Non-goals: Running the Omarchy installer, sourcing foreign shell/Lua, importing desktop navigation, or adding missing hardware/surfaces just to consume their theme fields. Preserve the sibling coherent-shell motion, minimum touch targets and recovery contract.
Read-only source plus derived generations. Accept a theme directory or collection member. Nix fetches pinned defaults with content hashes; user clones remain ordinary checkouts. Resolve each source into a validated immutable generation in a private cache and publish it atomically. Cache identity includes actual input hashes, compatibility version, image decode policy and icon dependencies; Git HEAD alone misses local edits. Updates never perform implicit Git pulls. Retain the last working generation and selected wallpaper independently of a removed clone, including at boot. A fresh home without a valid saved generation uses the packaged default; removing only the source does not reset a valid cached selection. Reject path escapes and executable directives as inputs, without deleting files. No plugin hooks run. A converted native theme format was rejected because it creates a fork the user must maintain.
Reuse Omarchy’s working mechanism. Package pinned omarchy-theme-color, omarchy-theme-set-templates, omarchy-theme-colors-from-alacritty, omarchy-theme-osc, and relevant appearance templates with their license. Keep omarchy-theme-set NAME, ~/.config/omarchy/themes/NAME, and ~/.local/state/omarchy/current/{theme,theme.name,background} as compatible entry points. A small coordinator derived from upstream omarchy-theme-set handles our source selection and validated activation; a shell bridge consumes its shell applyTheme and background themeTransition payloads. Replace the desktop-specific post-theme command list with installed-client adapters. Upstream’s headless mode can generate files but skips live shell/app updates, so it is not the runtime solution by itself. Pin Bash/coreutils/awk/sed/util-linux dependencies through Nix. Do not package the entire Omarchy desktop or fake every unsupported command with success stubs. A separately invented palette/template parser was rejected in favor of using their tested implementation.
The template helper hardcodes its staging/user-template paths. Carry a minimal documented path-parameter patch so the wrapper supplies isolated staging and curated template directories without changing the user’s HOME or writing to the clone. Default public state paths stay compatible. Limit generated template outputs to declared filenames inside staging; report unresolved placeholders before activation. The small shell-side loader parses already generated data into C/Cairo values, keeping raw keys, provenance, resolved palette, backgrounds, icon selector and compatibility report. It is an adapter, not a second palette engine. Preserve custom data and diagnose unresolved references. The coordinator must improve two upstream boundaries: rm followed by mv is not an atomic replacement for concurrent readers, and upstream tolerates failed IPC with || true. Publish versioned output through an atomic pointer and require acknowledgement/rollback for our shell; serialize late app reloads against their generation. This does not require changing a theme repository.
Exact override semantics. Use the upstream helpers for aliases, derived shades, scalar/mix/gradient template operations and section replacement; generate shell defaults only if no theme shell.toml exists; replace each shell.<section>.toml section; apply machine override keys last; then evaluate consumer fallbacks. Section replacement is intentionally different from key merging. Restrict application adapters to appearance keys even if the source file can also contain commands. Legacy Alacritty palette import runs the upstream helper only against a scratch copy, never the clone. Trusted packaged helpers are distinct from executable content supplied by a theme. Every imported source is treated as theme data regardless of whether its .git is a directory, file or absent.
One shared appearance contract. The research inventory maps every upstream section to our surface or an explicit absent consumer. Cards consume menu and border roles; drawer uses launcher; Settings uses menu/popups/controls; notifications and image picker use their own roles. Keyboard and local app adapters share the resolved palette. Upstream bar tokens do not create a bar. Preserve gradient stops, angles, alpha composition and per-side widths using cached Cairo/Pixman artwork. Typography/spacing are scaled to handheld design constraints, with an adaptation report rather than silent pixel changes. Reuse the in-flight icon resolver with selectable theme inheritance and invalidate its cache on theme generation changes.
Installed app adapters are enumerated. Inventory Foot, htop, mpv, nano/editor, nnn/files and Help plus keyboard and Sway chrome. Document which support exact colors, terminal inheritance, restricted built-in palettes or only partial appearance control. Implement each applicable adapter and show limitations; never imply arbitrary third-party UI obeys a terminal palette. Existing sessions receive supported reloads; restart-only changes are stated without killing apps. Applicable deficits are open work, not an excuse to tick full integration.
Wallpaper is a separate bounded consumer. Enumerate upstream image/video suffixes and sniff actual format, retain all choices, lazy-generate bounded previews, decode static images once at output size, and use aspect crop by default. User fit/crop/center/solid preferences and background overlays live outside the clone. Keep per-theme source-relative asset identity across generation changes. Re-selecting the active theme can explicitly cycle, while refresh is idempotent. The authorized the-background-chooser-supports-fill-solid-and-video successor owns overlays, additional fit modes, and muted video loops with visibility/reduced-motion pause, bounded decode/output, timeout and still fallback. Its task 3.3 retains the paired static/video performance and covered-media gates. This parent retains still-image crop selection, memory, removed-file recovery and a physical static workload; video playback is not claimed here. Neither wallpaper animation nor switching may worsen the existing card acceptance gates; a reduced rendering mode is visibly identified.
Transactional touch selection. Settings provides scrollable theme/background previews, tap selection, cancellable preview and apply. Prepare assets before transition; swap one generation at a scene boundary, preserving touch/focus ownership and card identity. Use existing motion rules and reduced motion. A failed consumer acknowledgement restores the previous shell generation; app reload status is reported separately. Serialize activation and retain a recovery default accessible via the existing Terminal route. No theme parsing or unbounded decoding on a drag frame.
Land the planning artifacts first. Implement loader/fixtures, then shared adapters and static backgrounds in independent task groups coordinated with sibling shell owners. Add a declaratively pinned default behind an opt-in trial. Complete video-background measurement separately. Reserve the board for exact-generation captures, real touch, reboot persistence and failure recovery; retain the normal session as rollback. Enable the default only after these gates. Archive only with all implementation and physical tasks complete; a host fixture pass cannot certify the device.
The reboot-v2 operator protocol enforces decision 1 instead of requiring a reset when the source disappears. It binds the retained generation, wallpaper fingerprint and preference bytes, and requires a catalog with no source id and the same generation. Old reboot-v1 checkpoints remain recoverable but cannot resume under the changed acceptance policy. No runtime receiver change or firmware rebuild is required.
The operator’s explicit proof waiver replaces further collection for already implemented behavior, not missing source work. Record the disposition and retain UNVERIFIED markers for absent measurements and specific physical trials. Consumer coverage and complete compatibility publication still gate archive.
All tasks are initially open. Commands naming new tools, tests or flake outputs
below are planned interfaces, to be added by that task before invocation;
they are not claims that those interfaces exist or have passed today. Host,
cross-build and physical proof are separate. Store committed results under
docs/evidence/omarchy-themes/ with revisions, commands and limitations.
nix build .#omarchy-theme-tools and record the output. Reserve the sole build slot..git directory clones, .git file worktrees and source directories without Git metadata. Record source hashes/licenses and prove no checkout changes with python3 tests/test_omarchy_theme_sources.py.python3 tests/test_omarchy_theme_resolution.py.omacom/omarchy themes/ collection (22, verified with ls themes/ against the fetched source) into nix/handheld-theme-default’s $out/share/omarchy/themes, not only catppuccin/catppuccin-latte. Fixed a real parser gap this surfaced: three built-ins (hackerman, last-horizon, solitude) set hyprland_active_border/hyprland_inactive_border to a multi-stop Hyprland rgba(RRGGBBAA)/rgb(RRGGBB) gradient, which neither tools/theme_tokens.py’s _argb nor the Rust receiver’s palette_value (nix/rust-shell-client/src/appearance.rs) accepted; both are now fixed with new unit tests (tests/test_handheld_theme_rendering.py::test_hyprland_hex_gradient_and_bare_rgb_are_distinct_from_css_decimal_form, nix/rust-shell-client/tests/appearance_module.rs::builtin_multi_stop_hyprland_gradient_palette_uses_first_stop_color), and all 22 built-ins now resolve. Measured upstream backgrounds at 66.4MB raw across all 22 themes (53MB backgrounds) against a 568x1232 panel with a compact-image requirement (openspec/specs/image/sd-layout/spec.md); 20 of the 22 (all but catppuccin/catppuccin-latte, whose bytes and generation identities are pinned) now ship a build-time imagemagick mogrify -resize 'x1250>' -quality 82 -strip background derivative at the same relative path, since every upstream background is landscape/square and the runtime decoder already crops to exact output size on every decode. This keeps the “unchanged theme checkout” requirement’s contract (no source-checkout mutation at use-time, generated output lives outside it) — see nix/handheld-theme-default/SOURCE.md — without a spec change; only background pixels are a derivative, not palette/icon/metadata. Verified with python3 tests/test_handheld_theme_bundle.py --package $(nix build --no-link --print-out-paths --max-jobs 1 --cores 4 .#handheld-theme-default), which now also runs every built-in through the real theme_activate.prepare() path (check_all_builtins_resolve) and asserts every bounded background is <= 1300px tall in the installed package. Measured closure: 28.7MB (nix path-info -S) for all 22 bounded, a single self-contained store path, versus 66.4MB unresized — 58% smaller for 11x the theme count of the previous 2-theme package. No panel/real-finger review of the new themes’ readability exists yet; that is task group 5’s reserved-board gate, unchanged by this slice.Proof: nix build .#omarchy-theme-tools is a package cross-build; the two Python invocations are host checks only. No device claim.
omarchy-theme-set NAME and paths plus direct source/collection selection, using upstream helpers and a narrow coordinator; test clone preservation, legacy scratch conversion, path boundaries and unknown-key reporting with python3 tests/test_omarchy_theme_activation.py. Closeout audit (2026-09-28): tools/omarchy-theme-set is a thin wrapper around tools/theme_activate.main() (fails closed with a plain stderr message on ThemeError/TransactionError/etc.); tests/test_omarchy_theme_activation.py now has 14 host cases covering exactly this list — test_selected_generation_and_public_paths_survive_removed_clone (clone preservation), test_legacy_palette_is_converted_only_in_scratch (legacy scratch conversion), test_rejects_escape_malformed_palette_and_oversized_input (path/escape boundaries) — all passing (python3 -m unittest tests.test_omarchy_theme_activation, 14 tests, OK). This landed across many commits after docs/evidence/omarchy-themes/endpoint-fanout-host.md’s 2026-09-23 checkpoint (which said this task was still open); that checkpoint is superseded by the later work, not by this tick alone.python3 tests/test_omarchy_theme_activation.py. Closeout audit (2026-09-28): tools/theme_transaction.py’s activate_generation()/exchange() two-phase protocol now fans out to both the Rust and deck receivers, and tests/test_omarchy_theme_transaction.py has 24 host cases covering exactly this list (test_a_genuine_commit_failure_for_a_warm_receiver_still_rolls_back_fully, test_rollback_failure_still_contacts_other_receiver, test_second_commit_failure_restores_pointer_and_both_receivers, test_unacknowledged_rollback_is_reported, test_activate_skips_a_prepare_already_warm_for_both_receivers for generation ordering/concurrent-swap skip, test_dangling_foreign_active_pointer_is_not_replaced for removal-of-a-source, test_post_replace_sync_failure_restores_previous_pointer for update invalidation), all passing. This is exercised live, not just in host fixtures: docs/evidence/theme-picker/background-selection/README.md, docs/evidence/theme-picker/store-relocation/README.md and docs/evidence/theme-picker/finger-tracking/README.md all show this exact coordinator driving the real Rust receiver on the physical board. docs/evidence/omarchy-themes/endpoint-fanout-host.md’s 2026-09-23 “task 2.2 … remain[s] open” note is stale, superseded by this later work.nix build .#handheld-theme-service and record its output and source revision. Closeout audit (2026-09-28): the literal handheld-theme-service flake attribute was never added — the capability landed under different names: nix/shell.nix’s systemd.services.theme-helper (mkIf cfg.coherentShell, ExecStart = k230-theme-helperd --listen /run/shell/theme-helper.sock) is the service, packaged by the handheld-theme-command derivation (nix build .#handheld-theme-command, confirmed buildable in this audit). The pinned default and fresh-home startup are nix/handheld-theme-default (nix build .#handheld-theme-default), documented with host identities in docs/evidence/omarchy-themes/persistent-default.md (exact upstream file hashes, fresh-home-needs-no-writable-state behavior, nix eval showing the opt-in k230.shell.themeReceiverTrial wiring installs handheld-theme-command). Persistent optional selection is real: selection is opt-in via coherentShell/themeReceiverTrial, not on by default in the base k230 image. Ticking on the capability, not the literal (never-added) attribute name.Proof: python3 tests/test_omarchy_theme_activation.py, python3 tests/test_omarchy_theme_transaction.py and nix build .#handheld-theme-command .#handheld-theme-default (the handheld-theme-service attribute named above was never added; see 2.3’s own note). Host failure injection and package construction do not prove physical rollback or reboot behavior; that is task group 5’s own reserved-board gate, not this group.
3.1 Build the generated-token consumer and coverage inventory for all upstream fields; verify real gradient stops/alpha, per-side widths, references, control states and font/spacing adaptations with python3 tests/test_handheld_theme_rendering.py and reviewed host captures. Completed 2026-10-10: the 102-field inventory now names production hover/focus owners, global bounded Rust/C metrics and applicable overlay scrims. Proof and limitations: docs/evidence/omarchy-themes/consumer-closeout-2026-10-10/README.md and host-results.json (436 Rust library cases, 13 C receiver, 7 rendering/inventory, 14 activation, 27 transaction; all passed; one diagnostic ignored; all targets compile). Six paired native-size host Cairo/Pango captures reviewed. Idle borders/persistent launcher selection remain deliberate layout omissions; geometry remains fixed and visual metrics bounded. No new physical result is inferred; the already committed operator waiver applies.
3.2 Integrate drawer and card chrome with the shared generation and selected icon theme; verify actual source icon inheritance/cache invalidation plus dark/light captures with python3 tests/test_handheld_theme_rendering.py --surface drawer-card. Coordinate with existing icon/card worktrees. Closeout (2026-10-02): host proof complete; see docs/evidence/omarchy-themes/drawer-card-generation/README.md. The named command exercised the production drawer-generation cache key, Rust inherited-icon decode/cache clear/redecode, the production card icon resolver with local and inherited theme assets, and the card appearance receiver forwarding of report.json icon_theme; it captured reviewed dark/light production drawer frames from pinned immutable generations. A separate exact-pinned headless QEMU pair produced dark/light card composition captures plus a light drawer frame, verified wallpaper source samples, endpoint rollback and restart persistence. No panel/glass or real-finger acceptance is claimed; those are independent group-5 gates.
3.3 MOVED, NOT PERFORMED HERE (Settings/notifications portion only): integrate Settings, notifications, chooser and keyboard as those sibling clients land; verify every corresponding role and explicit absent-surface report with python3 tests/test_handheld_theme_rendering.py --surface system. Do not tick this while consumers are only mockups. Closeout audit (2026-09-28): nix/handheld-settings.nix and nix/handheld-notifications.nix exist as real packages (not named mockups), and the chooser (theme_ui.rs) is thoroughly themed already, but no --surface system test flag exists and no evidence documents Settings/notifications actually consuming generated theme tokens end to end. The chooser/keyboard portions of this task stay here and are satisfied by 3.3.k and task group 4 — that part of this task is genuinely done, not moved. Scope split authorized by the user on 2026-09-28 (“yes a-d and f”): the Settings/notifications portion is carried forward verbatim into the successor the-settings-and-notifications-surfaces-are-themed (its own tasks 1.1-4.2, including the --surface system flag this task named but never implemented). No Settings/notifications theme wiring has been verified by this change; that work is not done, only relocated.
3.3.k Keyboard slice only: derive wvkbd’s seven start-up colour flags (--bg/--fg/--fg-sp/--press/--press-sp/--text/--text-sp) from the resolved palette in tools/keyboard_appearance.py; the supervised launcher (nix/shell.nix k230-supervised-keyboard) reads the published keyboard-appearance/active/wvkbd.args (falling back to a packaged default) and a persisted k230-keyboard-visible marker so a colour-triggered restart keeps shown/hidden state without a post-restart signal race; theme_activate.py/theme_catalog.py call keyboard_appearance.sync_and_restart right after the existing app-appearance post-commit call, reporting keyboard_appearance independently of shell/app status. Restart only ever signals a same-uid wvkbd-mobintl when the launcher’s own sentinel proves something resupervises it, so the non-coherent-shell legacy keyboard is never killed without a restart. Verified with python3 tests/test_handheld_keyboard_theme.py (host, 15 cases) plus the existing test_handheld_app_themes.py, test_handheld_theme_rendering.py, test_handheld_theme_default.py, test_handheld_theme_bundle.py, test_omarchy_theme_activation.py, test_omarchy_theme_transaction.py, test_theme_catalog.py and nix build .#handheld-theme-default .#handheld-theme-command. Settings/notifications/chooser integration and the --surface system test flag are NOT part of this slice and remain open; do not read 3.3 as complete. No panel, touch, focus-preservation or reboot evidence exists for this slice; that needs the reserved board.
3.4 Inventory and implement installed app appearance adapters, reusing Foot config/OSC; verify safe session-scoped reload and per-app limitations with python3 tests/test_handheld_app_themes.py. Closeout audit (2026-09-28): tools/app_appearance.py implements Foot config-file plus live-OSC recolour with an activation-lock-bounded sync; tests/test_handheld_app_themes.py has 9 host cases covering exactly this list — test_preparation_preserves_source_and_explicit_ansi, test_osc_is_exactly_upstream_order_and_never_contains_commands (safe OSC), test_sync_wait_is_bounded_by_activation_lock/test_live_osc_holds_activation_lock_through_flush (session-scoped reload), test_late_app_sync_never_reselects_prior_generation (per-app limitation: a late sync can’t undo a newer selection) — all passing (python3 -m unittest tests.test_handheld_app_themes, 9 tests, OK).
Proof: the named host rendering and app-adapter tests plus reviewed capture hashes. Build each changed derivation separately before image integration; these tests alone do not establish panel readability or touch correctness.
Current acceptance disposition (2026-10-10): the additional physical collection mentioned in earlier coverage checkpoints is waived for implemented behavior. Task 3.1 remains open for actual control-state and typography/spacing consumer gaps, not for new camera or latency evidence.
python3 tests/test_handheld_theme_backgrounds.py. Closeout audit (2026-09-28): partial. Per-theme selection memory is done — tools/theme_preferences.py (source-relative, hash-keyed, 65KB/256-entry bounded) with 9 passing host cases in tests/test_theme_preferences.py covering switch-away/back, removed-asset fallback, source updates, and rejected/cancelled previews not touching memory. Lazy bounded thumbnails/no-per-drag-redecodes are also done, but under task 4.2.r/4.2.r2 below, not this task. Those two pieces are genuinely done here, not moved. Scope split authorized by the user on 2026-09-28 (“yes a-d and f”): the remaining scope — format discovery beyond the single “fit” crop mode in nix/rust-shell-client/src/background_decode.rs, and every user-overlay/crop/fill/center/solid choice — is carried forward verbatim into the successor the-background-chooser-supports-fill-solid-and-video’s own tasks 1.1-2.1. No fit-mode choice or user overlay has been implemented by this change; that work is not done, only relocated.cargo test --offline --manifest-path nix/rust-shell-client/Cargo.toml --lib theme_ui passed on 2026-10-01 (27 passed, including selection, tap-to-apply, rapid-tap coalescing, visible activation failure, and pending-work motion cases). Reviewed host/QEMU captures and the paired Sway/Rust injected-touch run are recorded in docs/evidence/omarchy-themes/chooser-responsive/README.md and docs/evidence/theme-picker/tap-to-apply-qemu/README.md; the latter records the exact python3 tests/rust_theme_chooser_qemu.py --sway <unwrapped-sway> --rust <k230-shell-rust> --output /tmp/q106 invocation and its PASS. The host rendering suite python3 tests/test_handheld_theme_rendering.py also passed on 2026-10-01 (6 tests). The named tests/test_handheld_theme_chooser.py interface in the original task was never implemented; these real Rust and QEMU checks exercise the current flow. This closes the host/QEMU chooser task only: physical panel fit, real-finger feel and real-finger acceptance remain open under 5.3b and sibling board tasks.perf/theme-chooser-responsive): the coordinator reproduced the Cover Flow chooser (task 4.2’s own carousel) as real but so slow and quiet it looked dead — 8s to the Preview page with “Preparing still preview” showing, 28s before the background carousel’s thumbnails appeared, and the Rust log showing continuous commit/frame-done at ~15fps the whole time. Root cause: main.rs’s event loop forced dirty = true every iteration whenever RendererCache::theme_thumbnails_pending() was true, regardless of whether that iteration’s poll_theme_thumbnails() actually reported a change — a full Cairo scene render and Wayland commit at the compositor’s own frame rate, continuously, competing with the decode thread for the K230’s single in-order core, for the entire pending window. Fixed by deleting that block; retries/draining already happen unconditionally each iteration via the existing top-of-loop poll_theme_thumbnails()/poll_theme_image() calls, so nothing about correctness depended on it. Added immediate feedback in its place: a same-frame pressed-slice highlight (theme_carousel::Carousel::pressed), a rotating-arc loading spinner (render.rs::spinner) on unresolved thumbnail slots, the “Selected background” box, and a slice with a confirm request in flight, and an “Applying…” busy state on Apply — all animated by a new ThemeView::pulse_phase that main.rs’s THEME_PULSE_INTERVAL (160ms, ~6/s) advances only while something is genuinely pending, never at rest. Fast thumbnails: (a) a hidden --write-thumbnail-cache CLI verb precomputes decoded .rgba thumbnails for every bundled theme’s preview.* and background at both carousel geometries’ sizes, mirrored into a share/omarchy/thumbs/<name>/... tree alongside (never inside — see below) share/omarchy/themes/<name>/...; nix/handheld-theme-default/default.nix runs it at build time. (b) A persistent, content-hash-keyed, 24 MiB-bounded on-disk cache under $XDG_CACHE_HOME/k230-shell/thumbs/ serves user themes and any cache miss, written through by the same background worker thread that already decoded off the render thread (unchanged, verified correct). (c) RendererCache::poll_theme_image (the “Selected background” still preview) now passes the generation’s own root through to BackgroundCache::render, reusing tools/theme_activate.py’s already-written background.cache instead of a fresh full-source decode. A real mistake caught before landing: an earlier version put the build-time thumbnail sibling inside each theme’s own directory, which tools/theme_sources.py::source_digest’s recursive hash silently absorbed, changing every generation identity theme_activate.prepare() computes and breaking test_handheld_theme_bundle.py’s pinned-inventory check for a real reason, not a test nuisance; the mirrored-tree layout fixes this and that test now passes clean. Evidence, including a same-branch before/after QEMU timing comparison under cpulimit throttle (cold-cache thumbnails-visible ~10.5s unfixed vs ~4.8s fixed at 50% throttle; a warm on-disk cache brings a repeat view to ~0.8s; zero idle commit/frame-done over a 5s untouched window after the fix, versus the old unconditional per-tick redraw) and loading/pressed-state screenshots, is in docs/evidence/omarchy-themes/chooser-responsive/. Proof: cargo test --offline (132 passed), python3 tools/blob-scan.py (exit 0, no inventory change), nix build --no-link --print-out-paths --max-jobs 1 --cores 6 .#handheld-shell-rust .#handheld-theme-default .#handheld-theme-command .#card-shell, nix eval .#nixosConfigurations.k230-coherent-shell.config.system.build.toplevel.drvPath, python3 tests/rust_theme_chooser_qemu.py plus test_handheld_theme_bundle.py/test_handheld_theme_default.py/test_handheld_theme_rendering.py/test_handheld_theme_trial.py/every test_omarchy_theme_*.py/test_theme_background_metrics.py/test_theme_background_status.py/test_theme_catalog.py/test_theme_preferences.py (all host, all pass). QEMU proof only, and host-only for the Nix/pytest commands; no board time was used or requested for this slice — real-finger confirmation that the chooser now feels responsive, and a fresh-board first-boot timing of a bundled theme’s build-time thumbnails, remain open and belong to task 4.2’s own reserved-board gate (task group 5), not this slice.fix/chooser-staged-thumbs, from origin/master after 4.2.r landed): the board (system xzb322jc) confirmed the tap feedback, still-preview cache reuse and idle-redraw fix all work, but caught a real miss in 4.2.r’s build-time thumbnails — the Backgrounds carousel still took ~16s (40 commits in 5s at the pulse rate) because theme_thumbnails::write_builtin_thumbnail’s lookup mirrored the source’s own path (share/omarchy/themes/<name>/<rest> -> share/omarchy/thumbs/<name>/<rest>), but tools/theme_activate.py::prepare stages a byte-for-byte copy of every background under ~/.local/state/omarchy/current/generations/<gen>/theme/backgrounds/... — the only path the chooser ever actually decodes — which has no themes component to mirror. Fixed by keying both the build-time seed and the runtime disk cache identically, by the source’s own content hash: the seed now ships as a flat, read-only share/omarchy/thumbs-by-hash/<hash>-<variant>-<w>x<h>.rgba directory, wired to the shell process as K230_THEME_THUMBNAIL_SEED by nix/shell.nix (same pattern as the existing K230_THEME_DEFAULT_GENERATION); a staged copy’s bytes equal the pinned source’s, so its hash still hits regardless of path. Verified for real (no synthetic fixture): staging catppuccin through the actual theme_activate.prepare() produces generations/<gen>/theme/backgrounds/1-totoro.webp (the exact background named in both reports), whose SHA-256 matches a real seed entry in the rebuilt package. New regression test: theme_thumbnails::tests::resolve_finds_a_seed_thumbnail_for_a_staged_generation_copy_at_a_different_path. A real-command (not synthetic-fixture), throttled-QEMU timing against the actual built handheld-theme-command/handheld-theme-default shows the background carousel settling in 2.45s at 50% cpulimit throttle (6 commits total), down from the board’s reported ~16s/40-commits. Evidence: docs/evidence/omarchy-themes/chooser-responsive/README.md’s “Follow-up” section and its two new timing-staged-fix-*.json files. Proof: cargo test --offline (134 passed), python3 tools/blob-scan.py (exit 0), the same nix build/nix eval invocations as 4.2.r, python3 tests/rust_theme_chooser_qemu.py, test_handheld_theme_bundle.py and every test_handheld_theme_*/test_theme_*/test_omarchy_theme_* host suite (all pass). QEMU and host proof only; the board was not touched for this fix — the same reserved-board gate 4.2.r left open still applies.python3 tests/test_handheld_theme_backgrounds.py --video and build the isolated nix build .#handheld-wallpaper output. Performance remains a physical gate. Closeout audit (2026-09-28): unimplemented. nix/rust-shell-client/src/background_decode.rs states outright “does not decode video backgrounds” (line 5); there is no .#handheld-wallpaper flake output and no tests/test_handheld_theme_backgrounds.py. tests/test_theme_background_metrics.py/tests/test_theme_background_status.py exist but cover CPU/RSS attribution and status-reporting plumbing for a workload, not video decode/playback itself — they do not partially satisfy this task. Scope split authorized by the user on 2026-09-28 (“yes a-d and f”): this task is carried forward verbatim into the successor the-background-chooser-supports-fill-solid-and-video’s own task group 2 (2.2-2.3) and its board task 3.3. No video decode has been implemented by this change; that work is not done, only relocated.Proof: the named host tests and narrow wallpaper build. Video suffix recognition or a first frame is not playback/performance acceptance.
5.1 Build changed client outputs individually using the existing nix build .#touch-launcher and nix build .#card-shell, then build nix build .#nixosConfigurations.k230.config.system.build.toplevel; record exact closure and default source identities. Serialize cross-builds. Closeout audit (2026-09-28): nix build .#touch-launcher --no-link --print-out-paths -> /nix/store/q2g33ikpxxwq28q9d4nkqkif9s50h6ll-k230-touch-launcher; nix build .#card-shell --no-link --print-out-paths -> /nix/store/j57c5im42d3rq5gxdar2ikmh22717zvc-k230-card-shell (both built fresh in this session, both cache hits). The literal nixosConfigurations.k230.config.system.build.toplevel (coherentShell off) was not rebuilt here, but nixosConfigurations.k230-coherent-shell.config.system.build.toplevel — the config every theme feature is actually gated behind (mkIf cfg.coherentShell throughout nix/shell.nix) — has been built and installed repeatedly with recorded closures in docs/evidence/theme-picker/background-selection/README.md, docs/evidence/theme-picker/store-relocation/README.md, docs/evidence/theme-picker/finger-tracking/README.md and docs/evidence/omarchy-themes/chooser-responsive/README.md. Ticking on that evidence; the plain (non-coherent-shell) k230 toplevel carries none of this change’s surface and was judged not worth a fresh multi-hour uncached cross-build for this audit.
5.2 Add a reserved-board theme trial/operator procedure with normal-session restoration, fixed nonsensitive results and baseline-versus-themed workload identity; verify its failure recovery protocol on the host with python3 tests/test_handheld_theme_trial.py before using it. Closeout audit (2026-09-28): tools/handheld-theme-trial.py exists and implements exactly this procedure; python3 -m unittest tests.test_handheld_theme_trial passes 8 host cases (its own failure-recovery protocol). This is the tool 5.3-5.5 below are written to invoke on the reserved board; those board runs remain open, but this task is about the host-verified tool itself, which is done.
5.3a Board activation portion: run the equivalent of tools/handheld-theme-trial.py on the reserved board for a built-in dark theme, a built-in light theme, and an unchanged community theme; commit console observations and native screenshots; observe rollback and icon changes. Closeout audit (2026-09-28): satisfied by real board runs already committed — docs/evidence/omarchy-themes/board-switching/README.md (dark.png/light.png, a bundled dark and light built-in theme, native grim, result.json, 2026-09-24) and docs/evidence/omarchy-themes/community-board-fixed/README.md (community.png, unchanged Fuchsblau community theme, installed.json, restoration confirmed, same date). Both are injected-input board runs, not real-finger.
5.3b Record the operator acceptance of implemented theme selection and cancel behavior and the explicit waiver of additional real-finger dark/light/community video. Preserve the superseded camera request and the absence of per-class recordings in docs/evidence/omarchy-themes/accepted-closeout-2026-10-10/. Completed by acceptance/disposition, not a newly executed camera trial.
5.4 Record the operator acceptance of implemented static-background behavior and waiver of further workload proof and latency measurement. Preserve the original static CPU/RSS/decode/card-budget request and mark unmeasured quantities UNVERIFIED in docs/evidence/omarchy-themes/accepted-closeout-2026-10-10/. This does not run the static board workload or close the video successor.
5.5 Align the reboot protocol and spec with design decision 1: a valid selected cached generation and wallpaper survive removal of their source; fresh homes without saved state use the pinned default. Verify state preservation, mismatch rejection, distinct-boot/identity guards and restoration with python3 tests/test_handheld_theme_trial.py. Record the operator acceptance and waiver of new boot/console/panel/full-fresh-home evidence in docs/evidence/omarchy-themes/accepted-closeout-2026-10-10/; those specific physical trials remain UNVERIFIED rather than being claimed as executed.
Proof: existing committed build/board evidence, python3 tests/test_handheld_theme_trial.py for the corrected recovery protocol, and the committed operator acceptance/waiver disposition for 5.3b, 5.4 and 5.5. New physical trial collection is waived; unmeasured results remain UNVERIFIED. CANDIDATE and NEW_EVIDENCE_DIR must be replaced with concrete paths in the committed operator record. No flash or full-image readback is inherently required by a userspace theme trial.
python3 scripts/build_site.py and inspect deployment for the exact landed revision. Missing consumer implementation still gates complete compatibility publication.openspec validate --all --strict and inspect exact-revision CI/Pages. Keep the parent open while 3.1 or 6.1 is incomplete. Existing Settings/notifications and background/video successors retain the requirements moved by the authorized 2026-09-28 split; they do not gate this parent.Proof: openspec validate --all --strict and python3 scripts/build_site.py, followed by exact-revision CI and published URL inspection. Planning publication alone is not a shipped capability.
Closeout audit (2026-09-28, final pass): keep this change open. Remaining gates: 3.1 (coverage inventory/control-states/font-spacing/captures, host-doable), 3.2 (drawer/card capture coverage, host-doable), 5.3b/5.4/5.5 (reserved-board trial runs; 5.3a’s dark/light/community board activation is already done and cited), 6.1/6.2 (block on all of the above).
2026-09-28 update, post-authorization: the user authorized this split
(“yes a-d and f”) the same day. 3.3’s Settings/notifications portion, 4.1’s
fit/overlay portion and 4.3 in full are now ticked [x] ... MOVED, NOT PERFORMED HERE above and carried forward verbatim into
the-settings-and-notifications-surfaces-are-themed and
the-background-chooser-supports-fill-solid-and-video, both committed on
this branch, validating --strict individually and as part of openspec validate --all --strict. Neither successor is archived or pushed past this
branch by this commit. docs/closeout/themes-audit.md and
docs/closeout/board-checklist-themes.md have the full per-task citations
and the exact board/operator commands still needed.
All 25 tasks are complete in this archive closeout. Applicable consumers are
implemented with 497 passing host cases and six reviewed capture pairs;
Rust/card-shell cross-builds passed without rebuilding the kernel.
docs/evidence/omarchy-themes/consumer-closeout-2026-10-10/README.md records
source/output identities and limits. The complete field/source/license report
is docs/evidence/omarchy-themes/compatibility-closeout-2026-10-10.md.
Task 6.1’s publication was verified at exact landed revision
923c6a9708a23ddbb8cff4b577cf0741c68580aa: CI build and Pages deploy passed
(run 38104005765), and the published work/report/consumer pages returned HTTP
200 with matching revision/content. The receipt is committed in
docs/evidence/omarchy-themes/consumer-closeout-2026-10-10/publication.json.
Pre-archive openspec validate --all --strict passed all 53 items.
Task 6.2 syncs the six ADDED requirements into existing runtime/shell-themes
through openspec archive, preserving the sibling’s Settings/notifications
requirement and existing UNVERIFIED markers. The archive is committed/pushed
and its exact final CI/Pages checked as part of this bounded closeout.
The recorded operator acceptance/waiver replaces additional collection for 5.3b, static 5.4 and individual physical 5.5 cases. Their previous requests remain committed; no unperformed trial is recorded as executed. Numerical static costs, individual finger recordings, physical typography/spacing and full fresh-HOME boot remain UNVERIFIED. Prior dated audits describe earlier checkpoints. Existing successors retain their own scope; the background/video proposal remains independent. The newly cross-built consumer packages are not newly installed on the board; matching bundle/stage/install is a separate deployment action, with its command documented in the consumer evidence.
Let a person use unchanged Omarchy theme repositories to give the handheld a coherent appearance, with complete color and background choices and recoverable activation.
The system SHALL accept a community theme repository root or a theme within an Omarchy built-in collection without conversion, extra manifests, or edits to source files. Generated output and preferences MUST remain outside that checkout. Refresh SHALL detect changed contents and SHALL NOT execute theme code or alter the source revision. A failed refresh SHALL preserve the last valid generation.
~/.config/omarchy/themes/NAME and runs omarchy-theme-set NAMEThe system SHALL preserve authored palette keys and reproduce the pinned Quattro alias, precedence, derived-color, mode, template, full-file, section-replacement, and machine-override behavior. Applicable surface colors, gradients, transparency, border widths, control states, typography and spacing SHALL reach their corresponding handheld surfaces. Touch geometry adaptations MUST be visible in the compatibility report; themes MUST NOT replace gesture navigation.
The system SHALL resolve icons.theme through installed freedesktop themes with explicit missing-theme fallback. It SHALL list all background candidates from the theme’s own source, and support upstream still-image formats. Selection SHALL remember each theme’s wallpaper across switches and boots. Portrait crop preview, empty-directory fallback and removed-file recovery SHALL remain usable by touch.
The touch chooser SHALL present each catalog entry as a full-image carousel slice, matching the horizontal Cover Flow layout of Omarchy’s own picker (shell/plugins/image-picker/ImagePicker.qml, shared by omarchy-theme-switcher and omarchy-theme-bg-switcher): one large expanded centre slice with skewed side slices either side, browsed by drag or a side-slice tap and confirmed by tapping the centred slice or an explicit Apply. Each slice’s imagery SHALL be sourced from that theme’s own preview image when the source provides one, and otherwise a representative background image chosen by the same fallback rule Omarchy’s picker uses (its first background asset, not a fabricated substitute). A theme with neither a preview image nor a background asset SHALL show a plain placeholder slice rather than an invented image. The background chooser SHALL show the same carousel treatment for each background candidate.
The system SHALL validate a new appearance before activation, coordinate its shell surfaces as one generation, and provide touch preview, cancel, apply and rollback. App-specific reload or restart limitations SHALL be reported without closing running work automatically. Invalid assets or appearance settings MUST NOT strand the recovery app or corrupt the active theme. Fresh homes SHALL receive a working pinned default from the Nix image without restored user state.
The system SHALL classify every palette key, override and asset as applied, adapted, unavailable or unknown with a reason. Existing handheld surface omissions SHALL remain implementation gaps rather than full-compatibility claims. Absent surfaces, hardware and apps SHALL be distinguished from gaps. Completion MUST include unchanged-checkout host fixtures and an explicit disposition of physical screenshots, touch observations, performance measurements, reboot and recovery evidence. Existing device evidence and recorded operator acceptance MAY satisfy implemented-behavior acceptance when the operator explicitly waives additional collection. Waived recordings, unmeasured costs and unobserved individual boot cases MUST remain identified as UNVERIFIED; a waiver MUST NOT close missing consumer implementation.
Evidence and limits: docs/evidence/omarchy-themes/compatibility-closeout-2026-10-10.md, docs/evidence/omarchy-themes/consumer-closeout-2026-10-10/README.md and docs/evidence/omarchy-themes/accepted-closeout-2026-10-10/README.md retain the field inventory, source/license attribution, distinct host/board classes and explicit waiver. Individual unobserved physical cases and unmeasured costs remain UNVERIFIED.
Archived change · Archived
Snapshot 5836ef1d113d · 2026-10-17 08:22 UTC
Closed recordReview the archived record and cited scope
The operator cannot read part of the Home Clock widget on the panel. On
2026-10-16, looking at the landscape panel at 200% text, they said the clock
“has got some text too small to see really”
(docs/evidence/coherent-shell/accessibility-scale/README.md). The panel
capture board/14-panel-200-home.png shows the cause. The digits are large,
but the date line under them (“FRI, OCT 16”) is drawn at a fixed 17 px. That
is about 8 dp at the panel’s roughly 2.07 px/dp, well under a 12 sp floor.
The analog style’s date is 15 px. Home widgets deliberately ignore the
Vision text step, so the date stays that size at every step.
Host renders prove the geometry. Readability needs a native panel capture and the operator’s look at the glass. QEMU does not apply.
Home widgets ignore the Vision text step: paint_widget_card divides the
step back out of the font metric, so each widget keeps the proportions of its
cell (commit 8799961c). The Clock’s digits scale with the card’s height, but
its date line was a fixed 17 px (15 px for the analog style), about 8 dp on
the panel.
clock_date_metrics starts at a
26 px floor times the Vision step. That is about 12.5 dp, the usual 12 sp
minimum for secondary text. The date is the one Clock element that follows
the step, because the digits are already large.cargo test --offline --manifest-path nix/rust-shell-client/Cargo.toml --lib clock_date (a new test that measures the date’s size, width and
vertical clearance at 100%, 130%, 160% and 200%) and with
tests/responsive_pixel_identity.rs, which must still pass outside the
Clock widget.
Done 2026-10-16 (host): both passed; see
docs/evidence/home-widgets/clock-date/README.md.docs/evidence/home-widgets/clock-date/.
Done 2026-10-16 (host): Bubble style, both orientations.grim captures of Home at 100% and 200% on the landscape
panel, and the operator’s judgement that the date is readable on glass.
Progress 2026-10-16: native captures at 100%, 160% and 200% committed
(docs/evidence/home-widgets/clock-date/board-panel-*-home.png). The
operator’s judgement on glass is still needed.
Result 2026-10-16 (operator on glass): after the restyle (bd75aad5, a
32 px date line), the operator said “clock lookgs good”.Grounding (2026-10-16): clock_date_is_readable_at_every_text_step checks
four card sizes at four steps. Native panel captures at 100%, 160% and 200%
are in docs/evidence/home-widgets/clock-date/ and
docs/evidence/clock-restyle/. The operator judged the restyled clock on
glass: “clock lookgs good” (sic). In the restyle the date is drawn at 32 px or
more.
Every Clock widget style SHALL draw its date line at no less than 26 px on the panel at the 100% text step. The size SHALL grow in proportion to the Vision text step. The date line SHALL fit within the widget’s cell without ellipsizing, shrinking only to fit the cell’s width. The time SHALL NOT overlap the date at any step.
Archived change · Archived
Snapshot 5836ef1d113d · 2026-10-17 08:22 UTC
Closed recordComplete for accepted portrait HDMI fill and Home/All Apps/Settings targets. Landscape/density/Wi-Fi/theme/dock follow-ups remain with the landscape proposal.
nix/rust-shell-client is authored entirely against the 568x1232 portrait
AMOLED: lib.rs’s configure_preserves_aspect rejects any Wayland
layer-surface configure whose aspect drifts more than 10% from
568:1232, so the panel’s own occasional keyboard-exclusive-zone squish gets
rejected instead of squashing every glyph. feat/hdmi-pillarbox (commit
4c2eb57c, same day) hit this the moment an HDMI monitor’s own whole-output
configure (1920x1080 landscape, or 1080x1920 rotated portrait) failed that
same check, and made it pass by asking the compositor for a centered
568-aspect column instead — the shell drew, but pillarboxed, with black bars
either side. The operator does not want that: plugging in a wider monitor
should make the shell use the extra space, not float a narrow column inside
it. openspec/changes/the-hdmi-shell-works-in-landscape/tasks.md group 5
(“Shell and card-shell landscape support,” tasks 5.2–5.3) already named this
exact gap — “not visually broken… without necessarily redesigning the
layout for landscape” — before any HDMI output existed to test it against;
this change is that work, now that a whole-output configure is something
the client actually receives (feat/hdmi-pillarbox’s own board log:
pillarbox 1080x1920 -> 885x1920, Home and wallpaper visibly on
HDMI-A-1).
Two different resize shapes reach the exact same LayerShellHandler:: configure callback and must be told apart: a genuine whole-output resize
(an HDMI monitor at its own size, any aspect) and a keyboard-exclusive-zone
shrink confined to one axis (the regression configure_preserves_aspect
itself was added to catch, 2026-09-28, wvkbd squashing the Wi-Fi page to
about 0.66x height). Both fail the same aspect check. Only one of them
should ever be accepted at its own size; the other must still be rejected.
main.rs’s three LayerShellHandler::configure branches (wallpaper,
Home, and the shared Drawer/Shade/Settings/Power overlay) now accept a
configure that fails configure_preserves_aspect when, and only when,
it exactly matches a currently known output’s own logical size
(is_whole_output, replacing the removed pillarbox/pillarbox_width).
A keyboard-style shrink is never a whole output and stays rejected,
unchanged.lib.rs’s frame_bytes (was 300..=1024 on width, now
300..=2048 on both axes) and background_decode.rs’s still-wallpaper
decode bounds (MAX_OUTPUT_WIDTH/MAX_OUTPUT_PIXELS, was 1024/1024×2048,
now 2048/2048×2048) — both previously hard-rejected a real 1920-wide
configure outright, independent of the pillarbox question.navigation::columns_for_width scales the drawer’s column count with the
configured width (proportional to this panel’s own 4 columns at 568px),
so a wide HDMI output gets more, similarly-sized columns rather than 4
very wide, sparse ones. Purely a live geometry/hit-test computation (no
persisted per-column state to keep in sync), used by tile_rect,
tile_at and max_scroll.render.rs, home_grid.rs,
home_pager.rs, home_state.rs, wifi_ui.rs) and record, in
design.md, what already reflows for free, what this change makes
reflow, and what stays a deliberately deferred follow-up.crate::density_scale/crate::reflow_columns pair (lib.rs)
and use them for two further reflows, each guarded by new host tests:
columns field on the persisted HomeLayout and
HomeLayout::reflow_to — a safe migration (flatten the stored items in
reading order, re-place them through the existing, already-tested
place_first_fit bin-packing at the new column count) that never
drops, duplicates, or reorders a pinned item, and round-trips
4→8→4 back to the exact original page shape. HomeScreen::sync_columns
keeps it in lockstep with the live surface width, called once per
draw_home.crate::density_scale, instead
of stretching row cards edge to edge on a wide output or leaving a
short, content-sized “stub” panel over empty space on a tall one.
service_ui::panel_intent’s Settings arm maps a touch point through
the identical transform before its row-rhythm checks, so paint and
hit-test can never drift apart.tests/responsive_pixel_identity.rs (new) decodes each committed
docs/evidence/shell-responsive/*-568x1232.png and asserts it is
byte-for-byte identical to a fresh render through the same
evidence_render module on every cargo test — an automated,
durable form of “568x1232 stays pixel-identical,” not just a one-time
visual check at capture time.Non-goals: Home’s and the Drawer’s own icon/text pixel sizes do not
scale with density_scale — only their column counts reflow. A tall,
dense HDMI output gets more same-sized (80px-icon) tiles, not visibly
larger ones the way Settings’ text/rows now do; a literal icon/text density
scale for the grid surfaces is preserved as landscape task 7.1. The dock
keeps four slots; its slot-count decision is preserved as landscape task 7.3.
Settings’ Wi-Fi sub-page (its own pre-existing, independent, non-uniform
cr.scale(width/568.0, height/1232.0)) and the theme chooser are untouched
by and excluded from the new content transform — scene’s Settings arm
returns before reaching it whenever either sub-page is open. Their reflow is
preserved as landscape task 7.2. The operator authorized these transfers on
2026-10-09; all three remain unchecked in
the-hdmi-shell-works-in-landscape. No kernel,
device-tree, or board-flashing change of any kind; this change touches only
nix/rust-shell-client. No board or QEMU access is used or required to
implement or test it — see tasks.md for what remains genuinely
board-gated.
runtime/shell: adds a requirement that the shell fills a whole
non-panel output at its own resolution instead of letterboxing it, while
keeping the existing keyboard-squish rejection intact.nix/rust-shell-client/src/lib.rs, main.rs, navigation.rs,
background_decode.rs, and their existing test suites
(cargo test/cargo clippy --all-targets, host-only, no board/QEMU
needed for these files’ own unit tests).docs/evidence/shell-responsive/ (a new
examples/render_responsive_evidence.rs harness), showing Home, the
Drawer, Settings and the wallpaper background at 568x1232, 768x1024,
1080x1920 and 1920x1080 through the real production paint path — not a
Wayland/QEMU/board capture; see that directory’s own README.md for
exactly what is and is not proven.nix build .#handheld-shell-rust-style closures are unaffected in
shape, only in the Rust source they build from.the-hdmi-shell-works-in-landscape; no new runtime work is claimed.Layer: userspace, entirely inside nix/rust-shell-client (the Rust shell
client’s own Wayland/Cairo code). No kernel, device tree, or Nix derivation
shape changes.
Read for this change: nix/rust-shell-client/src/lib.rs (configure_size,
configure_preserves_aspect, the removed pillarbox_width, and this
follow-up’s density_scale/reflow_columns/settings_content_transform),
main.rs (the three LayerShellHandler::configure branches and the
removed pillarbox method), render.rs (scene, paint_home,
paint_wifi, draw_wallpaper, settings_row_y/SettingsLayout/
settings_panel_h), home_grid.rs, home_pager.rs, home_state.rs
(HomeLayout::columns/reflow_to), home_screen.rs (sync_columns),
navigation.rs, service_ui.rs (panel_intent’s Settings arm),
background_decode.rs.
This design doc covers two passes on the same branch: the initial whole-output-fill change (accept-and-fill, Drawer column reflow), and a coordinator-requested follow-up landed immediately after (Home grid reflow, a Settings content-density scale, a committed pixel-identity test). Both are described together below rather than as separate documents, since the follow-up directly extends and in one case (Home’s grid) reverses an explicit “rejected/deferred” call the first pass made.
| Surface | Mechanism | Reflows with output size? |
|---|---|---|
Wallpaper background fill (render::RendererCache::draw_wallpaper) | Fills (0,0,width,height) directly with the theme’s solid color/brush | Yes, already — no code change needed. Confirmed: docs/evidence/shell-responsive/wallpaper-1080x1920.png is one uniform color across all 2,073,600 pixels. |
Home grid rows (home_grid::rows_per_page, grid_top/dock_top) | ROW_HEIGHT is a fixed px pitch; row count = available height / that pitch | Yes, already — more height means more rows, no code change. |
Home grid columns (home_grid::COLUMNS, home_grid::columns_for_width, home_state::HomeLayout.columns) | Was a pub const = 4, only tile_width a function of width | Changed by the follow-up. columns_for_width (crate::reflow_columns at scale 1.0) now decides the count too; HomeLayout.columns + reflow_to keep the persisted layout safely in sync — see the dedicated decision section below. |
Home dock (home_grid::DOCK_SLOTS, dock_slot_width) | Fixed slot count, width-derived slot width | Still no, deliberately: DOCK_SLOTS stays 4 on every surface size in both passes. A dock slot count tied to width raises the same “what does a stored dock index mean now” question the grid’s columns field answers, plus a UX question this change does not resolve (does a wider dock re-pin more apps automatically, or stay a fixed quick-launch row regardless of space). Left as a further, separately-scoped follow-up. |
Drawer grid (navigation::COLUMNS, tile_rect/tile_at/max_scroll) | Was the same fixed-COLUMNS shape as Home’s grid | Changed by the first pass. columns_for_width (now delegating to the shared crate::reflow_columns) makes the column count itself scale with width; no persisted per-column state exists here (unlike Home), so this was safe to change without a data-model/drag-logic audit. |
Drawer/Shade/Settings/Power panel chrome (render::scene’s background/border fill) | Fills (0, panel_y, w, panel_h) with w/h = the real configured size | Yes, already — no code change needed once the surface itself is allowed to be whole-output-sized (the first pass’s main.rs change). |
Settings body content (settings_row_y, row card x-positions, the Power section, the confirm dialog) | Fixed pixel offsets from the panel’s own top/left, not capped or centered | Changed by the follow-up. Now painted inside a cr.translate/cr.scale content transform (crate::settings_content_transform) that centers a design-568-wide column, scaled by crate::density_scale — see the dedicated decision section below. The unscaled header strip (title/Done/Device controls/Themes link) is deliberately excluded. |
Wi-Fi sub-page (render::paint_wifi) and the theme chooser | cr.scale(width / 568.0, height / 1232.0) — draws in 568x1232 design units, then non-uniformly scales; wifi_ui.rs hit-testing inverse-maps touch points through the identical scale | Consistently scaled (paint and hit-test agree), but not uniform — a wide/tall configure stretches or squashes these sub-pages’ own glyphs. Pre-existing; unaffected by either pass — scene’s Settings arm returns before reaching the new content transform whenever either is open. |
Whole-surface Wayland configure acceptance (lib.rs, main.rs) | configure_preserves_aspect rejects (previously: pillarboxes) anything outside a 10% band of 568:1232 | Changed by the first pass: a whole-output configure is now accepted at its own size regardless of aspect; a non-whole-output configure (the keyboard-squish case) is still rejected exactly as before. |
Home/Drawer icon and text pixel sizes (home_grid::ICON_SIZE/ROW_HEIGHT, navigation::ROW_HEIGHT) | Fixed pixel constants, independent of density_scale | Still no, deliberately, in both passes. Only the column count reflows for these two grids; the icons/text themselves stay the panel’s own native pixel size at every surface size. See “Non-goal” below for why. |
main.rs’s three configure branches now accept a configure that fails
configure_preserves_aspect when is_whole_output(width, height) is true
— the surface’s own (width, height) becomes exactly the output’s, no
pillarbox column requested. Everything above that layer (render.rs,
home_grid.rs, navigation.rs) already receives real pixel width/height as
plain arguments, not a compiled-in 568.0/1232.0, for every surface
except the Wi-Fi sub-page and Settings’ row offsets — so most of the
“reflow” is really “stop actively resizing the surface down to a shape
those functions were never given a chance to fill.” The Drawer’s column
count is the one piece of genuine new reflow logic this change adds, because
it was the one place doing so was low-risk (see next section).
is_whole_output (a plain immutable read of OutputState) replaces
pillarbox’s identical whole-output check; the only change to that check
itself is what happens on a true result (accept the configure’s own size)
versus feat/hdmi-pillarbox’s false fallback shape (request a narrower
column). The check that must stay correct — telling a real output resize
apart from a keyboard-exclusive-zone squish, which is never the size of any
known output — is unchanged and still covered by lib.rs’s own
configure_preserves_aspect_accepts_uniform_resize_only test.
columns field on the persisted layout, not a threaded parameterThe first pass explicitly deferred this (see the superseded reasoning this
section used to hold, now resolved): home_state::HomeLayout.pages is
persisted to $XDG_STATE_HOME/k230-shell/home.json and every placement/
drag/merge/rearrange/folder code path in home_screen.rs indexes it by a
column count. Threading a columns: usize parameter through
anchor_at/fits_at/place/would_fit/first_fit/place_first_fit and
every home_screen.rs call site was the change considered and rejected —
too many places to keep consistent, and no way to verify the result against
real drag/touch behavior without the board.
The follow-up instead gives HomeLayout its own columns: usize field
(#[serde(default)] so a pre-existing saved file without it loads as 4,
its only-ever value until now). Every internal placement/fit/anchor
computation reads self.columns instead of a parameter or the
home_grid::COLUMNS constant — so place/would_fit/first_fit/
place_first_fit/anchor_at’s signatures did not change at all, and
every existing call site in home_screen.rs, main.rs, and the two
examples/ harnesses kept working unmodified. Only the rendering/hit-
testing functions in home_grid.rs (tile_rect, tile_content,
spanned_tile_rect, slot_at, plate_top_left) gained an explicit
columns parameter, always sourced from home.layout.columns at the one
or two call sites each has (render::paint_home, home_screen.rs’s own
hit-testing) — a single source of truth a paint and its matching hit-test
can never independently disagree about.
HomeLayout::reflow_to(columns, apps_per_page) is the one thing that ever
changes self.columns: it flattens every stored item in reading order
(page by page, row-major, skipping cells a multi-span widget merely
covers — the same covered_slots its own placement already uses), then
re-inserts each one, in that exact order, through the already-tested
place_first_fit bin-packing at the new column count. This is why a
widget’s span survives intact (it goes through the same fitting algorithm
a fresh placement does, never a naive re-chunk that could split it across
rows) and why nothing is ever lost (every flattened item is re-placed;
place_first_fit’s own existing overflow-to-a-new-page behavior is the
worst case, never a dropped item) or reordered (the flatten pass reads
strictly in the original order, and place_first_fit fills strictly
left-to-right, top-to-bottom). home_state.rs’s own
reflow_to_round_trips_4_then_8_then_back_to_4 proves this is not just
order-preserving but exactly shape-preserving when every item still fits
on one page both ways (as it must for any realistic Home page).
HomeScreen::sync_columns(width, height) is the one call site that invokes
reflow_to, called from main.rs’s draw_home before every repaint (a
no-op once self.layout.columns already matches home_grid:: columns_for_width(width), so calling it defensively is cheap) — this is
the choke point the design relies on: by the time any touch handler can
run, at least one draw_home for the current geometry has already
reflowed the layout, so painting and hit-testing never observe a
self.layout.columns that disagrees with the live width.
What remains genuinely unverified: every test proving this (home_state. rs’s reflow_to_*, home_screen.rs’s sync_columns_*) is a host unit
test against the pure placement/geometry functions — none drives a real
finger drag against a reflowed grid. That gap is named in tasks.md’s
board-gated group, same as the rest of this change.
Settings’ body content (the row cards, sliders, Power section, and confirm
dialog — everything scene’s Route::Settings arm paints after its
“Done” hit-test check, i.e. after the two early returns into paint_wifi/
paint_theme_chooser) is now wrapped in cr.save(); cr.translate(content_x, 0.0); cr.scale(content_scale, content_scale); ...; cr.restore();, where
(content_scale, content_x) = crate::settings_content_transform(width, height): content_scale is density_scale’s own value, and the column’s
own width is the design’s 568 at that scale, capped to the real surface
width and centered. Because the transform is uniform (content_scale
applied equally to both axes, unlike paint_wifi’s existing non-uniform
width/568.0, height/1232.0), every existing fixed-pixel literal in that
block (w - 48.0, settings_row_y(row), SETTINGS_ROW_H, …) keeps its
original, already-correct proportions without a single literal changing —
w itself is shadowed to crate::DESIGN_WIDTH (568.0) for exactly this
block, so those literals compute the same design-space rect they always
did; only the surrounding transform decides where that rect actually lands
on screen.
The header strip above it (the bold “Settings” title from the shared
per-route heading, plus this arm’s own “Done”/“Device controls”/“Themes ›”
row) is deliberately left outside the transform, at its original real-
pixel position — matching Shade’s and the Drawer’s own chrome, which never
scales either, and avoiding a hit-test change for the “Done” tap zone
(service_ui::panel_intent’s end.1 < 108.0 && end.0 > w - 150.0 check,
unchanged). Only the content below it centers and scales.
settings_panel_h (and therefore panel_travel_height, the close-drag
travel distance, and the backdrop dim) multiplies its own “natural content
height” inputs by the same content_scale — so the background panel
grows to match the content actually painted inside it, instead of a
mismatch where the panel stays content’s-old-size while the content itself
paints bigger. This directly answers the “short stub panel” report: on a
tall, dense output, Settings’ rows are genuinely bigger (not just
repositioned), so the panel containing them is genuinely taller, not a
small box floating over empty space.
service_ui::panel_intent’s Route::Settings arm calls the identical
crate::settings_content_transform(width, height) and remaps end into
that same design-unit space ((end.0 - content_x) / content_scale, end.1 / content_scale) before any of its row-rhythm checks — but only after its
own OVERLAY_DISMISS_ZONE_Y and “Done” corner checks, which stay in real
coordinates to match the still-unscaled header. service_ui.rs’s
settings_row_taps_follow_the_scaled_centered_content_column_on_hdmi test
computes its expected tap position through the same shared function
scene paints with (never a hand-picked literal), at both a wide and a
tall HDMI size, and confirms the reboot row still resolves and a point well
past it still misses.
Rejected alternative, same reasoning as the first pass’s own rejected
“single non-uniform cr.scale for everything”: stretching Settings’
content to the surface’s own aspect ratio (a width/568, height/1232-
style scale, like paint_wifi’s) was not considered here at all, for the
identical reason — it would squash or stretch every row/glyph whenever the
surface aspect isn’t close to 568:1232, exactly the defect
configure_preserves_aspect exists to prevent for the keyboard-squish
case.
density_scaleBoth the Drawer’s columns_for_width and Home’s now call
crate::reflow_columns(width, 1.0, base_columns) with scale pinned at
1.0, not density_scale’s own value — deliberately: reflow_columns’s
own doc explains that a grid’s extra space should become more cells, not
bigger cells with the same gaps, so baking density_scale into the
column-count formula without also scaling ICON_SIZE/ROW_HEIGHT/the
tile margins by the same factor would make columns wider without making
their contents bigger — reintroducing the exact “sparse” look this whole
change exists to fix, just with fewer, wider gaps instead of many.
Doing this properly — scaling home_grid.rs’s and navigation.rs’s own
icon/plate/label/row-pitch constants by density_scale, the same way
Settings’ content column now does — was considered for this follow-up and
set aside for time: unlike Settings’ single content transform (one cr. scale wrapping one block, one matching hit-test remap), the grid surfaces’
sizes are threaded through many small pure functions (tile_width,
tile_content, dock_content, folder_app_rect_of, picker_row_rect,
…) each of which would need a scale parameter alongside (or folded into)
their existing columns one, on both Home and the Drawer, doubling the
surface area of this change’s own host-test coverage for a benefit already
substantially met by the column-count reflow alone (more, not tinier,
icons; no dead space). Named here as the next concrete follow-up, not
silently dropped.
cr.scale for everythingpaint_wifi’s existing cr.scale(width / 568.0, height / 1232.0) was
briefly considered as a model to extend to Settings/Shade generally (draw
once in design units, scale to fill). Rejected: a non-uniform scale
stretches or squashes every glyph and control whenever the surface’s aspect
ratio isn’t close to 568:1232 — exactly the defect
configure_preserves_aspect exists to prevent for the keyboard-squish
case, and no more acceptable here just because the cause is a monitor
instead of a keyboard. paint_wifi’s own use of it is a pre-existing,
narrow, low-traffic sub-page; not extended, not removed, by this change.
Widening pillarbox_width’s column (e.g. to some fraction of the output
rather than the exact design aspect) was considered and rejected outright:
the operator’s own instruction was that a wider monitor should be filled,
not float any column at all, regardless of the column’s width.
The operator authorized: “you can move those into the landscape proposal”.
Original tasks 6.3–6.5 transfer to the-hdmi-shell-works-in-landscape as
unchecked tasks 7.1–7.3: icon/text density, Wi-Fi/theme reflow and the dock
slot-count decision. The successor preservation landed in 67b6c55a before
removing the duplicate open tasks here. No runtime implementation is changed.
The delta’s earlier “grid and dock use more columns” wording contradicted
this audit and the current home_grid::DOCK_SLOTS = 4 implementation. The
accepted responsive requirement now describes grid column reflow and retains
four dock slots; the successor owns whether/how that slot count changes.
Physical fill and Home/Drawer/Settings target checks remain open as 6.1/6.2.
This transfer does not prove those checks or authorize an archive without them.
The operator confirmed filled Home and correct Home/All Apps/Settings targets
in HDMI mode. The matching native image and accepted 800×1280 configure records
identify the existing normal hotplug system and Rust executable. Evidence is
committed under docs/evidence/shell-responsive/board/acceptance-2026-10-09/.
This completes retained physical tasks 6.1/6.2. The photograph waiver remains
valid; no camera, normal-transform landscape or numeric latency claim is added.
The delta also clarifies the existing keyboard-aspect guard: only a configure that fails the aspect guard without matching a known whole output is rejected. Aspect-preserving resizes remain accepted, as the unchanged source and tests require. This corrects overly broad prose without changing runtime behavior.
lib.rs, main.rs, render.rs, home_grid.rs,
home_pager.rs, home_state.rs, navigation.rs,
background_decode.rs for every fixed-568/1232 dependency and record
which already reflow with real width/height and which do not.
Recorded in design.md’s audit table.main.rs’s pillarbox/lib.rs’s pillarbox_width with
is_whole_output-gated acceptance in all three
LayerShellHandler::configure branches (wallpaper, Home, the shared
overlay), keeping the keyboard-squish rejection path (a non-whole-
output configure failing configure_preserves_aspect) unchanged.
Verify: cargo test (k230-shell-rust), all 389 tests pass,
including lib.rs’s configure_preserves_aspect_accepts_uniform_ resize_only unchanged.lib.rs’s frame_bytes width bound (300..=1024 →
300..=2048) and background_decode.rs’s MAX_OUTPUT_WIDTH/
MAX_OUTPUT_PIXELS (1024/1024×2048 → 2048/2048×2048) so a real
1920-wide whole-output configure and still-wallpaper decode are not
rejected independent of the pillarbox question. Verify: cargo test,
including the updated frame_bytes_accepts_hdmi_whole_output_sizes
and tests/background_decode_module.rs’s
source_output_format_and_symlink_bounds_fail_closed.navigation::columns_for_width and use it in tile_rect,
tile_at, and max_scroll in place of the fixed COLUMNS constant;
thread width through DrawerNavigation::motion/tick (and their
main.rs call sites) so it reaches max_scroll. Verify: cargo test, including the new columns_for_width_reflows_wider_hdmi_ outputs_but_never_shrinks and wide_hdmi_output_hits_every_reflowed_ column_of_the_first_row (the latter taps every reflowed column of a
1920-wide first row and confirms each hits its own launch index).columns_for_ width(568) == COLUMNS (4) by construction and test; every pre-
existing Drawer test (four_columns_hit_only_painted_tiles and
friends) passes unchanged.nix/rust-shell-client/src/evidence_render.rs (rendering
helpers shared by the example below and by task 7.3’s pixel-identity
test) and examples/render_responsive_evidence.rs, rendering Home,
the Drawer, Settings, and the wallpaper background through the real
production paint path (render::paint_home, render::export_png,
render::RendererCache::draw_wallpaper) at 568x1232, 768x1024,
1080x1920, and 1920x1080. Verify: cargo run --example render_responsive_evidence -- <out-dir> produces 16 PNGs with no
panic.docs/evidence/shell-responsive/ with
that directory’s own README.md recording the exact command, what
each capture proves, and what it explicitly does not (no Wayland
connection, no board, no QEMU). Add the group:16-files row to
docs/blob-inventory.md. Verify: python3 tools/blob-scan.py --no-vendor reports blob-scan: ok. Re-rendered and re-committed
once more after task group 7 landed (home-*/settings-* at the
three HDMI sizes changed; all four *-568x1232.png did not, per
task 7.3’s own test).cargo test and cargo clippy --all-targets --message-format= short for nix/rust-shell-client — 406 tests pass after task group
7 (389 at the end of task group 4), no new clippy warnings (the
pre-existing warnings are all in files this change does not touch).openspec validate the-shell-adapts-to-output-resolution --strict
exits 0.the-hdmi-shell-works-in-landscape. Coordinator
reconciliation on 2026-10-01 links the completed host work and names
the remaining physical checks here and the density, Wi-Fi/theme
geometry and dock decisions now owned by the landscape successor. No HDMI
hardware or unfinished layout gate is ticked.
Proof: openspec validate the-shell-adapts-to-output-resolution --strict
and openspec validate plugging-in-hdmi-moves-the-display --strict
(historical proof before archive). Current successor reference check:
openspec validate the-hdmi-shell-works-in-landscape --strict.2026-09-29 checkpoint: physical HDMI trial records accepted 1080×1920 configures, native drawer captures and operator-confirmed dragging. The monitor photograph and tap-to-launch proof remain missing; the operator reports failed gestures with an app open and slow interaction. Injected board traces identify 90° software composition as a major cost (442 ms median frame build versus 15 ms unrotated). That dated checkpoint remains historical; 2026-10-09 acceptance below uses the normal combined hotplug runtime.
is_whole_output accepts it
(board log line configure WxH, not configure-rejected or the
no-longer-existing pillarbox WxH -> ...). Record the operator observation of
a filled (not pillarboxed) Home screen with a matching native capture;
the operator waived a monitor photograph on 2026-10-09. Commit
under docs/evidence/shell-responsive/board/.Physical closeout — 2026-10-09: the operator explicitly accepts filled Home
and correct Home/All Apps/Settings targets in the accepted HDMI arrangement.
The matching native capture and numeric accepted configure records are in
the acceptance report.
No photograph is required under the prior waiver. Exact diagnostic command:
python3 docs/evidence/shell-responsive/board/acceptance-2026-10-09/capture-board.py --output /protected/private-responsive-capture. This is native/serial evidence
plus a separately recorded operator physical observation, not a camera recording.
The operator authorized moving original tasks 6.3–6.5 to
the-hdmi-shell-works-in-landscape,
where they remain unchecked as 7.1–7.3. This preserves icon/text density,
Wi-Fi/theme reflow and the dock slot-count decision without claiming any was
performed. Tasks 6.1/6.2 are completed by the separate physical closeout above; the
transferred tasks remain open in their successor.
See the committed scope decision.
Scope proof: openspec validate the-shell-adapts-to-output-resolution --strict
and openspec validate the-hdmi-shell-works-in-landscape --strict.
Landed on the same branch immediately after task groups 1–6 above; see
design.md’s two new “Decision (follow-up)” sections and its “Non-goal,
both passes” section for the full reasoning, including what was
reconsidered and rejected here.
feat/shell-responsive onto feat/hdmi-pillarbox’s
then-current head (46a8e37e, HDMI Sway output config +
theme_gtk.py fix) before starting; no conflicts (disjoint files).
Verify: cargo test still 389/389 immediately after the rebase, no
code changes yet.lib.rs’s density_scale, reflow_columns, and
settings_content_transform, each with its own unit tests
(density_scale_is_pixel_identical_at_native_and_bounded_above,
reflow_columns_matches_base_at_design_width_and_only_grows,
settings_content_transform_fills_the_panel_at_native_size).
Refactor navigation::columns_for_width to delegate to
reflow_columns (behavior-preserving: every pre-existing Drawer test
passes unchanged). Verify: cargo test.HomeLayout.columns (#[serde(default)]),
HomeLayout::reflow_to, home_grid::columns_for_width; give
home_grid::tile_rect/tile_content/spanned_tile_rect/slot_at/
plate_top_left an explicit columns parameter (sourced from
home.layout.columns at every call site, never independently
recomputed) in place of the COLUMNS constant; add home_grid:: apps_per_page’s width parameter; add HomeScreen::sync_columns,
called from main.rs’s draw_home. Verify: cargo test, including
new tests home_state.rs’s reflow_to_a_wider_column_count_never_ loses_or_reorders_items, reflow_to_round_trips_4_then_8_then_back_ to_4, reflow_to_is_a_no_op_when_columns_already_match,
reflow_to_keeps_a_multi_span_widget_intact_as_one_item;
home_grid.rs’s columns_for_width_matches_the_reference_at_568_and_ grows_for_hdmi, wide_hdmi_grid_hits_every_reflowed_column_of_the_ first_row; home_screen.rs’s sync_columns_reflows_to_a_wide_ output_and_back_without_losing_items — plus every pre-existing
drag/rearrange/folder/widget test in home_state.rs/home_screen.rs
passing unchanged, proving the field/parameter-shape refactor did
not change behavior at the reference column count.cr.save/translate/scale
transform to render.rs::scene’s Route::Settings arm (after its
“Done” check, excluding the Wi-Fi/theme-chooser early returns and the
unscaled header strip); make settings_panel_h/panel_travel_height
take a content_scale; add the matching remap to service_ui:: panel_intent’s Settings arm. Verify: cargo test, including new
test service_ui.rs’s settings_row_taps_follow_the_scaled_centered_ content_column_on_hdmi (taps the reboot row’s real on-screen
position at both a wide and a tall HDMI size, computed through the
same shared transform function scene paints with, and confirms a
miss well past the row).nix/rust-shell-client/tests/responsive_pixel_identity.rs:
decodes each committed docs/evidence/shell-responsive/*-568x1232. png and asserts it is byte-for-byte identical to a fresh render
through the (now-shared) evidence_render module, so “568x1232 stays
pixel-identical” is an automated cargo test assertion, not a one-
time visual check. Verify: cargo test --test responsive_pixel_identity — 4/4 pass against the evidence committed
by task group 4, confirming the follow-up changed nothing at
568x1232 before task 7.6 even re-rendered anything.cargo run --example render_responsive_evidence -- <out-dir>; confirm by direct cmp
that all four *-568x1232.png are byte-identical to the previous
commit and the other 12 changed (home-*/settings-* at the three
HDMI sizes; drawer-*/wallpaper-* unchanged, as expected since
neither’s own logic changed this round). Re-commit under docs/ evidence/shell-responsive/ (same group:16-files count, no
docs/blob-inventory.md row change needed) with the directory’s own
README.md updated to describe what changed and why.cargo test and cargo clippy --all-targets for
nix/rust-shell-client — 406 tests pass, no new clippy warnings.
Update this change’s proposal.md, design.md, and
specs/runtime/shell/spec.md to describe the follow-up (two new
ADDED requirements: Home’s grid reflow, Settings’ content column).
Verify: openspec validate the-shell-adapts-to-output-resolution --strict exits 0.Grounding: the normal board’s accepted wallpaper-configure 800x1280,
home-configure 800x1280 and configure 800x1280, matching native Home image
and operator acceptance are recorded in
docs/evidence/shell-responsive/board/acceptance-2026-10-09/README.md and
capture.json. The system’s actual logical HDMI geometry is 800×1280.
nix/rust-shell-client/src/main.rs accepts a valid size when it preserves the
existing aspect guard or matches a known whole output. Existing host fixtures
cover other geometries.
When a Wayland layer-shell configure gives a surface exactly the size of
a currently known output (an HDMI monitor at its own resolution, at any
aspect ratio, landscape or rotated portrait), the shell SHALL accept that
size and paint its wallpaper, Home grid/dock, and Drawer/Shade/Settings/
Power panel chrome to fill it completely, with no letterboxed or
pillarboxed band of unpainted or differently-colored space. A configure
that fails the existing aspect guard and is not the size of any known output
(in particular, a single-axis shrink such as an on-screen keyboard’s exclusive
zone) SHALL continue to be rejected exactly as before this requirement existed,
leaving the surface at its last accepted geometry. Aspect-preserving resizes
SHALL retain their existing acceptance behavior.
This requirement governs whether the surface itself is allowed to take
the output’s full size and whether what already reflows (the wallpaper
fill, Home’s row count, panel chrome) is allowed to do so. It does not by
itself require every on-screen element to relayout for the new size:
paint_wifi’s own pre-existing non-uniform scale and the theme chooser are
untouched by this requirement and remain named, out-of-scope follow-up work
in design.md.
configure whose size
matches a connected HDMI output’s own logical size (e.g. 1920x1080)configure reduces only the surface’s height (or only its
width), beyond the existing aspect tolerance, to a size that does not match
any known output’s own logical size*Grounding: nix/rust-shell-client/src/home_state.rs’s HomeLayout:: reflow_to and its own columns field, home_grid::columns_for_width, and
home_screen::HomeScreen::sync_columns, all read for this change. Proven
host-side by home_state.rs’s reflow_to_a_wider_column_count_never_loses_ or_reorders_items, reflow_to_round_trips_4_then_8_then_back_to_4,
reflow_to_is_a_no_op_when_columns_already_match, reflow_to_keeps_a_ multi_span_widget_intact_as_one_item, and home_screen.rs’s sync_columns_ reflows_to_a_wide_output_and_back_without_losing_items — host unit tests.
The operator accepts the Home target on the real
800×1280 HDMI arrangement in
docs/evidence/shell-responsive/board/acceptance-2026-10-09/operator-report.json.
The Home screen’s grid SHALL use more columns, proportional to the
surface’s own width (the same reflow the Drawer’s grid already uses),
instead of a fixed column count that leaves a wide output’s extra space as
bigger gaps between the same four columns. The dock SHALL retain its existing
four slots; whether/how its slot count reflows is preserved in
the-hdmi-shell-works-in-landscape task 7.3. Every icon, folder, and widget
already pinned to the grid SHALL remain present after a column-count
change, in its original relative reading order (top-left to bottom-right,
page by page); a widget’s multi-cell span SHALL remain a single, contiguous,
non-overlapping footprint at the new column count. Reflowing to a column
count already in effect SHALL NOT alter the stored layout.
*Grounding: nix/rust-shell-client/src/lib.rs’s density_scale and
settings_content_transform, render.rs’s scene (the transformed block
in its Route::Settings arm) and settings_panel_h, and service_ui.rs’s
panel_intent (the matching touch-point remap), all read for this change.
Proven host-side by lib.rs’s density_scale_is_pixel_identical_at_native_ and_bounded_above, settings_content_transform_fills_the_panel_at_native_ size, and service_ui.rs’s settings_row_taps_follow_the_scaled_centered_ content_column_on_hdmi (which maps a real touch point through the same
transform scene paints with and confirms it still resolves to the
correct row, and that a point past the row still misses). The operator
accepts the real Settings row target in the same HDMI arrangement, recorded in
docs/evidence/shell-responsive/board/acceptance-2026-10-09/operator-report.json.
Settings’ body content (the row cards, sliders, and Power section below the unscaled header strip) SHALL paint within a centered column no wider than the design’s own 568px, scaled up on a surface taller and denser than the 568x1232 design so its rows and text are not left disproportionately small relative to the extra space, and the panel containing it SHALL grow to match that scaled content’s own real height instead of remaining a short, content-sized “stub” over empty space below it. A tap SHALL resolve against that same centered, scaled position — never the row’s un-transformed design-unit position — so a real touch always lands on what is actually drawn there.
Archived change · Archived
Snapshot 5836ef1d113d · 2026-10-17 08:22 UTC
Closed recordAccepted installed shell is closed. Side-edge Back/general ownership and numerical motion tooling remain in the existing successor; other theme source requirements remain in their own proposals.
A person can launch apps, but the current permanent top bar and Back/Home footers make the 568×1232 touch screen feel like a button menu. The intended handheld uses a live card deck as Home, an installed-app drawer rising from it, and a notification shade descending from the top. Those surfaces need one direct-touch and motion contract before their implementations meet.
The production Rust shell is implemented and installed in the daily mainline
system; exact acceptance, source/bundle/runtime identity, ordinary boot and
limits are committed in docs/evidence/coherent-shell/operator-closeout-2026-10-10/README.md.
The operator explicitly waived further camera, per-case physical and comparative
probe evidence. Numerical motion measurement remains deferred to the existing
the-shell-gets-side-edge-back-and-motion-trace successor, which also owns
unimplemented side-edge Back and general at-down arbitration. These are not
implemented features of this archive. Existing host/QEMU/native/operator
results retain their evidence classes; missing quantitative and individual-case
observations remain UNVERIFIED rather than being invented for closeout.
The accepted navigation is app → Overview → pinned Home → All apps, per
runtime/home-screen’s landed gesture topology. This supersedes the historical
deck-as-Home/direct-deck-to-drawer wording wherever it remains below.
Acceptance and rollback retention replace the old capture-only default-promotion
prerequisites; no new probe benchmark or six-surface dark/light trial is claimed.
Non-goals: A second competing Home destination or hold-for-recents model; permanent Apps/Windows/System/Back/Home controls in the final shell; synthetic universal Back keypresses into arbitrary Wayland apps; Palm assets or pixel copying; LG television webOS patterns; an assumed new compositor/GPU renderer; haptic/vibration integration on this board; a lock screen; telephony, battery, account, or cloud services; replacing the sibling’s bounded live-card lifecycle.
runtime/device-settings: truthful, recoverable shell settings and system controls.runtime/notification-center: previews, history, actions, dismissal, privacy, and interruption policy.runtime/handheld-shell-design: add the accepted portrait appearance, navigation, direct manipulation, scene, accessibility and feedback contract while retaining its existing overlay requirements.
runtime/shell: replace the final persistent-bar navigation requirement with accepted Overview → pinned Home → drawer and shade/Settings behavior, retaining the separate rollback session. The installed bar remains only as a rollout/rollback session; Terminal remains a named recovery app in the drawer.
Planning affects the replacement of the shell bar in the final session, a Rust UI client for the launcher drawer/shade/Settings, the selected opt-in Sway card-scene integration, notification service, and Nix image defaults in later implementation. Host mockups and state/trace fixtures need no board. Operator acceptance covers the installed behavior with an explicit further-proof waiver. Numerical motion cadence and unrecorded individual physical cases remain UNVERIFIED; existing observations keep their original classes. No kernel, device-tree, stage-1, or radio change is presumed.
The installed development session is Sway/Pixman on the 568×1232 RM69A10 panel with GT9895 touch, Foot, wvkbd, a persistent top bar, and a desktop-entry launcher. The bar’s physical evidence is in docs/evidence/shell-real-touch-*; it proves the rollback path, not the final interface. The bounded live-card owner and selected opt-in Sway 1.12/wlroots 0.20.2 composition route are documented in the-shell-manages-apps-as-cards and docs/research/card-composition-architecture.md. Their physical cost and real-finger gates remain open. docs/research/handheld-ux/interaction-contract.md supplies contrast, geometry, focus and recovery evidence classes; this proposal supersedes its persistent-bar placement as a final design requirement.
The proposed surface sheet, motion storyboard, route map, and motion research are original planning artifacts, not installed captures. The Palm Pre User Guide documents app→card, card→Launcher upward gestures, horizontal cards, flick and throw; it does not provide measured animation timings. Android’s current navigation guide is a comparison for bottom swipe and app discovery, while Android’s developer guidance shows why edge/keyboard conflict policy matters. The later accepted Home proposal supplies pinned Home, with the Palm-style live deck retained as Overview; no hold-for-recents path is introduced. None of these sources proves K230 behavior.
The production Rust shell is implemented and installed in the daily mainline
system; exact acceptance, source/bundle/runtime identity, ordinary boot and
limits are committed in docs/evidence/coherent-shell/operator-closeout-2026-10-10/README.md.
The operator explicitly waived further camera, per-case physical and comparative
probe evidence. Numerical motion measurement remains deferred to the existing
the-shell-gets-side-edge-back-and-motion-trace successor, which also owns
unimplemented side-edge Back and general at-down arbitration. These are not
implemented features of this archive. Existing host/QEMU/native/operator
results retain their evidence classes; missing quantitative and individual-case
observations remain UNVERIFIED rather than being invented for closeout.
The accepted navigation is app → Overview → pinned Home → All apps, per
runtime/home-screen’s landed gesture topology. This supersedes the historical
deck-as-Home/direct-deck-to-drawer wording wherever it remains below.
Acceptance and rollback retention replace the old capture-only default-promotion
prerequisites; no new probe benchmark or six-surface dark/light trial is claimed.
Goals: A full gesture interface with one compositor-owned motion scene, live-card Overview followed by pinned Home and the drawer from below, shade from above, truthful Settings, private notifications, predictable Back/keyboard behavior, and tested physical recovery. Desktop-entry icons accompany names and never leak private app identity.
Non-Goals: Permanent navigation rail/footer in the final session; synthetic universal Back into arbitrary apps; a second competing Home destination; a new compositor or GPU chosen without measured reason; haptic work on the current board; battery/telephony/account services; changing the sibling’s bounded live-card source/close lifecycle.
Overview and pinned Home have separate roles. The accepted runtime/home-screen topology supersedes the original deck-as-Home plan: a bottom upward app gesture reaches the live-card Overview, a new upward gesture from Overview’s bottom navigation area reaches pinned Home without closing apps, and a new upward gesture from Home reaches All apps. Swiping a card itself upward retains its close action. Empty Overview offers a stable route to Home and Terminal in All apps. The old bar remains a separately selectable rollback session; normal composition has no permanent rail/footer.
Home opens installed apps. The drawer rises from Home’s bottom edge, tracks the finger and settles on release; cancellation restores the previous scene without launching. From an app, a pure upward bottom gesture reaches Overview, while a qualified two-axis gesture may select an existing neighbor. Apps launch only through their deliberate targets. Desktop-entry icons and readable names retain bounded caching, fallback and privacy rules. Help in All apps opens guidance and an optional deliberately selected large-labeled Navigation buttons view; changing route dismisses the aid. Search is the already-landed drawer capability, not deferred by this archive.
Top-edge shade owns notifications and Settings. A downward pull from the top reveals a nonmodal shade over the current scene. It contains a notification list and Settings entry; ordinary previews enter near its top edge and retreat into history/count without shifting or focusing the app. Settings opens within the shade’s spatial path, not a separate System button. A side swipe on a history item reveals Dismiss and commits only after a clear threshold; critical ongoing events remain. The existing privacy/priority/event broker policy stays intact. A later org.freedesktop.Notifications adapter is optional after explicit shell/system and integrated-app sources work.
Back is contextual shell navigation (side-edge mechanism moved to the authorized successor). An inward swipe from a qualified side edge closes the top shell context: long-press sheet, Settings, shade, drawer, then keyboard when keyboard focus owns the touch. A Back gesture in app content is not translated to an arbitrary Escape/Alt-Left keypress. Apps differ in navigation semantics; app content keeps its own scroll/selection/edge handling outside a verified shell edge. Bottom Home remains the shell escape from an app or overlay. Help and accessibility aid explain routes, but permanent Back/Home buttons are rejected for the final interface.
One touch owner wins at down and can cancel cleanly (general arbiter moved to the authorized successor). The compositor arbitrates bottom Home/drawer, top shade, side contextual Back, keyboard insets, live-card drag, active overlay and app content using measured hit regions and direction/distance gates. The keyboard’s lower region wins against bottom navigation there; a visible affordance or tested outer region still reaches Home, and keyboard dismissal never types into the app. A second contact, focus loss, view unmap, motion reversal, or premature release cancels from the current visual position, without turning the stream into a tap. The exact regions are provisional until real-finger trials; failed conflict gates keep the existing rollback session active. A gesture cue is shown at rest/first use, then can quiet down; it never needs a full-width button dock.
Use the selected Sway scene owner for cross-surface motion. The sibling card implementation owns live source eligibility, direct drag, expand, graceful-close request/refusal and seat focus lifecycle. This successor adds a single interruptible spatial state above those events. Sway owns the live scene trees, touch arbitration, z-order and focus; launcher/shade clients submit intent and geometry, without trying to animate another app’s pixels. App→deck maps one live rectangle into its card slot; deck→drawer rises from the bottom, shade→Settings descends from the top; card→app expands from its visible slot; throw tracks up and disappears only on observed exit. Current transform, target, velocity, source identity, pointer/focus owner and z-order are kept for reverse/retarget. A new gesture starts from the displayed state, not a reset keyframe. Client-only fake thumbnails, a second DRM owner, and a default new compositor are rejected because they cannot meet the live/focus contract without separate proof.
Motion references and deferred measurement. Quantitative trace implementation and the board budget run remain in the existing side-edge/motion successor, not an archive gate for this accepted shell. No budget number or pass is claimed here. Palm/Android references supply action/direction, not numeric timing. Finger tracking occurs for every accepted movement, with one-to-one displacement of the manipulated panel edge or grabbed live-card point until its travel bound. The recognition/release threshold is independent of visual travel: crossing it while still touching does not finish a transition. A held finger stops movement; reversal immediately follows the same position mapping. Inertia and easing apply only after release or cancellation. A bounded velocity estimate settles a card to at most one adjacent slot per release initially; lists coast inside content and stop on new touch without activating a row. Reduced motion shortens settling but retains drag, scene identity, destination and feedback. Scene damage/output scheduling owns animation ticks; frame-done and output-presented are logged separately. The approximately 52.19 Hz advertised mode implies about 19.2 ms nominal intervals, not measured scanout. Declare p95/p99 input-to-present, frame interval, CPU/RSS and blank-frame budgets before board tuning; proposed review target is no unexplained blank frames and p95 input-to-present within two observed output intervals during two live apps. If Pixman misses, trim decoration and unnecessary damage first; do not replace live tracking with a static capture. A renderer/compositor change needs a separate cost decision.
Visual grammar follows the active appearance. The former fixed teal palette is superseded by the active Omarchy generation’s authored section brushes, foreground, readable secondary foreground and accent. Gradient stops, direction and alpha remain intact; no decorative wash or alternate brand palette masks them. Type has clear title/body/meta roles, an 8-pixel rhythm and 24-pixel inset. Keep established hit geometry and at least 56-pixel controls. Expose themed desktop-entry artwork on Home rather than boxing each icon; give unresolved icons a deliberate neutral glyph container. The dock is one quiet tray, not nested trays. Ordinary control/notification rows use low-emphasis themed surfaces without routine border outlines. Focus, pressed selection, destructive confirmation and drag/drop retain deliberate cues. Theme carousel cards have rounded clips and a focused/active cue rather than outlines around every preview. Existing borderless clock/weather widgets remain borderless. The shell has no permanent Back/Home footer.
Bounded 2026-10-01 polish: docs/evidence/mainline-display/physical-2026-10-01/final-runtime-home.jpg shows nested icon/dock plates on the actual panel; docs/evidence/theme-picker/row-repaint/preflight.png shows rectangular theme preview outlines. These observations ground the problem, not the proposed result. Change userspace paint/style paths only. Preserve compositor overview/card movement and the coordinator’s renderer damage/caching work. Show matched native-resolution host renders for Home, drawer, Settings, shade and theme picker using real pinned dark/light theme appearances and wallpapers. A overview/card review image must explicitly identify its existing compositor capture; this pass cannot claim to have rendered live cards in the Rust client. The user accepts the installed result and waives a further real-glass dark/light recording; unrecorded per-surface contrast cases remain UNVERIFIED. Rejected: an invented brand palette, opacity masks flattening authored brushes, nested icon rectangles, a renderer rewrite and permanent navigation buttons.
The final shell UI client targets Rust; the compositor boundary stays put. Sway/wlroots remains responsible for live app/card pixels, touch arbitration at app/deck boundaries, z-order and focus. A Rust client owns drawer/shade/Settings surfaces, their finger state and route requests over the existing bounded session IPC. Existing C launcher source is a development reference and rollback, not the final client. Current Settings and notification helpers are separate Python services; a Rust UI does not imply they have been rewritten. The pinned nix/rust-shell-probe/ has now cross-built as a small layer-shell client using wl_shm software buffers and the existing overlay namespace; its historical comparative 568×1232 map/touch/resource/cadence trial is waived by the user. The production Rust shell has separate exact runtime/native-board identity and accepted interaction; no Rust/C/Qt comparative result is claimed. Host build and QEMU prove different things from a real touch/panel run. If Rust runtime or cost fails, retain the C reference and Qt results as evidence; do not assert a toolkit choice from source availability alone.
Build one opt-in Rust UI client from the proven protocol boundary. Keep nix/rust-shell-probe/ frozen as a reproducible feasibility artifact; create a separately pinned nix/rust-shell-client/ and .#handheld-shell-rust for the actual drawer, shade and Settings. Reuse the probe’s Wayland/layer-shell/SHM route semantics and released-buffer discipline, not its diagnostic drawing. Render software surfaces with Cairo plus Pango text bindings against the Cairo/Pango libraries already used by the C rollback client; this supports readable shaping, clipping, gradients and borders without a GTK widget stack. Evaluate the exact Rust binding dependency graph and cross-build before adoption; the production package is selected in the accepted daily mainline system with retained rollback; numerical board measurement is deferred. Use GIO’s desktop-entry semantics for installed names and launch, resolve icons through the selected freedesktop theme with bounded decode/cache and neutral private fallbacks, and keep all blocking catalog/decode/service work outside the Wayland dispatch path. The Rust process consumes the existing Settings JSON command, notification history socket, appearance-generation receiver contract and theme catalog command; it does not replace those services. Theme chooser preview/activation and all themed surface roles retain their own the-shell-loads-omarchy-themes acceptance gates. The compositor, not the Rust client, continues to move live app pixels, and no probe-only rectangle counts as the final drawer.
A bottom gesture keeps both axes until release and switches directly between apps. The compositor retains the same contact from app entry through lateral selection; moving up then sideways does not require an up/down pair or a new gesture owner. Vertical motion controls the app-to-card transform and horizontal motion translates the held scene point one-to-one, exposing the neighboring card in the drag direction. There is no axis lock that discards the other coordinate after recognition, no automatic progression while held, and no reset of geometry when the path bends. A pure upward release past the existing Home threshold settles into the deck. A qualified lateral release settles the visibly selected neighbor directly in a full or near-full app carousel; it does not first complete entry into the overview, recenter a card, or start a second expansion animation. A horizontal start anywhere along the bottom edge band uses only a slight zoom proportional to actual upward travel (none if the swipe stays purely horizontal), while a curved upward-then-sideways gesture retains its achieved vertical geometry. A short/reversed release returns to the originating app. At most one neighbor is committed per release initially; the corresponding horizontal travel bound is visible, with no wrap-around. A new touch stops settlement and retargets from the displayed geometry. (The “bottom-center band” qualifier here is superseded by decision 12 below: recognition no longer depends on start position.)
Both routes use the same deck ordering: dragging content right exposes its left neighbor, and left exposes its right neighbor. Focus-only switching does not reorder that sequence, so reversing the quick switch returns predictably. The compositor snapshots stable app IDs for the gesture and reconciles inserts/removals without substituting an unrelated target; a vanished/non-focusable target restores the source or a valid deck. Private/unavailable entries retain the sibling’s neutral preview rules and may be activated only through its existing focus policy. With one app or no neighbor in a direction, keep a bounded edge response and restore the source; do not start another app or wrap around. Only the settled target receives focus and is raised visibly.
Initial quick-switch recognition is confined to the central half of the existing bottom edge band, excluding keyboard-owned pixels and active shell overlays. That region is a provisional host geometry, not a physical usability claim. Bottom-corner and side Back ownership stay separate; ordinary app scrolling/selection outside the region stays with the app. The drawer gesture from Home remains a separate route. Thresholds select the release destination but never multiply movement. Release settling for both horizontal switching and vertical Home starts at the displayed position and measured, bounded swipe velocity, then smoothly decelerates or springs to the destination without an initial position or derivative jump or an intermediate forced overview. No timer advances the scene while the contact is held. Second contact or cancellation drains the owned stream without an app tap or throw-close. Reduced motion preserves the same geometry and destinations with shorter settling. This central-band gate is superseded below.
The user’s request on 2026-09-24 adds these two-axis and quick-switch routes to the installed vertical-only entry. nix/card-shell-policy/card-shell-policy.c:cs_entry_motion currently derives only vertical progress; the installed one-axis correction is recorded in docs/evidence/coherent-shell/direct-drag/installed.md. Google’s Android gesture guide documents bottom-edge switching, and Google’s gesture navigation codelab describes conflicts with app controls near that region. They inform the interaction, not K230 proof or an exact two-axis trajectory. Requiring a lift between entry and lateral selection was rejected because it breaks direct manipulation; changing the whole deck to focus-reordered history was rejected because left/right reversal would become unpredictable.
The central-band quick-switch gate is dropped; distance/velocity alone decide a lateral switch. A same-day real-finger board report on the just-landed two-axis entry found the central-band gate itself broke the primary case it was meant to serve: an 80%+ horizontal swipe starting near either side of the bottom edge still snapped back to the source app, because a pure lateral swipe outside the central half additionally required simultaneous upward travel past entry_distance, which an intentionally horizontal swipe does not produce. Recognition now depends only on measured lateral displacement (about 30% of the panel width, matching the target 25-35% range for a deliberate page-turn) or release velocity (about 0.4 px/ms in the swipe direction), independent of where along the qualified bottom edge band the touch started; the vertical-progress requirement is dropped for a pure lateral switch, though up-then-sideways still works identically. Release velocity is now a recency-biased estimate that walks back through recent samples only as far as needed for a stable interval (minimum ~6ms span, capped at ~120ms to bridge a sparse ~100ms event cadence), instead of a single last-interval delta gated by a fixed 80ms freshness window; the old gate zeroed momentum whenever dispatch lagged, the event cadence was sparse, or the finger’s last recorded sample preceded a slightly later release. A flick back toward the start still cancels the switch. Keyboard-owned pixels, active shell overlays and the existing bottom edge_band remain the only positional gates. Measured touch cadence (docs/evidence/touch-reports.md, docs/evidence/touch-evtest.txt) shows real reports arriving roughly every 8ms during continuous motion, informing both the window bound and its minimum span. See docs/evidence/card-shell/app-switch-swipe/ and nix/card-shell-policy/card-shell-policy.c:cs_entry_up_at.
wl_shm probe first, then measure exact board mapping/touch/CPU/RSS against C and Qt; do not promote the probe to the normal session without the existing physical acceptance gates.The production Rust client and compositor are built and installed in the matching daily mainline system, and the user accepts that result. Preserve the separate rollback session and protected previous boot selection. The original comparative probe, repeated physical matrices and camera promotion gates are waived by the user’s explicit closeout instruction. Existing source, host/QEMU, board-native, ordinary-boot and operator evidence remains distinct. Side-edge Back, the general arbiter and trace implementation remain open in their existing successor. No stage-1, kernel or radio change is part of this archive.
The opt-in coherent system also needs a bootable image identity, distinct from
the normal rollback image. Reuse mkBoardImage for a sdImage-coherent output
while retaining sdImage on the normal system. Its boot partition carries the
coherent system’s exact init= closure selection, kernel, initrd and device
tree. A running switch-to-configuration test is only a reversible preview:
the external bootloader hook is a no-op and U-Boot imports the fixed
/boot/bootargs.txt, so neither a profile update nor
switch-to-configuration boot alone selects this session after restart.
For later persistent selection, compare the matching image’s complete boot
file hashes with the installed files, preserve the previous selection and
recovery image, and update only the files that differ under a reserved board
procedure. A full image flash remains the fallback, not a prerequisite for
userspace-only changes. An ordinary reboot and exact running-system and
service identity are separate physical proof gates.
Current disposition — 2026-10-10: the operator accepted the installed result
and explicitly waived further proof gathering. The current task wording below
records that acceptance or measurement deferral; it does not mark historical
unperformed camera/benchmark commands as executed. Original open tasks and
commands are preserved under docs/evidence/coherent-shell/operator-closeout-2026-10-10/.
Later acceptance supersedes the older “keep open until captured” checkpoint notes.
The accepted route is app → Overview → pinned Home → All apps. Side-edge Back,
general ownership and trace implementation remain in their authorized successor.
Groups 1–3 can start after this revised proposal lands. Group 4 consumes the selected the-shell-has-a-card-composition-plan interface and the-shell-manages-apps-as-cards live-source/focus/cost gates. Group 5 requires a reserved board and installed opt-in image. The current bar is a separate rollback session, never a final navigation element.
The final launcher/drawer/shade/Settings UI client targets Rust. Current C source is a development reference/rollback, while Sway remains the compositor and current Python Settings/notification helpers remain separate services. The Rust probe in group 0 is a feasibility gate, not completion of any gesture, Settings, notification, or physical task. Implement the actual opt-in UI as nix/rust-shell-client/ and .#handheld-shell-rust, leaving nix/rust-shell-probe/ and its measured package reproducible. Reuse the Wayland/SHM and private route contracts, but require rendered names/icons, real service state and gesture behavior before calling it a shell. Compare the physical probe with the independent Qt Quick software probe before selecting the final default; the opt-in Rust UI package can be developed meanwhile.
Some named host files and narrow packages now exist as source checkpoints; each unchecked case below still requires its own actual implementation and passing command. tests/test_shell_motion.py now implements all thirteen task-4.1/4.2/4.3 integration cases with passing named evidence; tools/shell-motion-trace.py remains an interface to create, not current proof; tests/test_rust_shell_probe.py now covers only the probe. Existing Nix, OpenSpec, and capture commands are current. No host result substitutes for the physical gates.
wl_shm renderer with Cargo.lock, private route request and touch/cancel instrumentation; verify python3 tests/test_rust_shell_probe.py --case route-timeout --case configure-resize --case buffer-release --case touch-cancel, then nix build .#handheld-shell-rust-probe --dry-run. Record the evaluated target/dependency graph and compare dependency choices with the Qt Quick software probe. Dry-run is an evaluation gate, not a cross-build.nix build .#handheld-shell-rust-probe --no-link --print-out-paths --max-jobs 1 --cores 4 only in the reserved build slot. Record exact target/store path and runtime closure; inspect binary target and dynamic dependencies. A package build does not prove mapping or touch. See docs/evidence/coherent-shell/rust-probe-host.md.docs/evidence/coherent-shell/operator-closeout-2026-10-10/README.md. No new Rust/C/Qt resource or cadence comparison was run or claimed.nix/rust-shell-client (Route::Drawer/Route::Shade/Route::Settings/Route::Hide, lib.rs) plus nix/card-shell-policy/card-shell-policy.c’s CS_DECK, not by growing nix/touch-launcher --serve as this task’s own cited command assumed; tests/test_shell_routes.py/test_shell_gestures.py still only build the old nix/touch-launcher C rollback and are stale for this task. Real host/QEMU evidence: docs/evidence/coherent-shell/{drawer-route-host.md,rust-drawer-interaction-host.md,reveal-integrated-qemu/README.md,reveal-stream-host.md}. coherentShell stays an opt-in flag (nix/shell.nix, default false), so the old bar is the default session and there is no final bar only inside the opt-in path, matching the proposal.docs/evidence/coherent-shell/rust-drawer-interaction-host.md (“tracks scroll displacement while a finger moves, preserves sampled velocity until release, bounds its offset and flick velocity, stops coasting on a new contact without launching, and cancels tap on a scroll, long press, second contact or Back”). Horizontal sections are not exercised (single section today); optional per the task text.docs/evidence/coherent-shell/rust-drawer-interaction-host.md (“A long press opens a cancellable context sheet”), docs/evidence/coherent-shell/drawer-route-host.md.nix/rust-shell-client/src/icon.rs (drawer/notification) and nix/card-shell/icon.c (card headers, added by the-shell-behaves-as-one-coherent-system task A.3). Verify: python3 tests/test_shell_icons.py (8/8 passing 2026-09-28) plus docs/evidence/coherent-shell/icons/, rust-icons-host.md/.png.coherentShell = false rollback session; the ordinary image’s coherent selection landed earlier. Narrow task-group proof: CARGO_TARGET_DIR="$HOME/tmp/k230-admission-host-target" cargo test --offline --locked --manifest-path nix/rust-shell-client/Cargo.toml (498 passed, 1 existing ignored), reviewed production dark/light panel and HDMI host renders, then the exact coherent package-set cross-build recorded in docs/evidence/coherent-shell/navigation-aid-2026-10-10/README.md (one RISC-V Rust derivation, no dependency fetch/rebuild). Source 9e4515ed32cc849bfcc56dbe60d02e877bee75a7; the built artifact, hashes and retention roots are committed with this task. No board deployment or touch/discovery result is asserted; task 5.3 retains that physical gate and remains unchecked..#handheld-shell-rust package and fresh-home defaults, with host captures showing readable installed-app names, fallback icons and drawer geometry from real desktop entries. Verify: cargo test --manifest-path nix/rust-shell-client/Cargo.toml --locked. Correction (2026-09-28): this exact command was previously ticked citing another change’s stale evidence without being rerun here, and it did not in fact pass in this worktree — tests/theme_catalog_module.rs failed to compile (crate::runtime_trace unresolved in a #[path]-included module). Fixed on master by the close/themes merge (d622576a; the test crate now imports k230_shell_rust::runtime_trace; test-harness only, no shell-logic change). Rerun on close/shell-umbrella rebased onto a1daf003: 299/299 passing (239+22+14+8+11+5 across lib/bin/integration suites, 0 failed). Package defined at flake.nix:191; build/integration checkpoints: docs/evidence/coherent-shell/{prototype-launcher-build.md,image-wiring-host.md}. The rollback .#touch-launcher is unaffected.test_shell_routes.py still targets the old C rollback). Evidence: docs/evidence/coherent-shell/{settings-backend.md,notification-backend.md}, Route::Shade/Route::Settings in nix/rust-shell-client/src/lib.rs.openspec/changes/the-shell-behaves-as-one-coherent-system/proposal.md names this task explicitly as unimplemented (“The general side-edge contextual Back mechanism … → the-handheld-presents-a-coherent-shell tasks 2.2 and 4.4, still open”). Only a narrower bottom-edge overlay-escape + dismiss-direction fix landed (docs/evidence/coherent-shell/overlay-bottom-escape-qemu/), which that same proposal says explicitly does not complete this task. Scope split authorized by the user on 2026-09-28 (“yes a-d and f”): carried forward verbatim into the successor the-shell-gets-side-edge-back-and-motion-trace’s own task 1.1. No side-edge Back gesture has been implemented by this change; that work is not done, only relocated. See the scope-split note after task 4.4 below.tools/device_settings.py implements exactly this contract ("network"/"brightness"/"keyboard"/"motion" keys, read-only/unavailable states, no battery key). Verify: python3 tests/test_device_settings.py (9/9 passing 2026-09-28, incl. test_capability_states, test_no_battery_or_network_identifiers, test_fresh_home).python3 tests/test_device_settings.py (same run; test_restart_cancel, test_denial_consumes_confirmation, test_expired_and_replaced_confirmation pass) plus docs/evidence/coherent-shell/settings-backend.md.nix build .#handheld-settings (derivation proof only). Ran 2026-09-28: nix build .#handheld-settings --no-link --print-out-paths --max-jobs 1 --cores 4 → /nix/store/46sw7cwipb8g0pfjqa7vry4x1x65345g-k230-settings, exit 0.tools/notification_center.py implements this. Verify: python3 tests/test_notification_center.py (9/9 passing 2026-09-28, incl. test_priority, test_privacy, test_retention_deduplication_and_expiry, test_unknown_source).tools/notification_center.py’s preview data is non-focus-taking by construction (module docstring: “non-focus-taking preview data”; emitted events carry "focus": False), so the “typing-focus” case holds regardless of keyboard state. Verify: same test run (test_preview_timeout_preserves_history, test_action_gone_and_retry, test_critical_retained_until_resolved, test_critical_flood_is_bounded pass); docs/evidence/coherent-shell/notification-backend.md.python3 tests/test_notification_center.py --case history-flick-stop --case swipe-cancel --case swipe-dismiss --case critical-retained with CARD_SHELL_SWAY and K230_SHELL_RUST bound to the exact cross-built executables. Paired injected-touch QEMU and host proof: docs/evidence/coherent-shell/notification-history-motion-qemu/README.md; on-glass task 5.4 remains open.nix build .#handheld-notifications (derivation proof only). Ran 2026-09-28: nix build .#handheld-notifications --no-link --print-out-paths --max-jobs 1 --cores 4 → /nix/store/n9p1qlrflc463v3siyrhj49n5hdbh1fd-k230-notifications, exit 0. A desktop notification adapter remains a separately reviewable extension. 4.1 Consume the sibling’s live-source, privacy, graceful close and focus lifecycle, showing only eligible live cards and neutral private/unavailable placeholders; verify python3 tests/test_shell_motion.py --case live-gate --case private-no-icon --case close-refused. Reopened (2026-09-28) on coordinator review: a previous tick here cited scattered docs/evidence/coherent-shell/ files in place of this task’s own named test, which does not exist (tests/test_shell_motion.py is confirmed absent, matching this file’s own preamble). Real, relevant evidence does exist (nix/card-shell/adapter.c privacy/eligibility handling per the-shell-manages-apps-as-cards tasks 2.1/3.1; docs/evidence/card-shell/injected/README.md) but substituting it for the named fixture is exactly the “citing different evidence than the task requires” pattern AGENTS.md’s evidence discipline warns against; leaving open until test_shell_motion.py exists and passes, or the task is formally revised to name different proof. Completed with fresh named proof (2026-10-10): the fixture now exists and its exact three-case command passed against the current selected gp9gv2nh…/g7xzwwvr… compositor. It checks two live roots/subsurfaces, visible neutral unavailable/private cards, distinguishing-icon/name suppression, actual graceful close/timeout, surviving focus and keyboard delivery. docs/evidence/coherent-shell/integration-gate-2026-10-10/README.md commits the command, executable identities, UTC results, actual captures and a failing private-marker-omission control. This is QEMU user/native Wayland injected-input proof, not a new board or physical timing result.
4.2 On the selected opt-in Sway scene route, coordinate bottom app→deck, deck→drawer, card→app and top shade→Settings geometry, z-order, clipping and focus as one state; verify python3 tests/test_shell_motion.py --case shrink-live --case drawer-rise --case shade-descend --case expand-live --case focus. Reopened 2026-09-28, same reason as 4.1. Partial QEMU evidence exists (docs/evidence/coherent-shell/{reveal-integrated-qemu,direct-reveal-drag-qemu,rust-shade-dismiss-qemu,two-axis-qemu}/README.md) but does not substitute for this task’s own named fixture. Completed with fresh named proof (2026-10-10): all five cases now exist and their exact command passed against the newly built gg7m8cqi…/2djjlzlh… compositor and unchanged selected q2rxmp98… Rust shell. The current app→Overview→pinned Home→Drawer route is the accepted archived Home task-group-10 implementation, superseding the historical direct deck→drawer wording above and design decision 1; no new navigation scope is introduced. Actual captures/counters prove held live shrink/clipping, one-to-one drawer/shade travel, overlay z-order, card expansion, Settings return and keyboard focus. The same frozen fixture fails on the old compositor because 100px of finger travel moves Drawer 120px; the adapter now uses the Rust drawer’s height-minus-32 travel. docs/evidence/coherent-shell/coordinated-scene-2026-10-10/README.md commits commands, hashes, UTC results, captures, the old-artifact regression control, passing 4.1 compatibility cases and the repaired host build-output roots. QEMU injected-input proof only; updated-compositor board deployment and distinct physical gates remain open.
4.3 Support reverse/retarget from current visible geometry on Back, new drag, second contact, unmap and close refusal with no blank/misowned frame; verify python3 tests/test_shell_motion.py --case reverse --case retarget --case unmap --case refusal --case private-no-flash. Reopened 2026-09-28, same reason as 4.1. nix/card-shell-policy/card-shell-policy.c does have a reverse/retarget state machine (entry_reverse_from, entry_reverse_dx, entry_reverse_anchor, expand_reversing, expand_reverse_from) exercised in docs/evidence/coherent-shell/two-axis-qemu/README.md, but that is not this task’s own named fixture. Completed with fresh named proof (2026-10-10): all five cases pass on the newly built dicjv65r…/awym9l5z… compositor and unchanged selected Rust shell. Back and second contact now seed reversal from current visible geometry instead of immediate restoration, with canceled streams drained through entry-mode release. Actual native-client exits, graceful-close refusal/timeout and mid-entry privacy changes are exercised. The prior compositor fails both cancellation controls; all eight task-4.1/4.2 compatibility cases and 38 host policy checks pass. docs/evidence/coherent-shell/interruption-gate-2026-10-10/README.md preserves commands, source/artifact hashes, UTC results, sampled frames, controls, build retention and the separate user acceptance report. This is QEMU injected-input proof only; updated-compositor board deployment and distinct physical/trace gates remain open. Existing Back command only; side-edge Back remains in its successor.
4.4 MOVED, NOT PERFORMED HERE: define touch ownership for bottom Home/drawer, top shade, side Back, keyboard, deck and app content; test app scroll/text selection and keyboard conflict before enabling edges. Confirmed still open at audit (2026-09-28), same citation as task 2.2: the-shell-behaves-as-one-coherent-system/proposal.md names task 4.4 as still open — side-edge Back ownership specifically is unresolved. Scope split authorized by the user on 2026-09-28 (“yes a-d and f”): carried forward verbatim into the successor the-shell-gets-side-edge-back-and-motion-trace’s own task 1.2. No general touch-ownership arbiter has been implemented by this change; that work is not done, only relocated. See the scope-split note below.
4.5 MOVED, NOT PERFORMED HERE: add touch→scene damage/commit→frame-done→output-presented trace IDs, reduced-motion parity, process CPU/memory sampling, and declared board p95/p99 budgets. Confirmed not started at audit (2026-09-28): tools/shell-motion-trace.py and tests/test_shell_motion.py do not exist on disk (this task’s preamble already calls them “interfaces to create, not current proof”). This is real, unbuilt measurement tooling, not a small gap. Scope split authorized by the user on 2026-09-28 (“yes a-d and f”): carried forward verbatim into the successor the-shell-gets-side-edge-back-and-motion-trace’s own task 2.1 (host) and 2.2 (board). Neither the trace tool nor its tests have been built by this change; that work is not done, only relocated. See the scope-split note below.
4.6 Build the integrated closure only after narrow packages and fixtures pass; verify nix build .#nixosConfigurations.k230.config.system.build.toplevel (cross-build proof only). This task names the plain k230 toplevel (routinely proven: docs/evidence/cross-build.txt), but the component this group is actually coordinating only exists in the opt-in k230-coherent-shell configuration. Task 4.9 (done) already built sdImage-coherent, which necessarily builds the k230-coherent-shell toplevel as a dependency: docs/evidence/coherent-shell/boot-artifacts/README.md, integrated-image-host.json.
Scope-split note on tasks 2.2, 4.4, and 4.5 (staged 2026-09-28, authorized 2026-09-28): these three tasks describe genuinely unimplemented, non-trivial scope that does not depend on the board — the side-edge contextual Back gesture (2.2/4.4, confirmed still open by a sibling change’s own proposal text) and the touch→commit→present motion-trace tool with declared budgets (4.5, whose interfaces do not exist). The successor change the-shell-gets-side-edge-back-and-motion-trace carries these three tasks and their capability-spec text forward. The user authorized this split on 2026-09-28 (“yes a-d and f”). Tasks 2.2, 4.4, and 4.5 above are now ticked [x] ... MOVED, NOT PERFORMED HERE, and this parent’s own runtime/handheld-shell-design spec delta has been narrowed to drop the side-edge-Back and general-arbitration clauses the successor now owns (see that file). Nothing here claims the side-edge gesture, the arbiter, or the motion-trace tool actually exist — only the task bookkeeping moved.
4.7 Extend the bottom gesture policy to two-axis held tracking, upward-to-lateral continuation, quick switch gated by measured distance/velocity alone (not by where along the qualified bottom edge band the touch started — see design.md decision 12; a same-day real-finger report found the original central-band gate itself caused snap-back on legitimate wide swipes), separate release thresholds, stable focus-independent order, bounded neighbor selection and source/target disappearance. Pure lateral switching SHALL stay in a full or near-full app carousel with only zoom proportional to actual upward finger travel; release SHALL seed horizontal and vertical settling from current geometry and bounded measured velocity (a recency-biased estimate over recent samples, not a single stale last-interval delta), without a forced overview stage. Added displacement/hold/reversal/cancellation, release-velocity/no-jump, one-app/end-of-deck, keyboard/overlay/app conflict, reduced-motion and no-throw/no-tap cases to the existing native policy fixture, plus a dedicated app-switch-swipe case (80% slow swipe, 30% fast flick, sparse ~100ms cadence, stale-last-sample flick, up-then-sideways, reversal-cancels, pure-vertical); verified with python3 tests/test_card_shell_state.py (29/29, host policy proof only). Evidence: docs/evidence/card-shell/app-switch-swipe/README.md.
4.8 Implement compositor scene translation and direct release-to-neighbor focus/raise, plus smooth pure-upward Home settlement, without resetting visible geometry or velocity, including interrupted settlement. Build the exact candidate with nix build .#card-shell --max-jobs 1 --cores 4 --no-link --print-out-paths, then run python3 tests/test_card_shell_two_axis_runtime.py using CARD_SHELL_SWAY set to that exact unwrapped target. Reopened (2026-09-28) on coordinator review: a previous tick here cited docs/evidence/coherent-shell/two-axis-qemu/README.md (from 2026-09-24, source 532115c2) as passing. Rebuilt .#card-shell fresh from the current worktree and reran the fixture: it fails —
AssertionError: ((0, 0, 566, 1230), (16, 0, 552, 1128)) at tests/card_shell_runtime.py:252, meaning the live view is not shrinking vertically on the two-axis entry gesture in the current compositor build. The cited evidence describes an earlier source revision, not the one now on this branch; this is exactly the “cite stale evidence instead of rerunning” pattern that must not stand. Left open until the fixture passes against a fresh build.
Fixed and reverified (2026-09-28, branch fix/two-axis-entry-regression, base 88ccca15): bisected between the 2026-09-24 evidence’s source (532115c2, rebased into this history as byte-identical b8bfe26c) and HEAD. Culprit: 1bc355c3 (“card-shell: Android-recents-sized, rounded overview cards”, the-overview-shows-large-rounded-cards) grew the overview’s own card slot to 80%/80% of the panel while intentionally leaving entry_card_width/entry_card_height (the direct-switch entry gesture’s own anchor/travel reference, decision 6 of that change’s design.md) untouched — the two, previously nearly equal by coincidence, now diverge by ~224px in height. cs_entry_visual_rect’s single fixed linear entry_anchor_shift_y correction (sized to keep one anchor point exactly under the finger despite blending toward a differently-sized rect) scales with that divergence; for this bottom-edge gesture’s near-1 anchor fraction it grew large enough to push the entering card’s computed top edge negative (off the output) for most of the drag — mathematically exact for the one point it solved, but visually indistinguishable from “the view isn’t shrinking.” Fixed in nix/card-shell-policy/card-shell-policy.c (cs_entry_visual_rect/cs_entry_set_geometry) and .h: r.y/r.height now blend directly between cs_entry_target_rect (while held, entry_anchor_factor==1) and cs_card_rect (as it settles to 0), exact at both ends with no separate correction term; entry_anchor_shift_y removed. tests/card_shell_policy_driver.c’s entry_finger_y helper updated to mirror the new formula (same asserted finger-position constants, since the anchor invariant is preserved by construction). Verified: nix build .#card-shell --max-jobs 1 --cores 6 --no-link --print-out-paths -> /nix/store/wgzh0z3kxgj41kfgdx5sg1q5syfv0sg1-k230-card-shell (unwrapped sway /nix/store/vr72vwrsgcya09qpannsgbv0339p242s-.../bin/sway); python3 tests/test_card_shell_two_axis_runtime.py PASSES (origin=(0,0,566,1230), vb=(30,26,536,1128) on the same 100px drag that previously gave vb=(16,0,552,1128)); python3 tests/test_card_shell_state.py 36/36; tests/test_card_rounded_clip.py, test_card_shell_video_card.py, test_card_shell_switch_neighbour_runtime.py, test_card_shell_scaled_cache_runtime.py all PASS on the fixed build. See docs/evidence/coherent-shell/two-axis-qemu/README.md’s 2026-09-28 section for the full bisection, root-cause derivation, and before/after pixel comparison. Two unrelated QEMU fixtures (test_card_shell_touch_first_runtime.py, test_card_shell_home_bleed.py’s two-axis case) failed on a wait_for timeout during this session on both the fixed and unpatched builds under heavy shared-host load (~50 concurrent worktrees, load average 25-62) — confirmed pre-existing and independent of this fix, not a regression, and out of this task’s scope. Real-glass reachability, touch ownership, finger alignment, animation smoothness, and latency remain UNVERIFIED (host-QEMU proof only).
4.9 Expose a bootable opt-in coherent-shell image through the existing board-image builder while preserving the normal sdImage rollback output. Verify evaluated identities with nix eval --raw .#nixosConfigurations.k230-coherent-shell.config.system.build.toplevel and nix eval --raw .#sdImage-coherent.drvPath; build nix build .#sdImage-coherent --max-jobs 1 --cores 4 --no-link --print-out-paths in the sole build slot and inspect its kernel, initrd, device tree and bootargs.txt against that exact coherent closure. This is host artifact proof, not a persistent board boot. See docs/evidence/coherent-shell/boot-artifacts/README.md and integrated-image-host.json.
5.1 Record operator acceptance of implemented shell routes/recovery and waiver of additional camera/per-case physical collection in docs/evidence/coherent-shell/operator-closeout-2026-10-10/README.md, retaining prior exact navigation and ordinary-boot evidence. The historical named 60-second camera command was not run for this closeout.
5.2 Record operator acceptance of live-card behavior and the additional camera waiver, retaining prior card implementation, host/QEMU and accepted board evidence. Verify the committed disposition in docs/evidence/coherent-shell/operator-closeout-2026-10-10/README.md; no new reverse/throw/refusal video is claimed.
5.3 Record accepted drawer/Settings/Help/navigation-aid behavior and waiver of additional scroll, long-press and app/keyboard-conflict captures. Verify the exact operator report and native Help artifact references in docs/evidence/coherent-shell/operator-closeout-2026-10-10/README.md. No new per-case physical outcome table is claimed.
5.4 Record operator acceptance of implemented notification/Settings behavior under the explicit proof-collection waiver, with earlier host/QEMU event, focus, dismissal, priority and failure evidence retaining its limits. Verify docs/evidence/coherent-shell/operator-closeout-2026-10-10/README.md; no new notification/typing/critical/failure camera trial was performed.
5.5 Record the user-authorized measurement deferral and confirm the already authorized successor the-shell-gets-side-edge-back-and-motion-trace still owns trace-tool implementation and board measurement in tasks 2.1/2.2 and its motion-budget requirement. Verify the disposition in docs/evidence/coherent-shell/operator-closeout-2026-10-10/README.md. No latency/frame/CPU/RSS number or budget pass is asserted.
5.6 Validated after committed evidence on 2026-10-01; openspec validate the-handheld-presents-a-coherent-shell --strict passed and python3 tools/work-status.py completed its cached audit. This closes validation/bookkeeping only. Unmet physical tasks remain unchecked; the umbrella is not archived.
5.7 Record accepted two-axis/app-switching behavior with existing implementation/QEMU evidence and the explicit waiver of further per-direction, hold, reversal, deck-end, target-exit and keyboard-conflict physical captures. Verify docs/evidence/coherent-shell/operator-closeout-2026-10-10/README.md; no new camera matrix is claimed.
5.8 Record the installed matching mainline bundle, unchanged kernel/initrd, preserved stage-1/selectors and rollback roots, all installed hashes, exact system/profile/client/compositor/helper, four active services and untouched ordinary boot with fresh ID effcb1f4-3cdc-4647-bd7b-517d4072ae1a. The named python3 tools/console.py /dev/ttyACM0 --wait=5 identity/service command and reviewed panel-native Help passed; actual commands and reports are in docs/evidence/coherent-shell/combined-board-candidate-2026-10-10/README.md. Record the user’s acceptance/waiver of additional physical and themed-state prerequisites in docs/evidence/coherent-shell/operator-closeout-2026-10-10/README.md. No active appearance generation/report existed before or after, so restoration of a selected generation is not claimed.
cargo test --offline --manifest-path nix/rust-shell-client/Cargo.toml --lib in the existing host development environment.cargo run --offline --manifest-path nix/rust-shell-client/Cargo.toml --example render_polish_evidence -- <out-dir> <dark-generation> <light-generation>; record source identity, input paths and limitations under docs/evidence/shell-polish/.nix build --impure --expr invocations with --no-link --print-out-paths --max-jobs 1 --cores 4 recorded verbatim in docs/evidence/shell-polish/cross-build.md, selecting committed source 376f08632152d03963bd47a86ae9b352e357d271 and nixosConfigurations.k230-coherent-shell.pkgs.callPackage for nix/rust-shell-client and nix/card-shell.nix. Both passed. The generic standalone Rust attribute has a different dependency graph; use the configuration graph for board-qualified binaries. A build does not prove installation or panel behavior.docs/evidence/coherent-shell/operator-closeout-2026-10-10/README.md. Retain previous production host renders and exact installed native captures with their original provenance; no new camera/contrast/theme-apply trial is claimed.2026-10-01 Settings polish follow-up to 6.1: separate the output-description
line from the volume slider and move its picker tap band with the text. The
library suite passes 426 checks (one existing ignored benchmark); the production
host evidence example now includes a synthetic present output in both pinned
dark/light renders. See docs/evidence/shell-polish/settings-volume-layout/README.md.
The slider’s position and broader route geometry are unchanged. Matching
cross-build/install and real-glass review are distinct from this host result;
6.4 remains open.
Settings volume-layout follow-up is built and running on the board from source
5bb67db1. Nine native runtime/uinput checks and dark/light/picker captures pass:
docs/evidence/shell-polish/settings-volume-layout/board/README.md.
The original theme/volume were restored; boot/profile remain unchanged. This
qualifies these bounded controls, not all six surfaces or the unperformed
real-glass/persistent-boot parts of 6.4 and 5.8.
2026-10-01 persistent-deployment reconciliation: the exact source 5bb67db1
Rust executable (3hy6h165…) now runs in normal system/profile p1a1hz…
after an untouched ordinary reboot with matching Image/initrd/DTB/init selector.
All three shell services are active, Home is visible in a reviewed native
capture and panel photograph, and saved appearance generation/report hashes
are unchanged. Proof:
coherent-ordinary-boot.
This supersedes the runtime-only deployment note above, but does not tick 5.8:
that task explicitly follows the required on-glass gates, several of which
remain open in this umbrella. It also does not complete all-six-surface glass
polish in 6.4. The selected-system boot proposal owns the bounded reboot proof.
2026-10-10 combined-install follow-up to 1.5: matching Help/navigation aid now
runs in the ordinary daily mainline system, with exact operator acceptance
and native board rendering recorded in
docs/evidence/coherent-shell/combined-board-candidate-2026-10-10/README.md.
This supersedes the earlier host-only deployment note without completing
task 5.3’s broader named camera/gesture/conflict proof.
Defines truthful device settings and system actions that a person can understand and operate on the handheld without an external keyboard.
Grounding: operator acceptance and explicit additional-proof waiver in docs/evidence/coherent-shell/operator-closeout-2026-10-10/README.md; prior host/QEMU/board evidence retains its original provenance. This is acceptance of the installed result, not a newly recorded individual-case test or timing measurement.
The shell userspace SHALL show only controls backed by a readable or writable system capability in the installed image. It SHALL identify unavailable, read-only, and pending controls explicitly. It SHALL NOT show a battery gauge or battery-dependent action without observed battery hardware and state reporting.
Grounding: operator acceptance and explicit additional-proof waiver in docs/evidence/coherent-shell/operator-closeout-2026-10-10/README.md; prior host/QEMU/board evidence retains its original provenance. This is acceptance of the installed result, not a newly recorded individual-case test or timing measurement.
The shell userspace SHALL label power and restart actions by effect, require confirmation for disruptive actions, and report denial or failure without trapping the person. Settings defaults SHALL be provided by the NixOS image for a fresh home.
Grounding: operator acceptance and explicit additional-proof waiver in docs/evidence/coherent-shell/operator-closeout-2026-10-10/README.md; prior host/QEMU/board evidence retains its original provenance. This is acceptance of the installed result, not a newly recorded individual-case test or timing measurement.
The shell userspace SHALL use the active appearance generation’s authored palette and section brushes, a consistent text hierarchy, spacing system, and touch vocabulary across the deck, drawer, shade, Settings, and notifications at the panel’s 568×1232 portrait size. At the current output scale of 1, one logical pixel equals one panel pixel; interactive targets SHALL be at least 56 such pixels tall and later scaling SHALL preserve physical size. Essential information SHALL remain legible without color alone. The final normal session SHALL have no permanently visible Apps/Windows/Keyboard/System rail or Back/Home footer.
Grounding: operator acceptance and explicit additional-proof waiver in docs/evidence/coherent-shell/operator-closeout-2026-10-10/README.md; prior host/QEMU/board evidence retains its original provenance. This is acceptance of the installed result, not a newly recorded individual-case test or timing measurement.
The shell userspace SHALL preserve authored background gradients, alpha, foreground and accent when painting its Home, drawer, shade, Settings and theme picker. Routine app-icon plates, control rows and theme preview frames SHALL avoid unnecessary borders; focus, selection, destructive actions and drag/drop SHALL remain distinguishable. Existing gestures and interactive targets SHALL retain their behavior. The compositor SHALL continue to own live overview/card pixels and movement.
Grounding: operator acceptance and explicit additional-proof waiver in docs/evidence/coherent-shell/operator-closeout-2026-10-10/README.md; prior host/QEMU/board evidence retains its original provenance. This is acceptance of the installed result, not a newly recorded individual-case test or timing measurement.
Grounding: accepted Home navigation in docs/evidence/home-screen/navigation/operator-acceptance-2026-10-01.md, exact candidate navigation acceptance and ordinary boot in docs/evidence/coherent-shell/combined-board-candidate-2026-10-10/README.md, and the operator’s additional-proof waiver in docs/evidence/coherent-shell/operator-closeout-2026-10-10/README.md.
The shell SHALL keep the live-card Overview separate from pinned Home. A purely upward bottom-edge gesture from an app or transient shell surface SHALL reach Overview with the eligible app shrinking into its live card. An upward gesture from Overview’s bottom navigation area SHALL reveal pinned Home without closing or unmapping running apps. A new upward gesture from Home’s bottom edge SHALL reveal All apps. The same contact SHALL NOT traverse both destinations. Swiping a card itself upward SHALL retain its close action. Empty Overview SHALL retain a useful Home route, and All apps SHALL include named Terminal recovery. Repeating Home SHALL leave pinned Home stable.
Grounding: operator acceptance and explicit additional-proof waiver in docs/evidence/coherent-shell/operator-closeout-2026-10-10/README.md; prior host/QEMU/board evidence retains its original provenance. This is acceptance of the installed result, not a newly recorded individual-case test or timing measurement.
The compositor SHALL retain one touch owner when an app-entry gesture bends from upward to sideways movement. The manipulated point SHALL follow both finger coordinates one-to-one within declared travel bounds, with no held-contact easing, automatic progress, or axis-change jump. A qualified lateral release SHALL settle and activate the visibly selected adjacent running app directly from the current full or near-full carousel geometry, without a forced overview or second expansion stage; a purely upward release SHALL settle into Overview from its current geometry. A horizontal gesture starting anywhere along the qualified bottom edge band SHALL offer the same adjacent-app switching without requiring an upward gesture or a full card zoom, gated only by measured lateral displacement or release velocity in the swipe direction and not by where along the band the touch started. Release thresholds SHALL NOT amplify visible motion. Short/reversed gestures, and a release whose recent velocity trends back toward the start, SHALL restore the originating app without activating a neighbor. Settling on either axis SHALL begin at the displayed position and bounded measured release velocity, with smooth deceleration or spring and no initial position or derivative jump; velocity SHALL influence motion only after release and SHALL be estimated from recent samples rather than a single possibly-stale last delta. A new accepted touch SHALL stop or retarget settlement from current geometry.
Both routes SHALL use the deck’s stable left/right app order, unchanged by focus-only switching, and SHALL commit at most one neighbor per release initially. Dragging the scene right SHALL reveal the left neighbor and vice versa. They SHALL NOT wrap at either end, launch a new app, throw-close an app, or substitute a newly mapped app for a disappearing target. The compositor SHALL preserve the sibling’s privacy, source-lifetime, focus eligibility and visible raise behavior. Keyboard-owned regions, active overlays, side Back regions and ordinary app content outside the qualified bottom region SHALL keep their touch ownership.
Grounding: operator acceptance and explicit additional-proof waiver in docs/evidence/coherent-shell/operator-closeout-2026-10-10/README.md; prior host/QEMU/board evidence retains its original provenance. This is acceptance of the installed result, not a newly recorded individual-case test or timing measurement.
A downward gesture from the top edge SHALL reveal a notification shade over the current scene; the shade SHALL expose notification history and a truthful Settings entry. The bottom-edge app/overlay gesture SHALL remain the escape to Overview while a context is open; its Home route SHALL retain pinned Home and running apps.
Grounding: operator acceptance and explicit additional-proof waiver in docs/evidence/coherent-shell/operator-closeout-2026-10-10/README.md; prior host/QEMU/board evidence retains its original provenance. This is acceptance of the installed result, not a newly recorded individual-case test or timing measurement.
The shell userspace SHALL follow one accepted finger during a deck drag, drawer/Settings/history scroll, or eligible section swipe. During an accepted drag, the manipulated edge or grabbed point SHALL move one logical pixel per logical pixel of finger movement within its travel bounds, including immediate reversal; a stationary held finger SHALL produce no continued movement. Recognition and release thresholds SHALL NOT multiply visible displacement. Easing, inertia, and automatic settling SHALL begin only after release or cancellation. A release SHALL resolve from the displayed position with bounded momentum and a visible settled destination; a new touch SHALL stop coasting. Tapping a card or app SHALL activate it. A deliberate long press SHALL show a context cue before an action, allow movement away or cancellation without activation, and never masquerade as a tap. All apps SHALL provide a Help target with gesture guidance and a deliberately opened Navigation buttons aid for Home, All apps, Notifications and Settings. The large labeled controls SHALL appear only while that aid is open; a route change SHALL dismiss the aid. The aid SHALL NOT form permanent navigation chrome.
Grounding: operator acceptance and explicit additional-proof waiver in docs/evidence/coherent-shell/operator-closeout-2026-10-10/README.md; prior host/QEMU/board evidence retains its original provenance. This is acceptance of the installed result, not a newly recorded individual-case test or timing measurement.
The shell userspace SHALL present app→card entry, adjacent deck travel, card→app expansion, drawer rising from Home, shade descending over the task, and app launch/return as related positions in one scene. The selected live app SHALL keep its identity and visual content through eligible transforms; direction, scale, stacking order, and focus SHALL resolve coherently when motion is interrupted, reversed, or retargeted. No transition SHALL show an unowned black/blank frame or another app’s private pixels. Reduced motion SHALL preserve interactive drag, destination, focus, feedback, and recovery with shorter settling and no decorative travel.
Grounding: operator acceptance and explicit additional-proof waiver in docs/evidence/coherent-shell/operator-closeout-2026-10-10/README.md; prior host/QEMU/board evidence retains its original provenance. This is acceptance of the installed result, not a newly recorded individual-case test or timing measurement.
After a gesture is accepted, another surface SHALL NOT reinterpret that sequence as a tap or swipe. Accepted press, long press, snap, close request, refusal, and failure SHALL have immediate visible feedback.
Grounding: operator acceptance and explicit additional-proof waiver in docs/evidence/coherent-shell/operator-closeout-2026-10-10/README.md; prior host/QEMU/board evidence retains its original provenance. This is acceptance of the installed result, not a newly recorded individual-case test or timing measurement.
The drawer, eligible card headers, and trusted app notifications SHALL resolve an installed app’s desktop-entry Icon through the image’s icon theme where available, use a consistent sized fallback glyph when absent or unreadable, and keep a text label as the identifying route. Icon loading SHALL be bounded/cached so scrolling does not repeatedly decode assets. A private card SHALL show a neutral placeholder without its title or app-specific icon. Context actions SHALL use readable labels with any icon as a secondary cue.
Grounding: operator acceptance and explicit additional-proof waiver in docs/evidence/coherent-shell/operator-closeout-2026-10-10/README.md; prior host/QEMU/board evidence retains its original provenance. This is acceptance of the installed result, not a newly recorded individual-case test or timing measurement.
Each shell surface SHALL distinguish loading, empty, stale, failure, and cancellation where those states apply, using short text and a next gesture or contextual action. Focus and pressed states SHALL have a non-color cue; a failed launch SHALL retain the drawer or Home recovery.
Grounding: operator acceptance and explicit additional-proof waiver in docs/evidence/coherent-shell/operator-closeout-2026-10-10/README.md; prior host/QEMU/board evidence retains its original provenance. This is acceptance of the installed result, not a newly recorded individual-case test or timing measurement.
The shell userspace SHALL present a consistent visual frame and navigation around the app-card interaction when that capability is available. When it is unavailable, it SHALL state that visual cards are unavailable and retain a safe task/drawer route; it SHALL NOT portray metadata as a live app surface or silently replace a failed live deck with a second Home design.
Defines a bounded, privacy-aware way for the handheld shell to preview, revisit, act on, and dismiss system and application notifications.
Grounding: operator acceptance and explicit additional-proof waiver in docs/evidence/coherent-shell/operator-closeout-2026-10-10/README.md; prior host/QEMU/board evidence retains its original provenance. This is acceptance of the installed result, not a newly recorded individual-case test or timing measurement.
The shell userspace SHALL show a brief preview for an eligible new event and retain it in a reachable history until dismissal or expiry. The top-edge shade SHALL expose Notifications and indicate pending events; a preview SHALL open its event when tapped. The history SHALL show source, time, readable summary, and whether an action remains available; a trusted known app MAY show its resolved desktop-entry icon beside its text name, while unknown or privacy-redacted sources SHALL use a neutral icon and label. Dismissing a preview SHALL NOT silently erase history.
Grounding: operator acceptance and explicit additional-proof waiver in docs/evidence/coherent-shell/operator-closeout-2026-10-10/README.md; prior host/QEMU/board evidence retains its original provenance. This is acceptance of the installed result, not a newly recorded individual-case test or timing measurement.
The shell userspace SHALL offer only actions whose target is currently available and SHALL distinguish opening an event from dismissing it. A failed action SHALL leave the event reachable with a short error and Retry or contextual dismissal route. Dismiss All SHALL require a clearly labeled control and SHALL NOT dismiss an ongoing critical system event.
Grounding: operator acceptance and explicit additional-proof waiver in docs/evidence/coherent-shell/operator-closeout-2026-10-10/README.md; prior host/QEMU/board evidence retains its original provenance. This is acceptance of the installed result, not a newly recorded individual-case test or timing measurement.
The shell userspace SHALL hide sensitive body text in unsolicited previews by default, showing a neutral source and summary until the person opens history. It SHALL distinguish ordinary, important, and critical events: ordinary previews SHALL not take keyboard focus; important previews SHALL remain non-modal; critical events SHALL explain the immediate condition and preserve a visible recovery route. Unknown senders SHALL use ordinary priority with a hidden body.
Existing grounding: docs/evidence/shell-real-touch-apps/README.md records
physical Apps/Terminal/Monitor interaction and a legacy Home-to-Terminal
recovery confirmation. docs/evidence/shell-real-touch-system/README.md
records touch followed by reboot and return to the shell. Exact confirmation
labels and Cancel are not individually camera-legible; earlier injected menu
and failure-path evidence is separately labeled in docs/evidence/shell-features/
and docs/evidence/shell-virtual-touch.txt. These observations ground the
installed development bar, not the gesture-led final session.
Grounding: operator acceptance, exact installed/runtime identity and the additional-proof waiver are recorded in docs/evidence/coherent-shell/operator-closeout-2026-10-10/README.md and docs/evidence/coherent-shell/combined-board-candidate-2026-10-10/README.md.
In the final normal session, the shell SHALL keep live-card Overview and pinned Home distinct. A purely upward bottom-edge gesture from an app or transient shell surface SHALL reach Overview. An upward gesture from Overview’s bottom navigation area SHALL reach pinned Home without closing running apps; a new upward gesture from Home SHALL reveal All apps with named Terminal and Monitor actions. Swiping a card itself upward SHALL retain its close action. An app-entry gesture curving sideways without lifting, or a horizontal gesture from anywhere within the qualified bottom band, SHALL select an adjacent running app for activation on qualified release while preserving deck order, privacy and existing app/keyboard ownership. The top-edge downward gesture SHALL reveal notification history and Settings. Bottom-edge escape and explicit close/return controls SHALL retain recovery from shell contexts. The shell SHALL NOT synthesize a universal Back key into arbitrary apps; qualified side-edge Back and the general at-down arbiter remain the separate successor’s requirements. Normal composition SHALL NOT retain permanent Apps, Windows, Keyboard, System, Back or Home controls. Help SHALL provide gesture guidance and a deliberately opened large-labeled navigation aid. The old persistent-bar session SHALL remain a separately selectable rollback with its existing Apps, Windows/Home, Keyboard and System controls, at least 56-pixel-high targets and primary controls at least 128 pixels wide on the 568-pixel panel; its empty-window/Home/Back recovery and keyboard controls retain their existing behavior.
Settings SHALL offer reboot and power-off only after a second confirmation
surface that names the action and includes Cancel. A failed or denied system
action SHALL show the failure and leave a route to the shade or Home. The
session user SHALL have authority only for those two explicit systemctl
operations; no general passwordless command or root shell is part of the
control.
systemctl command fails or is deniedevemu/uinput event activates a block in the rollback barArchived change · Archived
Snapshot 5836ef1d113d · 2026-10-17 08:22 UTC
Closed recordClosed. Landscape HDMI and the keyboard-case landscape panel both work; Home and Drawer keep native icon size with more columns, Wi-Fi and the theme chooser reflow, and the dock grows to six slots on wide screens. The dock shrink path and the 1232x568 dock are host-only.
The accepted HDMI shell uses portrait rotation. Its success does not establish
usable Home, navigation and Settings in landscape. Preserve original HDMI
tasks 5.1–5.4 explicitly under the operator-authorized scope split on 2026-10-09. The automatic
switching proposal closes separately. Geometry work already belongs to
the archived the-shell-adapts-to-output-resolution; reuse it rather than create a competing
implementation owner.
Non-goals: changing accepted portrait defaults without instruction, redesigning every shell screen, adding new hotplug or input drivers, HDMI audio/CEC, or claiming host renders prove real monitor interaction. Host geometry work needs no board; landscape qualification requires the single board/serial reservation. The operator waived a monitor photograph, while observations and native captures remain required.
The operator asked that, in the keyboard case, the panel be rotated 90 degrees counterclockwise and that this change’s layout work be done for it. Add a build-time panel orientation (portrait stays the default), a landscape panel profile, configure handling for a whole output whose size changes, 1232×568 layouts for every shell surface, rotated touch and gestures, and physical proof on the second board, with an HDMI regression check at the end (tasks 8.1–8.7).
None.
runtime/shell: add the explicit minimum usable HDMI landscape requirement,
and a selectable landscape orientation for the built-in panel.Future work owns the landscape Sway qualification profile, the remaining geometry
and layout integration, and physical evidence. Shared responsive code/tasks
are supplied by the archived the-shell-adapts-to-output-resolution; this proposal owns their
HDMI landscape integration gate. Automatic HDMI implementation at 6b4fe555, accepted and recorded at
a55e5a55, is a prerequisite, not landscape evidence. This proposal changes planning only.
Original HDMI group 5 remains unfinished. The accepted monitor uses 1280×800
with transform 90 and a touchscreen trackpad. That proves portrait HDMI,
not normal-transform landscape. Shared whole-output configure, Home/Drawer
reflow, Settings transforms and hit-testing already belong to
the archived the-shell-adapts-to-output-resolution; its accepted portrait
fill and target evidence is available for reuse. This proposal owns the transferred density, Wi-Fi/theme geometry
and dock follow-ups in tasks 7.1–7.3. None is completed by this transfer.
Qualify minimum usable Home/navigation/Settings in landscape and preserve every original task 5.1–5.4. No full redesign, default portrait change, new hotplug driver or replacement responsive implementation is implied by this proposal.
Layers: Nix/Sway output configuration and Rust/card-shell userspace geometry. The combined runtime uses exclusive outputs on one CRTC; keep that constraint. Use a separately selected landscape qualification profile, preserving accepted portrait defaults until an explicit instruction changes them. Choose an actual supported EDID mode rather than assuming the historical 720p example is selected. Reuse responsive production paint and hit-test paths and fixtures. The original literal/scaling audit includes Wi-Fi and must not be silently dropped merely because a shared proposal deferred it.
Host renders establish fixture behavior only. A real monitor can expose density, focus, input mapping and output configure differences. Preserve native captures and operator observations as separate evidence classes. No monitor photograph is required. Do not infer landscape interaction from accepted portrait use.
Original commands and separate board gate are retained in tasks. Branch
proposal/hdmi-landscape-successor-2026-10-09, original base ba5217ca.
Owned paths: only this proposal directory. Worktree ownership is recorded in
the integration evidence; no build slot or board reservation is involved.
The operator directed: “we dont need a settings button to reboot into hdmi now that hot swap works and yeah we want landscape layout support as a new proposal and land hdmi”. This proposal is authorized for landing as a plan. Original HDMI tasks 5.1–5.4 transfer here; task 5.1 explicitly uses the working automatic exclusive-output arrangement and retains its original rollback build command, adding the shipping mainline bundle proof. All original landscape layout and physical requirements remain open. No landscape source implementation, new board trial or installed profile is claimed.
Proposal integration base is a55e5a55838b150479bf97c43b7406eda7e04a05; the
original draft base was ba5217ca. Only this proposal directory is owned.
The operator authorized moving icon/text sizing, Wi-Fi/theme layout and dock layout into this proposal: “you can move those into the landscape proposal”. Original responsive tasks 6.3–6.5 are preserved as 7.1–7.3, all unchecked. Home/Drawer column reflow alone is not a density scale; keep the existing portrait geometry intact while adding a deliberate actual-output sizing policy. Wi-Fi and the theme chooser need a real reflow or uniform centered scale, replacing their independent non-uniform scaling. Decide dock slot reflow from actual layout/hit-target evidence rather than merely stretching four slots. Reuse the shared responsive owner’s existing geometry paths. No implementation, new installed profile or physical qualification is claimed.
Responsive physical fill and Home/All Apps/Settings target checks are accepted
for the normal 800×1280 portrait-HDMI arrangement and committed in
docs/evidence/shell-responsive/board/acceptance-2026-10-09/. The archived
responsive change supplies the shared implementation and this bounded proof;
all seven implementation/physical tasks here remain open. No portrait
observation closes this proposal’s separate normal-transform landscape gate.
Operator: “in this configuration the board should really be rotated 90 degrees
counterclockwise … we should do it here (you can ignore hdmi … we can test
it at the end tho)”. Camera frames from the bench (the camera sits at the
device’s top edge, opposite the person at the keyboard) fixed the direction:
a runtime transform 90 put the terminal upright for the camera and upside
down for the typist; transform 270 is upright from the keyboard side.
The orientation is a build-time option, as hdmiTransform already is, with
portrait kept as the default because accepted portrait defaults change only
on explicit instruction. A board in the keyboard case runs the landscape
profile. A runtime toggle in Settings is not part of this change.
Landscape HDMI (task 5.1, 2026-10-14) is the flake output
k230-mainline-drm-shell-landscape-hdmi (boot files
kernelMainlineDrmShellLandscapeHdmiBootFiles): the landscape panel profile
with k230.shell.hdmiTransform = "normal". Sway takes the monitor’s
EDID-preferred mode, so no mode is assumed (the operator’s monitor offers
1280×800). The display controller has one CRTC, so the panel and HDMI are
mutually exclusive outputs: plugging the cable moves the session to HDMI-A-1
and unplugging returns it to DSI-1, with no reboot and no Settings button.
While HDMI is active the glass is a trackpad, so the touch calibration matrix
for normal is the identity.
The shell’s landscape layout (help::wide) applies to every output at least
1.6 times as wide as it is tall. Before 5.2/5.3 it also required a short
output, so a 1920×1080 monitor fell back to the portrait pages, stretched
non-uniformly, with Settings running off the bottom.
The shared layout work (5.2, 5.3, 7.1–7.3) is done once, against actual output geometry, so it serves both 1232×568 on the panel and HDMI landscape. The panel’s 568×1232 portrait renders stay byte-identical, guarded by the existing pixel-identity test.
Original HDMI tasks 5.1–5.4 are preserved below with their proof commands.
All implementation/physical gates remain unchecked. The operator authorized
this successor on 2026-10-09 and dropped the obsolete Settings reboot path.
Task 5.1 now selects landscape through the working automatic arrangement. Implement shared geometry
through the archived the-shell-adapts-to-output-resolution and reuse its
committed evidence,
while retaining this proposal’s separate physical landscape gate.
Coordinator cross-reference (2026-10-01):
the-shell-adapts-to-output-resolution
owns output configures, Drawer/Home column reflow, Settings transforms and matching
hit-testing. Its host implementation and paired fixtures are recorded there;
its completed tasks 6.1/6.2 record accepted portrait-HDMI fill and targets. This proposal’s
tasks 7.1–7.3 own density, Wi-Fi/theme geometry and dock follow-ups. Use that work for 5.2/5.3 below rather than implementing it twice.
These links do not complete this proposal’s HDMI hardware or landscape gates.
HDMI-A-1 qualification
profile to the Sway configuration (supported EDID mode, for example
1280x720, transform normal), preserving the accepted portrait default.
Record the combined runtime’s one-CRTC, mutually exclusive outputs in
design.md; use automatic cable switching, without a reboot button.
Verify the legacy rollback configuration with nix build .#nixosConfigurations.k230.config.system.build.toplevel and the shipping
mainline profile with nix build .#kernelMainlineDrmShellBootFiles.
Done 2026-10-14 (host): k230-mainline-drm-shell-landscape-hdmi and
its boot files kernelMainlineDrmShellLandscapeHdmiBootFiles
(landscape panel, hdmiTransform = "normal", EDID-preferred mode); the
one-CRTC exclusive outputs and automatic cable switching are recorded in
design.md. At master 339fb0f6 these built:
.#nixosConfigurations.k230.config.system.build.toplevel
(hpab8g78…), .#kernelMainlineDrmShellBootFiles (8xvklh2x…) and
.#kernelMainlineDrmShellLandscapeHdmiBootFiles (4zml1kip…). The
landscape-HDMI system (gs1daqsn…) is installed on the board, its Sway
config reading output HDMI-A-1 transform normal and calibration
1 0 0 0 1 0.nix/rust-shell-client/src/lib.rs’s
DESIGN_ASPECT and the direct 568.0/1232.0 literals it and
render.rs/wifi_ui.rs use for coordinate scaling, so they derive
from the actual configured output geometry instead of a compiled-in
constant, without changing the existing portrait behavior when the
output really is DSI-1 at 568x1232 (existing tests must keep
passing unchanged). Verify with cargo test and
cargo clippy --all-targets for nix/rust-shell-client.
Done 2026-10-14 (host): layout is chosen from the configured output’s
own size. help::wide (shared by Settings, Wi-Fi, themes, the shade,
folders and Help) now selects the real-pixel landscape layout for every
output at least 1.6x as wide as tall; before, a 1920x1080 monitor fell
back to the 568x1232 artwork scaled non-uniformly. The 568/1232
literals remain only as the portrait artwork’s reference size, scaled
to the actual surface, and DESIGN_ASPECT only guards against a
keyboard exclusive-zone squish. Portrait tests pass unchanged; six
tests that pinned 1920x1080 as portrait now use 1280x1024 for the
centred-column case. cargo test 510 + 22 pass; clippy adds no
warnings. Renders: docs/evidence/hdmi-hotplug/landscape/host-renders/.nix/rust-shell-client/src/home_grid.rs, navigation.rs) not
visually broken (overlapping, off-screen, or unreachable elements) at
a landscape aspect ratio, without necessarily redesigning the layout
for landscape — “usable,” not “redesigned,” is the bar for this
change. Verify with new unit tests exercising the same functions at
a landscape geometry (e.g. 1280x720) alongside the existing
568x1232 cases, cargo test.
Done 2026-10-14 (host): Home’s grid and the Drawer tests now run at
1280x800 and 1280x720 as well as 1920x1080, every tile on-screen and
hit-testing to itself; host renders of Home, Drawer, Settings, Wi-Fi,
themes, the shade, a folder, Power and Help at 1280x800 and 1920x1080
show nothing overlapping, off-screen or unreachable
(docs/evidence/hdmi-hotplug/landscape/host-renders/).docs/evidence/hdmi-hotplug/landscape/.
Done 2026-10-14 (board grim + operator): grim -o HDMI-A-1 captures of
Settings and Home at 1280x800 on master 6e963323, and the operator’s
“Both look right” for the monitor
(docs/evidence/hdmi-hotplug/landscape/board/). Routes were opened over
the shell socket, not by touch; no monitor photograph (waived).openspec validate the-hdmi-shell-works-in-landscape --strict;
publish the reviewed successor without claiming implementation.Planning validation passed 2026-10-09. Implementation and physical proof remain open.
The operator authorized moving the responsive proposal’s original tasks 6.3–6.5 here. These remain unperformed, with their requirements retained.
crate::reflow_columns;
ICON_SIZE/ROW_HEIGHT/tile margins stay the panel’s own native
pixel size at every surface size, unlike Settings’ content column.paint_wifi’s and the theme chooser’s existing non-uniform
cr.scale(width/568.0, height/1232.0), which this change’s Settings
content transform deliberately excludes and leaves as-is.DOCK_SLOTS, deliberately left fixed at 4 by the responsive
implementation) using the archived responsive 6.1/6.2 evidence and once this
proposal’s landscape 5.4 evidence is in hand to verify against.
Done 2026-10-16 (docs/evidence/hdmi-hotplug/landscape/wide-dock/).
The dock gets one slot per grid column, capped at what the icon budget
leaves after one full page, and never fewer than 4
(home_grid::dock_slots): 4 on the portrait panel, and 6 at 1280x800
and 1232x568. HomeLayout::fit_dock adds empty slots when the surface
widens. When it narrows, items move into free slots or onto the grid,
so no pinned item is hidden. Host: cargo test passed (547 lib tests
plus all integration targets, 0 failed), and the portrait Home render
is byte-identical. Board (injected pointer plus native grim, HDMI
1280x800, system zqy2i8w0…): six slots shown, Video dragged into
slot 6 and persisted, and a click on slot 6 launched it. The shrink
path and the 1232x568 dock are host-only.Operator design answers, 2026-10-14 (still to implement and verify; none is done):
docs/evidence/hdmi-hotplug/landscape/wide-reflow/).
Open: the operator’s look and a tap on a grid card on the board.
Board 2026-10-15 (system 7n025h1f…, HDMI 1280x800): the operator said
“it works and it feels pretty good”; the shell log records no grid tap, so
the tap stays open.Closure, 2026-10-16:
ICON_SIZE (80) and ROW_HEIGHT are fixed constants, and only the column
count follows the surface (home_grid::columns_for_width, and
navigation::columns_for_width for the Drawer). Host tests
columns_for_width_matches_the_reference_at_568_and_grows_for_hdmi and
icon_sizes_are_in_the_finger_sized_band cover it. A board native grim
at 1280x800 shows Home’s Video icon at the panel’s size, with the 9-column
layout "columns":9 in the saved home.json
(docs/evidence/hdmi-hotplug/landscape/wide-dock/board-six-slots-1280x800-grim.png).
The Drawer at that size is host-only: an injected bottom-edge mouse swipe
does not open it on HDMI.
The 1232x568 host renders are in docs/evidence/panel-landscape/host/. The
spec delta now states the decision instead of a density scale.Operator, 2026-10-13, with the second board in its keyboard case on the bench: “notice that in this configuration the board should really be rotated 90 degrees counterclockwise we already had the ‘make that layout work’ card we should do it here (you can ignore hdmi i am sure it will be fine we can test it at the end tho)”. Tasks 5.2, 5.3 and 7.1–7.3 are the shared layout work; complete them here against the panel’s 1232×568 geometry as well as HDMI.
k230.shell.panelTransform option (normal, default, or
270) driving the output DSI-1 line, and a landscape panel system
plus its boot files and SD image as separate flake outputs. The default
system’s toplevel derivation SHALL be unchanged. Verify with nix eval
of the default toplevel drvPath against master and nix build of the
landscape boot files.
Done 2026-10-13 in 0804c0aa: the default toplevel drv was
lhdphdj84vyngfcflhvkpdxny2dxljz5… on both master and the change, and
.#kernelMainlineDrmShellLandscapeBootFiles and .#sdImage-landscape
built. Later shell and device-tree fixes on this branch change the
default system deliberately.shell-ui accept a whole-output configure whose output size
is learned late or changes at runtime (rotation), instead of rejecting
it and drawing nothing, while still rejecting a keyboard exclusive-zone
squish. Verify with new unit tests and cargo test.
Partial 2026-10-13: frame_bytes now accepts a 568 px tall frame (the
board logged home-configure-rejected before), with
frame_bytes_accepts_the_landscape_panel. Open: a size change at runtime
(update_output is still empty).
Done 2026-10-14 (host unit tests; no Wayland or board run): the
accept/refuse decision is now a pure function,
configure_acceptable(outputs, w, h) (a bounded size that keeps the
design aspect or equals a known output; a keyboard exclusive-zone
squish is neither), and a configure that is refused is remembered per
surface (RejectedConfigures). new_output and update_output now
re-offer every remembered configure that the current output sizes make
acceptable, so a size learned after the first configure, or changed by a
rotation, lays the surface out instead of leaving it undrawn; a squish
stays refused. New tests in lib.rs:
a_late_output_size_accepts_the_whole_output_configure,
a_runtime_rotation_re_lays_out_in_both_directions and
a_keyboard_exclusive_zone_squish_is_still_refused. The Wayland wiring
in main.rs (apply_configure, retry_rejected_configures) is
compile-checked and covered only through that decision function; a
rotation on the board (8.5) remains the observation of it.cargo test, cargo clippy --all-targets
and reviewed 1232×568 host renders.
Partial 2026-10-13: Home (two compact rows, so 2-row widgets fit; also
fixed the unbounded page growth that OOM-killed shell-ui), Shade
(the sheet keeps one notification row) and Help (two columns). Host
renders add 1232×568 plus Shade, Power and Help; every portrait and HDMI
render is byte-identical to 0804c0aa. cargo test 473 passed; clippy
reports 65 warnings, the same as the base. Reviewed: Home, Drawer,
Settings, Shade, Power, Help, keyboard. Open: Wi-Fi pages, the theme
chooser, the folder overlay, and notifications with real items.
Partial 2026-10-13 (Settings controls, host evidence only): at 1232×568
Settings now lays its rows out in three columns (Wi-Fi, Brightness,
Volume; Keyboard, Motion, Key backlight; Power with its confirmation),
so Keyboard, Motion, Key backlight and the Power rows fit on the panel
with no scroll. Taps and slider drags map through the same per-column
offset as the paint (new unit tests: every row’s rect lies inside
1232×568, a tap at each row’s centre hits that row, with and without the
Key backlight row). Portrait and HDMI renders are unchanged. Also fixed
the Keyboard row’s hit band, which pointed at the Volume row. On the
board 2026-10-14: a native grim shows all three columns, and an
injected tap toggled Key backlight (settings-three-column-grim.png,
settings-key-backlight-off-injected.png in
docs/evidence/keyboard-base/shell/board/). The Wi-Fi and theme
sub-pages are untouched.
Partial 2026-10-14 (host evidence only): the remaining listed surfaces
now lay out at 1232×568. Wi-Fi (list, entry with and without the
240 px keyboard, rejected-password banner, saved network, open
network, connecting, forget confirmation) was painted through a
non-uniform 568×1232 scale, which squashed every glyph; it now has a
two-column real-pixel layout (wifi_ui::layout, read by both the paint
and wifi_ui::hit). The theme chooser stacked two carousels that need
about 1230 px; it now sits side by side with a smaller theme carousel
(theme_ui::chooser_layout, THEME_GEOMETRY_WIDE), each carousel
clipped and hit-tested to its own half. The open folder shows eight
member tiles per row in two rows (16 members, as many as the portrait
card holds) in a card that starts below the compositor’s top band
(home_grid::folder_columns). The shade keeps its header and both
sliders in a left column and gives the notification list the full
panel height beside them, so four rows are visible at once
(service_ui::shade_layout); swipe-to-dismiss, scroll, close-drag
zones, Dismiss all and Settings read the same layout. New tests assert
every control’s rect lies inside 1232×568, its tap at the centre hits
it, and rects do not overlap
(every_wide_wifi_*, the_wide_connecting_and_forget_*,
the_wide_chooser_*, a_tap_at_the_centre_of_each_wide_carousel_*,
the_wide_folder_overlay_*, every_wide_shade_control_*,
the_wide_shade_scrolls_*). Host renders are committed in
docs/evidence/panel-landscape/host/ (render_landscape_surfaces
example; the shade renders there and in
docs/evidence/keyboard-base/shell/host-renders/ were regenerated, the
only renders that changed). Every other 1232×568, portrait and HDMI
render, and all 568×1232 renders of the new surfaces, are
byte-identical to 6aa0795d. cargo test: 572 passed (558 at the
base) and 1 failed, the same
responsive_pixel_identity::drawer_568x1232_matches_the_committed_evidence_exactly
that fails on the base, which this change does not touch; clippy: 65
warnings, identical to the base. Left open: this task stays unticked
because its cargo test verification is not clean on the base’s own
failure, and because the native grim captures of Wi-Fi, the theme
chooser, the folder overlay and the shade with notifications belong to
8.5; folder renaming under the 240 px keyboard hides the member tiles
(the card cannot rise above the top band).
Done 2026-10-14: the drawer failure was a stale PNG. git bisect on
that test found 3a1a3e51, which deliberately themed the drawer’s
search field and did not refresh docs/evidence/shell-responsive/ drawer-568x1232.png; it is regenerated (README there). cargo test --no-fail-fast: 573 passed, 0 failed. With every listed surface laid
out and reviewed at 1232×568 on the host, 8.3’s own verification is
met; the native captures and the folder-rename limit stay with 8.5.docs/evidence/panel-landscape/README.md). Exercised: bottom-edge
swipe on Home → Drawer, bottom-edge swipe from the Drawer → card
overview, top-edge pull → Shade, taps on the drawer search field and the
landscape keyboard. This needed cs_fit_card: the card shell never
started at 1232×568. The operator’s finger then showed the
GT9895’s X range is 1080, not 1024 (touch-range.md). The device-tree
correction is committed; its booted proof belongs to 8.5.grim captures of each surface in 8.3 and a camera photograph from the
keyboard side under docs/evidence/panel-landscape/ (physical: native
capture plus camera).
Partial 2026-10-13: native captures and one camera frame are committed,
but from a switch-to-configuration test trial, not a booted landscape
image, and without the new device tree. Installed and booted at 09:40
CDT: device tree 1080, no calibration matrix, services active, native
Home capture (board/installed-home.png). Open: the per-surface native
captures and camera frame again on the installed image, after the
operator’s glass pass.
Drawer/shade jank on the installed image was the compositor’s
per-layer software rotation (3.5 fps vs portrait’s 10.4 fps); the
landscape profile now uses the rotate-once renderer (8.7 fps) and is
reinstalled (rotation-performance.md; operator: “plenty fast now”).
2026-10-14, installed image 9lp7f072…: native captures of the
Drawer, Settings, power sheet, Help, shade with four notifications,
Wi-Fi, a saved network and the theme chooser (the last three opened by
injected taps), plus a focused terminal (board/installed-*.png).
Then Home with a folder and the Battery widget, the open folder, and
the on-screen keyboard over Drawer search, which exposed and now
verifies a fix: wvkbd’s landscape height (-L) was unset, so a 120 px
keyboard sat under a 296 px reservation (system s53ywx90…). Open: the
camera frame.
Done 2026-10-14: native captures of every 8.3 surface on the installed
image are committed. The camera photograph is waived by the operator
(Operator, 2026-10-14: “waive the camera pics”.); the bench webcam could not see the panel.9lp7f072…: after being
asked to open Settings and an app, type on the keyboard and return
Home with a real finger, the operator reported “real finger check
worked fine”. Operator report only; no camera frame of it.DSI-1 disconnected, and the card shell’s restore() committed a
transaction against the half-destroyed output (NULL scene_output).
Fixed in nix/card-shell/adapter.c. On the board, a forced
card0-DSI-1/status off during the overview no longer crashes Sway
(injected, sysfs; docs/evidence/hdmi-hotplug/landscape/teardown-crash.md).
Done 2026-10-14 on the fixed build (physical: operator plus native
capture). Plugging in moved the shell to HDMI-A-1 at 1280x800,
transform 90, as before, and the HDMI touchpad relay appeared. Unplugging
brought DSI-1 back at transform 270. Sway kept the same PID.
Operator: “yeah it’s good to go”. Captures and log are in the same
evidence file.The stage-1 boot splash logo stays portrait in this change (U-Boot draws it before any compositor); a landscape splash image is out of scope unless the operator asks for it.
Host implementation proof: cargo test --offline --manifest-path nix/rust-shell-client/Cargo.toml and cargo clippy --all-targets --manifest-path nix/rust-shell-client/Cargo.toml, plus reviewed native-portrait and HDMI host
render fixtures. Physical layout/hit-target acceptance remains task 5.4.
Planning proof: openspec validate the-hdmi-shell-works-in-landscape --strict.
The system SHALL offer a qualified landscape HDMI configuration in which Home, navigation and Settings remain visible, reachable and correctly hit-tested, while preserving the existing portrait panel behavior. The shell SHALL derive coordinate scaling from actual configured output geometry. Reuse the responsive shell capability’s implementation without replacing its existing task owner.
Home and Drawer SHALL keep the panel’s native icon and text size on every output, and a wider output SHALL add grid columns instead of enlarging icons (operator decision 2026-10-14: “Keep panel size, more columns”). Wi-Fi and the theme chooser SHALL use a real wide reflow (columns taken from the surface, theme cards in a grid) instead of a non-uniform stretch. On a wide output the dock SHALL offer more than four slots, one per grid column, within the icon budget that keeps a full page plus its dock resident; the extra slots stay empty until apps are pinned, and returning to a narrower output SHALL NOT hide a pinned item.
The system SHALL offer a build-time panel orientation for the built-in
568×1232 DSI panel. Portrait (transform normal) SHALL remain the default.
A landscape profile SHALL rotate the panel output 90 degrees counterclockwise
as seen by a person typing on the attached keyboard case (Sway
transform 270), giving a 1232×568 logical output. In that profile the
shell’s own surfaces (wallpaper, Home and dock, Drawer, shade, Settings
including Wi-Fi and the theme chooser, the on-screen keyboard, notifications
and the power sheet) SHALL accept the whole-output configure, lay out without
overlapping, off-screen or unreachable controls, and hit-test against the
same rotated geometry. Touch input SHALL map to the rotated output, and the
edge gestures SHALL follow the rotated edges. The HDMI output behavior SHALL
be unchanged by the panel orientation.
Archived change · Archived
Snapshot 5836ef1d113d · 2026-10-17 08:22 UTC
Closed recordReview the archived record and cited scope
Plugging in HDMI can leave the monitor dark. On 2026-10-16, after about two
hours of uptime, the operator plugged in the HP 27wm and saw nothing. The
compositor could not allocate a scanout buffer for any mode from 1920x1080
down to 1280x800: every attempt logged Failed to create DRM dumb buffer: Cannot allocate memory. It fell back to 1280x720, which the monitor did not
show.
A power-key wake 60 s later did get a 1280x800 buffer, by chance. The same allocation failures appear at boot (11:52:57 the same day), where 1920x1080 always fails.
The kernel has no CMA, so every scanout buffer must come from the page allocator as one physically contiguous block:
/proc/buddyinfo showed two free 4 MiB blocks and none of
2 MiB.Fragmentation grows with uptime, so plug-in grows less reliable the longer the handheld runs.
CMA and DMA_CMA with a 64 MiB default
area. Contiguous scanout buffers then come from a reserved pool that
ordinary movable pages may borrow while it is free.output HDMI-A-1 to 1280x800, the mode the shell has been
accepted and tuned at. With CMA, 1920x1080 would become allocatable and Sway
would pick it as the monitor’s preferred mode. That would roughly triple the
per-frame CPU work of the Pixman rotation pass, and 1080p over this DSI link
is unproven. A monitor without 1280x800 keeps Sway’s own preferred-mode
choice.Needs a kernel rebuild and a reboot. The final proof needs the operator to
plug the cable in after hours of uptime. Host checks: the kernel config
contains CONFIG_DMA_CMA=y and CONFIG_CMA_SIZE_MBYTES=64, and the system
closure builds.
The compositor allocates scanout buffers through wlroots’ DRM dumb-buffer
allocator. The canaan DRM driver backs those buffers with DMA-coherent
memory. Without CMA, that memory comes straight from the buddy allocator, so
the largest contiguous block is MAX_PAGE_ORDER (4 MiB at 4 KiB pages), and
any block is only available while memory is unfragmented.
CMA_SIZE_MBYTES), not on the command line. The boot files carry their
own bootargs.txt, and keeping the size in the kernel’s config means
every boot path gets it. 64 MiB holds a triple-buffered 1280x800 XRGB
swapchain (12 MiB) plus cursor and client buffers with room to spare.
While unused, the pages remain available for movable allocations.framebuffer@10000000). The kernel places the default CMA area
through memblock, which avoids reserved regions. The boot log will show
where it landed.CMA, DMA_CMA and CMA_SIZE_MBYTES=64 in
nix/kernel-mainline-drm.nix, and pin output HDMI-A-1 mode 1280x800 in
nix/shell.nix. Verify by building the board boot files
(nix build .#kernelMainlineDrmShellLandscapeHdmiBootFiles) and by checking
the built kernel’s config for CONFIG_DMA_CMA=y and
CONFIG_CMA_SIZE_MBYTES=64.
Done 2026-10-16: docs/evidence/hdmi-plug-cma/board-2026-10-16.md.bg #000000 solid_color from the HDMI-A-1 output line in
nix/shell.nix. On a 2026-10-16 hotplug, Sway’s swaybg for HDMI-A-1
covered the shell’s wallpaper. Both are background-layer surfaces, and
swaybg’s black stacked on top; stopping that swaybg showed the vinyl
wallpaper. Verify by building the board boot files and checking the built
sway config has no bg on that line, then on the board: replug HDMI and
capture the wallpaper with grim.
Done 2026-10-17 (board, operator replug): no swaybg runs; the wallpaper
is visible on HDMI after a replug. See the evidence file, section 1.2.CmaTotal/CmaFree from /proc/meminfo.
Done 2026-10-16 (board, soft reboot 15:40): cma: Reserved 64 MiB,
CmaTotal: 65536 kB, CmaFree: 63016 kB; same evidence file.With the combined mainline device tree, the system SHALL switch the active output to HDMI when a monitor is plugged in and return to the panel on unplug, without a reboot, on every plug however long the system has been running. The monitor SHALL be driven at 1280x800 when it offers that mode. It SHALL preserve the accepted HDMI portrait rotation and trackpad input, and restore direct touch when the panel becomes active again. The separately qualified HDMI-only and panel-only boot trees remain available for recovery; their presence does not require a manual Settings reboot control.
Grounding: docs/research/hdmi-hotplug.md §5 names three concrete,
schematic- and source-grounded blockers this goal must clear: the physical
HDMI hot-plug-sense pin is wired only to the LT9611 itself
(HDMI_HPD→HPD_GPIO2, schematic sheet “HDMI+ETH”), not to any
independent K230 GPIO, so detecting a plug event at all requires the LT9611
to already be a live, probed I2C device while the panel device tree is the
one running; the shared GPIO24 reset net (see “DSI lanes are shared wiring”
above) forbids independently resetting either chip after their initial
power-on reset; and canaan_dsi.c has no live panel/bridge re-attach path
in the surveyed baseline (see the HDMI-only qualification requirement
above). The runtime re-plan keeps both consumers registered and uses two
exclusive encoders with 250 ms HPD work and generic polling as fallback,
rather than adding live re-attachment.
Touch retains both shared pins; their unknown electrical drive type is not
used as an assumption for shared-IRQ operation.
Grounding: observed 2026-10-09: the first combined trial established both visible
switching directions with trackpad on HDMI and direct touch on return. The
matching faster kernel trial was accepted by the operator: HDMI replug took
“couple of seconds”, panel return was “almost instant”. A later “it works
great land it” confirms the requested cable/navigation checks; the qualification
records that question context rather than inventing per-gesture traces.
Read-only state before and after acceptance retains boot ID
cff529ad-6aa6-4a31-b9af-337bbc783521, enabled HDMI at the accepted portrait
transform and virtual touchpad. See
docs/evidence/hdmi-hotplug/live-switch/fast-runtime-operator-report.json,
fast-runtime-qualification.json and fast-runtime-qualified-state.json.
No-reboot switching works on this tested mainline arrangement. The matching
normal bundle is installed and ordinary autoboot is observed separately in
docs/evidence/hdmi-hotplug/live-switch/normal-hotplug-install-serial.json
and normal-hotplug-runtime-state.json. The separate
sampled HPD-to-connector ≤1s and HPD-to-enabled ≤3s targets remain unmeasured:
the bounded watcher captured no transitions. The operator explicitly deferred
precise latency measurement on 2026-10-09; no sampled result is claimed. See
docs/evidence/hdmi-hotplug/live-switch/closeout-2026-10-09.md.
Operator-visible approximate
timing is evidence for the 30s scenario ceiling, not those precise targets.
Grounding (2026-10-17): after 3 h 41 min of uptime with shell restarts and
theme changes, a plug allocated the 1280x800 scanout buffer 1.2 s after HPD
with no allocation failure, and the operator saw the shell on the monitor.
After the swaybg fix, a replug showed the wallpaper. The board side finished
within 2 s of HPD. The monitor’s own lock time, about 25–30 s after that on
one replug, is reported by the operator and not measured
(docs/evidence/hdmi-plug-cma/board-2026-10-16.md).
Archived change · Archived
Snapshot 5836ef1d113d · 2026-10-17 08:22 UTC
Closed recordClosed on operator acceptance; see evidence for waived captures and retained limits.
Without a working RTC, every boot starts the system clock at the kernel’s
compiled-in epoch until NTP catches up, which is wrong for anything that
timestamps files, logs, or notifications before the network is up — and is
simply wrong forever if there is no network. The on-chip K230 RTC is
already described in the device tree and status-enabled by default
(rtc@0x91000c00, compatible = "canaan,k230-rtc", no status override).
docs/research/board-capability-inventory.md finds the entire gap is a
single Kconfig line: drivers/rtc/rtc-k230.c already exists in our pinned
kernel source tree, but RTC_DRV_K230 defaults to n and our
structuredExtraConfig never sets it — instead setting only the unrelated
CONFIG_RTC_DRV_SUN6I=y (an Allwinner RTC this board does not have).
RTC_DRV_K230 so /dev/rtc0 (backed by the already-okay
device-tree node) appears.systemd-timesyncd’s existing
default behavior of writing NTP-corrected time back to the RTC when one
is present, and run hwclock --systohc at points where that is the
standard mechanism, so the wall clock a reboot sees reflects the last
known-good time.UNVERIFIED rather than inferring it from the DT node being
enabled, and the board test plan is written to distinguish the two cases
(warm reboot vs. a real power-off-and-wait).system/rtc: the system/ group already holds nixos-config, kernel
and console; wall-clock persistence is a person-observable capability
distinct from all three (it is not “the kernel boots,” it is not “there
is a NixOS closure,” and it is not “there is a console”) and gets its
own spec file, per the inventory’s own suggestion.None.
The kernel (nix/kernel.nix — one Kconfig line, in its own clearly
delimited hunk since feat/speaker is concurrently editing this same
file) and NixOS time configuration (nix/hardware.nix or nix/k230.nix).
No device-tree change — the RTC node is already enabled. Confirming
/dev/rtc0 exists, that hwclock -r reads a plausible time, and that a
warm reboot preserves it are hardware-only gates. Whether a full
power-off preserves it stays UNVERIFIED unless a backing supply is
documented on the schematic; this change does not claim otherwise.
The operator accepts this delivered functional scope and waives additional
capture-only acceptance gates. docs/evidence/proposal-closeout/2026-10-01/clock.md records the exact report,
prior evidence and limits. Its task dispositions supersede older statements
that these acceptance gates remain open; they do not claim new test runs.
See proposal.md. Grounding, read directly from the pinned tree’s own
unpacked source
(/nix/store/bjgv1xn5b66gbz2kxv2aqzr1szp7dk7c-linux-xuantie-k230-src at
the time of writing):
arch/riscv/boot/dts/canaan/k230.dtsi’s rtc@0x91000c00 node
(compatible = "canaan,k230-rtc") carries no status property at all,
which per the devicetree spec means enabled by default — already
confirmed in docs/research/board-capability-inventory.md.drivers/rtc/rtc-k230.c exists in this tree and matches that
compatible string.drivers/rtc/Kconfig’s RTC_DRV_K230 is tristate ... default n depends on ARCH_CANAAN — the one and only reason /dev/rtc0 does not
exist today.nix/kernel.nix’s structuredExtraConfig sets only
CONFIG_RTC_DRV_SUN6I=y today (an Allwinner part not on this board) and
no RTC_DRV_K230 line at all — checked directly against the current
file.services.timesyncd module
(nixos/modules/system/boot/timesyncd.nix, read from the pinned
nixpkgs source tree) is enabled by default
(default = !config.boot.isContainer) and needs no configuration from
this project; the actual write-back to /dev/rtc0 after a successful
NTP sync is systemd-timesyncd’s own built-in binary behavior
(periodic and at clean shutdown), not something a NixOS module option
configures — the Nix module only starts the daemon. This project’s part
is only making /dev/rtc0 exist for that daemon to find.Goals: /dev/rtc0 exists; hwclock -r reads a plausible time;
timedatectl reports RTC time alongside Local time/Universal time;
a warm reboot’s clock reflects the last known-good time rather than the
kernel’s compiled-in epoch.
Non-Goals: claiming the RTC block survives a full power-off — that
depends on whether this specific board’s RTC domain has a battery or
supercapacitor backing it, which is not documented anywhere in this
repository or in LILYGO’s published hardware pinmap/BOM. This change
explicitly marks that scenario UNVERIFIED rather than inferring
“DT node enabled” as “survives power-off.” Also non-goals: NTP server
configuration (networking.timeServers already covers this, untouched),
timezone/localtime handling.
okay by omission; adding an explicit status = "okay"; would be a
no-op restatement, not a fix. RTC_DRV_K230 = yes; (built-in, not a
module — the RTC is needed from very early boot for a sane clock before
any module-loading userspace runs, and this board’s kernel builds most
of its own SoC drivers in for the same reason). Kept in its own clearly
delimited hunk in nix/kernel.nix’s structuredExtraConfig, since
feat/speaker is concurrently editing this same file for audio
Kconfig.services.timesyncd’s existing default enablement, and add
one explicit hwclock --systohc unit rather than trusting only
systemd-timesyncd’s internal periodic write-back. time-sync.target
is the standard systemd synchronization point reached once the first
NTP sync completes; a small oneshot service ordered after it
(k230-rtc-sync.service) runs hwclock --systohc once per boot. This
makes the “NixOS uses it” contract this proposal asks for auditable
(a named unit, inspectable with systemctl status) rather than resting
entirely on systemd-timesyncd’s internal ~hourly write-back cadence,
which could leave a short reboot-to-reboot gap where the RTC never got
updated at all. Rejected: relying solely on systemd-timesyncd’s
built-in behavior — correct on its own terms, but with no local,
inspectable evidence in this repo that it actually ran on this board’s
/dev/rtc0, versus a named unit whose systemctl status and journal
entries are exactly that evidence.UNVERIFIED is the honest answer for full power-off, not a claim
either way. The inventory found no schematic or BOM reference to a
backing battery/supercap for this RTC domain, and this repository has
no prior board observation of a full power-off’s effect on the clock.
The combined board test plan’s RTC section is written to physically
distinguish “warm reboot” (this change’s actual claim) from “full
power-off and wait” (left UNVERIFIED unless that test is separately
run and its result recorded).hwclock --systohc running before the first NTP sync completes would
write a wrong time into the RTC] → ordering k230-rtc-sync.service after
time-sync.target (not merely after systemd-timesyncd.service starts)
is specifically to avoid this; time-sync.target is only reached once a
sync has actually completed.Enable RTC_DRV_K230, add the sync unit; cross-build the kernel and full
system closure. Install the built kernel to /boot and reboot (a kernel
config change). Physical acceptance: confirm /dev/rtc0, hwclock -r,
timedatectl, reboot, and hwclock -r again to confirm persistence
across the warm reboot. Rollback is reverting this commit; nothing else
about system time handling changes.
The operator accepts this delivered functional scope and waives additional
capture-only acceptance gates. docs/evidence/proposal-closeout/2026-10-01/clock.md records the exact report,
prior evidence and limits. Its task dispositions supersede older statements
that these acceptance gates remain open; they do not claim new test runs.
RTC_DRV_K230 = yes; to nix/kernel.nix’s
structuredExtraConfig, in its own clearly delimited, separately
commented block (no shared lines with feat/speaker’s audio
Kconfig edits). Proven:
nix build .#kernel --max-jobs 1 --cores 6 --no-link --print-out-paths
exited 0, producing
/nix/store/78cdif47ayqwv67m7crjpawfzy2mx3af-linux-riscv64-unknown-linux-gnu-6.6.36-xuantie
(build proof only) — one kernel derivation shared with the
backlight and Bluetooth Kconfig/driver changes.k230_rtc_read_time() also masked the day-of-month field with
0xf instead of 0x1f. Added nix/patches/k230-rtc-mday-mask.patch,
wired into nix/kernel.nix’s patches list. Proven:
nix build .#kernel --max-jobs 1 --cores 6 --no-link --print-out-paths
exited 0, producing
/nix/store/16qspvmvblal5q059y8p6zbsn1ynjcdy-linux-riscv64-unknown-linux-gnu-6.6.36-xuantie
(build proof), and confirmed on the board (hardware proof, task 4.1).systemd.services.k230-rtc-sync: a oneshot unit ordered
after time-sync.target, running hwclock --systohc, in
nix/hardware.nix (the real-hardware-only base; nix/k230.nix is
the shared hardware+QEMU base). Proven:
nix build .#nixosConfigurations.k230-coherent-shell.config.system.build.toplevel --max-jobs 1 --cores 6 --no-link --print-out-paths
exited 0, producing
/nix/store/152qrxpkagai2fahgyhkxq7sp8sk98n4-nixos-system-nixos-26.11.20260919.20b1ddd,
which schedules unit-k230-rtc-sync.service (build proof only).ls /dev/rtc0, hwclock -r, timedatectl, a reboot, then
hwclock -r again to the combined board test plan
(docs/evidence/backlight-bluetooth-rtc-board-test-plan.md), with
expected output and the failure signature for “RTC exists but does
not persist” (a reboot-to-reboot jump back to the kernel’s
compiled-in epoch) versus “no RTC at all” (/dev/rtc0 missing,
hwclock -r reporting no such device)./boot and reboot. Under the
reserved board lock, confirm ls /dev/rtc0, run hwclock -r and
timedatectl, reboot, and run hwclock -r again to confirm the
clock survived the warm reboot. Done, plus a second board finding
folded in: k230_rtc_read_time()’s day-of-month read mask was
0xf (should be 0x1f), dropping bit 4 — see
nix/patches/k230-rtc-mday-mask.patch and
docs/evidence/rtc/mday-mask-fix.md. Verified on the board: days
15, 16 (the bit-4 boundary), 26 and 31 all read back correctly,
and hctosys sets the correct time after a real cold reboot from
a freshly bootswapped /boot (not the kernel’s compiled-in
epoch). /proc/cmdline’s init= on that boot confirms the new
toplevel was actually running.The updated completed tasks describe actual acceptance, waivers and scope
transfer, not execution of the superseded protocols. See docs/evidence/proposal-closeout/2026-10-01/clock.md.
Historical checkpoint notes above that say physical gates remain open are
superseded by this record. Quantitative or individually unreported results
are not promoted to physical proof.
Proof: openspec validate the-clock-survives-a-reboot --strict; committed operator report;
python3 scripts/render_work_board.py --working-tree --output <snapshot.json>.
Expose the on-chip RTC to Linux and preserve a synchronized wall clock across warm reboots. Full main-power-removal retention is explicitly unverified.
The system SHALL expose the K230 SoC’s on-chip RTC as /dev/rtc0, and
hwclock -r and timedatectl SHALL report a plausible time from it.
Grounding: arch/riscv/boot/dts/canaan/k230.dtsi in the pinned Xuantie
kernel tree already carries rtc@0x91000c00 (compatible = "canaan,k230-rtc") with no status override, meaning enabled by default
per the devicetree spec; drivers/rtc/rtc-k230.c already exists in the
same tree, gated only by RTC_DRV_K230, which our
structuredExtraConfig never set — setting instead only the unrelated
CONFIG_RTC_DRV_SUN6I=y.
ls /dev/rtc0 on the boardhwclock -r or timedatectlThe system’s time, once synchronized (by NTP or by an explicit
hwclock --systohc), SHALL survive a warm reboot: the system clock
immediately after boot SHALL reflect the last known-good time rather than
resetting to the kernel’s compiled-in epoch.
Grounding: services.timesyncd is enabled by default in NixOS
(nixos/modules/system/boot/timesyncd.nix, default = !config.boot.isContainer) and writes a synced time back to a present RTC;
this change additionally runs hwclock --systohc in a
k230-rtc-sync.service unit ordered after time-sync.target, so the
write-back is both automatic and independently auditable.
Whether the RTC keeps time across a full power-off (main power removed, not merely a warm reboot) SHALL NOT be claimed as working until a backing supply (battery or supercapacitor) for this RTC domain is documented from the schematic or BOM, or a physical power-off-and-wait test is performed and recorded.
Grounding: neither this repository’s DT/schematic notes nor LILYGO’s
published hardware pinmap document a backing supply for the K230 RTC
block; the inventory and this proposal deliberately do not infer one from
the DT node being okay.
Archived change · Archived
Snapshot 5836ef1d113d · 2026-10-17 08:22 UTC
Closed recordClosed on operator acceptance; see evidence for waived captures and retained limits.
During real-finger bottom-edge gestures and in the card overview, a band about 50 px tall along the panel’s bottom edge cycled between the correct image, a stale-dark frame and black. The compositor’s scene and DRM present timestamps stayed clean, so the fault lies below composition, in scanout.
This change replaces the withdrawn change the-vo-commits-registers-at-vblank.
That change deferred the VO’s shadow-register commit to the vblank interrupt
(nix/patches/canaan-drm-defer-reg-load-to-vblank.patch). On the board the
patch left the band unchanged, and a kernel carrying it panicked at boot once
in two attempts. The patch is no longer applied. Its evidence stays under
docs/evidence/card-shell/bottom-band-flicker/, and its history is in git.
The operator approved dropping it on 2026-09-25.
max_render_time 8 (in nix/shell.nix, commit
ece1ee74), so composition starts about 8 ms before each vblank instead
of right after the previous one. The flicker stopped once this was applied.display/panel requirement’s grounding records this fix and its
evidence, replacing the unverified vblank-latch text.display/panel: “The panel displays what the system draws” gains a
scenario for continuous gesture animation and its grounding.nix/shell.nix (already landed). No kernel, device-tree or boot change.The operator accepts this delivered functional scope and waives additional
capture-only acceptance gates. docs/evidence/proposal-closeout/2026-10-01/flicker.md records the exact report,
prior evidence and limits. Its task dispositions supersede older statements
that these acceptance gates remain open; they do not claim new test runs.
The bottom-band flicker appeared only while frames rendered continuously,
and it cycled correct, stale-dark and black on consecutive frames
(max-render-time-fix.md). Scene and present timing were clean
(board-diagnostic.md), and deferring the VO register commit to vblank
changed nothing (kernel-vblank-latch.md).
Goals: a stable panel image during gestures on real glass.
Non-Goals: establishing the scanout or DDR mechanism, and changing the VO driver.
max_render_time 8. It moves composition and its
memory traffic next to the vblank, away from the scan of the last lines,
and it is a configuration change that is easy to revert.kernel-patch-boot-panic.md).The operator accepts this delivered functional scope and waives additional
capture-only acceptance gates. docs/evidence/proposal-closeout/2026-10-01/flicker.md records the exact report,
prior evidence and limits. Its task dispositions supersede older statements
that these acceptance gates remain open; they do not claim new test runs.
max_render_time 8 to the DSI-1 output line in
nix/shell.nix (commit ece1ee74). Verify with nix build .#nixosConfigurations.k230-coherent-shell.config.system.build.toplevel
and by reading the live k230-sway.conf on the board (board observation,
recorded in docs/evidence/card-shell/bottom-band-flicker/kernel-patch-boot-panic.md).docs/evidence/card-shell/bottom-band-flicker/max-render-time-fix.md,
before-max-render-time.png, after-max-render-time.png).kernel-patch-boot-panic.md, without-kernel-patch-injected-gestures.png).display/panel requirement “The panel displays what the
system draws” with the gesture scenario and its grounding. Verify with
openspec validate the-compositor-renders-ahead-of-scanout --strict.The updated completed tasks describe actual acceptance, waivers and scope
transfer, not execution of the superseded protocols. See docs/evidence/proposal-closeout/2026-10-01/flicker.md.
Historical checkpoint notes above that say physical gates remain open are
superseded by this record. Quantitative or individually unreported results
are not promoted to physical proof.
Proof: openspec validate the-compositor-renders-ahead-of-scanout --strict; committed operator report;
python3 scripts/render_work_board.py --working-tree --output <snapshot.json>.
Grounding: observed on hardware — photographs in docs/evidence/panel-photos/.
The panel was driven to three known states from a shell on the board —
/dev/urandom (speckled bright field), /dev/zero (dark), and 0xFF
bytes (bright) — and photographed each time. Three states rather than one
deliberately: a single bright frame could be a reflection and a single
dark frame is what a dead panel looks like, so the change is the
evidence. A fourth photograph shows the kernel console rendering on the
panel at 71x77 characters. See docs/evidence/panel-lit.md.
What is NOT yet grounded: the image still moves slightly. The 25% DSI
burst headroom fix referred to here was confirmed on hardware and it
blanks the panel outright; it was reverted in a96ca99. See
docs/evidence/dsi-burst-headroom.md.
On the corrected image, measured over 30 s with the webcam exposure
locked and the oblique view rectified by a four-fiducial homography, so
the numbers are in real panel rows: brightness is now flat (95%..101% of
mean, against 19 dips with the worst at 53% before), and the residual is
a uniform whole-frame vertical shift of about 2.8 rows RMS out of
1232. Near and far halves of the panel move identically — std 2.76
against 2.76, correlation 0.959 — so there is no accumulation down the
frame and no tearing. Mechanism is not established; the untested
hypothesis is that 35 00 SET_TEAR_ON is issued but nothing consumes
TE. See docs/evidence/flicker-after-headroom-revert.md.
A separate real-finger report — a band about 50 px tall along the panel’s
bottom edge flickering only during bottom-edge app-switch gestures and in
the card overview — was traced with a board scene/render/present
diagnostic (docs/evidence/card-shell/bottom-band-flicker/max-render-time-fix.md)
to a defect below composition: scene and DRM present timing stayed clean
while consecutive camera frames showed the band cycling between correct,
stale-dark and black. Deferring the VO’s register commit to vblank did not
change it and was withdrawn (kernel-patch-boot-panic.md). Setting Sway’s
max_render_time 8 on DSI-1 removed it on real glass
(max-render-time-fix.md) and on the patch-free kernel under injected
gestures (kernel-patch-boot-panic.md). The mechanism is inferred, not
measured.
The system SHALL present the panel as a working framebuffer at 568x1232, and what is written to that framebuffer SHALL appear on the screen.
A framebuffer device existing is not evidence. This SHALL be grounded by a
photograph of the physical screen, because a pipeline that reports success and
shows nothing is a failure mode this hardware has already produced once — the
Wi-Fi driver reported start ap successs! while transmitting nothing.
Archived change · Archived
Snapshot 5836ef1d113d · 2026-10-17 08:22 UTC
Closed recordClosed on operator acceptance; see evidence for waived captures and retained limits.
Overview offers no obvious route to Home while keeping apps open. Standard mouse input reaches the Rust launcher but the compositor’s overview owns only touch events, and Rust overlay wheel events are ignored. The user reports these navigation gaps on the physical board.
Make overview cards, the Home footer, and edge drags navigable with a normal mouse or the board’s built-in glass acting as an HDMI trackpad.
Make the overview Home target tappable as well as swipeable, without closing any app.
Bind four-finger spread to smoothly expand the centered card; keep inward pinch for overview.
Support wheel/two-finger scrolling in scrollable shell surfaces and audit Home, drawer, overview, shade, Settings, themes and Wi-Fi routes by actual pointer interaction.
Complete Home → overview with a visible bottom gesture handle: tap/click for open windows; swipe up for the app drawer.
Distinguish an edge tap from a drag before taking client input or hiding a mapped overlay. App header controls and drawer-search Backspace must remain tappable. Ordinary app-launch behavior is unchanged.
None.
runtime/shell: pointer navigation, overview-to-Home, centered-window spread, and shell scrolling.Userspace Sway adapter, Rust Wayland client, and Nix session configuration. Host/headless tests can establish event dispatch and scene outcomes. The physical board is needed for deployment, captures and real-glass acceptance. No kernel, touch calibration, display rotation, theme redesign, or hardware haptics changes.
The operator accepts this delivered functional scope and waives additional
capture-only acceptance gates. docs/evidence/proposal-closeout/2026-10-01/mouse.md records the exact report,
prior evidence and limits. Its task dispositions supersede older statements
that these acceptance gates remain open; they do not claim new test runs.
The shell has two input owners: compositor-native overview/edge navigation and Rust layer surfaces for Home and overlays. Standard wl_pointer support was added to Rust but is absent in the overview adapter. The relay makes the inactive built-in glass a relative trackpad in HDMI mode.
Provide complete round trips between app, overview, Home and drawer without terminating windows. Keep mouse controls consistent with touch. Preserve existing gestures and ordinary application input. Do not alter display transforms, kernel drivers or the trackpad relay’s physical coordinate mapping.
Persistent Back/Home button bars were rejected in the prior touchscreen design. Make the existing footer affordance interactive and provide mouse edge drags instead. Replaying a mouse drag as touch into arbitrary apps is rejected; only compositor-owned shell navigation uses shared policy. Hard-coded desktop icon coordinates are unsuitable for production dispatch; tests may use known geometry with assertions against actual focus and scene state.
Pointer ownership must survive dragging across a card or layer boundary and cancel safely on output/device/seat loss. Wheel deltas from discrete mice and smooth touchpads must both work without fighting momentum or changing theme selection on scroll. Native captures and injected input do not establish physical gesture recognition.
The first installed matrix exposed an existing focus hook placed inside Sway’s session-lock conditional. A launched application could be focused while Home still hid its scene, causing a following bottom gesture to reopen the drawer. Move the callback after that conditional, using contextual patch anchors. The regression must focus an ordinary app from Home and observe home_selected=0; the board launcher assertion requires both app focus and dismissed Home/drawer, not app focus alone.
The operator confirmed real-finger overview entry, overview-to-Home and drawer scroll/search, but found no discoverable Home-to-overview route. Ordinary drawer activation opens another terminal; the operator accepts multiple windows and rejected a proposed forced focus-or-launch change. Retain normal GIO desktop entry activation, and leave this change focused on navigation/input ownership.
Provide a visible Home bottom handle: tap/click enters overview while retaining all windows, and upward drag continues to reveal the drawer. Reject displaced or cancelled sequences as handle taps. A translated multi-finger pan is never a tap.
The operator also reported that app header taps open the shade and drawer-search Backspace taps dismiss the drawer. The compositor currently owns these edge contacts and begins navigation at touch-down. Hold edge intent until meaningful motion distinguishes a shell drag from ordinary client interaction. A tap must reach its original live surface as a balanced input sequence, with no drawer unmap or shade reveal. Protect the target lifetime, cancellation, multi-contact drain, device/seat loss and pointer pairing. Once a drag qualifies, continue the existing native tracking/settlement using the original down position and time. Do not shrink edge bands or move app controls as a substitute for arbitration.
Use real Wayland receivers and the actual Sway compositor for injected touch and pointer regression checks. On the board, simulate the reported app-header and compact-search-keyboard taps; then collect separate real-finger acceptance. No existing physical checkbox is completed by this design revision.
The operator accepts this delivered functional scope and waives additional
capture-only acceptance gates. docs/evidence/proposal-closeout/2026-10-01/mouse.md records the exact report,
prior evidence and limits. Its task dispositions supersede older statements
that these acceptance gates remain open; they do not claim new test runs.
openspec validate the-shell-is-navigable-with-a-mouse --strict.python3 -m unittest discover -s tests -p 'test_card_shell_pointer_navigation.py' against the built compositor (headless injected input).cargo test --manifest-path nix/rust-shell-client/Cargo.toml --lib and cargo check --manifest-path nix/rust-shell-client/Cargo.toml --bin k230-shell-rust (host only).nix build .#nixosConfigurations.k230-coherent-shell-hdmi-trial.config.system.build.toplevel --no-link --print-out-paths --max-jobs 2 --cores 8. 3.1 Exercise a pointer navigation matrix for app, overview, Home, drawer, shade, Settings, theme and Wi-Fi routes, including scrolling and keeping apps alive. Commit commands, objective outcomes, captures and remaining gaps under docs/evidence/the-shell-is-navigable-with-a-mouse/. Proof: python3 tests/shell_pointer_navigation.py --help followed by its recorded headless or reserved-board invocation. Evidence class must name injection versus real glass.
3.2 Install the built closure on the reserved physical board and verify exact profile, active services and native captures. Proof: ./tools/console.py /dev/ttyACM0 --wait=3 "readlink /run/current-system; systemctl is-active shell shell-ui k230-touch-trackpad", plus recorded pointer interactions. No flash required.
3.3 Record the operator’s 2026-10-01 mouse-navigation acceptance. Prior actual-board/headless pointer matrix remains committed. Additional photographs and exhaustive gesture rechecks are waived; this does not claim an individually observed four-finger pinch sequence.
3.4 Land tested source/evidence, push master and confirm exact site revision and media publication. Proof: recorded Pages run and published revision at https://knewter.github.io/tdisplay-k230/work/. Do not archive while physical gates remain open.
4.1 Implement Home handle tap/click to overview and defer shell edge ownership until tap/drag intent is known, preserving ordinary drawer activation. Proof: python3 -m unittest discover -s tests -p 'test_card_shell_pointer_navigation.py' and the recorded actual-compositor native-touch edge regression (including compact-keyboard pairing), plus the matching full HDMI system cross-build. Host injection is not physical proof.
4.2 Deploy the matching userspace closure on the reserved board; simulate header and drawer-search Backspace taps through native touch dispatch, verify Home → overview retains window IDs, and record exact system/executable identities. Preserve gestures and recovery. No flash/kernel/DT change.
4.3 Record the earlier real-finger acceptance of the edge-tap/Search correction and Home handle, plus current mouse-navigation acceptance. Retain installed-board edge-control evidence. No additional photograph or repeated glass test is required.
4.4 Validate, land source/evidence, push master and inspect exact publication. Keep task 3.3’s HDMI recognition/photograph gate open until performed.
Task 4.1 exact cross-build and headless input proof: docs/evidence/the-shell-is-navigable-with-a-mouse/edge-controls-host/README.md. Fixture protocol checks are distinct from task 4.2 actual-board key semantics and task 4.3 real-glass acceptance.
Task 4.2 installed board identity and native uinput header/Backspace/Home checks: docs/evidence/the-shell-is-navigable-with-a-mouse/edge-controls-board/README.md. Real-glass 4.3 remains open.
Task 4.4 successful exact-revision Pages build/deploy and published revision check: docs/evidence/the-shell-is-navigable-with-a-mouse/edge-controls-board/publication.json. Physical tasks 3.3 and 4.3 remain open.
The updated completed tasks describe actual acceptance, waivers and scope
transfer, not execution of the superseded protocols. See docs/evidence/proposal-closeout/2026-10-01/mouse.md.
Historical checkpoint notes above that say physical gates remain open are
superseded by this record. Quantitative or individually unreported results
are not promoted to physical proof.
Proof: openspec validate the-shell-is-navigable-with-a-mouse --strict; committed operator report;
python3 scripts/render_work_board.py --working-tree --output <snapshot.json>.
Grounding: operator acceptance in docs/evidence/proposal-closeout/2026-10-01/mouse.md, with prior source and board/QEMU evidence retaining their original classes and limits.
The userspace shell SHALL allow primary clicks/drags and scrolling to navigate Home, app drawer, overview, notification shade and Settings, including theme and Wi-Fi pages. An app SHALL remain open when Home is selected from overview.
In HDMI trackpad mode the userspace shell SHALL use a four-finger outward pinch on the built-in glass to expand the centered live overview window. Inward pinch SHALL open overview. Ordinary two-finger application pinch SHALL remain available to applications.
Archived change · Archived
Snapshot 5836ef1d113d · 2026-10-17 08:22 UTC
Closed recordComplete; operator accepts Home interactions and right-click New Window. Physical daylight, fresh-install and reboot-layout limits remain explicit in the spec.
A person picking up this handheld today has no ordinary home screen. At rest (no application focused, the card overview dismissed) the panel shows only the theme wallpaper; the only way to a specific application is the vertically scrolling “All apps” drawer reached by swiping up, and the only thing titled “Home” on this device is the live app-card overview itself. The user’s own words: “why no homescreen there should be a normal-ass homescreen with pinned icons and i can swipe between screens of icons”. No amount of drawer scrolling gives a person the thing every phone launcher (webOS, Android, iOS) provides: a small, chosen set of app icons, arranged by the person, reachable in one glance without opening a full alphabetical catalog.
This collides with a real prior decision. Decision 1 of
the-handheld-presents-a-coherent-shell (design.md, still unarchived) reads
“Home is the deck, not a grid… This shell chooses the Palm-style live deck
as Home rather than an Android home grid”, and its non-goals list “an
Android-style second home grid”. That decision was made to avoid two competing
home destinations, which was the right worry with the information available
then. The user has now explicitly asked for exactly the grid it rejected. This
proposal supersedes that specific sentence of decision 1 (not the sibling
change’s card-manipulation physics, close lifecycle, or composition-boundary
decisions, which this proposal does not touch) and resolves the “two homes”
worry differently: by giving the deck back its own name (the app switcher/
overview) and reserving “Home” for the one screen that already appears
whenever nothing else is focused. See design.md for the full reconciliation
and the coordinator note about updating the sibling proposal’s wording.
docs/evidence/home-screen/closeout-2026-10-09.md.Non-goals: search, folders or categories beyond the existing drawer list, home-screen widgets, a wallpaper picker (Home reads the existing theme wallpaper, it does not add a way to choose one), multi-user profiles, haptics (no haptic hardware exists on this board), the second CPU core, and any change to the sibling change’s card drag/expand/throw-close physics or composition boundary. The navigation addition changes Overview-to-Home routing and scene visibility; card manipulation and close-lifecycle behavior remain owned by their existing implementation.
Board dependency: the pager physics, grid layout, pin persistence, and
drag-reorder are host-testable Rust unit tests and run under cargo test --offline with no hardware. A QEMU injected-touch test (styled on
tests/rust_theme_chooser_qemu.py) exercises the compositor/client pairing,
the new layer-shell surface, page swipe, dock taps, and the pin flow with a
synthetic desktop-entry/icon fixture — this is QEMU proof of wiring and
layout, not of touch feel, contrast, or real-glass usability. The navigation addition includes a reserved physical-board injected-input
trial and matching-system installation. The broader real-finger, daylight
readability and rearrangement acceptance remains explicitly open in task 8.1.
runtime/home-screen: a pinned-icon, paged launcher shown whenever no
application owns the panel, its persistence, its pin/unpin/rearrange
interactions, and its reconciled place in the shell’s gesture topology.None. (The card overview’s on-screen title is cosmetic chrome text, not a
requirement of any archived openspec/specs/ capability; runtime/shell,
runtime/gpu-validation, and runtime/video are unaffected. The sibling
the-handheld-presents-a-coherent-shell and the-shell-manages-apps-as-cards
changes are still unarchived, so no MODIFIED delta can legally target their
not-yet-existing capability specs per .skills/k230-spec-change/SKILL.md;
this proposal’s design.md instead records in prose exactly which sentence of
the sibling’s design.md it supersedes, for the coordinator to reconcile at
that change’s next revision or archive.)
Userspace only: nix/rust-shell-client/ gains new modules (pager physics,
grid/dock layout, pin persistence) and a new always-mapped layer-shell surface
plus its touch/frame/configure wiring in main.rs; nix/card-shell/adapter.c
and its routing/focus hooks make Home reachable without unmapping apps.
No kernel, device tree, boot, radio, or second-core change. No new Nix
package; the existing .#handheld-shell-rust and .#card-shell outputs and
the k230-coherent-shell NixOS configuration absorb the change. Host build,
cargo test, and a QEMU injected-touch smoke test can all proceed without the
physical board; real-finger and daylight-readability board acceptance remain
open evidence gates for the coordinator.
The user requested GNOME Shell behavior after reconsidering launch-versus-focus. Task group 11 carries the now implemented and accepted refinement, with right-click menus in mouse mode and the existing long-press-to-move interaction preserved on touch. It does not reopen accepted mouse navigation or require recordings solely to reconfirm accepted behavior.
Today, on this 568x1232 portrait panel:
nix/card-shell/, patched Sway) owns a live application-card
overview. It is titled “Home” on screen (nix/card-shell/adapter.c’s
rebuild_chrome, the touch_first() branch, hardcoded "Home" label) and
is entered by a bottom-edge gesture from a running application, or a
persistent recovery route, per the-shell-manages-apps-as-cards and
the-handheld-presents-a-coherent-shell. With zero running applications it
shows an empty “No running apps” canvas, still labeled “Home”.nix/rust-shell-client/) owns the drawer (“All apps”,
reached by swiping up from the idle/empty state — see
card_shell_drawer_up in nix/card-shell/route.c, gated on !shell.active
so it never fires while the overview itself is open), the notification
shade, Settings, and the Quattro-style theme carousel. It also owns a
persistent Layer::Background wallpaper surface (nix/rust-shell-client/ src/main.rs’s WallpaperState/ensure_wallpaper) that is visible whenever
nothing else covers it — this is the literal “nothing is open” screen a
person sees today, and it has no icons on it at all.the-handheld-presents-a-coherent-shell/design.md (still
unarchived) reads: “Home is the deck, not a grid… This shell chooses the
Palm-style live deck as Home rather than an Android home grid or hold-for-
recents path”, with “an Android-style second home grid” listed as a
non-goal. That decision was reasoned from Palm webOS’s own model (app→card,
card→Launcher) and from wanting exactly one home destination. The user has
since asked directly for a grid of pinned icons with swipeable pages, which
is precisely what that decision ruled out. This proposal does not dispute
the reasoning that two home destinations would be confusing; it disputes
which screen should be named Home, and picks the one every mainstream
handheld launcher — including webOS itself, past its very first release —
actually uses that name for.Both of the ecosystems this shell already draws from (Palm/HP webOS via the [Palm Pre User Guide](https://support.bell.ca/_web/guides/User-Guides/Mobile/ PalmOne/Palm-EN/palm_pre_userguide_en%28en%29.pdf), cited by the sibling change, and later webOS TV/webOS 3.x devices; Android via [Android’s navigation guide](https://support.google.com/android/answer/ 9079646?hl=en) and [gesture guide](https://support.google.com/android/answer/ 9079644?hl=en)) converged on the same three-layer shape, not two:
| Layer | webOS (post-Pre “Just Type”/launcher era, and webOS 3 Smart TV launcher) | Android |
|---|---|---|
| Home | A grid of app icons the person places, paged, with a persistent Quick Launch bar of ~5 icons pinned at the bottom that stays fixed across every page | A grid of app icons/widgets the person places, paged, with a persistent hotseat row pinned at the bottom that stays fixed across every page |
| App switcher / recents | The card deck (webOS’s original and still most-cited contribution): live thumbnails of running apps, swipe to browse, throw up to close | The Overview/Recents screen: live thumbnails of running apps, swipe to browse, swipe up to close |
| App drawer / catalog | webOS 3’s launcher exposes “all apps” as a separate paged grid one level beyond Home (distinct from the curated Home pages); the original Pre instead used a persistent Launcher edge-swipe to the full catalog | The all-apps drawer, opened from Home (swipe up on the hotseat area, or a dedicated affordance), alphabetical/searchable, separate from Home’s curated pages |
The Pre’s very first release did fold “Home” into the card deck (an empty deck was the resting state, because the Pre had no persistent grid at all) — that is the specific, early-Pre-only precedent the sibling decision generalized from. Every later webOS revision, and Android throughout, treat “Home” as the pinned grid and keep the live-card view as a separate, differently-named surface (Card view / Overview) that is entered from Home or from a running app, not conflated with it. This proposal follows the converged, later model: three distinct, named layers (Home, Overview, Drawer), not two.
Goals: a pinned-icon Home with swipeable pages and a persistent quick-launch dock; pin/unpin/rearrange; sane fresh-install defaults; state that survives a restart and reboot; tap-to-launch-or-focus; a coherent, written-down place for Home in the existing gesture map, changing as little of the existing, already-evidenced card-overview and drawer machinery as possible.
Non-goals: search, folders, widgets, a wallpaper picker, multi-user
profiles, haptics, the second core, changing the card overview’s own
manipulation physics (drag/expand/throw-close), composition boundary, or
close-lifecycle (all owned by the-shell-manages-apps-as-cards and
the-shell-has-a-card-composition-plan), and re-litigating whether the
overview should exist at all (it should; it is Android’s Overview / webOS’s
card deck, not Home).
Layer::Bottom surface, not a mode of the existing overlayThe Rust client’s existing on-demand overlay (self.layer, Layer::Overlay,
used for Drawer/Shade/Settings) sits above every normal application window
by wlroots’ own layer-shell stacking order, and is only mapped on demand. Home
must do the opposite: sit below every normal application window (so a
focused, full-screen app automatically occludes it with no shell-side
tracking of “is an app focused” at all) and be visible whenever nothing
occludes it. Layer::Bottom sits directly above the existing Layer:: Background wallpaper and directly below ordinary toplevels and the existing
Layer::Overlay surface, which is exactly the required position: below an
app, below the card overview’s own compositor-native scene (inserted above
the normal window stack), and below the drawer/shade/Settings overlay when
one of those is open on top of Home.
Rejected: reusing the existing Route::Hide value on the overlay surface to
mean “show Home”, because that surface is Layer::Overlay — showing Home
there would paint over a focused, full-screen application, which is wrong.
Rejected: drawing Home directly into the wallpaper surface itself, because
that surface’s buffer/redraw contract is already shared by plain wallpaper,
per-theme background decode, and video-wallpaper playback
(background_decode.rs, video_wallpaper.rs); adding icon hit-testing and
page-swipe state to it risks all three. A separate surface keeps every
existing wallpaper consumer untouched and lets Home be alpha-composited over
whichever of those three the wallpaper surface is currently showing, exactly
as icons overlay a wallpaper on every reference launcher.
User decision, 2026-09-27: “swipe up from windows list” shows Home and “swipe up from home” shows the app drawer. This supersedes the earlier “keep every gesture unchanged” decision: that left Home hidden behind apps.
Userspace: the compositor owns a Home visibility state and suppresses normal app scene layers while Home is selected, without moving/unmapping/closing windows or changing their identities. Ordinary app focus exits that state. Session-lock surfaces remain outside this app-layer suppression. Output teardown restores normal scene state. Home’s Rust Layer::Bottom surface continues rendering icons and accepting its existing page/pin interactions.
The Overview-to-Home transition moves the whole Overview with the finger, revealing Home underneath. Release settles smoothly to Home when qualified, or back to Overview when cancelled/too short. The next swipe is a distinct contact; the Home gesture must never accidentally open the drawer too. Multi-touch cancels navigation without leaking part of the contact sequence into an app or into Home. Existing card close/open and overlay escape paths retain their ownership rules.
Rejected: closing apps, parking them in the scratchpad, or putting them on a special workspace merely to expose Home. Those were diagnostic shortcuts, not the user’s navigation model, and would complicate launch/focus behavior. Physical gesture proof remains UNVERIFIED until task 10’s board trial.
theme_carousel.rs’s Cover Flow model (skewed neighbor slices, blend-based
bitmap selection) fits a single hero item users browse one at a time. Home’s
pages are not single items — each page is a 4-column icon grid a person reads
as a whole — so a full-bleed pager (each page is exactly one panel-width
apart, no skew, no partial-neighbor peeking beyond an intentionally minimal
edge sliver so a page boundary is not mistaken for a resize) is the right
shape, closer to navigation.rs’s drawer scrolling than to the carousel, but
paged (settle to a whole page) rather than free-scrolling (settle to any
pixel). This is the same “coverflow vs. off-the-shelf ViewPager” choice
every Android launcher and webOS’s own Home page made for the same reason.
Physics conventions are taken from theme_carousel.rs::Carousel and
navigation.rs::DrawerNavigation (already the shell’s two existing precedents
for touch physics) rather than invented fresh: 1:1 drag (dragging one panel
width moves exactly one page), momentum decay at the same DECAY_PER_16MS = 0.88 per-16ms factor every other flick in this shell uses, a
MIN_COAST_VELOCITY cutoff below which a release settles immediately instead
of coasting a fraction of a page, and an ease-out-cubic settle whose duration
scales with distance exactly like theme_carousel::settle_duration_ms and
service_ui::NotificationSwipeSettle. New module home_pager.rs implements
this for whole-page positions (position: f64 in page-units, not
index-units-with-skew), with its own unit tests mirroring
theme_carousel.rs’s (drag_moves_one_to_one_with_the_finger,
slow_release_settles_immediately_to_nearest,
fast_flick_coasts_then_settles_and_decays_over_time).
Page-count indicator dots are drawn, never tappable (per the user’s own
“page-indicator dots are fine, since they’re indicators, not controls”
constraint) — render.rs’s paint_home draws them from HomePager::page( count) and count, with no hit-test region.
The quick-launch dock (webOS Quick Launch bar / Android hotseat) sits below
the grid, at a fixed vertical position, and never scrolls with the pager. It
holds a bounded number of slots (sized to fit 568px width at the same 56px+
touch target convention every other surface in this shell uses — 4 slots at
that width, matching the existing bottom persistent-bar precedent’s target
sizing). Dock membership is part of the same persisted layout (a dock: Vec<Option<AppRef>> alongside pages: Vec<Vec<Option<AppRef>>>), and an icon
can be dragged between the dock and a page during rearrange mode, exactly as
both reference launchers allow.
User correction, 2026-10-01: secondary click opens the app menu in mouse mode, including supported New Window and named desktop actions, identified running windows, and pin/unpin or rearrange actions where relevant. The operator explicitly rejected long-press menus because that contact is how icons are grabbed and moved. Preserve the existing long-press-to-grab flow, drawer-to-Home dragging, dock/page placement and remove targets. Opening or dismissing a right-click menu must not alter placement; outside click and Escape dismiss it. Touch has no new app-menu gesture in this scope. Rearrangement remains contextual, with Done/tap-empty exit and no permanent navigation chrome or idle wobble animation.
Primary tap/click activates the most recently used reliably identified window
of that app, or launches through GIO desktop-entry semantics when none exists.
A missed identity match must fall back to launch, never focus an unrelated
app. Run tree/catalog/launch work off Wayland dispatch. Existing
focus_or_launch is a starting point, not proof of full multi-window parity.
New Window bypasses the focus shortcut. Prefer the desktop file’s new-window
action, expose other named desktop actions through GIO, and avoid duplicate
New Window entries. A generic fresh launch is offered only when the app’s
capabilities support it; honor single-window metadata and do not invent
application CLI flags. No guarantee of a second window for single-instance
applications. Select a listed running window by its verified container ID.
Reference behavior checked 2026-10-01: GNOME Help describes primary activation and an icon menu for window selection/new windows. Shell appDisplay opens the menu for long-press/secondary click. Shell appMenu uses desktop actions and suppresses a duplicate generic New Window item. These sources establish the interaction reference, not K230 hardware proof. Rejected: always spawning on primary tap and taking long-press away from icon movement. GNOME is the activation/menu reference, not a requirement to copy its conflicting long-press gesture. The existing historical implementation remains until group 11 is implemented and verified.
Per openspec/config.yaml’s standing rule (“Application defaults belong in
this repo and the NixOS image… Fresh homes must provide the usable starting
point”), first run (no saved home.json) seeds Home from
catalog::installed_apps() by matching a small ordered list of preferred
desktop-entry-id substrings — terminal, file manager, text editor, system
monitor, video player, and Settings, plus the drawer itself as a permanent,
unremovable dock-adjacent affordance the same way both reference launchers
keep an “all apps” affordance always reachable from Home — skipping any that
are not installed on this image rather than showing a placeholder, then
immediately persisting the seeded layout so a second boot is stable even if
the catalog later changes. This mirrors the existing bounded, best-effort
matching style already used for the launcher curation in
the-launcher-explains-app-actions, without depending on that change (which
curates the drawer’s names, not Home’s default membership).
home_state.rs::state_path() follows the exact fallback shape
theme_thumbnails.rs::disk_cache_dir_from already established for this
client’s other on-disk state ($XDG_STATE_HOME/k230-shell/home.json, or
$HOME/.local/state/k230-shell/home.json when XDG_STATE_HOME is unset or
empty), matching the existing $XDG_CACHE_HOME/k230-shell/thumbs /
~/.cache/k230-shell/thumbs convention one directory family over (state, not
cache, because a cache may be silently dropped and this must not be). The
file is a versioned JSON document (serde/serde_json, already a pinned
dependency) with a schema integer field from the first write, an ordered
pages: Vec<Vec<Option<String>>> of desktop-entry ids (slot-stable, None
for an empty grid slot so a removal does not shift every later icon), and a
fixed-length dock: Vec<Option<String>>. A desktop entry that has since been
uninstalled is skipped at load (slot kept, rendered empty) rather than
crashing or silently compacting the grid, so a later reinstall of the same
package restores its position. Writes are atomic (write to a sibling temp
file, then rename), the same durability convention as every other
state-bearing write this project makes to $HOME.
dirty flag, same convention as every other surface
in this client); at rest it costs one static buffer already resident, no
per-frame work, matching the “no idle redraw” requirement.<!-- UNVERIFIED -->; a miss always
falls back to the existing, already-correct launch path rather than
focusing the wrong window silently.the-handheld-presents-a-coherent-shell/design.md’s
decision 1 at its next revision, the same way that file’s own decision 12
already superseded decision 11 in place.navigation.rs::pressed/up).Land this proposal, then implement home_pager.rs/home_state.rs/
home_screen.rs and their unit tests, then wire the new surface into
main.rs and render.rs, then the two-line nix/card-shell/ change, then
the QEMU smoke test and evidence captures. No image identity change is
needed: the existing .#handheld-shell-rust, .#card-shell, and
k230-coherent-shell build the same way; Home is additive behavior inside
the already-opt-in coherent shell, not a new opt-in flag. Real-finger board
acceptance (readability, long-press feel, dark/light capture on the physical
AMOLED) is out of scope for this pass per the coordinator’s explicit “don’t
touch the board” instruction and remains a named open evidence gate in
tasks.md.
Tasks 1–9 document the first Home implementation. Task 10 now authorizes compositor navigation changes and a reserved board trial. The older no-board/no-gesture-change migration notes describe that original pass, not the newly authorized navigation work. Broad task 8.1 stays open.
Home and the app-action refinement are installed and operator-accepted.
docs/evidence/home-screen/closeout-2026-10-09.md records the final New Window
confirmation and reuses previous Home/focus/drag observations on the exact
same installed Rust executable. No new camera, measurement or reboot is
inferred. All 25 tasks are complete; dated earlier open-task notes remain
historical. The archived spec retains explicit limits on unobserved physical
fresh-install seeding, reboot-layout persistence and daylight readability.
the-handheld-presents-a-coherent-shell and
the-shell-manages-apps-as-cards proposals/designs and record the exact
decision superseded and the exact gestures kept unchanged; verify with
openspec validate the-shell-presents-a-pinned-home-screen --strict.nix/rust-shell-client/src/home_pager.rs: whole-page 1:1
drag, momentum decay, ease-out settle, page/dot math, mirroring
theme_carousel.rs’s and navigation.rs’s existing conventions and unit
test shapes; verify with cargo test --offline -p k230-shell-rust home_pager. Done: 8 unit tests.nix/rust-shell-client/src/home_grid.rs: page/dock slot
geometry and hit-testing (tap vs. drag vs. long-press timing, page-size
slots, dock slot count) as pure, host-testable functions; verify with
cargo test --offline -p k230-shell-rust home_grid. Done: 6 unit tests.nix/rust-shell-client/src/home_state.rs: the
$XDG_STATE_HOME/k230-shell/home.json (falling back to
$HOME/.local/state/k230-shell/home.json) versioned layout file, atomic
write, missing-entry-preserves-slot load behavior, and default-seed
selection from catalog::installed_apps(); verify with cargo test --offline -p k230-shell-rust home_state. Done: 12 unit tests.Route-adjacent Home surface state to main.rs (a new
always-mapped Layer::Bottom layer-shell surface, its own buffer pool
usage, frame/configure callbacks, and touch dispatch keyed on that
surface, mirroring the existing WallpaperState pattern) and a
paint_home renderer in render.rs that composites pinned icons and the
dock, alpha-transparent elsewhere so the existing wallpaper layer shows
through; verify with cargo test --offline -p k230-shell-rust (existing
suite stays green) and cargo build --offline -p k230-shell-rust. Done:
175 tests pass (139 lib/bin + 36 across the existing integration
suites), full binary builds clean.--render-fixture home verification were
dropped in favor of a direct pin on long-press, matching both reference
launchers’ grab-then-place gesture — see design.md decision 5’s revised
text and home_state::HomeLayout::pin’s no-op-if-already-pinned
semantics; --render-fixture still only covers drawer|shade|settings,
since Home is not a Route value.)home_screen::focus_or_launch’s best-effort
desktop-entry-id-to-running-app_id match (off the Wayland dispatch
thread, on the existing launch worker), falling back to
launch_selected unchanged on no match; verify with cargo test --offline -p k230-shell-rust home_screen covering the id-normalization and
fallback logic against a synthetic get_tree fixture. Done: 4 unit
tests (app_id_matches/find_running_con_id); the QEMU harness proves
the not-yet-running launch path end to end, not the focus-an-existing-
window path (no fixture client with a matching app_id was spawned in
this pass — see docs/evidence/home-screen/qemu/README.md).nix/card-shell/adapter.c’s rebuild_chrome title from
"Home" to "Overview", and add "home" to nix/card-shell/route.c’s
card_shell_launch_surface allow-list; verify with nix build --no-link --print-out-paths --max-jobs 1 --cores 6 .#card-shell. Done: builds;
strings on the resulting sway-unwrapped binary confirms “Overview”
and the “home” allow-list entry are present.nix build --no-link --print-out-paths --max-jobs 1 --cores 6 .#handheld-shell-rust .#card-shell. Done:
/nix/store/4vwq285cbg1w0s4is25s76gq6nk49abf-k230-shell-rust-riscv64-unknown-linux-gnu-0.1.0
and /nix/store/3gk7wpcrj11hpivfsq4ph9qzyxf55pwg-k230-card-shell.nix eval .#nixosConfigurations.k230-coherent-shell.config.system.build.toplevel.drvPath.
Done: evaluates to
/nix/store/gxvv2vy1g23m86qlhvs4d60aqr2fvpj2-nixos-system-nixos-26.11.20260919.20b1ddd.drv.tests/rust_theme_chooser_qemu.py: boot the cross-built sway (from
nix-store -qR <card-shell store path>) and the cross-built Rust client
under qemu-riscv64-static with a synthetic desktop-entry/icon fixture,
inject touch to swipe Home’s pages, tap the dock, long-press to pin from
the drawer and to rearrange on Home, and screenshot each step; verify
with python3 tests/rust_home_screen_qemu.py --sway <sway> --swaymsg <swaymsg> --rust <rust> --theme-bundle <theme-bundle> --icons <icons> --client <native-probe-client> --output <dir>.
Passed all 24 checks with the exact candidate compositor/Rust executables;
see docs/evidence/home-screen/navigation/qemu-result.json. Done: PASS, all twelve checks true; see
docs/evidence/home-screen/qemu/. (User-mode qemu-riscv64-static
headless Pixman, not qemu-system-riscv64’s k230 machine — this
repo’s existing Rust-client QEMU tests all use the same user-mode
approach, since the compositor/client pairing needs no board devices,
and it is what tests/rust_theme_chooser_qemu.py itself actually uses
despite this task’s original text.) This is QEMU proof of wiring/layout,
not of the physical panel, touch controller, or real-glass feel.docs/evidence/home-screen/qemu/. Done, plus a rearrange/
remove/restart-persistence sequence and an additional “showcase” pass
(a fully-populated, colorfully-iconed fresh Home) for visual review.
These are QEMU/synthetic captures, not board photographs; the
physical-panel, real-finger, and daylight-readability gates remain open
for the coordinator (see task 8.1).python3 tools/blob-scan.py and check its exit code directly. Done: exit 0.origin/master before final report;
verify with git -C <worktree> fetch origin && git -C <worktree> rebase origin/master and re-run 6.1-6.3, 7.2. Done: rebased cleanly (no
conflicts) onto fa1f54e6; 6.1/6.2 and the QEMU harness (6.3) all
re-passed against the rebuilt store paths, and 7.2 (blob-scan) passes
after adding inventory rows the rebase’s upstream commit newly required.python3 tools/capture-feature.py home-screen --provenance real-touch --duration 30 --description 'Real-finger Home page swipe, pin, rearrange, dock, launch-or-focus' --output-dir docs/evidence/home-screen/real-touch. Left open per the coordinator’s
explicit instruction that this implementation does not touch the board
or /dev/ttyACM0.
Done 2026-10-08 by operator real-finger report on the installed mainline
shell, in place of capture at the operator’s request, one theme only by
operator decision: docs/evidence/home-screen/real-touch/operator-report-2026-10-08.md.openspec validate the-shell-presents-a-pinned-home-screen --strict. Done: valid.Coordinator note: the-handheld-presents-a-coherent-shell/design.md’s
decision 1 (“Home is the deck, not a grid”) is superseded by this change’s
design.md. This change does not edit that file (it is unarchived and
under active, concurrent revision by other work); the coordinator should add
a superseding note to its decision 1 at that change’s next revision or
archive, the same way its own decision 12 already superseded decision 11 in
place.
python3 -m unittest tests.test_card_shell_route and the existing policy
command python3 -m unittest tests.test_card_shell_state.
Source f39cb7eb; 37 route/policy checks pass. The Home-layer runtime
regression passes, as do 20 Rust Home tests and the desktop-ID regression.python3 tests/rust_home_screen_qemu.py --sway <sway> --swaymsg <swaymsg> --rust <rust> --theme-bundle <theme-bundle> --icons <icons> --client <native-probe-client> --output <dir>.
Passed all 24 checks with the exact candidate compositor/Rust executables;
see docs/evidence/home-screen/navigation/qemu-result.json.nix build .#nixosConfigurations.k230-coherent-shell.config.system.build.toplevel --no-link.
On the reserved board, repeat the navigation sequence through verified
injected touch, capture Overview/Home/Drawer, and check app identity and
focus after returning. Keep real-finger acceptance distinct and open.
Passed: docs/evidence/home-screen/navigation/README.md and result.json;
three window IDs retained, measured held motion, Home icon restores Terminal.Task 10 delivery verified at 04eefdbf: source and physical-board evidence
landed on master, the qualified system is running and persistently selected,
and Pages run 36300532436 passed build and deployment. The published evidence
page and /work/ card both serve the new native captures. Task 8.1 remains
open; no archive is claimed.
Historical 4.2 remains the accepted long-press-to-grab implementation. The operator rejected replacing it with a stationary-hold menu on 2026-10-01. This group adds right-click app actions without changing touch placement. It is separate from the accepted mouse/HDMI navigation closeout.
cargo test --offline --manifest-path nix/rust-shell-client/Cargo.toml with multi-window, missing/mismatched identity and desktop-action fixtures.docs/evidence/home-screen/; run python3 tests/rust_home_screen_qemu.py --sway <sway> --swaymsg <swaymsg> --rust <rust> --theme-bundle <theme-bundle> --icons <icons> --client <native-probe-client> --output <dir>, then commit its actual result. QEMU injection is not finger evidence.nix build .#handheld-shell-rust .#nixosConfigurations.k230-coherent-shell-hdmi-trial.config.system.build.toplevel --no-link --print-out-paths; install the recoverable candidate under the board reservation and record exact identities with python3 tools/console.py /dev/ttyACM0 --wait=3 'readlink -f /run/current-system'. Obtain operator acceptance of tap/focus, right-click New Window and preserved icon dragging; a committed operator report suffices unless a defect needs capture.openspec validate the-shell-presents-a-pinned-home-screen --strict, land/push source and evidence and inspect matching CI/Pages. Keep original unresolved placement and physical scope tracked; this planning refinement alone does not ship the menu.App-actions groups 11.2–11.3 passed: docs/evidence/home-screen/app-actions/qemu/README.md.
Cross Rust and the matching full coherent system also built from source 2885352;
11.4 retains operator acceptance; its named HDMI trial build and recoverable
component installation have now passed. Original 8.1 remains open.
Recoverable component installation passed: docs/evidence/home-screen/app-actions/board/README.md.
The candidate has a 30-minute independent restoration timer; operator feedback
is still required by 11.4. The named individual Rust and HDMI toplevel builds
have now passed; their exact output paths are recorded in that board README.
2026-10-01 operator accepted hold-and-drag without a menu on the installed
candidate: docs/evidence/home-screen/app-actions/board/operator-acceptance-2026-10-01.md.
11.4 still retains explicit primary-focus/New Window acceptance.
Full coherent-system runtime activation passed after the component trial:
docs/evidence/home-screen/app-actions/board/full-system/README.md.
The built system now runs with the expected Rust executable and without component
service overrides. Boot files/profile remain unchanged; ordinary boot remains a
separate gate. Menu delivery/dismissal passed again; automatic primary-focus/New
Window qualification was inconclusive and operator acceptance remains open.
11.5 source/evidence validation, master publication and Pages deployment passed
at 29c9e144, run 36929358280; tasks 8.1 and 11.4 remain unchecked.
The corrected full-system actual-board app-action probe passed all six checks,
including distinct New Window and primary activation of the most recent existing
window: docs/evidence/home-screen/app-actions/board/full-system/actions-result.json.
Earlier probes ignored floating_con nodes; this was a harness filter error,
not an established shell defect. Existing windows/layout were preserved and only
the owned new window was closed. Task 11.4 still awaits separate operator
acceptance, rather than treating injected pointer input as physical mouse input.
All 25 tasks are complete. Task 8.1’s operator exceptions and real-finger
acceptance are recorded on October 8. Task 11.4’s named builds and recoverable
installation already passed; the October 8 focus/drag observations apply to
the exact same currently installed Rust executable. The remaining right-click
New Window check is accepted by “i confirmed it works”. See
docs/evidence/home-screen/closeout-2026-10-09.md for context, exact identities,
proof classes, limitations and the archive commands. Historical open-task
notes above describe their dated checkpoints, not today’s completion state.
Defines the handheld’s pinned-icon Home: the paged icon grid and quick-launch dock a person sees whenever no application owns the panel, its pin/unpin/ rearrange interactions, its fresh-install defaults and persistence, and its place in the shell’s gesture topology alongside the existing card overview and drawer.
Grounding: operator accepts Home page swipes and icon taps on the installed
shell in docs/evidence/home-screen/real-touch/operator-report-2026-10-08.md.
Host pager fixtures and paired QEMU wiring remain separate evidence; no
physical timing or per-frame tracking measurement is inferred.
Whenever no application is focused and the card overview is not active, the shell SHALL present Home: the current theme wallpaper with a grid of touch-sized pinned application icons, arranged across one or more horizontally swipeable pages. A page swipe SHALL track the finger 1:1, apply momentum on release, and settle to the nearest whole page with an ease-out motion. When more than one page exists, Home SHALL show a row of page-count indicator dots that are visual indicators only and never a tappable control.
Grounding: dock taps and Home page navigation accepted in
docs/evidence/home-screen/real-touch/operator-report-2026-10-08.md; no new
recording or measured fixed-position trace is inferred.
Home SHALL show a fixed-position quick-launch dock beneath the icon grid, holding a bounded number of pinned icons that do not move or scroll when the grid pages change.
Grounding: pin/unpin/rearrange and icon dragging accepted in
docs/evidence/home-screen/real-touch/operator-report-2026-10-08.md; the
final right-click app-action check is accepted in
docs/evidence/home-screen/closeout-2026-10-09.md.
A person SHALL be able to add or remove an installed application through its mouse app menu or long-press grab and deliberately drag icons from the drawer to Home or rearrange them between pages and dock slots. A long-press SHALL grab an icon for movement, not open a menu; a deliberate drag SHALL preserve direct manipulation without also activating the app. Rearrangement SHALL provide contextual Done/remove controls, with no permanent navigation chrome. Pinning an already-pinned app SHALL preserve its placement rather than duplicate it.
When no saved Home layout exists, the shell SHALL seed Home from the installed desktop-entry catalog with a curated default set (a terminal, a file manager, a text editor, a system monitor, a video player, and Settings), omitting any entry not present on the running image rather than showing a placeholder for it, and SHALL persist the seeded layout immediately so a later boot is stable even if the catalog subsequently changes.
Every pin, unpin, rearrange, and page assignment SHALL be written to a layout file under the shell user’s XDG state directory, and SHALL be read back and reproduced exactly on the next start of the shell, including after a reboot. An application that was pinned and has since been uninstalled SHALL keep its grid position empty rather than shifting later icons into it, so reinstalling the same application restores its place.
Grounding: primary launch/focus accepted in
docs/evidence/home-screen/real-touch/operator-report-2026-10-08.md, with
matching installed executable in the October 9 closeout report. Six
injected-board multi-window/primary/New Window checks remain separate proof
in docs/evidence/home-screen/app-actions/board/full-system/actions-result.json.
Matching remains best-effort for apps without usable desktop identity; a miss
falls back to the normal desktop-entry launch path.
Tapping or primary-clicking a Home/dock icon outside rearrange mode SHALL activate its most recently used identifiable window if already running, or launch it if none is, using the same desktop-entry argument expansion and working-directory semantics the drawer already applies.
Grounding: operator navigation accepted in
docs/evidence/home-screen/navigation/operator-acceptance-2026-10-01.md and
docs/evidence/hdmi-hotplug/live-switch/fast-runtime-qualification.json.
The paired QEMU and injected-board trials in
docs/evidence/home-screen/navigation/README.md remain distinct from those
physical reports; no new cancellation/second-contact recording is inferred.
A bottom-edge swipe from a running application SHALL open Overview. An upward swipe beginning in Overview’s bottom navigation area SHALL reveal Home without closing, unmapping or moving running apps. Swiping up from Home’s bottom edge SHALL open All apps. Swiping a card itself upward SHALL retain the existing close-card action. Home selection SHALL end when an existing app is focused or a new app is launched. Navigation SHALL track contact displacement and settle smoothly after release or cancellation.
Grounding: right-click New Window accepted in
docs/evidence/home-screen/closeout-2026-10-09.md, with previous primary focus
and icon-grab acceptance on the exact same installed Rust executable. Native
pointer delivery/dismissal and six injected-board action checks remain
separate evidence under docs/evidence/home-screen/app-actions/board/.
Home/dock and the shared launcher app-icon path SHALL provide the same menu through secondary click in mouse mode. Long-press SHALL retain the existing icon-grab/rearrange behavior and SHALL NOT open this menu. The menu SHALL offer named supported desktop actions and identified running windows; New Window SHALL bypass primary focus behavior when supported, prefer the desktop entry’s new-window action and not appear twice. Single-window apps SHALL NOT be promised an unsupported second window. Menu dismissal SHALL preserve layout, application focus and ordinary pointer/touch ownership.
Archived change · Archived
Snapshot 5836ef1d113d · 2026-10-17 08:22 UTC
Closed recordReview the archived record and cited scope
To change the keyboard, a person has to open the notification shade, enter Settings and find the right row. No Settings option makes text larger or raises contrast; the only accessibility setting shortens motion. The shade’s “Dismiss all” target is 74 logical px tall, about 36dp at this panel’s density, so it is easy to miss.
the-shell-behaves-as-one-coherent-system planned these as slices B and C,
plus a shade tap-target requirement that no task tracked. That change’s slices A
(webOS-fan overview) and E (bottom-edge overlay escape) are implemented and
have host/QEMU proof. B and C have no code yet. This scope-split successor
keeps every B and C requirement and task, so the parent can close once its A
and E board gates pass.
Status: staged, not authorized. The parent’s task D.3 requires explicit coordinator/user authorization for this split. Until it is given, the parent still owns these requirements. When the split is authorized, remove the parent’s slice B/C requirements and tasks in the same commit that makes this change active, so neither change is archived with the other’s requirements.
ControlState/ServiceRequest, and an unavailable state looks the same as in
Settings. The brightness half of the original requirement is now met by the
shade’s brightness slider from the-brightness-control-is-a-slider
(nix/rust-shell-client/src/service_ui.rs SHADE_SLIDER_TOP). This
change keeps that scenario but does not add a second brightness control. Its
on-glass proof stays with that change’s own task 6.2.notification-center requirement with no
task): every shade tap target, including “Dismiss all”, gets a
48dp-equivalent (about 99 logical px) hit region.the-handheld-presents-a-coherent-shell tasks
2.2/4.4).the-handheld-presents-a-coherent-shell task 1.5.The host work (Rust unit tests, nix build .#card-shell, host renders) needs
no board. Reachability, legibility and persistence across a reboot on the real
panel each need a reserved board and a real finger (tasks B.4, C.4).
None.
None. The requirements are ADDED to runtime/notification-center and
runtime/device-settings, which the-handheld-presents-a-coherent-shell
introduces and which do not yet exist under openspec/specs/. The parent
used the same additive pattern.
Userspace only: nix/rust-shell-client/src/{render.rs,service_ui.rs,service_data.rs},
the theme-token path shared with nix/card-shell/render.c, and persisted
Settings state. There are no kernel, device-tree, stage-1 or radio changes.
This is a scope split of the-shell-behaves-as-one-coherent-system. Its
decisions 2 and 3 and the open question below are carried over unchanged.
The implementation layer is userspace: the Rust shell client and the
card-shell C renderer. The Nix layer changes only if a new persisted default
is needed.
Current code, read on master 38c264e4:
Route::Shade render (nix/rust-shell-client/src/render.rs, from about
line 1717) paints notifications, “Dismiss all”, the Settings entry and a
brightness slider. It has no keyboard control. The Route::Shade arm of
panel_intent (service_ui.rs, about lines 652-693) hit-tests scroll,
item actions, “Dismiss all” (116.0..190.0, 74 px) and Settings.KeyboardToggle is sent only from Route::Settings
(service_ui.rs, about lines 733-737).nix/ matches text_scale, high_contrast or
accessibility. settings.motion (reduced motion) is a separate control.ServiceRequest::KeyboardToggle that Settings sends
and gates on the same ControlState. A shade-only state model was rejected
because it would duplicate the unavailable/read-only/pending semantics.the-brightness-control-is-a-slider already sends the brightness request
under the same ControlState. A second stepper control was rejected
because it would duplicate one control in one sheet.docs/design/webos-polish-review.md P1-1.cargo test suite.This change was split from the-shell-behaves-as-one-coherent-system
(tasks B.1-B.4, C.1-C.4 and the B/C half of D.2). The user authorized this
split on 2026-09-28 (“yes a-d and f”); the parent’s own B.1-B.4/C.1-C.4 are
now ticked [x] ... MOVED, NOT PERFORMED HERE and cross-reference this
file. Task IDs keep the parent’s numbering. B.5 is new: it tracks a parent
requirement that had no task. None of the tasks below are done yet;
authorization only removes the blocker on starting them.
Route::Shade’s layout
(render.rs, the Route::Shade branch) for keyboard show/hide, reusing
ControlState/ControlValue exactly as Settings’ existing rows do
(service_data.rs). Brightness is already the shade slider from
the-brightness-control-is-a-slider; do not add a second brightness
control. Verify with
cargo test --manifest-path nix/rust-shell-client/Cargo.toml --locked.panel_intent’s Route::Shade arm (service_ui.rs) with
hit-testing for the new toggle, sending the same
ServiceRequest::KeyboardToggle value Settings already sends, gated on the
same ControlState the Settings row already checks. Add unit-test cases
mirroring service_ui.rs’s existing
shade_and_settings_hits_are_bounded_and_cancel_scroll_taps test. Verify
with cargo test --manifest-path nix/rust-shell-client/Cargo.toml --locked.cargo test invocation as B.2, plus a host render screenshot of the shade
with the new row committed to
docs/evidence/coherent-shell/shade-quick-toggles/.116.0..190.0 in service_ui.rs, 74 px), a hit region of at least 99
logical px (48dp-equivalent) without overlap, and add a unit test asserting
each region’s height. Verify with
cargo test --manifest-path nix/rust-shell-client/Cargo.toml --locked.python3 tools/capture-feature.py shade-quick-toggles --provenance real-touch --duration 30 --description 'Shade quick-toggle reachability and live state' --output-dir docs/evidence/coherent-shell/shade-quick-toggles. Keep open until
committed.
2026-10-16: done with injected events (uinput pointer and the
compositor trackpad command) on HDMI 1280x800, not real touch, per the
user’s instruction to inject instead of asking for taps. Covered: reachable,
toggles the keyboard with the Shade staying open, and shows “Unavailable”
and ignores a tap once wvkbd is stopped
(docs/evidence/coherent-shell/shade-quick-toggles/README.md, board/).
The DSI panel orientation was not exercised.service_data.rs) and persistence (following the existing theme-choice
persistence mechanism). Verify with
cargo test --manifest-path nix/rust-shell-client/Cargo.toml --locked.
Done 2026-10-16 (host): tools/theme_vision.py stores vision.json with the
theme state; see docs/evidence/coherent-shell/accessibility-scale/README.md.render.rs (Home/drawer/shade/Settings) and
nix/card-shell/render.c (card headers) apply it consistently; this is
the same cross-renderer boundary webos-polish-review.md P1-1 already
names for fonts, so reuse rather than duplicate whatever token-passing
mechanism that finding’s eventual fix establishes if it lands first.
Verify with cargo test --manifest-path nix/rust-shell-client/Cargo.toml --locked and nix build .#card-shell --max-jobs 1 --cores 4 --no-link --print-out-paths.
Done 2026-10-16 (host): sections.accessibility in every generation; Rust
and card-shell both scale by text-scale; high contrast rewrites the palette.docs/evidence/coherent-shell/accessibility-scale/. Verify
with the C.1/C.2 commands plus the new screenshots.
Done 2026-10-16 (host): Settings “Vision ›” page; renders in
docs/evidence/coherent-shell/accessibility-scale/host/.python3 tools/capture-feature.py accessibility-scale --provenance real-touch --duration 30 --description 'Text-scale and high-contrast option on glass' --output-dir docs/evidence/coherent-shell/accessibility-scale.
Keep open until committed.
Progress 2026-10-16 (board, injected taps + grim, HDMI): toggles apply and
the choice persists across a soft reboot; see
docs/evidence/coherent-shell/accessibility-scale/README.md. Real-panel
legibility (glass/camera) is still unrecorded. Panel grim captures on
DSI-1 found the battery ring’s percentage overflowing at the larger step;
fixed by 91a60bfb and re-captured (same README).
Result 2026-10-16 (operator on glass, landscape panel): not legible
enough. “the drawer is not particularly legible at ‘large’ text but also i
think ‘normal and large’ is a pretty shitty accessibility option anyway”.
This task stays open for the redesign in C.5–C.8.
Closed 2026-10-16 by C.8: the operator accepted the redesign on glass.tools/theme_vision.py (TEXT_SCALES), the helper protocol
and Rust VisionChoice, vision_text_scale (bound raised to 2.0),
appearance.c (its bound too), and the Vision page as a stepped control.
An existing large choice maps to 130%. Verify with the theme Python
suites and cargo test --offline --manifest-path nix/rust-shell-client/Cargo.toml.
Done 2026-10-16 on vision-steps; see docs/evidence/coherent-shell/accessibility-scale/README.md § Redesign.docs/evidence/coherent-shell/accessibility-scale/,
and a test that measures text height against card height.
Done 2026-10-16 (host); renders in docs/evidence/coherent-shell/accessibility-scale/steps/.grim
captures of Home, drawer, Shade, Settings and Vision, and the operator’s
legibility judgement on glass. Closes C.4 if accepted.
Progress 2026-10-16: captures at both steps (injected input, native grim)
are in docs/evidence/coherent-shell/accessibility-scale/board/13–23.
Result 2026-10-16 (operator on glass, landscape panel): accepted. “it’s
all good however the clock widget could use a redesign it’s got some text
too small to see really but yeah it’s good”. The clock widget’s small text
is outside this change (Home widgets keep their 100% sizes); it is
recorded as a limit in the evidence README.openspec validate the-shell-offers-quick-toggles-and-vision-options --strict. Passed
2026-09-28 on close/shell-umbrella.nix build .#nixosConfigurations.k230-coherent-shell.config.system.build.toplevel
(cross-build proof only, not board proof). The parent named the k230
toplevel. The Rust client and card shell are only in the opt-in
k230-coherent-shell configuration, so that configuration is the one that
exercises this code.
Done 2026-10-16 (cross-build only): from master 9d2135110c02, run
22:47:00Z–22:48:40Z, exit 0. Output
/nix/store/8w4p48rhqb001v15ndwxx72hh208i9wa-nixos-system-nixos-26.11.20260919.20b1ddd;
its closure contains k230-shell-rust and k230-card-shell. The board ran
the kernelMainlineDrmShellLandscapeHdmiBootFiles system instead (see the
accessibility-scale README).Grounding (2026-10-16): the first implementation offered one larger step
(1.25x). On the panel (568x1232 at 4.1”, about 331 ppi, 2.07 px per dp) the
default body text is 17-18 px (about 8.5 sp) and drawer labels are 14 px
(about 6.8 sp), roughly half of common phone defaults. The 1.25x step left the
drawer illegible to the operator: “the drawer is not particularly legible at
‘large’ text”, with labels ellipsized (“Same G…”) over a translucent drawer
that shows the Home clock and wallpaper through it
(docs/evidence/coherent-shell/accessibility-scale/board/11-panel-drawer.png).
Grounding (2026-10-16): the four steps and the reflow were host-tested and
rendered at every step in both orientations
(docs/evidence/coherent-shell/accessibility-scale/README.md, “Redesign”).
On the landscape panel, native grim captures at 160% and 200% of Home, the
drawer, the Shade, Settings and the Vision page are in board/13–23 of
that directory. The operator judged them legible on glass. Persistence across
a reboot was observed on the board with injected taps (board/06, 07).
The card-shell headers’ scaling is host-tested only
(tests/test_card_shell_appearance.py); no board capture of the card deck at
a larger step exists.
Settings SHALL offer a person four text-size steps, 100%, 130%, 160% and 200% of the shell’s design size, and a high-contrast palette variant. Both choices are independent of the theme currently active and of the existing reduced-motion toggle. The 200% step follows WCAG 1.4.4 (resize text). At every step, text SHALL reflow rather than be cut off: drawer labels wrap to at most two lines and the drawer uses fewer columns, and Settings and Shade cards grow to fit their text. A label is ellipsized only when it would exceed two lines at the chosen size. With any vision option other than the defaults, the drawer and Shade SHALL draw their text over an opaque surface, not a translucent one that shows Home through it, and app icons and their tap targets SHALL grow with the step up to at least 48 dp (99 px on this panel).
The chosen scale and contrast variant SHALL apply consistently to both the Rust-rendered surfaces (Home, drawer, shade, Settings) and the C-rendered card deck and its labels, using the same shared theme-token mechanism that already carries per-theme colors across that boundary, so a person does not get a larger Settings but an unchanged card header. Home widgets keep the proportions of their cells, so a widget’s contents are not scaled by the step; the Clock widget’s date, which follows the step, is the exception. The choice SHALL persist across restarts the same way the active theme choice already does.
Grounding (2026-10-16): host tests in service_ui.rs cover the keyboard
row’s hit region and its unavailable state (tasks B.1–B.3). On the board, with
injected pointer events on HDMI at 1280x800, the toggle was reachable, showed
and hid the keyboard with the Shade staying open, and showed “Unavailable”
and ignored a tap once wvkbd was stopped
(docs/evidence/coherent-shell/shade-quick-toggles/README.md). Brightness is
the existing Shade slider. Real-finger use and the DSI panel orientation were
not exercised.
The notification shade SHALL offer at least a brightness-step control and a
keyboard show/hide toggle directly in the shade, without requiring
navigation into Settings, reusing the same ControlState/ControlValue
and ServiceRequest types Settings’ own rows already send so the two
surfaces cannot disagree about a capability’s live state. An unavailable
capability SHALL render the same unavailable/read-only treatment the
Settings row for that capability already uses, not a silently missing
control.
ControlState is unavailable or read-onlyGrounding (2026-10-16): task B.5 gave every Shade tap target, including
“Dismiss all”, a hit region of at least 99 logical px, with a unit test that
asserts each region’s height (service_ui.rs). Host-tested only; no
real-finger measurement.
Every shade tap target, including “Dismiss all”, SHALL meet or exceed a
48dp-equivalent hit region on this panel’s measured density (~99 logical
px), independent of how much smaller its visible label is, consistent with
runtime/handheld-shell-design’s existing “Shared portrait shell language”
requirement’s own stated target once that target is corrected to the same
48dp-equivalent value (see this change’s companion critique,
docs/design/shell-ux-critique.md §7, for the arithmetic showing the
currently-stated “56 logical px” floor is only ~27dp, not “comfortably
above” 48dp as that requirement’s own text currently assumes).
Archived change · Archived
Snapshot 5836ef1d113d · 2026-10-17 08:22 UTC
Closed recordClosed on operator acceptance; see evidence for waived captures and retained limits.
The operator asked directly for a ruthless UX critique of this shell against
webOS and Android Material 3 Expressive, naming three examples: the card
switcher shows one card at a time, cards carry no icons, and swiping up from
the bottom of Settings does nothing. docs/design/shell-ux-critique.md
(this change’s companion document) traces all three to exact code and finds
15 ranked findings in total.
Most of what that critique found is not new scope. Two of the user’s
three examples — the Settings swipe-up dead end and the missing card icon —
are already fully specified by the open, unarchived
the-handheld-presents-a-coherent-shell change (runtime/handheld-shell-design
requirements “Shade and contextual Back preserve the task” and “Installed
application icons retain identity and privacy”) with matching tasks (2.2,
4.4, and 1.4) still [ ] open. Several more findings duplicate
docs/design/webos-polish-review.md’s already-filed P0-1/P0-2/P0-4/P1-1/
P1-2/P1-4. This change does not repeat any of that spec text or re-open
those tasks; it names them and stops.
What is left over — confirmed by grep across every open change’s
proposal.md/design.md (shell-ux-critique.md §5/§10 records the exact
searches) — is three findings that genuinely have no owner:
card-shell-policy.c:31-32,192-210) shows roughly
8.7% of a card’s width at each edge — a color swatch, not an identifiable
neighbor. the-handheld-presents-a-coherent-shell’s “Bottom app switching
follows both touch axes” requirement governs the drag gesture’s feel
(“a full or near-full app carousel”), a deliberate choice recorded in its
design.md decision 11; it does not claim anything about the released,
idle deck’s legibility, and nothing else does either.This change turns those three, and only those three, into requirements.
Addendum (slice E): a later, more literal operator report on the same
example this proposal already named — “if in settings swiping up from
bottom does nothing it should be like any app really” — found that
the-handheld-presents-a-coherent-shell tasks 2.2/4.4 (the routing this
proposal pointed to above) remain open, and identified the exact single
cause: nix/card-shell/adapter.c’s input_down cedes every touch to a
mapped Drawer/Shade/Settings overlay before the compositor’s own
bottom-edge recognizer runs, at all, for any of the three overlay surfaces.
Rather than wait on or duplicate tasks 2.2/4.4’s larger, still-unspecified
side-edge Back mechanism, this addendum adds a narrower, bounded,
independently implementable fourth slice with its own requirements, host
and QEMU evidence: the bottom-edge gesture wins over any mapped overlay
(reaching the overview or switching apps exactly as from an app, from any
Settings sub-page), Settings’ own local dismiss gesture is fixed to agree
with Shade’s direction, and Settings’ relationship to the card overview
(not a card) is decided and recorded. Unlike slices A-D, slice E has
already been implemented, not merely specified — see tasks.md group E.
the-handheld-presents-a-coherent-shell task 1.4 (real card icons)
directly, rather than merely widening room for it, and is implemented as
the same CS_DECK mode and gestures — not a second, separately-entered
Overview destination (see design.md decision 1). The direct bottom-edge
app-switch gesture’s own geometry is explicitly decoupled from the
deck’s new card size so its existing feel (30% threshold, flick,
1:1 tracking, full-size neighbour) is unaffected.ServiceRequest/PanelIntent plumbing already used for these same actions
inside Settings.the-handheld-presents-a-coherent-shell design decisions 11/12)
unchanged; adds no new gesture, only fixes which surface a touch in the
existing qualified bottom edge band is routed to.None. All requirements are ADDED to capabilities other open changes
already introduce (runtime/card-shell, runtime/notification-center,
runtime/device-settings, and — slice E only —
runtime/handheld-shell-design from the-handheld-presents-a-coherent-shell);
none of those capabilities is archived yet, so each ADDED requirement here
is additive to those changes’ own deltas, the same pattern
the-shell-loads-omarchy-themes and
the-shell-swaps-themes-without-a-python-stall already use for
runtime/shell-themes.
None.
the-handheld-presents-a-coherent-shell tasks 2.2
and 4.4, still open; slice E’s bottom-edge escape and dismiss-direction
fix are bounded, narrower fixes that do not complete those tasks.the-handheld-presents-a-coherent-shell for any
remaining drawer/notification-side or shared-resolver-architecture work
(this slice’s resolver, nix/card-shell/icon.c, is independent of the
drawer’s own icon.rs, not a shared process — see design.md’s
Non-Goals).docs/design/webos-polish-review.md P0-1 (not an OpenSpec change; a
correction against currently shipped code with no open proposal of its
own — a future change may be needed to formalize it, which is outside
this proposal’s scope).docs/design/webos-polish-review.md
P0-2/P0-4/P1-1/P1-2/P1-4, same as above.shell-ux-critique.md §6/§11, routed to
the-handheld-presents-a-coherent-shell task 4.5’s existing scope; not
new requirements here.the-handheld-presents-a-coherent-shell/design.md decision 2) — flagged
as a recommendation for the coordinator in shell-ux-critique.md §4, not
acted on here without explicit authorization to reverse a recorded
rejection.design.md decision 1) — the webOS-fan card sizing this slice
implements lives inside the existing CS_DECK mode and gestures, which
is exactly the property that keeps it a bounded slice rather than the
full redesign a second destination would be.Userspace only, split across the two existing shell processes:
nix/card-shell-policy/card-shell-policy.c
(cs_default_config, the deck layout math, the new
entry_card_width/entry_card_height/cs_entry_target_rect split, and
scroll momentum), nix/card-shell/adapter.c (icon/name resolution,
header layout, the two cs_entry_set_geometry call sites) and
render.c (the new card_icon_header), plus a new
nix/card-shell/icon.c/.h (no new library dependency — Cairo’s native
PNG decoder only) registered in nix/card-shell.nix/
nix/patches/sway-k230-card-shell.patch. No device tree, kernel, boot,
radio, or second-core change.nix/rust-shell-client/src/service_ui.rs
(panel_intent’s Route::Shade arm) and render.rs (Shade painting) only;
reuses the existing ServiceRequest::Brightness/KeyboardToggle request
types already wired to service_data.rs, so no new IPC surface is needed.service_data.rs, render.rs) and the theme-token pipeline shared with
nix/card-shell/render.c, so both renderers pick up the chosen scale/
contrast consistently — the same cross-renderer consistency gap
webos-polish-review.md P1-1 already flags for fonts generally.nix/card-shell/adapter.c (input_down’s drawer_mapped() carve-out,
prepare_impl’s cancel-on-remap guard, a new shell.overlay_escaping
flag) and nix/card-shell/route.c (card_shell_launch_surface accepts
"hide"). The dismiss-direction fix touches
nix/rust-shell-client/src/service_ui.rs (panel_intent’s Route::Shade
and Route::Settings arms, now sharing OVERLAY_DISMISS_ZONE_Y/
OVERLAY_DISMISS_DY). Neither touches the overview’s card geometry or
headers, deliberately, since another agent owns that work concurrently.Host model tests (cargo test --manifest-path nix/rust-shell-client/Cargo.toml --locked, the existing tests/test_card_shell_state.py /
test_card_shell_gestures.py C fixtures) and narrow nix build derivation
proofs can all proceed without the board, per each task group below. Real-
finger legibility (is the new peek width actually readable at arm’s length;
does the new accessibility text scale actually help), touch-target size for
the new shade toggles, and on-glass contrast checking are physical
acceptance gates that remain open and unverified until a board reservation
records them, consistent with every sibling change’s own evidence
discipline. Slice E’s own physical acceptance (does the bottom-edge escape
and unified dismiss direction feel right on real glass, from a real finger)
is likewise open and unverified — see task E.4.
This proposal originally made no source changes; it was planning only,
produced under AGENTS.md’s instruction that several other agents are
concurrently editing the compositor and the Rust shell. Two slices have
since been implemented as authorized follow-ons: slice A (deck legibility,
superseded to the user’s chosen webOS-fan direction — see tasks.md
A.1-A.3 and docs/evidence/card-shell/webos-fan-switcher/) and slice E
(bottom-edge overlay escape and consistent dismiss direction — host- and
QEMU-tested, its commands recorded in tasks.md). Each keeps its own board
acceptance task open (A.4, E.4). Slices B and C (shade quick toggles,
vision accessibility) remain planning-only.
The operator accepts this delivered functional scope and waives additional
capture-only acceptance gates. docs/evidence/proposal-closeout/2026-10-01/coherent.md records the exact report,
prior evidence and limits. Its task dispositions supersede older statements
that these acceptance gates remain open; they do not claim new test runs.
This change is the OpenSpec half of a pair with
docs/design/shell-ux-critique.md, requested directly by the operator: “can
you have an agent really nitpick the shell design compared to webos/android
material expressive.” That document’s §12 ranks 15 findings; this change
implements only the three that have no existing owner (§0/§12 there explains
the routing for the other twelve). It targets capabilities three other open,
unarchived changes already introduce (runtime/card-shell from
the-shell-manages-apps-as-cards, runtime/notification-center and
runtime/device-settings from the-handheld-presents-a-coherent-shell),
adding further ADDED requirements to each rather than creating new
capability names — the same pattern the-shell-loads-omarchy-themes and
the-shell-swaps-themes-without-a-python-stall already use for
runtime/shell-themes.
Slice E was added later, from a second, more literal operator report on the
same finding this change’s companion critique already named: “if in
settings swiping up from bottom does nothing it should be like any app
really.” That is shell-ux-critique.md finding #1 (P0), already routed in
this change’s original text to the-handheld-presents-a-coherent-shell
tasks 2.2/4.4; those tasks remain open (they cover the larger, still-
unimplemented side-edge contextual Back mechanism), so slice E targets the
narrower, immediately actionable defect those tasks’ own evidence already
names — nix/card-shell/adapter.c:2130’s unconditional
if (drawer_mapped()) return false; — with a bounded touch-routing and
Rust-surface fix, rather than waiting on or duplicating that larger change.
It adds a fourth capability target, runtime/handheld-shell-design (from
the same sibling change as notification-center/device-settings), to the
three this change already touched, following the identical ADDED-only
pattern.
This change makes no source changes for slices A-D; slice E is a real,
implemented, host- and QEMU-tested fix (see tasks.md group E), authorized
directly against the operator’s report per AGENTS.md’s instruction to
continue through bounded, authorized implementation rather than holding it
behind further proposal-only cycles. Slices A-D remain planning only,
produced while other agents concurrently edit the compositor and Rust
shell; per AGENTS.md, they should be validated and handed to the
coordinator promptly rather than held back for implementation.
Goals: name a bounded, independently-implementable fix for each of the
three genuinely unowned findings from shell-ux-critique.md; keep each fix
small enough to land without touching the gesture state machines several
other in-flight branches (fix/app-switch-swipe, fix/bare-app-cards,
impl/direct-app-switch, fix/direct-drag, perf/theme-background-decode,
per python3 tools/work-status.py at proposal time) are actively changing.
Non-Goals: re-specifying anything the-handheld-presents-a-coherent-shell
already specifies beyond the card-header icon piece this slice now folds in
(navigation-gesture consistency and non-color pressed states remain that
document’s still-open tasks 2.2/4.4 — not touched here); re-deriving any
webos-polish-review.md finding; reopening the recorded “search remains
deferred” decision; a second, separately-entered Overview destination
distinct from the existing deck (still rejected — see decision 1’s
2026-09-25 update: the webOS-fan card sizing lives inside the same
CS_DECK mode and gestures, not a new screen); haptic feedback (no
actuator on this board, per motion-research.md’s schematic search);
battery/telephony; live appearance-driven icon-theme switching for card
headers (nix/card-shell/icon.c reads K230_ICON_THEME once; threading
the active theme’s own icon set to the C compositor over the existing
card_appearance IPC, which today carries only colors, is the
cross-boundary resolver architecture shell-ux-critique.md #1.2 flagged as
undesigned — still undesigned after this slice, left for a future change).
Superseded 2026-09-25: fix deck legibility with a webOS-style card
“fan” inside the existing deck, not by merely widening its peek, and not
by adding a second, separately-entered Overview mode. The user was
shown both options — the originally-planned “widen the existing single-
card peek” (below, kept for record) and the richer multi-card option
illustrated in docs/design/shell-ux-critique-switcher.svg — and chose
the richer direction, with one constraint: it must not be a second,
separately-entered destination. The shipped shape is still the same
CS_DECK mode and the same entry/exit gestures (bottom-edge swipe up,
tap-to-expand, flick-to-close) — no fourth state machine, no new
affordance to enter it — but the deck’s own card geometry shrinks to
roughly 46% of the panel width (card_width/card_height/gap in
cs_default_config, nix/card-shell-policy/card-shell-policy.c) so 2-3
cards sit on screen at once with a legible peek on each side, each
carrying a resolved icon and app name in a header above it (task 1.4 of
the-handheld-presents-a-coherent-shell, folded into this slice — see
“Modified Capabilities” below). This still satisfies the original
requirement text (“enough of each neighbor to identify it”) with a wider
margin than a minimally-widened single-card peek would have.
The direct bottom-edge app-switch gesture (cs_begin_entry/
cs_entry_motion/cs_entry_up_at) is a different destination
(entered from inside an app, not from the deck) that the user separately
confirmed must keep its exact current feel: a 30% width threshold, flick
velocity, 1:1 tracking, and a full-size neighbour mid-switch. Because
that gesture’s geometry (cs_entry_set_geometry’s target, via the new
cs_entry_target_rect) previously came from the same card_width/
card_height the deck now shrinks, cs_config splits them:
entry_card_width/entry_card_height keep the old near-full-screen
slot the direct-switch gesture anchors against, independent of the
deck’s own (now smaller) card size. entry_anchor_shift_y (new,
mirroring the existing x-axis entry_anchor_shift) corrects the
resulting height mismatch in cs_entry_visual_rect’s vertical
interpolation so a plain swipe-up-to-enter-deck gesture still tracks the
finger exactly, not just the lateral switch. tests/card_shell_policy_driver.c
confirms this: every direct-switch test case (two-axis-entry,
two-axis-conflicts, direct-carousel, app-switch-swipe,
tracked-entry, tracked-expansion) keeps its original numeric
assertions unchanged, because entry_geometry()’s helper now builds
cs_entry_set_geometry’s target from cs_entry_target_rect() (numerically
identical to the old single-field geometry) instead of cs_card_rect().
The deck’s own horizontal scroll also gained momentum + snap (a released
drag coasts via cs_tick-driven scroll_settling/scroll_from_dx
toward the newly-selected card’s rest position, and a decisive flick
pages under the plain distance threshold via select_flick_speed) — a
physics improvement the smaller, tighter-packed cards make more
noticeable, not a new requirement of its own.
Original 2026-09-24 decision, superseded above, kept for record: fix
deck legibility by widening the existing peek, not by adding a second
Overview mode. Considered alternative: a distinct multi-up grid
“Overview” screen (illustrated as one option in
docs/design/shell-ux-critique-switcher.svg’s proposed panel, closer to
webOS/LuneOS’s Exposé-like views or Android’s grid-style recents) entered
from its own affordance, separate from the existing single-card deck.
Rejected for that bounded proposal: it is a new navigation destination
(a fourth state machine layered on the three shell-ux-critique.md §2
already found: C card policy, Rust overlay routes, Rust Home surface),
with its own entry/exit gestures, its own empty/loading/private states,
and its own physical-acceptance gate — a full redesign, not a narrow
slice, and it risks re-litigating the-handheld-presents-a-coherent-shell
design decision 11’s carousel geometry rather than sitting beside it.
Widening the existing deck’s peek fraction was scoped as a single-
function change (cs_default_config’s card_width/gap, and the
layout math that consumes them) with no new state, no new gesture, and
no new screen. The user’s subsequent choice above keeps that same
“no new destination” property while going further on card size/count,
which the risk this decision flagged (re-litigating design decision 11)
is addressed by the entry_card_width/entry_card_height split, not by
staying conservative on card size.
Shade quick toggles reuse existing request types instead of a new
settings/notification bridge. The shade already has an IPC path to the
same service broker Settings uses (ServiceRequest, service_data.rs);
adding shade-side UI that sends the identical ServiceRequest::Brightness/
KeyboardToggle values Settings already sends avoids inventing a second
capability-state protocol. Rejected alternative: a shade-only
“mini-settings” model with its own state — rejected because it would
duplicate ControlState’s unavailable/read-only/pending semantics
(the-handheld-presents-a-coherent-shell’s “Settings expose only
supported state and actions” requirement) instead of reusing them.
Accessibility text-scale/contrast rides the existing theme-token
pipeline rather than inventing a second styling mechanism. Both
renderers already consume theme tokens for color
(webos-polish-review.md P1-1 documents the two renderers’ font
declarations are separately hand-rolled, which is exactly the failure
mode this decision avoids repeating for scale/contrast). Extending that
existing shared pipeline, rather than adding a Rust-only or C-only
scale mechanism, is what makes the “applies to card headers too” scenario
in the device-settings delta possible at all.
Claim the bottom-edge escape at the compositor’s touch-routing layer,
not inside the Rust overlay’s own route/page dispatch. Considered
alternative: give Route::Settings (and Drawer/Shade) their own
bottom-edge-swipe-up case in service_ui.rs’s panel_intent, mirroring
how each route already recognizes its own local dismiss swipe. Rejected:
panel_intent only ever sees touches the compositor has already decided
to forward to the client; the operator’s literal report (“if in settings
swiping up from bottom does nothing it should be like any app really”)
and shell-ux-critique.md S1.1’s trace both locate the actual defect one
layer lower, in nix/card-shell/adapter.c’s input_down, which cedes
the touch to the overlay (drawer_mapped()) before the compositor’s own
recognizer ever runs. Fixing it there instead of in the Rust client has
two consequences worth recording: it reuses the exact same thresholds
and code path (cs_begin_entry/cs_edge_down) an app already gets, so
“the same as any app” is true by construction rather than by a second,
parallel implementation that could drift; and it applies uniformly
regardless of which Settings sub-page (theme chooser, Wi-Fi, password
entry) is currently showing, since the compositor’s drawer_mapped()
check does not distinguish sub-pages — closing shell-ux-critique.md
S2’s “dead ends three levels deep” finding as a side effect, with no
separate per-page fix needed. The overlay is told to dismiss itself via
the pre-existing Route::Hide (already reachable from the command line
as k230-shell-rust --surface hide, which is how the coordinator’s own
testing closed a stuck Settings panel before this fix existed) rather
than a new IPC message, spawned the same fire-and-forget way the
compositor already launches the drawer/shade overlay
(card_shell_launch_surface, nix/card-shell/route.c). Because that
spawn is asynchronous, the compositor also needs to tolerate
drawer_mapped() still reading true for a frame or two after the escape
gesture legitimately starts, without letting its own defensive
cancel-on-remap cleanup (prepare_impl, originally written to drop
stale pre-existing drags when an overlay newly maps) discard the
gesture it just started on the overlay’s behalf; a small
shell.overlay_escaping flag distinguishes the two cases.
Unify Shade and Settings’ own local dismiss gesture; leave the
Drawer’s alone. shell-ux-critique.md S2 flagged three different,
independently hand-tuned dismiss predicates (Drawer down, Shade up,
Settings down) as evidence of three uncoordinated navigation state
machines. The fully general fix that critique and
the-handheld-presents-a-coherent-shell design decision 4 both point
toward is a single side-edge contextual Back gesture (that change’s task
2.2); this change does not implement that larger mechanism, which needs
its own edge-ownership arbitration across the compositor and both
overlay clients. What this change does fix, narrowly: Settings and Shade
are both top-anchored sheets reached through the same downward path
(Settings opens from within the shade — decision 3 of
the-handheld-presents-a-coherent-shell/design.md), so there was never
a reason for them to disagree, and Settings’ downward direction was
simply copied from the Drawer’s convention without noticing the two
surfaces anchor to opposite edges. Flipping Settings to match Shade
(both dismiss on an upward drag near the top) removes one of the three
inconsistent predicates entirely; the Drawer’s downward,
scrolled-to-top-only convention is left unchanged because it anchors to
the bottom edge and reversing it to match Shade/Settings would put it
in direct conflict with scrolling the drawer’s own content upward.
Settings behaves like an app without being a card. The operator’s
report frames the goal as “it should be like any app really.” Read
narrowly as a touch-routing complaint (decision 4 above), that is now
true. Read as “should Settings appear in the card overview like webOS’s
Settings card, or Android’s Settings-in-recents,” the answer is no, for
an architectural reason that predates this change and is not being
revisited here: this shell’s card overview represents the sibling
the-shell-manages-apps-as-cards implementation’s live, backgroundable
toplevel windows (CS_LIVE content), each with its own eligibility,
privacy, and close lifecycle; Settings is a layer-shell overlay
(namespace k230-shell-drawer), the same kind of transient surface as
the Drawer and Shade, with no backgroundable process or live pixels a
card could represent. webOS’s Settings genuinely was an ordinary
card-switchable application. Android’s standalone Settings app is a real
Activity with its own task and does appear in recents — but this shell’s
Settings, reached only through the shade and closed with it, is a much
closer match to Android’s own Quick Settings panel, which is not
represented in recents either. Making Settings a literal card would mean
giving a transient overlay a live-source/focus/privacy contract designed
for real applications, a materially larger change than this proposal’s
bounded slices, and the other agent currently reworking the overview’s
own card geometry and headers makes this an especially poor moment to
add a new kind of card to that model. The bottom-edge escape (decision
4) already delivers the touch-routing behavior “like any app” that
prompted the request; runtime/card-shell’s new requirement in this
change’s spec delta makes the “not a card” half of this decision
testable rather than merely asserted here.
the-handheld-presents-a-coherent-shell design decision
11’s “full or near-full app carousel” language during the direct-switch
two-axis drag. This proposal’s requirement is scoped to the released,
idle layout only (see its “mid-drag” scenario) specifically to avoid
touching that decision; the implementation confirms the drag-time
geometry stays independent of the idle deck’s card size via the
entry_card_width/entry_card_height/cs_entry_target_rect split
(decision 1) rather than merely asserting it from this document — proven
by tests/card_shell_policy_driver.c’s direct-switch cases keeping their
original numeric assertions unchanged.tasks.md), not fixed numbers here, because
neither can be justified from a source read alone — both need a rendered
comparison at minimum, and ideally on-glass legibility confirmation, per
shell-ux-critique.md §14.the-handheld-presents-a-coherent-shell still plans.None — additive UI only, no data format, protocol, or persisted-state
changes beyond the new text-scale/contrast preference, which follows the
existing theme-choice persistence mechanism already in place. Slice E
(bottom-edge overlay escape and dismiss-direction consistency) is likewise
additive touch-routing behavior with no persisted state; it does not
replace or complete the-handheld-presents-a-coherent-shell tasks 2.2/4.4,
which remain open for the general side-edge Back mechanism.
The operator accepts this delivered functional scope and waives additional
capture-only acceptance gates. docs/evidence/proposal-closeout/2026-10-01/coherent.md records the exact report,
prior evidence and limits. Its task dispositions supersede older statements
that these acceptance gates remain open; they do not claim new test runs.
Three independent slices (A, B, C) plus a shared evidence/spec task, plus a
fourth slice (E) added later and already implemented. Each slice touches a
disjoint file set and can be implemented, tested, and landed in parallel by
separate worktrees without coordination beyond the usual
python3 tools/work-status.py check, per AGENTS.md. Slice A’s host/QEMU
tasks (A.1-A.3) and slice E’s host/QEMU tasks are ticked with their
evidence. Every slice’s board task (A.4, E.4) is left open per AGENTS.md’s
“do not tick physical tasks” and the k230-spec-change skill’s QEMU-vs-board
distinction.
Slices B and C moved 2026-09-28 (user-authorized scope split, “yes a-d
and f”): every B/C task (B.1-B.4, C.1-C.4) is now ticked
[x] ... MOVED, NOT PERFORMED HERE and carried forward verbatim into the
successor the-shell-offers-quick-toggles-and-vision-options. No B/C code
exists in this change; the tick means the task’s ownership moved, not that
the work was performed here. This parent’s runtime/device-settings and
runtime/notification-center spec deltas, which existed solely for slices
B/C, have been removed from this change (they now live only in the
successor).
Superseded 2026-09-25: the user chose the richer webOS-fan direction
(2-3 small cards visible, real icon + app name header per card) over the
originally-scoped “widen the existing single-card peek,” on the condition
that it stay the same CS_DECK mode/gestures, not a second destination —
see design.md decision 1’s superseding note. This also folds in the
C-compositor half of the-handheld-presents-a-coherent-shell task 1.4
(real card-header icons): that task’s own architecture note (“needs a
resolver reachable from the C compositor… build or share an icon
resolver on both sides of the Wayland boundary”) is resolved here as an
independent, PNG-only resolver (nix/card-shell/icon.c), not a shared
process/library with nix/rust-shell-client/src/icon.rs — see that task’s
own tracking for whether to unify them later.
card_width ≈ 46% of panel width (.5*(width-2*inset)), card_height
sized close to the panel’s own portrait aspect, gap=10, giving 2-3
cards visible with a >30%-of-card-width neighbor peek at the real
568×1232 panel. Recorded in card-shell-policy.c’s cs_default_config
comments and the policy driver’s overview-geometry test case (below).
valid_config()’s bounds extended for the new independent
entry_card_width/entry_card_height fields and still accept the
chosen sizes.cs_default_config and the deck layout math
(card-shell-policy.c) to the webOS-fan size, and split the direct
bottom-edge app-switch gesture’s own geometry into
entry_card_width/entry_card_height (a new cs_entry_target_rect(),
used by both nix/card-shell/adapter.c call sites that previously fed
cs_entry_set_geometry from the shared cs_card_rect) plus a new
entry_anchor_shift_y vertical tracking correction, so the two-axis
carousel’s “full or near-full” feel, 30% threshold, flick velocity and
1:1 tracking are provably unaffected (tests/card_shell_policy_driver.c’s
two-axis-entry/two-axis-conflicts/direct-carousel/
app-switch-swipe/tracked-entry/tracked-expansion keep their
pre-existing numeric assertions unchanged). Also added momentum + snap to
the deck’s own horizontal scroll (scroll_settling/scroll_from_dx,
select_flick_speed) and two new cases, overview-geometry and
scroll-momentum. Verify: python3 -m unittest test_card_shell_state
(run from tests/) — 31/31 cases pass.nix/card-shell/adapter.c’s desktop_identity_icon (extends the
existing .desktop Name= parser to also read Icon= in the same file
pass) plus new nix/card-shell/icon.c (freedesktop icon-theme
resolution — index.theme Directories=/Inherits= scoring, hicolor
fallback, pixmaps/ fallback, PNG-only via Cairo’s native decoder, no
gio/gdk-pixbuf dependency — mirroring icon.rs’s algorithm), wired
through render.c’s new card_icon_header (real icon, falling back to
the existing letter badge when none resolves). Verified standalone
against the real installed Yaru/hicolor icon paths for foot/htop/folder
before wiring into the build. Card labels/icons stay within render.c’s
existing clipping (label_clip, clip_box) at the new card width.
Verify: nix build .#card-shell --max-jobs 1 --cores 6 --no-link --print-out-paths (succeeds) plus the headless-QEMU captures below.w51crww9, one a real-glass scroll
report): (a) cards were too small (~45% of the panel’s own height per
the board, sitting flush under the title with about half the panel
empty below) — resized to ~50% of the panel width and 60% of its height
(55-65% requested), vertically centered between the title and the
footer hint via a new card_top_offset (cs_card_rect’s y anchor,
replacing a fixed inset there only — inset itself and
cs_entry_target_rect are unchanged), with a new entry_anchor_shift_y
term correcting the direct-switch gesture’s y-tracking for the resulting
overview/entry y-offset mismatch (previously only height was corrected).
(b) Icon/label sizes increased (32-40px icon, a 20px label consistent
with the chrome’s own type scale, ellipsis already handled by the
existing Pango layout). (c) The overview’s own card raises to the top of
its scene stacking order in CS_DECK, not just CS_ENTERING/
CS_EXPANDING, as a defensive z-order fix. (d) The board report’s real
gap — “Monitor” showed a letter badge, not a real icon, under the real
installed theme — was PNG-only decoding missing an SVG-only resolution
path; nix/card-shell/icon.c now decodes SVG via librsvg (linked
directly, the same two calls icon.rs uses, no gio/gdk-pixbuf), and
follows the active theme’s own icon_theme (report.json, via
appearance_apply), not just K230_ICON_THEME. (e) The real-glass
scroll report — “i can’t flick to swipe through multiple cards quickly,
it snaps to each card as i go” — was the deck’s momentum coast being
limited to ±1 card; replaced with a velocity-projected physics fling
(CS_SCROLL_OMEGA) that can carry several cards, reusing the direct
bottom-edge app-switch gesture’s own recency-windowed velocity estimator
(touch_window_span, factored out of entry_release_velocity) via a
separate scroll_history buffer; a slow release still snaps to the
nearest card; a fresh touch mid-coast catches it and continues 1:1 (no
jump, via a new cs_down catch path); the ends clamp with a soft
rubber band (a damped, shorter coast), not a hard stop. Also fixed a
latent bug this pass’s own QEMU capture caught: adapter.c’s runtime
card-height recompute had its own stale copy of an old fraction that
silently overrode the policy default. Verify: python3 -m unittest test_card_shell_state (run from tests/) — 34/34 cases pass, including
four new scroll-physics cases (scroll-fling-multi-card,
scroll-slow-release-snaps-nearest, scroll-catch-mid-coast,
scroll-end-clamp-soft) and every direct-switch case with unchanged
numeric assertions; nix build .#card-shell --max-jobs 1 --cores 6
succeeds; recaptured headless-QEMU evidence
(docs/evidence/card-shell/webos-fan-switcher/, dark+light) with an
“ordinary maximized” app-window fixture (card_shell ordinary,
floating enable, resize set 100 ppt 100 ppt, move position 0 0,
matching production) that also incidentally resolved an odd-looking
overlapping-card artifact and a broken composite “opened” frame in the
prior capture generation, both traced to that earlier capture’s smaller,
inconsistent floating-window fixture size, not to card-shell itself.Route::Shade’s layout
(render.rs, the Route::Shade branch) for brightness step and keyboard
show/hide, reusing ControlState/ControlValue exactly as Settings’
existing rows do (service_data.rs). Scope split authorized by the user
on 2026-09-28 (“yes a-d and f”): carried forward into the successor
the-shell-offers-quick-toggles-and-vision-options’s own task B.1, which
also records that the brightness half is superseded by the shade slider
the-brightness-control-is-a-slider already added — only the
keyboard-toggle half remains to build there. Nothing here is implemented;
that work is not done, only relocated.panel_intent’s Route::Shade arm (service_ui.rs:279-320)
with hit-testing for the new toggles, sending the same
ServiceRequest::Brightness/KeyboardToggle values Settings already
sends, gated on the same ControlState the Settings row already checks.
Carried forward into the successor’s own task B.2 (keyboard-toggle only,
brightness already superseded per B.1’s note).service_data.rs) and persistence (following the existing theme-choice
persistence mechanism). Scope split authorized by the user on 2026-09-28
(“yes a-d and f”): carried forward verbatim into the successor
the-shell-offers-quick-toggles-and-vision-options’s own task C.1.render.rs (Home/drawer/shade/Settings) and
nix/card-shell/render.c (card headers) apply it consistently; this is
the same cross-renderer boundary webos-polish-review.md P1-1 already
names for fonts, so reuse rather than duplicate whatever token-passing
mechanism that finding’s eventual fix establishes if it lands first.
Carried forward into the successor’s own task C.2.docs/evidence/coherent-shell/accessibility-scale/. Carried
forward into the successor’s own task C.3.cs_begin_entry/cs_edge_down (app-entry) and drawer-reveal recognizers
even while a Rust overlay (Drawer/Shade/Settings/any sub-page) is mapped,
instead of unconditionally ceding the touch
(nix/card-shell/adapter.c input_down’s drawer_mapped() bail); signal
the overlay to dismiss via the pre-existing Route::Hide
(card_shell_launch_surface, now also accepting "hide" —
nix/card-shell/route.c); protect the claimed gesture from
prepare_impl’s defensive cancel-on-remap cleanup during the helper’s
asynchronous round-trip via a new shell.overlay_escaping flag. Verify:
nix build .#card-shell --max-jobs 1 --cores 6 --no-link --print-out-paths,
python3 tests/test_card_shell_route.py,
python3 -m unittest test_card_shell_state (run from tests/, 29/29,
unaffected — this task does not touch card-shell-policy.c),
python3 tests/test_card_touch_routing.py --sway <unwrapped card-shell sway> (7/7 existing cases unaffected), and
CARD_SHELL_SWAY=<unwrapped sway> CARD_SHELL_CLIENT=<probe client> python3 tests/test_card_shell_two_axis_runtime.py (already-approved
two-axis mechanics unaffected).cs_begin_entry claims it, the overlay unmaps);
from Settings mapped over a focused app with a second app running, a
bottom-edge sideways swipe switches directly to the neighbour app; a tap
on Settings’ own top-area Close control is unaffected (no compositor-side
card entry fires for it); a downward swipe near the top no longer
dismisses Settings and an upward one does. New test:
tests/test_rust_overlay_bottom_escape_runtime.py. Verify:
python3 tests/test_rust_overlay_bottom_escape_runtime.py --sway <unwrapped card-shell sway> --rust <handheld-shell-rust k230-shell-rust> --client <card-composition-probe-client> --output <dir>. A negative control against
the unmodified pre-fix adapter.c/route.c reproduces the reported bug
(times out waiting for the compositor to claim the gesture at all). See
docs/evidence/coherent-shell/overlay-bottom-escape-qemu/README.md.OVERLAY_DISMISS_ZONE_Y/
OVERLAY_DISMISS_DY); leave the Drawer’s bottom-anchored,
scrolled-to-top-only downward convention unchanged
(nix/rust-shell-client/src/service_ui.rs panel_intent). Verify:
cargo test --manifest-path nix/rust-shell-client/Cargo.toml --locked
(172/172 lib tests plus the new
service_ui::tests::shade_and_settings_share_one_upward_dismiss_direction
case; full workspace 219/219), and E.2’s QEMU command (scenarios 3-4 cover
this end to end with real injected touch, not just the unit model). D.1 Validate this change: openspec validate the-shell-behaves-as-one-coherent-system --strict.
D.2 Run nix build .#nixosConfigurations.k230.config.system.build.toplevel --no-link --print-out-paths --max-jobs 2 --cores 8: passed, producing /nix/store/p0gzcaa6bfqblzzqdcfpqznmq8x2wd28-nixos-system-nixos-26.11.20260919.20b1ddd. Cross-build only, not deployment or boot proof. Source base ea40ee5d contains the accepted implementation.
D.3 Close A/E using the committed operator acceptance and capture waiver. Preserve the previously authorized B/C successor the-shell-offers-quick-toggles-and-vision-options; this archive makes no claim that its quick-toggle/accessibility work is finished.
The updated completed tasks describe actual acceptance, waivers and scope
transfer, not execution of the superseded protocols. See docs/evidence/proposal-closeout/2026-10-01/coherent.md.
Historical checkpoint notes above that say physical gates remain open are
superseded by this record. Quantitative or individually unreported results
are not promoted to physical proof.
Proof: openspec validate the-shell-behaves-as-one-coherent-system --strict; committed operator report;
python3 scripts/render_work_board.py --working-tree --output <snapshot.json>.
Grounding: operator acceptance in docs/evidence/proposal-closeout/2026-10-01/coherent.md, with prior source and board/QEMU evidence retaining their original classes and limits.
While the card overview (CS_DECK mode) is settled and not being dragged,
the compositor SHALL lay out its cards as a horizontal, center-selected row
sized so that 2-3 cards are visible at once on the real panel: a center card
roughly half the panel’s width and 55-65% of its height, vertically
centered in the space between the title and the “Swipe up for apps” hint
(not sitting flush under the title), with a gap tight enough that each
visible neighbor’s icon and part of its name are identifiable without
paging to it, matching the user’s chosen webOS-fan direction over both the
prior single-card deck and a distinct, separately-entered grid Overview
mode. Each card SHALL carry a header above it containing: the app’s icon at
a legible size (32-40 logical px), resolved through the same installed icon
theme the drawer uses (its .desktop Icon=, in any representation that
theme ships — PNG or SVG — never a letter badge when a themed icon
resolves) and following the active theme’s own icon-theme selection when it
names one; and the app’s name, resolved from its .desktop Name= (never
the live window title), at a size consistent with the shell’s own
typography scale and legible at arm’s length, truncated with an ellipsis
rather than overflowing. This requirement governs the idle overview’s
static layout and header content; it does not change the two-axis drag/
quick-switch (direct bottom-edge app-switch) gesture’s own geometry,
thresholds, or feel, which stays governed by the “direct app switch keeps
its geometry independent of the overview’s card size” requirement below and
the-handheld-presents-a-coherent-shell design decision 11.
.desktop entry, or its entry’s Icon=
does not resolve to a themed icon filecs_motion/cs_entry_motion paths)Grounding: operator acceptance in docs/evidence/proposal-closeout/2026-10-01/coherent.md, with prior source and board/QEMU evidence retaining their original classes and limits.
The direct bottom-edge app-switch gesture (swiping sideways along the
bottom edge from inside an app) SHALL keep its existing feel — a 30% of
panel width distance-or-flick threshold, 1:1 finger tracking, and a
full-size neighbor visible mid-switch — regardless of the card overview’s
own card size. The policy’s entry-gesture geometry (the anchor/travel
computation cs_entry_set_geometry establishes, and the vertical/
horizontal finger-tracking correction terms that depend on it) SHALL be
computed from a fixed, near-full-screen target independent of the
overview’s card_width/card_height, so a future change to the overview’s
card sizing cannot silently perturb this gesture’s thresholds or tracking
accuracy.
card_width/card_height in
cs_config) changesGrounding: operator acceptance in docs/evidence/proposal-closeout/2026-10-01/coherent.md, with prior source and board/QEMU evidence retaining their original classes and limits.
Reaching the card overview from Settings (per this change’s bottom-edge escape requirement above) SHALL dismiss Settings and reveal the overview’s existing cards; Settings itself SHALL NOT appear as a selectable card in the deck, before or after that dismissal. Settings is reached through the shade, not launched as a running application, and carries no backgroundable process or live source a card could represent — unlike webOS’s own Settings, which ran as an ordinary card-switchable application, and unlike Android’s standalone Settings app, which is a real backgroundable Activity with its own task. Architecturally, this shell’s Settings is closer to Android’s Quick Settings panel (attached to, and dismissed with, the notification shade) than to either of those standalone apps, and Quick Settings is not represented in Android’s recents/overview either. The bottom-edge escape requirement above already gives Settings the touch-routing behavior a person expects from “acting like any app” — leaving the overview’s cards to represent only actual running, focusable applications keeps the overview’s existing live-source/focus/privacy contract (owned by the sibling live-card implementation) unextended to a surface that has none of those properties.
Define coherent navigation between the card overview and transient shell surfaces, including uniform bottom-edge escape and overlay dismissal.
Grounding: operator acceptance in docs/evidence/proposal-closeout/2026-10-01/coherent.md, with prior source and board/QEMU evidence retaining their original classes and limits.
docs/design/shell-ux-critique.md S1.1 found the exact cause of “swiping up
from the bottom of Settings does nothing”: nix/card-shell/adapter.c’s
input_down ceded every touch to a mapped Drawer/Shade/Settings layer-shell
overlay (drawer_mapped()) before the compositor’s own bottom-edge
recognizer (cs_begin_entry/cs_edge_down) ever ran, regardless of where on
the screen the touch started. This requirement is this change’s fix for that
finding, and for the-handheld-presents-a-coherent-shell’s own “Home is the
live card deck” requirement’s “from an app or transient surface” clause,
which this same defect left unimplemented for every transient surface.
While the Drawer, Shade, Settings, or any Settings sub-page (theme chooser,
Wi-Fi, password entry) is mapped, a touch that begins within the same
qualified bottom edge band an ordinary app already honors SHALL be claimed by
the compositor’s existing bottom-edge recognizer instead of being forwarded
to the overlay, using the same thresholds and feel as from an app: a purely
upward release SHALL reach the card overview, and a qualified sideways
release (directly, or continued from an upward start without lifting) SHALL
switch directly to the adjacent running app, per the-handheld-presents-a- coherent-shell design decision 11/12’s already-approved two-axis mechanics,
which this requirement reuses unchanged. The overlay SHALL be dismissed as
part of claiming the gesture, so the person is never left with the overlay
still covering the destination it just navigated to. A touch that begins
outside that qualified band — including the overlay’s own top-area controls
— SHALL continue to reach the overlay exactly as before.
Because this claims the gesture at the compositor’s touch-routing layer
rather than inside the overlay’s own page/route state, it applies uniformly
regardless of which Settings sub-page is showing, closing
shell-ux-critique.md S2’s “dead ends three levels deep” finding (Shade →
Settings → Wi-Fi → password entry) without a separate per-page fix: the
bottom edge reaches the overview from any depth.
Grounding: operator acceptance in docs/evidence/proposal-closeout/2026-10-01/coherent.md, with prior source and board/QEMU evidence retaining their original classes and limits.
docs/design/shell-ux-critique.md S2 found three overlay surfaces each
recognizing a different, independently hand-tuned local dismiss gesture —
Drawer on a downward drag, Shade on an upward drag, and Settings on a
downward drag despite opening from within the shade’s own downward path —
with no single stated rule governing any of them.
Each top-anchored overlay sheet’s own local dismiss gesture (distinct from the bottom-edge escape above, and from a tap on an explicit close control) SHALL retract the sheet back toward the edge it opened from. Shade and Settings SHALL therefore share one identical rule: an upward drag starting near the top of the sheet dismisses it, using the same start-position zone and displacement threshold for both. The Drawer, which rises from the bottom edge instead, correctly keeps its own reversed convention — a downward drag once its content is scrolled to the top sends it back toward the bottom edge it rose from, an overscroll-to-dismiss idiom that does not conflict with scrolling the drawer’s own content — and is unchanged by this requirement.
Archived change · Archived
Snapshot 5836ef1d113d · 2026-10-17 08:22 UTC
Closed recordReview the archived record and cited scope
If the display is dark when the HDMI cable is unplugged, the panel comes back
dark too. Nothing then shows that the unplug worked; the person sees a black
handheld and has to guess that a power-key tap will wake it. On 2026-10-16 the
board did exactly this. A power-key press at 12:18:10 sent
output * power off, HDMI reported disconnected at 12:18:11, and DSI-1 was
created with the stored “off” and stayed dark until the next press at 12:18:48
(journal, same boot). The accepted power requirement asks for this: a short
press keeps its state “across an HDMI hotplug”. The operator asked for the
opposite: “when hdmi unplugs, display should show up so you know it worked”.
output * power on with that mapping, once per
unplug.display/hdmi).Needs the physical board for the final proof: an HDMI unplug while the display is dark. Host tests cover the relay’s command order and the daemon’s state sync.
Three processes share display power:
k230-power-keyd (nix/power-keyd/power_keyd.py) toggles
output * power off|on on a short press and caches the result in
Actions.dark.k230-touch-trackpad (nix/touch-trackpad/) polls DRM connector status. It
switches between trackpad mode (HDMI is the output) and direct touch (the
panel is the output). On direct touch it maps touch to DSI-1 over Sway IPC.output *, so an output created later
(DSI-1 after an unplug) inherits a stored “off”.The relay sends the wake on a real unplug. The relay polls DRM sysfs.
It now also watches the HDMI connector’s status, and when that changes
from connected to anything else it sends output * power on ahead of the
touch mapping. This reuses the mapping’s existing retry, with no new
hotplug watcher. Sway stores the * power state even before DSI-1 exists,
so the order against output creation does not matter. The wake is sent
once per unplug: it is cleared after a successful mapping, and the first
reading after a relay restart never counts as an unplug.
The Trackpad → DirectTouch mode edge is not used. Board journal
2026-10-16 13:36:29–31 shows why: a power-key blank on HDMI disables HDMI
scanout (enabled → disabled) with the cable still in, so the relay left
trackpad mode at 13:36:30, one second before HPD reported the unplug.
Waking on that edge undid every power-off of the monitor. The first
implementation (0051c34b) did this; the connector-status edge replaces it.
The power key reads Sway’s state. A cached flag goes stale once another
process changes power. Before each action the daemon reads get_outputs:
the display is dark when no active output reports power: true. If Sway is
unreadable or lists no active output, the daemon keeps its cached flag, so
a transient IPC failure never inverts a press.
No wake on plug-in. The operator asked only for unplug. Plug-in keeps the stored state, so the monitor stays dark if the person darkened the panel first.
output * power on, the mapping retries on the next poll
with the wake still pending.connected to not connected (a real unplug, not a power-key blank that only
disables scanout), send output * power on before the direct-touch
mapping, once, retrying with the mapping if Sway is not ready. Verify with
cargo test --offline --manifest-path nix/touch-trackpad/Cargo.toml.
Done 2026-10-16 (host): 50 + 2 tests passed, including
only_a_real_unplug_counts_not_a_blanked_monitor.get_outputs before each action, and keep
the cached state when Sway is unreadable or reports no active output.
Verify with python3 -m unittest tests.test_power_keyd.
Done 2026-10-16 (host): 13 tests OK.power off, HPD disconnect, power on) and a native capture. This needs
the operator to unplug the cable; the key press may be the operator’s or
an injected KEY_POWER.Tasks 1.3 and 1.4 done 2026-10-16 (board, operator cable and key, journal):
docs/evidence/power-key/hdmi-unplug-wake/board-2026-10-16.md.
Grounding: Board-read and operator 2026-10-14: taps darkened and woke the panel in the same session (DSI-1 power false/true), and with HDMI connected the same taps sent output * power off/on and blanked and woke the monitor (docs/evidence/power-key/display/). Board 2026-10-16 14:04, operator cable and key: a blank on HDMI stayed dark, unplugging lit the panel one second after HPD, and the next press darkened it (docs/evidence/power-key/hdmi-unplug-wake/board-2026-10-16.md).
A short physical power-key press SHALL turn the display in effect (the panel, or the HDMI monitor while it is the output) off when lit and on when off, while preserving the running applications and selected brightness. Waking the panel SHALL consume that key gesture without activating an application or power action. Unplugging HDMI SHALL turn the panel on, even when the display was off, so the person can see that the unplug worked; the next short press then turns it off.
Archived change · Archived
Snapshot 5836ef1d113d · 2026-10-17 08:22 UTC
Closed recordReview the archived record and cited scope
With the handheld clipped into its keyboard base, a person cannot type on the keys in front of them. Pressing them does nothing. Typing still means summoning the on-screen keyboard, which covers almost half of the landscape panel. The keyboard’s backlight stays dark, and its Caps Lock light never lights. The base also carries a battery and a charger, but nothing on screen shows the charge or whether the battery is charging. Home’s Battery widget reports “no battery info”, so the first warning is the board switching off.
The keyboard base is the LILYGO “nRF9151 cellular / GNSS / keyboard base”
(k230_bsp/docs/HARDWARE_PINMAP.md in Xinyuan-LilyGO/T-Display-K230). Its
modem is a separate proposal,
the-nrf9151-gives-the-handheld-cellular-sms-and-location. This change covers
everything else on the base that Linux can use:
bq27xxx fuel-gauge driver.display/keyboard: the keyboard base’s keys, Caps Lock light and key
backlight, as Linux input and LED devices with a layout matching the legends.system/battery: the base’s battery and charger reported as Linux
power-supply devices, with low and critical battery policy.runtime/shell: hardware-keyboard behavior (hiding the on-screen keyboard,
shell keys, backlight follows typing) and battery state in the shade.runtime/device-settings: a keyboard backlight control. Battery status
appears only once battery hardware is observed, as the existing requirement
already demands.KEYBOARD_TCA8418, GPIO_PCA953X,
CHARGER_BQ25890, BATTERY_BQ27XXX_I2C, INPUT_DRV260X_HAPTICS,
LEDS_GPIO and LEDS_PWM.bq27xxx.k230-tdisplay-mainline-drm-common.dtsi)
gains a pinctrl node and the base’s devices.Sources read for this design:
Xinyuan-LilyGO/T-Display-K230 at tree 4a87c53c:
k230_bsp/docs/HARDWARE_PINMAP.md, the pin map of the nRF9151 base.k230_launcher/k230_phone_ui/src/ui_hardware.c, the LVGL launcher’s
driver for the base.docs/dts-evidence.md, for the FPIOA and the fact that our Linux tree has
no pinctrl.docs/research/board-capability-inventory.md, for the nRF9151/UART3 conflict.tca8418_keypad.c and ti,tca8418.yaml;gpio-pca953x.c;bq25890_charger.c;bq27xxx_battery_i2c.c and bq27xxx.yaml;drv260x.c.The vendor does not use a Linux driver for any chip on the base. Its vendor device tree has no nodes for them.
Bus. keyboard_i2c_begin() uses /dev/mem to switch IO46 and IO47 to FPIOA
function 0 (GPIO). It then bit-bangs I2C on /dev/gpiochip1 lines 14 and 15
(open-drain, pull-up, 8 µs half-period), and afterwards restores function 3.
Probe. Its probe looks for:
| Chip | Address |
|---|---|
| BQ25896 | 0x6B |
| BQ27220 | 0x55 |
| TCA8418 | 0x34 |
| XL9555 | first answer in 0x20–0x27 |
It reports Keyboard base not detected when none answers.
Keys.
tca8418_key_name().extension_keyboard_shift_symbol_for_code()
puts punctuation on Shift of the letter and number keys, for example
Shift+Q is ` and Shift+E is -.IRQ and reset.
0x344) and read as the TCA8418
interrupt.Backlight. IO52 is muxed to PWM4 (IOMUX value 0x1191) and driven through
/sys/class/pwm. The vendor kernel has a PWM driver. Our kernel has none: PWM
is a recorded non-goal in docs/research/mainline-kernel-inventory.md.
LEDs. The XL9555’s P0.3, P0.4 and P0.5 drive three LEDs. LED 0 follows Caps Lock.
Charger. The BQ25896 is used with a 704 mA charge current and a 4288 mV regulation voltage, both defaults, and its watchdog disabled.
Fuel gauge. The BQ27220 is read with standard commands at the following registers:
| Register | Quantity |
|---|---|
| 0x06 | temperature |
| 0x08 | voltage |
| 0x0A | flags |
| 0x0C | current |
| 0x10 | remaining capacity |
| 0x12 | full-charge capacity |
| 0x16 | time to empty |
| 0x18 | time to full |
| 0x2A | cycle count |
| 0x2C | state of charge |
| 0x2E | state of health |
Mainline bq27xxx at our pin has no BQ27220 entry.
gpio0_ports is IO0–31 and gpio1_ports is IO32–63. So:
| Pad | Bank line |
|---|---|
| IO42 | gpio1 10 |
| IO43 | gpio1 11 |
| IO46 | gpio1 14 |
| IO47 | gpio1 15 |
| IO52 | gpio1 20 |
Goals:
power_supply devices.Non-goals: see the proposal. In particular, no charge-parameter changes and no modem.
The first group is a read-only probe on the board. The pinctrl and driver choices below depend on its answers, and the vendor issue (T-Display-K230_canmv_rt#11: TCA8418 and XL9555 not ACKing under Linux) means a guess could cost a boot.
The probe:
/dev/mem reads of it are refused;i2cdetect -r on the hardware I2C4 bus (Decision 2);It writes nothing to any chip.
The DesignWare controller at 0x91409000 (I2C4), with IO46 and IO47 muxed to
function 3 (IIC4_SCL/IIC4_SDA) by the Linux pinctrl node, at 100 kHz. It costs
no CPU per bit and uses the kernel’s ordinary I2C client drivers. On
2026-10-13 it answered at 0x20, 0x34, 0x38, 0x55 and 0x6B
(docs/evidence/keyboard-base/probe/). LILYGO’s RT-Smart keyboard driver
(keyboard_ext.c) also uses IIC4 on these pads.
Earlier attempts on this unit saw every address NACK on both the hardware controller and a GPIO bit-bang bus. The cause was a protective film still over the base’s pogo pins, not the bus, so those runs say nothing about either bus.
Rejected:
i2c-gpio bit-banging on gpio1 14/15, as LILYGO’s Linux UI does. It
costs CPU on the one Linux core and needs I2C_GPIO, which is not built.
It stays the fallback if the hardware controller misbehaves under load./dev/mem IOMUX pokes from userspace, as the vendor does. They need root,
race any kernel owner of the pads, and leave the pads in whatever state a
crash left them.PINCTRL_K230 is already built (nix/kernel-mainline.nix:499), but our
device tree has no pinctrl node. Every pad today keeps U-Boot’s FPIOA setting
(docs/dts-evidence.md). This change adds a canaan,k230-pinctrl node at
0x91105000 with states only for the base’s pads:
| Pad | Function |
|---|---|
| IO42 | GPIO input, pull-up |
| IO43 | GPIO |
| IO46/47 | GPIO, open-drain-capable, pull-up |
| IO52 | GPIO now, PWM4 once the PWM port lands |
The driver applies only states that consumers reference, so pads such as the console’s IO38/39 stay as U-Boot left them. The first boot of this device tree must show the console still working. That is checked in the probe-to-bind group before any key work.
Rejected:
TCA8418.
ti,tca8418 at 0x34, IRQ on gpio1 10 falling edge, 7 rows by 10 columns.linux,keymap is generated from the vendor’s code-to-name table:
code n is row (n-1)/10, column (n-1)%10.Reset (IO43). The binding has no reset property, so IO43 is a gpio-hog.
Its polarity and level must come from the probe. The vendor code never drives
it, so its pad state at probe time is the only grounding.
XL9555.
nxp,pca9555 at the probed address.gpio-leds on P0.3/4/5 named k230:green:capslock, k230:status-1 and
k230:status-2. The colors are UNVERIFIED until a camera frame shows them.BQ25896.
ti,bq25896 at 0x6B. The binding requires charge parameters.BQ27220.
BQ27220 chip entry to bq27xxx_battery.c and
bq27xxx_battery_i2c.c, using the vendor’s register list above. It is
read-only: no data-memory or configuration writes./sys/class/power_supply, and userspace cannot
create a power_supply. A second, private battery API would mean every
consumer reads two sources.DRV2605. ti,drv2605 at 0x5A if the probe finds it, with the default
library. No consumer is added.
First step. IO52 stays a GPIO (gpio1 20) driven by a gpio-leds entry
named k230::kbd_backlight. The ::kbd_backlight suffix is the name
convention desktop tools look for. This needs no new driver.
Second step. A port of the vendor K230 PWM driver turns it into a
pwm-leds entry with the same name and a brightness range.
Rejected:
/dev/mem, as the vendor does.Layout. A custom xkb symbols file, k230-base, reproduces the vendor’s
Shift-symbol table. The kernel keymap emits ordinary key codes for each
legend, for example KEY_Q, and xkb puts ` on Shift+Q.
Fn and Fn-R. Both map to KEY_RIGHTALT, and xkb treats that as
ISO_Level3_Shift. The Fn layer:
| Fn + | Gives |
|---|---|
| Up / Down | PgUp / PgDn |
| Left / Right | Home / End |
| Del | Insert |
Shell keys.
KEY_LEFTMETA (Super).KEY_MICMUTE, with no action in this change.Sway applies the layout only to the base’s input identifier, so a USB
or Bluetooth keyboard keeps us.
Rejected:
tca8418 has no Fn layer support.keyd or interception-tools. They add a daemon that grabs the device
and re-emits it, and the layout belongs in xkb, where Sway already reads
it.On-screen keyboard. Any key from the base’s input device while wvkbd is
shown hides wvkbd, through the existing visibility signal path in
nix/shell.nix. A Sway bindsym --no-repeat cannot see every key without
consuming it, so this uses a small k230-keyboard-base user service that reads
the evdev device without grabbing it. The same service drives:
kbd-capslock
trigger follows the VT keyboard, which Sway does not drive, so it is not
used.Shell keys are Sway bindings to existing shell commands:
| Key | Action |
|---|---|
| Super (LILYGO) | the app drawer |
| Super + Tab | the card overview |
| Esc on Home, with no app focused | the existing back action |
| Fn + LILYGO | a grim screenshot, matching the vendor |
Battery policy. A k230-battery-policy system service watches
power_supply uevents and the gauge’s capacity while discharging:
The levels are Nix options. Rejected: UPower, which is a heavier dependency than this single-battery device needs, and which has no K230 packaging precedent here.
| Layer | Owns |
|---|---|
| Kernel and device tree | Devices exist and report truthfully. |
| Nix | Layout, services and options. |
| Rust shell client | The shade and Settings. |
Stage 1 owns nothing new.
0x3C register versus a
label.Evidence classes are named per task: host (build or unit test), QEMU, board-read (a command on the running board), injected (synthetic evdev), camera, and operator (a person at the real keys or glass). A host or QEMU result never ticks a board task.
1.1 Write tools/keyboard-base-probe.sh:
/dev/mem is
refused);i2cdetect -r -y on hardware I2C4
(IO46/47, function 3; design Decision 2);Proof (host): bash -n tools/keyboard-base-probe.sh and a review of the
write-free command list.
1.2 Run the probe on the board with the base attached, holding
flock /tmp/k230-board.lock, and commit the output to
docs/evidence/keyboard-base/probe/. Record:
Proof (board-read): the committed probe log.
1.3 If the TCA8418 or XL9555 does not answer, try the hardware controller on function 3 once and record the result. Then open the enable/power question as an explicit task here, before group 3. The battery groups proceed independently. Proof (board-read): the committed result. Both answered on the hardware controller itself, so no enable task opens.
canaan,k230-pinctrl node and states for IO42, IO43, IO46,
IO47 and IO52 only, plus the hardware I2C4 node (design Decision 2), to
nix/dts/k230-tdisplay-mainline-drm-common.dtsi.
Proof (host): nix build .#deviceTreeMainlineDrm.
Done: the pinctrl states and the i2c@91409000 node are in the dtsi.
nix build .#deviceTreeMainlineDrm built on 2026-10-14
(y4j8bwc0…-k230-tdisplay-mainline-drm.dtb).tools/push-file.py --src <dtb> --dest /boot/k230-tdisplay.dtb --reboot.
Record that the console on /dev/ttyACM0 still logs in, that the panel and
touch work, and that i2cdetect -y <bus> lists the 1.2 addresses.
Proof (board-read): the console log and i2cdetect output in
docs/evidence/keyboard-base/bus/.
Done 2026-10-14 (board-read): installed through the boot bundles, not
push-file.py. The serial getty is active, the panel is connected, touch
and the keypad take interrupts, and i2cdetect -y -r 1 lists 0x20, 0x34,
0x55, 0x6b (bound) and 0x38 (docs/evidence/keyboard-base/bus/README.md). 3.1 Generate the 7×10 linux,keymap from the vendor code table:
KEY_RIGHTALT;KEY_LEFTMETA;KEY_MICMUTE.Add the ti,tca8418 node, the IO43 gpio-hog at the level 1.2 observed,
and KEYBOARD_TCA8418. Proof (host): a generator unit test that
round-trips every vendor code (the table names 65 of codes 1–68; 4, 30 and
31 are unused), then nix build .#deviceTreeMainlineDrm. Done with
tools/keyboard-base-keymap.py and tests/test_keyboard_base_keymap.py.
3.2 Add the k230-base xkb symbols file, with the vendor Shift table and
the Fn layer, and the Sway input stanza for the base only. Proof (host):
xkbcli compile-keymap with the layout, plus a test asserting each vendor
Shift symbol, with its result.
Done as a complete keymap, nix/keyboard-base/k230-base.xkb, loaded with
Sway’s xkb_file for 1:1:tca8418. xkbcli compile-keymap --keymap (1.13.2)
compiles it, and tests/test_keyboard_base_xkb.py drives libxkbcommon:
every Shift symbol, Caps capitals, the digit row and the Fn layer pass;
changing one symbol makes it fail.
3.3 Add the nxp,pca9555 node at the probed address and the three
gpio-leds. Enable GPIO_PCA953X and LEDS_GPIO.
Proof (host): nix build .#kernelMainlineDrm.
Board-read (no camera): the LEDs register and switch their lines, in
docs/evidence/keyboard-base/leds/.
3.4 Install on the board. Record:
evtest on the base’s device for every key (board-read, with an
operator pressing);ls -la typed into foot, shown in a native grim capture and a camera
frame (operator + camera);Store all of it in docs/evidence/keyboard-base/keys/.
Partial evidence: evtest-2026-10-13T211125Z.log and the evemu recordings
in keys/ (board-read), and the operator typing on the base throughout
6.2. Closed by the operator: “keyboard seems good to me dont worry about
recording” and “waive the camera pics” (2026-10-14). There is no
ls -la capture, Shift line or Caps Lock frame.
gpio-leds k230::kbd_backlight. Proof (host):
nix build .#deviceTreeMainlineDrm. Then (camera) a frame with it on
and a frame with it off, written through sysfs, in
docs/evidence/keyboard-base/backlight/. The line itself switches
(docs/evidence/keyboard-base/leds/, board-read); the camera frames remain.
Closed 2026-10-14: the line switches (board-read), Settings’ Key backlight
row toggles the LED (injected tap), and the operator waived the camera
frames (“waive the camera pics”).pwm-leds entry of the same name. Proof (host):
nix build .#kernelMainlineDrm. Then (camera) three distinct
brightness levels.
Done 2026-10-14: nix/patches/mainline/pwm-k230.c (forward-port with
prescale, disabled-output and polarity fixes), pwm@9140a040, and IO52 on
function 2 as a 0–255 pwm-leds at 20 kHz. Built as part of
.#kernelMainlineDrmShellLandscapeBootFiles. On the board (board-read),
the PWM registers track 255, 128, 32, 4 and 0. Operator, camera waived:
“it dims fine, off is dark” (docs/evidence/keyboard-base/backlight/). 5.1 Write the forward-port patch adding BQ27220 to bq27xxx. It is
read-only, with no data-memory writes. Enable BATTERY_BQ27XXX_I2C.
Proof (host): nix build .#kernelMainlineDrm.
5.2 Add the ti,bq25896 node with the 1.2 register values and
CHARGER_BQ25890. Document any field the driver would rewrite. Proof
(host): nix build .#deviceTreeMainlineDrm and a reviewed
field-by-field table in docs/evidence/keyboard-base/charger/.
Done 2026-10-14: charger@6b with linux,skip-reset and
linux,read-back-settings, every ti,* value equal to the register it
names; nix build .#deviceTreeMainlineDrm built. The table and the one
rewritten field (REG02 CONV_RATE) are in the charger README. On the board
only REG02 changed on bind.
5.2a Find the BQ25896 INT line. bq25890_charger will not bind
without an interrupt (No irq resource found), and neither LILYGO’s code
nor its pin map names where INT goes; the XL9555’s INT is equally
unknown. Until this is found, 5.2 adds no charger node. When it binds,
use linux,skip-reset and linux,read-back-settings, so the driver reads
the charge parameters instead of writing them. It still writes
CHG_CONFIG=1 and WATCHDOG=0 (both already set) and CONV_RATE. Proof
(board-read): the line identified on the board, with the method
recorded.
Partial 2026-10-14: not identified. INT reaches no GPIO-muxed K230 line:
gpiomon -e both on every unclaimed line of both GPIO chips during a
USB-C unplug and replug saw no edge, and LILYGO’s pin map names no INT.
Pads muxed away from GPIO are not covered (the IOMUX readout is a
placeholder). The charger no longer needs it to bind:
bq25890-poll-without-irq.patch polls the IRQ handler every 2 s when no
interrupt is given, and the board logs no interrupt; polling every 2000 ms.
Closing this without the line needs the operator’s scope decision.
Public-source search 2026-10-14 (operator asked; docs/evidence/ keyboard-base/charger/int-line-search.md): no keyboard-base schematic is
published, LILYGO’s pin map names no INT for the BQ25896 or XL9555, and
LILYGO’s own launcher polls the charger over I2C every 30 s. Finding the
net now needs a continuity probe of BQ25896 pin 1 on the base PCB, or
LILYGO’s schematic.
Closed by operator scope decision 2026-10-14, with the line still
unidentified: “yeah close charger interrupt line do what lilygo does i
guess”. The charger stays on polling: LILYGO polls over I2C every 30 s, and
this kernel polls every 2 s. Nothing here claims the line was found.
5.3 On the board, record:
power_supply capacity, status, voltage_now and current_now;online value, cable in and cable out;Proof (board-read): the logs in docs/evidence/keyboard-base/charger/.
Partial 2026-10-14: gauge capacity, status, voltage and current on USB, on
battery (cable out, about -405 mA) and in charger Hi-Z (Discharging, then
Charging once restored); charger online 1 with the cable in and 0 in
Hi-Z; registers before and after bind, only REG02 CONV_RATE changed.
Done 2026-10-14: with the cable physically out (operator), the charger read
online 0, Discharging, no VBUS, EN_HIZ clear; the gauge Discharging
at about -400 mA (cable-out-2026-10-14.log).
5.4 If 1.2 found a DRV2605, add its node and INPUT_DRV260X_HAPTICS,
and record its input device appearing (board-read). Otherwise record
“not fitted” and close the task. Not fitted: 0x5A did not answer
(docs/evidence/keyboard-base/probe/).
6.1 Add the k230-keyboard-base user service. It reads evdev without
grabbing it and handles:
Proof (host): unit tests with a fake evdev stream, and
nix build of its derivation.
6.2 Add the Sway bindings:
grim screenshot;Proof (host):
nix build .#nixosConfigurations.k230-mainline-drm-shell-landscape.config.system.build.toplevel.
Built as part of .#kernelMainlineDrmShellLandscapeBootFiles (system
w3isqi2b…). Esc-as-back is in the keyboard-base service rather than a
Sway binding, because a binding would take Esc from focused apps. It
calls card_shell back only when no app has focus, with unit tests.
Board follow-up 2026-10-14 (operator + board-read): LILYGO opens
the drawer. Of five real LILYGO+Tab presses, two reported Shift 23–46 ms
before Tab, so Sway saw Super+Shift+Tab and the terminal got it; the
overview binding now also takes Super+Shift+Tab. Fn+LILYGO “did nothing”
because the screenshot gave no sign; it now blinks the key backlight and
adds a “Screenshot saved” notification. Fn reaches the board as
KEY_RIGHTALT (fn-evemu-record-2026-10-14T0237Z.txt). The operator then saw the overview
open but Tab also reach the terminal: Sway delivers the key for an
--input-device binding, so the chord bindings are now global (injected
experiment in the keys README). Recording:
docs/evidence/keyboard-base/keys/shortcuts-evemu-record-2026-10-14T0112Z.txt
and shortcuts-sway-bindings-2026-10-14T0112Z.json.
6.3 Add the battery to the shade, and the keyboard backlight control to
Settings, persisted under /var/lib/k230. Both are hidden when their device
is absent. Proof (host): cargo test in nix/rust-shell-client, plus
host renders with and without a fake power_supply/LED tree.
The shade reuses home_widgets::battery; Settings’ “Key backlight” row is an
on/off preference that keyboard_based.py re-reads, so Off keeps the keys
dark. The preference is /var/lib/k230-keyboard-base/key-backlight, a
shell-owned directory beside /var/lib/k230 (a child of the root-only 0700
directory would be unreachable to the shell user). Tests:
keyboard_base::tests, render::tests::the_shade_shows_a_battery_line_only_when_a_battery_exists,
render::tests::settings_shows_the_key_backlight_row_only_when_the_led_exists,
service_ui::tests::the_key_backlight_row_is_tappable_only_when_the_led_exists,
and tests/test_keyboard_based.py (preference off keeps the LED dark). Host
renders: docs/evidence/keyboard-base/shell/host-renders/. Not glass or board
evidence; 6.5 records that.
Board (board-read, native grim, 2026-10-14): the landscape shade shows
“100% - Full” from the real gauge, in
docs/evidence/keyboard-base/shell/board/. In landscape the Key backlight row
sits below the panel edge and Settings does not scroll (injected drag); that
predates this task and is tracked by landscape task 8.3.
6.4 Add the k230-battery-policy service and its Nix options. Proof
(host): state-machine tests covering 15%/5% once each, two readings at
3%, the countdown, a cancel on charge, and disabled. tests/test_battery_policy.py
(7 tests, including the /run/k230-battery-policy.json override used by
6.6); options k230.shell.batteryPolicy.*. Installed on the board as
system iw5x7hn5…, where the service is active with 15/5/3.
6.5 On the board, record:
Store all of it in docs/evidence/keyboard-base/shell/.
Partial 2026-10-14: the shade’s battery line and the Settings Key backlight
row (native captures; the row toggled by injected taps, preference file
off then on) in docs/evidence/keyboard-base/shell/board/. The operator
reports LILYGO opens the drawer. Open: camera frames, the key press hiding
the on-screen keyboard, and Home’s widget.
2026-10-14: Home’s Battery widget reads 100 % on the board (native
capture home-battery-widget.png, widget added to a test layout).
Camera frames waived by the operator (Operator, 2026-10-14: “waive the camera pics”.). Still open: a key
press hiding the on-screen keyboard.
Done 2026-10-14: the operator reports “pressing a key hides the osk”
(operator; camera waived).
6.6 Exercise the low-battery policy on the board with the thresholds
raised temporarily through a /run override, so a real discharge crosses
them. Record the notifications, the countdown, the cable cancel, and one
clean shutdown in the journal.
Proof (board-read + camera): docs/evidence/keyboard-base/battery-policy/.
Partial 2026-10-14 (board-read): with a /run override of 100/99/98 % and
the charger in Hi-Z for a real ~400 mA discharge, the journal records the
low and very-low notifications, the critical countdown, a cancel when the
charger came back, a second countdown and logind’s orderly poweroff through
systemd-shutdown. The board then halted with the panel lit instead of
powering off: no SBI SRST and no PMU power-off handler, so a shutdown on
battery keeps draining it. Open: a real power-off (power-key task 3.4’s
handler), then one clean shutdown that actually removes power, and the
camera frame.
2026-10-14: the PMU power-off handler is restored and the same
systemctl poweroff now removes power (docs/evidence/power-key/power-off/).
Rerun 02:18–02:31 CDT on that kernel: same notifications, countdown and
cancel, then the policy’s poweroff cut power (operator: “it went fully
dark”); the power key started it again, charger reconnected by the test’s
cleanup. Native capture of the countdown in the shade. The camera frame
this task names is waived by the operator (Operator, 2026-10-14: “waive the camera pics”.).
openspec validate the-keyboard-base-types-lights-and-reports-its-battery --strict
and python3 tools/blob-scan.py --no-vendor. Merge, push, and check CI and
the published spec pages. Archive only when every task above has its named
proof committed.
Done 2026-10-14: validate —strict and blob-scan pass at 9ba70f63; master
pushed, Spec site run 38623895514 built and deployed, and the published
backlight evidence page carries the live-slider record. Every task above has
its proof committed; the charger cold start and base-absent boot keep their
UNVERIFIED grounding markers in the specs.Make the keyboard base’s physical keys, Caps Lock light and key backlight usable from Linux and the shell, with a layout that matches the printed legends.
The system SHALL establish which keyboard-base chips answer, at which I2C address and over which bus, by a read-only probe recorded before any driver is bound to them. The probe SHALL NOT write a register of any keyboard-base chip. The system owns this requirement; stage 1 is unchanged.
Pressing a key on the base SHALL deliver the character or action printed on it to the focused application through the shell’s normal keyboard path. Shift SHALL produce the symbol the vendor layout assigns to that key. Holding a key SHALL repeat it. A USB or Bluetooth keyboard attached at the same time SHALL keep its own layout.
ls -la on the base into the terminal and presses EnterThe system SHALL expose the key backlight as a Linux LED device named with the kbd_backlight suffix. The shell SHALL turn it on when a key is pressed, turn it off after a configurable idle period without key presses, and keep it off while the panel is off. A person SHALL be able to choose its level, or turn it off entirely, in Settings. Without a PWM driver the only levels SHALL be on and off; with the K230 PWM driver the LED SHALL dim.
When a kbd_backlight LED device exists, Settings SHALL offer a keyboard backlight control: an on/off switch while the device has one brightness step, and a level slider once it has more. The choice SHALL persist across reboots in system state, not in a home directory. Moving the slider to a lit level SHALL light the keys at that level within a fraction of a second, for a short preview, without a key press; outside that preview the keys stay lit only while typing. When no such device exists, Settings SHALL NOT show the control.
When a person types on the keyboard base while the on-screen keyboard is shown, the shell SHALL hide the on-screen keyboard without losing the typed key. The on-screen keyboard SHALL stay available through its usual gesture. The shell SHALL NOT grab the base’s input device away from Sway.
The LILYGO key SHALL open the app drawer. LILYGO with Tab SHALL open the card overview. Fn with LILYGO SHALL take a screenshot of the panel. Esc SHALL perform the shell’s back action when no application has keyboard focus, and SHALL reach the application unchanged otherwise.
When a battery power_supply device exists, the shade SHALL show its charge percentage and whether it is charging, updated within 60 seconds of a change. When none exists, the shade SHALL show no battery element at all.
capacity, and a charging mark while a cable is connectedReport the keyboard base’s battery and charger truthfully to Linux and the shell, and stop the system cleanly before the battery browns it out.
With the keyboard base attached, the system SHALL expose a battery power_supply device that reports state of charge, voltage, current and charging status from the fuel gauge, and a charger power_supply device that reports whether external power is present. Readings SHALL come from the chips, not from an estimate.
/sys/class/power_supply/*/capacity and status on the board with the base attachedThe system SHALL configure the charger driver with the charge current, regulation voltage, termination and precharge values the charger already holds on this board, as read by the read-only probe. Any register the driver would write to a different value SHALL be named in committed evidence before that image boots on the board.
While discharging, the system SHALL notify the person once when the charge reaches 15% and again at 5%. At 3%, after two consecutive readings at or below that level, it SHALL show a 60-second shutdown warning and then request a clean poweroff. Connecting power during the warning SHALL cancel it. The levels SHALL be image options, and the shutdown SHALL be possible to disable.
Archived change · Archived
Snapshot 5836ef1d113d · 2026-10-17 08:22 UTC
Closed recordReview the archived record and cited scope
Home’s Battery widget is a 2x2 ring showing a percentage and a charging bolt.
A person who plugs the handheld in cannot tell from Home how fast it is
charging, how long until full, whether the charger or the cell is warm, or how
worn the cell is. The keyboard base now carries a BQ27220 fuel gauge and a
BQ25896 charger that expose all of this through power_supply; none of it
reaches the screen.
uevent file per supply, discovered by supply
type, with every field optional and omitted when absent.Non-goals: historical graphs, charge-limit or charger controls, low-battery notifications, changing the kernel drivers, a details view in Settings.
Needs the physical board only for the final value comparison; the implementation and host renders proceed without it.
Home’s 2x2 Battery widget shows a percent ring and a charging bolt. The
keyboard base exposes a BQ27220 fuel gauge (bq27220-0, type Battery) and a
BQ25896 charger (bq25890-charger-0, type USB) through power_supply, with
current, voltage, charge, health, cycles, temperature, input limit and charge
targets. None of it reaches Home.
Goals: one Home widget that shows every useful battery and charger metric the drivers expose, read cheaply and without breaking saved layouts.
Non-Goals: history graphs, charger controls, notifications, driver changes, a Settings details page.
WidgetKind::BatteryDetails
serializes as battery_details, so existing home.json files and the 2x2
Battery widget are untouched. It is 4x2 so the metric grid fits at panel
and HDMI sizes.uevent read per supply. home_widgets::battery::read_details
parses /sys/class/power_supply/*/uevent, picking supplies by
POWER_SUPPLY_TYPE. Every field is optional; a missing field drops its
cell rather than showing a placeholder.CHARGE_FULL / CHARGE_FULL_DESIGN. Current is rounded to 10 mA
so noise does not force repaints.CURRENT_NOW reads 0 when idle or full, so power shows 0.0 W
in that state; this matches the hardware rather than hiding the cell.docs/evidence/battery-details-widget/board/README.md).uevent parser to home_widgets::battery,
keeping BatteryState, read_state and format unchanged; add the
BatteryDetails widget kind (4x2, new serialized tag), its picker entry,
painting, and the 10 s / 30 s poll choice with change-gated repaint.
Proof (host): cd nix/rust-shell-client && cargo test.docs/evidence/battery-details-widget/host/ with a README;
inspect the images; register the PNGs in docs/blob-inventory.md and run
python3 tools/blob-scan.py --no-vendor. Evidence class: host render.nix build .#kernelMainlineDrmShellLandscapeHdmiBootFiles.
Evidence class: host build. Done 2026-10-15 at 51b290ff: store path
/nix/store/zyavn9qqw40hz4zj4ychk451l20anr2v-k230-coherent-shell-boot-files
(a build, not a flash or board observation)./sys/class/power_supply. Evidence class:
board observation. Progress 2026-10-15: placed by injected click,
page turned by the operator’s swipe, grim values match sysfs for the
full/idle/unplugged state
(docs/evidence/battery-details-widget/board/README.md). Open until
the operator places it with a physical click.
Done 2026-10-15: the operator placed Battery - Details from the picker with
the physical trackpad at 22:48 and accepted the widget (“graph looks
fine”, “works ship”) (docs/evidence/home-screen/operator-trackpad-2026-10-15.md). Values versus sysfs: board README above.Grounding: the attributes come from the board’s bq27220-0 fuel gauge and
bq25890-charger-0 charger as read from sysfs on 2026-10-15 while charging
over USB-C (docs/evidence/keyboard-base/charger/README.md records the gauge’s
sign convention, about +600 to +700 mA charging and -400 mA discharging, and
the charger’s registers). Layout legibility is a host render
(docs/evidence/battery-details-widget/host/README.md). Appearance and values
on the board’s glass are until the operator places the
widget.
Home SHALL offer a “Battery - Details” widget occupying 4 columns by 2 rows,
drawn by the shell and placeable on any grid page like the other widgets. It
SHALL show the battery percentage prominently with the state word (Charging,
Discharging, Full or Not charging) and, while charging, the charge type; the
time to full or time to empty when the gauge reports it; battery current in
milliamps with its sign (positive charging, negative discharging) and power in
watts; battery voltage; stored charge against full charge in milliamp-hours;
health as full charge over design charge; cycle count; battery temperature in
degrees Celsius; and a charger line stating whether input power is online, the
input current limit, the charge current and voltage targets, and the charger’s
health when it is not Good. The shell SHALL find the battery and charger by
their power_supply type and parse one uevent per supply; any attribute that
is missing SHALL be omitted rather than shown as zero or a placeholder. When no
battery supply exists the widget SHALL show the same “No battery info” state as
the Battery widget. The existing Battery widget and previously saved layouts
SHALL be unaffected.
Archived change · Archived
Snapshot 5836ef1d113d · 2026-10-17 08:22 UTC
Closed recordReview the archived record and cited scope
On HDMI the operator could remove widgets on Home’s first page but not on the
second. The board log shows their two-finger trackpad presses on page 2 ending
in touch-cancel, and a grim taken at that moment shows Home frozen about 44%
of the way between pages 1 and 2. A two-finger trackpad pan reaches Home as a
synthetic touch (TRACKPAD_PAN_ID). When it ends near where it started,
main.rs cancels it, and HomePager::cancel stops the drag without settling,
so the pager stays between pages. Painting follows the fractional position,
but hit testing rounds to the nearest page, so presses on what looks like page
2 land on page 1’s cells.
Removing the only widget on the last page shows the same gap: the page is deleted, but the pager stays at its index and Home shows a blank page with no page dots.
Non-goals: changing how trackpad pans are turned into touches, or swipe thresholds and fling physics.
HomePager::cancel clears the drag and velocity but not the position, and
HomePager::tick only moves the pager while coasting or settling.
HomeScreen::tick does not tick the pager at all in rearrange mode, which
pages through page_switch instead. HomeScreen::is_animating decides whether
main.rs keeps ticking.
cancel settles a fractional position to the nearest page.HomePager::off_page(count): at rest and either fractional or past
the last page. tick starts a settle to the clamped nearest page when it
holds, and HomeScreen::is_animating reports it so ticks resume.page_switch is live, so the two never fight over the
position.HomePager::cancel), and settle an
at-rest pager that is between pages or past the last page
(HomePager::off_page, HomePager::tick, HomeScreen::is_animating,
HomeScreen::tick). Host tests: a cancelled drag at 0.44 settles to
page 1; losing the last page settles back; removing the only widget on
page 2 in rearrange mode returns Home to page 1.
Proof (host): cd nix/rust-shell-client && cargo test — 545 lib tests
pass (2 ignored), and the other suites pass.docs/evidence/home-screen/page-settle/README.md.docs/evidence/home-screen/operator-trackpad-2026-10-15.md).Grounding: host tests in home_pager and home_screen; on-board behaviour
is until tasks 2.1 and 2.2 are recorded.
When a page drag ends without a release, for example a two-finger trackpad pan the shell cancels, Home SHALL settle to the nearest page rather than stop between two. When the number of pages shrinks so that the page in view no longer exists, Home SHALL settle onto the last page that does, including in rearrange mode. At rest, what Home paints and where a press lands SHALL always refer to the same page.
Archived change · Archived
Snapshot 5836ef1d113d · 2026-10-17 08:22 UTC
Closed recordReview the archived record and cited scope
On 2026-10-15 the operator added the Battery widget from Home’s widget picker
on the HDMI monitor (1280x800) and “nothing showed up”. A board capture
(docs/evidence/home-screen/widget-picker-fit/board/before-widget-rows-past-the-card-1280x800-grim.png)
shows the Widgets page drawing its Battery and Weather rows below the picker
card, over the dock. The picker treats a press outside its card as a dismiss
(HomeScreen::resolve_picker_tap), so pressing either row closed the sheet.
A plain tap on a widget row also did nothing; only a press-and-hold followed
by a drag placed a widget, which is awkward on a trackpad.
nix/rust-shell-client/src/home_grid.rs (picker row geometry),
home_screen.rs (resolve_picker_tap), render.rs (row labels),
home_state.rs (subtitles), evidence_render.rs and the
render_landscape_surfaces example (picker renders).runtime/home-screen gains one requirement.home_grid::picker_row_rect stacked fixed 92 px rows with 14 px gaps from the
card’s top. The Widgets page has one Back row plus one row per WidgetKind
(seven today). That is 20 + 7x92 + 6x14 = 748 px, but the card is 556 px tall
at 1280x800 and shorter on the 1232x568 landscape panel. Hit-testing and
painting share picker_row_rect, so the overflowing rows were drawn, but a
press on them failed the card test first and dismissed the sheet.
Goals: every row of every picker page inside the card at every surface; a tap or click places a widget.
Non-Goals: scrolling the picker, or changing the drag path or the menu.
picker_grid
sizes rows for WidgetKind::ALL.len() + 1. Rows take the card’s height
up to 92 px, with the gap dropping to 8 px before rows go below 56 px.
When one column would squeeze rows below 85 % of full height and the card
is wide enough for two 360 px columns, the rows split into two columns.
The portrait panel keeps one column at full size.row height / 92, clamped to 0.6-1.0, and the subtitle is at
least 11 px.HomeLayout::first_fit on
the page in view, else place_first_fit, the same placement path as
pinning. It returns HomeAction::LayoutChanged, so the shell saves
home.json as it does after a drop.docs/evidence/home-screen/widget-picker-fit/host/. The board
proof is a tap on a row on the HDMI monitor placing that widget.home_grid::tests::every_picker_row_sits_inside_the_card_at_every_surface;
renders in docs/evidence/home-screen/widget-picker-fit/host/.home_screen::tests::a_plain_tap_on_a_widget_preview_places_it_and_closes_the_sheet
and a_tap_on_a_widget_row_works_on_landscape_surfaces_too
(cargo test --lib, 516 passed, 2026-10-15).hfmjszha… (2026-10-15 16:57,
docs/evidence/home-screen/widget-picker-fit/README.md): the rows fit
and a click on Weather placed it. Still open: the operator’s own click
on the physical trackpad.
Done 2026-10-15: the operator’s physical clicks on picker rows placed
Battery - Details and Weather at 22:48 (the plain Battery row was not the
one clicked), and they accepted the result (docs/evidence/home-screen/operator-trackpad-2026-10-15.md).Grounding: host tests
home_grid::tests::every_picker_row_sits_inside_the_card_at_every_surface,
home_screen::tests::a_plain_tap_on_a_widget_preview_places_it_and_closes_the_sheet,
home_screen::tests::a_tap_on_a_widget_row_works_on_landscape_surfaces_too;
host renders docs/evidence/home-screen/widget-picker-fit/host/; the board
capture of the defect is
docs/evidence/home-screen/widget-picker-fit/board/before-widget-rows-past-the-card-1280x800-grim.png.
Every row of every widget-picker page SHALL lie inside the picker card at every supported surface size, using two columns and shorter rows where one column does not fit. A tap or click on a widget row SHALL place that widget at the first free spot it fits on the page in view, else on the first page with room, close the sheet and save the layout. A press-and-hold on the row SHALL still drag the widget instead.
Archived change · Archived
Snapshot 5836ef1d113d · 2026-10-17 08:22 UTC
Closed recordReview the archived record and cited scope
On HDMI with a trackpad the operator could not move or remove a Home widget. A right-click on a widget does nothing: Home’s secondary click only opens an app’s menu or, on empty space, the Home menu. Long press is the only way into rearrange mode, and holding a trackpad button still for half a second is not something a mouse user tries. Even in rearrange mode a widget has no remove badge, so removing one means dragging it onto Remove.
Non-goals: a per-widget context menu, widget settings, or changing how app icons answer a secondary click.
main.rs handles a pointer press of BTN_RIGHT (0x111) on Home by asking
HomeScreen::app_at for an app, then HomeScreen::open_menu_at for empty
space. A widget is neither, so the click falls through. In rearrange mode
HomeScreen::badge_at already hit-tests a badge for every filled anchor at
home_grid::plate_top_left, but render.rs paints widgets with
paint_widget_card and skips the badge, so a widget’s badge is invisible and
sits at its anchor cell’s plate corner rather than the widget’s corner.
HomeScreen::rearrange_at. A secondary click that lands on a widget
(through filled_slot_at, which covers the widget’s whole painted rect)
sets rearranging and arms no drag. It refuses under the same conditions
as open_menu_at: picker open, folder open, already rearranging, or a
drag or contact live.HomeScreen::badge_corner
returns the plate corner for icons and the widget rect’s top-left (inset
by the same amount) for widgets. badge_at and render.rs both use it.HomeScreen::rearrange_at and call it from the secondary-click
path in main.rs after app_at and before open_menu_at. Host tests:
a right-click on a widget enters rearrange mode with no drag; on an app
or empty space it does not.HomeScreen::badge_corner, and hit-test the same corner in badge_at.
Host test: clicking a widget’s badge removes it.
Proof (host): cd nix/rust-shell-client && cargo test — 540 lib tests
pass (2 ignored), and the other suites pass.tools/board-pointer.py) on a
widget enters rearrange mode showing widget badges; a scripted click on
a widget’s badge removes it. Capture with grim.
Evidence class: injected pointer + grim.
Done 2026-10-15: right-click on page 1
(docs/evidence/home-screen/widget-right-click/README.md); right-click
and a badge click removing a widget on page 2
(docs/evidence/home-screen/page-settle/README.md).docs/evidence/home-screen/operator-trackpad-2026-10-15.md).Grounding: until tasks 1.1, 1.2 and 2.1 are recorded.
A secondary click on a Home widget SHALL enter rearrange mode without picking the widget up and without opening any menu. It SHALL NOT do so while the Home menu or a folder is open, while already rearranging, or while a drag or touch contact is active. In rearrange mode every widget SHALL show a remove badge at its top-left corner, and a click on that badge SHALL remove the widget. A press and drag on a widget in rearrange mode SHALL move it, as for icons.
Archived change · Archived
Snapshot 5836ef1d113d · 2026-10-17 08:22 UTC
Closed recordReview the archived record and cited scope
On HDMI at 1280x800 the operator could not move or remove Home widgets. A press-and-hold on the Battery - Details widget did nothing. Home hit-tests each grid cell’s own tile, but a multi-cell widget is painted across the gaps between its cells, so a press on a widget’s middle often lands in a gap and hits nothing. At 1280x800 (nine 121 px columns with 18 px gaps, 166 px rows with 18 px gaps) these dead strips cross every 4x2 widget.
Non-goals: changing the grid geometry, drop targeting during a drag, or how a widget is removed.
home_grid::slot_at returns the cell whose tile contains the point and
returns nothing for gaps; a test says gaps between icons are intentionally
inert. render.rs paints a widget over home_grid::spanned_tile_rect, which
covers the gaps inside its span.
HomeScreen::filled_slot_at. Before the per-cell
lookup, check each multi-cell item on the page in view against its
spanned_tile_rect and return its anchor. Press, long press, rearrange
drag and secondary click all share this one lookup.home_grid::slot_at unchanged. Drop targeting and the icon gap
behaviour keep their current semantics and tests.HomeScreen::filled_slot_at. Add a regression test using the board’s
1280x800 layout, where (300, 300) on the page 2 widget sits in a column
gap and a row gap.
Proof (host): cd nix/rust-shell-client && cargo test — 537 lib tests
pass (2 ignored), and the other suites pass.tools/board-pointer.py) at
(300, 300) on the widget enters rearrange mode. Capture it with grim.
Evidence class: injected pointer + grim. Done 2026-10-15 on the Clock
widget (same gaps): docs/evidence/home-screen/widget-hit-area/README.md.docs/evidence/home-screen/operator-trackpad-2026-10-15.md).*Grounding: reproduced on the host from the board’s saved layout at 1280x800
(HomeScreen::filled_slot_at regression test). On-board behaviour is
A press, long press or secondary click anywhere inside the rectangle where Home paints a multi-cell widget SHALL resolve to that widget, including points that fall in the gaps between the widget’s grid cells. Single-cell icons SHALL keep their tile-only hit area, so the gaps between separate icons stay inert.
Archived change · Archived
Snapshot 5836ef1d113d · 2026-10-17 08:22 UTC
Closed recordReview the archived record and cited scope
On HDMI the operator found that the first two-finger swipe on Home did
nothing, and that holding two fingers on a widget to right-click it stopped
working. The board record shows two separate causes in k230-touch-trackpad:
BrokenPipe
(k230-touch-trackpad: shell IPC phase=begin error=BrokenPipe, 22:48:36 on
2026-10-15), is dropped, and only the gesture after it reconnects.Non-goals: changing libinput configuration, swipe or fling thresholds, or how the shell treats a right-click.
shell_ipc::run keeps one Unix socket to sway. A begin whose command fails
clears the socket and reports the gesture as refused, so the gate passes it to
libinput as an ordinary touchpad stream. The socket is reopened only for the
next gesture. gestures::Gate buffers a new contact as a Candidate: a lone
contact times out after PAIR_MS (45 ms), and a multi-finger one after
DECIDE_MS (250 ms). A timed-out candidate is flushed to the virtual
touchpad with its source timestamps, which uinput passes on (the gate’s tests
check this), so libinput measures every touch by its real duration.
begin once on an I/O error. Reconnect and resend the same
command, so the sequence number and timestamps are unchanged. A refusal
(success: false) is not retried.MAX_BUFFER still bounds a
very long hold. A one-finger candidate keeps its 45 ms pairing window, so
pointer motion is not delayed.TAP_PRESENTED_US (40 ms)
before the lift frame, which keeps its own time. libinput then applies its
own tap rules: two fingers are a secondary click and three a middle click.
Only still presses are re-timed; a press that moved has already been
handed to the shell or to libinput as motion.card_shell trackpad begin that fails
with an I/O error (shell_ipc::run). Host test
a_compositor_restart_does_not_lose_the_next_gesture: it fails without
the retry and passes with it.Gate::expire, Gate::push), and present it as a 40 ms tap
ending at the lift. Host test
a_long_still_two_finger_press_reaches_libinput_only_at_the_lift.
Proof (host): cd nix/touch-trackpad && cargo test — 49 and 2 tests
pass.--device=), so the run covers the real gate, relay, libinput and
shell path. Evidence class: injected raw touch + shell log.
Done 2026-10-15:
docs/evidence/display-touch/trackpad-restart-and-long-press/README.md.docs/evidence/home-screen/operator-trackpad-2026-10-15.md).*Grounding: host tests in nix/touch-trackpad; on-board behaviour is
When the compositor has restarted since the last two-finger gesture, the trackpad relay SHALL reconnect and still deliver the next qualified two-finger gesture rather than drop it. A multi-finger contact that stays still SHALL reach libinput only when it moves, changes spread or contact count, or lifts. A still press that lifts SHALL be presented to libinput as a tap, so a still two-finger press of any duration is a secondary click.
Archived change · Archived
Snapshot 5836ef1d113d · 2026-10-17 08:22 UTC
Closed recordReview the archived record and cited scope
The Battery - Details widget shows the battery at one instant. With the board unplugged, the operator asked to see how the charge has filled or drained over time. The widget’s own proposal left history graphs out of scope, so this adds them as a separate change.
home.json. It records whether
or not the widget is placed, so a newly placed widget already has history.Non-goals: current or power graphs, a zoomable or tappable graph, history for the 2x2 Battery widget, a history view in Settings, recording while the shell is not running.
nix/rust-shell-client: home_widgets::battery (history file), main.rs
(recording on the existing poll), render.rs (graph painting).$XDG_STATE_HOME/k230-shell/battery-history.tick_home_widgets already polls /sys/class/power_supply every 30 s, or
every 10 s while a Battery - Details widget is placed. Home layout state is
kept in $XDG_STATE_HOME/k230-shell/home.json. The board is often rebooted,
so a history held only in memory would usually be empty.
battery-history is
<unix seconds> <percent> <c|d>. Lines that fail to parse are skipped.home.json does. At one
short line per minute, writes stay small.home_widgets::battery with unit tests for parsing, pruning, gaps and
future-dated samples. Record on the existing poll in main.rs and paint
the graph in paint_battery_details.
Proof (host): cd nix/rust-shell-client && cargo test — 535 lib
tests pass (2 ignored), and the other suites pass.docs/evidence/battery-details-widget/history/, with a README.
Inspect the images and register the PNGs in docs/blob-inventory.md.
Evidence class: host render.docs/evidence/battery-details-widget/history/board/README.md
(discharge, the gauge’s 88 -> 7 recalibration, a power-off gap; no
charging span yet).*Grounding: requested by the operator on 2026-10-15 after the widget showed live discharge figures on the board. Host renders and board captures are
docs/evidence/battery-details-widget/history/.*
The shell SHALL record the battery percentage and whether the battery was charging about once a minute while it runs, and immediately when the charging state changes, to a per-user history file beside the Home layout. Recording SHALL happen whether or not a Battery - Details widget is placed. The file SHALL keep at least the last 24 hours, SHALL survive shell restarts and reboots, and SHALL be pruned so it does not grow without bound. The Battery - Details widget SHALL draw the last 12 hours of recorded percentage as a line graph from 0 to 100 percent. Charging spans SHALL be visually distinct from discharging spans, and spans with no samples for more than 5 minutes SHALL be shown as gaps rather than joined.
Archived change · Archived
Snapshot 5836ef1d113d · 2026-10-17 08:22 UTC
Closed recordReview the archived record and cited scope
The operator, using the HDMI trackpad on 2026-10-15, expected a two-finger
right-click on empty Home space to open the Home menu (Widgets / Wallpaper &
style / Home settings). Today only a long press there opens it. Secondary
click on empty space does nothing; it opens the app menu only on an app icon
(main.rs secondary-click handler, HomeScreen::app_at).
nix/rust-shell-client/src/home_screen.rs (HomeScreen::open_menu_at) and
the secondary-click branch of pointer_frame in main.rs.runtime/home-screen gains one requirement.Home’s menu (Widgets / Wallpaper & style / Home settings) opened only from a
long press on an empty Home cell (HomeScreen::down sets
empty_slot_at_down, tick opens the menu after LONG_PRESS_MS). The
secondary-click handler in main.rs pointer_frame (button 0x111) resolved
only app icons (HomeScreen::app_at), so a right-click on empty Home space
did nothing. On HDMI the board’s touchscreen is a libinput touchpad with
tap enabled and tap_button_map lrm, so a two-finger tap is a right-click.
Goals: a right-click on empty Home space opens the same Home menu as the long press, with the same exclusions.
Non-Goals: changing how taps become clicks, the app menu, or the long press.
HomeScreen, the long press’s conditions.
open_menu_at refuses while the menu is open, while rearranging, with a
folder open, or during a drag or contact. It opens only on an addressable
cell that filled_slot_at does not resolve, which is the same test as
empty_slot_at_down.app_at first and opens the app
menu when there is one; open_menu_at runs only when no app was hit.HomeScreen::open_menu_at opens the Home menu on an empty
addressable cell, under the long press’s conditions; the
secondary-click handler calls it when the click is not on an app.
Host test:
home_screen::tests::secondary_click_on_empty_home_space_opens_the_menu_but_not_on_an_icon
(cd nix/rust-shell-client && cargo test --lib, 514 passed,
2026-10-15)./nix/store/acmin041a4hb7nglym6h1lcm66sp3wyh-nixos-system-nixos-26.11.20260919.20b1ddd
(bundle 6cchn05l…, HDMI 1280x800, tap_button_map lrm). The operator
tried both and said “both work”. Evidence class: operator report, no
capture.Grounding: host test
home_screen::tests::secondary_click_on_empty_home_space_opens_the_menu_but_not_on_an_icon;
operator report on the HDMI trackpad, 2026-10-15, system acmin041…
(openspec/changes/archive/2026-10-15-home-space-right-click-opens-the-home-menu/tasks.md 1.2).
A secondary click on an empty, addressable Home cell SHALL open the same Home menu that a long press on that space opens, under the same conditions. It SHALL NOT open while that menu is already open, while rearranging, while a folder is open, or while a drag or touch contact is active. A secondary click on an app icon SHALL continue to open that app’s menu.
Archived change · Archived
Snapshot 5836ef1d113d · 2026-10-17 08:22 UTC
Closed recordClosed with explicit performance acceptance and selected system/QEMU integration proof. No further performance optimization is selected.
the-shell-manages-apps-as-cards declared an explicit card-interaction
budget (task 4.1, done) and has measured the default Pixman composition path
against it on hardware more than ten times since
(docs/evidence/card-shell/{board-cost/long-trace,touch-timestamps/board, throw-sampling,repaint-stages,throw-fixture-sync,scaled-cache-board}/README.md,
plus kernel-rvv/card-cost/README.md). Every round fails the same two
numbers: frame-update CPU p95 (borderline for one card, clearly over for two),
and, more strikingly, the tracking-presentation interval p95 sits at
~57.47-57.49ms against a 33.334ms budget in literally every run, unchanged
by repaint-stage instrumentation, RVV auto-vectorization, a scaled-cache
mirror path (on or off), or a touch-timestamp/fixture-race fix. That
invariance across every independently tested variable is itself informative:
it does not look like a CPU cost a code change will fix so much as a fixed
structural interval (an output-commit/vblank cadence this project has not
yet measured directly). docs/evidence/card-shell/renderer-decision.md
already declined the optional GPU/VGLite path as unjustified by current
evidence.
The parent’s own requirement text says exactly what to do here: “If it
cannot [preserve the required behavior within budget], the change SHALL
remain open or move to an explicitly authorized successor; it SHALL NOT be
archived as accepted card-shell behavior.” This is that successor, per
AGENTS.md’s “close deliberately” rule — staged so the question (accept the
1.7x-over-budget tracking cadence with a recorded decision, investigate the
panel/vblank cadence directly, or continue optimizing the Pixman path) is a
deliberate coordinator choice rather than an unresolved task sitting
indefinitely in an otherwise-closeable change.
Status: authorized. The user approved this split and its implementation
2026-09-28 (“frame budget go”). Board evidence committed the same day
(docs/evidence/card-shell/frame-budget/board-result-2026-09-28.md,
analysis.md) answered the “suggested first step” above directly: raw
hardware vblank stays a clean 19.16ms grid even while the deck animates
(idle p50/p95 19.161/19.162ms; drag-window p50/p95 19.161/19.163ms). The
~57ms presentation intervals are therefore the compositor’s own commit
cadence missing vblank slots (H1: render or commit overrun, rounded up to
the next whole vblank by canaan_crtc_atomic_flush’s synchronous commit),
not a panel or VO refresh limit; H4 (vblank IRQ at 1/3 rate) is refuted.
This authorizes option (c): reduce per-frame card-deck render/commit cost
and/or pipeline commits so an overrun costs one slot instead of serializing
the next. On 2026-10-01 the user explicitly authorized archiving the functional parent
and transferring sole ownership of its original task 4.2 and dependent task
5.1 to this existing successor. See
docs/evidence/proposal-closeout/2026-10-01/live-card-ui.md. Neither budget
acceptance nor the unperformed full-image/non-fixture QEMU gate is waived.
the-shell-manages-apps-as-cards task
4.3, already recorded as declined) without new evidence that changes its
premise.Task (a) above (measuring actual vblank/output cadence) and any further Pixman-path measurement both need the reserved board; this is board-gated work from the outset, unlike the other two successors staged in this closeout pass.
runtime/card-shell: carries the parent’s “Card interaction has an
explicit measured budget decision” requirement forward, unchanged, with
the parent’s functional archive leaving budget acceptance UNVERIFIED.Userspace performance investigation only (nix/card-shell/,
nix/card-shell-policy/, tools/card-shell-benchmark.py) and, if cadence
turns out to be the issue, possibly kernel/DRM timing investigation on the
panel driver (display/panel) — scoped once (a) above is attempted, not
predetermined here. No stage 1 change.
The operator explicitly accepts the current card Overview performance and
authorizes closure and landing. The exact permission is retained in
docs/evidence/card-shell/frame-budget/acceptance-2026-10-09/README.md.
This selects option (b), retaining the historical overrun/CPU misses and
the distinction between measured old candidates and current observed feel.
A new benchmark is unnecessary for this chosen acceptance; no numeric pass
is inferred. The selected board-system host build and actual non-fixture QEMU
guest integration subsequently passed, with their separate proof committed in
the same evidence directory. All eight tasks are complete for archive; no
further performance or kernel experiment is selected.
Ten-plus board rounds, spanning repaint-stage profiling, source-timestamp
fixes, a throw-fixture-race fix, a scaled-cache mirror path (on and off), and
an RVV comparison, have all measured the same tracking-presentation p95 of
~57.47-57.49ms against a 33.334ms (2x a ~19.2ms nominal interval at the
panel’s advertised ~52.19Hz mode) budget. See
docs/evidence/card-shell/{board-cost/long-trace,touch-timestamps/board, throw-sampling,repaint-stages,throw-fixture-sync,scaled-cache-board}/README.md.
Goal: resolve task 4.2’s open budget decision deliberately — either with a genuine fix, or a recorded, reviewed acceptance, rather than another open-ended board round repeating the same measurement.
Non-Goal: re-opening the GPU/VGLite decision without new evidence.
Not yet made — this is exactly the open decision this successor exists to make deliberately. The one thing already decided (inherited from the parent): whatever is chosen, it must preserve live visual cards, finger-following, deck selection, tap-to-expand, and recoverable throw-close; a reduced-refresh path that breaks any of those is rejected regardless of its budget numbers.
Update, 2026-09-28 (authorized implementation): the board vblank capture
(docs/evidence/card-shell/frame-budget/board-result-2026-09-28.md) and a
follow-on host cost measurement
(docs/evidence/card-shell/frame-budget/host-cost-table.md,
commit-pipelining-assessment.md) together narrow this to a genuine
two-way choice, not three: every CPU/damage-side lever this change’s own
task list named was already implemented or measured net-negative, and the
one remaining code-level lever (kernel commit pipelining) already has a
known, unresolved boot-panic risk from a prior attempt. The decision is
still the coordinator’s; this update states what is no longer open (further
Pixman-path tuning without a new, currently-unknown target) rather than
choosing for them.
Before another tools/card-shell-benchmark.py --board round with a new
independent variable, measure the panel’s actual output/vblank cadence
directly (e.g. DRM vblank timestamps or an equivalent kernel-level trace)
rather than continuing to infer it from the advertised mode. If the measured
cadence itself is ~57ms-ish, no CPU-side change to card-shell can close this
gate, and the decision becomes (b) or (c) in the proposal rather than more
Pixman tuning.
Board-gated from the outset. No host-only path closes this task.
The operator explicitly approved the functional parent’s archive. This change
became the sole owner of its original budget task 4.2 and dependent
image/non-fixture QEMU task 5.1. Their criteria and proof commands were retained;
their subsequent completion is recorded in the final decision below.
See docs/evidence/proposal-closeout/2026-10-01/live-card-ui.md. Functional acceptance is not budget acceptance.
The operator selects acceptance of the current Overview performance.
docs/evidence/card-shell/frame-budget/acceptance-2026-10-09/README.md
records the exact permission, historic numerical failures, their overrun
mechanism and current-candidate identity limits. This supersedes the open
decision and further measurement suggestion above. No kernel pipelining is
selected. The full selected board-system host build and ordinary non-fixture
QEMU guest run subsequently passed with committed artifact identities and two
fresh six-check reports across service restart. These are host/guest evidence,
not a newly installed board image or a numerical frame-budget pass. The original
bar system remains available as k230-bar-shell, and the accepted normal
mainline configuration retains its exact existing system closure.
This change was split from the-shell-manages-apps-as-cards (task 4.2, plus
its dependent task 5.1). Task IDs keep the parent’s numbering. Investigation was authorized by the
user 2026-09-28 (“frame budget go”); sole ownership of the unresolved budget
and full-image/non-fixture QEMU gates was transferred here by explicit
2026-10-01 functional-parent archive approval. See
docs/evidence/proposal-closeout/2026-10-01/live-card-ui.md. The transferred decision and integration gates are completed below with their
separate recorded evidence.
docs/evidence/card-shell/frame-budget/board-result-2026-09-28.md,
analysis.md). H1 confirmed (render/commit overrun quantized to the
vblank grid by canaan_crtc_atomic_flush’s synchronous commit); H4
(vblank IRQ at 1/3 rate) refuted.docs/evidence/card-shell/frame-budget/host-cost-table.md): Build
(wlr_scene_output_build_state) is 94.9% of render CPU (host p50 28.1 ms,
p95 30.0 ms; board p95 14.0-19.8 ms depending on card count — host runs
1.5-2.1x the board’s own Build time on this workload, via QEMU user-mode
emulation, not a faster proxy for it). Damage-extent instrumentation added
(card_bench_render_damage, new K230_CARD_SHELL frame-damage rows) shows
76-99.6% of the 568x1232 output is damaged on essentially every animated
frame — inherent to the webOS-fan deck moving several cards at once, not
a damage-tracking defect (confirmed by one clean 6.6%-damage counter-example
at 4.18 ms build). Every other code-level candidate in this task’s list
(avoid re-clip/re-scale of unchanged cards, cache each card’s scaled
result, skip scene sync when unchanged, reduce per-frame allocations) was
already implemented in prior rounds; verified by reading, not assumed.
The scaled-cache path (SWAY_K230_CARD_SCALED_CACHE=1, default-on in
nix/shell.nix) measured net negative on host (Build p50 +8.7%, p95
+12.1%) in two independent runs against two independent builds — not
disabled here because it is also the sole mechanism providing the required
capped (~15fps) live-preview rate; flagged as a decoupling opportunity for
a future task, not fixed in this one.docs/evidence/card-shell/frame-budget/commit-pipelining-assessment.md):
the mechanism is confirmed (kernel-side, canaan_crtc_atomic_flush’s
synchronous register write, per analysis.md H1) but the one known fix
(canaan-drm-defer-reg-load-to-vblank.patch) already caused an unrelated
boot panic and is deliberately not applied. Not attempted here: it is a
kernel change, board-gated, and this task was told not to touch the board;
reopening a change that already caused a boot panic is not “small and
safe” per this task’s own bar for touching the kernel.perf/deck-draw-less, base
d902bac4: found a real code-level lever 4.2b’s own list did not name —
nix/card-shell/adapter.c’s sync_node hardcoded
WLR_SCALE_FILTER_BILINEAR for every live mirror’s direct composite
regardless of motion, unlike the scaled-cache path’s existing
motion-aware fast filter. Switched it to
scene_in_motion() ? NEAREST : BILINEAR, matching that existing trade.
Host tests/card_shell_runtime.py --benchmark, four alternating
before/after pairs on the same host: Build p50 25.55ms -> 9.05ms (-65%),
p95 28.96ms -> 11.22ms (-61%), reproduced every full-sample run —
docs/evidence/card-shell/frame-budget/motion-time-filter-2026-09-28.md.
A separate, larger-looking lever (give the live mirror’s real opaque
region to the renderer instead of forcing it empty, so a rounded card’s
opaque interior takes Pixman’s SRC fast path) was implemented, measured
with the same alternating method, found not to reproduce a win
(within host noise, if anything slightly negative), and reverted rather
than kept on a hoped-for board result — recorded in the same evidence
file rather than silently dropped. Visual regression: existing 38-case
pixel-oracle/scaled-cache/policy unit tests, tests/card_rounded_clip_qemu.py
(--cache 0 and --cache 1) and all 17 native runtime checks all still
pass on the changed build; new tests/test_card_shell_motion_filter_runtime.py
confirms both filter modes are actually exercised in one session. System
closure builds (nixosConfigurations.k230-coherent-shell...toplevel).
This is a Build-stage CPU-cost reduction only; it does not by itself prove
4.2’s tracking-presentation p95 passes (see 4.2d below and analysis.md’s
H1 on commit-path serialization). A new numerical pass would require new
board proof; the current performance cost is explicitly accepted in 4.2d.docs/evidence/card-shell/frame-budget/acceptance-2026-10-09/README.md
and operator-decision.json. The historical 57.47–57.49 ms tracking
interval is render/commit overrun on a 19.16 ms vblank grid, not a panel
limit, and the declared numerical misses are not changed to passes. No
new benchmark/vblank capture or kernel optimization was performed.Proof of the selected acceptance path: review the exact operator permission,
the identified current functional walkthrough and the existing board cost/
vblank evidence cited in the committed decision. The previously proposed
tools/card-shell-benchmark.py --board and tools/measure-panel-refresh.sh
re-run belonged to the new-measurement/optimization path and were not run
under this explicit acceptance.
nix build .#nixosConfigurations.k230.config.system.build.toplevel, and run the
non-fixture tools/qemu-k230.sh --card-shell-smoke. The full selected board
system built successfully. The default selected QEMU invocation (no fixture
or no-build flags) built and booted the guest; two fresh reports passed all
six interaction checks across a service restart and zero-status teardown.
Exact commands, artifact identities, timestamps and evidence limits are
committed in docs/evidence/card-shell/frame-budget/acceptance-2026-10-09/.
The original bar-system derivation is preserved as k230-bar-shell; the
existing normal mainline system is unchanged. No board image was installed.openspec validate the-card-deck-still-misses-its-frame-budget --strict. Passed again on
closeout/card-overview-accepted-2026-10-09 during this closeout.Current closeout: all eight tasks are complete. The selected acceptance path and integration gates have their named proof; no new performance measurement, physical board boot or optimization is claimed.
Grounding: historical board cost/presentation measurements remain in
docs/evidence/card-shell/board-cost/long-trace/README.md and later board
cadence proof in docs/evidence/card-shell/frame-budget/board-result-2026-09-28.md.
Explicit current-performance acceptance and exact operator permission are in
docs/evidence/card-shell/frame-budget/acceptance-2026-10-09/README.md.
The historical numerical misses are accepted as costs, not rewritten as
budget passes or presented as new timings of the current candidate.
The card shell SHALL record input-to-visible-update latency, frame/update cost,
and incremental memory use at the panel’s native portrait mode on the default
Pixman path. If a declared interaction budget is missed, the implementation
SHALL record the result, including a direct measurement of the panel’s actual
output/vblank cadence where a CPU-side change cannot account for the miss. A
reduced-refresh or optimized path is acceptable only when it still preserves
live visual cards, finger-following, deck selection, tap-to-expand, and
recoverable throw-close. If it cannot, the change SHALL remain open or move
to a further authorized successor; it SHALL NOT be archived as accepted
card-shell behavior.
Archived change · Archived
Snapshot 5836ef1d113d · 2026-10-17 08:22 UTC
Closed recordReview the archived record and cited scope
Turn the board on and nothing happens. The glass stays black through DDR training, through U-Boot’s five-second countdown, and through the first three and a half seconds of Linux; then a wall of kernel text appears on it. A person holding the device has no way to tell a board that is booting from one that is dead until the console arrives, and what arrives is a console. That is the experience of a development kit, not of a thing.
Josh’s ask, verbatim: “have uboot drive the display because i don’t see any output til linux starts booting and the console comes out, and we’ll want a nice boot animation that transitions smoothly from uboot to when linux takes over plymouth-style”.
He also said “should be easy right”. It is not, and the shape of why is the shape of this change. Lighting the panel from U-Boot is the smallest of four pieces. The other three are: the kernel today resets the panel and replays its whole init sequence the moment it probes, which would extinguish anything U-Boot lit; the kernel’s framebuffer console clears the screen on takeover; and a splash that survives the kernel only matters if something on the Linux side then owns the screen and carries the image forward rather than cutting to black. Each of those is a different layer — stage 1, kernel, device tree, Nix, userspace — and each has its own proof.
board/canaan/common/logo/ in the SDK overlay), and LILYGO’s
published BSP extends that same path to this exact panel — a 568x1232
XRGB8888 logo loaded from the boot partition, scanned out from a fixed
address, with the RM69A10 init sequence and reset on GPIO22. This change
vendors that work onto the U-Boot this project builds, and corrects the one
value both vendors get wrong: the DSI PHY calibration band, which is
0x87 on this SoC at our lane rate, not 0x96.system/kernel capability
requires.0x200000, and OpenSBI then copies
the device tree to 0x2200000 — 32 MiB into that kernel — which the
board survives only because the bytes land in .BTF
(docs/evidence/opensbi-fdt-lands-in-kernel-image.md). The vendor’s own
logo path stages its picture at 0x1000000, also inside our kernel. There
is no map of what stage 1 puts where. This change writes one, chooses the
splash address against it, reserves it from the kernel through the device
tree, and makes U-Boot and the device tree take the number from a single
place in the flake.console=tty0 puts boot text on the glass. With a splash that is the
wrong default, and it is also what triggers the framebuffer console’s
clear. The switch restores exactly today’s behaviour for bring-up work.Non-goals. A NixOS generations menu, or any interactivity in U-Boot.
The rest of LILYGO’s U-Boot overlay beyond the four logo/ files and one
Kconfig hunk: their k230_board_common.c deletes enter_to_usb_burn_mode()
(that file belongs to the-card-is-flashed-over-usb-from-u-boot), their
defconfig moves the environment to 0x1e0000 / 64 KiB, and their board.c
sets a keyboard-backlight GPIO — none is carried
(docs/evidence/lilygo-uboot-logo.md).
Changing U-Boot’s bootdelay — the splash appears before the countdown, so
the countdown delays the kernel, not the picture, and shortening it is a
separate decision that affects the-card-is-flashed-over-usb-from-u-boot.
Brightness or backlight control beyond the 51 FE the init sequence already
sends. Touch during boot. HDMI. Changing which shell the board runs. A narrow opt-in Sway initial-scene patch
is now included because the measured startup black frame violates the handoff
requirement; general shell rendering changes remain out of scope.
Shrinking the boot itself: userspace starts around 22 s after the kernel
does today and this change hides that, it does not fix it.
Sequencing, and this is a hard dependency. Stage 1 on master is a
vendored binary. Nothing here can be done to a binary: the display code, the
Kconfig that enables it, the environment line that runs it and the /chosen
fixup all live in U-Boot source. every-blob-is-built-from-source-or-named
builds U-Boot and OpenSBI in the flake (nix/uboot-k230.nix,
nix/opensbi-k230.nix) and must land first. This change does not touch
firmware/stage1/ and does not plan around the vendored binaries at all. It
also expects that change to have moved OpenSBI’s device-tree copy out of the
kernel image, since the memory map this change writes would otherwise have
to document a collision it cannot fix.
the-screen-runs-a-shell-not-a-console is in flight and independent: it
delivers the thing that eventually replaces the splash. What this change
hands it is a contract — the screen is lit and showing a known image when
the compositor starts, and the compositor’s first frame is the end of the
splash — not a dependency in either direction.
Needs the physical board for everything that matters. Building U-Boot
with the display code enabled, producing the splash asset, compiling the
device tree, and measuring what Plymouth costs to cross-build are laptop
work. Whether the panel lights under U-Boot, whether it stays lit across the
kernel, and whether the handoff shows a dark frame can only be photographed
and captured on hardware; QEMU’s k230 machine models neither stage 1 nor a
display.
Four pieces, each proven separately:
| piece | layer | size |
|---|---|---|
| Light the panel from U-Boot with the right PHY band | stage 1 (U-Boot overlay, Kconfig, env) | vendored from LILYGO; one measured value to change |
| An address that survives the handoff, and a map | stage 1 env, device tree, Nix | small, but it is the place a wrong number corrupts a kernel silently |
| Probe and first modeset leave a lit panel alone | kernel (two drivers), U-Boot /chosen fixup | real driver work; the first modeset’s VO/DSI reprogramming and commit path are the open risk |
| Own the screen from the initrd to the shell without a cut | Nix, userspace | the largest cross-build in the change if it is Plymouth |
display/boot-splash: what the panel shows from power-on until the system
draws its first frame, who owns each stage of that, and how one stage hands
the lit panel to the next.display/panel: “The panel displays what the system draws” currently
promises that a boot ends with the console photographed on the screen and
that the panel is presented as an fbdev framebuffer. Both become a
configuration rather than the default: the panel is a DRM device at
568x1232, the console can be put on it, and by default what a boot shows is
the splash.image/boot-chain: gains the obligations that stage 1 lights the panel,
that it tells the kernel it did so, and that every address stage 1 loads
into is recorded in one map the splash buffer is chosen against. “Stage 1
hands control to our kernel” loses its “without modification to stage 1
itself” clause, which every-blob-is-built-from-source-or-named already
made untrue.Adds U-Boot source patches (the RM69A10 logo path, a /chosen fixup) to
nix/uboot-k230.nix, a Kconfig fragment enabling K230_BARE_DISP_LOGO, and
a line in the generated stage 1 environment. Adds a splash-asset derivation
and puts its output on the boot partition next to Image. Adds a
reserved-memory node to nix/dts/k230-tdisplay.dts. Adds two kernel
patches to nix/kernel.nix and records them in
docs/evidence/kernel-patches.md. Adds either boot.plymouth and a theme, or
a small DRM splash package, to the system closure — a riscv64 cross-build
with no binary cache either way, so it is sized before it is chosen. Removes
console=tty0 from the default kernel command line behind a new option.
Vendor source this change reads and cites by path:
.build/k230_linux_sdk/buildroot-overlay/boot/uboot/u-boot-2022.10-overlay/board/canaan/common/logo/{display_logo.c,k230_logo.c,st7701.c},
and LILYGO’s Xinyuan-LilyGO/T-Display-K230 at
k230_bsp/overlay/buildroot-overlay/boot/uboot/u-boot-2022.10-overlay/board/canaan/common/logo/
plus its Linux patches 0027, 0038 and 0051. The first task records the
LILYGO diff under docs/evidence/ so that the grounding does not depend on a
GitHub repository staying where it is.
The diagnostic preservation image at 671d404 boots to a correctly arranged
shell and visibly updates content; it also preserves the no-logo console and
normal display re-enable path. It still has an approximately 1.1–1.2 second
camera-visible startup dark gap. Evidence and limits are in
docs/evidence/splash-preserve-trial/README.md.
The implementation scope now includes narrowly preserving the matching stage-1 VO/DSI state on the first enable and seeding Sway’s first scene with the same immutable logo. These are required to pursue the existing continuous handoff behavior, not a relaxation of it. Both remain diagnostic until their physical acceptance checks pass. No animation is implemented by this change.
See proposal.md — Why. What shapes the approach:
every-blob-is-built-from-source-or-named gives the flake nix/uboot-k230.nix
(U-Boot 2022.10 plus Canaan’s rsync overlay, k230_canmv_v3_defconfig) and
nix/opensbi-k230.nix, and generates the stage 1 environment from text.
Every stage 1 piece of this design is a patch, a Kconfig line or an
environment line on top of that. Layer: stage 1.board/canaan/common/logo/ drives VO, DSI and the
D-PHY bare-metal and blits a logo for the CanMV’s ST7701. LILYGO’s BSP
overlay (Xinyuan-LilyGO/T-Display-K230,
k230_bsp/overlay/buildroot-overlay/boot/uboot/u-boot-2022.10-overlay/)
adds CONFIG_K230_BARE_DISP_LOGO_RM69A10: a 2-lane PHY routine,
rm69a10_568x1232_init() with a 13-command sequence, GPIO_RST_PIN 22,
and an OSD4 XRGB8888 scanout of /logo.xrgb from 0x1f000000. Read in
full on 2026-09-22 at commit bb831ab and diffed against the SDK copy —
docs/evidence/lilygo-uboot-logo.md, 549 lines over the four logo files.
Their sequence is not the one our device tree sends: rows 6-8 are the
partial-area block 31 …, 30 …, 12 (ENTER_PARTIAL_MODE), which lit
this panel under Linux but glitched (docs/evidence/panel-lit.md, “Still
wrong: the image is glitchy”), and which
nix/dts/display-rm69a10-568x1232.dtsi replaced with 13
(ENTER_NORMAL_MODE). The port sends the DTSI’s sequence, not LILYGO’s.
The same overlay also deletes enter_to_usb_burn_mode() from
k230_board_common.c and moves the U-Boot environment to
ENV_OFFSET 0x1e0000 / ENV_SIZE 0x10000; neither is carried (see the
vendoring decision below). It is authored by an AI agent and its
commit messages are not to be trusted (docs/research/linux-on-t-display-k230.md
§3), but LILYGO ships images in which it lights this panel.hs_freq 0x96 at 475 Mbps, where it is correct;
Linux’s canaan_dsi.c:383 (pristine pinned tree; line 428 in the tree
nix/kernel.nix builds) said 0x96 at any rate until
canaan,hsfreqrange was plumbed through the device tree. At our 594 Mbps the
measured answer is 0x87 (docs/evidence/dsi-hsfreqrange-hardcoded.md).panel-canaan-universal.c:318-329 pulses reset in
probe; our nix/kernel.nix adds three more pulses in prepare() ahead of
the init replay, because without them the panel did not answer.
canaan_vo_enable_crtc() (canaan_vo.c:652) performs VO initialization and
timing setup, and commit_tail_rpm enables the CRTC before programming the
planes. The explicit display-block reset writes are in the disable path
(canaan_vo.c:666), not at the start of canaan_vo_enable_crtc. The first
enable during boot was historically driven by fbdev emulation from the
output poll worker (dsi-phy-hang.md trace:
output_poll_execute → canaan_dsi_encoder_enable), scanning out a buffer
drm_fbdev_generic.c:89-98 allocated zeroed.docs/evidence/opensbi-fdt-lands-in-kernel-image.md. The vendor
logo path’s staging address 0x1000000 is inside our 57 MiB kernel too.systemd[1] first logs at ~22 s
(docs/evidence/panel-probe.txt). Anything that only runs from the main
system leaves the U-Boot frame static for twenty seconds./dev/ttyACM0 and says so.Goals:
Non-Goals (design level, beyond the proposal’s):
video driver so that
bmp display and fdt_simplefb work would be a rewrite of code we did
not write, for no visible benefit.Vendor LILYGO’s U-Boot logo path as patches on the SDK overlay, and cite
it; do not write our own. LILYGO’s diff against Canaan’s four files is the
only U-Boot code known to light this panel. It goes into
nix/uboot-k230.nix as a patch series applied after the overlay copy, with
the source commit recorded, plus a Kconfig fragment enabling
K230_BARE_DISP_LOGO and _RM69A10. Rejected: transcribing the sequence
into fresh code — a second implementation of a bring-up we only just got
right in Linux, with a second set of timing bugs. Rejected: taking LILYGO’s
whole overlay — it also carries their defconfig and board files, and this
project’s stage 1 is deliberately k230_canmv_v3 plus recorded deltas.
Concretely, three things in that overlay are left out on purpose
(docs/evidence/lilygo-uboot-logo.md, “What LILYGO’s U-Boot overlay
contains”, item 9): their k230_board_common.c deletes
enter_to_usb_burn_mode() and inlines it into do_2_burn_mode, a file
the-card-is-flashed-over-usb-from-u-boot owns; their defconfig moves the
environment to ENV_OFFSET 0x1e0000 / ENV_SIZE 0x10000 where this
project’s card has it at 3 MiB and 3.5 MiB, 8 KiB (nix/stage1.nix); and
their board.c drives GPIO52 low at board_init() for a keyboard
backlight this change has no opinion on. What is carried is the four
logo/ files and the one Kconfig hunk. The init sequence inside st7701.c
is rewritten to the DTSI’s (13 for LILYGO’s 31/30/12), so that stage 1
and the kernel initialise the panel identically. Layer: stage 1 (Nix
over vendor source).
Drive the same mode from U-Boot that Linux drives: 49.5 MHz, 594 Mbps,
hsfreqrange 0x87, with the PLL m/n/voc derived by the same arithmetic
canaan_dsi_clk_cfg() uses. A handoff that is also a mode change re-times
the panel in the middle of the thing we are trying to make seamless, and
the 39.6 MHz LILYGO uses is the refresh the device tree’s own comment
identifies as the source of AMOLED flicker. The band value is the measured
one; the vendor’s 0x96 in the connector table is replaced, not defaulted.
Also matched, register by register: VID_MODE_CFG (Linux writes 0xbf02,
canaan_dsi.c:280; LILYGO’s U-Boot writes 0x3f02), DPI_COLOR_CODING
(0x105 in Linux, canaan_dsi.c:288; 0x005 in LILYGO’s U-Boot). Each
divergence from LILYGO’s numbers is recorded in the same table as the
device tree divergences. Fallback, in order: if the panel does not light
or rolls under U-Boot at our numbers, first prove the path with LILYGO’s
exact table (39.6 MHz / 0x96), then move one parameter at a time — the
same method that found 0x87 in the first place. Rejected: shipping
LILYGO’s numbers — it works, and it hands Linux a panel at the wrong
refresh that then has to be re-timed. Layer: stage 1.
The “panel is lit” fact crosses to the kernel at runtime, in /chosen,
written only on success. k230_display_logo() clears a process-local C
readiness flag before every attempt and sets it only after the bounded asset
load and st7701_init() both succeed. ft_board_setup() — which the vendor
already uses to rewrite the memory node — asks that exported function and
writes canaan,stage1-splash as an empty boolean in /chosen. The state is
never put in the U-Boot environment: k230_set_dtb calls env_save(), so an
environment variable could survive a prior boot and falsely suppress Linux
reset/init. A boot with a missing or malformed logo, a PHY/init failure, or
an FDT write failure has no flag and the kernel follows its normal reset
path. Rejected: LILYGO’s static canaan,preserve-boot-splash in the panel
node (patch 0051). It is simpler, and it turns every stage 1 hiccup into a
permanently dark screen with no log line to say why. Rejected: passing it on
the kernel command line — bootargs.txt is generated by Nix before stage 1
runs and cannot know what stage 1 will manage to do. Layer: stage 1 →
device tree → kernel.
Kernel side: skip reset and init on the first prepare, and do not set up
fbdev, when the flag is present; both are per-boot, not per-board. Three
edits, all in nix/kernel.nix as the existing patches are:
panel-canaan-universal.c probe: request the reset GPIO GPIOD_ASIS
when lit (LILYGO 0051’s hunk, keyed on the runtime flag).canaan_panel_prepare(): when lit and this is the first prepare, skip
the reset pulses and the sequence, log that it did, and clear the flag;
any later prepare (DPMS, a second modeset after a disable) runs the full
path. Our own added reset pulses live in the same if.canaan_drv.c: skip drm_fbdev_generic_setup() when lit (LILYGO 0051’s
other hunk). This removes the boot-time modeset entirely; nothing touches
the pipeline until a DRM client opens the device. /dev/fb0 does not
exist on a splash boot, which is why display/panel is modified.Rejected: CONFIG_FRAMEBUFFER_CONSOLE_DEFERRED_TAKEOVER with fbdev kept.
It defers fbcon, but the modeset that clears the screen is the helper’s
own, from drm_fb_helper_hotplug_event → drm_fb_helper_set_par
(drm_fb_helper.c:1990) when the poll worker first sees the connector
change from unknown to connected; and the takeover itself fires on the
first console output at the current loglevel, which on this board is a
pr_warn about BTF every boot. Rejected: pre-filling the fbdev buffer with
the splash so the modeset is invisible — a patch to DRM core, not the
vendor driver, to solve a problem removing fbdev solves outright.
Layer: kernel.
Carry the image across the handoff, not the buffer. The reserved
region exists so the kernel does not allocate over what VO is still
scanning out; nothing in Linux reads it. The first Linux frame is the same
picture because the owner draws the same asset, from the store. Rejected:
a simple-framebuffer handoff. simpledrm would be evicted by
canaan-drm at probe through the aperture helpers, and canaan-drm’s
first modeset still has to run the VO initialization/timing and commit path;
the buffer identity alone buys nothing. The explicit display-block reset is in
the disable path. Rejected: making the reserved region the
CMA pool so the first GEM allocation lands on the U-Boot buffer — the
address is not guaranteed and dma_alloc_wc zeroes it anyway. Layer:
device tree, userspace.
The address is one constant in the flake, and it is chosen against a
recorded map — candidate 0x10000000, 4 MiB
(0x10000000..0x10400000). docs/evidence/stage1-memory-map.md now
records the physical-board bdinfo and the candidate image’s bootm lines:
the range is 86 MiB above the loaded initrd end (0x0aa07d8e), above but
clear of loadaddr (0x0c000000), below the force_dtb scratch address,
and 764 MiB below U-Boot’s exact LMB reservation beginning at 0x3fb37920.
The current initrd relocates to 0x3e12f000, leaving
0x10400000..0x3e12f000 = 733 MiB for CMA. Source analysis therefore
predicts that the 512 MiB CMA pool can remain at the logged 0x1e000000;
a reserved-memory DTS build and board boot must verify that the kernel layout
is unchanged. Rejected:
0x1f000000, LILYGO’s number. It is clear of everything stage 1 loads
or relocates, but it is inside the CMA pool the kernel places at
0x1e000000..0x3e000000. A no-map reservation there is excluded from
memblock allocation (drivers/of/fdt.c:479-494,
mm/memblock.c:1001-1025), splitting the free range into 335 MiB below
the hole and 493 MiB above it, and 512 MiB fits in neither; the likely
result is cma: Failed to reserve and the display driver’s dma_alloc_wc
falling back to the page allocator — reasoning from source, unverified on
the board, and the reason not to find out on the board. LILYGO’s images
survive it because they boot without an initrd, so their free range above
the hole runs to the top of RAM (524 MiB); this system pins 26 MiB of
initrd at the top at exactly the moment CMA is placed. The
constant feeds CONFIG_K230_BARE_DISP_LOGO_FB_ADDR (a new Kconfig symbol
replacing LILYGO’s #define) and the reserved-memory node’s reg
through the device tree’s preprocessor, so they cannot disagree. Rejected:
the vendor’s env_get_bootm_size()-as-an-address trick (k230_logo.c:198)
— it returns the size of the bootm region, is meaningful only by
accident, and its staging copy at 0x1000000 sits inside our kernel.
Rejected: no-map omitted so the kernel could reuse the 4 MiB — VO is
still reading it when the kernel starts, and 4 MiB of 1 GiB is not worth
the class of bug. Layer: Nix, stage 1, device tree.
Splash format: XRGB8888, as LILYGO’s path scans out; one asset, one
derivation. A PNG in the repository; a Nix derivation renders it to
568x1232 XRGB8888 with a size check equal to 2 799 104 bytes
(568 x 1232 x 4; LILYGO’s RM69A10_LOGO_XRGB_SIZE, and the U-Boot code
refuses any other filesize), and the same derivation produces the frames
the Linux-side owner uses, so frame 0 on both sides is the same bytes
through different pipelines. Rejected: RGB565 to halve the buffer — it
would diverge from the only U-Boot scanout configuration proven on this
panel, to save 1.4 MiB. Layer: Nix.
Linux-side owner: Plymouth in the systemd initrd if it cross-builds
within the shell stack’s budget; otherwise a minimal DRM splash in the main
system, with no animation until the shell. The rule is written here so
that the task that measures it does not also get to decide it. Budget:
no more than the 89 derivations / 875 MiB the shell change measured for
sway + foot + wvkbd, counted with the same method
(docs/display-environment-options.md). Why Plymouth first: it already does
the whole job — starts from the initrd, opens DRM, animates, and
plymouth quit --retain-splash leaves the last frame for the compositor —
and NixOS’s boot.plymouth module integrates it with the systemd initrd
this board uses. Why not assume it: nixpkgs’ plymouth lists
platforms.linux and no riscv64 exclusion, but nobody has built it for
riscv64 here, and its dependency graph (systemd, libdrm, freetype, pango
for the label plugin) is exactly the kind that arrives with a second
toolchain. Why the fallback has no animation: a splash that starts at 22 s
cannot animate anything a person is still waiting to see; it exists only
to satisfy the retain-until-the-shell property. Rejected as the sole
approach: letting the shell change’s compositor own the screen from the
start — sway starts after the same 22 s and its first act is a clear to its
background; it is the end of the handoff, never the middle. Rejected: an
animation in U-Boot — single-threaded, and every frame is time the kernel
is not being loaded. Layer: Nix, userspace.
The fallback owner uses the primary plane’s actual formats and hands master
off before the shell opens DRM. docs/evidence/drm-info.txt records that
the K230 primary plane supports RG16 and AR24 but not XR24. The static asset
remains B,G,R,X so that it matches stage 1; the fallback enables universal
plane enumeration, defaults to an
explicit RG16 conversion and permits AR24 only after discovering it on the
selected primary plane. It discovers the connected connector, preferred mode,
usable CRTC, and primary plane instead of treating their observed IDs as an
ABI. When the shell is about to start, it sends SIGUSR1; the owner calls
drmDropMaster() while retaining its fd and dumb framebuffer, acknowledges
that state, then polls until a non-zero successor framebuffer differs from
its own. It does not clear the CRTC; only after that successor is observed
does it remove its replaced framebuffer and dumb allocation. This avoids
using close-time DRM object lifetime as the handoff mechanism, but it does
not establish seamless scanout: only task 5.4’s film can prove that Sway’s
first modeset and the driver’s cleanup leave no dark frame. The service is
enabled only for a shell-enabled, non-console image. Shell restart treats an
already dropped master or an inactive optional owner as safe to proceed, but
refuses to open DRM if an active owner never acknowledges scanout. Layer: Nix,
userspace.
Console on the panel becomes k230.panelConsole, off by default. On:
console=tty0 stays, FRAMEBUFFER_CONSOLE is used, and Nix omits the
splash file from the boot partition, so stage 1 leaves the panel dark and
the kernel path is exactly today’s. Off: no console=tty0, splash file
present. The kernel is the same binary in both; the switch is a file on the
card and a command line, which is why it is cheap to flip while chasing a
panel regression. Rejected: a kernel command-line knob to turn off the
splash preservation — it would let the two sides disagree, and the failure
would look like a dead panel. Layer: Nix.
0x87 behaves differently under U-Boot’s PHY routine. → LILYGO’s
2-lane routine waits 20 ms where the SDK waits 1 ms and orders the resets
differently from canaan_phy.c. Prove the path on LILYGO’s numbers first,
then change one parameter at a time, measuring with tools/panel-measure.py.0x10000000 is under U-Boot’s heap or where bootm relocates the
initrd. → The physical-board bdinfo puts U-Boot’s LMB reservation at
0x3fb37920..0x40000000, and the current Loading Ramdisk to line ends
at 0x3fb36d4e; both are far above the chosen range. The remaining risk
is a future load command added without updating the recorded map. The CMA
placement risk is handled by the address decision above.31/30/12, our DT bytes send 13, and
the port rewrites the C to match the DT. Record both in
docs/evidence/rm69a10-init-sequence.md side by side, and make the
divergence table the place a future change has to edit.docs/evidence/ in task 1.1, with the commit hash, before anything
depends on it.Nothing here is destructive, and every step is reversible by removing a
file. The splash file absent from the boot partition is the old behaviour
in stage 1; the /chosen flag absent is the old behaviour in the kernel;
k230.panelConsole = true is the old behaviour in Nix. Stage 1 changes ride
the from-source build, so a stage 1 that fails to boot is recovered the way
every-blob-is-built-from-source-or-named recovers: a second card with the
last known-good image. The kernel patches are gated by the flag, so a
kernel carrying them boots identically on a card without a splash, which
is how they are tested before the U-Boot side lands.
plymouth quit --retain-splash and the compositor’s first modeset
compose cleanly on this driver, or whether the compositor’s drmModeSetCrtc
triggers the panel disable/enable path (and so, on the fallback, a
blink). Answerable only once the shell change has a compositor to start;
it changes how task 5.4 is filmed, not what is built.bootdelay should shrink now that the splash makes
the wait visible. Out of scope here and noted for
the-card-is-flashed-over-usb-from-u-boot, which is the change that needs
the prompt.The preserve-image trial isolates first-enable VO/DSI reprogramming and shows
correct automatic shell geometry, visible successive color updates, no-logo
console recovery and display off/on recovery. Its code remains on
diagnostic/preserve-splash-image, separate from the daily default. The
remaining dark gap is independently visible in the camera recording.
Pinned Sway and wlroots source explains an initial empty scene before the bar
and deferred terminal commands start; see
docs/evidence/splash-preserve-trial/compositor-startup.md. An owner-service
delay cannot put the logo into the compositor’s first framebuffer. Add an
opt-in Sway scene seed using the existing immutable 568x1232 BGRX asset,
constructed in an enabled scene layer before the first backend commit. Output
layers initially live under disabled staging, so merely creating it in an
output layer before request_modeset() is insufficient.
Place the placeholder above background clients and below normal shell content.
Keep it until an actual toplevel buffer and the mapped Swaybar panel surface are included in
a successful output commit and the matching presentation event is observed.
A mapped descriptor, background-only frame, successful TEST_ONLY call or an
unrelated presentation does not meet this condition. Presentation events are
software evidence; camera footage remains required for the physical claim.
Validate asset type and exact size, handle read/allocation failures, release buffer resources on teardown, and leave the existing compositor selected when the option is disabled. Missing or invalid assets must log a clear error and allow the ordinary shell to start. Do not depend on home state. Cold boot, normal no-logo shell, display re-enable and touch acceptance remain required; a draft or passing cross-build does not enable the new default.
The pinned Swaybar uses ZWLR_LAYER_SHELL_V1_LAYER_BOTTOM with namespace
panel in normal dock mode (swaybar/bar.c:105), not the top layer.
The readiness predicate must follow this actual surface; the first diagnostic
image seeded the logo but never retired it because it checked the wrong layer.
The pinned modetest exposes built-in -F patterns and an output writeback
file, but no input image file. The same-logo test therefore uses the unchanged
immutable k230-drm-splash: it validates the B,G,R,X asset, converts it to
RG16, verifies primary-plane support and calls drmModeSetCrtc once. This
corrects the proposed test tool without weakening the same-image requirement
or the physical dark-frame/fallback decision.
Both automatic display units are command-line masked for the controlled idle boot. Copies under temporary alternate unit names allow the first owner and Sway to start in a deliberate order without bypassing regenerated masks. The next-boot arguments are restored before the display experiment; a final normal reboot removes the runtime units and verifies automatic startup.
Dependency satisfied: every-blob-is-built-from-source-or-named is
archived on master. Stage 1 tasks edit source, Kconfig or the generated
environment through nix/uboot-k230.nix and nix/stage1.nix. The remaining
unchecked tasks below are the current acceptance gates.
Groups 1, 3 (build half), 4 (build half), 5.1 and 6.1 are laptop claims.
Everything that says hardware takes the board — say when you take
/dev/ttyACM0 and when you release it — and is proven by a photograph or a
console capture under docs/evidence/. QEMU proves nothing anywhere in
this change: its k230 machine models neither stage 1 nor a display.
board/canaan/common/logo/ files against the SDK copies on disk, their k230_canmv_t_display_defconfig display lines, and their Linux patches 0027, 0038, 0051, with the Xinyuan-LilyGO/T-Display-K230 commit hash they were read at. Verify by committing docs/evidence/lilygo-uboot-logo.md and confirming every path the change’s specs cite appears in it — laptop claimfirmware/stage1/tdisplay.env, the kernel Image size and its extent from 0x200000, OpenSBI’s FW_JUMP_FDT_ADDR, the initrd size, CONFIG_SYS_LOAD_ADDR, CONFIG_SYS_BOOTM_LEN, and the vendor logo path’s 0x1000000 staging address, each with the file and line it came from. Verify by committing docs/evidence/stage1-memory-map.md with a “read from the board” section left explicitly empty for task 2 — laptop claimm, n and voc the Linux driver uses for 49.5 MHz / 594 Mbps by working canaan_dsi_clk_cfg() (canaan_dsi.c:316-383) by hand, and put them beside LILYGO’s {4, 97, 0x19, 0x96} and the SDK’s ST7701 {9, 196, 0x17, 0xa3} in one table. Verify by adding the table to docs/evidence/dsi-hsfreqrange-hardcoded.md and checking the derived lane rate reproduces the DSI PHY: lane 594000 kbps line already in the boot log — laptop claimProves group 1 — laptop claim. git diff --stat showing only docs/evidence/, and ./scripts/build_site.py exiting 0 with the new evidence reachable.
bdinfo at the U-Boot prompt: relocaddr, reloc off, ram_top, fdt_blob, and the malloc base if printed. Verify by committing the transcript into the “read from the board” section of docs/evidence/stage1-memory-map.md — hardware claim. Ticked against docs/evidence/uboot-usb-host-coexist.txt: 1 GiB DRAM, relocaddr/offset 0x3ff3b000, embedded fdt_blob 0x97020, malloc 0x3fb39000..0x3ff3b000, and LMB reservation 0x3fb37920..0x40000000; recorded in the map §2.1.bootm’s own load messages — Loading Ramdisk to …, Loading Device Tree to … — with ./tools/capture-boot.py. Verify by committing them to the same document and marking each address in the map as loaded, relocated, or scratch — hardware claim. Ticked against docs/evidence/boot-from-source-cold.txt lines 85-86 (Loading Ramdisk to 3e135000, end 3fb3fa65 / Loading Device Tree to 000000000a0eb000, end 000000000a0ff681) and line 134 (Domain0 Next Arg1 : 0x000000000a0eb000): a real cold boot of the current stage 1, accepted by the coordinator as this task’s evidence; classified in stage1-memory-map.md §2.3.0x10000000 / 4 MiB (design.md; 0x1f000000 is rejected there because it sits inside the kernel’s CMA pool); move it only if 2.1 shows U-Boot’s relocated code or heap within it, or the map shows a stage 1 load reaching it. Verify by writing the chosen address, its size and the reason into the map, and releasing the board — hardware claim for the inputs, a written decision for the output. Chosen 0x10000000..0x10400000: the current map records it clear of all stage-1 loads, 764 MiB below the measured U-Boot LMB reservation, and below CMA; see stage1-memory-map.md §2.4.Proves group 2 — hardware claim. docs/evidence/stage1-memory-map.md with a bdinfo transcript and bootm load lines from /dev/ttyACM0.
nix/uboot-k230.nix as patches applied after the overlay copy, with a Kconfig fragment setting CONFIG_K230_BARE_DISP_LOGO=y and CONFIG_K230_BARE_DISP_LOGO_RM69A10=y, and replace their #define RM69A10_LOGO_FB_ADDR with a Kconfig symbol fed from one flake constant. Verify with nix build .#uboot-k230 succeeding and grep -c k230_display_logo result/u-boot being non-zero — laptop claimm/n/voc from 1.3, hs_freq 0x87 — and match VID_MODE_CFG and DPI_COLOR_CODING to what canaan_dsi.c writes, recording every value that differs from LILYGO’s in docs/evidence/dts-divergence.md’s table. Verify with nix build .#uboot-k230 and the divergence table listing each register once — laptop claimassets/, rendered to 568x1232 XRGB8888, failing the build unless the output is exactly 2 799 104 bytes (568 x 1232 x 4, the value LILYGO’s RM69A10_LOGO_XRGB_SIZE check compares filesize against; docs/evidence/lilygo-uboot-logo.md). Verify with nix build .#bootSplashImage and stat -c %s result/logo.xrgb printing 2799104 — laptop claimlogo.xrgb on the boot partition from nix/sd-image.nix, behind the option from 6.1, and add the splash file to the list of things stage 1 requires of the partition in docs/evidence/uboot-env.txt. Verify with nix build .#sdImage and debugfs -R 'ls /' <boot partition> listing logo.xrgb beside Image — laptop claimreserved-memory node for the splash buffer to nix/dts/k230-tdisplay.dts, taking its reg from the same flake constant as 3.1 through the preprocessor. Verify with nix build .#deviceTree and fdtget result/k230-tdisplay.dtb /reserved-memory/framebuffer@10000000 reg printing the chosen address and size (path adjusted if 2.3 moved it) — laptop claim./tools/capture-boot.py capture in which the moment of the photograph precedes Starting kernel, both under docs/evidence/ and referenced from docs/evidence/boot-splash.md — hardware claimtools/panel-measure.py exactly as dsi-hsfreqrange-hardcoded.md measured the Linux one. If it rolls or is dark, fall back to LILYGO’s full table (39.6 MHz / 0x96) to prove the path, then change one parameter at a time until our mode is stable, recording each step. Verify by committing the measurement table to docs/evidence/boot-splash.md with motion figures at or below the 0x87 row of the earlier document, and releasing the board — hardware claimBuild-host tasks 3.1, 3.2, 3.3 and 3.5 passed on 2026-09-22; see
docs/evidence/splash-port-build.txt. A narrow same-card trial subsequently proved the stage-1 splash on glass
while held at U-Boot; docs/evidence/boot-splash.md records the photograph,
video, USB regression pass and a physical Linux handoff defect. The logo is
left disabled pending that fix. Task 3.6 remains unchecked because the
prescribed second-card procedure has not been performed. The splash-enabled
diagnostic full-image build and host-side boot-partition
inspection now satisfy 3.4; see docs/evidence/splash-preserve-trial/build.txt
and image-contents.txt in that directory. This does not close a physical
handoff task.
Proves group 3 — hardware claim. A photograph plus a timestamped console capture showing the splash before Starting kernel, and a measurement showing no roll. The laptop half is nix build .#uboot-k230 .#bootSplashImage .#deviceTree .#sdImage.
k230_display_logo() has loaded the image and sent the init sequence; ft_board_setup() writes that state into /chosen as a boolean without using the persistent environment. Verify with nix build .#uboot-k230 and strings result/u-boot | grep finding the property name — laptop claimpanel-canaan-universal.c in nix/kernel.nix: read the /chosen flag at probe, request the reset GPIO GPIOD_ASIS when set, and in prepare() skip both reset pulses and the init sequence on the first prepare only, logging that it did and clearing the flag so a later prepare runs the full path. Patch canaan_drv.c to skip drm_fbdev_generic_setup() when the flag is set. Record both in docs/evidence/kernel-patches.md with their drop conditions. Verify with nix build .#packages.x86_64-linux.xuantie-kernel succeeding and each sed guarded by its grep -q as the existing patches are — laptop claimdocs/evidence/boot-splash-handoff.md showing /proc/device-tree/chosen carrying the flag, the driver’s “stage 1 splash: leaving fbdev unset” message, no panel prepare/init sequence before a DRM client starts, ls /dev/fb0 failing, and a photograph of the splash still on the glass at the prompt. The panel driver’s “left as stage 1 set it” line belongs to the first DRM modeset in 4.4, not the idle-kernel phase — hardware claimk230-drm-splash under a temporary first-modeset-owner.service copied from the built unit. Its first drmModeSetCrtc must scan out the same stage-1 logo converted to RG16; record its format/connector/CRTC/framebuffer line. Stock modetest cannot load the logo (its -F selects built-in patterns), so it cannot perform this same-image check. AR24 is optional only if the selected primary plane advertises it. Verify by committing the frame-by-frame result to docs/evidence/boot-splash-handoff.md: record whether the first modeset’s VO/DSI initialization and commit path produces a dark interval, its measured length, and whether the panel recovers without replaying its init sequence. This task decides the fallback: if it shows a dark interval, restore reset + init in prepare, re-run, record the blink, and restate the boot-splash requirement to what was measured — hardware claimlogo.xrgb removed. Verify by committing a capture showing the flag absent from /proc/device-tree/chosen, the panel driver sending the init sequence, /dev/fb0 present, and a photograph of the console on the panel — this is the “stage 1 did not light it” scenario and it must still look like panel-lit.md. Release the board — hardware claimProves group 4 — hardware claim. docs/evidence/boot-splash-handoff.md with both boots captured and the first-modeset film. The laptop half is nix build .#packages.x86_64-linux.xuantie-kernel.
5.1 Measure what Plymouth costs to cross-build for riscv64 against the pinned nixpkgs with the same method as docs/display-environment-options.md: derivations to build and unpacked size for boot.plymouth.enable = true with a minimal theme, on top of the existing closure. Verify by committing docs/evidence/boot-splash-owner.md with the numbers beside the shell stack’s 89 / 875 MiB budget and a one-line verdict applying the design’s rule — laptop claim
5.2 NOT TAKEN: 5.1 measured 897.3 MiB against the 875 MiB budget (over by 22.3 MiB), so 5.3 was taken instead (see the paragraph after group 5 and docs/evidence/boot-splash-owner.md). Original text: If 5.1 is within budget: enable boot.plymouth in nix/hardware.nix with a theme whose first frame is the 3.3 asset, running from the systemd initrd, and remove console=tty0 from the default command line. Verify with nix build .#nixosConfigurations.k230.config.system.build.toplevel and lsinitrd-equivalent inspection of the initrd showing plymouthd and the theme present — laptop claim
5.3 If 5.1 is over budget: add a minimal DRM splash program to the closure — opens /dev/dri/card0, sets the mode with a dumb buffer holding the 3.3 asset, holds it, and on a signal from the shell drops DRM master while retaining its buffer until a non-zero successor framebuffer replaces it, then releases only the replaced buffer without clearing — and start it as the first thing in the main system. Verify with nix build .#nixosConfigurations.k230.config.system.build.toplevel and the unit present in the closure; record in docs/evidence/boot-splash-owner.md that there is no animation and why — laptop claim
The splash-enabled toplevel build and installed conditional unit passed; see docs/evidence/splash-owner-build.txt. This is a build-host claim only.
5.4 MOVED, NOT PERFORMED HERE: Hardware. Film a complete boot from power-on to the owner’s last frame — and, if the-screen-runs-a-shell-not-a-console has landed, to the compositor’s first frame. Verify by committing the frame timings to docs/evidence/boot-splash-handoff.md showing no dark frame between the splash appearing and the last frame filmed, and the first Linux frame indistinguishable from the last stage 1 frame. Release the board — hardware claim
Proves group 5 — hardware claim. The filmed boot in docs/evidence/boot-splash-handoff.md. The laptop half is nix build .#nixosConfigurations.k230.config.system.build.toplevel with the measurement committed.
Task 5.1 measured 76 derivations / 897.3 MiB fetched-unpacked with the
minimal built-in spinner theme on 2026-09-22. The written 875 MiB budget is
exceeded by 22.3 MiB, selecting task 5.3 rather than 5.2. This is an
incremental dry-run cost, not installed closure size; see
docs/evidence/boot-splash-owner.md.
nix build .#shell-compositor-initial-splash, source review of initial staging/commit order, and recorded invalid-asset behavior.k230.panelConsole (default false) to the NixOS module: true keeps console=tty0 and omits logo.xrgb from the boot partition; false does the reverse. Verify with nix eval .#nixosConfigurations.k230.config.system.build.toplevel.drvPath succeeding with the option in both states, and nix build .#sdImage with it true producing a boot partition without logo.xrgb — laptop claim Done 2026-10-12 as a laptop claim, on the configuration .#sdImage builds today (k230-mainline-drm-shell, panelConsole = true via flake.nix:130-134): nix build .#sdImage exited 0 and debugfs on the boot partition finds no logo.xrgb and console=tty0 in bootargs.txt; the toplevel drvPath evaluates with the option in both states. See docs/evidence/splash-close-sdimage/README.md. The false state was evaluated, not built into an image, here.UNVERIFIED markers in display/boot-splash and image/boot-chain against the captures from groups 3, 4 and 5, restating any requirement 4.4 changed, and confirm every carried patch is in docs/evidence/kernel-patches.md as system/kernel requires. Verify with openspec validate the-screen-lights-before-linux and ./scripts/build_site.py exiting 0 Done 2026-10-12 by scope split: markers that committed evidence cannot ground are kept, reworded to name the successor the-mainline-kernel-keeps-the-boot-splash; every carried kernel patch is in docs/evidence/kernel-patches.md (stage-1 splash preservation, first-VO/DSI preservation). Verified with openspec validate the-screen-lights-before-linux --strict and python3 scripts/render_specs.py.Proves group 6. openspec validate --all and ./scripts/build_site.py both exiting 0.
Task 4.1 build evidence: docs/evidence/daily-shell-image-3f397a6.md records
the source-built U-Boot output and its runtime property string. This does not
verify a logo-enabled physical handoff. The daily image omits the logo.
2026-09-22 runtime-flag trial: docs/evidence/boot-splash-handoff.md proves
logo preservation to the Linux serial prompt and the successful /chosen
flag/no-fb0 path. No prepare message appears until the first modeset, because
no DRM client has prepared the panel before that point. Starting Sway then
logs the one-shot skip but still produces a physically wrapped/color-shifted
screen. Tasks 4.3/4.4 stay open: the prescribed second-card/matching-logo-mode
procedure is not complete, and the final handoff is still defective. The
normal no-logo boot configuration was restored after capture.
2026-09-22 same-kernel missing-logo regression satisfies task 4.5: docs/evidence/splash-preserve-trial/README.md links the no-flag/full-prepare/fb0 console transcript and physical console frame. The diagnostic splash configuration was restored afterward. The same trial proves physical content updates but still shows a compositor startup dark gap; task 5.4 remains open.
2026-09-22 integrated initial-scene candidate: docs/evidence/splash-initial-scene-ready/README.md records the matching kernel/compositor builds, successful seed retirement, and physical warm-boot samples without the earlier dark gap. Tasks 5a.1/5a.2 are complete. The earlier wrapped/color-shifted observations above are historical failures, not the latest result. Tasks requiring a second card, calibrated geometry, full power-on continuity, and physical keyboard acceptance remain open.
2026-09-22 follow-up: docs/evidence/splash-initial-scene-ready/keyboard-visibility-audit.md supplies physical show/hide visibility at camera focus 30 for task 5a.3; full label readability and real touch remain separate. docs/evidence/splash-uboot-motion/README.md records an attempted task 3.7 measurement that failed optical registration, so that box stays open. The normal logo, tiled shell and camera controls were restored.
2026-09-22 controlled first-modeset acceptance: docs/evidence/splash-first-modeset-preserve/README.md and its frame-by-frame audit close 4.4: 420 consecutive frames around owner startup retain the logo; the later shell transition also has no captured dark frame. The matching kernel journal records first VO/DSI preservation and the prepare skip. Task 4.3 retains its unmet second-card prerequisite; 5.4 retains its power-on requirement. Normal automatic startup was restored.
2026-09-22 option checks: docs/evidence/splash-option-acceptance/README.md records both toplevel derivation evaluations and a fresh canonical console-image build/boot-partition inspection. These host checks pass; 6.1 remains open because the final effective splash default still awaits physical acceptance.
2026-09-28 system/hw closeout audit: k230.panelConsole (nix/panel-console.nix, default false) already exists and is wired exactly as 6.1 specifies — flake.nix:76 selects splashImage = if cfg.k230.panelConsole then null else bootSplashImage, and nix/hardware.nix/nix/shell.nix gate console=tty0 ordering and the k230-drm-splash owner service on the same option. This session re-ran nix eval .#nixosConfigurations.k230.config.system.build.toplevel.drvPath (default false) and nix eval .#nixosConfigurations.k230-console.config.system.build.toplevel.drvPath (true); both succeeded. The second half of 6.1’s named proof — nix build .#sdImage with the option flipped to true, inspecting the boot partition for the absence of logo.xrgb — was not run this session: a build-slot was already busy with concurrent agents’ cross-builds (handheld-shell-rust, k230-coherent-shell toplevel) at closeout time, and this task’s own command implies temporarily flipping the default and reverting it, which this audit chose not to do while sharing the store with other in-flight builds. 6.1 stays unticked; only that one build/inspection step remains, the wiring itself is source-verified.
The operator chose “Close with a successor” on 2026-10-11. Tasks 3.6, 3.7, 4.3
and 5.4 are marked MOVED, NOT PERFORMED HERE: each is a hardware task, none
was performed to its stated proof, and each is preserved verbatim, with its
proof command, in the-mainline-kernel-keeps-the-boot-splash. Task 5.2 is
NOT TAKEN (5.1 selected 5.3). A ticked box on a moved or not-taken task
records the scope decision, not a physical result: no second-card boot, calibrated U-Boot motion
measurement, idle-kernel handoff capture or power-on film exists. The
board now runs the mainline kernel (k230-mainline-drm-shell), whose device
tree has no splash reserved-memory node; those prerequisites are tasks in
the successor too.
Defines what the panel shows from the moment the board is powered until the system draws its first frame, which stage of the boot owns each part of that, and how a lit panel is handed from one stage to the next without going dark.
Stage 1 SHALL initialise the panel and scan out an image from the boot partition before it loads the kernel, so that a person who powers the board sees the screen respond before any of the system has run. Stage 1 owns this requirement; nothing in the system contributes to it.
The image SHALL be loaded by exact filename from the root of the boot
partition, the same way stage 1 finds Image. When the file is absent stage
1 SHALL leave the panel untouched and continue booting, so that removing one
file restores the behaviour of a board without a splash.
Grounding, vendor source read on 2026-09-22. Canaan’s U-Boot overlay carries
a bare-metal display path for the CanMV’s ST7701 —
.build/k230_linux_sdk/buildroot-overlay/boot/uboot/u-boot-2022.10-overlay/board/canaan/common/logo/,
enabled by CONFIG_K230_BARE_DISP_LOGO (arch/riscv/cpu/k230/Kconfig:35,
which selects LAST_STAGE_INIT so k230_display_logo() runs from
last_stage_init() before the autoboot countdown). k230_logo.c:200 loads
/logo.yuv with ext4load, st7701.c:807 resets the panel, sets the PHY,
programs DSI and VO timing and points a layer at the picture. LILYGO’s
official BSP extends that path to this panel: its overlay’s k230_logo.c
adds a CONFIG_K230_BARE_DISP_LOGO_RM69A10 case with a 568x1232 XRGB8888
/logo.xrgb at 0x1f000000, st7701.c gains rm69a10_568x1232_init()
and GPIO_RST_PIN 22, and display_logo.c gains a 2-lane PHY routine and
an OSD4 scanout. Their init sequence is not the one this project sends:
its rows 6-8 are the partial-area block 31/30/12, which lit this panel
under Linux but glitched (docs/evidence/panel-lit.md), and which
nix/dts/display-rm69a10-568x1232.dtsi replaced with 13
(ENTER_NORMAL_MODE). Stage 1 sends the DTSI’s sequence. Recorded, with the
commit hash and the full diff, in docs/evidence/lilygo-uboot-logo.md.
Their U-Boot returns -1 and skips the logo when the load fails
(k230_logo.c, _k230_display_logo_load_pic). The vendored k230_canmv_v3
configuration this project builds does not enable any of it.
Starting kernel, and a timestamped capture together with a photograph records itStage 1 SHALL drive the panel at the pixel clock, lane rate and DSI PHY
calibration band the system’s device tree declares, so that the handoff is
not also a mode change. In particular the PHY calibration band at this
board’s lane rate is 0x87, and stage 1 SHALL use it rather than the value
either vendor hardcodes.
Grounding: measured on this board under Linux, like for like, changing only
the device tree value — 0x96 (the value in canaan_dsi.c:383 (pristine; 428 as patched) and in
LILYGO’s U-Boot k230_logo.c connector table) works and rolls, 0x97 blanks
the panel, 0x87 is stable to 0.02 px over 30 s;
docs/evidence/dsi-hsfreqrange-hardcoded.md. The system’s mode is 49.5 MHz,
568x1232, htotal 748, vtotal 1268, 2 lanes, 594 Mbps —
nix/dts/display-rm69a10-568x1232.dtsi. LILYGO’s U-Boot runs 39.6 MHz and
475 Mbps with 0x96, which sits inside the band that value calibrates for
and is why it works for them.
docs/evidence/dsi-hsfreqrange-hardcoded.md0x87 under Linux, not the rolling figures for 0x96DSI PHY: line reports the same lane rate and hsfreqrange stage 1 usedWhen stage 1 reports that it lit the panel, the system SHALL NOT pulse the panel’s reset line, SHALL NOT replay the panel’s initialisation sequence on its first enable, and SHALL NOT scan out a cleared buffer during boot. The first thing the system draws on the panel SHALL be a deliberate frame from whatever owns the screen, not a side effect of a driver probing. When stage 1 did not light the panel, the system SHALL initialise it in full as it does today.
The kernel owns this requirement, and it SHALL take the fact “the panel is lit” from stage 1 at boot time rather than from a static property of the device tree, so that a boot on which stage 1 failed to light the panel is a boot on which the kernel lights it.
Grounding, vendor kernel source read. panel-canaan-universal.c:318-329
pulses reset at probe; canaan_panel_prepare() (lines 124-150) replays
init_seq_v1, and nix/kernel.nix adds three reset pulses in front of it
because the panel would not answer otherwise. The modeset that puts a cleared
buffer on the screen during boot comes from the fbdev emulation:
canaan_drv.c calls drm_fbdev_generic_setup() at bind, the helper
allocates a zeroed dumb buffer (drm_fbdev_generic.c:89-98), and the first
commit is driven from the output poll worker — the soft-lockup trace in
docs/evidence/dsi-phy-hang.md is exactly that path,
output_poll_execute → canaan_dsi_encoder_enable. LILYGO’s kernel patch
0051 takes the same two steps (reset GPIO requested GPIOD_ASIS, fbdev
setup skipped) but keys them on a static device tree property; a board whose
logo failed to load would then never be lit at all. ft_board_setup() in
board/canaan/common/k230_board_common.c:574 is where the vendor U-Boot
already edits the device tree before boot, and is where a runtime flag can be
written.
stage 1 splash: leaving fbdev unset, no panel prepare/init occurs before a DRM client starts, and the first later DRM prepare logs that it left the panel as stage 1 set itdocs/evidence/panel-lit.md, and the framebuffer console is available on it when configuredFrom the moment stage 1 lights the panel until the shell draws its first frame, the panel SHALL NOT show a dark frame, and the first frame the system draws SHALL be the same image stage 1 was showing. An animation MAY run from that frame onward. Whatever owns the screen during that interval SHALL retain its last frame until the shell’s first frame replaces it, rather than clearing the screen and exiting.
Userspace owns this requirement. It is met by the thing that opens the display device first, and that thing is chosen in design.md against a measured build cost rather than assumed.
Grounding for the shape of the problem: userspace starts about 22 s into
the kernel boot on this board (docs/evidence/panel-probe.txt,
[ 22.947804] systemd[1]), so an owner that starts in the main system first carries forward a static
stage-1 frame. The measured build-cost decision in
docs/evidence/boot-splash-owner.md selects the minimal main-system DRM owner;
this change does not implement animation during that initial interval.
The system SHALL offer two configurations and default to the first: a boot
that shows the splash and puts no console on the panel, and a boot that
lights the panel from the kernel and shows the framebuffer console on it as
the-screen-comes-up-under-linux left it. Selecting the second SHALL be one
option in the NixOS configuration, and SHALL be what a person reaches for
when the panel path itself is being debugged.
Grounding: the console configuration is what runs today — console=tty0
via lib.mkBefore in nix/hardware.nix and FRAMEBUFFER_CONSOLE=y in
nix/kernel.nix, photographed in
docs/evidence/panel-photos/05-console-on-panel.jpg. It is kept because
every diagnosis in docs/evidence/ since the panel lit has depended on
seeing the kernel’s messages, and a splash that hides them would make the
next panel regression harder to see, not easier.
Grounding: observed on hardware — photographs in docs/evidence/panel-photos/.
The panel was driven to three known states from a shell on the board —
/dev/urandom (speckled bright field), /dev/zero (dark), and 0xFF
bytes (bright) — and photographed each time. Three states rather than one
deliberately: a single bright frame could be a reflection and a single
dark frame is what a dead panel looks like, so the change is the
evidence. A fourth photograph shows the kernel console rendering on the
panel at 71x77 characters. See docs/evidence/panel-lit.md.
What is NOT yet grounded: the image still moves slightly. The 25% DSI
burst headroom fix referred to here was confirmed on hardware and it
blanks the panel outright; it was reverted in a96ca99. See
docs/evidence/dsi-burst-headroom.md.
On the corrected image, measured over 30 s with the webcam exposure
locked and the oblique view rectified by a four-fiducial homography, so
the numbers are in real panel rows: brightness is now flat (95%..101% of
mean, against 19 dips with the worst at 53% before), and the residual is
a uniform whole-frame vertical shift of about 2.8 rows RMS out of
1232. Near and far halves of the panel move identically — std 2.76
against 2.76, correlation 0.959 — so there is no accumulation down the
frame and no tearing. Mechanism is not established; the untested
hypothesis is that 35 00 SET_TEAR_ON is issued but nothing consumes
TE. See docs/evidence/flicker-after-headroom-revert.md.
The roll was subsequently stopped by the DSI PHY calibration band:
canaan,hsfreqrange = <0x87> in the device tree,
docs/evidence/dsi-hsfreqrange-hardcoded.md.
The system SHALL present the panel as a display device at 568x1232 through
DRM, and what the system draws on it SHALL appear on the screen. The
framebuffer console on the panel — /dev/fb0 and console=tty0 — SHALL
remain available as a configuration, and SHALL be the configuration used
when the panel path is being debugged; it is no longer what a boot shows by
default, because display/boot-splash puts a splash there and the console’s
takeover is what would clear it.
Why this changed: the fbdev emulation is the thing that performs the first
modeset during boot, from the output poll worker onto a zeroed buffer
(drm_fbdev_generic.c:89-98, and the trace in
docs/evidence/dsi-phy-hang.md). A splash that survives the kernel cannot
coexist with it, so it becomes the debugging configuration rather than the
default. Nothing about the DRM device, the mode, or the plane formats
changes; modetest -s 48:568x1232@AR24 set a mode on this panel before the
fbdev fix was ever applied (docs/evidence/kernel-patches.md).
A framebuffer device existing is not evidence. This SHALL be grounded by a
photograph of the physical screen, because a pipeline that reports success and
shows nothing is a failure mode this hardware has already produced once — the
Wi-Fi driver reported start ap successs! while transmitting nothing.
Stage 1 SHALL initialise the panel and put a splash image on it before the kernel is loaded, from a file it finds on the boot partition by exact name, and SHALL skip the splash without failing the boot when that file is absent. Stage 1 owns this. The image format, the filename, the address the image is scanned out from and the display mode used are properties of the stage 1 this project builds and SHALL be recorded where the other things stage 1 requires of the boot partition are recorded.
Grounding: Canaan’s U-Boot overlay ships the mechanism for a different panel
(board/canaan/common/logo/k230_logo.c, gated by CONFIG_K230_BARE_DISP_LOGO
in arch/riscv/cpu/k230/Kconfig:35 and run from last_stage_init()), and
LILYGO’s BSP overlay carries the RM69A10 case of it —
CONFIG_K230_BARE_DISP_LOGO_RM69A10, /logo.xrgb, 568x1232 XRGB8888 at
0x1f000000 (an address this change rejects; docs/evidence/stage1-memory-map.md), reset on GPIO22 — in
k230_bsp/overlay/buildroot-overlay/boot/uboot/u-boot-2022.10-overlay/board/canaan/common/logo/
of Xinyuan-LilyGO/T-Display-K230, read 2026-09-22. Neither is enabled in
the k230_canmv_v3_defconfig this project builds.
Image, the device tree, the initrd and bootargs.txt, with the address it is scanned out fromThe project SHALL keep one document listing every physical address stage 1
loads something to or hands to the next stage — the kernel image and its
extent, the initrd and where bootm relocates it, the device tree as loaded
and as OpenSBI passes it on, OpenSBI itself, the environment import buffer,
U-Boot’s own relocated code and heap, and the splash buffer — with the size
of each and the source it was read from. Any new address stage 1 uses SHALL
be chosen against that map and added to it. The splash buffer SHALL be
reserved from the kernel through the device tree, and the address SHALL be
written in exactly one place in the flake from which both stage 1 and the
device tree take it.
Grounding: the map does not exist, and its absence has already cost a
corrupted kernel. docs/evidence/opensbi-fdt-lands-in-kernel-image.md proves
on the board that OpenSBI copies the device tree to 0x2200000, 32 MiB into
the 57 MiB kernel at 0x200000, and that the board survives only because
that lands in .BTF. The vendor’s logo path stages its picture at
0x1000000 (k230_logo.c:206), also inside our kernel. The addresses known
so far, from firmware/stage1/tdisplay.env and
docs/evidence/stage1-emergency-mode.md: Image at 0x200000,
bootargs.txt at 0x7000000, OpenSBI at 0x8000000, the DTB at
0x8400000, the initrd at 0x9000000, CONFIG_SYS_LOAD_ADDR=0xc000000; RAM
is 1 GiB and the kernel’s CMA is half of it (k230_defconfig,
CONFIG_CMA_SIZE_PERCENTAGE=50).
Grounding: docs/evidence/stage1-memory-map.md §§2.1–2.4 records physical
bdinfo, U-Boot relocation/LMB/malloc/stack ranges, actual bootm initrd and
DTB relocation messages, and the resulting splash address decision. The map
classifies loaded, relocated, scratch, U-Boot, and kernel-time ranges.
/proc/iomem or the device tree on the running boardBefore handing over, stage 1 SHALL record in the device tree it passes to the kernel whether the panel is initialised and scanning out, and SHALL record it only when that is true. This is a fact about the boot in progress, not about the board, so it SHALL NOT be a static property of the device tree source.
Grounding: the vendor U-Boot already edits the device tree before boot —
ft_board_setup() in board/canaan/common/k230_board_common.c:574 rewrites
the memory node, and board_fdt_chosen_bootargs() in k230_img.c:110
rewrites /chosen/bootargs (docs/evidence/stage1-emergency-mode.md). The
flag is one more property in the same place. LILYGO’s kernel patch 0051 keys
the kernel’s behaviour on a static canaan,preserve-boot-splash instead;
that design leaves the panel dark on any boot where the logo failed to
load.
Grounding: docs/evidence/splash-initial-scene-ready/inspection.txt records
/chosen/canaan,stage1-splash present on the splash boot;
docs/evidence/splash-preserve-trial/no-logo-inspection.txt records
NO_SPLASH_FLAG when the logo is absent. The same captures show the
corresponding no-fbdev and full-initialization/fbdev paths. These are physical
serial-initiated warm boots; they do not claim battery-only operation.
/proc/device-tree/chosen on the booted board carries the flagGrounding: observed on hardware. The vendored chain loaded our kernel, our
device tree and our initrd from the card and reached userspace: uname -a on
the board reports Linux nixos 6.6.36 #1-NixOS ... riscv64
(docs/evidence/hardware-userspace.md). Stage 1 itself was not modified; the
two things it required of us were recorded rather than rediscovered — the
literal filenames its blinux variable ext4loads, and the fact that the
kernel command line comes from the U-Boot environment and not from
/chosen/bootargs (docs/evidence/stage1-emergency-mode.md).
Since then stage 1 has been modified twice, and deliberately: its
environment loads bootargs.txt and the initrd and moved OpenSBI and the
device tree above the kernel (docs/blob-inventory.md, row A3), and
every-blob-is-built-from-source-or-named builds it from source. The clause
that forbade modifying it is therefore removed. What survives is the
obligation to record what stage 1 requires of us.
Stage 1 SHALL load the kernel, device tree and initrd this project builds from the SD card. Where stage 1 requires a particular filename, location, image format or load address, that requirement SHALL be recorded as a property of the stage 1 this project builds rather than discovered again each time. Where stage 1 has already lit the panel, it SHALL hand the kernel a running display and the fact that it is running, and the kernel SHALL be able to tell that boot from one where it must light the panel itself.
Archived change · Archived
Snapshot 5836ef1d113d · 2026-10-17 08:22 UTC
Closed recordReview the archived record and cited scope
A person on real glass (568x1232 K230, installed system, master db5b0584)
reported: “in webos/card overview mode i see black / glitching”. The
coordinator’s native capture of the card overview (swaymsg card_shell enter, Monitor focused, Terminal open) confirmed a real defect: the Rust
Home screen’s always-mapped Layer::Bottom surface
(the-shell-presents-a-pinned-home-screen) painted through the overview.
The overview’s own deck canvas is deliberately transparent so a person sees
their wallpaper behind the cards (nix/card-shell/adapter.c’s
shell.canvas, in root->layers.shell_overlay, above every output layer);
before Home existed that transparency only ever revealed the plain
wallpaper. With Home now sitting in Layer::Bottom — directly above the
wallpaper and below the overview — the same transparency reveals Home’s
grid tile and dock instead: the “Video” tile sat beside the Monitor card,
and the dock covered “Swipe up for apps”.
IPC-driven card_shell enter/back alone did not reproduce dark or
glitching frames on their own account (a 30fps webcam recording of three
toggles showed none), so the coordinator asked for the animated,
finger-driven paths (bottom-edge swipe-up entry, drag/throw, swipe-up
close, tap-to-expand) to be reproduced under QEMU with per-frame capture
and root-caused. That investigation (this change’s design.md) found that
the touch-first two-axis entry gesture (cs_begin_entry in
nix/card-shell-policy/card-shell-policy.c) folds cs_enter’s CS_SHRINK
action into its own result and only afterwards overwrites the policy mode to
CS_ENTERING, so shell.active — and therefore the deck’s transparent
canvas — is already showing at the very first touch-down, well before any
visible drag distance. The Home bleed-through was therefore present for the
whole entry gesture and the whole settled overview, not only the single
steady-state frame the native capture happened to show, which is consistent
with a person describing it as “glitching”: Home’s grid and dock appearing
and disappearing as the deck animates in and out on top of it.
Layer::Bottom scene layer (Home’s only occupant)
whenever the card overview is active, and restore it exactly when the
overview hands the screen back — at the same two points
(nix/card-shell/adapter.c’s CS_SHRINK handling and restore()) that
already toggle ordinary_backdrop for the same reason, so there is no
frame in between where both the deck and Home are visible.card_shell debug-scene diagnostic with a
home_enabled field so this invariant can be asserted directly, not only
inferred from pixels.tests/test_card_shell_home_bleed.py, a new
native Layer::Bottom fixture tests/card_shell_home_layer.c) that maps
a distinctly-colored stand-in for Home, drives the real touch-first
two-axis entry/drag/quick-switch/close gesture sequence, sweeps every
captured frame for that colour, and confirms Home is hidden throughout the
gesture and the settled overview, restored once a card is refocused, and
genuinely re-shown once every card closes (so the fix cannot pass by
permanently disabling Home).nix/card-shell-policy/ changes; tests/test_card_shell_state.py’s 29
cases pass unmodified.nix/rust-shell-client/src/home_*.rs) are untouched; this is a
compositor-side scene-visibility fix only.design.md’s closing
note.Headless-QEMU-injected-input only, via the real cross-built
nix/card-shell compositor and a native touch device
(SWAY_K230_CARD_TEST_INPUT=1), not physical touch or panel proof. A board
re-check (the same native capture the coordinator used to confirm the
original bug) remains the outstanding evidence gate; see tasks.md.
the-shell-presents-a-pinned-home-screen added an always-mapped
Layer::Bottom Home surface (nix/rust-shell-client/src/main.rs’s
HomeSurface) directly above Layer::Background (the wallpaper) and below
every ordinary toplevel and the drawer/shade/Settings Layer::Overlay
surface. That change’s own decision 1 says a focused app or an open overlay
occludes Home “with no explicit ‘is anything else showing’ check in this
client at all” — true for ordinary opaque stacking, but it did not account
for the card overview, which is a compositor-native scene
(nix/card-shell/adapter.c’s shell.ui/shell.deck/shell.canvas,
created under root->layers.shell_overlay) that sits above
Layer::Bottom and is not fully opaque everywhere. The coordinator’s report
— a person on real glass seeing “black / glitching” in the overview, and a
native capture confirming Home’s grid and dock painting through the deck —
is that gap. Full root-cause detail, the exact scene layers involved, and
the reproduction/regression evidence are in
docs/evidence/card-shell/overview-home-bleed-through/README.md; this file
covers the decisions, not the mechanism twice.
adapter.c), not the Rust clientThe design considered had the Rust client learn the overview’s open/closed
state (over some new IPC or socket) and hide or repaint itself
transparently in response. Rejected: the Rust client today has zero
knowledge of card-shell state — main.rs never references shell.active,
card_shell, or Overview — and adding that coupling would mean a new
message contract, a new failure mode (client and compositor disagreeing
about who currently owns the screen), and a client-side unmap/remap or
buffer-content decision that costs a Wayland round trip and risks its own
black frame from a freshly reattached surface. The compositor already knows
shell.active authoritatively and already toggles a scene node
(shell.ordinary_backdrop) at exactly the two moments that matter for the
mirror-image reason (revealing the wallpaper only when nothing better-
informed, like the overview canvas, is deciding that already). Toggling
output->layers.shell_bottom’s enabled flag at those same two points is a
pure scene-graph mutation: no client round trip, no buffer churn, and (per
the evidence README) provably atomic with the deck’s own enable/disable
calls, so no frame renders with both visible.
Layer::Bottom tree, not just paint over Home’s boundsGrepping nix/rust-shell-client/src/main.rs confirms Home is the only
client ever mapped on Layer::Bottom in this shell (Layer::Bottom appears
exactly once, in HomeSurface’s own mapping). Disabling the whole layer
tree is therefore equivalent to disabling Home specifically, and is simpler
and more future-proof than adding a card-shell-specific opaque rect sized to
match Home’s bounds (which would need to track Home’s geometry and would
still leave a second thing to keep in sync if a future change ever changed
Home’s shape).
CS_SHRINK/restore() boundaries, not atshell.active’s read sites
shell.active is read in roughly twenty places in adapter.c but written
in exactly two (handle_result’s CS_SHRINK branch, and restore()).
Syncing home_layer_sync at the write sites, alongside the existing
ordinary_backdrop_sync calls, keeps the invariant obviously paired and
grep-able, rather than requiring a change everywhere shell.active might
newly matter. It also means the fix engages at the exact moment
cs_begin_entry’s folded CS_SHRINK result reaches adapter.c — gesture
start, not gesture end — which the evidence README’s entry-01-touch- down.png confirms directly.
debug-scene, don’t add a new IPC verbcard_shell debug-scene already exists precisely to make scene-graph state
assertable without inferring it from pixels (its own comment: “Self-evident
diagnosis for ‘the wallpaper is not visible’”). Adding home_enabled to its
existing output is one field, reuses the same board (journalctl) and test
(ipc()/assertIn) paths every existing consumer already has, and needs no
new command parsing.
Layer::Bottom fixture, not the real Rust clientRunning the actual handheld-shell-rust binary under this suite’s headless
QEMU harness would need its full runtime environment (desktop-entry
catalog, $XDG_STATE_HOME layout persistence, its own Wayland globals) for
behavior this fix does not touch at all — the bug and the fix are entirely
about compositor-side scene visibility, not Home’s content. A tiny native
fixture (tests/card_shell_home_layer.c, modeled directly on the existing
tests/card_shell_drawer_layer.c pattern already used for the drawer’s own
Layer::Overlay bleed testing) maps the exact same layer/anchor/size shape
with a single unmistakable colour, giving a fast, deterministic,
false-positive-resistant assertion surface without any Rust/cross-build
dependency in the test itself.
The coordinator’s other suspected black-frame sources — a scaled-cache or
bare-cards mirror texture that has not drawn yet, a newly launched app’s
first frame — were not found in the exercised two-axis entry/drag/quick-
switch/close/settle sequence (assert_no_black_flash in
tests/card_shell_runtime.py, applied to every frame that sequence
captures). This is evidence against those sources in that specific
sequence, not an exhaustive sweep of every gesture the coordinator listed
(see the evidence README’s “Limits” section). No change was made to
nix/card-shell/scaled-cache.c, nix/card-shell-policy/card-shell- policy.c’s pad/plate interpolation, or app-launch first-frame handling,
because no defect was found there to fix; a future change should extend
assert_no_black_flash-style coverage to a from-launch sequence and to
scaled-cache-enabled runs (--scaled-cache) if the board re-check (this
change’s remaining evidence gate) still shows glitching after this fix
lands.
.#card-shell compositor and identify the exact scene
layering gap (the deck’s unpainted title-bar band, and a themed
transparent canvas, both above Home’s Layer::Bottom); verify with
docs/evidence/card-shell/overview-home-bleed-through/before-overview- home-bleeds-through.png and its debug-scene capture.home_layer_sync to nix/card-shell/adapter.c, called from
the CS_SHRINK branch of handle_result and from restore(), alongside
the existing ordinary_backdrop_sync calls; extend card_shell debug-scene with a home_enabled field. Verify with nix build .#card-shell --max-jobs 1 --cores 6.python3 -m unittest test_card_shell_state (29 cases, run from tests/).tests/card_shell_home_layer.c (a native Layer::Bottom
fixture standing in for Home) and wire --home-layer-client into
tests/card_shell_runtime.py’s two-axis path: home_enabled/pixel
assertions across the real finger-driven entry/drag/quick-switch/close/
settle sequence, plus an independent assert_no_black_flash sweep of
every captured frame. Verify with python3 -m unittest test_card_shell_home_bleed test_card_shell_two_axis_runtime (run from
tests/).nix build .#card-shell outputs); recorded in the evidence README.docs/evidence/card-shell/overview-home-bleed-through/.runtime/shell requirement delta in this change; verify
with openspec validate the-overview-hides-the-home-screen --strict..#card-shell and .#handheld-shell-rust, evaluate
nixosConfigurations.k230.config.system.build.toplevel, and check
python3 tools/blob-scan.py’s exit code. All pass; see the evidence
README’s “Narrow proof commands”.card_shell enter / debug-scene console probe. Exact identities, commands and limits: docs/evidence/card-shell/overview-home-bleed-through/board-2026-09-30/README.md. Stills establish the observed state; prior QEMU regressions separately cover entry/mid-drag/settlement and self-healing.Found while investigating a separate, unrelated report (bottom-band panel
flicker, docs/evidence/card-shell/bottom-band-flicker/hypotheses.md):
home_layer_sync ran only from handle_result’s CS_SHRINK branch and
restore(), so it depended entirely on card_shell’s own state machine
running again to correct any drift. An unrelated Sway focus change while
the overview stayed open (an IPC [app_id=...] focus command reaching an
already-mapped card) was observed to re-enable layers.shell_bottom’s
scene node without shell.active or shell.policy.mode changing at all —
nothing in card_shell’s state machine would ever run home_layer_sync
again to notice or correct it.
home_layer_sync(output) unconditionally from
prepare_impl (nix/card-shell/adapter.c), on every frame, before that
frame’s scene is ever built or committed — idempotent (a single
scene-node-enabled read, at most one write) and self-healing regardless
of what caused the drift. Verify with nix build .#card-shell --max-jobs 1 --cores 6.tests/test_card_shell_home_layer_self_heal.py: opens the
overview, sends two unrelated focus IPC commands while it stays open,
and asserts debug-scene’s home_enabled never flips back to 1 (then
confirms Home genuinely returns once the overview is actually left, so
the fix cannot pass by disabling Home forever). Verified failing against
the unfixed adapter (a home_layer_sync call removed) and passing
against the fixed one (3/3 consecutive passes observed). Verify with
python3 -m unittest test_card_shell_home_layer_self_heal (run from
tests/).runtime/shell delta;
verify with openspec validate the-overview-hides-the-home-screen --strict.Grounding: Real-finger operator confirmation, native overview capture, physical panel photograph and sanitized scene probe on the installed themed system; docs/evidence/card-shell/overview-home-bleed-through/board-2026-09-30/README.md. Entry/drag and self-healing regression coverage remains explicitly headless QEMU evidence in docs/evidence/card-shell/overview-home-bleed-through/README.md.
The shell SHALL NOT show any part of the Home screen surface while the card
overview (card_shell’s deck) is active, for the whole duration the
overview is entered — including the finger-driven bottom-edge entry
gesture from its first touch-down, not only once the gesture settles — and
SHALL restore the Home screen’s normal visibility the moment the overview
hands the screen back to a focused application or to the idle/no-app state.
focus command reaching an already-
mapped card, or any other code path outside card_shell’s own gesture
and button handling), and the overview’s own state does not otherwise
changecard_shell’s state machine itself toggles
visibility (entering, leaving)Archived change · Archived
Snapshot 5836ef1d113d · 2026-10-17 08:22 UTC
Closed recordReview the archived record and cited scope
A tap on the physical bottom/power button currently resets the handheld immediately. That loses the current session and makes the button unusable as a normal display sleep/wake control. The user wants a short press to turn the display off or on and a deliberate hold to show a power menu whose destructive actions require confirmation.
Non-goals: suspend-to-RAM, battery operation, a hardware RESET switch if the user’s button is actually wired directly to reset, and autonomous long-press power cutoff for an unresponsive kernel. The physical button identity is a named first evidence gate.
system/power: Linux PMU key events and safe power-key policy on this board.runtime/shell: a global, touch-friendly power sheet opened by the physical key, with explicit confirmations.The kernel and device tree need the PMU INT0 input path; the image must carry the required configuration and safe default policy. The Sway/shell session needs a key event route, display off/on action and power sheet. The reserved board, serial console and native display capture are required for acceptance; host tests and QEMU can verify state transitions but cannot prove the key or panel.
The replacement card boots the coherent NixOS image with Sway, the Rust shell and a writable root. The operator reports an immediate reset on a tap of the lower physical button; the exact switch identity is awaiting confirmation. The current kernel/device tree contains no K230 PMU input device (docs/research/board-capability-inventory.md, power-key section); the running board currently exposes only its touchscreen input. LILYGO’s 0064-input-k230-pmu-pwrkey.patch supplies an edge-driven Linux input driver and PMU DT node, but its 5-second orderly_poweroff(true) and PMU system-off callback do not implement the requested confirmation flow. Its upstream source is k230_bsp/overlay/buildroot-overlay/linux/0064-input-k230-pmu-pwrkey.patch in Xinyuan-LILYGO/T-Display-K230.
The existing backlight path has physical proof for swaymsg output DSI-1 power off/on and restoring brightness (docs/evidence/backlight/runtime-recovery/README.md). The Rust shell already owns the Settings power confirmation and has a bounded route socket. The image and known-good card recovery copy are available.
Goals: Let Linux receive both power-key edges, preserve a running session on tap, reuse the proven output power cycle, and show a global confirmation sheet on hold.
Non-Goals: Suspend, battery operation, firmware-level emergency cutoff, or changing a separate electrically wired RESET switch.
orderly_poweroff and system-off registration for this change; both bypass the requested sheet. Preserve edge routing, debounce and input reporting, but review every PMU register write against the vendor flow. Stage a candidate with a read-only serial/evdev probe, one deliberate short physical press and known-good card recovery available before enabling the user policy. If a short press still resets before a Linux release event, stop hardware claims and keep the existing image available.K230 PMU Power Key evdev device, handles KEY_POWER press/release, debounces repeats and uses a monotonic hold threshold (initially 700 ms). It ignores synthesized EV_KEY repeat values and disconnects cleanly. logind ignores this key so it cannot also execute its default shutdown policy. The helper sends a bounded route request to the Rust shell on hold, and a Sway output-power command on a completed short press. It verifies the active output and remembers whether it turned it off; restart state is reconciled from Sway rather than a stale file.--surface power opens a compact sheet over the current app using the existing layer and theme tokens. Tap targets for Cancel, Power off and Restart are at least 56 px high. Selection opens the existing confirmation state and uses the same limited system request path as Settings. Touch outside and the existing dismissal gesture close without action. A long hold that begins while dark wakes the panel before opening the sheet; release does not toggle it back off.Rejected: copying the vendor patch unchanged (its hold powers off), mapping KEY_POWER directly to systemctl (no confirmation), and using zero backlight brightness as display sleep (the validated Sway output-power path preserves the chosen brightness).
Publish this proposal first. Build and inspect the input-only kernel candidate; then deploy to the reserved board using the repository’s guarded /boot update or the saved-image flash path. Prove physical events before enabling policy. Deploy helper and shell route from the image, verify short/long behavior, then record actual glass and serial evidence. Restore the saved coherent image if PMU boot or display recovery fails. Archive only after every named physical gate passes.
The short-press route names output * power off/on, not DSI-1. With HDMI connected the panel is absent from Sway (one CRTC), and the DSI-1 form stored “off” for it: on 2026-10-14 a press at 23:16:08 followed by an HDMI unplug at 23:16:11 brought the panel back dark. The wildcard acts on the display in effect and keeps the dark state across a hotplug, so the next press wakes whichever display is present.
docs/evidence/power-key/identity/README.md, and verify the record names which switch can be intercepted by Linux.
Done 2026-10-14 (operator + board-read): the operator’s button is the top
right one with the board in the keyboard case; each press logs INT0 press
and INT0 release and arrives as KEY_POWER on “K230 PMU Power Key” with
no reset, so it is SW2 (PMU INT0). docs/evidence/power-key/identity/README.md.nix build .#kernel and nix build .#deviceTree succeed./boot update path, boot with the reserved console, and record python3 tools/console.py /dev/ttyACM0 --wait=3 'cat /proc/bus/input/devices' plus a real short press/release event log; verify that the same system stays running. Keep this hardware task unchecked if the press still resets or release never arrives.
Done 2026-10-14 (board-read over SSH, on the installed mainline landscape
image rather than a staged candidate): /proc/bus/input/devices lists the
key, and evemu-record logged two taps as press/release pairs (195 ms and
160 ms) with the boot ID unchanged. Limit: read over SSH, not
tools/console.py, because /dev/ttyACM0 on this bench is another device.
docs/evidence/power-key/mainline-events/.KEY_POWER to it; verify host state-machine tests cover a short press, hold, repeats, bounce, disconnect and one action per gesture, then build its narrow Nix derivation.output DSI-1 power off/on route for short presses and reconcile state after service restart; verify a host fake-command test does not turn a hold into a short press or wake into an app action.tools/console.py system/uptime command and store it in docs/evidence/power-key/display/.
Done 2026-10-14 (board-read + operator): the board logged DSI-1 power
false at 16:24:12 and true at 16:24:16 with continuous uptime and one boot
ID; operator: “it worked”. Camera waived by the operator; no serial log
(/dev/ttyACM0 is another device). docs/evidence/power-key/display/.power route with themed sheet, large touch targets, dismiss/Cancel, Power off and Restart; verify cargo test in nix/rust-shell-client and nix build .#handheld-shell-rust.
Done 2026-10-14 (host): the power route paints the themed sheet with
68 px Restart…, Power off… and Cancel rows, and a named two-button
confirmation; cargo test passes (511 + 22) and nix build .#handheld-shell-rust built at master 339fb0f6 (jj55fw9i…). Board
captures: docs/evidence/power-key/sheet/.nix build .#nixosConfigurations.k230-coherent-shell.config.system.build.toplevel, then record real-button/glass proof of hold → sheet → Cancel and hold → named confirmation without execution under docs/evidence/power-key/sheet/.
Partial 2026-10-14 (operator + native captures,
docs/evidence/power-key/sheet/): hold opened the sheet, Cancel closed it,
and Restart… showed the named confirmation with nothing run (boot ID
unchanged). The trial found the confirmation’s split bar easy to mis-tap and
the sheet not closing on a swipe; the revised sheet (two named buttons,
larger tap area, swipe to close) has host tests only. Open: the revised
sheet on the board, and the named k230-coherent-shell toplevel build.
Done 2026-10-14/15 (board journal + native capture + operator,
docs/evidence/power-key/sheet/): on boot 7c8f203e… a 1.15 s hold opened
the revised sheet, Restart… showed “Restart device?” with separate Cancel
and Restart buttons (revised-restart-confirmation-grim.png), a tap at
y=498.6 on Cancel cancelled it, and the boot ran on (operator: “it works
go”). nix build .#nixosConfigurations.k230-coherent-shell.config.system.build.toplevel
built 0m0wgs1p… at 339fb0f6 and 4n1simq4… at c1a4ed6d. Limit: the
hold → sheet → Cancel step on the sheet itself is the 16:38 trial.devm_register_power_off_handler, the patch 0064 register sequence:
long-press wake source, PMU_STATUS normal power-down, PMU system-control
pulse). The vendor’s automatic 5 s orderly_poweroff() stays out, as task
1.2 decided. Reason: keyboard-base 6.6 showed systemctl poweroff only
halted with the board powered (no SBI SRST), draining the battery.
Power-on afterwards is by a ~3 s hold of the power key (96000 PMU ticks).
Partial 2026-10-14 (docs/evidence/power-key/power-off/): with the handler,
systemctl poweroff cut power (operator: “it shut off this time”) and a
~3 s power-key hold started the board again with USB-C still connected; a
reboot returned on its own (board-read). Open: Restart and Power off
confirmed from the shell’s sheet, with serial or camera evidence.
Done 2026-10-14 (board-read + operator, docs/evidence/power-key/sheet/):
Restart confirmed from the sheet ran systemctl reboot and the board came
back on its own (boots ccd3f704… to c988db76…); Power off confirmed from
the sheet ran systemctl poweroff, the board stayed dark until a ~3 s key
hold (operator: “it did”), then booted dadc6e5c…. Limit: no serial or
camera capture (camera waived; /dev/ttyACM0 is another device).openspec validate the-power-key-controls-the-display-and-power-menu --strict, commit the physical evidence with exact commands and limits, and archive only when every task and named proof above is complete. Verify merged master, pushed revision, CI and the published capability page.
Done 2026-10-15: openspec validate --strict passed, the evidence above is
committed with its commands and limits, and the change is archived with
every task complete. Merge, push, CI and the published page are checked
after the push of this commit.Grounding: On the board 2026-10-14, a held power key opened the sheet, Cancel closed it, and Restart… showed the named two-button confirmation whose Cancel left the boot running (docs/evidence/power-key/sheet/). Swipe dismissal and the denied-action report are host tests (service_ui power-sheet tests); outside-tap dismissal was not tried on the glass.
The shell SHALL present a readable, touch-operated power sheet above the current app when the physical power key is held. It SHALL offer Cancel, Power off and Restart. Tapping outside or using the shell dismissal gesture SHALL close the sheet without a system action. The sheet SHALL not strand a user when an action is unavailable.
Grounding: Board-read and operator 2026-10-14: Restart and Power off ran only after their named confirmation (journal systemctl reboot/poweroff from the shell), and cancelling the confirmation kept the same boot ID (docs/evidence/power-key/sheet/).
The shell SHALL require a second touch confirmation naming Power off or Restart before invoking it. Opening the power sheet or merely holding the key SHALL never confirm an action. Confirmation SHALL use the same bounded system authority as the existing Settings power controls.
Lets the physical power key control the handheld display and request explicit system power actions without losing the running session on an ordinary tap.
Grounding: The mainline k230-pmu-pwrkey driver logs INT0 press and release for the top-right button (SW2), and evemu recorded one KEY_POWER press and release per tap with the board still running (docs/evidence/power-key/identity/, docs/evidence/power-key/mainline-events/). The separate RESET button is outside this driver.
The system SHALL expose press and release of the identified physical PMU power key to Linux as input events. An ordinary press SHALL NOT directly reset or shut down the running system. The system SHALL leave any separately wired hardware RESET button outside this policy.
Grounding: Board-read and operator 2026-10-14: taps darkened and woke the panel in the same session (DSI-1 power false/true), and with HDMI connected the same taps sent output * power off/on and blanked and woke the monitor (docs/evidence/power-key/display/).
A short physical power-key press SHALL turn the display in effect (the panel, or the HDMI monitor while it is the output) off when lit and on when off, keeping that state across an HDMI hotplug, while preserving the running applications and selected brightness. Waking the panel SHALL consume that key gesture without activating an application or power action.
Grounding: On the board 2026-10-14, a 1.15 s hold opened one sheet with the system still running (journal INT0 press, map-request, INT0 release; docs/evidence/power-key/sheet/); the 0.7 s threshold and no toggle after a hold are host tests (tests/test_power_keyd.py). The PMU’s own long-press power-off is not exercised.
The system SHALL distinguish a deliberate hold from a short press. A hold SHALL open the shell’s power sheet once and SHALL NOT also toggle the panel on release. A hold alone SHALL NOT reboot or power off the system.
Archived change · Archived
Snapshot 5836ef1d113d · 2026-10-17 08:22 UTC
Closed recordReview the archived record and cited scope
The handheld has one Linux CPU online even though the K230 contains two C908 cores. Enabling a guessed second CPU could reset a core, conflict with the vendor AMP ownership model, or leave Linux without correct timer, interrupt, and cache-coherency support. The current single-core shell and recovery path must stay usable while the project reaches an evidence-backed decision.
Non-goals: enabling CPU1, adding a cpu@1 DTS node, changing OpenSBI, loading
RT-Smart, writing reset/power/mailbox registers, or claiming a video speedup.
system/second-core-readiness: The system preserves safe single-hart
operation and supplies a read-only evidence/decision path before any
second-core bring-up is attempted.The current board boots a source-built Canaan-overlay OpenSBI 1.4 and a Linux
6.6.36 kernel with CONFIG_SMP=y, yet stage 1, the live device tree, and Linux
all enumerate exactly hart 0. See proposal.md and the existing
docs/research/second-core-feasibility.md for prior evidence. The shell, USB
recovery, display, VPU, and current video tests must remain available.
Vendor SDK source provides a distinct AMP mechanism rather than a normal Linux
SMP configuration: k230-amp.c maps a reserved RT-Smart region, explicitly
writes it back from cache, programs CPU1_HART_RSTVEC, then toggles CPU1_RST_CTL.
That source establishes that releasing the other core has real ownership and
cache consequences. It is not carried by this image and is excluded here.
Goals:
Non-Goals:
The helper reads /sys/devices/system/cpu, the live /proc/device-tree CPU,
PLIC and timer nodes, /proc/cpuinfo, and existing dmesg messages. It does
not issue SBI calls: even HART_GET_STATUS would add a new runtime interaction
whose behavior for an undocumented hart is not needed to establish that the
current handoff is one-hart. It also avoids MMIO reads because the known RMU
register includes write-one-to-clear bits and board access is owned by the
coordinator.
Linux’s cpu_ops_sbi.c calls SBI_EXT_HSM_HART_START only after a second DT
CPU has supplied a hart ID. Generic OpenSBI derives platform hart count from
/cpus; the current single CPU node therefore explains the one-hart banner.
The observed HSM extension means the ecall handler exists, not that an
undocumented CPU1 is assigned to the domain or has a release vector.
Linux SMP requires shared page tables, spinlocks, TLB/IPI operation and matching CPU topology. Vendor AMP instead supplies a firmware image, reserved memory, cache maintenance, reset vector, and interprocessor protocol. Combining them would hide incompatible peripheral and power-domain ownership decisions.
No deployment changes occur. The coordinator may run the read-only helper and commit a sanitized transcript. A later implementation proposal must cite that transcript plus vendor source for every gate, build a rollback-capable image, and stop at the first failed secondary-hart condition.
docs/research/second-core-feasibility.md with the pinned DTS/Linux/OpenSBI call chain and the vendor AMP source contract; verify source paths and primary links distinguish facts from hypotheses.sh -n tools/second-core-readiness.sh and bash tools/test-second-core-readiness.sh pass without a board.tools/second-core-readiness.sh on the known-good board and commits a sanitized transcript; verify it shows the OpenSBI/domain, live DT, and Linux CPU observations without changing CPU state. Hardware proof; not runnable under QEMU.openspec validate the-second-c908-core-is-investigated-safely --strict and the helper fixture test; leave hardware tasks unchecked until the coordinator records board evidence.Physical tasks: docs/evidence/second-core/README.md, live-handoff.txt, and
opensbi-banner.txt establish the snapshot, decision and remaining gates.
Preserve the working single-hart handheld while giving operators a reproducible, read-only basis for deciding whether a future second-core project is safe.
The system SHALL provide a board-side collection command that reads Linux CPU state, the live CPU and interrupt device-tree descriptions, and already emitted SBI/SMP kernel messages without writing MMIO, changing CPU online state, loading modules, or invoking a reset, power, mailbox, or HSM start operation.
Grounding: docs/evidence/second-core/live-handoff.txt records the physical read-only collection; tools/second-core-readiness.sh defines its operations.
The project SHALL record whether stage 1 and the live device tree enumerate a second hart separately from vendor claims about two physical C908 cores. It MUST NOT identify a Linux logical hart with a physical core from CPU count alone or treat a compiled SBI HSM extension as proof that another hart can start.
Grounding: docs/evidence/second-core/opensbi-banner.txt and docs/evidence/second-core/live-handoff.txt separately record the firmware and live Linux handoff.
/cpus tree, and Linux CPU masks each describe one hartcpu@1 node or a hart releaseBefore a later change may release a second core for Linux SMP, it SHALL have source- or board-grounded evidence for the second hart ID and reset/vector protocol, OpenSBI domain/HSM behavior, local timer and IPI/PLIC routes, CPU ISA and cache description, and a CPU-to-CPU shared-memory coherency contract. A separate AMP path SHALL additionally define its firmware image, reserved memory, cache maintenance, mailbox protocol, and exclusive peripheral ownership.
Grounding: docs/evidence/second-core/README.md records the decision against each prerequisite; docs/research/second-core-feasibility.md traces the pinned firmware/kernel and vendor AMP sources.
Archived change · Archived
Snapshot 5836ef1d113d · 2026-10-17 08:22 UTC
Closed recordClosed on operator acceptance; see evidence for waived captures and retained limits.
Operator report, verbatim: “when i swipe down in the app drawer to scroll
back up, it closes the drawer that’s no good also review the design of the
app drawer it’s fuggin awful as is performance.” The scroll-reversal
drag-to-close bug landed separately, in its own reviewed commit. This
change covers the other two complaints, after a first attempt at both was
reviewed by the coordinator and correctly rejected: the redesign “was the
same design with a 4th column” (only COLUMNS/icon sizes changed; tile
plates, header, footer all unchanged), and the performance fix (a label
cache alone) still estimated 95-236ms/frame on the board — “isn’t a fix.”
Full review, including the rejected first attempt and why it fell short:
docs/design/app-drawer-review.md.
paint_drawer_tile, render.rs). Icon
fallback: a round, theme-accent-tinted circle with the initial —
confirmed rare against a real catalog (docs/evidence/app-drawer/).paint_drawer_chrome, render.rs;
navigation::handle_rect/search_field_rect).navigation::search_keyboard_key_at), filtering the grid live and
case-insensitively by substring (service_ui::filter_app_indices) —
a cheap, uncached linear scan over this repo’s bounded (128-entry)
catalog. An alphabetical fast-scroller remains explicitly out of
scope (needs its own grid-width layout coupling this device’s small
catalog does not justify).navigation::panel_top,
replacing the old ~19%-of-height gap) rather than most of a screen
of dead space above it.DrawerGridCache,
render.rs), rebuilt only when the filtered catalog, theme, panel
width or search query actually changes; an ordinary scroll/fling frame
reuses it and blits one viewport-sized slice instead of repainting
every tile. IconCache::paint_label (from the earlier, rejected
attempt) is retained — it is what makes each real rebuild (e.g. one
search keystroke) cheap. Host benchmark, driving the real
RendererCache::draw path over 200 simulated scroll frames of a
64-app catalog: cold (fresh cache every frame) 33.6ms/frame, warm
(persistent, scroll-only) 0.87ms/frame — a 38.8× reduction. Scaled by
this repo’s own established 20-40x host-to-board multiplier, the
estimated board cost is 17.3-34.6ms/frame: straddling the ~20ms target
(clears it at the low end of the multiplier, not at the high end) —
reported honestly as UNVERIFIED, a real order-of-magnitude
improvement over both the original uncached approach and the earlier
rejected label-cache-only attempt, not claimed as a confirmed pass.
K230_DRAWER_FRAME ms=… (rate-limited, main.rs) lets the coordinator
read the real number on the board directly.runtime/shell: modifies the app grid’s presentation requirement (no
per-app plate, round icon fallback, search) and adds a requirement for
board-readable drawer frame timing. See specs/runtime/shell/spec.md
in this change. (The drag-to-close direction-correctness requirement
from the earlier bug-fix commit is unchanged by this change.)nix/rust-shell-client only (Rust shell client): navigation.rs,
service_ui.rs, main.rs, render.rs, icon.rs. No device tree,
kernel, or NixOS module changes. No new dependency. cargo build .#handheld-shell-rust and the full system closure both cross-build
(riscv64) as proof the change compiles for the target; no QEMU or board
run was performed for this change. Real-finger, on-board frame-timing,
and real-finger search verification remain open gates (tasks.md §6).
Follow-up after real-glass acceptance (2026-09-30): search should use the normal wvkbd keyboard shared with Foot and Wi-Fi. The operator noticed the current compact custom keypad; track replacement, focus cleanup, reflow and new physical proof in tasks 6.1–6.3.
The operator accepts this delivered functional scope and waives additional
capture-only acceptance gates. docs/evidence/proposal-closeout/2026-10-01/drawer.md records the exact report,
prior evidence and limits. Its task dispositions supersede older statements
that these acceptance gates remain open; they do not claim new test runs.
Pending measurement work is preserved in the-shell-profiles-reported-interaction-jank before archive.
Userspace: the Rust shell client (nix/rust-shell-client). No device tree,
kernel, or NixOS module changes.
Rejected: the first redesign attempt (3→4 columns only). Kept every
per-app tile as a themed rounded-rect card, the full header and footer,
and search deferred. Coordinator review: “it’s the same design with a 4th
column.” Correct — only the grid arithmetic changed. Replaced entirely by
the design in docs/design/app-drawer-review.md: no tile plate, header/
footer removed, search implemented.
Rejected: reusing the WiFi password entry’s on-screen keyboard for
search. That keyboard (render.rs’s paint_wifi) is hand-coded to that
screen’s own full-height layout (hardcoded literal coordinates throughout,
e.g. 530.0 + row as f64 * 90.0), with shift/symbols state coupled to
WifiView. Reusing it for the drawer would need factoring it into a
generic, position-parameterized component first — real surgery on a
screen this change does not otherwise touch, for a feature (symbols/shift)
search does not need (matching is already case-insensitive, so there is
nothing typing an uppercase letter or a symbol changes about which apps
match). Built a new, smaller, lowercase-only keyboard purpose-fit to
search instead (navigation::search_keyboard_key_at).
Rejected: an alphabetical fast-scroller. Would need its own hit-region carved out of the grid’s right edge, coupling grid-width layout math to whether the rail is showing. This device’s catalog is capped at 128 apps and the real installed set is far smaller — a scroll rail solves a “thousands of apps” problem this handheld does not have. Named as an explicit non-goal, not silently dropped.
Rejected (this change): scroll-direction damage-limited blitting (shift
the already-composited on-screen bitmap by the scroll delta, paint only
the newly-exposed strip). The cached-bitmap architecture actually shipped
(DrawerGridCache) already turns the per-frame cost into one blit of a
bounded, viewport-sized area regardless of catalog size — the
order-of-magnitude win was already captured there. A further win from
also avoiding re-blitting the unchanged overlap between two adjacent
scroll positions is real but marginal next to that, and adds real
complexity (tracking a previous frame’s composited pixels, dirty-strip
edge math). Left as the named next lever (docs/design/ app-drawer-review.md §6) if board measurement (open task 5.2) shows the
current architecture still falls short, rather than built speculatively
now.
Rejected: rebuilding the grid cache incrementally (single-row patch)
instead of wholesale. A single search keystroke, or a catalog rescan,
can change which apps are in the filtered set at every position (not
just append/remove at the end), since filtering re-derives the whole
display list from scratch each time (service_ui::filter_app_indices).
Diffing the old and new filtered lists to patch only the changed rows
would be more code for a rebuild that already only happens on a real
content change (not every scroll frame) and, per the host benchmark, costs
under 1ms warmed/33ms cold either way — not on the frame-rate-critical
path a scroll/fling actually exercises.
tasks.md 5.2).The operator accepted reversal and search but immediately noticed search uses a different keyboard from Foot and Wi-Fi. The compact launcher-painted rows were an initial prefix-filter shortcut, not a hardware limitation. Replace them with the normal wvkbd surface, ordinary Wayland text keys and the shared show/hide helper. Reuse Wi-Fi’s narrowly scoped keyboard focus approach for an active Search field, and release it on Done/Enter, Escape, app launch, route exit, surface loss or seat loss. Keep Wi-Fi secret state independent from public search text. Size the list’s visible region from the actual keyboard reservation rather than assuming the old 300px custom keypad; its scroll cache remains keyed by the current catalog/filter/theme. Preserve existing edge-intent routing and original desktop-entry launch behavior. The already accepted compact-keyboard check is historical proof; the replacement needs its own real-glass acceptance.
The operator additionally reported that tapping compact Backspace closes the drawer and the Search field never displays an insertion cursor. The replacement SHALL show a themed focus ring and a steady insertion caret, keep long queries horizontally visible at the insertion point, and use the system keyboard’s own correction key. Home’s bottom handle passed the separate operator check. No real-glass acceptance of the replacement is inferred from that Home result.
The operator accepts this delivered functional scope and waives additional
capture-only acceptance gates. docs/evidence/proposal-closeout/2026-10-01/drawer.md records the exact report,
prior evidence and limits. Its task dispositions supersede older statements
that these acceptance gates remain open; they do not claim new test runs.
Pending measurement work is preserved in the-shell-profiles-reported-interaction-jank before archive.
navigation.rs/service_ui.rs/main.rs: Contact:: scrolled_away, drawer_close_candidate_after_scroll, and the
“no fling in flight” gate at touch-down. Landed in commit
5bcf6ef5 (“fix(drawer): stop a mid-gesture scroll reversal from
closing the drawer”), with no layout/visual changes, before the
redesign work below. Proven there:
cargo test --lib/--bin (233 lib + 20 bin passed at that
commit), cargo clippy (zero new warnings).paint_drawer_tile
(render.rs) paints only a 64px icon and a single-line
ellipsized 14px label directly on the sheet, no service_card
call for the tile itself.Icon= value by Icon= value against
the built system closure and the real k230-touch-launcher
binary’s own XDG_DATA_DIRS. Confirmed a harness gap in this
change’s own evidence-gathering (the first screenshot’s
hand-assembled XDG_DATA_DIRS never included pkgs.foot/
pkgs.htop/videoProbe.player’s own share/ roots, and never set
K230_ICON_THEME), not an icon.rs resolution defect — full
table in docs/evidence/app-drawer/README.md. Re-rendered with
the exact real XDG_DATA_DIRS (extracted from the built
k230-touch-launcher binary) and K230_ICON_THEME=Yaru-purple:
every application now resolves a real icon. Fixed anyway, as
defense in depth: catalog::terminal_like (reads Terminal=/
Categories= from the raw desktop file) plus a
utilities-terminal fallback retry in paint_drawer_tile, for
any future application whose icon name genuinely is not in the
bundled theme. Proven: catalog::tests:: terminal_like_reads_the_terminal_flag_and_the_category (new).scene()
returns early into a dedicated paint_drawer for Route::Drawer
that never calls the old header/footer code at all.navigation::handle_rect/search_field_rect,
paint_drawer_chrome).navigation::search_keyboard_key_at/
search_keyboard_hit), live case-insensitive substring filtering
(service_ui::filter_app_indices), and display-index-to-catalog
mapping so launch/long-press resolve to the correct app while
filtered (ShellClient::drawer_filtered_apps/
launch_drawer_app/pin_drawer_app, main.rs).rounded_top, new helper), filling from a small fixed top inset
(navigation::panel_top = 32px, replacing the old ~19%-of-height
gap); panel_travel_height’s Drawer case updated to match.COLUMNS = 4, ROW_HEIGHT = 110.0, equal 24px
margins/gutters (dividing 568px width with no remainder), a
subtle round press highlight in place of the old bordered square.
GRID_BOTTOM_INSET shrinks from 72px to 24px now that there is
no footer to reserve space for.navigation.rs (four_columns_hit_only_painted_tiles,
search_field_hit_is_bounded_to_its_own_pill_and_above_the_grid,
handle_rect_is_centered_above_the_search_field,
search_keyboard_key_at_resolves_letters_and_the_control_row,
search_keyboard_hit_matches_its_own_top_edge, plus the geometry
fixes to pre-existing scroll tests now that 30 apps no longer
overflow the redesigned viewport); service_ui.rs
(filter_app_indices_matches_case_insensitive_substrings,
drawer_search_key_focus_and_clear,
drawer_close_drag_zone_is_the_top_chrome_and_the_grid_only_at_top);
render.rs (drawer_grid_cache_rebuilds_only_when_its_own_key_changes,
scrolling_repaints_clipped_rows_but_keeps_chrome,
pressed_grid_tile_has_a_visible_highlight_without_affecting_its_neighbor).docs/evidence/app-drawer/ with a README recording the exact
commands, limits and blob-inventory rows. Proven: python3 tools/blob-scan.py --no-vendor exits 0.DrawerGridCache (render.rs): pre-renders the entire
filtered grid into one bitmap, keyed on (filtered display list,
theme generation, panel width, search query); rebuilt only on a
key change. paint_drawer blits one viewport slice per frame
instead of repainting every tile. Proven:
render::tests::drawer_grid_cache_rebuilds_only_when_its_own_key_changes
(new).IconCache::paint_label (from the earlier, rejected
attempt) since it still earns its keep making each real cache
rebuild (e.g. one search keystroke) cheap.K230_DRAWER_FRAME ms=… rate-limited timing log
(DRAWER_FRAME_LOG_INTERVAL = 500ms), gated to Route::Drawer,
in main.rs’s draw.#[ignore]d host benchmark
(render::tests::drawer_grid_cache_host_timing) driving the real
RendererCache::draw path over 200 simulated scroll frames of a
64-app catalog. Measured on this host (AMD Ryzen 9 5950X, cargo test --lib --release drawer_grid_cache_host_timing -- --ignored --nocapture): cold (fresh cache every frame) 33.60ms/frame mean,
warm (persistent, scroll-only) 0.87ms/frame mean — a 38.8×
reduction.docs/evidence/card-shell/backdrop-blur-feasibility.md §3),
warm estimates to 17.3-34.6ms/frame — straddles the ~20ms target
(clears it at the low end of the multiplier, not at the high
end). Reported as such in docs/design/app-drawer-review.md
§3.4, an honest order-of-magnitude improvement over both prior
estimates, not claimed as a confirmed pass.cargo test --lib (nix/rust-shell-client): 248 passed, 1
ignored (the opt-in benchmark, §3.4), 0 failed.cargo test --bin k230-shell-rust: 22 passed, 0 failed.cargo clippy --lib --bins --test appearance_module --test background_decode_module --test service_data_module (excluding
tests/theme_catalog_module.rs, which fails to compile on
master itself for reasons unrelated to and out of scope for
this change — confirmed via a baseline check before this change’s
first commit): zero new warnings in navigation.rs,
service_ui.rs, main.rs, icon.rs, catalog.rs or
render.rs (the same 6 pre-existing baseline warnings as before
this change, unchanged in kind).nix build .#handheld-shell-rust --max-jobs 1 --cores 6 --no-link --print-out-paths: exit 0,
/nix/store/6vwwhrxgxpligcijpgay34qjww2wd5ml-k230-shell-rust-riscv64-unknown-linux-gnu-0.1.0.nix build .#nixosConfigurations.k230-coherent-shell.config.system.build.toplevel --max-jobs 1 --cores 6 --no-link --print-out-paths: exit 0,
/nix/store/jdcpajgdlbvhgyhhwan6rnnhc4xwjy2p-nixos-system-nixos-26.11.20260919.20b1ddd.openspec validate the-app-drawer-is-redesigned --strict:
valid. python3 scripts/render_work_board.py > /dev/null: exit
0. python3 tools/blob-scan.py --no-vendor: exit 0 (see 2.9).origin/master twice: once past the
feat/brightness-slider merge (real, concurrent edits to
main.rs/render.rs/service_ui.rs — resolved by hand, import
lists and struct field lists only, no logical overlap, since that
work owns the Settings brightness row and the shade and this
change owns only the Drawer), and again with git rebase --onto origin/master 870135ac after the coordinator landed this
change’s own bug-fix commit on master directly as 44e54e35
(a byte-identical cherry-pick of 870135ac, confirmed via git diff --stat 870135ac 44e54e35 producing no output) — dropping
this branch’s own now-duplicate copy rather than replaying it a
second time. Full test suite re-run clean after each rebase.redesign-real-icons.png
and found nearly every real app showing the fallback circle.
Investigated and fixed — see 2.2.1 and docs/evidence/app-drawer/ README.md’s own investigation table. Re-verified: cargo test/
clippy (4.1-4.3, including the new
catalog::tests::terminal_like_reads_the_terminal_flag_and_the_category),
both nix builds (4.4-4.5) all re-run after this follow-up, not
just before it.5.1 Real-glass operator acceptance, 2026-09-30. Reproduce the exact reported scroll-reversal gesture by real finger on glass and confirm the drawer does not close (the bug-fix commit’s own gate).
5.2 Transfer the unperformed sustained K230_DRAWER_FRAME ms= board measurement, 17.3–34.6 ms estimate comparison and ~20 ms target to the-shell-profiles-reported-interaction-jank task 2.1. This is completed scope transfer, not measured performance.
5.3 Real-glass operator acceptance, 2026-09-30 (current compact keyboard). Real-finger tap on the search field, type on the compact keyboard, and confirm live filtering and correct launch of a filtered result.
5.4 Transfer the contingent damage-limited blitting proposal/decision to the-shell-profiles-reported-interaction-jank task 2.2, preserving docs/design/app-drawer-review.md section 6. No optimization or performance result is claimed.
cargo test --offline --manifest-path nix/rust-shell-client/Cargo.toml, then nix build .#handheld-shell-rust.docs/evidence/app-drawer/ before ticking this task.The updated completed tasks describe actual acceptance, waivers and scope
transfer, not execution of the superseded protocols. See docs/evidence/proposal-closeout/2026-10-01/drawer.md.
Historical checkpoint notes above that say physical gates remain open are
superseded by this record. Quantitative or individually unreported results
are not promoted to physical proof.
Proof: openspec validate the-app-drawer-is-redesigned --strict; committed operator report;
python3 scripts/render_work_board.py --working-tree --output <snapshot.json>.
Grounding: docs/design/app-drawer-review.md §1 (an earlier revision
of this document) traces the reported bug (“swipe down in the app drawer
to scroll back up, it closes the drawer”) to two independent mechanisms
that each decided close-eligibility once, at the start of a touch, and
never revisited it as the gesture actually unfolded. Fixed in
nix/rust-shell-client/src/navigation.rs (Contact::scrolled_away,
gating DrawerNavigation::up’s release-only dismiss check) and
service_ui.rs (drawer_close_candidate_after_scroll, gating the live
“follow the finger” close drag main.rs’s motion handler runs on
every sample). Landed in its own commit, separately from the redesign
this change otherwise covers. Regression tests reproduce the exact
gesture: navigation.rs::scrolling_away_from_the_top_then_reversing_never_closes_within_one_gesture,
main.rs::drawer_live_close_drag_never_engages_after_a_mid_gesture_scroll_reversal.
A downward drag on the app drawer’s grid or its top chrome SHALL close the drawer only when the grid was at rest at its own scroll top — with no fling still decelerating toward it — at the moment the finger touched down. Once a gesture has actually scrolled the grid away from its own top, that same held gesture SHALL NOT close the drawer for the remainder of its duration, even if the grid’s scroll position later returns to (or clamps at) its top before the finger releases. After a fling has fully decelerated to a stop at the top, a new, separate downward drag MAY close the drawer.
Grounding: docs/design/app-drawer-review.md §2.4. Reopens an explicit
prior deferral (the-handheld-presents-a-coherent-shell/design.md
decision 2, shell-ux-critique.md §4) at the coordinator’s direction, on
review of a first redesign attempt that omitted it. Initially implemented with a compact keyboard; superseded by the shared
system-keyboard path and visible caret proven in
docs/evidence/app-drawer/system-keyboard-board/README.md and a plain
case-insensitive substring filter (service_ui::filter_app_indices).
The app drawer SHALL present a tappable search field above its icon grid. Tapping it SHALL raise an on-screen keyboard and filter the grid, live, to applications whose name contains the entered text, matched without regard to letter case. Clearing or leaving the field empty SHALL restore the full, unfiltered grid. Selecting a filtered result SHALL launch or pin the same real application selecting it from the unfiltered grid would have.
Grounding: docs/evidence/shell-features/desktop-launcher/README.md, its
console, PNGs and camera recording establish physical-panel discovery, launch,
refresh and error recovery using injected input. The user separately confirmed finger usability on 2026-09-22; normal source-image reboot persistence is demonstrated by the separate
image-launcher video and console, without restoring home-directory state.
Grid presentation added by this change: docs/design/ app-drawer-review.md §2, nix/rust-shell-client/src/navigation.rs
(COLUMNS = 4, ROW_HEIGHT = 110.0) and render.rs
(paint_drawer_tile: a plain icon and label, no card/plate; a round,
theme-tinted circle-with-initial icon fallback), host-rendered
before/after evidence at docs/evidence/app-drawer/. Physical operator acceptance is recorded in docs/evidence/proposal-closeout/2026-10-01/drawer.md and the
system-keyboard-board operator report. Measurements remain deferred.
The system’s Apps surface SHALL list visible application desktop entries from the user’s XDG data directories and Nix profile data directories, applying user-over-system precedence and desktop visibility rules. Reopening Apps SHALL reflect entries added or removed since the previous open. The surface SHALL provide readable application names and touch-accessible pages when the list exceeds the portrait display. Launching an entry SHALL preserve desktop-entry argument expansion and working-directory semantics. Terminal applications SHALL open in the configured terminal. A launch error SHALL leave a visible explanation and a usable Back control. The application grid SHALL present at least 4 columns of icons at this panel’s width, each icon at least 56 logical pixels square, with a single-line, ellipsized application name below each icon and no surrounding card or plate. An application with no resolvable icon SHALL show a round, theme-coloured fallback bearing its initial letter, rather than leaving the tile blank.
Archived change · Archived
Snapshot 5836ef1d113d · 2026-10-17 08:22 UTC
Closed recordReview the archived record and cited scope
After the-screen-comes-up-under-linux the panel is lit and the kernel console
is on it. A person holding the board can read boot messages and, if they have a
serial cable, type. What they cannot do is touch anything. There is no window,
no keyboard, nothing to press — the screen is an output device and the touch
panel emits events nobody listens to.
That is the gap between a board that displays and a board you can use. Dozer is a Crux application with swappable shells, and nothing can be a shell here until something owns the screen, owns the touch events, and can put a second application on top of the first.
The prerequisite the-screen-comes-up-under-linux is now archived and supplies
the DRM, panel, and touch interfaces this change consumes. The shell remains a
hardware-facing change: first-light, physical touch accuracy, and unattended
boot still require the board and are tracked in this change’s tasks and
evidence.
the-screen-comes-up-under-linux removed the need for a serial cable to
read. This removes it to type.evtest output is not a touch that activates a button. That is a
separate claim and it gets separate evidence.docs/display-environment-options.md
measures each candidate; the chosen stack has a number and the number is part
of what gets proven.Non-goals.
llvmpipe. Software GL would cost
2.4 GiB of Mesa and LLVM to produce the slowest option available. If Pixman
turns out to be too slow, that is a finding to record, not a reason to reach
for llvmpipe inside this change.Needs the physical board. QEMU’s k230 machine models no display pipeline,
so no claim about a compositor on this panel can be proven under emulation. One
part can proceed without hardware: whether the stack cross-compiles at all,
and what it costs, is a build-host claim and is separated into its own task
group so it can be answered while the board is in pieces.
runtime/shell: what owns the screen and the touch panel once the system is
up — the compositor, how it renders without a GPU, how a person types, and
what a touch actually does.None. display/panel and display/touch are introduced by
the-screen-comes-up-under-linux and this change consumes them without
changing their requirements: it needs a framebuffer at 568x1232 and touch
events in panel coordinates, which is exactly what they already promise.
Adds a NixOS module under nix/ for the compositor stack and its session, and
the packages it needs to the system closure. It also carries the small kernel
configuration required by the existing NixOS firewall backend; it does not
change the device tree or display/touch drivers.
Build cost, measured on solomon against the pinned nixpkgs, including the
touch-menu utilities (docs/evidence/shell-build.txt): the final enabled
closure is 1,280,679,016 bytes (1221.0 MiB), a +110.2 MiB / +95-path delta
against the 1109.9 MiB baseline. The complete build sequence took 2705 seconds
(45 minutes) and built about 235 derivations across its resumed stages. The
final menu increment, including htop, jq, gnused, grim, and regenerated
image/configuration paths, added 22 derivations and 8.0 MiB unpacked. These are
build-host measurements; they do not establish runtime performance.
The original candidate comparison remains useful as a historical estimate,
but the measured final closure and build sequence above are the claim for this
change (docs/display-environment-options.md):
| stack | riscv64 derivations to build | to fetch (unpacked) |
|---|---|---|
cage + foot + wvkbd (smoke test) | 68 | 292 MiB |
sway + foot + wvkbd (the shell) | 89 | 875 MiB |
hyprland + foot (rejected) | 184 | 2.2 GiB |
Disabling Xwayland is worth 55 of those derivations on its own and removes GTK 3, CUPS and Avahi from the closure. This change takes that override, which means no X11 application can ever run on this board without revisiting the decision.
No new toolchain. The sway stack builds on the GCC 15.3.0 cross-compiler the closure already uses; Hyprland would have required a second full GCC cross-bootstrap, which is a large part of why it is rejected.
Consumes the interfaces from the-screen-comes-up-under-linux. That change
is archived, but the board-facing dependency remains: without a DRM device that
supports dumb buffers, the compositor has nothing to allocate from, and without
touch events it has nothing to route.
Standalone use means the shell needs no host commands or external keyboard. The board has no battery available for this work, and a power cable is allowed. At the user’s request, a separate USB wall-supply power-on trial is not an acceptance gate. Record automatic startup after a touch-triggered reboot on the available power connection; label USB-connected reboot evidence accurately and do not claim it proves a disconnected power-on test.
See proposal.md — Why. The full comparison, with every measurement and every
source citation, is docs/display-environment-options.md; this document
records only what shapes the approach.
The layer this work lands in is primarily Nix and userspace. The shell does
not change stage 1, the device tree, or the display/touch drivers. It does add
the small kernel configuration needed by the NixOS firewall backend. The clean
seam remains: the-screen-comes-up-under-linux owns
everything down to and including /dev/dri/card0 and /dev/input/event*; this
change owns everything above them. If a problem turns out to need a device tree
property — a swapped touch axis, a plane format — it belongs on the other side
of that line and gets fixed there, not worked around here.
What constrains the approach:
mesa-libgbm, a generic buffer-manager
library linked by wlroots but unused by Pixman’s allocator; that is not a GL
runtime and does not change the CPU/dumb-buffer rendering path.drmGetRenderDeviceNameFromFd() returns NULL
(render/wlr_renderer.c:268).docs/evidence/cross-build.txt: the
existing 1.2 GiB closure took 353 local derivations and 73 minutes, of which
a single extra cross toolchain was the largest cost. Package choice here is a
build-time decision as much as a runtime one.Goals:
Non-Goals (design level, beyond the proposal’s):
Wayland, not X11. The X11 path on a GPU-less board is
xf86-video-modesetting with a shadow framebuffer — it works, and it is
strictly more machinery for strictly less. It also means an X server, an input
driver stack, and a second window-system vocabulary in a repository that has
none. Rejected. Note this also rejects SXMO’s dwm variant by construction.
wlroots with the Pixman renderer, not Mesa’s software GL. Both reach
pixels. Path (b) — llvmpipe via kms_swrast — genuinely works on riscv64 now
(Mesa >= 24.2 forces ORCJIT on architectures LLVM’s MCJIT never supported, and
riscv64’s default gallium driver list includes llvmpipe and softpipe), so this
is a real choice rather than a forced one. It is rejected on cost: mesa for
riscv64 is 2.4 GiB unpacked and brings LLVM 21, to put a JIT and a full GL
implementation between the currently enabled Linux C908 core and 700,000 pixels. Pixman is
a 2D rasteriser with no GL API surface at all, and emersion’s introduction of
it said plainly that it “should be significantly faster than our previous
llvmpipe-based fallback”. We would be paying 2.4 GiB to go slower.
sway, not cage. Cage is cheaper — 68 derivations against 89 — and it was
the initial favourite. It is disqualified by one fact: grep -rn 'layer_shell'
over the cage source tree returns nothing. Its entire source is cage.c output.c seat.c view.c xdg_shell.c xwayland.c. Every Wayland on-screen
keyboard is a wlr-layer-shell client, and a board with no physical keyboard
needs one. Cage survives as the smoke test in task group 2, where “does a
Pixman compositor start on this device” is the only question being asked.
sway, not dwl, labwc, river or Weston. dwl is configured by editing
config.h and recompiling, which under Nix means an overlay per keybinding;
it also measured more expensive than sway (112 against 89). labwc is a
desktop stacking paradigm — title bars and a root menu — on a 568-pixel-wide
screen, and also more expensive. Weston is the one that is genuinely close:
renderer=pixman is documented, drm_fb_create_dumb() is right there in
libweston/backend-drm/fb.c, its GBM code is behind #ifdef BUILD_DRM_GBM,
and kiosk-shell suits a handheld. It loses on packaging, not merit: nixpkgs
builds Weston with RDP, VNC, Vulkan, Lua and Xwayland enabled — 288
derivations, 3.8 GiB — and trimming it means an override that fights the
nixpkgs default at every bump. Weston is the recorded fallback: if sway
fails for a reason that is sway’s fault rather than the hardware’s, a trimmed
Weston is the next thing to try.
sway also because SXMO is sway. Josh named SXMO as the fallback. Its
Wayland variant — swmo — is sway with wvkbd, wofi, wob, foot and the
lisgd gesture daemon on top, and sxmo.org recommends it over the dwm variant.
Choosing sway costs nothing against that fallback and is a prerequisite for it.
What we are declining is SXMO’s packaging, which does not exist in nixpkgs at
all (no sxmo-utils, no module; the two third-party attempts are unmaintained
since 2024 and 2022), and its assumption of a phone — modem, proximity sensor,
a power button that raises the menu — none of which this board has.
Use an i3bar click menu for the few controls the board needs. swaybar
already turns a touchscreen release inside a status block into a JSON click
event, which is the same proven path used to toggle wvkbd. A status_command
can retain a small page state without a new GUI toolkit or a launcher whose
touch behaviour has not been established. Four 128-pixel blocks, leaving room
for swaybar’s text padding, in a 56-pixel
bar give Apps, Windows/Home, Keyboard, and System visible targets. Apps starts
or focuses a readable foot terminal and a htop monitor. Windows pages
through actual sway containers and has Home, which uses the terminal presence
check so closing every terminal does not strand the user. Window paging wraps,
and an empty workspace says so while retaining Home and Back. A system command
is run synchronously after its matching confirmation (never by exec); if
sudo denies it, the menu stays up with a failure page and a path to retry or
return Home.
System changes to a confirmation page before its narrowly-authorized
systemctl reboot or systemctl poweroff, and Cancel returns to the main
page. This is SXMO-inspired interaction, not SXMO packaging.
The installed-application launcher that now supplies the Apps behavior is a separately archived extension of this work. It does not expand this change’s scope into a general desktop environment; this change records the shell surface, input path, session controls, and measured resource cost.
The menu implementation can be exercised with evemu and /dev/uinput, but
that only proves injected input reached swaybar. It does not prove a finger
lands on the expected control through the GT9895 and panel glass; the latter
stays a photographed board claim.
Hyprland is rejected on two independent grounds, either sufficient.
First, it cannot run without GL: CMakeLists.txt:129-130 makes GLES3 a
REQUIRED build dependency, its only renderer is src/render/OpenGL.cpp, and
since 0.41 it uses aquamarine rather than wlroots so there is no
WLR_RENDERER knob to turn. Aquamarine’s DRMDumb.cpp is a cursor-plane
fallback, not a render path — Backend.cpp builds CGBMAllocator as the
primary allocator or logs “Cannot open backend: no allocator available”.
Second, the build: 184 derivations and 2.2 GiB, including Qt 6 (through
hyprland-qtutils, which drags libpq, mariadb-connector-c and unixodbc),
glslang on a board with no shaders, and a full second GCC cross-bootstrap
because nixpkgs builds it with gcc16Stdenv against this closure’s 15.3.0.
It could be made to run on llvmpipe — aquamarine issue #370 describes exactly
that on the display-only qxl driver, complete with a 425 MB log from
uncached EGL retries. That is the best case and it is not good enough.
Disable Xwayland. Worth 55 of wlroots’ 85 derivations on its own, and it removes GTK 3, CUPS, Avahi, at-spi2-core and dconf from the closure. The cost is that no X11 application can run on this board. On a 4.1” touchscreen with no keyboard that is not a cost. Recorded here because it is easy to hit later and hard to diagnose from “the application did not start”.
Set WLR_RENDERER=pixman explicitly even though wlroots would pick it.
render/wlr_renderer.c:268 selects Pixman automatically when the backend’s DRM
fd has no render node, which is this board. Setting it anyway turns a silent
fallback into a stated intention: if someone later adds a GPU driver, the
declaration is visible and deliberate rather than a behaviour that quietly
changed underneath us.
Do not rotate the output. The panel is portrait natively and the controller
reports in the same space, so the correct configuration is transform normal
and nothing else. With Pixman, a non-normal transform is a per-pixel CPU
rotation on every composite. If the axes turn out wrong, fix them in the device
tree (touchscreen-swapped-x-y, touchscreen-inverted-x/-y) — which means
fixing them in the-screen-comes-up-under-linux’s territory — or failing that
with a libinput calibration matrix. Never both: an output transform and a
calibration matrix compose, and a double rotation looks exactly like broken
hardware.
Write map_to_output explicitly rather than trusting the heuristic.
sway auto-maps a built-in touch device to a built-in output
(sway/input/seat.c:723-730), and get_builtin_output_name() at lines 654-668
looks for exactly one output named eDP-*, LVDS-* or DSI-* — which a
MIPI-DSI panel will be. So it will very likely work with no configuration. One
explicit line removes the dependency on that, and it matters because a touch
device that is not mapped to an output gets no transform applied at all,
which is the mechanism behind every “I rotated the screen and touch went 90
degrees off” report.
drm_info
and a modetest capability dump, before a single compositor package is
built. Canaan’s own DRM reference describes DRM_IOCTL_MODE_CREATE_DUMB on
/dev/dri/card0, which is encouraging — but vendor documentation grounds
nothing on this board, as the Wi-Fi radio already demonstrated.AR24, AR12, AR15, RG24, RG16, which includes ARGB8888 and RGB565 but not XR24.
→ Presents as a compositor that starts and then fails to commit a frame.
Mitigation: the same drm_info dump in task group 1 answers it, and the fix
is small once it is not a mystery.ID_PATH does not start with platform-. → Touch works but lands in
the wrong place. Caught by the explicit map_to_output, and visible in
swaymsg -t get_inputs.librsvg
with vendored Rust crates and the GTK 3 tail behind mako. → Mitigation:
the cage smoke test at 68 derivations comes first and answers the risky
question cheaply; and mako and bemenu are separable, worth 19
derivations, if the shell needs to land sooner.system/nixos-config requires. → It does, and knowingly. The measured
delta is committed so the increase is a recorded decision rather than drift.the-screen-comes-up-under-linux is archived. It supplied /dev/dri/card0
with a real-panel mode and touch events with coordinates; the committed
evidence is docs/evidence/drm-info.txt and docs/evidence/touch-evtest.txt.
This change consumes those capabilities but still needs its own compositor and
real-glass interaction evidence.
Group 2 is the only build-host claim here — it can be answered on
solomon with the board in pieces. Everything else is a hardware claim:
QEMU’s k230 machine models no display pipeline, so no compositor running on
this panel can be proven under emulation, and a task in groups 1 or 3-6 that
cites a QEMU run is wrong.
Groups 1 and 2 are independent of each other and both come before group 3. Group 1 is first in order because it is the cheapest way to find out the whole approach is wrong.
The compositor choice rests on dumb buffers existing and the primary plane speaking a format Pixman speaks. Both are currently assumptions. Answer them before building anything.
/dev/dri/renderD* node exists, and the DRM_CAP_DUMB_BUFFER capability. Verify with ./tools/console.py /dev/ttyACM0 --wait=3 "drm_info" and commit the output to docs/evidence/drm-info.txtXR24 (XRGB8888) and AR24 (ARGB8888) are among them. Verify by extending docs/evidence/drm-info.txt with the plane format list and a one-line verdict on whether wlroots’ preferred format is available./tools/console.py /dev/ttyACM0 --wait=3 "modetest -M <driver> -s <connector>:568x1232" plus a photograph of the test pattern, both committedProves group 1 — hardware claim. drm_info and a photographed modetest
pattern, committed under docs/evidence/. If 1.1 shows no dumb buffer support,
stop: the design’s premise is wrong and the fallback is a direct DRM or LVGL
shell, which is a different change.
enableXWayland = false, plus foot, an on-screen keyboard and seatd — behind an option that is off by default, so the existing minimal closure is unaffected until it is switched on. Verify with nix eval .#nixosConfigurations.k230.config.system.build.toplevel.drvPath succeeding with the option off and with it onnix build .#shell-compositor and record the store pathnix build .#nixosConfigurations.k230.config.system.build.toplevel, and commit the wall-clock time, the derivations-built count and the resulting closure size to docs/evidence/shell-build.txt against the 89-derivation / 875 MiB estimate in docs/display-environment-options.mddocs/evidence/shell-build.txt; if the list is empty, say so explicitly rather than leaving the section outhtop, jq, and gnused). Verify with nix build .#nixosConfigurations.k230.config.system.build.toplevel and append the wall-clock time, derivation count, and closure size to docs/evidence/shell-build.txt. This is a build-host claim only; do not run it concurrently with another full closure/image build.Proves group 2 — build-host claim. nix build .#nixosConfigurations.k230.config.system.build.toplevel on solomon, with the
measurement committed. This says nothing whatsoever about the board.
cage is 68 derivations against sway’s 89 and answers the one question that
could invalidate everything. It is a probe, not a destination — it has no
layer-shell and so can never host the keyboard.
cage and foot and start it on the board. Verify with ./tools/console.py /dev/ttyACM0 --wait=3 "cage -- foot" and a photograph of a terminal on the panelWLR_DEBUG-level log to docs/evidence/compositor-first-light.txt, showing the Trying to create drm dumb allocator line and no GLES or GBM errorProves group 3 — hardware claim. A photograph plus
docs/evidence/compositor-first-light.txt. If this fails, the failure is the
most valuable thing this change produces and it gets written down before
anything else is attempted.
WLR_RENDERER=pixman set explicitly. Verify with a photograph of the board booting unattended to a sway session with a terminal after a touch-triggered reboot, with no host commands needed to start the session and no external keyboard. The existing USB power connection is allowed. The user explicitly removed a separate wall-supply power-on test from acceptance; no battery is requiredtransform normal, scale 1, and confirm sway agrees. Verify with ./tools/console.py /dev/ttyACM0 --wait=3 "swaymsg -t get_outputs" committed to docs/evidence/shell-session.txtDSI-1 and whether the GT9895’s ID_PATH starts with platform- — and add an explicit map_to_output regardless. Verify with ./tools/console.py /dev/ttyACM0 --wait=3 "swaymsg -t get_inputs" appended to docs/evidence/shell-session.txt, showing the touch device mapped to the panelProves group 4 — hardware claim. A photograph of an unattended boot into
sway, plus docs/evidence/shell-session.txt.
5.1 Add the on-screen keyboard as a layer-shell client that can be summoned and dismissed by touch. Verify with a photograph of the keyboard over the terminal and a second photograph with it dismissed and the terminal fully visible
5.2 Type a command entirely on the panel and show its output on the panel. Verify with a photograph of the typed command and its result — this task is not complete on a keyboard that appears; it is complete on a command that ran
5.3 Confirm a press lands on the key that was pressed, not a neighbour and not its mirror. Verify by typing a string that distinguishes the four rotations and mirrorings of the layout, photographed, with the string and the reasoning recorded in docs/evidence/shell-session.txt
5.4 If the axes are wrong, fix them in the device tree rather than in the compositor, and record which layer the fix landed in. Verify by stating in docs/evidence/shell-session.txt whether a touchscreen-swapped-x-y/touchscreen-inverted-* property, a libinput calibration matrix, or nothing at all was needed — and confirm that no more than one of them is in force
5.5 Exercise the persistent Apps, Windows/Home, Keyboard, and System touch bar. Verify first with an evemu/uinput event and record it explicitly as injected-input evidence; then photograph or record real glass taps that launch/focus Terminal and Monitor, page to and focus another sway window, recover Terminal with Home after closing it, toggle the keyboard, cancel one system confirmation, and confirm the other. The latter is the hardware claim and is required before this task is checked.
5.6 Run the user-requested original Neofetch through Nix on the board and show it in a panel terminal. Verify with its Nix build/store path, console transcript, and screenshot/video. The final image must initialize its Nix store database automatically; verify nix-store -q --requisites /run/current-system after a fresh boot without a manual database load.
5.7 Ship the portrait Foot, htop and Neofetch defaults in NixOS rather
than restoring home-directory state. Build the system and verify plain
application launches on the board with a fresh home, recording the immutable
config paths and panel screenshots. A preserved private backup is not an
implementation dependency. Evidence: docs/evidence/shell-features/declarative-final/README.md.
5.8 Fix the observed firewall startup failure without disabling the firewall. Verify the current generated IPv4/IPv6 rules against the kernel configuration, build the kernel/system, then capture an active firewall service and installed filter/mangle rules after board boot.
Proves group 5 — hardware claim. Photographs of a command typed on the
panel and its output, plus real-glass touch-bar evidence, committed under
docs/evidence/. Injection evidence is diagnostic and does not substitute for
the photograph or recording.
There is no prior art for Pixman composite throughput on a C908. The number does not gate this change; not having it does.
k230.shell.frameTiming, then record K230_CPU_FRAME_WALL journal lines in docs/evidence/shell-performance.txt. Each successful sample is CLOCK_MONOTONIC wall-clock elapsed time, including scheduler delay, from immediately before wlr_scene_output_build_state() through wlr_output_commit_state() returning: scene build, Pixman submission, and KMS commit submission. It is not process CPU accounting, a vblank, presentation, or physical scanout measurement. Verify by committing the measurement and method to docs/evidence/shell-performance.txt./tools/console.py /dev/ttyACM0 --wait=3 "free -m; ps aux --sort=-rss | head -15" appended to docs/evidence/shell-performance.txtdocs/display-environment-options.md: whether a compositor is viable on this board, or whether a direct DRM/KMS shell with no compositor is now the recommendation. Verify by the document saying one or the other in a sentence, with the measurement citedProves group 6 — hardware claim. docs/evidence/shell-performance.txt,
committed.
UNVERIFIED wording in runtime/shell against the committed photographs, logs and measurements, while retaining the recorded startup provenance and real-glass controls/calibration limitations. Verify with openspec validate the-screen-runs-a-shell-not-a-consoledocs/ path committed. Verify with ./scripts/build_site.py exiting zeroruntime/shell requirement, while retaining the historical candidate estimates for comparison. Verify with openspec validate --allffprobe and review the visible result.2026-09-23 real-touch acceptance: tasks 4.1 and 5.1/5.3/5.4/5.5 use the
physical recordings in docs/evidence/shell-real-touch-keyboard/,
shell-real-touch-apps/, and shell-real-touch-system/, their native/serial
corroboration, and direct operator reports in the adjacent files. The user
confirmed the command output, completion of the keyboard sequence, and
explicitly “home works too it’s all good” after the Home camera limitation
was explained. Accept the reported Home recovery without another retake.
The successful asymmetric string is 1qazoplm (letter o); its first exho
attempt remains documented. No axis correction layer is in force.
Camera limitations remain explicit: a hide transition and exact system
button labels are not independently resolved, and Home is user-confirmed.
The automatically returning shell after touch-triggered reboot satisfies
the revised startup check; no disconnected power-on claim is made. A
deliberate full-panel drag remains unrecorded, so these completed task boxes
do not by themselves ground that separate spec scenario or authorize a
claim that every physical scenario has been filmed.
Defines what owns this board’s screen and touch panel once the system is up: the compositor that draws, how it draws with no GPU driver, how a person types without a host computer or external keyboard, and what a touch actually does.
The compositor SHALL composite in software into DRM dumb buffers. It SHALL NOT require OpenGL, OpenGL ES, Vulkan, a GBM allocator, or a DRM render node, and the system SHALL NOT carry a Mesa GL or Vulkan runtime in order to run it.
Grounding: wlroots-0.20.2/render/wlr_renderer.c:220-228 lists pixman among
the values of WLR_RENDERER, alongside gles2 and vulkan, so the software
renderer is a supported selection rather than a debug path; line 268 selects it
automatically when has_render_node() is false, which is the case for a
display-only KMS driver. The Pixman renderer
advertises WLR_BUFFER_CAP_DATA_PTR and not WLR_BUFFER_CAP_DMABUF
(render/pixman/renderer.c:196-204), so wlr_allocator_autocreate() skips its
GBM branch and reaches the dumb-buffer branch at
render/allocator/allocator.c:140-152, whose only conditions are a DRM fd and
drmIsMaster() on it. include/render/allocator/drm_dumb.h declares
wlr_drm_dumb_allocator_create(int fd) returning buffers with a void *data
the CPU writes into. The trade-offs of every alternative are recorded in
docs/display-environment-options.md. On the board, docs/evidence/drm-info.txt:
canaan-drm exposes a primary node only (no renderD*),
DRM_CAP_DUMB_BUFFER = 1, and modetest scanned out a dumb buffer in
ARGB8888 and in RGB565, photographed. The primary plane has no XRGB8888, so
the compositor must render RGB565 (sway render_bit_depth 6) or ARGB8888;
wlroots’ default of XRGB8888 is refused by output_pick_format()
(types/output/render.c:147-190) with no fallback.
mesa-libgbm library may be present but is unused by the
Pixman/dumb-buffer path, as recorded in docs/evidence/shell-build.txt.Hyprland SHALL NOT be the compositor, and the reason SHALL stay written down so the decision is not re-litigated from the name alone.
Grounding: hyprland-0.56.2/CMakeLists.txt:129-130 reads set(GLES_VERSION "GLES3") then find_package(OpenGL REQUIRED COMPONENTS ${GLES_VERSION}) — a
hard build requirement — and line 529 links OpenGL::EGL OpenGL::GLES3. Its
only renderer is src/render/OpenGL.cpp; Pixman appears in the tree solely as
region arithmetic (pixman_box32 at src/render/OpenGL.cpp:1020). Since 0.41
it does not use wlroots but its own backend, aquamarine, whose
CMakeLists.txt:22 also reads find_package(OpenGL REQUIRED COMPONENTS "GLES3"). There is therefore no WLR_RENDERER=pixman to set. Measured on the
pinned nixpkgs, hyprland + foot adds 184 riscv64 derivations and 2.2 GiB of
substituted paths, including Qt 6 and a second GCC cross-bootstrap
(riscv64-unknown-linux-gnu-gcc-16.2.0); see
docs/display-environment-options.md.
Every package this change adds is compiled for riscv64 without a native binary cache, so the cost of the shell SHALL be measured on the build host and committed, and SHALL be the smallest of the candidates that meets the other requirements here.
Grounding: docs/evidence/shell-build.txt records the completed enabled
build: about 235 derivations across resumed stages and 2705 seconds (45
minutes), with a final 1,280,679,016-byte (1221.0 MiB) closure, +110.2 MiB and
+95 paths over the 1109.9 MiB baseline. The final menu/image increment,
including htop, jq, gnused, and grim, added 22 derivations and 8.0 MiB
unpacked. docs/display-environment-options.md remains the historical
candidate estimate: 68 derivations for the cage smoke test, 89 for sway
with foot and wvkbd, 184 for Hyprland, and 288 for nixpkgs’ default
Weston.
The compositor SHALL be built with Xwayland disabled.
Grounding: measured against the same pin, wlroots needs 85 local
derivations and 500 MiB of fetches by default and 30 derivations and 210 MiB
with enableXWayland = false; Xwayland drags in GTK 3, CUPS, Avahi,
at-spi2-core and dconf. Recorded in docs/display-environment-options.md.
docs/, alongside the numbers for the options that were not chosenGrounding: docs/evidence/shell-real-touch-system/README.md records a
physical touch-triggered reboot, automatic return to the terminal, the serial
boot transcript, and active shell/seatd/firewall after startup. The user
removed a separate wall-supply power-on trial from acceptance. This remains
USB-connected warm-reboot evidence; no disconnected power-on is claimed.
The system SHALL start the compositor without a host computer, external keyboard, login prompt or a display manager, and the compositor SHALL take the panel at its native 568x1232 in portrait, with no rotation and no scaling.
A compositor that starts is not a shell that works. The evidence SHALL be a
photograph of the physical screen together with the compositor’s log, because a
Wayland session can report a successful mode set and present nothing — the same
failure this board already produced once, when the Wi-Fi driver reported
start ap successs! and transmitted nothing.
Grounding: docs/evidence/shell-real-touch-keyboard/README.md combines
real Goodix contacts, physical hidden/shown keyboard frames, native captures,
and the operator’s confirmation of the keyboard sequence and command output.
The successful asymmetric argument is 1qazoplm (letter o). The camera does
not independently resolve the hide transition; that action is accepted on
the direct operator report, not described as filmed.
The shell SHALL present an on-screen keyboard that a person can summon and dismiss by touch, and characters typed on it SHALL reach the focused application.
Grounding for key entry and axis decision:
docs/evidence/shell-real-touch-keyboard/README.md and
docs/evidence/shell-session.txt record the real-touch asymmetric command,
operator-confirmed output, and fresh identity calibration matrix. Source
contains no DT swap/invert correction; the panel uses native portrait and
explicit output mapping. The initial exho typo remains documented. This is
not a calibrated pixel-error or every-tap-perfect claim.
Touches SHALL be routed to the surface drawn at the touched location, in the panel’s own 568x1232 coordinate space, with the axes neither swapped nor mirrored.
Input events with coordinates are not the same claim as touch that works.
display/touch proves the controller reports movement; this proves the shell
acts on it. Where the two disagree the fix SHALL be recorded as a compositor
input mapping or a libinput calibration matrix, and which one it is SHALL be
stated, because the two live in different files and a later kernel change can
invalidate only one of them.
Grounding: docs/evidence/shell-real-touch-apps/README.md records physical
Apps/Terminal/Monitor interaction and the user’s explicit Home recovery
confirmation after the camera limitation was explained.
docs/evidence/shell-real-touch-system/README.md records touch followed by
reboot and automatic return to the shell. Exact confirmation labels and the
cancel action are not legible in the camera view; acceptance combines the
operator’s completed procedure and overall confirmation with those recordings.
Earlier injected menu/state/failure-path evidence remains separately labeled
in docs/evidence/shell-features/ and docs/evidence/shell-virtual-touch.txt.
Do not describe operator-confirmed actions as individually camera-proven.
The shell SHALL keep a persistent touch bar with Apps, Windows/Home, Keyboard, and System controls. Its visible targets SHALL be at least 56 pixels high and the primary controls SHALL each be at least 128 pixels wide on the 568-pixel panel. Apps SHALL start or focus a readable terminal and a system monitor without a physical keyboard. Windows SHALL page through running sway windows, wrap after the last window, and show an explicit no-windows state while keeping Home and Back available. Its Home control SHALL return to a running terminal or start one when it was closed. Keyboard SHALL summon or dismiss the on-screen keyboard. System SHALL offer reboot and power-off only after a second confirmation page that names the action and includes Cancel. A failed or denied system action SHALL return a visible failure state with a route back to System or Home; it SHALL NOT terminate the touch menu.
The session user SHALL have authority only for those two explicit systemctl
operations; no general passwordless command or root shell is part of the
control.
systemctl command fails or is deniedevemu/uinput event activates a menu blockThe compositor and the separately archived installed-application launcher SHALL NOT be treated as a decision about which application shell draws the product experience. They provide a surface, an input path, a way to type, and a small way to launch installed desktop entries; the later application shell remains open.
Grounding: openspec/config.yaml identifies the current Sway handheld goal and
places AtomVM/Dozer integration outside its scope. The archived launcher change
is scoped to desktop-entry discovery and session utilities. docs/findings.md
records the application-framework assessments as still open.
Archived change · Archived
Snapshot 5836ef1d113d · 2026-10-17 08:22 UTC
Closed recordReview the archived record and cited scope
A four-button status row is an entry point, but not a pleasant application launcher on a 568×1232 handheld. Opening an app needs a full portrait surface with enough hierarchy, labels, and spacing to be read and tapped comfortably.
None.
runtime/shell: The cable-free session gains a native portrait Apps surface
for installed desktop applications as well as its built-in terminal and monitor.The change affects the shell Nix module, its bar action path, a small local
Wayland client, touch-menu tests, and the runtime/shell OpenSpec delta. It
adds only the Wayland client libraries and protocol build tools already in the
shell’s dependency family. Package build evidence can be collected on a
laptop; real-glass usability remains coordinator hardware work.
The persistent 56-pixel swaybar is the proven click route for Apps, Windows,
Keyboard, and System. Its prior Apps row made useful actions reachable, but a
fourth 128-pixel block cannot present an attractive handheld launcher. See
proposal.md for the user-facing motivation.
Goals:
Non-Goals:
Use a local Wayland SHM layer-shell client. The client creates an overlay
surface with exclusive zone zero and no extra top margin. Sway already
subtracts the persistent bar’s 56-pixel exclusive area; adding another margin
would expose a second strip of the underlying app, as the first board trial
showed.
It draws a title and four high-contrast portrait cards into one ARGB SHM
buffer and listens for both wl_touch and wl_pointer release events. This
uses wayland-client and protocol XML already available through the pinned
Wayland/wlroots stack. It does not need a widget toolkit, GPU, font catalogue,
or extra daemon. The fixed bitmap labels are deliberately local and
predictable.
Retain swaybar as the entry point. Apps launches the client in the session; Windows, Keyboard, and System retain their current status-command state machine. The surface’s Back card closes it, returning to the bar’s home controls.
Use a narrow action bridge. The client invokes one wrapper-owned helper
with terminal, monitor, or new-terminal. The helper contains the same
known app IDs and Foot profiles as the bar path; it never accepts arbitrary
commands. Terminal and Monitor query Sway then focus-or-start. New terminal
always starts another readable Foot window.
Use GLib for installed applications and Pango/Cairo for text. GDesktopAppInfo applies XDG precedence, Hidden/NoDisplay/TryExec filtering, and parses/launches Exec without shell evaluation. The service exports the shell profile XDG data directories and a Sway desktop identity. Pango/Cairo, already in the closure, renders arbitrary application names. Entries refresh at each Apps open and paginate after the built-ins. Terminal=true is routed through the existing Foot bridge; unsupported launches show an in-surface error.
Deploy via the normal shell system closure. Apps starts the launcher only in the Sway session; closing it or an unavailable client leaves the bar usable. Removing the package/wrapper restores the bar-only Apps path and leaves no state or privilege change.
nix build .#touch-launcher --option max-jobs 2 --option cores 8 after the coordinated
builder slot is idle; inspect nix path-info -Sh .#touch-launcher. This is
a cross-package claim, not hardware proof.python3 tests/test_touch_menu.py, python3 tests/test_desktop_catalog.py,
nix eval --raw .#nixosConfigurations.k230.config.system.build.toplevel.drvPath,
and openspec validate the-shell-launches-apps-without-a-keyboard --strict.
Record their laptop-only result and a labelled layout preview.docs/evidence/shell-features/. Release the board after capture.Fixed baseline 4.1 evidence: docs/evidence/shell-features/portrait-launcher/README.md
and its final camera recording, screenshots, action script and window-tree log.
Input was injected; actual finger accuracy remains the parent shell change’s task.
docs/evidence/shell-features/.Discovery task 4.2 evidence: docs/evidence/shell-features/desktop-launcher/README.md
and its video, screenshots and console. Input was injected on the physical board.
The user separately confirmed launcher finger usability on 2026-09-22; see
docs/evidence/shell-features/desktop-launcher/README.md. Existing video
provenance stays injected. Broader axis/battery/system-control tasks stay open.
Task 4.3: docs/evidence/shell-features/desktop-launcher/README.md links the
source-image build/write/reset evidence, normal system/config paths with no
service drop-ins, and post-reboot launcher video and screenshots. Shell home
state was not restored. The boot is USB-attached, not a battery-only test.
Provides the handheld Sway shell with keyboard-free application discovery and launch.
Grounding: docs/evidence/shell-features/portrait-launcher/README.md records
physical-panel rendering and injected actions. The user separately confirmed launcher finger usability in
docs/evidence/shell-features/desktop-launcher/README.md; the normal source-image reboot and post-boot launcher capture are recorded
in the same evidence directory.
The persistent Apps control SHALL open a native Wayland portrait launcher while Keyboard, Windows/Home, and System remain available through the persistent bar. The launcher SHALL present a visible title and touch-sized, high-contrast Terminal, Monitor, New terminal, and Back targets. Terminal and Monitor SHALL focus their existing window when present or start it when absent. New terminal SHALL start a separate terminal window. Back SHALL close the launcher without requiring a physical keyboard.
Grounding: docs/evidence/shell-features/desktop-launcher/README.md, its
console, PNGs and camera recording establish physical-panel discovery, launch,
refresh and error recovery using injected input. The user separately confirmed finger usability on 2026-09-22; normal source-image reboot persistence is demonstrated by the separate
image-launcher video and console, without restoring home-directory state.
The system’s Apps surface SHALL list visible application desktop entries from the user’s XDG data directories and Nix profile data directories, applying user-over-system precedence and desktop visibility rules. Reopening Apps SHALL reflect entries added or removed since the previous open. The surface SHALL provide readable application names and touch-accessible pages when the list exceeds the portrait display. Launching an entry SHALL preserve desktop-entry argument expansion and working-directory semantics. Terminal applications SHALL open in the configured terminal. A launch error SHALL leave a visible explanation and a usable Back control.
Archived change · Archived
Snapshot 5836ef1d113d · 2026-10-17 08:22 UTC
Closed recordReview the archived record and cited scope
The reason to own this board rather than a headless one is the 4.1” AMOLED on
the front. After the-board-boots-what-we-built it runs our Linux and answers
on a serial cable, and the screen is dark. Everything this project is actually
for — AtomVM with something to show, the Dozer core with a shell — is waiting
on a panel and a working touch surface.
The shipped RT-Smart firmware drives both, so the hardware is known good and
the init sequence is known: it is sitting in LilyGO’s rm69a10.c. What is
missing is the same thing expressed to Linux.
panel-canaan-universal, which takes its init command sequence, timings,
lane count and reset GPIO from the device tree. So this is a new .dtsi
transcribed from the vendor’s working init sequence, not a new driver.goodix.c; this
panel’s controller is the Goodix Berlin generation, supported in mainline
since roughly 6.7. This backports that support onto the 6.6-based tree.start ap successs! and transmitted
nothing. A /dev/fb0 that exists is not a screen that works.Non-goals. The backlight beyond what is needed to see the panel at all. Any GPU or acceleration — the K230’s 2.5D block has no Mesa or Vulkan driver and everything here is software-rendered. Rotation, colour calibration, or power management. Choosing a UI toolkit; that is a later decision and this change deliberately does not constrain it.
display/panel: what is on the screen and how the panel is driven.display/touch: what happens when a person touches it.system/kernel: gains the obligation to carry this board’s panel and touch
support, and to say how it diverges from the upstream Xuantie tree.Adds a device tree source for this board and a kernel patch or overlay
backporting goodix_berlin. Both land in the kernel derivation, so this change
touches how the system is built, not only what it contains.
Carrying a backport means the kernel derivation stops being a pinned upstream revision and becomes a pinned revision plus patches. That is a maintenance cost this change knowingly takes on, and it is the first patch in the tree.
Needs the physical board throughout. Nothing here can be proven under QEMU —
its k230 machine models no display pipeline at all.
See proposal.md — Why. What shapes the approach:
panel-canaan-universal.c in the pinned kernel is fully device-tree driven,
so a new panel is a .dtsi. The reference k230-canmv-v3-lcd.dts proves the
pattern with display-st7701-480x800.dtsi.rm69a10.c is a working init sequence for this exact panel on this
exact board. It is the source of truth; the datasheet is not.docs/rtsmart-boot-log.txt records the vendor bring-up order: power on,
reset via GPIO22 three times, set backlight, rm69a10_init, set PHY
frequency, DSI resolution init, rm69a10_568x1232_init.goodix.c. Mainline gained Berlin support around 6.7; the pin is 6.6-based.Goals:
Non-Goals:
Transcribe the init sequence from rm69a10.c, not from the datasheet.
The vendor code is observed working on this board. A datasheet sequence would
be a second source to debug against, and this project’s standing rule is that
a datasheet grounds nothing — the RTL8189 datasheet described a working radio
whose enable line was never driven.
Backport goodix_berlin rather than bumping the kernel. Moving to a
mainline kernel new enough to include it was considered and rejected: the
pinned Xuantie tree carries the K230 SoC support this board boots on, and
trading a known-good SoC port for a touch driver is the wrong direction. The
cost is the first carried patch in the tree, and a record of it so a later
bump can drop it.
Prove the panel with a photograph. A /dev/fb0 node, a mode set, and a
successful ioctl are all things this hardware can produce with nothing on
the screen. The Wi-Fi radio already demonstrated the pattern: the driver
reported start ap successs!, brought an interface up with an IP, and
transmitted nothing detectable by three separate receivers. A photograph is
the only evidence that cannot be produced by a pipeline that is lying.
Bring up panel and touch as separate task groups. They share only the device tree. Coupling them would mean a touch failure blocks evidence that the screen works, and the screen is the more valuable of the two.
panel-canaan-universal cannot express something the panel needs. →
Then the decision to avoid a C driver is wrong and should be revisited
explicitly rather than worked around in the device tree..dtsi is written, and it
changes a task’s contents rather than the approach.Every group here is a hardware claim. QEMU’s k230 machine models no
display pipeline, so nothing in this change can be proven under emulation.
mpp/kernel/connector/src/rm69a10.c into a reviewable table. Verify by committing it to docs/evidence/rm69a10-init-sequence.md with each entry citing its line in the vendor sourcedocs/rtsmart-boot-log.txt, including the three resets on GPIO22 before init. Verify by extending that document and noting anything the boot log shows that the source does not explaindisplay-rm69a10-568x1232.dtsi for panel-canaan-universal, modelled on display-st7701-480x800.dtsi, carrying the sequence from 1.1. Verify by building the DTB with nix build .#deviceTree and checking it compiles without warnings.dts including that panel, and record every divergence from k230-canmv-v3-lcd.dts. Verify by committing the divergence list to docs/evidence/dts-divergence.md and building the DTBdocs/evidence/panel-probe.txt showing the panel bound with no DSI errorsfbset -i over the serial console, captured into docs/evidence/panel-probe.txtdocs/evidence/ — a framebuffer node is explicitly not sufficient evidence for this taskdocs/evidence/gt9895-touch.md). Verify by booting with compatible = "goodix,gt9916" against a backported goodix_berlin and recording in docs/evidence/touch-probe.txt whether it bindsgt9895_data chip entry to the backported driver or port LilyGO’s RT-Smart gt9895.c. Neither was needed. The backported goodix_berlin drives the GT9895 with the existing gt9916 chip data once the device tree declares the interrupt correctly: IRQ_TYPE_EDGE_FALLING yields 0 interrupts, IRQ_TYPE_LEVEL_LOW yields 2173 in a 45 s capture, with multitouch events on /dev/input/event0. Both branches of this task assumed the driver could not drive the part; it can. See docs/evidence/touch-reports.md.
- REOPENED. Closed earlier as “neither branch needed, the Berlin
backport works”. It binds, but two evtest runs with a finger on
the panel produced zero events and /proc/interrupts shows only 4
interrupts since boot on the goodix-berlin line. Binding is not
working. See docs/evidence/touch-probe.txt. Verify with nix build .#packages.x86_64-linux.xuantie-kernel and by recording the choice and its reason in docs/evidence/kernel-patches.md
- Resolved to NEITHER branch. The GT9895 answers the Berlin protocol,
so the existing v6.12 backport binds it through the
"goodix,gt9895", "goodix,gt9916" fallback and no driver change is
needed. The first branch was not available in any case: the driver
has no chip table to add an entry to. Recorded in kernel-patches.md.docs/evidence/touch-probe.txtevtest session committed to docs/evidence/touch-evtest.txt, showing a drag rather than a single tap, and confirm the axes are neither swapped nor mirrored. Drag: continuous slot-0 trajectory spanning X 86..728 and Y 765..1765 (docs/evidence/touch-reports.md). Orientation: a drag cannot establish it, so two taps on a drawn target at opposite corners were used, with predictions recorded before reading the result — observed (250,208) and (850,2130) against (216,234) and (807,2166) predicted, matching the unmirrored unswapped mapping and excluding swap, X-mirror and Y-mirror.UNVERIFIED markers in display/panel and display/touch against the committed photograph and evtest session, or restate what remains unproven. Verify with openspec validate the-screen-comes-up-under-linux. display/panel: resolved against the committed photographs; what remains unproven is restated precisely — a uniform whole-frame vertical shift of ~2.8 panel rows, measured in real panel rows after rectification, mechanism not established. display/touch: resolved — reporting and axis orientation both grounded, with the wider-than-declared X range recorded as a caveat.system/kernel requirement so a later kernel bump can tell what is still needed. Verify with openspec validate --allDefines what appears on this board’s AMOLED and how the panel is driven under Linux.
The RM69A10 SHALL be driven through the kernel’s device-tree-configured generic Canaan panel support. This project SHALL NOT add a panel driver in C for it.
Grounding: drivers/gpu/drm/panel/panel-canaan-universal.c in the pinned
Xuantie kernel is 395 lines and reads its init command sequence
(struct panel_cmd_seq *init_seq_v1), timings (struct videomode vm), reset
and power GPIOs, and DSI lane count from the device tree. The reference
k230-canmv-v3-lcd.dts uses it via display-st7701-480x800.dtsi for a
different panel.
The init sequence SHALL be transcribed from the vendor’s working implementation rather than derived from the panel datasheet.
Grounding: LilyGO’s mpp/kernel/connector/src/rm69a10.c drives this exact
panel on this exact board; docs/rtsmart-boot-log.txt records it running —
rm69a10_init, rm69a10_568x1232_init, rm69a10_set_phy_freq. The panel
reset is GPIO22.
Grounded on hardware by photographs in docs/evidence/panel-photos/.
The panel was driven to three known states from a shell on the board —
/dev/urandom (speckled bright field), /dev/zero (dark), and 0xFF
bytes (bright) — and photographed each time. Three states rather than one
deliberately: a single bright frame could be a reflection and a single
dark frame is what a dead panel looks like, so the change is the
evidence. A fourth photograph shows the kernel console rendering on the
panel at 71x77 characters. See docs/evidence/panel-lit.md.
What is NOT yet grounded: the image still moves slightly. The 25% DSI
burst headroom fix referred to here was confirmed on hardware and it
blanks the panel outright; it was reverted in a96ca99. See
docs/evidence/dsi-burst-headroom.md.
On the corrected image, measured over 30 s with the webcam exposure
locked and the oblique view rectified by a four-fiducial homography, so
the numbers are in real panel rows: brightness is now flat (95%..101% of
mean, against 19 dips with the worst at 53% before), and the residual is
a uniform whole-frame vertical shift of about 2.8 rows RMS out of
1232. Near and far halves of the panel move identically — std 2.76
against 2.76, correlation 0.959 — so there is no accumulation down the
frame and no tearing. Mechanism is not established; the untested
hypothesis is that 35 00 SET_TEAR_ON is issued but nothing consumes
TE. See docs/evidence/flicker-after-headroom-revert.md.
The system SHALL present the panel as a working framebuffer at 568x1232, and what is written to that framebuffer SHALL appear on the screen.
A framebuffer device existing is not evidence. This SHALL be grounded by a
photograph of the physical screen, because a pipeline that reports success and
shows nothing is a failure mode this hardware has already produced once — the
Wi-Fi driver reported start ap successs! while transmitting nothing.
Defines what the board does when a person touches the screen.
The GT9895 controller SHALL be probed and SHALL report touches as standard
Linux input events, over the digitizer’s native 1024x2400 range declared via
touchscreen-size-x / touchscreen-size-y, mapping monotonically onto the
panel with the axes neither swapped nor mirrored, so that a consumer scaling
by 568/1024 and 1232/2400 lands a touch where it is seen.
Why not report in the panel’s own 568x1232 space, which is what a reader
would expect: the driver cannot. goodix_berlin_core.c reports through
touchscreen_report_pos(), which applies the swap and invert properties and
does not scale; touchscreen-size-x/y only declare the advertised
maximum, and the controller’s raw values pass through unchanged. Pre-scaling
in the kernel would mean patching the backport further and discarding
digitizer resolution. Reporting the native grid and letting the consumer map
it to the display is the ordinary Linux arrangement.
Grounding for the hardware: the schematic gives the controller as a GT9895 on I2C, with reset on GPIO24, SCL on GPIO36, SDA on GPIO37 and interrupt on GPIO23. The shipped RT-Smart firmware drives it.
evtest session showing coordinates that track a deliberate movement, not only that a device node existsThe GT9895 is not supported by the pinned kernel and its support SHALL be carried as an explicit patch, recorded with what was backported and from where, so the cost of the pin is visible when the kernel is next moved.
Grounding: the pinned Xuantie kernel carries drivers/input/touchscreen/goodix.c,
which serves the older GT9xx generation, and no goodix_berlin source. But
the gap is larger than “backport it”: goodix_berlin landed in v6.9,
not 6.7, and mainline has never supported the GT9895 at any version. At
v6.18 the I2C driver matches only goodix,gt9916 and the binding
enumerates gt9897 and gt9916. See docs/evidence/gt9895-touch.md.
What the project HAS is LilyGO’s RT-Smart gt9895.c (219 lines): not a
Linux driver, but a working register-level description of this part on this
board.
The route SHALL therefore be chosen by experiment rather than asserted. The
goodix,gt9916 compatible is a one-word change and the Berlin generation
shares a programming model, so whether the existing driver drives this part
is cheap to discover once the board boots — and the answer decides between
teaching the mainline driver the GT9895 and porting the vendor one.
The kernel SHALL be built from a pinned revision of the Xuantie tree used by Canaan’s Linux SDK, and every patch this project carries on top SHALL be recorded with what it does and why it is needed.
Grounding: k230_canmv_v3_defconfig in kendryte/k230_linux_sdk builds
ruyisdk/linux-xuantie-kernel at 7d4e1f444f461dbe3833bd99a4640e7b6c2cd529
with the k230 defconfig.
The kernel SHALL carry support for this board’s panel and touch controller. Panel support is configuration — a device tree describing the RM69A10 to the generic Canaan panel support already in the tree. Touch support is a patch, because the pinned tree predates GT9895 support.
Where this project’s device tree diverges from the k230-canmv-v3 reference,
the divergence SHALL be recorded. The reference describes a different display
— an ST7701 at 480x800 — so the divergence is expected and is the point.
Archived change · Archived
Snapshot 5836ef1d113d · 2026-10-17 08:22 UTC
Closed record(parent 2.3, verbatim) Run the capture tool on the reserved board across a
Withdrawn by the operator, 2026-10-12 (after being offered this change as the next to land): “can we just close it or at least dont give me a before this is all fine i dont want to spend time on it”. None of the measurements below was performed for this change, and none is claimed. The tasks stay unticked. No requirement from this change enters openspec/specs/; it was archived with --skip-specs. The closest existing board figures are the parent’s warm apply trials in docs/evidence/theme-picker/board-session-2026-10-12b/README.md (tap-up to shown frame 27.5-42.2 ms, injected taps). They were not produced by tools/analyze-theme-swap-jank.py and do not stand in for tasks 1.1-2.2.
the-shell-swaps-themes-without-a-python-stall built the persistent theme
helper, prepare-ahead, optimistic apply, tap-to-apply, finger tracking and the
runtime trace. Four of its measurement tasks have no board result: the
before/after jank capture (parent 2.3), the tap-to-visible re-run against the
~100 ms target (parent 3.4, deferred by the user), and the compositor-stage
profile and flamegraph (parents 15.2 and 15.3). The operator authorized
splitting them out on 2026-10-12 so the parent can close its remaining
motion, cost-attribution and finger-acceptance work. This change preserves
those four tasks unchanged. It records no result.
tools/theme-swap-jank.py
captures for a dark, a light and a community theme on the reserved board.tools/analyze-theme-swap-jank.py and report it against the ~100 ms target.docs/evidence/theme-picker/cpu-profile/README.md)
as a complete compositor profile.None.
runtime/shell-themes: board measurements of swap latency and runtime CPU
cost stay pending until this change records them.Evidence goes under docs/evidence/omarchy-themes/theme-swap-jank/ and
docs/evidence/theme-picker/. No source change is planned unless a
measurement justifies one, and that would be its own change.
The parent change landed its tools: tools/theme-swap-jank.py,
tools/analyze-theme-swap-jank.py, tools/theme-picker-profile.py, the
default-off runtime trace (parent 15.1) and the runtime-perf package. A
partial physical CPU profile exists. In it, 648 of 697 samples have unknown
callers, and compositor stage spans and scheduler correlation are missing.
The user deferred the tap-to-visible re-run. This change keeps those
obligations visible without holding the parent open.
Goals: run the four carried measurements on the reserved board and commit reviewed reports with exact commands, runtime identities, observer cost and coverage gaps. Non-goals: changing picker behavior, or claiming a target was met from host, QEMU or injected-only evidence.
theme-helper.service. If no such installed system can be restored safely,
record that gate rather than substituting a QEMU baseline.Observer cost can distort small timings, so the tracing-off and tracing-on runs are paired. The board has a single operator. Every run takes the board lock and restores the selected generation.
Withdrawn by the operator, 2026-10-12 (after being offered this change as the next to land): “can we just close it or at least dont give me a before this is all fine i dont want to spend time on it”. None of the measurements below was performed for this change, and none is claimed. The tasks stay unticked. No requirement from this change enters openspec/specs/; it was archived with --skip-specs. The closest existing board figures are the parent’s warm apply trials in docs/evidence/theme-picker/board-session-2026-10-12b/README.md (tap-up to shown frame 27.5-42.2 ms, injected taps). They were not produced by tools/analyze-theme-swap-jank.py and do not stand in for tasks 1.1-2.2.
theme-helper.service lands on an installed system. Record
docs/evidence/omarchy-themes/theme-swap-jank/README.md with the exact
journalctl/board commands and both reports. Needs the reserved
board; not run by this change.tools/analyze-theme-swap-jank.py’s tap-to-visible metric
against the board once 3.1b/3.2/3.3 land, and report against the ~100 ms
target. Needs the reserved board; 3.1b/3.2/3.3 now have source/package
proof. The named measurement remains unperformed and was deferred by the user.openspec validate the-theme-swap-is-profiled-on-the-board --strict,
commit the reviewed reports, push and inspect the matching CI/Pages run.
Archive only when every measurement above, or its documented unsupported
gate, is committed.The shell theme system’s latency and CPU-cost claims SHALL rest on reviewed measurements from the installed board. Each report SHALL name the runtime identities, the exact commands, the observer cost and the coverage gaps. Tap-to-visible latency SHALL be reported against the ~100 ms target. A miss SHALL remain a miss. Elapsed trace spans SHALL NOT be presented as sampled CPU cost. Host, QEMU and injected-only results SHALL NOT be presented as physical latency.
Archived change · Archived
Snapshot 5836ef1d113d · 2026-10-17 08:22 UTC
Closed recordClosed with every task complete. Installed as system 298a2bf6 (Rust hl4bca4g); operator accepted the visible apply (28-42 ms tap-to-shown) and real-finger picker motion on both rows. The helper's durable activation (149-179 ms) is recorded, not claimed under 150 ms.
Choosing a theme freezes the handheld for 2.8-3.5 s on the board
(docs/evidence/omarchy-themes/background-decode-cache-qemu/README.md),
during which touch and animation stall and the person sees no feedback
until the swap either completes or is rejected. About 1.2 s of that is paid
twice per Apply (preview then activate), and it is pure Python
interpreter start-up and import cost, not theme work: a bare k230-theme --help takes 1259 ms against 71 ms for runuser alone, and
PYTHONPROFILEIMPORTTIME attributes most of that to importing
theme_activate/dataclasses/inspect. The user’s stated target is a
swap visible within about one frame (roughly 100 ms) of the Apply tap, with
touch and animation never stalling.
Tune picker touch motion against an explicit interaction contract: direct tracking during contact, continuous release/settling velocity, actual elapsed time and immediate interruption. Omarchy’s current picker supplies discrete geometry rather than touch momentum; Apple’s Motion HIG informs behavior, not invented Apple numeric constants. Keep profiling and finger acceptance separate (task group 18).
Add a persistent theme-helper.service (tools/theme_helperd.py) that
imports tools/theme_catalog.py’s dependency chain once and serves every
later list/preview/activate request over a private Unix socket by
calling that same module’s build_parser()/handle() — the identical
code a fresh CLI invocation already ran, reviewed and evidenced, so this
changes when the import cost is paid, never the two-phase
prepare/commit/rollback protocol itself.
Replace k230-theme’s wrapped entry point with tools/theme_client.py,
an argv-compatible front end that talks to that socket without importing
theme_catalog (and so not its own heavy dependents) unless it actually
falls back — board evidence blamed that import chain, not bare
interpreter start-up, for most of the 1.2 s, so a client that eagerly
imported it regardless of the daemon would not have removed the cost it
exists to remove.
The client falls back to the unmodified, pre-existing in-process path (never a second subprocess) whenever the daemon socket is missing, refused, or slow to answer, so a board that has not yet picked this up, or whose daemon crashed and is mid-restart, still switches themes exactly as it does today — only without the speed-up.
Add tools/theme-swap-jank.py (a root, board-side capture tool) and
tools/analyze-theme-swap-jank.py (a host-side report) so tap-to-visible
latency and per-frame gaps become a measured, reproducible number instead
of a felt impression, for this change and for the remaining work it does
not do (below).
Removing the interpreter-start-up tax was the first, cleanly separable, host-and-QEMU-provable piece of the instant-swap target. Three more pieces have since landed in this same change:
BackgroundCache (background_decode.rs) is now a small
bounded LRU rather than a single slot, so browsing a second candidate no
longer evicts a first one’s decode before its own commit lands. The
compositor (nix/card-shell/appearance.c/adapter.c) gained a matching
advisory prepare hook that pre-builds the deck’s gradient
(card_brush_scene) for the candidate generation, adopted at commit
instead of repainted — with the same “missing/stale falls back to the
old inline path, never breaks correctness” posture background.cache
itself already had.theme_ui.rs’s
ThemeView::poll_prepare_ahead, wired from main.rs’s existing per-tick
carousel-settle loop, warms a theme once it has been the carousel’s
centred item, at rest, for a short debounce — reusing the existing
preview action/reply (already calling prepare_only()) with no new
protocol, and never surfacing that reply to the chooser’s own navigation
state.keyboard_appearance.sync_and_restart (the wvkbd restart) now runs on
a background thread from theme_catalog.py’s activate handling, so
theme-helper.service’s reply to the chooser no longer waits on it.defer_app_sync=True after the existing
two-phase commit and preference publication. Its app_appearance result is
{"state": "deferred"}; a non-daemon thread performs the existing app adapter
call, including its shared GTK keyfile, with the same active-generation guard.
Direct transaction callers retain the synchronous result. The helper can
reply before this update finishes; CLI fallback waits at interpreter exit.theme_transaction.activate_generation() now remembers, per
receiver, which generation it last successfully prepared, and skips
sending a second prepare to a receiver already holding the exact
generation being committed — retrying with a real prepare, transparently,
if a stale assumption turns out wrong, so correctness never depends on
the memory being right.On the two-phase transaction’s acknowledgement contract specifically:
no requirement or code path in this change ever alters what a receiver’s
own prepare/commit/rollback exchange requires to succeed, or the
“ack only after a real, flushed frame” rule each receiver’s own handling
already applied before this change. Optimistic Apply adds a rendering side
effect alongside that protocol — gated strictly on a receiver’s own,
already-prepared state, never substituting for or shortening the real
exchange — so every activation still goes through the exact same
prepare/commit/rollback acknowledgement sequence as before; only when the
chooser’s own display reflects a generation the receiver already holds
prepared has changed, not when that generation becomes durably active.
Left open, and not claimed complete here:
--rust-socket/--deck-socket fanout into
nix/shell.nix’s theme-helper.service — that remains whatever other,
separate work is landing it (see impl/card-appearance-endpoint in this
repository’s own worktree list). Until that fanout is wired, the
compositor side of this requirement is present and tested in isolation
but has nothing live to receive it from in production.docs/evidence/omarchy-themes/theme-swap-jank/).Task 3.3b now has a bounded implementation within this change. The buffer-swap, prepare-ahead and deferred-update pieces still do not establish the board’s own latency number.
runtime/shell-themes: adds a swap-latency requirement (this capability
itself has not yet been archived from the-shell-loads-omarchy-themes,
so the delta here is ADDED, not MODIFIED, per
.skills/k230-spec-change/SKILL.md’s archive-time check).tools/theme_catalog.py (refactored, behavior-preserving split into
build_parser()/handle()), two new tools
(tools/theme_helperd.py/tools/theme_client.py), one new systemd unit
(nix/shell.nix’s theme-helper.service), and
nix/handheld-theme-command.nix’s wrapper target. Host-testable end to
end (tests/test_theme_helper_daemon.py, python3 -X importtime proof
that the fast path avoids the heavy import chain). The absolute board
number (this change’s actual contribution to the 2.8-3.5 s budget) needs
the reserved board; QEMU-under-qemu-riscv64-static and host timings in
this change’s evidence are directional, not the K230’s real number, because
neither reproduces the K230’s in-order core.
The operator reports exaggerated and delayed movement while dragging either row. The current 49/43-pixel collapsed-slice pitch is not the visible focused card’s travel, and per-motion synchronous redraws can service stale positions. Correct the touch-to-rendered-geometry mapping, release velocity after a hold, and touch-event redraw scheduling. Keep tap-to-apply and bounded caches intact; this supplements, rather than closes, the broader profiling work in group 13.
Userspace: tools/ (Python theme coordinator), nix/shell.nix (systemd),
and the existing Rust/C picker work described below. Task 3.3b adds Rust
reply-parser and chooser-status compatibility for deferred app updates.
No kernel, device-tree or stage-1 changes.
tools/theme_catalog.py’s CLI already had exactly the logic a persistent
helper needs to reuse: build_parser() (extracted from main(), no
behavior change) and handle(args) -> (result, exit_code) (also extracted,
same). tools/theme_helperd.py binds a private Unix socket
(/run/shell/theme-helper.sock, mode 0600, directory 0700, SO_PEERCRED
uid check — the same posture as the existing appearance sockets) and, per
request, reconstructs an argv (its own fixed startup flags plus the
request’s action-specific bits) and calls that exact parser/handler. This
means the daemon’s behavior for any single request is provably identical to
running theme_catalog.py fresh with the same flags: there is no second,
hand-rolled protocol for preview/activate semantics to drift from the
one already reviewed and evidenced in tests/test_theme_catalog.py.
tools/theme_client.py is the only piece with a real design decision:
whether to import theme_catalog up front, for the sake of one shared
parser. Doing so would have re-imported theme_activate, which
board evidence already named as most of the cost this whole change exists
to remove. Instead theme_client.py carries a second, deliberately
minimal argparse parser (build_light_parser()) whose only job is to
recognise the request shape (action, id, --background,
--expected-generation) well enough to build a socket request; any flag it
does not confidently recognise, any parse failure, or a missing/refused/slow
socket sends the call to fallback(), which imports theme_catalog and
runs the exact original path. The two parsers can disagree at the margins
(e.g. the light parser does not itself enforce --expected-generation
being required) without being unsafe, because disagreement only ever
degrades to a slower or more verbosely-erroring identical answer, never a
different acceptance decision — the daemon’s copy of theme_catalog’s
real parser is what actually validates and acts on every request, whichever
path reached it.
Board evidence after task 6.3’s skip-redundant-prepare fix still showed
397 ms from Apply tap to the Rust shell’s own commit-accepted marker —
short of the user’s original ~100 ms target. The remaining cost lives
inside activate_generation()’s own durable work (the atomic pointer
swap, missing-public-link creation, fsync, the wallpaper preference
commit, and the then-synchronous app-sync round trip), none of which could be skipped or
reordered without risking exactly the correctness this protocol exists
for. Rather than continue trimming that durable path, the user approved
showing the new appearance immediately when it is already safe to do so.
Why gating on “already prepared” is sufficient for correctness. A
receiver only ever holds a prepared candidate after successfully
validating it byte-for-byte against the same load()/load_snapshot()
checks a real prepare exchange already runs (bounds, symlink rejection,
generation-identity match, palette/background integrity). Rendering that
already-validated candidate early therefore risks nothing a real prepare
ack would not already have accepted — there is no new, less-trusted data
path. What optimism cannot know in advance is whether the durable commit
will actually land (a second receiver’s commit or preference publication
can still fail); that is why the optimistic render never touches a
receiver’s own prepared/active bookkeeping or the wire acknowledgement
contract at all (see nix/rust-shell-client/src/main.rs’s
show_theme_optimistically and nix/card-shell/appearance.c’s new show
phase, both pure rendering side effects). The real commit/rollback
event — unmodified, still gated on a real flushed frame the same as
before this task — is what settles the receiver’s actual state
authoritatively; a failed durable commit’s own existing rollback handling
is what makes the screen correct again, not new code this task adds.
Why the client-side check, not a server-side flag. should_apply_ optimistically/optimistic_apply_due (main.rs) are pure functions
comparing the just-submitted Activate request’s own expected_generation
against the local receiver’s own prepared snapshot — no round trip,
no new IPC for the primary (Rust-surface) case, since the chooser and that
receiver are the same process. This is why the target generation must
already be prepared in this same process: nothing here can safely infer
that a remote receiver (the compositor) is also warm, which is exactly why
the compositor side is deliberately advisory/best-effort (see below)
rather than a precondition this feature waits on.
The compositor’s show phase. A new, additive protocol-1 phase in
nix/card-shell/appearance.c’s request(): renders service.candidate
immediately when it is already prepared and matches the requested
id/path, exactly like the existing commit branch’s own render call, but
never touches service.prepared/service.candidate_path/service. current — so a subsequent real commit or rollback for the same
candidate behaves identically to a world where show was never sent.
Sent best-effort, fire-and-forget, from the Rust chooser directly to the
compositor’s own socket (K230_CARD_APPEARANCE_SOCKET, defaulting to
nix/shell.nix’s existing SWAY_K230_CARD_APPEARANCE_SOCKET production
path) with a short write deadline and no reply read; any failure (socket
missing, refused, a rejected mismatch) is silently ignored. This channel
is presently reachable only once the two-phase transaction’s own
--rust-socket/--deck-socket fanout is wired into theme-helper.service
(tracked separately, not by this task); until then it is dormant, correct,
and tested in isolation, not a regression risk.
Rejected: relaxing the wire acknowledgement contract itself (e.g.
having a receiver ack prepare early, or ack commit before its own
frame is flushed). Rejected because that contract is what task 1’s own
instrumentation and every existing transaction test assume; loosening it
would have widened this task far past “show something already known-good
early” into “change what every receiver promises,” for a benefit this
narrower design already captures.
Rejected: an optimistic-shown flag inside ThemeView/the durable
transaction, coordinated across processes. Would need new state
(un)winding on every possible interleaving (rapid double Apply, a
receiver restart mid-flight, a stale prepared-state assumption already
handled defensively in task 6.3). The chosen design needs none of that:
the optimistic render is stateless with respect to the durable
transaction (it reads prepared, renders, and is done), so there is
nothing to reconcile if the two ever disagree — the real commit/rollback
event, unaware optimism ever ran, always wins.
Keep activate_generation() synchronous by default so its direct callers keep
applied, superseded and failed outcomes. The catalogue opts into
defer_app_sync=True, receiving {"state": "deferred"} only after the original
receiver acknowledgements, pointer publication, preference commit and lock
release. Dispatch failure returns a separate app failure, never a shell rollback.
A named non-daemon thread invokes the same adapter once. It re-acquires the
activation lock and verifies the expected generation, so a delayed old update
cannot replace a newer theme’s app configuration. Its completion state and
exception type go to the existing THEME_TIMING app_deferred syslog channel,
without polluting the CLI JSON streams. The adapter writes Foot configurations
and the shared GTK keyfile; this does not add OSC broadcasts to arbitrary PTYs.
The existing terminal follower remains separate. A direct CLI/fallback process
waits for this thread at interpreter exit, as it already does for keyboard sync.
Rejected: changing every transaction caller to an asynchronous result, or
passing a no-op adapter and reporting applied before any app update. The
explicit opt-in preserves the existing synchronous contract and truthful result.
Host tests block the adapter behind an event while the real helper socket
answers activation and a following list request. Separate tests cover eventual
Foot configs, stale-update refusal, adapter failure without shell rollback, and
no dispatch after failed prepare, commit or preference publication. Physical
latency and current-board installation remain separate gates.
k230-theme as a long-running client that keeps a persistent
connection open. The chooser already treats each preview/activate
as a discrete, synchronous call with its own timeout and error handling
(tools/theme_transaction.py); keeping a stateful connection open across
taps would have added reconnect/staleness handling for no benefit a
request-per-connection socket does not already give.discover()’s theme-source walk into a file-watch cache instead
of a daemon. Would only address the discovery/list cost, not the
import cost itself (which dominates per the board’s own
PYTHONPROFILEIMPORTTIME breakdown), and adds a staleness class (a
theme added on disk after the cache was built) this change’s approach
does not have, since the daemon simply calls the unchanged, always-fresh
discover() per request.theme_activate.py’s own imports (e.g. defer dataclasses).
A real, smaller, complementary win left as a follow-up; it reduces the
daemon’s own one-time start-up cost, not the per-call cost this change
targets, since the daemon already pays that import cost exactly once.tests/test_theme_helper_daemon.py proves: byte-identical list/preview
output through the daemon versus the direct path; a real preview+
activate reaching theme_transaction.activate_generation’s actual
prepare/commit exchange (not a stub) with the daemon in the loop; a
malformed request never wedging the daemon for the next real one; the
client falling back correctly when no daemon is listening; and, via a real
subprocess with python3 -X importtime, that theme_catalog/
theme_activate/theme_transaction/theme_preferences/
keyboard_appearance are never imported by the client process on the
daemon-reachable path. nix build .#handheld-theme-command builds the
real riscv64 package; running its k230-theme-helperd/k230-theme under
qemu-riscv64-static on this host measured 5 sequential list calls at
1.148 s/call with no daemon versus 0.785 s/call with one running (about a
32% reduction) — directional only, since qemu-user translation overhead,
not the K230’s in-order core, dominates this host’s absolute numbers.
The user reports slow theme-picker swipes and apparently repeated loading on
source 926c7a61. This report is not a measured diagnosis. Source review
finds that the merged one-page picker requests both thumbnail variants for
up to 17 themes and 17 backgrounds, while the shared FIFO cache holds only
36 entries. That bound was justified for one carousel, before both moved to
the same page. With 17 themes and just two backgrounds, stationary demand
already exceeds capacity. Eviction followed by unconditional requests can
repeat disk loading/hashing or decoding without any content change.
Keep the bounded cache; derive one working set for both carousels from viewport-intersecting slices, with centered-first scheduling and controlled admission. Use the same set for requests and pending-work decisions, and protect its resident entries from obsolete in-flight replies. Retain the existing 36-entry bound and add an explicit 24 MiB resident-pixel bound, rather than making the cache arbitrarily large. This bounds ready thumbnail surfaces, not total process RSS; the existing bounded worker queues and decode cache remain separate. Offscreen layout and hit-testing remain unchanged. Also defer the optional, synchronous candidate-overlay pre-render until neither carousel is dragging, coasting, or settling. This changes speculative work scheduling, not live rendering or the durable appearance protocol.
A host regression must begin with a two-carousel catalog whose old request set exceeded 36 entries, then prove the new admitted set warms and reaches quiescence (no continual requeues/evictions), stays bounded while moving, and retains center priority. A motion-gate test must cover both carousels and show pre-render becomes eligible again at rest. Physical responsiveness is still UNVERIFIED: after the panel trial, compare cold/warm swipes, idle loading activity, frame gaps and process CPU on the exact installed build.
The second picker trial preserved the active generation but native capture
showed a permanent Loading backgrounds row; all four injected background
drags reached Rust yet produced no commits. Existing selected() compares
only the active report’s source pathname with current catalog paths. A Rust
thumbnail-tool rebuild also rebuilds the bundled-theme derivation, changing
its store path even when theme files are identical. A missing active catalog
ID makes the chooser select index zero without requesting active backgrounds.
This precedes the thumbnail working-set change; that rebuild exposes it.
Keep exact-path matching first. For an unmatched source, recognize only a
unique built-in entry with the same bundled /share/omarchy/themes/NAME
location beneath a Nix store object and the exact source-content digest in
the active report. Do not match user themes by display name, guess between
multiple entries, or write the active pointer. Missing/changed content remains
unmatched. Host fixtures must prove relocation, exact-path priority, and
rejection of changed content, another origin, malformed identity and ambiguity.
A physical repeat must show the actual background row and unchanged durable
generation before using its swipe/memory measurements as comparable evidence.
The paired browsing observation proved that speculative overlay completions during held touch fell from five to zero, but did not prove smoother warm browsing: warm commit-gap median was 125 ms before and 132 ms after, and maxima were 258/285 ms. Both idle windows were quiet. The second run had no resolved background row, so its lower final RSS and reopening cost cannot establish an equal-content win. Task 12.2’s relocation repair must first restore that row. Task 11.3 stays open; these observations are neither physical-finger acceptance nor a cold cache comparison.
Two remaining costs need separate attribution. theme_dirty() invalidates
RendererCache’s full cached scene whenever carousel position changes, so
live movement rebuilds the panel, including unchanged content. Meanwhile,
poll_prepare_ahead() can drain queued neighbor requests when centered is
None: movement suppresses dwell selection but not all speculative request
admission. Helper cgroup CPU overlapped several new warm swipe windows at
roughly 33–39%; a preparation included about 2.8 seconds of wallpaper-cache
work and 1.5 seconds of template rendering. These facts identify work to
measure, not proof that either cost alone explains each frame gap.
Add bounded, opt-in profiling that distinguishes the Rust main thread from thumbnail workers, helper subprocesses from the daemon, and CPU time from elapsed waiting. Record live rebuild count/time, thumbnail request/completion and hash/read/decode phases, appearance-prepare handling, speculative submission/completion, and overlay pre-render separately. Use monotonic phase markers and aggregate counters or bounded buffers; avoid per-pixel logging or unbounded journals. Default rendering stays uninstrumented. Collect native media in a separate pass and compare instrumentation-on/off observer cost.
Make speculation eligibility explicit: while either carousel has a contact, coast, or settle, admit no new dwell or neighbor preparation. Pause admission without consuming the queued neighbor or expanding its bound, reset the center dwell appropriately, and resume with the latest settled center before optional neighbors. A request already executing may finish and consume CPU; account for its full lifetime rather than treating the admission gate as cancellation. Its completion cannot trigger another speculative request while movement continues. Preserve foreground preview/activation priority, request identity checks and the single prepared-slot transaction rules. The existing overlay pre-render motion gate remains a separate protection.
Compare a baseline containing the relocation and thumbnail fixes with only this admission change added, using the same visible catalog, selected theme, background row, kernel, compositor, geometry and background playback state. Record process/cache history explicitly. Per-thread/phase data decides the next rendering change; a broad renderer rewrite, new toolkit, CPU affinity or compositor replacement is outside this task group. If live repaint remains dominant after speculation is bounded, retain that measured remainder here instead of marking swipe acceptance complete.
theme_carousel.rs::motion divides finger displacement by collapsed-slice
pitch (49 pixels for themes, 43 for backgrounds). The focused card’s center
travels 255 or 223.5 pixels in the corresponding first index transition.
The existing unit test asserts index displacement and therefore misses visible
amplification. Derive input mapping from the rendered layout and test actual
card-center displacement, including fractional positions and reversals; do
not relabel a slot-count assertion as screen-space tracking. Keep a stable
reference card during a contact and invert its piecewise center trajectory so
it follows displacement across transitions. Apply the matching local scale
to release velocity, and age that velocity explicitly when release follows
a hold. End-of-list clamping remains bounded.
For the Themes page only, defer touch-motion and frame-callback redraws to the event loop after queued Wayland events have updated the latest position. Respect buffer/frame readiness and preserve immediate tap feedback, foreground activation, and other shell routes. A coalesced intermediate frame is useful; rendering every obsolete sample is not. The board comparison must distinguish mapping, input backlog and render cost. Real-finger acceptance remains open until the operator actually tests the candidate; injected motion can prove geometry and accounting but cannot substitute for that observation.
Task 13.2’s opt-in trace will give overlay commits monotonic frame IDs and request Wayland presentation feedback for those exact commits. Keep callback, commit, feedback-receive and compositor-provided presentation timestamps separate, including clock ID, refresh period, sequence, flags and discarded submissions. Only compare presentation timestamps with input/process clocks when their clock domains match; absent feedback is unavailable evidence. Record main-thread render/rebuild/copy and background work spans with both wall time and thread CPU time, plus the latest picker input sequence. Buffer only a bounded, numeric/allowlisted trace in memory and write it after the capture interval. Trace mode is off by default; measure observer overhead. A report ranks individual stalls within named swipe phases, excludes idle intervals, and shows which spans overlap each stall without treating overlap as proof of causation. Screenshots/camera captures run separately from timing.
The same opt-in recorder will cover shell rendering and theme-helper work, using a shared trace ID, process/thread identity, nested span IDs and remote parent IDs on the existing helper socket. Fixed event names and numeric data exclude theme names, paths, request bodies and credentials. Export uses Perfetto-compatible trace events; this is a local diagnostic format, not an OTLP collector or a claim of complete system coverage. Missing components, dropped events, truncated spans and clock mismatches must remain visible.
CPU flamegraphs require sampled stacks, separately from nested span timelines. Probe the running kernel and perf support before selecting a bounded sampling command; keep raw stacks private until reviewed, retain build/symbol identities, and report unsupported unwinding explicitly. Extend coverage to compositor render/commit/presentation and kernel scheduling only with verified hooks and clock alignment. Compare tracing disabled/enabled and sampling separately so observer cost cannot masquerade as a regression. The picker is the first workload; these formats and tooling should also support cards, launch, drawers and theme activation without a new profiler for every feature.
A generation hashes the selected background as well as theme contents.
The current preview’s generation therefore cannot authorize a different
background. A single background tap must chain a Preview for that exact
background into Activate with the returned generation. No second user tap
is required. Retain the current selected marker until acknowledged commit;
show Applying beside the background row, then Applied to Home or a visible
failure. The catalogue’s current theme/generation follows acknowledged
activation so later taps do not mistake an old theme for the current one.
Physical background/Home agreement is recorded with injected touch and native
captures in docs/evidence/theme-picker/background-selection/README.md.
Real-finger acceptance remains UNVERIFIED for this correction.
The 2026-10-01 physical trace attributes warm swipe frames to about 92 ms of main-thread scene CPU versus about 3 ms copying pixels. Both rows are resolved in the reviewed preflight. The user reports visible jank, especially themes. Restrict the optimization to the existing Settings picker: position/pressed-only changes repaint the affected row, including its old/new outlines and labels, through the identical Cairo scene under an integer clip. Keep the other row and chrome cached. Semantic state, thumbnail completion, theme, services, route and geometry changes retain full invalidation. Byte-for-byte full-render comparisons protect pixels and fallback behavior. This is a bounded cache change, not a new renderer or a claim of smoothness. Admit speculative work only while both carousel rows are at rest; preserve queued neighbor work.
Compare the exact candidate on the reserved board against the retained baseline with matching input and unchanged generation. Report rendering CPU separately from commits/presentation, and retain observer overhead, complete stack and real-finger gates when their full proofs are absent.
User feedback on 2026-10-01: browsing is somewhat less janky, but acceleration and settling still feel wrong. This precedes row-repaint candidate deployment. The references serve different purposes:
/tutorials/data/design/human-interface-guidelines/motion.json
when the JavaScript page cannot be extracted.Current local source, theme_carousel.rs: tick caps coast elapsed at 50 ms
and settling at 48 ms. Actual 100-200 ms frame intervals therefore stretch
wall-clock motion. Coast uses stepped integration with 0.88/16 ms decay;
settling separately starts a cubic ease-out with 140-260 ms duration and
no inherited velocity. These are source findings, not a new physical acceptance.
Preserve exact reference-card displacement while held. After release, evaluate deceleration analytically with full elapsed time and carry screen-space velocity into the centering trajectory. Use a critically damped or similarly monotonic velocity-continuous settle as a tunable starting point, bounded at catalogue ends. A new touch catches the currently displayed position immediately. No extra acceleration during contact; do not reproduce a desktop click animation under a held finger. Initial tuning parameters are our candidates, not Apple values; choose them after comparing slow releases, flicks, reversals, holds, interruption and end bounds for both rows. Input adaptation to HDMI mouse/ trackpad should retain this contract without changing one-finger touch mapping.
Keep the rendering-cost trial unchanged first; otherwise a physics change would confound frame-count/performance comparisons. Then plot distance/velocity over wall time and test irregular cadences (8/16/33/100/200 ms), with a bounded board trial and explicit user feedback. Do not equate lower CPU with good feel.
tools/theme_catalog.py’s main() into a reusable
build_parser()/handle(args) with no behavior change; verify with the
existing python3 -m unittest tests.test_theme_catalog (10 cases, all
still passing) and tests/test_theme_commit_under_occlusion_runtime.py’s
subprocess invocation still working unmodified.tools/theme_helperd.py: a private-socket daemon that calls
that exact parser/handler per request, survives a malformed request
without wedging, and shuts down cleanly on SIGTERM. Verify with
python3 -m unittest tests.test_theme_helper_daemon.tools/theme_client.py: an argv-compatible front end that
tries the daemon first without importing theme_catalog eagerly, and
falls back to the unmodified in-process path otherwise. Verify the
import-avoidance itself with the -X importtime subprocess case in
tests/test_theme_helper_daemon.py, and correctness/fallback with the
rest of that file.nix/shell.nix’s theme-helper.service (guarded by
cfg.coherentShell, same posture as shell-ui.service) and point
nix/handheld-theme-command.nix’s k230-theme wrapper at
theme_client.py. Verify with nix build --no-link --print-out-paths --max-jobs 1 --cores 6 .#handheld-theme-command and a manual run of the
built k230-theme-helperd/k230-theme pair under qemu-riscv64-static
(see docs/evidence/omarchy-themes/theme-swap-jank/README.md).Proof: python3 -m unittest tests.test_theme_catalog tests.test_theme_helper_daemon
and the nix build above.
tools/theme-swap-jank.py, a root board-side capture tool:
triggers a swap, samples per-process CPU from /proc, and collects a
merged wall-clock timeline from the Rust shell’s own commit/
wallpaper-commit/frame-done log lines and K230_CARD_SHELL sway_log
lines via journalctl -o json. Verify with python3 tools/theme-swap-jank.py --self-test.tools/analyze-theme-swap-jank.py: frame-interval histogram,
gaps over 33/50/100 ms with bounding-event context, the longest stall and
its surrounding events, tap-to-visible latency against a configurable
target, and per-process CPU. Verify with python3 tools/analyze-theme-swap-jank.py --self-test.theme-helper.service lands on an installed system. Record
docs/evidence/omarchy-themes/theme-swap-jank/README.md with the exact
journalctl/board commands and both reports. Needs the reserved
board; not run by this change.
Moved 2026-10-12 on the operator-authorized scope split: carried verbatim
into the successor change the-theme-swap-is-profiled-on-the-board
(task 1.1). Not performed here; no result is claimed.Proof for 2.1/2.2: the two tools’ own --self-test. Proof for 2.3: the
committed before/after JSON reports and the exact board commands that
produced them.
tools/theme_transaction.py’s
prepare_only(generation, ...) sends the two-phase protocol’s existing
“prepare” message (the same one activate_generation() already sends
immediately before every commit — appearance.rs’s Prepare handling
already decodes/caches the wallpaper there) without committing, taking
no lock, safe to call repeatedly for different candidates. Wired into
theme_catalog.py’s preview action so browsing already warms both
receivers when --rust-socket/--deck-socket are configured. Verify
with python3 -m unittest tests.test_omarchy_theme_transaction tests.test_theme_catalog.background_decode.rs): BackgroundCache was a
single-slot cache, so browsing a different candidate (task 3.2, or
the Preview page’s own background carousel) evicted an
already-prepared one before its own commit landed, falling back to a
background.cache file read. It is now a small bounded LRU
(CACHE_CAPACITY = 4), so commit is a guaranteed in-memory hit for
any of the last few prepared candidates, not just the single most
recent. Verify with cargo test --offline --test background_decode_module (adds
multiple_recent_candidates_stay_warm_without_evicting_each_other).nix/card-shell/appearance.c/adapter.c): appearance.c
gained an advisory card_appearance_prepare_fn hook, called once per
successfully validated prepare, before its ack (never able to affect
prepare’s own accept/reject decision). adapter.c’s
appearance_prepare uses it to pre-build the deck’s gradient
(card_brush_scene) for the candidate generation, disabled/detached
until a matching commit; appearance_canvas_refresh adopts it at
commit (destroy old, promote pointer, enable+position) instead of
repainting, falling back to today’s inline build whenever nothing
warm matches (dimension/brush/generation changed, or nothing was
prepared ahead) — purely advisory, like background.cache itself.
Verify with python3 -m unittest tests.test_card_shell_appearance
(extended for the new PREPARE hook line) and nix build --no-link --print-out-paths --max-jobs 1 --cores 6 .#card-shell (real
wlroots/Sway types; this task’s C changes cannot be host-unit-tested
beyond the protocol-level hook).prepare_only() (3.1a) as a theme becomes the centred
carousel item, before Apply. Implemented in theme_ui.rs
(ThemeView::poll_prepare_ahead/prepare_ahead_submitted/
prepare_ahead_reply) and wired from main.rs’s existing per-tick
carousel-settle loop: once the centred index is unchanged for 220 ms
with the carousel at rest (!Carousel::is_animating()), it submits the
existing ThemeRequest::Preview (background id None) directly to the
shared ThemeWorker, bounded to one in-flight warm-up at a time (the
stricter half of “one or two”), and the very next settled index simply
replaces the desired target rather than queuing a backlog —
“cancelled on scroll-away” in the sense that a candidate passed through
while still moving, or superseded before its debounce elapsed, is never
submitted. Its reply is recognised by prepare_ahead_reply and
discarded before ThemeView::accept ever sees it, so it can never
navigate or repaint the chooser. Reuses the existing preview action
(already calling prepare_only() per 3.1a) rather than adding a new
verb or protocol. Verify with cargo test --offline --lib theme_ui.wvkbd recolour/restart until after the visible swap
commits and this response is otherwise ready, so it never blocks
activated: true. theme_catalog.py’s activate action now reports
keyboard_appearance: {"state": "deferred"} immediately and runs
keyboard_appearance.sync_and_restart on a background (non-daemon)
thread; theme-helper.service’s request loop sends its reply the
moment handle() returns, independent of that thread, so the
daemon-served path drops this cost entirely, while a bare CLI
subprocess is unaffected (the interpreter already waits for a
non-daemon thread at process exit, so its total wall-clock time is
unchanged). Verify with python3 -m unittest tests.test_theme_catalog
(adds test_activate_reports_keyboard_sync_as_deferred_but_it_still_completes).activate_generation(..., defer_app_sync=True) and reports
app_appearance: {"state": "deferred"}. Direct callers keep the synchronous
result. A non-daemon thread invokes the same guarded app adapter, including
its shared GTK keyfile, without changing prepare/commit/rollback. Late old
work refuses a newer generation; failures are logged without shell rollback.
The Rust consumer accepts the new status through both transports and retains
the normal applied message. Named host proof: python3 -m unittest tests.test_omarchy_theme_transaction tests.test_theme_catalog tests.test_theme_helper_daemon tests.test_handheld_app_themes (70 pass),
cargo test --offline --manifest-path nix/rust-shell-client/Cargo.toml --test theme_catalog_module (6 pass), and cargo test --offline --manifest-path nix/rust-shell-client/Cargo.toml --lib theme_ui (28 pass).
Package proof: nix build .#handheld-shell-rust .#handheld-theme-command
(both built). Committed proof and artifact identities:
docs/evidence/theme-picker/foot-deferral-2026-10-10/README.md.
No new board observation or latency claim; deploy the compatible helper and
Rust client together before qualifying that physical behavior.tools/analyze-theme-swap-jank.py’s tap-to-visible metric
against the board once 3.1b/3.2/3.3 land, and report against the ~100 ms
target. Needs the reserved board; 3.1b/3.2/3.3 now have source/package
proof. The named measurement remains unperformed and was deferred by the user.
Moved 2026-10-12 on the operator-authorized scope split: carried verbatim
into the successor change the-theme-swap-is-profiled-on-the-board
(task 1.2). Not performed here; no result is claimed.prepare()’s own costOnce 3.1b/3.2/3.3a were on the board, k230-theme preview/activate of an
already-prepared catppuccin/catppuccin-latte (a generation that
already existed, with its own background.cache) still took 3.95-4.26 s
each — slower than the pre-daemon 2.8-3.5 s baseline, and
journalctl -u theme-helper showed no entries at all, because nothing on
this path had ever logged anything.
theme_activate.py’s prepare() checked whether the
destination generation already existed only at the very end of the
function — after staging every asset (a byte-for-byte copy of every
background image), invoking omarchy-theme-color --all and
omarchy-theme-set-templates (each itself spawning several awk/sed
subprocesses), and (for a still background) building the wallpaper
cache. All of that ran, and was discarded, on every call, even for a
generation prepared thousands of times before. theme_client.py’s own
--helper-timeout-s compounded this: its 0.3 s default was sized for
the daemon’s own Python-import savings, not for this real (if
unnecessary) prepare() cost, so almost every preview/activate
timed out waiting on a working daemon reply and fell back to the full
in-process path — paying the wasted timeout, the ~1.2 s import chain,
and prepare()’s cost a second time. Confirmed on this host: a repeat
prepare() for the same generation dropped from ~250-370 ms to ~2-3 ms
once the identity check moved first; the daemon-vs-fallback confusion is
fixed by widening the client timeout to 10.0 s (see theme_client.py’s
own comment for the exact reasoning) and by theme_helperd.py’s new
per-request timing making the daemon’s own answer time directly visible
instead of inferred.theme_activate.py’s prepare() now computes the
generation identity (two content hashes plus a cheap background-name
listing, no asset bytes copied and no external helper spawned) and
checks for an existing destination before staging, invoking any
omarchy-theme-* helper, or building a wallpaper cache. A cache hit
returns the on-disk report.json (patched only for the one genuinely
request-specific field, a since-removed remembered background) without
touching checked_copy/invoke. Verify with python3 -m unittest tests.test_omarchy_theme_activation (adds
test_repeated_preparation_of_an_existing_generation_skips_staging_and_helpers
and test_repeated_preparation_reports_a_newly_missing_remembered_background,
both asserting checked_copy/invoke raise if called on a cache hit).theme_client.py’s DEFAULT_TIMEOUT_S raised from 0.3 to
10.0. Verify with python3 -m unittest tests.test_theme_helper_daemon
(adds test_client_stays_on_the_daemon_for_a_legitimately_slow_but_working_reply,
a daemon reply mocked to take 0.6 s — past the old default, comfortably
inside the new one — asserting theme_client.fallback is never called).tools/theme_timing.py (Stopwatch +
log()) emits one THEME_TIMING <component> <action> phase=Xms ...
line per request via syslog (never stdout/stderr, which
theme_catalog.rs’s command_error() parses byte-for-byte as JSON on a
nonzero exit — seeing this in journalctl needs no code reading, only
the exact commands in this change’s evidence doc). Wired into
theme_activate.prepare() (per-phase: hashes, background listing,
cache hit/miss/race, staging, each external helper invocation, publish),
theme_transaction.exchange() (per prepare/commit/rollback round trip,
by endpoint), theme_catalog.handle() (per action, plus the deferred
keyboard thread’s own eventual completion), theme_helperd.handle_line()
(request parse time and self.lock wait, separate from handle()’s own
breakdown), and theme_client.py (which path was taken — daemon or
fallback — and why a daemon attempt was abandoned, if it was). Also adds
a rust-shell <ms>ms theme-command <action> <id> duration=<ms>ms line
to theme_catalog.rs’s execute(), in the same shape
tools/theme-swap-jank.py’s existing RUST_LOG_RE already parses, timing
the chooser’s own wait on the k230-theme subprocess. Verify with
python3 -m unittest tests.test_theme_timing and cargo test --offline.activate of an
already-prepared theme is now well under 500 ms end to end, with
journalctl showing the daemon path taken and prepare() reporting
cache=hit. Board result (coordinator, system 46vdy1dy...):
activate 1.27-1.38 s (was ~4.2 s), preview warm 1.06-1.08 s;
THEME_TIMING showed handle activate total 245 ms (discover 42,
prepare_entry 73, activate_generation 128, keyboard-deferred
dispatch 3.6), helperd total 265 ms, client socket_round_trip 270 ms
path=daemon, exchange prepare 10-20 ms/commit 7-14 ms per receiver,
keyboard_deferred sync_and_restart 300 ms off the critical path. This
confirmed the daemon path itself is fast (~250-270 ms); the ~1.0 s
remaining per call is the theme_client.py Python-interpreter-plus-
runuser subprocess start-up the Rust chooser still pays for every
request — named explicitly as task 5’s own starting point below.Proof for 4.1-4.5: the tests named above (host), plus the board run above.
nix/rust-shell-client/src/theme_catalog.rs’s ThemeWorker
speaks theme-helper.service’s own line protocol directly over
K230_THEME_HELPER_SOCKET (/run/shell/theme-helper.sock, matching
theme_client.py’s DEFAULT_SOCKET; set explicitly in nix/shell.nix)
— the exact same JSON-line request/reply shape
tools/theme_client.py/tools/theme_helperd.py already speak to each
other, so there is no second, drifting protocol. On any socket problem
(missing, refused, timed out, malformed reply) it falls back to the
existing k230-theme subprocess unchanged, which itself still tries the
same daemon and falls back further, so a socket that is merely slow to
start still degrades no worse than before this task. An empty
K230_THEME_HELPER_SOCKET disables the direct path entirely, matching
K230_THEME_COMMAND’s own unset-env convention. Verify with cargo test --offline --test theme_catalog_module (5 new cases: a working
socket reply is used without ever invoking the subprocess; a
daemon-reported error is returned without retrying via the subprocess;
a missing socket, and a malformed reply, both fall back to the
subprocess; an empty socket path disables the direct attempt entirely
— each proven by a “poison” fake subprocess that marks a file if it
ever actually runs).discover’s ~42 ms: theme_catalog.discover() is now a
cached wrapper (_discover_uncached does the real walk) keyed by
(user_themes, builtins), invalidated by a cheap stat-only fingerprint
of exactly the directory levels discover() itself reads (each root’s
top level, and one level under a user entry’s own themes/ collection)
— never a content read or the identity-hashing/find_preview()/
resolve() work discover() itself does. A bare CLI process only ever
calls this once per invocation (empty cache, no behaviour change); the
daemon serves many requests against a catalog that, in the normal
preview-then-activate chooser flow, has not changed. Verify with
python3 -m unittest tests.test_theme_catalog (adds
test_discover_is_cached_until_the_catalog_directory_actually_changes,
proving an unchanged catalog is not re-walked and that adding or
removing a theme is still noticed on the very next call).prepare_entry’s ~73 ms: theme_activate.py’s
helper_digest() caches source_digest(tools) indefinitely, keyed by
the tools directory’s own resolved path. tools is
theme_helperd.py’s own fixed --tools startup flag (a Nix store path
in production), immutable for the daemon’s whole lifetime, unlike the
theme’s own source_hash (deliberately left uncached: a person can edit
their own theme’s files while the daemon keeps running). Verify with
python3 -m unittest tests.test_omarchy_theme_activation (adds
test_helper_digest_is_cached_across_repeated_preparations, counting
source_digest calls across two prepare() calls for the same tools
path).phj9y4fggpb177b0hgaawbh510chhwil, master
f4f75998, docs/evidence/omarchy-themes/instant-theme-swap/ board-chooser-2026-09-25.md): list path=socket 166 ms, warm
preview 206 ms, cold prepare-ahead (carousel opens) 4071 ms, tap
Apply -> Rust appearance-commit-accepted 556 ms, activate
path=socket 509 ms with helper breakdown parse=65.0ms discover=2.0ms prepare_entry=90.6ms activate_generation=336.0ms (handler total
438.6 ms, helper total 504.1 ms). The direct socket removed essentially
all of the ~1.0 s subprocess/Python start-up as predicted (roughly 8x
faster than the pre-daemon baseline), but still misses the ~150 ms
target: activate_generation re-runs the two-phase prepare exchange
during Apply even though the chooser’s own prepare-ahead already
prepared that exact generation, and parse/prepare_entry cost more
than a cache hit should. This is section 6’s own starting point below.Proof for 5.1-5.3: the tests named above, all passing on this host; proof for 5.4 is the board run quoted above.
theme_helperd.py’s Helperd.handle_line() called
theme_catalog.build_parser() (constructing a fresh argparse. ArgumentParser, with all its subparsers/actions) on every request,
not once at daemon start — the board’s 65 ms parse phase was almost
entirely this construction, not argument parsing itself. Fix: build the
parser once in Helperd.__init__() and reuse it. Verify with
python3 -m unittest tests.test_theme_helper_daemon (adds
test_the_argument_parser_is_built_once_not_once_per_request, counting
build_parser calls across several requests on one daemon instance).prepare_entry’s 91 ms): theme_activate. prepare() re-hashed the theme’s own source tree
(source_digest(theme), a full content read/hash of every file) on
every call, even for a generation prepared moments before by the same
unchanged theme — deliberately never cached before this task, because a
person can edit their own theme’s files while the daemon keeps running.
Fix: tools/theme_sources.py gains source_fingerprint(theme), a
stat-only walk (name, size, st_mtime_ns per file, no content read) of
exactly the same tree source_digest() walks; theme_activate. theme_digest() wraps source_digest() with a cache keyed by the
theme’s resolved path, invalidated only when source_fingerprint()
itself changes — so an edited file (which changes its size and/or
mtime) is still re-hashed, and an unchanged theme is not. Verify with
python3 -m unittest tests.test_omarchy_theme_sources (adds
test_fingerprint_matches_digest_sensitivity_without_reading_content)
and tests.test_omarchy_theme_activation (renames the existing digest-
caching test to test_theme_and_helper_digests_are_cached_across_ repeated_preparations and adds test_theme_digest_cache_is_invalidated_ by_an_edit_between_preparations, editing a theme file between two
prepare() calls and asserting a fresh digest/generation).activate_generation’s
336 ms): tools/theme_transaction.py’s activate_generation() always
sent a fresh prepare to both receivers before commit, even when a
receiver already held that exact generation staged from an earlier
exchange() call (task 5’s own prepare-ahead, or the chooser’s own
warm preview) — there was no memory of which receiver was already
warm for which generation. Fix: exchange() now records, per endpoint,
the generation last successfully prepared for it
(_prepared_state: dict[Path, str], cleared on that endpoint’s own
commit or rollback); activate_generation() partitions its targets
into warm (already holding this exact generation) and to_prepare,
sends prepare only to to_prepare, and commits all targets
unconditionally. If a “warm” receiver’s commit is rejected anyway (the
tracking was stale — e.g. a concurrent caller reset that receiver
without this process’s knowledge), the code transparently falls back to
a real prepare + commit for that one receiver before re-raising on
any further failure, so a stale assumption degrades to exactly today’s
behaviour rather than a wrong commit, and full rollback correctness
(all-or-nothing across receivers) is unchanged. Verify with python3 -m unittest tests.test_omarchy_theme_transaction (adds
test_activate_skips_a_prepare_already_warm_for_both_receivers,
test_activate_prepares_only_the_receiver_that_was_not_already_warm,
test_stale_warm_assumption_retries_with_a_real_prepare_and_still_ succeeds, test_a_genuine_commit_failure_for_a_warm_receiver_still_ rolls_back_fully, and test_exchange_tracks_prepared_state_across_ prepare_commit_rollback).nix/rust-shell-client/src/theme_ui.rs’s ThemeView gains
pending_neighbor_warms, populated with the active theme’s immediate
list neighbours (one or two, whichever exist) every time a list reply
is accepted — covering both chooser-open and the return from Preview/
Cancel back to List. poll_prepare_ahead() still prioritises a real
dwell-driven warm-up (task 3.2’s own 220 ms centred-and-at-rest debounce)
every tick, and only drains the neighbour queue (one request per idle
tick, still bounded to one in flight, still discarded before reaching
ThemeView::accept) when nothing dwell-driven is due — so a person
actively browsing is never delayed behind a neighbour warm-up, but a
static chooser (or one returning from Preview) starts warming the two
themes a first swipe is most likely to land on without waiting on any
dwell at all. Verify with cargo test --offline --lib theme_ui (adds
a_list_reply_queues_both_neighbours_of_a_mid_list_active_theme,
a_list_reply_queues_only_the_one_neighbour_at_each_end_of_the_list,
a_single_theme_list_queues_no_neighbours,
the_neighbour_queue_drains_when_nothing_is_dwell_driven, and
a_dwell_driven_request_takes_priority_over_the_neighbour_queue).journalctl showing activate_generation
skip the redundant prepare for both receivers (a warm=2 — or
similar — log line, or simply the absence of a second appearance- prepare-accepted between the chooser’s own warm-up and its Apply) and
parse/prepare_entry dropping close to their cache-hit floor. Also
confirm the cold-open case: with 6.5 installed, the second theme a
person previews after opening the chooser (having not touched the first
one long enough to trigger its own dwell) should already be warm from
the neighbour queue, not a fresh ~4 s preview. Needs the reserved
board; not run by this task — see this task’s own evidence doc for the
exact commands.
Run 2026-10-12, task stays open (two cold-process trials; docs/evidence/theme-picker/board-session-2026-10-12/README.md): Apply of
an already-prepared generation was not under 150 ms (activate_generation
193 to 242 ms, activate round trip 253 to 314 ms). activate_generation did skip
the redundant prepare for both receivers (prepare_phase 0.1 to 3.1 ms,
warm=2 targets=2), but a second appearance-prepare-accepted still occurs at the
tap because the chooser sends a preview first. The cold-open neighbour check
passed: the second theme previewed 231 to 241 ms about 0.3 s after the first
(380 ms), not a fresh ~4 s (process-cold, not disk-cold). Next measured correction:
skip or make idempotent the tap-time preview for a generation already held.
Host proof for that correction (branch perf/theme-tap-apply; the board check remains open):
ThemeView::tap_theme now seeds Desired::generation from known_generations
(learned by the browse-time warm) for a non-active theme, so the tap sends
Activate directly with no preview and no second appearance-prepare-accepted;
a rejected direct Activate evicts the cached generation so the retry previews.
Separately, RendererCache::content_generation() no longer counts chooser
changes with a bump-per-change counter (the tap’s own press/release toggled
theme_pressed twice and made the browse-time pre-render read
content-changed although the view had returned to the identical state); it
now folds in a value fingerprint of the compared chooser fields, so a
reverted view matches again while a real change still does not. Host tests:
cargo test --offline --lib theme_ui (36 passed, incl.
tap_theme_on_a_warmed_slice_skips_the_preview_and_activates_directly,
a_rejected_direct_activate_evicts_the_known_generation_so_the_next_tap_previews,
tap_theme_on_the_active_slice_ignores_a_known_generation) and
cargo test --offline --lib render::tests (incl.
a_pressed_wash_that_came_and_went_leaves_content_generation_unchanged).
No host test shows prerendered=true on glass; the board must re-run the
10.7/6.6 trial and show no tap-time preview, prerendered=true, and the
new tap-to-shown time. The content-changed cause is inferred from code
(UNVERIFIED on the board).
Board re-run 2026-10-12 (b), task stays open (docs/evidence/theme-picker/board-session-2026-10-12b/README.md, “Task 6.6”; candidate
3m65ag9z, source e93b5a23, two cold-process trials, injected taps): no tap-time
preview and no second appearance-prepare-accepted follow a tap. The
browse-time pre-render is reused (prerendered=true, 4 of 4) after a second
correction: the chooser fingerprint was recomputed only when the per-update
cache-key check fired, so a settle in sub-quarter-item steps left it on a
mid-settle position. Tap-up to shown frame fell from 510-570 ms to 151-190 ms.
It is still not under 150 ms: activate_generation is 140-174 ms, of which
commit_phase is 72-109 ms and swap_pointer 26-33 ms, and the activate round
trip is 280-326 ms.
Follow-up 2026-10-12 (b), task stays open (same README, “Follow-up: what
the tap waited on”; candidate hl4bca4g, two cold-process trials, injected
taps): the touch-up handler no longer draws the picker before the optimistic
check, Home’s repaint waits for the commit, and a reused optimistic commit is
acknowledged on arrival. Tap-up to the shown frame is 27.5-34.2 ms
(prerendered=true, 4 of 4). The durable activation is still not under
150 ms: activate_generation 167-179 ms (commit_phase 105-116 ms, shell
commit exchange 37-53 ms), round trip 333-342 ms. Whether “end to end” means
the visible apply or the helper’s durable activation is for the coordinator
to decide; until then the task stays open. Installed as system 298a2bf6
(README, “Install of candidate 8”); one installed apply trial: shown 28.0
and 42.2 ms, activate_generation 152.0 and 148.7 ms, round trip 313 and
309 ms.
Accepted 2026-10-12 by the operator on installed system 298a2bf6…
(Rust hl4bca4g…), after being asked whether “end to end” means the visible
apply (28-42 ms) or the helper’s durable activation (149-179 ms): “it’s great
now i tried it all it’s good”. The operator measure is the visible apply; the
durable activation figures above stand as recorded and are not claimed under
150 ms.Proof for 6.1-6.5: the tests named above, all passing on this host; proof for 6.6 is the reserved board, not run here.
nix/rust-shell-client/src/main.rs gains should_apply_ optimistically (pure: is the just-submitted Activate request’s own
target generation exactly the local AppearanceReceiver’s own
prepared snapshot) and optimistic_apply_due (pure: has this exact
pending_id already been checked this Apply), checked once per fresh
Apply right after Wayland event dispatch in serve’s own loop — the
same tick a touch-up calling theme_action(ThemeIntent::Apply) would
have run in. When eligible, show_theme_optimistically renders the
already-validated prepared snapshot through the same draw_wallpaper/
draw/flush calls the real commit path already uses (skipping only for
a video-backed selection, an unrenderable snapshot, or an overlay not
immediately ready for a new frame — each of which the real commit
event’s own existing readiness handling still covers correctly), and
logs rust-shell <ms>ms optimistic-apply shown ms=<tap-to-frame>. This
never touches AppearanceReceiver’s own prepared/active bookkeeping,
the Activate request submit_theme already dispatched to ThemeWorker
unchanged, or the wire acknowledgement contract in any way — the real
AppearancePhase::Commit/Rollback handling (unmodified) is what
authoritatively settles both the receiver’s own state and the visible
appearance once the durable transaction actually completes, which is
also what correctly reverts the display and (via ThemeView::accept’s
existing, unmodified Err handling) surfaces a visible error on a
durable commit failure. A cold/unprepared generation is unaffected: it
is never prepared early to qualify, and Apply shows the pre-existing
busy state exactly as before. Verify with cargo test --offline
(route_tests::optimistic_apply_fires_only_for_an_activate_matching_the_ prepared_generation, route_tests::optimistic_apply_due_is_scoped_to_ each_fresh_pending_id_for_a_rapid_double_apply, and
theme_ui::tests::a_failed_activate_clears_pending_and_surfaces_a_ visible_error).nix/card-shell/appearance.c gains an additive "show" protocol
phase: renders service.candidate immediately when it is already
service.prepared and matches the requested id/path, exactly like the
existing commit branch’s own render call and with the same best-effort
restore-on-failure as that branch, but never touches service.prepared/
service.candidate_path/service.current — so a real commit or
rollback for the same candidate behaves identically whether or not
show was ever sent. main.rs’s show_appearance_optimistically sends
this best-effort, fire-and-forget (a short write deadline, no reply
read — any failure is silently ignored) to K230_CARD_APPEARANCE_SOCKET
(defaulting to nix/shell.nix’s existing SWAY_K230_CARD_APPEARANCE_ SOCKET production path), after its own local render/log so a slow or
unreachable compositor never inflates the logged tap-to-frame latency.
This channel is only reachable once the two-phase transaction’s own
--rust-socket/--deck-socket fanout is wired into theme-helper. service (a separate, not-yet-landed task — see proposal.md’s own
note); until then it is dormant, correct, and tested in isolation.
Verify with python3 -m unittest tests.test_card_shell_appearance
(adds test_show_renders_a_prepared_candidate_without_disturbing_the_ two_phase_state, test_show_is_rejected_for_a_generation_that_was_ never_prepared, and test_show_never_blocks_a_later_rollback_from_ restoring_the_previous_generation, all against the real compiled
appearance.c over a real socket).proposal.md’s “What This Does Not Do” section is
revised: its former “Two-phase transaction reordering” bullet read as
ruling out any such change permanently, which stopped being accurate
once the user approved this; it now explains precisely what did and did
not change (the chooser’s own display timing, never the wire
acknowledgement contract). design.md gains a new “Optimistic Apply”
section recording why gating on “already prepared locally” is
sufficient for correctness, why the compositor side is best-effort
rather than a precondition, and the two alternatives rejected (relaxing
the wire ack contract itself; a cross-process optimistic-shown flag).
Verified with openspec validate the-shell-swaps-themes-without-a- python-stall --strict.4b947d13, installed as
i3dxi8y0...): the optimistic path did not fire. No
optimistic-apply shown line anywhere in the journal for an Apply of a
neighbour-warmed, then explicitly confirmed, theme; the durable path
alone still ran (activate ... ms=441, helper activate_generation= 356.6ms). This is task 7.5’s own starting point, below — see its
grounding comment for the exact log sequence and root cause.ThemeView::poll_prepare_ahead
never checked self.pending, so while a real, explicit request (a
confirm tap’s own Preview, submitted via submitted()) was still
awaiting its reply — the page stays List until that reply lands, so
main.rs’s own page == ThemePage::List gate did not stop it either —
the same per-tick call could also drain pending_neighbor_warms and
submit an unrelated neighbour’s own warm-up Preview. ThemeWorker
processes requests strictly in submission order on one thread, and each
appearance receiver keeps only a single most-recently-prepared
candidate; the neighbour’s later “prepare” therefore silently
overwrote what the confirm’s own “prepare” had just staged in
AppearanceReceiver::prepared — before its own reply was even back —
so by the time Apply ran, appearance.prepared() named a different
generation than the one just confirmed, and optimistic_apply_skip_ reason correctly (if unhelpfully, before this task) returned
generation-mismatch. Fix: poll_prepare_ahead now returns None
unconditionally whenever self.pending.is_some() — no dwell-driven
warm-up, no neighbour-queue drain — resuming on whatever tick pending
next clears; the dwell clock keeps accumulating in the meantime, so
nothing already waited out is lost. Also adds a debug log,
rust-shell <ms>ms optimistic-apply skipped reason=<reason>, on every
Apply tap that does not show optimistically (not-prepared,
generation-mismatch, commit-draw-in-flight, video-background,
unrenderable-snapshot, not-ready-for-a-frame, draw-wallpaper- failed, draw-failed, flush-failed), via the new pure
optimistic_apply_skip_reason (should_apply_optimistically now
delegates to it). Verify with cargo test --offline (adds
theme_ui::tests::a_pending_confirm_pauses_every_warm_up_until_its_own_ reply_lands — reproduces the exact board sequence: warm neighbour A,
swipe to and confirm neighbour B, assert nothing is emitted for any
number of ticks while B’s own Preview is pending, confirm Apply then
targets exactly B’s own reported generation; confirmed this test fails
without the fix — left: Some((2, Preview {...})) right: None — and
passes with it — and route_tests::optimistic_apply_skip_reason_names_ the_specific_cause).Proof for 7.1-7.3, 7.5: the tests named above, all passing on this host (7.5’s own regression test independently confirmed to fail against the pre-fix code); 7.4 is the board result quoted above, negative before this fix, not re-run since (board not touched by this task).
2b575dba, installed
as nmdf96j1...): the race is fixed and the decision is reached, but
two new problems: (a) optimistic-apply skipped reason=not-ready- for-a-frame — the same class of bug cd36242b fixed for
draw_wallpaper()’s own entry guard and the durable commit path’s
ready predicate, but draw()’s own entry guard (the theme chooser’s
own overlay/settings surface) still gated on self.frame_pending, and
so did show_theme_optimistically’s own separate readiness pre-check
(copied from the durable path before this task noticed the durable
path’s own overlay_ready term had the identical gap); (b) about
300 ms from the Apply touch-down to the optimistic decision, not yet
root-caused with board timing data.redraw_entry_ready(appearance_ pending, configured, layer_present) (main.rs) is draw()’s entry
guard now, with no parameter to gate on any surface’s own outstanding
frame callback — structurally the same fix cd36242b already applied
to draw_wallpaper(), extended to the overlay surface, whose own entry
guard that earlier fix never touched. show_theme_optimistically’s own
separate overlay_ready/ready pre-check is removed entirely: it now
attempts draw_wallpaper()/draw() directly and reads their own
return values, exactly like the durable commit path’s ready == true
branch already does (with no 1400 ms retry window, since unlike a
durable commit, a missed optimistic frame costs only the optimism
itself — the real commit/rollback event still lands and settles
correctly regardless). The durable commit path’s own overlay_ready
term (serve’s own pending_appearance handling) is fixed the same
way, closing the identical latent gap there too (previously invisible
behind its own 1400 ms retry loop). Verify with cargo test --offline
(adds route_tests::redraw_entry_never_gates_on_a_surfaces_own_ outstanding_frame_callback, whose signature — no frame-pending
parameter at all — is itself the regression proof: this mistake cannot
be reintroduced by accident).optimistic-apply skipped reason=.../shown log now carries ms=<tap-to-decision-or-frame>, so
a board re-run can attribute the remaining latency precisely (input
recognition before submit_theme sets theme_apply_tapped_at —
already close to the existing touch-up <id> log, since submit_theme
runs synchronously in the same call chain — versus this task’s own
decision/draw/flush cost, which reading main.rs’s code found no
blocking calls in: try_submit is try_send (never blocks),
AppearanceSnapshot::clone() carries no pixel data, and (after 7.7) the
draw calls no longer wait on any frame callback). Closeout audit
(2026-09-28): the ms= fields (nix/rust-shell-client/src/main.rs
lines ~1600-1749) are on disk and were exercised by the very next board
run, quoted verbatim in task group 8’s own grounding comment above
(coordinator, master e2ba1d7e, installed s376wb46...:
optimistic-apply shown ms=222.7) — this instrumentation’s own board
data is what root-caused task 8’s synchronous-overlay-rebuild finding.
Ticked here because that board run already exists and is cited, not
because a further run was performed by this audit.Proof for 7.1-7.3, 7.5, 7.7: the tests named above, all passing on this
host; 7.4/7.6 are the board results quoted above; 7.8’s own instrumentation
answered its own question on the very next board run — see task 8 below,
which its board evidence directly motivates: optimistic-apply shown ms=222.7 is (almost) entirely the synchronous overlay-scene rebuild
Apply’s own optimistic show pays inline, not event-loop or dispatch
latency.
draw_wallpaper()’s own buffer-pool
exhaustion check raised from >= 2 to >= 3 (the overlay surface’s own
pool was already bounded to 3), and the SHM pool’s own initial-size hint
raised from * 5 to * 6 slots (568x1232x4 bytes each, ~2.8 MB, matching
the coordinator’s own figure) — an estimate only, since SlotPool
itself grows automatically on any further allocation regardless
(confirmed by reading smithay-client-toolkit’s own SlotPool::resize
doc: “the pool automatically resizes when you allocate new slots”).
This alone (independent of pre-rendering) is what stops the durable
commit’s own redraw from ever again failing merely because an
optimistic draw is still holding a buffer the compositor has not yet
released.RendererCache (render.rs) gains content_generation: u64
(bumped by set_theme_view/set_services/a real set_drawer_pressed
change/a poll_theme_image- or poll_theme_thumbnails-detected change
— every non-appearance input a scene render depends on — and
deliberately not by set_appearance/set_icon_theme, which a
candidate pre-render is expected to differ from self.theme on, on
purpose), render_candidate_overlay(theme, route, width, height, apps)
(computes a full overlay-scene raster for an arbitrary theme using a
fresh, isolated IconCache and every other input read live from
self — services/chooser/pressed/preview_surface/
preview_error/thumbnails — provably never touching self.theme/
self.icons/static_pixels/route, so nothing can flash the wrong
theme before Apply), and adopt_prerendered_overlay(theme, route, width, height, pixels) (seeds self.theme/self.icons/
static_pixels/route/width/height/scroll directly from an
already-computed raster, so draw()’s own next call sees a cache hit
and takes its cheap shift-and-copy path instead of rebuilding). Verify
with cargo test --offline --lib render::tests (adds
content_generation_bumps_on_content_changes_but_not_on_appearance_ changes, render_candidate_overlay_never_mutates_the_live_cache,
adopt_prerendered_overlay_is_a_cache_hit_with_the_candidates_own_ pixels).main.rs’s own event loop computes the pre-render once per
(generation, route, geometry, content_generation) tuple whenever the
Preview page’s own currently-loaded candidate is already the receiver’s
own prepared snapshot (the same precondition Optimistic Apply itself
checks — never a cold generation, never a merely-warmed neighbour still
being browsed past), bounded to one slot (ShellClient:: prerendered_overlay: Option<PrerenderedOverlay>), and only after that
tick’s own queue.flush() — never earlier in the same iteration —
so the real, synchronous Cairo cost this pays is never charged against
flushing the very Preview-page frame that made it eligible. Skipped
entirely while an Activate is already in flight. Verify with cargo test --offline --lib route_tests
(prerendered_overlay_matches_requires_every_field_to_agree, the pure
matching predicate this trigger and Apply-time consumption both share).show_theme_optimistically consumes the stored pre-render
(always taking the one bounded slot, matching or not, so a stale one
never lingers for a later Apply) when it matches this exact Apply’s own
generation, route, geometry, and content_generation; on a match it
calls adopt_prerendered_overlay instead of set_appearance (skipping
the rebuild entirely); on any mismatch it falls back to set_appearance
exactly as before this task. The optimistic-apply shown ms=... log
gains prerendered=true/false. Verify with the 8.2/8.3 tests above
(the underlying primitives) plus route_tests:: optimistic_apply_fires_only_for_an_activate_matching_the_prepared_ generation and the existing Optimistic Apply suite, all still passing
unmodified.ShellClient::optimistic_active: Option<String> records the generation a successful optimistic show
just flushed; the very next Commit/Rollback event’s own handling
checks may_reuse_optimistic_frame (pure: true only for a Commit
whose own generation matches exactly — a Rollback’s own target is by
definition the previous generation, never the one just shown) and
clears optimistic_active unconditionally either way, so it can only
ever be read by that one next event. A match skips draw_wallpaper/
draw/flush entirely (pending_appearance’s own new
reuse_optimistic element) and goes straight to the same video-state
bookkeeping (adopt_committed_video_state, factored out of what was
previously inline in the redraw-success branch so both paths share it)
and the ack — still sent only after a real, already-flushed frame,
never before one. Verify with cargo test --offline --lib route_tests
(may_reuse_optimistic_frame_only_for_a_commit_matching_exactly).optimistic-apply shown ms= drops close
to the ~30 ms target (a cache-hit shift-and-copy plus an attach+commit,
not a rebuild) with prerendered=true for a warm Apply; confirm no
appearance-commit-rejected draw-wallpaper-failed on the success path
(the third buffer); confirm the durable commit’s own log shows
appearance-commit-accepted reused=optimistic and activate_generation
no longer carries a retry’s own doubled cost; confirm a geometry, page,
or content change between prepare and Apply correctly falls back to a
full rebuild (prerendered=false) rather than showing stale content.
Closeout audit (2026-09-28): this recheck was in fact run — it is task
group 9’s own grounding comment above (coordinator, master c6f0237a,
installed vq6vkvqz...). Following this project’s own established
convention for “board re-check” tasks (7.4 and 7.6 above are ticked
despite negative results, because finding and reporting the real cause
is the deliverable), ticking here too: the result was
prerendered=false (not the target), root-caused to submit_theme’s
own theme_dirty() invalidating the very pre-render it needed, which
task group 9 then fixed; the durable-commit-reuse half of this check
did pass (appearance-commit-accepted reused=optimistic, no rejection).
The unmet target is what task group 9 exists to close, not evidence
this recheck itself was skipped.Proof for 8.1-8.5: the tests named above, all passing on this host; proof for 8.6 is the reserved board, not run here.
Preparing…/error/message status line below
it) is extracted out of paint_theme_chooser into a new, standalone
paint_preview_footer_status (render.rs) and painted live, by
RendererCache::draw() itself, on every call — whether that call just
rebuilt static_pixels or reused it (including an adopted pre-render).
paint_theme_chooser no longer paints any of it at all (for either
page: the List page’s own status line is unaffected, still baked into
its cached body as before). This is what makes a pre-render computed
before an Apply tap still correct after one: the tap’s own pending
transition changes only what the live overlay paints, never what the
cached/pre-rendered body underneath it has to be rebuilt for. Verify
with cargo test --offline --lib render::tests (adds
adopted_prerender_still_shows_the_live_pending_state_via_the_overlay,
independently confirmed to fail — the exact stale-idle-button pixels
— with this task’s fix temporarily disabled, and pass with it restored;
all 25 pre-existing render::tests cases, which exercise the Apply
footer’s own pixels through the unchanged public RendererCache::draw,
still pass byte-for-byte unmodified, proving the split is
output-equivalent for every case that was already covered).content_generation (task 8.2) no longer bumps for a
set_theme_view call that changes only pending/pending_id/
selection_error/error/message/pulse_phase — exactly the fields
9.1 moved to the live overlay — via a new pure theme_view_cache_key_ differs (comparing page/list/preview/theme_pressed/
background_pressed exactly, theme_position/background_position
with the same small tolerance RendererCache::draw’s own scroll
check already uses). invalidate() itself stays unconditional on every
set_theme_view call, so a live (non-optimistic) draw() still
rebuilds on every theme_view change exactly as before this task;
content_generation is now a narrower, pre-render-specific freshness
signal, decoupled from that. This also closes the coordinator’s own
third observation (double pre-render computation ~150ms apart, a full
THEME_PULSE_INTERVAL): a pulse-only tick can no longer churn
content_generation either. Verify with cargo test --offline --lib render::tests (adds a_pending_only_theme_view_change_does_not_bump_ content_generation, proving both that pending/pulse changes are now
excluded and that a genuine content change — a different preview —
still bumps it as before).theme_view. pending.is_none() outright, not just “not an Activate”: the background
carousel’s own busy spinner (a Preview{background_id: Some(_)}
request in flight) is baked into the cached body the same as anything
else content_generation does not track, and 9.1’s live overlay does
not cover it (only the Apply/Cancel footer and status line) — so
computing a pre-render while a background selection is still pending
risked caching a stale busy indicator no later live paint would ever
correct. Requiring nothing at all pending closes that gap by
construction rather than adding a second live overlay for it.optimistic-apply shown ms=... prerendered=false now carries
reason=<field> (no-prerender-computed, generation, route,
geometry, content-changed, or not-on-settings-route) naming
exactly which check failed, via a new prerendered_overlay_mismatch_ reason that prerendered_overlay_matches (task 8.3’s own pure
predicate) now delegates to, so the two can never drift apart. Verify
with cargo test --offline --lib route_tests
(prerendered_overlay_mismatch_reason_names_the_specific_field).optimistic-apply shown ms=<N> prerendered=true for a warm Apply, with <N> close to the ~30 ms
target; confirm the earlier double-prerender-computation symptom is
gone (at most one optimistic-apply prerendered line per genuine
content change while dwelling on the Preview page); confirm the
screen’s own footer text still reads Applying… then Theme applied/
Apply again correctly across the transaction, never stuck on a stale
Apply; if prerendered=false still occurs, its own reason= field
states why directly. Closeout audit (2026-09-28): this recheck was run
— it is task group 10’s own grounding comment above (board re-check of
task 9, master 644cd061, installed n44hk9js...): a matched
pre-render took 161ms touch-up-to-commit (target ~30ms), and the
double-prerender symptom was still present, ~154ms apart, for the same
generation. Ticked per the same “recheck ran and reported” convention
as 7.4/7.6/8.6 above: the result was short of target and the
double-prerender symptom was not yet fixed, which is exactly what
motivated task group 10’s tap-to-apply redesign (10.4 root-causes the
double-prerender to the removed Preview page’s async still-image
decode). The footer-text wording check was superseded by 10.2’s removal
of the Apply/Cancel footer entirely, not separately confirmed here.Proof for 9.1-9.4: the tests named above, all passing on this host (9.1’s own regression test independently confirmed to fail against the pre-fix code); proof for 9.5 is the reserved board, not run here.
theme_ui.rs rewritten: ThemePage::Preview removed (only
Controls/List remain — the theme carousel, the active theme’s own
background carousel below it, and a plain “Current theme”/“Current
background” label under whichever slice of each is centred and durably
active, all on one page). A new Desired/ThemeView::advance state
machine (desired, private-but-pub-for-struct-update, same convention
as prepare_ahead_watch) coalesces rapid taps: a fresh tap always
overwrites desired; advance() submits the next step toward it only
when nothing is already in flight; a reply that no longer matches
desired is discarded, and the caller’s own follow-up advance() call
immediately moves on to whatever is now desired — bounding in-flight
work to one request, with the documented tradeoff that a second rapid
tap’s own visible effect is bounded by the first tap’s own in-flight
round trip, not instantaneous (proven directly:
rapid_taps_across_themes_coalesce_onto_the_last_one). New ThemeView:: tap_theme/tap_background replace preview_request/background_request/
apply_request; ThemeIntent::Apply and ThemeView::selection_error/
selection_failed are removed. The original implementation incorrectly
sent a background selection directly to Activate with the previous
background’s generation. Task 16 corrects this: both theme and background
taps prepare the target selection first, then activate its generation. New known_generations: HashMap<String, String>
remembers a warm-up reply’s own (theme_id, generation) (via
record_known_generation, wired from main.rs’s theme_reply on a
prepare_ahead_reply hit) so the pre-render trigger (10.3) can target a
centred-but-not-tapped theme without its own fresh round trip. New
ThemeView::applying_theme_index/applying_background_index drive a
brief, in-place busy spinner on the tapped slice (render.rs:: paint_carousel’s existing busy: Option<usize> parameter, unchanged)
instead of blocking the carousel. Verify with cargo test --offline --lib theme_ui::tests (24 tests, all passing, including tap-apply of a
cold theme, tap-apply of the already-active theme, background tap-apply,
the video/already-selected background no-ops, rapid-tap coalescing, and
rollback-on-failure with a visible error).render.rs’s paint_theme_chooser merges the old List and
Preview branches into one: the theme carousel, its “Current theme”/
origin label, the “Backgrounds” heading, the background carousel, its
own “Current background”/“Tap to apply” label, then one pending/error/
message line — all on the fixed layout theme_ui::THEME_CAROUSEL_TOP
(moved from 204.0 to 132.0) and BACKGROUND_CAROUSEL_TOP (now a
const-expr THEME_CAROUSEL_TOP + THEME_GEOMETRY.expanded_h + 100.0 =
872.0, not board-verified for fit/spacing — see this task’s own
evidence). paint_preview_footer_status (the Preview page’s own live
Apply/Cancel footer overlay, task 9.1) and RendererCache::draw’s own
call to it are removed outright: with no Apply button, nothing needs a
second, live paint pass any more — set_theme_view’s own unconditional
invalidate() (task 9.2’s own doc) already forces the ordinary rebuild
path to repaint the busy spinner and pending/error/message line fresh on
every ThemeView change, and the one case that skips a fresh rebuild
(an adopted pre-render) is correct exactly because, at the moment it
is shown, the applied theme already looks done — proven by
a_theme_view_change_after_adopting_still_rebuilds_and_shows_pending
(renamed/re-reasoned from 9.1’s own regression test) and
a_pending_only_theme_view_change_does_not_bump_content_generation
(re-targeted to the one List page, doc updated). The single large
“screen crop” still-image preview (RendererCache::poll_theme_image/
preview_surface, theme_preview_image_pending) is now a deliberate,
documented permanent no-op — both carousels already show their own
thumbnails via ThemeThumbnailCache, so nothing paints a decoded still
any more; ThemeImageWorker/ThemeImageKey and the worker’s own two
tests are kept, unused, as a named follow-up to prune rather than a
silent removal. Verify with cargo test --offline --lib render::tests
(all passing, including the fixed
list_and_background_rows_paint_their_own_thumbnail_once_decoded,
which caught a real bug this task introduced and fixed in the same
commit: the merged poll_theme_thumbnails match arm used to return
early when chooser.list was None, skipping the background carousel’s
own thumbnail requests whenever its own detail loaded without a list —
the two are now requested independently).main.rs’s touch-down/motion/up/tick handlers no longer branch
on ThemePage::List/Preview to pick a carousel: both carousels are
probed independently now that both are visible at once —
Carousel::down/motion/tick are called unconditionally (each is
keyed by its own armed contact.id internally, safe to call on both;
tick has no touch-ownership concept at all and always advances both),
and Carousel::up is tried on the theme carousel first, falling
through to the background carousel only on None (a touch id it never
armed), which correctly finds whichever one, if either, owns a given
touch. theme_reply now compares theme_position/background_position
before and after accept() to decide which physics carousel (if
either) to re-index, instead of branching on page — precise, since
only accept()’s own List/settling-Preview handling ever changes those
fields, never a concurrent drag. The pre-render trigger (task 8.3) is
retargeted from the removed Preview page’s own loaded candidate to the
theme carousel’s own centred candidate on the List page, using
known_generations (10.1) rather than a fresh Preview round trip, so
pre-rendering the very next likely tap-apply never itself costs a round
trip. show_theme_optimistically gained per-stage ms= instrumentation
(optimistic-apply stage adopt_ms=... wallpaper_ms=... overlay_ms=... flush_ms=..., logged alongside the existing summary line) — the
coordinator’s own ask, board evidence 2026-09-28: a matched
pre-render still took 161ms touch-up-to-commit, target ~30ms. This
instrumentation is coarse (one line per draw_wallpaper/draw call,
since attach/damage/wl_surface::commit all happen inside those calls
and are not separately timed); a finer breakdown inside draw/
draw_wallpaper themselves, and the wallpaper-buffer-attach
optimization the same board evidence asked for (pre-build the actual
wl_buffer at prepare time so adopting is attach-only, no pixel copy),
are not attempted this task — named as deferred follow-up work in
this task’s own evidence doc, since implementing and tuning either
without a way to measure them on the actual board (this task did not
touch the board) risks a change that looks right in a diff and is
wrong, or merely neutral, in practice. Verify with cargo test --offline
(route_tests, 14 tests, unchanged and passing — should_apply_ optimistically/optimistic_apply_due/may_reuse_optimistic_frame/
prerendered_overlay_matches are pure functions this task did not
touch, confirming the optimistic-apply/pre-render machinery’s own
correctness is intact under the new single-page model).644cd061 (before this
task), the Preview page’s own RendererCache::poll_theme_image was
actively decoding the selected background’s “screen crop” still image
asynchronously; that decode completing bumps content_generation (its
own changed branch) independently of theme_view_cache_key_differs
(task 9.2’s fix only excludes ThemeView fields, not this separate
decode-completion signal) — a ~150ms async decode completing shortly
after the Preview page loads exactly matches the reported ~154ms gap
and a “computed twice for the same generation” symptom (the second
compute reacting to the image arriving, not a fresh tap). This task’s
own 10.2 makes poll_theme_image a permanent no-op (nothing paints a
decoded still any more, both carousels use ThemeThumbnailCache
instead), which removes this specific trigger structurally: there is no
longer an asynchronous decode running that could bump content_ generation a second time while a person dwells on an unchanged
candidate. This is reasoned from the code, not re-verified against
fresh board evidence this session (the reserved board was not used, per
this task’s own constraint); 10.6’s board re-check is where that gets
confirmed or refuted.specs/ runtime/shell-themes/spec.md (this change’s own delta — the capability
has not been archived into openspec/specs/ yet, so every requirement
here, including this one, is still ADDED), with the user’s verbatim
decision as its grounding, and lightly reworded “A warm Apply shows…”
to note that “Apply tap” now means a tap on either carousel’s own
centred slice, not a since-removed button — the mechanism that
requirement describes is unchanged. openspec validate the-shell-swaps-themes-without-a-python-stall --strict passes.tests/rust_theme_chooser_qemu.py rewritten for the one-page
flow: opens the chooser, waits for the active theme’s own detail to
auto-load (no tap needed), browses the theme carousel by drag and by a
side-slice recentre-tap (still never applies), confirms a warmed theme
applies on a single centred tap with no further tap (screen repaints,
exactly one activate for it, --expected-generation correct),
browses and tap-applies a background of that theme directly (activate
with --background, and specifically asserts no preview call was
needed for it), then proves rapid-tap coalescing: THEME_COMMAND sleeps
1.5s before answering a preview call for one designated theme
(K230_TEST_THEME_SLOW_ID), giving a reliable window to tap a
different theme while the first is in flight; asserts the superseded
theme’s own request was genuinely sent but never activates, and the
second tap’s theme does. Written and syntax-checked; not yet run to a
real result (10.6b).sway-unwrapped, built after finding
.#nixosConfigurations.k230.pkgs.sway-unwrapped is plain upstream
sway without the card_shell commands this harness needs — the
correct binary is a side effect of .#card-shell, at its own
swaybar/swaymsg/swaynag symlink target). Both attempts failed at
k230-shell-rust: route timed out (main.rs::request’s pre-existing
500ms socket-round-trip deadline for the --surface helper
invocation) before reaching any theme-chooser-specific code —
confirmed via git diff 80817e3d..HEAD -- main.rs to be outside this
task’s own diff, and the shared host was running several other
concurrent agents’ own builds and at least one other qemu-riscv64- static session at the same time, so contention rather than a code
regression is the leading explanation. Not chased further by loosening
a timeout this task does not own. See this task’s own evidence doc for
the full account. Closeout audit (2026-09-28): PASS under QEMU with a
synthetic backend — python3 tests/rust_theme_chooser_qemu.py --sway <sway-unwrapped from .#card-shell's swaymsg target> --rust <.#handheld-shell-rust> --output /tmp/q106, recorded with exact store paths, the synthetic command
log and capture hashes in docs/evidence/theme-picker/tap-to-apply-qemu/README.md.
QEMU proof only; panel fit and on-glass behaviour remain 10.7/14.4.optimistic-apply stage adopt_ms=... wallpaper_ms=... overlay_ms=... flush_ms=... for a warm tap-apply, and whether the
total (optimistic-apply shown ms=...) has moved from the 161ms board
baseline toward the ~30ms target now that the double-pre-render trigger
is structurally removed (10.4); confirm the new
THEME_CAROUSEL_TOP/BACKGROUND_CAROUSEL_TOP layout (10.2) actually
fits the 1232px panel without clipping or crowding. Needs the reserved
board; not run by this task.
Re-checked 2026-10-12, two cold-process trials (injected taps, journal, native
grim captures; not a camera view of the glass): both bundled dark (catppuccin)
and light (catppuccin-latte) read correctly and the picker fits the 568x1232 panel
with the “Theme applied” line about 27 px above the bottom edge, not clipped.
optimistic-apply shown ms was 201.2/204.4 (light) and 156.1/163.2 (dark);
stage adopt/wallpaper/overlay/flush for the warm taps ranged 0.4-0.5 /
2.6-11.5 / 55-86 / 0-0.9 ms. It has not moved from the 161 ms baseline toward
~30 ms; reason on every tap: prerendered=false reason=content-changed, so the
browse-time pre-render is discarded; the frame appears about 510 to 570 ms after
touch-up because a tap-time preview (255 to 288 ms) runs first. The original dark
generation was restored (hash identical before and after). Evidence:
docs/evidence/theme-picker/board-session-2026-10-12/README.md (section “Task 10.7 and 6.6”).Proof for 10.1-10.3, 10.5, 10.6a: the tests and commands named above, all passing/PASS on this host; proof for 10.4 is code review, named as such, not board evidence; 10.6b and 10.7 are not run/not obtained this task. The wallpaper-buffer-attach optimization and a finer per-stage attach/damage/commit breakdown (both asked for alongside 10.3) are deferred follow-up work, not attempted this task — see 10.3’s own doc.
Keep this change open (or split at review time into an explicit successor
per AGENTS.md) until 2.3, 3.4, 6.6, and 10.7 have results; 3.3b is named
here so it is not silently dropped or claimed done without a board result.
Task 5.4’s board result is recorded above (board-chooser-2026-09-25.md).
9.5 was resolved above (its board recheck already ran, as task group 10’s
own grounding comment).
Closeout audit (2026-09-28): the note above pre-dates task groups 11-16.
The full current gate list after this audit is: 2.3 (board), 3.3b
(host-doable, deliberately not attempted here — touches a load-bearing
two-phase-transaction return contract; see 3.3b’s own text), 3.4 (board,
depends on 3.3b), 6.6 (board), 10.7 (board/panel),
11.3 (board, depends on task 13’s harness), 13.1-13.3 (host-doable but a
substantial new profiling/gating harness, not attempted in this audit —
see docs/closeout/themes-audit.md), 13.4 (board, depends on 13.1-13.3),
14.4 (real-finger acceptance specifically, not injected), 15.2 (partial;
compositor-stage coverage is host-doable, the physical capture is board),
15.3 (board). 7.8, 8.6 and 9.5 are now ticked above with citations to
existing board runs already quoted as grounding comments in this file.
The user reports slow swiping and apparently repeated theme loading on the
installed 926c7a61 Rust shell. Source review identifies an over-capacity
combined thumbnail request set and speculative main-thread pre-render during
motion; neither is yet a measured explanation of this board report.
cargo test --offline --manifest-path nix/rust-shell-client/Cargo.toml --lib theme_picker
and cargo test --offline --manifest-path nix/rust-shell-client/Cargo.toml --lib theme_thumbnails.cargo test --offline --manifest-path nix/rust-shell-client/Cargo.toml --bin k230-shell-rust theme_prerender.tools/theme-swap-jank.py capture for this gesture
sequence if necessary; its current activate-only run is not swipe proof.
Commit the result before checking this task. Physical proof remains pending;
host tests alone do not satisfy it. Closeout audit (2026-09-28): the one
paired attempt at this run is docs/evidence/theme-picker/working-set/ README.md, which is explicit that it is “not a completed picker
performance result” — the new run’s own background row never loaded
(“Loading backgrounds” stuck), confounding the opening/memory comparison,
and warm swipes were still slow (125-132ms median, worse than the old
run’s max). Needs a fresh reserved-board run repeating this exact
workload with the store-relocation lookup bug (task 12.1) already fixed
underneath it, which it was not for that attempt.
2026-10-12 board result, task stays open: the fresh reserved-board run
with 12.1 underneath was performed as task 13.4 (docs/evidence/theme-picker/board-session-2026-10-12/README.md). Both rows
resolved (after applying a theme: a pointer-less board never loads the background
row), the generation stayed unchanged, repeated loading settled and warm swipes
improved in median, but the candidate uses about +6 MiB more Rust RSS (+8%) at the
end of the warm idle window than the repaired baseline in all three recorder-off
pairs, warm-swipe p95 did not improve, and repaint still dominates. Checking this
box needs the memory increase explained or removed and the next correction named
under 13.4 measured.
2026-10-12 (b) board result (docs/evidence/theme-picker/board-session-2026-10-12b/README.md, “Task 11.3”; candidate 3m65ag9z against the
same repaired baseline 8cik, three recorder-off pairs in alternating order, all
gates passed): warm theme commit gap median 140 to 63 ms and p95 173 to 89 ms,
background 84 to 38 ms, warm commits 59 to 97, Rust CPU in warm theme swipes 79 to
57%, idle unchanged. Memory: end-of-warm-idle RSS median +2.0 MiB (pairs +2.0, -2.3,
+11.0; the +11 pair is a low baseline run, the candidate ends at 80-87 MiB in all
three), and with the picker closed the candidate is below the baseline. The board’s
picker-memory log attributes the open-picker difference to the 2.0 MiB card cache
and 1.5 MiB scratch surfaces, released when the picker closes. The 13.4 corrections
are measured: row-local thumbnail damage, the cached slice repaint, and the RSS
attribution.
Installed as system fm8gk6xi… (ordinary boot 34d77814).Host proof for 11.1–11.2 (2026-09-26): --lib theme_picker passed 1
regression; --lib theme_thumbnails passed 16 tests; the additional narrow
--lib thumbnail filter passed 18 tests including the two existing renderer
checks; --bin k230-shell-rust theme_prerender passed 1 motion-gate test.
All used the offline Cargo command above. The 40-theme/40-background fixture
has old demand of 68 variants; the 568-pixel viewport admits 24, submits each
once, then performs 200 stationary polls without another request. It also
settles after both rows move and after a wider viewport exercises admission.
Additional fixtures cover stale in-flight replies, preservation of an oldest
visible resident, and actual byte-budget eviction. These are deterministic
host cache/channel tests, not timing or physical swipe evidence. No Nix build
or board use was performed for these tasks; 11.3 remains open.
python3 -m unittest discover -s tests -p test_theme_catalog.py.Board proof for 12.2: docs/evidence/theme-picker/store-relocation/README.md
now records verified normal installation, the saved theme centered, a populated
background row responding to a drag, and the repeated 70.93-second browse
measurement with unchanged generation. The initial image matches the earlier
one-shot capture exactly. Both idle windows have zero redraws; warm swipe
commit gaps remain slow (median 141 ms), so task 11.3 stays open.
Host proof for 12.1 (2026-09-27): the exact unittest discovery command above
passes 21 tests. Six added regressions cover an identical source relocated to
a new store package after the old object is removed, unchanged active pointer
and report, real list-to-preview background discovery without activation,
changed source rejection, same-name user origin, ambiguous/malformed identity,
and exact-path priority without hashing. The board confirmed a null active
catalog ID with a preserved generation before this fix; native frames showed
Loading backgrounds. The installed board proof above, rather than these host tests, closes 12.2.
The partial paired evidence is committed in
docs/evidence/theme-picker/working-set/README.md. Task 11.3 remains open:
held-touch pre-rendering stopped, but warm swipe improvement was not proved,
and the second capture lacked the active background row. None of the tasks
below is complete merely because that partial evidence or this plan landed.
tools/theme-picker-profile.py
with host fixtures in tests/test_theme_picker_profile.py; preserve the
historical capture unchanged. Require resolved/visually reviewed theme and
background rows, catalog counts, exact source/runtime identities, matching
active generation, geometry and background playback state before treating
runs as comparable. Record whether each opening is first-observed,
verified process-cold, or warm; do not infer disk-cold or delete user cache.
Capture both carousel swipes and 15-second idle windows without activation,
using the verified virtual device and existing single-process injector.
Planned host proof: python3 -m unittest discover -s tests -p test_theme_picker_profile.py.
Fixtures must reject missing-row comparisons, PID reuse and generation
changes, and must not count idle intervals or callback/commit mixtures as
swipe frame gaps. Keep only allowlisted public fields and hashed private
generation identities.
Done 2026-10-11: tools/theme-picker-profile.py (stdlib only; subcommands
validate, preflight, capture, reduce, compare) and
tests/test_theme_picker_profile.py landed. python3 -m unittest discover -s tests -p test_theme_picker_profile.py
passes 31 tests (host fixtures only; no board, injected event or camera evidence).
Fixtures cover missing/unreviewed rows, store-identity and generation
mismatches, PID reuse, Rust-clock restarts, generation change, activation,
process-cold verification, idle/callback/wallpaper events excluded from swipe
gaps, private-field allowlisting, and comparison gating. Board capture and
the physical comparison remain task 13.4.cargo test --offline --manifest-path nix/rust-shell-client/Cargo.toml --lib theme_picker.
Compare instrumentation-on/off overhead on the board before interpreting
detailed timings; no native screencopy runs inside the timing pass.
Host/source part done 2026-10-12: nix/rust-shell-client/src/runtime_trace.rs
keeps fixed-name counters (count, wall, thread CPU, max wall) for 17 kinds
bucketed by rest/held/moving gesture phase with a bounded phase log,
still default-off (K230_TRACE_PATH; K230_TRACE_COUNTERS_ONLY=1 drops the
event ring); main.rs/theme_thumbnails.rs add speculative completion and
thumbnail request/completion counts. tools/theme-picker-profile.py adds
opt-in per-thread CPU with start-time identity, RSS, helper cgroup CPU,
verified instrumentation mode, reduce --rust-trace and an overhead OFF ON
comparison; 19 new host fixtures cover overlapping phases and
counter/PID/thread-identity discontinuities. Proved: cargo test --offline --manifest-path nix/rust-shell-client/Cargo.toml --lib theme_picker and
python3 -m unittest discover -s tests -p test_theme_picker_profile.py
(50 tests). NOT proved: the on/off overhead comparison on the board, which
is the first step of task 13.4’s session; no board number or detailed timing
is claimed here. Operator notes are in docs/runtime-tracing.md.
Board overhead measured 2026-10-12 (injected, installed ybpn ELF): three
recorder-off, three counters-only and one trace run of the same workload give
about +0.08 percentage points of Rust CPU when idle and about +3 points in
background swipes, no change in background commit-gap median, no memory increase,
and theme-row differences inside the recorder-off run-to-run spread. Judged small
enough to interpret counters, with that caveat. See docs/evidence/theme-picker/board-session-2026-10-12/README.md
(section “Task 13.2 / 13.4: observer cost first”).cargo test --offline --manifest-path nix/rust-shell-client/Cargo.toml --lib prepare_ahead
and cargo test --offline --manifest-path nix/rust-shell-client/Cargo.toml --bin k230-shell-rust speculative_theme_motion.
Completed 2026-10-10: the motion gate already landed in f4bf213e after
the historical audit below. Closed its remaining center-priority gap: queued
neighbors now wait for the latest settled center’s full dwell. Both named
commands pass (7 preparation cases and a six-combination row-motion regression),
along with 28 theme-UI and 22 route checks; nix build .#handheld-shell-rust
passes under the sole build lock. A test-only old-source control fails at the
prematurely admitted neighbor. Commands, hashes, source/artifact identities,
host output, cross-build and verified extended retention are committed in
docs/evidence/theme-picker/admission-closeout-2026-10-10/README.md.
Host/cross-build only; tasks 13.1/13.2/13.4 and physical acceptance remain open.python3 /run/theme-picker-profile.py capture --plan /run/picker-plan.json --output /run/picker-profile.json;
the private plan supplies the verified device, runtime identities and row
preconditions, and each run uses a unique output. Commit sanitized results,
exact invocation and observer-cost limits. Run the 13.2 instrumentation
off/on overhead pair (overhead OFF ON, same build, same workload, no
native screencopy) first; interpret detailed counters only if it is small. If warm swipes or memory regress,
or repaint still dominates, document the next measured correction and keep
11.3 open; a host regression or scheduling fix alone does not close it.
Performed 2026-10-12 (injected input, journal and Rust-trace timing, native
grim stills and sampled frames; no finger, no camera): overhead pair first,
then three matched alternating-order pairs of 8cik against the installed
candidate in both recorder-off and trace mode (gates passed in all six pairs),
with identical runtime references, a fixed catppuccin generation unchanged in
every sample, 22 themes and 4 backgrounds, and both rows responding in native
stills. Result: the candidate improves cadence and CPU (warm theme commit-gap
median 137.5 to 114 ms, background 87 to 39 ms, render per frame 129 to 99 ms and
62 to 3 ms, full scene rebuilds down 69 to 100%) but regresses memory
(+6.0 MiB at the end of warm idle in all three recorder-off pairs), warm-swipe p95
does not improve (173 to 160 ms), the theme row still repaints at about 93 ms per
frame, and 23 to 33 full scene rebuilds still occur while moving. No speculative
admission starts during motion in the candidate (0 of 36 in held/moving);
admitted rest-time work is still in flight at the next touch. Next measured
corrections (named, not done): row-local damage for thumbnail completion instead of
a full scene rebuild; cut the theme-row repaint cost; attribute the RSS growth
(UNVERIFIED cause) before changing the neighbour queue. 11.3 stays open.
Evidence, commands, runtime identities, observer cost and limits: docs/evidence/theme-picker/board-session-2026-10-12/README.md.Closeout audit (2026-09-28): all of 13.1-13.4 are genuinely unimplemented,
not merely unchecked. tools/theme-picker-profile.py and
tests/test_theme_picker_profile.py (13.1) do not exist anywhere in the
tree; cargo test --lib prepare_ahead and --bin k230-shell-rust speculative_theme_motion (13.3) name targets that do not exist (grep -rn speculative_theme_motion nix/rust-shell-client/ finds nothing). This is
af492080’s own plan (task groups 13-16 of this file), landed as a plan
commit only; 16 was implemented and closed (see below), but 13 was not
started. This is real remaining scope for this change, not a board gate on
already-written code — keep the whole group open.
cargo test --offline --manifest-path nix/rust-shell-client/Cargo.toml --lib theme_carousel.cwfx0amr…
(Rust k2z9z61k…): “it’s really janky moving between theme cards and it
shouldn’t be”. Not accepted. This matches the board session’s measured theme-row repaint
(about 93 ms per frame) and the full scene rebuilds during motion
(docs/evidence/theme-picker/board-session-2026-10-12/README.md).
Sprite repaint, 2026-10-12 (4d17b3c5, Rust b0yyyda8…): with
injected theme-row swipes, the moving-phase row repaint fell from about
80 ms CPU / 100 ms wall to 30 ms / 43 ms. Frames during the same swipes
rose from about 51 to 91, and no full rebuilds occurred mid-swipe
(docs/evidence/theme-picker/row-sprites-2026-10-12/README.md). After
using it on the panel, the operator wrote “it’s good to go land it”. That
accepts the feel for landing. Accepted 2026-10-12 on installed system
rav09qp6… (Rust b0yyyda8…): asked whether both rows follow the finger
without exaggerated travel or a backlog after it stops, the operator replied
“14.4 they do, is good”. This acceptance does not cover task 18.4’s curve
properties or the 11.3/13 comparison.Task 14.1 host proof: the exact --lib theme_carousel command passed 13
geometry/physics tests, including rendered-center tracking for both rows,
integer/fractional starts, reversals, held ticks, stale release velocity and
screen-space fling continuity. --bin k230-shell-rust passed 19 route tests.
Task 14.2: the matching full system built, and the guarded physical-board
trial processed all 20 injected motion samples per phase with 2–4 commits
during contact/hold. See docs/evidence/theme-picker/finger-tracking/README.md
for commands, identities, geometry captures and timing limits. Task 14.3’s
qualified candidate was installed with verified backup/profile/boot hashes,
then normally rebooted: all four shell services active, no failed units, and
current/booted/profile identities all match 7hhr1fp…. Task 14.4’s
real-finger acceptance remains open.
python3 -m unittest discover -s tests -p 'test_runtime_trace*.py' and
cargo test --offline --manifest-path nix/rust-shell-client/Cargo.toml --lib theme_picker.the-theme-swap-is-profiled-on-the-board
(task 2.1). Not performed here; no result is claimed.the-theme-swap-is-profiled-on-the-board
(task 2.2). Not performed here; no result is claimed.Task 15.1 proof: the two named host commands pass (9 Python and 3 Rust
tests), plus 19 binary route tests and 54 helper/catalog/transaction tests.
Both normal/coherent system closures cross-built. The first physical capture
joined four helper requests and 36 presented frames without trace loss; see
docs/evidence/theme-picker/runtime-trace/README.md. This leaves 15.2/15.3
and the broader task 13 profiling/overhead gates open.
Task 15.2 partial physical proof: nix build .#runtime-perf --cores 8
passed, and the physical board recorded 697 CPU-clock samples with matching
PID/TID and unchanged generation. Reviewed CPU stack and flat hotspot SVGs
are in docs/evidence/theme-picker/cpu-profile/README.md. Unknown callers
appear in 648 samples; compositor stage spans, scheduler correlation and
complete stack qualification remain open. This does not close 15.2/15.3.
cargo test --offline --manifest-path nix/rust-shell-client/Cargo.toml --lib theme_ui
and python3 -m unittest tests.test_theme_catalog. Correct the QEMU fixture
so different background choices have different generations.Task 16.1/16.2 proof: 24 Rust and 21 Python checks passed; the corrected
paired Sway/Rust QEMU fixture passed. The physical board applied both still
backgrounds through injected picker taps; native Home images and the
reopened picker agree. A shell/helper restart retained the selection.
docs/evidence/theme-picker/background-selection/README.md records reviewed
captures, generation identities and the successful persistent installation.
Real-finger acceptance and a normal reboot of this image are not claimed.
Task 16.3: source, physical evidence and image installation are on master.
Pages run 36298384207 passed build and deployment at d937b8cd; the
published evidence page and work card were checked over HTTP, including all
five newly discovered screenshots. URL:
https://knewter.github.io/tdisplay-k230/evidence/docs-evidence-theme-picker-background-selection-readme-md/
The archive override and missing screenshot inventory entries that blocked
the earlier runs were corrected; wider tasks 11/13/14/15 remain open.
cargo test --offline --manifest-path nix/rust-shell-client/Cargo.toml --lib picker_row
(full-render pixel comparisons and fallback coverage), --lib prepare_ahead,
and --bin k230-shell-rust speculative_theme_motion; build the Rust target.ybpn, source
faae7298, against repaired baseline 8cik): matched injected swipes on both
rows, three alternating-order pairs in recorder-off and trace mode, independent
restoration timer on every run, generation and process identities unchanged,
CPU (recorder-off), render and presentation gaps (trace) reported separately,
native stills outside every timing pass. Row repaint cut full scene rebuilds by
69 to 100% and background-row frames from about 87 to 39 ms median; theme-row
repaint is still about 93 ms per frame. Evidence: docs/evidence/theme-picker/board-session-2026-10-12/README.md.
Not done by this commit (coordinator): push, and the check of the actual site
deployment named above. 14.4 and the wider 13/15 gates remain open.Task 17.1 baseline: docs/evidence/theme-picker/row-repaint/README.md records
resolved two-row physical traces and the separate 1,490-sample CPU capture.
Caller and observer limits remain open; the user still reports jank.
openspec validate the-shell-swaps-themes-without-a-python-stall --strict.cargo test --offline --manifest-path nix/rust-shell-client/Cargo.toml --lib theme_carousel.
Completed 2026-10-12 (host only): release motion now integrates the
full elapsed time in closed form (exponential coast, k = -ln(0.88)/16 ms).
Hand-over times inside a tick are exact for both the coast threshold and
the catalogue bounds. The coast passes its exact velocity to a critically
damped (omega = 22/s) settle, and a new touch catches the drawn position.
The named command passes 21 tests. They cover 8/16/33/100/200 ms cadences
against a 1 ms reference, seven slow/flick/bound releases, a stale hold,
a reversal, a long hold followed by release, and interruption. Geometry
is shared by both rows. The board trial (18.3) and finger acceptance (18.4)
remain open.si9vd
against the installed candidate: 80 injected gestures (flick, slow, hold-release,
reversal, interrupt; both rows; two repetitions in each of two alternating runs
per build and row), generation and identities unchanged throughout, native stills
after every settle. The shell emits no per-frame carousel position or velocity,
so no position or velocity plot is published (a replay through the host model
would be a model, not a board result). Published instead: injected finger path
against frame-commit timelines, release-to-last-commit times, and the settled item
per gesture (docs/evidence/theme-picker/board-session-2026-10-12/README.md, section “Task 18.3”). Closing needs a bounded
per-frame position/velocity record in the Rust trace (not added in this session) and
the matching curves.
Curves published 2026-10-12 (b) (docs/evidence/theme-picker/board-session-2026-10-12b/README.md, “Task 18.3”): the shell now records one
carousel trace event per committed frame (position, velocity and motion phase of
both rows). Four trace-mode runs of the same five injected programs, two repetitions
each, on candidate 3m65ag9z, with generation and identities unchanged and no events
dropped. Board-committed position and velocity curves for all 40 gestures are in
18.3/position-curves.png and 18.3/velocity-curves.png: monotonic approach and no
overshoot in every gesture, and repeatable final items.
The measured candidate was installed through the guarded coherent installer
(system fm8gk6xi…); baselines si9vd and 8cik stay pinned on the board.fm8gk6xi… (Rust 3m65ag9z…),
after being asked about tracking, flick distance, settling and interruption on
both rows: “yeah it’s fast go”. This is a report of improvement, not an answer
on the four properties, so the task stays open.
Operator finger acceptance 2026-10-12 on installed system 298a2bf6…
(Rust hl4bca4g…), after being asked for tracking, flick distance (about 8
items), settling and interruption on both rows: “it’s great now i tried it all
it’s good”. Real-glass operator report; no camera recording or per-property
measurement was taken for it.Task 17.2 source/build and the first task 17.3 injected pair: docs/evidence/theme-picker/row-repaint/pair/README.md. Task 17.3 remains open for combined-source installation and deployment; real-finger acceptance is separate.
2026-10-01 persistent-install reconciliation: the combined coherent system
/nix/store/p1a1hz9n8s4g8qyr55ffl3dzbnjgqwr8-nixos-system-nixos-26.11.20260919.20b1ddd
was selected persistently and survived an ordinary reboot; the running Rust
client is
/nix/store/3hy6h165ii649z6vjzjd36jwg16d37rc-k230-shell-rust-riscv64-unknown-linux-gnu-0.1.0/bin/k230-shell-rust.
The saved appearance generation and report hash match before and after boot.
See docs/evidence/boot-verification/coherent-ordinary-boot/README.md and
postboot.json. This verifies installation, ordinary boot and remembered
appearance for the existing home. It does not complete 17.3: the existing
matched pair measured candidate source 42e22d4353e35d9c4f6367ed5b159c80b489ec5d
and binary /nix/store/2mprr7lqh4hznwz9z1zmv7vamf5nbnna-k230-shell-rust-riscv64-unknown-linux-gnu-0.1.0,
whereas the installed combined source is 5bb67db128210f830dab4de0d20a4b0eca13c578.
Between those identities main.rs and render.rs changed, including picker
carousel painting, so the older pair cannot establish the current binary’s
matched swipe cost. A matched baseline/current-candidate pair is still needed;
do not infer it from the normal reboot or unchanged appearance. The evidence
inventory and source comparison are recorded in
docs/evidence/theme-picker/closeout-2026-10-01/README.md. Tasks 14.4 (real
finger), 10.7 (picker panel/tap timing), and wider 13/15 gates remain separate.
The 2026-10-12 board session found the Backgrounds row stuck on “Loading
backgrounds” whenever k230-theme list reports active: null, the normal
state of a board that has never applied a theme (docs/evidence/theme-picker/board-session-2026-10-12/README.md).
The chooser only requested detail for a reported active theme, so no
request was ever sent.
K230_THEME_DEFAULT_GENERATION’s
report.json source; the first slice when it is unknown) and load its
backgrounds without marking it “Current theme”. Tapping it applies it
durably. Proof: cargo test --offline --manifest-path nix/rust-shell-client/Cargo.toml --lib theme_ui.
Done 2026-10-12 (host only): 33 tests pass, including five new
regressions: default centred and its backgrounds loaded, unknown default
falls back to the first slice, a user theme sharing the name is not used,
a tap applies durably, and the report parser. The full suite passes
except the existing drawer_568x1232_matches_the_committed_evidence_exactly.k230-theme list must still report
active: null.
Done 2026-10-12 (injected tap, native capture): installed system
cwfx0amr… (Rust k2z9z61k…), ordinary boot a563b9fb. The picker centred
on built-in catppuccin, and Backgrounds showed Totoro instead of “Loading
backgrounds”. k230-theme list still reported active: null. Evidence:
docs/evidence/theme-picker/default-backgrounds-2026-10-12/README.md.
No finger observation.Grounding: user decision of 2026-09-25 (comment above); nix/rust-shell-client/src/theme_ui.rs and its unit tests; board apply trials on installed system 298a2bf6 in docs/evidence/theme-picker/board-session-2026-10-12b/README.md (“Task 6.6” and “Install of candidate 8”): a centre tap activates directly, with no preview request. Operator acceptance 2026-10-12: “it’s great now i tried it all it’s good”. Taps in those trials were injected.
The theme chooser SHALL present the theme carousel and the active theme’s
own background carousel on one page, with no separate preview page and no
Apply/Cancel footer. A tap on a carousel’s own already-centred slice SHALL
apply that theme or background immediately, through the same
preview(learn the generation)/activate request pair an explicit Apply
button previously sent, chained automatically with no further tap needed.
Dragging or tapping an off-centre slice SHALL only recentre the carousel on
that slice; it SHALL NOT itself apply anything. Rapid taps across different
targets SHALL coalesce onto the most recently tapped one: at most one
request for this chooser SHALL be in flight at a time, a reply that no
longer matches the most recently tapped target SHALL be discarded rather
than shown or applied, and the chooser SHALL move on to the now-desired
target as soon as that discarded reply is recognised, with no queue of
stale, superseded activations ever building up or later firing.
preview/activate pair, and the existing optimistic-show path when the
receiver already has it prepared), with no separate confirm or Apply stepactivate request is sentGrounding: docs/evidence/omarchy-themes/background-decode-cache-qemu/README.md for the removed cost; docs/evidence/omarchy-themes/theme-swap-jank/README.md and tests/test_theme_helper_daemon.py; board journals in docs/evidence/theme-picker/board-session-2026-10-12b/README.md show each Apply handled by the resident helperd (THEME_TIMING helperd activate).
When the persistent theme helper (theme-helper.service) is running, a
k230-theme preview or k230-theme activate invocation SHALL NOT import
the theme-activation module chain (theme_activate, theme_transaction,
theme_preferences, keyboard_appearance) in its own process; that
invocation SHALL instead delegate the request to the already-warm helper
process over a private, owner-only Unix socket and print exactly the
answer that helper computed. The invocation SHALL fall back to the
unmodified, pre-existing in-process behavior, with no difference in
accepted flags, output shape, or exit codes, whenever the helper socket is
absent, refuses the connection, or does not answer within a bounded
timeout.
theme-helper.service is active and a person’s chooser calls
k230-theme preview <id> then k230-theme activate <id> --expected-generation <g>theme-helper.service is stopped, crashed, or mid-restartk230-theme preview/k230-theme activate still complete
correctly, using the same two-phase prepare/commit/rollback protocol and
producing the same result shape as before this requirement existedGrounding: tests/background_decode_module.rs and tests/test_card_shell_appearance.py; board journals in docs/evidence/theme-picker/board-session-2026-10-12b/README.md show activate_generation ... prepare_phase=0.1-3.9ms warm=2 targets=2 and appearance-commit-accepted reused=optimistic.
Each of the two appearance receivers (the Rust chooser/wallpaper client and
the Sway/card-shell compositor) SHALL retain, in memory, the decoded
wallpaper or built gradient for at least the most recently prepared
candidate generations (bounded, not unbounded), so that a commit for any
of those candidates adopts the already-prepared result — a buffer/pointer
swap plus redraw — rather than re-decoding a wallpaper or repainting a
gradient. A candidate that was never prepared, or whose prepared state was
evicted or does not match the commit’s own generation/geometry, SHALL fall
back to the pre-existing inline decode/paint; this requirement never
changes what is rendered, only whether that work is repeated.
commit adopts that retained wallpaper/gradient
without a fresh decode or Cairo paintcommit for A is still a guaranteed in-memory hit,
bounded to a small recent-candidate history rather than a single slotcommit arrives for a generation that was never prepared, or
whose prepared geometry/brush no longer matchesGrounding: nix/rust-shell-client/src/theme_ui.rs unit tests; board cold-open neighbour check in docs/evidence/theme-picker/board-session-2026-10-12/README.md (second theme warm about 0.3 s after the first, not a fresh ~4 s preview).
While the Themes list page is open and its carousel is at rest (no drag, coast, or settle animation in progress) on one theme for a short, bounded dwell time, the chooser SHALL issue a best-effort warm-up request for that theme, bounded to a small number of requests in flight at once, without navigating the chooser or otherwise becoming visible to the person browsing. A theme passed through while the carousel is still moving, or superseded by a different centred theme before its own dwell time elapses, SHALL NOT itself cause a warm-up request.
Grounding: user decision of 2026-09-25 (comment above); board apply trials in docs/evidence/theme-picker/board-session-2026-10-12b/README.md: tap-up to shown frame 27.5-42.2 ms with prerendered=true, ahead of a durable activation of 149-179 ms, including one trial on installed system 298a2bf6. Operator acceptance 2026-10-12: “it’s great now i tried it all it’s good”. Taps were injected.
When an Apply tap’s target generation is already the Rust receiver’s own
prepared snapshot, the chooser SHALL render that appearance — the
wallpaper, and every other Rust-shell surface driven by it — on the very
next frame, without waiting for the durable two-phase commit (still
dispatched, unchanged, and left to settle to completion asynchronously).
This SHALL NOT alter the two-phase protocol’s own acknowledgement contract
in any way: a receiver’s prepared/active bookkeeping, and the “ack only
after a real, flushed frame” rule each receiver’s commit/rollback
handling already applies, remain exactly as before this requirement: the
optimistic render is a side effect additional to that protocol, never a
substitute for its own eventual, authoritative commit or rollback. A
generation that is not already prepared SHALL continue to show the
pre-existing busy/pending state on Apply and SHALL NOT be prepared early
merely to make it eligible for this requirement. When the compositor can be
reached directly, the same already-prepared candidate MAY also be shown
there immediately, on the same advisory, side-effect-only basis (never
altering its own two-phase bookkeeping either); this is a best-effort
optimization, not a correctness requirement in its own right, since the
durable commit’s own real commit/rollback message to the compositor
settles its display correctly regardless of whether this arrives.
active snapshot and every other durable
record (the active pointer, preferences, app appearance) settle to match
exactly what is already on screen, with no further visible changeGrounding: injected board pairs and sprite repaint in docs/evidence/theme-picker/row-sprites-2026-10-12/README.md and docs/evidence/theme-picker/board-session-2026-10-12b/README.md; operator real-finger acceptance 2026-10-12 (“14.4 they do, is good”; “it’s great now i tried it all it’s good” on installed system 298a2bf6). No camera recording was taken.
While a person holds and drags either picker row, the reference preview card’s horizontal center SHALL track their horizontal displacement in surface pixels, subject only to catalog end bounds. Momentum SHALL start only after release; a stationary hold SHALL expire earlier fling velocity. Queued input SHALL be coalesced to its latest position before the next eligible motion repaint.
Grounding: board per-frame position and velocity curves for 40 injected gestures in docs/evidence/theme-picker/board-session-2026-10-12b/README.md (task 18.3: monotonic approach, no overshoot, repeatable final items); operator real-finger acceptance of tracking, flick distance, settling and interruption on both rows, 2026-10-12, on installed system 298a2bf6. No camera recording was taken.
Both picker rows SHALL use actual elapsed time for release motion and SHALL carry screen-space release velocity continuously into centering. A new contact SHALL interrupt motion at the displayed position without a jump. Held movement SHALL remain direct, and settling SHALL not activate a theme or background.
Archived change · Archived
Snapshot 5836ef1d113d · 2026-10-17 08:22 UTC
Closed recordReview the archived record and cited scope
Every board action today goes through the serial console at 115200 baud:
deployment, test triggers and screenshots. That is slow, and it holds the
single port that the boot controller and recovery need. On 2026-10-11 a
temporary, runtime-only sshd (key-only, under /run) made screenshot fetches
and test triggers quick and simple, without taking the serial port. The operator asked for that access to be part of the image.
nix/keys/k230-operator.pub. No private key, address or network
name is committed.system/console: adds a requirement for key-only network login alongside
the serial console.nix/k230.nix (all images built from it, including QEMU), nix/keys/.
SSH host keys are generated on the board at first start and persist in
/etc/ssh.
nix/k230.nix is the base module for every image. It sets root’s password
to empty so that the serial console autologs in. The NixOS firewall is on
(nixos-fw). On 2026-10-11 the installed system had an sshd binary but no
running service, no sshd privilege-separation user and no port open.
services.openssh in the base module. NixOS creates the sshd
user, /var/empty and host keys, and openFirewall opens port 22.PermitRootLogin = "prohibit-password",
PasswordAuthentication = false, KbdInteractiveAuthentication = false.
PermitEmptyPasswords = false is set explicitly, not left to OpenSSH’s default. The empty console
password therefore cannot be used over the network..pub file is committed./run sshd: it disappears at every reboot and
needs a bind-mounted passwd entry and a runtime firewall rule.~/.ssh, can be
dropped from nix/keys/ in a later image.nix/k230.nix with the dedicated key from nix/keys/k230-operator.pub. Host proof: nix eval --json .#nixosConfigurations.k230-mainline-drm-shell.config.services.openssh.settings shows root key-only login with password and keyboard-interactive login off, and nix eval .#nixosConfigurations.k230-mainline-drm-shell.config.networking.firewall.allowedTCPPorts includes 22. Passed 2026-10-11: PermitRootLogin = "prohibit-password"; PasswordAuthentication, KbdInteractiveAuthentication and PermitEmptyPasswords all false; firewall [ 22 ]; the root key file reads the committed ssh-ed25519 key.nix build .#kernelMainlineDrmShellBootFiles. Passed 2026-10-11 at eb6579a8: bundle /nix/store/66ij9hh2gczfh7qcnk40lrw8x16x8irv-k230-coherent-shell-boot-files, system c6qjs04y…; Image, initrd.uimg and the Rust shell are unchanged from the installed build, and the generated sshd.conf-final carries the key-only settings.ssh -i ~/.ssh/k230_board_ed25519 root@<board> (address kept private). Also show that a password-only attempt is refused (ssh -o PubkeyAuthentication=no -o PreferredAuthentications=password,keyboard-interactive root@<board> fails). Hardware proof. Done 2026-10-11 on ordinary boot 8050d551 of system c6qjs04y: key login succeeded, password-only attempt got Permission denied (publickey).; see docs/evidence/console/ssh-installed-2026-10-11/.Grounding: docs/evidence/console/ssh-installed-2026-10-11/README.md: after an ordinary autoboot of system c6qjs04y (boot 8050d551), root logged in with the dedicated key, and a password/keyboard-interactive-only client was refused with Permission denied (publickey). The serial console stayed in use throughout the install.
The system SHALL run an SSH server reachable over the board’s network
connection, admitting root by public key only. It SHALL refuse password,
keyboard-interactive and empty-password logins. The serial console SHALL stay
available as the recovery path.
Archived change · Archived
Snapshot 5836ef1d113d · 2026-10-17 08:22 UTC
Closed recordReview the archived record and cited scope
A person holding the handheld cannot open an app’s window list with a finger. In
the Rust shell the per-app menu (app_actions::AppMenu) opens only on a mouse
right-click (nix/rust-shell-client/src/main.rs, pointer button 0x111). A long
press in the drawer starts the drag-to-Home move instead. So the loading, “No
open windows” and “That window has closed” recovery states added by
the-rust-shell-explains-stale-denied-and-ended-states (archived 2026-10-11)
can be reached only with a mouse. None of that change’s recovery states has
been observed on the glass with a real finger. The operator closed the
predecessor on 2026-10-11 without that capture (“just close it it’s good”)
after confirming that brightness works. This change carries the unperformed
capture and the touch-reachability gap.
runtime/card-shell: the window list is reachable by touch.Changing the recovery copy or contract (src/recovery.rs), the video session’s
lifecycle ownership, or the drawer’s drag-to-Home gesture.
nix/rust-shell-client (touch entry to the menu). The capture needs the
physical board, the bench webcam and the operator’s finger. The touch entry’s
host tests do not.
Layer: userspace (Rust shell client, .#handheld-shell-rust). AppMenu opens
from PointerHandler::pointer_frame on a right-button press only. Touch input
in the drawer goes through navigation::DrawerNavigation, where a long press
arms the drag to Home. The recovery copy and its rendering already exist
(src/recovery.rs, archived change
2026-10-11-the-rust-shell-explains-stale-denied-and-ended-states).
LONG_PRESS_MS (500 ms) opens its AppMenu. The finger
still owns the touch (app_actions::MenuHold). Lifting it without moving
leaves the menu open. Moving it past the 12 px hold slop closes the menu and
starts the existing drag to Home from the hold’s start point, so the
drag-to-Home gesture still works in the same way.AppMenu that does not conflict with the drawer’s long-press drag to Home. Record the rejected alternatives in design.md. Host proof: cargo test --manifest-path nix/rust-shell-client/Cargo.toml. Done 2026-10-11: hold to open, lift to keep it open, move to drag (see design.md). cargo test passed except drawer_568x1232_matches_the_committed_evidence_exactly, which fails identically on base 2500bcda. Additional injected-touch QEMU proof (not board proof): docs/evidence/recovery-routes/touch-app-menu-qemu-2026-10-11/.nix build .#handheld-shell-rust. Passed 2026-10-11: /nix/store/17506zjlnfdmpvr272lrzf5cncif3f7b-k230-shell-rust-riscv64-unknown-linux-gnu-0.1.0 (staged tree). The committed revision 383d4524 was installed on the board as ELF si9vd9hh…; see docs/evidence/recovery-routes/touch-menu-installed-2026-10-11/.the-rust-shell-explains-stale-denied-and-ended-states 3.1) After deployment, capture real-finger recovery/error readability: python3 tools/capture-feature.py recovery-routes --provenance real-touch --duration 30 --description 'Recovery routes for stale, denied, and ended states' --output-dir docs/evidence/recovery-routes. The capture covers the empty and stale window list, the denied Settings action, and video stopped and cancelled. Serial-triggered setup (closing a window, refusing brightness writes, stopping the video session) is recorded as such. Hardware proof; stays open until the capture exists. Done 2026-10-11 on the installed build: docs/evidence/recovery-routes/touch-capture-2026-10-11/. Real-finger input; serial/SSH triggers recorded as setup. Observed on glass: empty and stale window list, Settings denial (native grim for the wording). Video stopped and cancelled are logged and filmed, but their wording is not legible on camera (operator reported working). Loading and video-ended remain UNVERIFIED in the specs.Grounding: docs/evidence/recovery-routes/touch-capture-2026-10-11/README.md (2026-10-11): on the installed build, holding a drawer tile still opened its menu (shell log app-menu-hold then app-menu-ready, no home-drag-begin) under a real finger, and the menu stayed open after lift. The touch route is the drawer hold; Home’s long press still enters rearrange mode.
The shell SHALL offer a touch route to an app’s window list that does not start the drawer’s drag to Home. The list’s loading, empty and stale states SHALL then be reachable with a finger.
Archived change · Archived
Snapshot 5836ef1d113d · 2026-10-17 08:22 UTC
Closed recordReview the archived record and cited scope
A person using the Rust coherent shell who sees a window list that is still loading, empty, or stale, who is denied a system action, or whose video ends, stops, or is cancelled, gets no short explanation and no named way out. The predecessor change the-shell-makes-recovery-routes-legible (superseded 2026-10-11) targeted the Python/C touch-launcher, which the shipped Rust shell (k230-coherent-shell / k230-mainline-drm-shell) no longer launches. This change carries the still-unmet requirements to nix/rust-shell-client.
runtime/home-screen gesture topology has no persistent bar, so the premise no longer exists. nix build .#touch-launcher: touch-launcher is reachable only via touch-menu.sh from the swaybar, which nix/shell.nix omits under coherentShell (~889-903); the Rust shell runs Home/drawer/card helpers (~1499, ~1592).runtime/app-launcher (~22-25), with board evidence from archived 2026-10-08-the-launcher-explains-app-actions. Not restated.runtime/card-shell: loading/empty/stale window list; no raw diagnostics.runtime/device-settings: denied system action.runtime/video: Stop, EOF, cancelled recovery.Modal error stacks, a global notification system, moving video/card lifecycle ownership, reviving touch-launcher.
nix/rust-shell-client (state copy, rendering, tests). Host work needs no board; the real-finger capture needs the physical board and a deployed image.
Layer: userspace (Rust shell client, built as .#handheld-shell-rust). The contract lives in src/recovery.rs (state IDs, copy, recovery action, person_safe guard). Audit of where each state is rendered (2026-10-11, source reading, not a board observation):
app_actions::AppMenu, drawn by render::draw_app_menu) is the Rust shell’s window list. Loading showed “Loading app actions…” with no visible way out; a ready menu with no open window said nothing; a window that vanished before focus fell through to the generic “Couldn’t open ” launch splash.service_ui::action_message rendered the helper’s raw code (action-denied, brightness-denied, target-unavailable · try again), and submit/outcome failures rendered raw worker error strings.nix/video-session.py running mpv inside a terminal, and that window closes when playback stops, ends or is cancelled. The shell’s own VideoPlayback is wallpaper video only.SplashStatus::Stale, “That window has closed · Tap for Apps”) that waits for a tap and opens Apps.nix/video-session.py writes k230-video-end.json (owner-only, {"schema":1,"reason":…}) to its runtime directory: stopped for a Stop after a frame was shown, cancelled for one before, and ended for mpv’s “Exiting… (End of file)”. A window the person closed (“(Quit)”), a timeout or an error writes nothing. The shell polls the record every 500 ms, consumes it once and shows the state as a recovery splash (“Video ended · Tap for Apps”, “Video stopped/cancelled · Tap to go back”). It does so only when no overlay or launch is on screen; otherwise it only logs recovery-<id>.nix/rust-shell-client, without moving video/card lifecycle ownership. Host proof: cargo test --manifest-path nix/rust-shell-client/Cargo.toml.cargo test --manifest-path nix/rust-shell-client/Cargo.toml.recovery::RecoveryState::{VideoStopped, VideoEnded, VideoCancelled} when nix/video-session.py playback stops, ends or is cancelled. Owner decision: the session records the end reason (k230-video-end.json) and the shell shows it as a recovery splash. The session keeps lifecycle ownership. Host proof: python3 -m pytest -q tests/test_video_session.py (end reasons) and cargo test --manifest-path nix/rust-shell-client/Cargo.toml (record parsing, single consumption, splash bake).nix build .#handheld-shell-rust.docs/evidence/recovery-routes/installed-2026-10-11/README.md. Preflight, stage, temporary boot, qualification, persistent install and ordinary autoboot passed, and the new Rust shell ELF is running. This proves installation, not glass readability. The real-finger capture originally in this task was not performed: the operator closed this change on 2026-10-11 (“just close it it’s good”). The capture moved, unchanged, to successor the-shell-proves-recovery-states-by-touch task 3.1, together with the finding that the window list opens only on a mouse right-click.The card shell SHALL show short person-facing copy and a visible Back, Apps, or Home action while the window list is loading, empty, or stale. It SHALL NOT render raw filesystem paths, helper diagnostics, or secrets in that copy.
When a system action is refused, the shell SHALL show short person-facing copy and a visible Back or Retry action, and SHALL NOT render raw paths, helper output, or secrets.
After video Stop, end-of-file, or cancellation, the shell SHALL show short copy for that state and a visible Back, Apps, or Home action, without raw paths or diagnostics.
Archived change · Archived
Snapshot 5836ef1d113d · 2026-10-17 08:22 UTC
Closed recordClosed. Vectors run through runtime-gated Pixman on the installed mainline ordinary system; card budgets still fail unchanged and no extension beyond V is used by default. A physical return to the earlier image was not exercised (read-only route check only).
The normal system leaves a physically verified CPU vector path unused, so applications cannot benefit from the board’s proven vector execution without selecting a diagnostic image. The user now wants that path enabled by default and wants every other useful, actually supported CPU extension audited rather than assumed from a processor name.
None.
system/kernel: the ordinary system uses physically proved vectors and records a bounded ISA inventory with explicit runtime gates and recovery evidence.The Nix kernel, Pixman and image package graph, kernel build patch, extension inventory and board evidence change. The normal kernel and renderer store paths change; stage 1 and device tree are audited but changed only if a specific supported extension demonstrably requires it. Physical-board proof is required for default deployment. QEMU and host checks can proceed independently but cannot establish board support.
See proposal.md. The pinned vendor k230.dtsi declares rv64imafdcv_zba_zbb_zbc_zbs_zicbom_zicbop_zicboz_svpbmt and separately names zicntr, zicsr, zifencei, and zihpm. This is firmware-supplied description, not execution proof for every extension. The physical trial kernel reported base acdfimv; its hwprobe V bit, signal/scheduling context test, and 192 Pixman byte comparisons passed. Six card runs in three matched pairs found small mixed CPU effects and failed independent card budgets. The normal system still uses the original kernel and Pixman.
Goals: Build one coherent default kernel/modules/initrd/renderer closure using the proven RVV path; retain runtime scalar dispatch and known-good rollback; produce a source- and runtime-grounded extension inventory with decisions by layer.
Non-Goals: Promise a card speedup, change existing performance budgets, force vector instructions globally, enable every vendor-specific opcode, alter stage 1 without evidence, or infer physical support from QEMU.
RISCV_ISA_V/RISCV_ISA_V_DEFAULT_ENABLE settings into the normal kernel derivation, then build matching external modules and initrd through the normal NixOS configuration. Keep the isolated trial output available for comparison and recovery provenance. The alternative of selecting a trial kernel in the ordinary image without rebuilding its dependent artifacts risks a mismatch.-Drvv=enabled in the actual system package graph. Check the final closure has one Pixman provider and the actual compositor maps it. Pixman must select RVV only after the running kernel reports V; PIXMAN_DISABLE=rvv remains an operational scalar control. The prior replaceDependencies card package was suitable for a bounded experiment but not the fully rebuilt normal graph.zicbop hints, counters and control/fence instructions are not generic reasons to rebuild all userspace with a wider -march. Xuantie custom instructions and vector-version compatibility need their own source/runtime proof before use. Reject global -march based only on DT strings because it could put unsupported instructions in startup paths before any runtime gate.UNVERIFIED and defer their use pending per-extension source and physical evidence.Land the scope first. Build a complete candidate image and preserve its exact store paths. Stage it as a one-time selection with root watchdog/recovery; do not overwrite the known persistent entry or protected credentials. After physical checks and a separately recorded recovery boot, select the proved normal image. Revert by selecting the preserved prior closure if any check fails.
The mainline migration and the theme deployment made k230-mainline-drm-shell the persistent system before this plan’s staging ran. That system has a mainline 7.3.0-rc5 kernel with RISCV_ISA_V=y, Zb*/Zicbo*/Svpbmt enabled, and this change’s RVV Pixman overlay. That deployment already used a one-time candidate boot, preserved rollback roots and verified ordinary autoboot. The remaining gates therefore run on the installed system: identities, vector context, pixels and paired card workloads. QEMU boots the exact candidate kernel with the vector probe, not a full image. By operator decision the rollback route is checked read-only, not drilled. The vendor-kernel .#toplevel remains buildable but is no longer the ordinary image.
Retarget, 2026-10-11 (operator decision). The ordinary system is now
k230-mainline-drm-shellon mainline 7.3.0-rc5 withRISCV_ISA_V=yand the runtime-gated RVV Pixman. The theme deployment (docs/evidence/omarchy-themes/installed-consumers-2026-10-10/) made it the persistent selection through its own one-time boot, preserved rollback roots and verified ordinary autoboot. This change’s one-time boot, recovery drill and persistent-switch sequence therefore no longer applies. Tasks 3.1 and 3.3–3.6 are restated against that installed system. The operator chose to cite the preserved rollback route and check it read-only rather than drill it (3.5). Evidence:docs/evidence/cpu-extensions/installed-mainline-2026-10-11/README.md.
nix build .#kernel --max-jobs 1 --cores 4 --no-link --print-out-paths (host cross-build only). See docs/evidence/cpu-extensions/normal-image-build/README.md.nix build .#shell-compositor --max-jobs 1 --cores 4 --no-link --print-out-paths (host cross-build only). The same Pixman output previously passed the trial’s scalar on/off control; the new ordinary image still needs its own physical dispatch check. See docs/evidence/cpu-extensions/normal-image-build/README.md.nix build .#toplevel --max-jobs 1 --cores 4 --no-link --print-out-paths (host cross-build only). See docs/evidence/cpu-extensions/normal-image-build/README.md; physical boot/recovery remain open.rg -n 'riscv,isa|riscv,isa-extensions' /nix/store/l6jdpbzp53y5n24ky6602f41gzs6f6ik-linux-xuantie-k230-rvv-src/arch/riscv/boot/dts/canaan/k230.dtsi (source audit, not execution proof). See docs/evidence/cpu-extensions/README.md; physical per-extension execution remains explicitly unverified.nix build .#toplevel --max-jobs 1 --cores 4 --no-link --print-out-paths (host cross-build only). See docs/evidence/cpu-extensions/installed-mainline-2026-10-11/README.md §2.2: Zba/Zbb/Zbc/Zbs executed 4/4 physically; no extension added to ordinary codegen; benefit and default use left UNVERIFIED. Host build: the shipped k230-mainline-drm-shell toplevel at 3b08b46c equals the installed system. 3.1 Check the matching candidate kernel boots in emulation with its vector probe and corrupt control, and retain console transcripts with machine limits. Verify with python3 tools/rvv-context-qemu.py --package <context-probe> --corrupt-package <corrupt-probe> --kernel <installed-kernel-output> --output <new-output> (QEMU virt proof only; a probe initramfs, not the full NixOS system, which tools/qemu-k230.sh cannot boot for this board profile). See docs/evidence/cpu-extensions/installed-mainline-2026-10-11/README.md §3.1 (QEMU only).
3.2 Replace the fixed old trial identities in the pixel and card drivers with a validated candidate manifest covering system, kernel, probe, Pixman, package, executable and configuration; retain strict running-system and mapped-library guards, and test valid, stale and missing identity cases with python3 tests/test_pixman_rvv_probe.py && python3 tests/test_card_shell_rvv_benchmark.py (host guard proof).
Host proof: PIXMAN_SOURCE_TAR=/nix/store/s2cifkjf074cwcim1p9lij646fi3p3zy-pixman-0.46.4.tar.gz python3 tests/test_pixman_rvv_probe.py && python3 tests/test_card_shell_rvv_benchmark.py passed 5 pixel/detector and 8 card tests. Temporary manifests and mocked board transport do not prove a candidate boot, physical vector dispatch, or card acceptance.
3.3 On the reserved physical board, verify candidate identities on the installed ordinary boot (restated 2026-10-11: no one-time selection, because the candidate is the persistent system) and run the vector context and 192-case pixel checks; preserve serial reports and exact commands in docs/evidence/; verify with python3 tools/pixman-rvv-compare.py --board --manifest <matching-candidate-manifest> --package <matching-probe-path> --output <new-output> after the matching candidate boot (physical proof). See docs/evidence/cpu-extensions/installed-mainline-2026-10-11/README.md §3.3: PASS, 192/192 equal, context PASS, corrupt control PASS.
3.4 On that candidate boot, record console, shell, Wi-Fi and representative one-/two-card results with unchanged acceptance and budget scripts; verify with python3 tools/card-shell-rvv-benchmark.py --board --manifest <matching-candidate-manifest> --repeats 3 --revision <candidate-revision> --output <new-output> (injected-input physical workload, not real-finger or optical proof). See docs/evidence/cpu-extensions/installed-mainline-2026-10-11/README.md §3.4: measurement COMPLETE; all six runs fail unchanged card budgets and the same five bar-era interaction checks; no consistent RVV speedup.
3.5 Restated 2026-10-11 by operator decision (no recovery drill). On the board, read-only check that the theme installer’s preserved recovery route is intact. The rollback profile and init roots must be valid store paths, every staged backup/ boot file must match its recorded hash, and the protected /boot files must be unchanged. Cite the installer’s rollback subcommand and the U-Boot ums reimaging route. Verify with the committed docs/evidence/cpu-extensions/installed-mainline-2026-10-11/rollback-route-check.py run over tools/console.py; its output is a read-only physical observation, not a performed recovery. See docs/evidence/cpu-extensions/installed-mainline-2026-10-11/README.md §3.5: read-only PASS; no recovery performed.
3.6 Restated 2026-10-11: the proved image is already the persistent selection (theme deployment). Verify that the same ordinary autoboot carried the 3.3/3.4 runs (matching boot ID with ordinary-boot.json) and confirm the exact /run/current-system identity with python3 tools/console.py --wait=5 'readlink -f /run/current-system' on the reserved board. Leave this task unchecked if any physical gate fails (physical deployment proof). See docs/evidence/cpu-extensions/installed-mainline-2026-10-11/README.md §3.6.
Grounding: docs/evidence/card-shell/kernel-rvv/board-trial/README.md records physical hwprobe V, representative signal/scheduling preservation and normal recovery; docs/evidence/card-shell/pixman-rvv/pixel-trial/README.md records 192 exact physical pixel comparisons and RVV callback execution. docs/evidence/cpu-extensions/installed-mainline-2026-10-11/README.md records the installed mainline ordinary system’s identities, physical vector context, 192 equal pixel cases, mapped RVV Pixman and its scalar control. These do not prove complete ISA coverage or card acceptance.
The system SHALL include a matching vector-capable kernel, modules, initrd and userspace renderer in its ordinary image. The renderer SHALL require the running kernel’s vector capability before executing vector instructions and SHALL retain scalar fallback and a runtime disable control. The system SHALL record exact artifact and runtime identities; a processor name, device-tree string, host build or emulated run SHALL NOT replace physical default-image proof.
Partial grounding: the pinned vendor arch/riscv/boot/dts/canaan/k230.dtsi lists base, vector, bit-manipulation, cache-block and supervisor extensions; docs/evidence/card-shell/kernel-rvv/board-trial/boot1-selected.log reports base acdfimv on this board. docs/evidence/cpu-extensions/README.md records the inventory and decisions, and docs/evidence/cpu-extensions/installed-mainline-2026-10-11/README.md records physical Zba/Zbb/Zbc/Zbs single-opcode execution on the mainline system. Safe default use of every listed extension remains .
The system SHALL inventory useful CPU extensions named by its pinned device tree and relevant firmware, kernel, toolchain and library support. Each enabled non-baseline userspace instruction path SHALL have a supported execution environment, an appropriate runtime gate or explicit hardware restriction, and representative physical verification. The inventory SHALL explain exclusions and distinguish standard userspace instructions from privileged features, hints, and vendor-specific or version-dependent instructions. Unknown support SHALL remain explicitly unverified rather than trigger a global ISA build flag.
Grounding: docs/evidence/cpu-extensions/installed-mainline-2026-10-11/README.md records the installed mainline ordinary system’s physical pixel/context proof, paired card workloads and a read-only check of its preserved rollback route. docs/evidence/omarchy-themes/installed-consumers-2026-10-10/README.md records how that system became persistent: one-time candidate boot, rollback roots and verified ordinary autoboot. A physical return to the earlier image was not exercised for this change (operator decision, 2026-10-11) and remains .
The system SHALL reach a persistent vector-capable image only through a deployment that preserves a known-good rollback selection and protected boot data. It SHALL record representative console, shell, network and card workload results on the installed image without relaxing existing card budgets or calling an unproved speedup accepted. The preserved rollback route SHALL be checked and recorded on the board.
Archived change · Archived
Snapshot 5836ef1d113d · 2026-10-17 08:22 UTC
Closed recordAdd shared state IDs/copy keys and visible recovery mapping without moving video/card lifecycle ownership. Verify with python3 tests/test_launcher_navigation.py && python3 tests/test_window_catalog.py…
Superseded 2026-10-11. This change targeted the Python/C touch-launcher, which the Rust coherent shell no longer launches. Unmet requirements move to
the-rust-shell-explains-stale-denied-and-ended-states. Tasks below were not performed and are deliberately left unticked; specs are not synced.
Home recovery is explained only inside Help while the first persistent control says Windows. Error states also expose raw helper/GLib text inconsistently, making recovery less clear.
runtime/recovery-navigation: shared visible recovery routes and status-copy contract.None.
Touch bar, launcher, and video/system state copy/fixtures. It does not replace card composition, catalog discovery, or video lifecycle ownership. Board readability testing remains required.
Current Help says “Windows / Home,” while the persistent bar says only Windows and Home appears after entering that page. Native launcher error evidence shows a truncated filesystem path in a raw GLib error.
Superseded 2026-10-11. This change targeted the Python/C touch-launcher, which the Rust coherent shell no longer launches. Unmet requirements move to
the-rust-shell-explains-stale-denied-and-ended-states. Tasks below were not performed and are deliberately left unticked; specs are not synced.
python3 tests/test_launcher_navigation.py && python3 tests/test_window_catalog.py && python3 tests/test_video_session.py.nix build .#touch-launcher.python3 tools/capture-feature.py recovery-routes --provenance real-touch --duration 30 --description 'Visible Home and recovery routes' --output-dir docs/evidence/recovery-routes. Keep board evidence separate from host state fixtures.Keep a person oriented and able to recover from shell navigation and transient failures.
The shell SHALL expose a visible Home recovery route at the same decision level as window switching or clearly disclose it before entering a subpage, while retaining Apps, Windows, Keyboard, System, and Back behavior.
Catalog, window overview, system action, and video surfaces SHALL use short person-facing status copy and an available visible recovery action. Raw paths, helper diagnostics, and secrets SHALL not be displayed in the person-facing status.
Archived change · Archived
Snapshot 5836ef1d113d · 2026-10-17 08:22 UTC
Closed recordReview the completed analysis and pursue its existing theme-motion, card/keyboard and theme-consumer owners. Landscape remains separate.
KEEP. Per the user’s “stale as suggested” decision on
docs/closeout/stale-triage.md, pick this up after the current shell work
lands, consolidating the existing informal reviews
(docs/design/webos-polish-review.md, docs/design/shell-polish-review-2026-09.md,
docs/design/handheld-shell/visual-gap-audit.md) into this change’s own
review-round-2/ deliverables rather than re-critiquing from scratch. See
the “Decisions” section of the triage doc.
A working launcher, keyboard, and card mechanism do not yet tell us whether the handheld feels coherent, discoverable, and refined in everyday use. The first UX plan is archived, but new card work needs a broader design critique against actual screens and journeys, with an explicit answer to what still separates this shell from the intended webOS-inspired experience.
None.
docs/handheld-ux-plan: Add a repeatable whole-product critique, reviewable current/target comparisons, and a baseline-to-integrated-build review with explicit ownership of follow-up work.Planning and evidence live under docs/research/handheld-ux/ and docs/evidence/; recommendations target userspace and Nix image defaults. This proposal owns analysis and successor planning, not implementation of another shell, renderer, or design system. It does not reopen the archived first audit or duplicate launcher-action, recovery-navigation, card, gesture, or GPU ownership.
Reference study, native-capture critique, and annotated layouts can proceed without the board. Fresh integrated captures require the coordinator’s serialized board slot; any new optical, real-finger, or startup observation needs its own recorded evidence. Existing accepted keyboard/Home observations are reusable; do not request repetition unless a changed behavior or specific evidence gap requires it.
Non-goals: webOS pixel cloning, speculative effects, battery acceptance (the device is USB-powered), new hardware enablement, AtomVM/Dozer, or claiming design recommendations are shipped. The marketing site is updated for accurate evidence and status, not redesigned as part of this round.
See proposal.md for motivation. The archived the-handheld-has-a-coherent-ux-plan provides an interaction contract, flow matrix, issue ledger, reference study, and schematic layouts in docs/research/handheld-ux/. Those are inputs, not proof that today’s integrated shell meets the intended design. Master 3a296b5 includes board-injected card architecture evidence and a host-tested product adapter; the installed image and opt-in compositor packages must be identified separately during review.
The review layer is documentation about userspace behavior and Nix defaults. Kernel, device tree, and stage 1 remain owned by their existing changes. Startup can be observed without making this analysis responsible for a boot-chain redesign.
Goals: Produce a useful, repeatable critique with concrete visual alternatives and an executable follow-up order. Make the gap between functional mechanisms and a polished whole apparent to a reviewer without asking them to infer it from test totals.
Non-Goals: No production source changes in this analysis change, no fresh-home state restoration, no numeric “UX completeness” percentage, and no claim of physical usability from screenshots. Implementation successors keep their own acceptance gates.
Create a dated docs/research/handheld-ux/review-round-2/ baseline and reusable rubric. Cover: first usable USB-powered boot; discover and launch an app; type with the keyboard; enter/switch/return from cards; close and refusal; use/stop media; reach Home/Help/System; and recover from empty, loading, stale, error, and denied states. Evaluate keyboard-hidden and keyboard-visible composition where applicable.
For each journey record source/image/store path, starting state, actions, expected and observed result, evidence class, issue IDs, and unknowns. Review hierarchy, type roles, spacing, icons and labels, contrast, focus, reach, feedback, transitions, motion reduction, state persistence, and cross-surface consistency. An absent or unavailable feature is recorded as such, not simulated into the baseline. Rejected alternative: inspecting only isolated happy-path screens, which misses focus and recovery problems.
Reuse and verify the existing webOS references; inspect the actual cited material when applying the change. Record reference URL, access date, video timestamps where applicable, the observed principle, and its relevance to this device. Compare spatial continuity, direct manipulation, task switching, chrome, discovery, and feedback with our actual implementation. Distinguish observations from recommendations. Complement that comparison with general usability/accessibility analysis so the critique remains useful beyond cards. Rejected alternative: treating “webOS-like” as acceptance or promising a pixel clone.
Provide at least three annotated current-versus-target comparisons covering Apps, cards, and keyboard/recovery composition, plus one transition storyboard. Use repo-native SVG/HTML or annotated captures with readable labels at 568x1232; mark target drawings as proposals. Render and inspect the artifacts. Consolidate recommendations into shared type, spacing, color, target, and motion guidance, building on the existing contract. Explain trade-offs and CPU/memory/performance dependencies; defer costly effects until measured. Rejected alternative: a list of unrelated aesthetic tweaks or a redesign that depends on unproved acceleration.
Extend the issue ledger with stable IDs, reproducible observation, user impact, severity, evidence confidence, current artifact, proposed correction, owning proposal/path, dependency, acceptance, and rough effort. Mark missing footage as an evidence gap rather than an observed defect. Route launcher actions and recovery language to their existing successors, card behavior to the card change, and renderer eligibility to the GPU change. Create full proposals only for uncovered priorities; landing a proposal does not implement it.
An analysis agent can review reference/visual consistency while another reviews task flows, using separate owned documents. The coordinator reconciles contradictions and selects a small first implementation tranche. This can run beside card/GPU work without a board/build slot. A later serialized board session captures the integrated candidate and rechecks P0/P1 findings against the baseline; note any items still unimplemented or lacking physical evidence. Reuse accepted Home/keyboard observations when unchanged. Cold-start timing remains an explicit observation gap if a justified power-cycle session is unavailable.
The final report answers: what works, what feels unfinished and why, how the webOS-inspired target differs, what improved in the candidate, and the next three implementation priorities. The analysis may conclude while its successor changes remain open; it cannot conclude before its own baseline, comparisons, critique, candidate recheck, and backlog are committed.
Publish this proposal first. Apply the analysis to the current baseline, then publish findings and any uncovered successor proposals promptly. Recheck a later integrated build and publish the resulting evidence/status through the existing site pipeline. Archiving syncs only the added documentation capability requirements; runtime features stay with their own changes. Documentation corrections use ordinary reviewed commits and require no reflash.
Sequenced by user decision (2026-09-28): start groups 1-2 after the
current shell work lands, and fold docs/design/webos-polish-review.md,
docs/design/shell-polish-review-2026-09.md, and
docs/design/handheld-shell/visual-gap-audit.md into references-and-gap.md
and findings.md as raw input rather than repeating that critique — see
Status (2026-09-28) in proposal.md.
docs/research/handheld-ux/review-round-2/baseline.md and rubric.md, pinning source/image/experimental packages and linking the existing evidence for each surface and journey in design.md. Verify by reviewing the inventory against the flow matrix; explicitly retain unavailable states and evidence gaps. Coordinator-reviewed 2026-10-01; current-source/store identity, journey matrix cross-check, and unavailable states are explicit.references-and-gap.md. Verify every comparison has an inspected source and a current artifact or UNVERIFIED marker; do not infer device performance from a reference video. Coordinator-reviewed 2026-10-01; book PDF/printed page numbers, Palm Pre guide pages and webOS OSE guide sections are recorded with 2026-10-01 access date; no video timestamp is used.Proof: openspec validate the-handheld-gets-a-design-and-ux-review --strict plus coordinator review of the three documents and cited artifacts. This is host documentation proof, not QEMU or hardware acceptance.
review-round-2/. Render and inspect all sheets; record the exact render invocation and review corrections in visual-review.md. Verify proposal labels, portrait geometry, readable annotations, and links to current evidence. Coordinator reviewed the rendered sheets and required revisions, then agreed on closure 2026-10-01; older card/keyboard sources and the missing latest deck image remain clearly labeled.journey-review.md. Verify each issue names a reproducible action/state and evidence confidence, and each relevant keyboard-visible state is covered or explicitly unknown.findings.md, with stable issue IDs, severity, confidence, proposed correction, existing owner or successor, dependency, rough effort, and observable acceptance. Verify shared type/spacing/color/touch/motion recommendations are coherent and the independent reviewer has recorded agreement or remaining disagreements. Coordinator review and corrections are recorded in findings.md and visual-review.md; no disagreement remains on the four scoped findings, and physical impact stays unverified where applicable.Proof: openspec validate the-handheld-gets-a-design-and-ux-review --strict and python3 scripts/build_site.py, plus recorded visual inspection and independent critique. Site generation proves publication integrity, not usability; do not mark these tasks complete from validation alone.
Sequenced by user decision (2026-09-28): best timed after the
theme-picker, power-key, and other current shell work lands, so the recheck
runs against a more final integrated candidate — see Status (2026-09-28)
in proposal.md.
flock /tmp/k230-board.lock python3 tools/console.py /dev/ttyACM0 --wait=3 'readlink -f /run/current-system; systemctl is-active shell.service; systemctl show shell.service -p MainPID -p ExecStart; readlink -f /proc/$(systemctl show shell.service -p MainPID --value)/exe'. Record any separately launched experimental compositor’s unit/PID, resolved executable, and package explicitly; the default system closure alone does not identify it. Commit a sanitized transcript and native screenshots with their exact capture commands. Verify the candidate is identified separately from baseline and opt-in packages; no reflash is required merely to conduct this review.candidate-recheck.md with before/after evidence and remaining owners. Reuse unchanged accepted physical observations. If a changed behavior requires new optical/finger evidence, use python3 tools/capture-feature.py ux-review-round-2 --provenance real-touch --duration 30 --description 'Focused design review of changed handheld flows' --output-dir docs/evidence/ux-review-round-2 during a coordinated operator session, inspect the footage, and record its actual limits. If unavailable, mark those claims UNVERIFIED and preserve the acceptance work with its runtime owner; do not silently waive it.Proof: the recorded console command, committed native captures and reviewed recheck table; use the named camera command only for actual physical interaction. This is hardware observation with separately labelled injected/native/optical/finger evidence, not QEMU proof. Missing physical footage cannot establish readability or finger tracking.
recommendations.md answering what works, what feels unfinished, the webOS-inspired gap, candidate improvements, and the next three priorities. Map every priority to an existing proposal or create full bounded successor artifacts; verify no duplicate card/GPU/launcher/recovery scope and list parallel paths and board dependencies. The three priorities route to existing picker-motion/theme, integrated card/keyboard recheck, and theme-consumer/Settings owners; no duplicate successor proposal was needed.Proof: openspec validate --all --strict, python3 scripts/build_site.py, and python3 tools/work-status.py; inspect the exact-revision CI/Pages run with gh run list --branch master --limit 5 and gh run view <run-id>. Record the deployed URL and revision in the handoff. This proves planning/publication, not completion of successor runtime features.
Host closeout note (2026-10-01): Tasks 1.1, 1.2, 2.1, 2.3 and 4.1
are complete in docs/research/handheld-ux/review-round-2/; named strict
validation and the site build pass. Task 2.2 remains open because this review
did not walk every current-source journey, even though the exact candidate has
three unchanged operator-accepted real-finger checks. Tasks 3.1–3.2 remain
open for the focused integrated candidate/physical recheck. Task 4.2 remains
open for reviewed publication, merge/push, exact-revision CI/Pages and the
published URL. This change is not ready to archive.
Integrated candidate checkpoint — 2026-10-09: tasks 3.1/3.2 are complete.
The exact named console proof ran with pager/color controls to preserve complete
identity fields; active unit/PID, service wrapper, actual compositor/Rust
executables and loaded Pixman are identified independently. Four inspected
native captures and their exact commands/hashes are committed under
docs/evidence/ux-review-round-2/candidate-2026-10-09/; candidate-recheck.md
reviews all four findings and preserves every optical/finger/runtime unknown.
No finding had P0/P1 severity. Task 2.2 remains open for the focused current
journey walkthrough, and 4.2 remains open for final publication/archive.
This checkpoint adds no runtime implementation or blanket physical acceptance.
Functional walkthrough closure — 2026-10-09: the operator answered the requested Terminal keyboard, two-app switch/Home and video play/stop/Home checks with “terminal keyboard works. switching apps works. videos work”. The exact question/reply is committed in the candidate operator report. Task 2.2 is complete as analysis coverage with explicitly unavailable/unknown states; no unperformed runtime accessibility, exceptional-state, optical or motion proof is ticked. This supersedes the pending 2.2 checkpoint above.
Publication closure — 2026-10-09: the full current report and operator
walkthrough are merged/pushed at 817804758cae1801e9b57de3cda6969eccd15529.
Strict all-item validation passed; the full site build passed with 673 pages,
17,883,724 bytes and 93.07 seconds. CI/Pages run 37999119193 passed, and the
actual public work board returned HTTP 200 with that exact revision. The named
work-status command completed with cached master/origin equal at the earlier
1e9d42bf checkpoint; master was separately checked after publication. Final
archive validation/publication follows as the same reviewed closeout. All nine
analysis tasks are complete. No runtime successor gate is waived.
Grounding: identified console/native evidence and current operator functional
walkthrough in docs/evidence/ux-review-round-2/candidate-2026-10-09/README.md;
coverage, unavailable routes and physical unknowns are explicit in
docs/research/handheld-ux/review-round-2/journey-review.md. Documentation review
is complete; optical, accessibility and exceptional-state runtime claims remain
UNVERIFIED where matching observations are absent.
The documentation SHALL expose a dated design and UX review spanning shell, launcher, cards, keyboard, terminal, media, Help, System, startup, and recovery. It SHALL assess visual consistency and complete user journeys using a reusable rubric. Each finding SHALL distinguish functional status, design quality, evidence confidence, and unobserved behavior, and identify the reviewed revision and installed or experimental artifact. Documentation owns the critique; runtime owners retain implementation responsibility.
Grounding: rendered comparison sheets and recorded coordinator inspection
in docs/research/handheld-ux/review-round-2/visual-review.md; exact publication
and browser evidence in docs/evidence/ux-review-round-2/README.md. These are
reviewable design mockups, not device implementation or physical acceptance.
The review SHALL provide at least three annotated current-versus-target comparisons covering Apps, cards, and keyboard/recovery composition, plus a transition storyboard. It SHALL identify reference sources and observed interaction principles, including a concrete comparison with the intended webOS-inspired experience. Proposed layouts SHALL be marked as proposals, and recommendations SHALL explain user benefit, consistency with the shared visual/touch contract, and relevant performance constraints.
Grounding: identified candidate/recheck evidence in
docs/evidence/ux-review-round-2/candidate-2026-10-09/README.md; independent
critique, four-finding reconciliation and owned priorities in
docs/research/handheld-ux/review-round-2/findings.md, candidate-recheck.md and
recommendations.md. Unimplemented and physically unverified runtime work
retains its named owner and acceptance gate.
The review SHALL retain an independent critique, severity-ranked findings with separate confidence, and a recheck of P0/P1 findings against an identified integrated candidate. Each finding SHALL identify an existing owner or a bounded successor, an observable acceptance condition, dependencies, and whether it can proceed without the board. Unimplemented or physically unverified findings SHALL remain explicit. The report SHALL name the next three implementation priorities and ensure new priority proposals are validated and published on master.
Archived change · Archived
Snapshot 5836ef1d113d · 2026-10-17 08:22 UTC
Closed recordComplete: automatic switching and navigation accepted. Settings reboot scope canceled; landscape remains in its separate proposal. Precise latency measurement is deferred.
Plugging in HDMI moves the shell to the monitor; unplugging returns it to the panel and direct touch without rebooting. The operator accepted the faster cable cycle, portrait HDMI rotation, trackpad behavior and navigation on 2026-10-09. The qualified tuple is installed normally and is the default built SD image. This change closes that delivered automatic behavior.
display/hdmi: bridge presence, shared wiring constraints, separate
qualification/recovery trees and physically proved automatic cable switching.sdImage,
preserving protected stage 1, selectors and rollback roots.the-hdmi-shell-works-in-landscape proposal. Its physical gate remains open.Non-goals: HDMI audio, CEC, camera/ISP, shared IRQ experiments, landscape layout implementation and precise sampled latency qualification in this closeout. The operator waived a monitor photograph; actual observations and matching serial/sysfs identities are committed physical evidence.
display/hdmi: board-specific HDMI qualification/recovery and accepted
automatic cable switching without rebooting.display/touch: shared GPIO23/24 constraint and the existing virtual-trackpad
requirement updated to reflect physically accepted automatic panel return.Kernel DSI/LT9611 drivers, device trees, Nix image wiring and the existing input
relay implement this behavior. Implementation/default promotion landed at
6b4fe555645ac553914549fcd926d1f0902b65d1. Evidence lives in
docs/evidence/hdmi-mainline/ and docs/evidence/hdmi-hotplug/live-switch/.
Normal installed system is
/nix/store/yl3si5ak6yi709yg1fqsnwgq0zn4xfcs-nixos-system-nixos-26.11.20260919.20b1ddd.
The volatile trial, normal installation/autoboot and built SD image remain
separate evidence classes; no whole-image flash is claimed. This archive changes
planning/spec/evidence only and requires no new board action.
docs/research/hdmi-hotplug.md is the research this design builds on; read
it first. The load-bearing facts, restated only where a decision hinges on
them:
T-Display K230_V1.0_NEW.pdf, sheets “K230” and “HDMI+ETH”).HDMI_RSTN→TP_RST and HDMI_INT→TP_INT net-label ties), with
disagreeing polarity/trigger-type requests between the vendor LT9611 DT
node and our own touch node on that same wire.drivers/gpu/drm/canaan/canaan_dsi.c’s canaan_dsi_bind() resolves
&dsi’s single downstream port exactly once, at boot, via
drm_of_find_panel_or_bridge(). There is no runtime re-attach path.drm_bridge_connector_init() is not called anywhere in our
kernel’s canaan DRM driver) — a real, small gap that blocks HDMI output
entirely today, independent of switching.ui_hdmi_test.c) is a double-tap-confirm, reboot-based,
self-reverting device-tree swap. No source found — LILYGO’s, Canaan’s
reference tree, or ours — switches without a reboot.Goals: get a real HDMI-A-1 output working on this board’s own device
tree (not a copy of the unrelated reference tree); provide a working,
self-reverting manual switch a person can trigger from Settings; attempt
no-reboot automatic switching as an honestly-graded, separately staged
effort; make the minimum shell/card-shell changes needed to show something
coherent in landscape once an HDMI output exists.
Non-goals: adopting LILYGO’s 800x480@60 output as our target mode;
HDMI audio or CEC; a full landscape redesign of every shell screen in this
change (tracked separately if it grows beyond what HDMI needs); rewriting
canaan_dsi.c’s DSI-host architecture in general — only the specific,
minimal changes this capability needs.
k230-canmv-v3.dts wholesale (no RM69A10 panel node, no GT9895 touch
node, 800x480@60). Copying that would give us a working HDMI output with
the wrong resolution and would not exercise this board’s actual GPIO23/24
sharing at all, since that tree never has touch present to conflict with.
We instead add an LT9611 node to a variant of nix/dts/k230-tdisplay.dts,
using this board’s own I2C3/GPIO23/GPIO24 wiring (schematic-confirmed),
targeting 720p60 first. Rejected: copying LILYGO’s reference-tree DTB
verbatim — faster to a working demo, but it would not be this board’s
HDMI path, and 800x480 is a worse target than 720p for a monitor.canaan_dsi.c before anything
else. Without drm_bridge_connector_init(), no DTB, ours or LILYGO’s
copied one, produces a usable HDMI-A-1 under our kernel. This is a
kernel patch, reviewed and host-build-proved like any other patch in
nix/kernel.nix, before the first board boot with an LT9611 node
present.nix/sd-image.nix’s existing force_dtb/lcd_dtb/
hdmi_dtb U-Boot selector files (already present and hardware-tested,
currently all pointed at the panel DTB) is strictly additive: write a
second DTB, flip the selector file, reboot; write the restore marker
first so any subsequent reboot for any reason reverts to the panel.
Rejected: gating the whole proposal on no-reboot automation working —
would leave HDMI unusable indefinitely if stage 4 proves infeasible,
contradicting AGENTS.md’s “keep changes moving.”docs/research/hdmi-hotplug.md §5 (LT9611 must be
live while the panel DT is booted to detect a plug at all; the shared
GPIO24 reset net forbids independently resetting either chip after
initial power-on; canaan_dsi.c has no live re-attach path today) are
none of them cosmetic. This stage’s tasks are written to produce a clear
pass/fail/infeasible record rather than to assume success. If it proves
infeasible, the Settings-triggered reboot switch from decision 3 remains
the shipped capability and this change closes with that scope, per
AGENTS.md’s “preserve every remaining requirement… in an explicit
successor proposal” if a split is later authorized.nix/shell.nix’s Sway config gets an
HDMI-A-1 output/input stanza; rust-shell-client’s design-space
transform (lib.rs’s DESIGN_ASPECT and the 568.0/1232.0 literals
it feeds) is parameterized on the actual output geometry rather than
hardcoded. Per-screen landscape layout quality (grid reflow, navigation
chrome) is out of scope for this change and tracked as follow-on work;
the acceptance bar here is “usable and not visually broken,” not
“redesigned for landscape.”canaan_dsi.c
rearchitecture, well beyond this change’s board time] → accepted
explicitly by decision 4: the manual switch ships regardless, and this
risk is recorded rather than hidden if it materializes.No data migration. Boot-path migration is additive and reversible: a second
DTB file and a flipped selector text file, both reversible by reboot (see
decision 3 and docs/research/hdmi-hotplug.md §6). The kernel patch
(bridge-connector creation) is unconditional and has no effect on the panel
boot path, since it only executes when dsi->bridge is non-NULL, which
never happens without an LT9611 DT node present.
The first mainline HDMI trial initializes LT9611 before Goodix probes.
Goodix then asserts their shared GPIO24 and erases the bridge’s setup,
including I2C access enable, while the bridge’s cached power_on stays true.
Restoring I2C access and cycling the output recovered a 256-byte EDID and a
working monitor picture. See docs/evidence/hdmi-mainline/README.md.
The kernel driver now defers LT9611 probe until its optional
lontium,shared-reset-owner I2C device has finished binding and adds a
managed consumer link. The HDMI DTB points that property at touch.
Rejected: a fixed delay or another bridge-owned reset pulse; neither
establishes reset ordering, and the second resets already-initialized touch.
The matching full build and fresh volatile board trial passed. Goodix
registered before LT9611, automatic HPD returned a 256-byte EDID, and the
operator accepted the monitor trial. Exact evidence classes and limits are
recorded in docs/evidence/hdmi-mainline/README.md.
The Nix layer supplies a separate k230-mainline-drm-shell-hdmi profile
with the existing touchscreen-to-touchpad service and uinput loaded.
The original mainline HDMI bundle had neither service nor virtual-input
module. The ordinary panel profile retains its direct-touch setup.
The implementation targets k230-mainline-drm-shell, now the default
sdImage, using the matching mainline panel/HDMI trees from group 7. The
vendor system remains a rollback target, not the source of a DTB for a
mainline boot. Image assembly adds k230-tdisplay-hdmi.dtb with the same
system boot arguments; force_dtb still selects the intact panel tree.
tools/display_switch.py verifies the installed Image, panel recovery
DTB and bootargs against the running system before selecting HDMI. It
writes/fsyncs a fixed panel restore marker, prepares the HDMI tree with
those same bootargs, atomically replaces force_dtb, remounts /boot
read-only and requests a reboot. A failed write or denied reboot restores
the panel selector. The root helper has an exact sudo command; Settings
uses the existing short-lived, single-use confirmation token protocol.
The early k230-display-restore unit restores the panel selector before
Sway starts and removes the marker. This needs Linux to reach the restore
unit: it cannot recover a kernel/initrd failure before that point. The
previous assertion that any bad DTB can be repaired by a power cycle is
not established by a Linux-only marker. Use a qualified, matching boot
bundle, retain the staged protected baseline and serial recovery, and keep
task 3.3 open until the Settings-driven forward/return sequence is proved.
No stage-1 change or pre-Linux rollback guarantee is claimed.
One installed system includes the existing relay and uinput. Its mode
check keeps direct touch on a connected panel and grabs Goodix only for
connected HDMI; it does not infer that an HDMI-capable kernel means HDMI
is active. The explicitly named HDMI trial profile remains available.
The accepted output geometry is preserved.
The extra Settings row appears only when the controller is installed. Its confirmation uses the same scaled geometry for painting/hits and keeps its buttons within the current output; older Settings fixtures keep their existing row rhythm and pixels.
k230_set_dtb/hdmi_dtb/lcd_dtb fallback
(nix/sd-image.nix:142-156) perform any live display-presence probing of
its own, independent of a userspace-written selector file? Not resolved
by this research (our U-Boot ships as a prebuilt blob; the C source was
not read). If it does, that may be a cheaper place to do boot-time
auto-selection than anything proposed here, and is worth a follow-up
before deep investment in stage 4.INT_ATST_GPIO3 output and the GT9895’s interrupt
output both open-drain? Not determinable from the schematic (drive type
is not a schematic-visible property) or from any source read. The
read-only probe task must establish this, or record it as still
unknown, before any shared-IRQ design proceeds.The operator explicitly requested automatic plug/unplug switching after
accepting the group-7 HDMI trial. The separate Settings implementation is
parked at commit 58498320; it is removed from the active source tree and
is not a prerequisite for this work. Its host evidence remains a record of
that checkpoint, not the current installed system.
Task 4.1’s mainline qualification tree keeps the existing panel graph and
adds the LT9611 only as an I2C HPD monitor. The driver waits for the Goodix
reset owner, enables register access as the existing revision probe does,
masks its HPD interrupt sources, and exposes read-only hpd sysfs status.
It neither acquires reset/IRQ GPIOs nor attaches a DSI device or DRM bridge.
This replaces the old shared-interrupt experiment: the electrical drive
type is still unknown, so polling is the intended path. The matching monitor-driver trial captured actual unplug/replug with DSI
connected/enabled on one boot ID; its real-touch operator report remains
pending. Cable detection is grounded in
docs/evidence/hdmi-hotplug/live-switch/monitor-cable-cycle.json; visible
handoff is still UNVERIFIED.
The qualification boot is volatile and retains the protected panel bundle. Do not infer a live-display switch from this cable-status proof. Once it passes, task 4.2 must specify and implement the runtime DRM/DSI arrangement explicitly. Both output geometries and HDMI trackpad behavior from the accepted trial should be retained. No monitor photograph is required by the operator.
The matching driver trial now establishes polling HPD alongside an enabled panel without rebinding DSI or acquiring shared GPIOs. The operator affirmed replug and the panel, completing the named monitor probe/cable gate. The runtime source is now applied for the combined trial; real-touch/navigation proof remains separate and pending in task 4.3. The shipping target is automatic cable switching on mainline, preserving the accepted HDMI orientation and trackpad behavior; the parked Settings prototype is not a prerequisite. The remaining manual and landscape tasks stay explicit and open.
The kernel keeps two downstream DSI devices registered at boot: the panel on logical channel 0 and LT9611 on logical channel 1. This distinguishes the Linux device registrations; the host’s video virtual channel remains 0 and the LT9611 sends no DSI command messages. The combined device tree gives DSI port 1 two indexed endpoints, 0 for the panel and 1 for LT9611 Port B. The host adds its DRM component only once both consumers have attached, avoiding the vendor master’s unsafe deferred-bind cleanup path.
Two encoders share the one CRTC but prohibit cloning onto one another.
The panel connector reports connected unless HDMI HPD is connected; the
HDMI bridge connector reports HPD normally. A delayed worker reads bridge
HPD every 250 ms and runs DRM hotplug detection on both connectors only when
the cable state changes. Both connectors retain generic DRM polling as a
fallback. GPIO23 remains owned by touch; no bridge interrupt is enabled. The
worker starts after binding, waits for DRM registration/poll initialization,
and is synchronously cancelled before component teardown. On a cable
change, the ordinary DRM hotplug event lets the existing Sway session disable
the old output and enable the other; the connectors and consumers remain
registered throughout. This avoids live component teardown, graph rebinding,
and transferring ownership of the shared reset/interrupt pins. The initial
qualification ceiling remains 30 seconds per transition, measured against
real cable actions rather than injected status. The operator confirmed both
visible handoff directions and touch modes on the first generic-poll trial,
but judged both directions too slow. The revised target is cable detection
within one second and DRM output activation within three seconds; monitor
video-lock time and visible operator timing remain separately recorded. The bridge
also retains the read-only raw hpd attribute, letting the watcher measure
raw HPD-to-DRM activation separately from the operator’s visible transition
report; cached DRM status is not treated as an immediate cable timestamp.
The encoder’s enable/disable callbacks use the selected consumer’s lane
count and panel callbacks only for the panel. The panel retains its measured
canaan,hsfreqrange=0x87; HDMI uses the accepted 0x96. A DSI transfer returns
-EPIPE while the HDMI consumer is selected, so a panel brightness update
cannot send panel commands onto the HDMI video stream. The stage-1 splash
handoff remains panel-only and assigns its active DSI device before panel
callbacks send commands.
Touch remains the sole owner of GPIO23/24 for the entire boot and every transition. LT9611 HPD and video interrupt sources remain masked when there is no bridge IRQ; the still-unknown shared interrupt drive type is not assumed safe. No cable event triggers reset of either shared device. Panel GPIO22/25 are independent and follow its ordinary prepare/unprepare path.
The existing touch relay is enabled in the daily mainline system. It selects
trackpad mode only when HDMI is connected and its scanout is enabled; it
releases the grab and virtual device before returning to direct touch. It
restores Sway’s map_to_output DSI-1 and identity calibration, retries while
the compositor is starting, and repeats after a socket replacement. The
accepted Sway HDMI preferred mode and transform 90 remain unchanged.
The existing shell already cancels card-shell state before an output is
disabled (card_shell_output_disable in nix/card-shell/adapter.c), and
the Rust client’s layer-close handlers recreate Home and wallpaper on the
next available output. Those source paths need no speculative rewrite;
their actual behavior during the cable trial remains part of task 4.3.
Host fixtures prove mode selection and IPC retry behavior only, not glass
or real-finger interaction.
The combined candidate is exposed separately and staged for a volatile trial before making it the normal boot/image device tree. The protected panel payload and system profile are retained until matching physical qualification. Task 4.3 records actual panel→HDMI→panel observations, DRM/Sway state, input mode and unchanged boot ID. Task 4.4 resolves only against that evidence. Host build, injected input and native screen capture are recorded as their own evidence classes and do not complete those gates.
The operator accepts the faster combined trial and confirms the requested
real-touch checks with “it works great land it”. Exact qualification and
unchanged trial boot identity are recorded in
docs/evidence/hdmi-hotplug/live-switch/fast-runtime-qualification.json and
fast-runtime-qualified-state.json. The repository’s normal mainline bundle
and sdImage now use this combined tree and build to the same immutable
bundle/image paths as the qualified trial and inspected prepared image.
Normal installation retains the previous root backups and profile roots,
preserves stage 1 and DT selectors, and observes ordinary autoboot separately.
Visible HDMI timing is approximately a couple of seconds and panel return
almost instant, per the operator. The bounded watcher did not overlap a
cable action, so the separate sampled ≤1s/≤3s targets remain unmeasured and
task 4.3 records this limitation. The operator subsequently deferred precise
latency measurement (“ignore latency measurement good enough for now”); the
named physical handoff/navigation gate is complete without claiming the
sampled targets passed. See docs/evidence/hdmi-hotplug/live-switch/closeout-2026-10-09.md. Working no-reboot switching is recorded in task 4.4
without converting those approximate observations into precise measurements.
Manual switch and landscape tasks remain open; this change is not archived.
The preceding sections preserve the chronology of vendor, manual prototype, monitor and combined runtime decisions. The operator now drops the obsolete Settings reboot/self-revert scope because automatic switching works, and authorizes a separately landed landscape proposal. Earlier descriptions of manual/landscape tasks as open within this change are superseded by this explicit decision. The canceled prototype supplies no recovery guarantee.
the-hdmi-shell-works-in-landscape preserves tasks 5.1–5.4 and their separate
layout/physical gates, reusing the responsive implementation. It uses automatic
exclusive-output switching rather than the canceled Settings path. Precise
HPD timing remains deferred. This closes all 17 retained HDMI tasks against
committed proof, without ticking canceled, transferred or unperformed checks.
See docs/evidence/hdmi-hotplug/live-switch/scope-decision-2026-10-09.md.
No GPIO is driven differently from today’s boot in this group; every step reads state only. This is the first work this change may run on hardware.
&i2c3 alongside touch:
flock -w 120 /tmp/k230-board.lock python3 tools/console.py /dev/ttyACM0 --wait=3 "i2cdetect -y 3".
Record which adapter number Linux assigned to &i2c3 from
/sys/class/i2c-adapter/*/name in the same session rather than
assuming 3, since adapter numbering is not guaranteed to match the
DT alias. Expect 0x3b (LT9611) and 0x5d (GT9895, already known
working) both listed.i2cget itself sends:
flock -w 120 /tmp/k230-board.lock python3 tools/console.py /dev/ttyACM0 --wait=3 "i2cget -y 3 0x3b 0x00"
(or the adapter number from 1.1). Record the returned byte and
whether the chip acknowledges at all; do not yet attempt to decode it
against the LT9611 register map without a datasheet read (not yet
done in this change) — this step establishes “something answers,”
not “the chip is initialized correctly.”
Done 2026-09-29 on adapter 1: 0x00 read back. The same session
also made the mainline driver’s page-select writes to read chip ID
0x17 0x02. That deviation is recorded in
docs/evidence/hdmi-hotplug/probe/lt9611-probe-2026-09-29.md.flock -w 120 /tmp/k230-board.lock python3 tools/console.py /dev/ttyACM0 --wait=3 "cat /sys/kernel/debug/gpio"
(or gpioinfo/gpioget against the gpio0_ports chip if
debugfs is unmounted). Record both lines’ direction, active state,
and whether GPIO23’s consumer is already the touch driver (expected,
since no LT9611 node is loaded yet).INT_ATST_GPIO3
output and the GT9895’s interrupt output are open-drain (needed
before any shared-IRQ design in group 4): read the GPIO23 pull
configuration and any available driver/debugfs description of drive
type from the same session as 1.3. If this cannot be determined from
software alone, record that explicitly rather than guessing — this
remains an open question in design.md either way.docs/evidence/hdmi-hotplug/probe/, and resolve the two
<!-- UNVERIFIED --> markers in specs/display/hdmi/spec.md’s
“The LT9611 is present and addressable” requirement against what was
actually observed.drivers/gpu/drm/canaan/canaan_dsi.c’s bridge-attach branch
in canaan_dsi_bind() to call drm_bridge_connector_init() and
attach the resulting connector to the encoder, mirroring the existing
panel branch’s connector setup immediately above it in the same
function. Add the patch to nix/kernel.nix alongside the existing
documented patches (goodix-berlin backport, panel reset-timing fix,
etc.), with the same kind of comment explaining what upstream is
missing and why. Verify with nix build .#kernel.
Done 2026-09-28: nix/patches/canaan-dsi-bridge-connector.patch,
applied from nix/kernel.nix. nix build .#kernel succeeded
(/nix/store/mvayir0f4aksyd4pnayiz2ipvxwy4b4k-linux-riscv64-unknown-linux-gnu-6.6.36-xuantie),
and the patched line is present in the applied source
(drivers/gpu/drm/canaan/canaan_dsi.c:733 in the resulting
linux-xuantie-k230-src). Host build only; not booted.nix/dts/k230-tdisplay-hdmi.dts (or equivalent alternate top-level
board file sharing k230-tdisplay.dts’s includes), wired to this
board’s own &i2c3/GPIO23/GPIO24 facts from
docs/research/hdmi-hotplug.md §1–§2 — not a copy of LILYGO’s
reference-tree fallback. Target 720p60 as the initial mode. Verify
the DTB compiles and the graph resolves with
nix build .#deviceTree pointed at the new dtbName
(nix/device-tree.nix’s existing dtbName parameter), and inspect
the compiled DTB with dtc -I dtb -O dts to confirm exactly one
&dsi port@1 endpoint (the LT9611’s) and no RM69A10 panel node —
this task does not attempt to make both coexist in one DTB (that is
group 4’s problem, if it is solved at all).
Done 2026-09-28: nix/device-tree.nix gained a dtsFile parameter
(default unchanged, ./dts/k230-tdisplay.dts); flake.nix exposes
the alternate board as deviceTreeHdmi
(dtbName = "k230-tdisplay-hdmi.dtb",
dtsFile = nix/dts/k230-tdisplay-hdmi.dts). nix build .#deviceTreeHdmi produced
/nix/store/048wxyx0pnmb6ydcr9j1q3w3hldnjl36-k230-tdisplay-hdmi.dtb.
dtc -I dtb -O dts confirms exactly one &dsi port@1 endpoint
(dsi_out_lt9611) and no rm69a10/canaan,universal/
touchscreen node anywhere in the decompiled tree. The LT9611 node
deliberately uses port@0/port@2 (not the vendor
k230-canmv-v3.dts’s port@1/port@2) — see the node’s own
comment and docs/research/hdmi-hotplug.md §4 for why, read
directly from this kernel’s lontium-lt9611.c. Confirmed the
default deviceTree output is unaffected (nix build .#deviceTree
still builds the byte-identical k230-tdisplay.dtb path). Host
build only; not booted.nix/dts/k230-tdisplay.dts unchanged): verify with
nix build .#nixosConfigurations.k230.config.system.build.toplevel.
This proves the patch is inert on the panel boot path before any
board time is spent on it.
Done 2026-09-28: succeeded,
/nix/store/2hjv5ksw5fbhazi94hxymc91kqzjdz9c-nixos-system-nixos-26.11.20260919.20b1ddd.
Default DTB and boot path untouched.The operator dropped original tasks 3.1–3.3 and the Settings reboot/self-revert
requirement because automatic cable switching works. These tasks were not
performed and are not marked complete. The parked prototype at 58498320 and
unmerged draft at 6b0ad375 are historical, with no shipping requirement or
physical recovery claim. See docs/evidence/hdmi-hotplug/live-switch/scope-decision-2026-10-09.md.
The staged monitor and combined trials passed their named host and physical gates. Their historical records retain the distinction between cable status, visible output, input modes and navigation acceptance. Precise timing was explicitly deferred by the operator, not measured or passed.
&dsi port@1
endpoint, coexisting
with the active panel node. Verify the DTB compiles and the LT9611
driver probes (a kernel log line, not yet a working bridge) with the
panel still the active display. Host proof:
nix build .#kernelMainlineDrmShellHpdMonitorBootFiles; the bundle
includes the kernel and deviceTreeMainlineDrmHpdMonitor. Board proof:
flock -w 120 /tmp/k230-board.lock python3 tools/console.py /dev/ttyACM0 --wait=5 "dmesg | grep -i lt9611".
If this cannot be made to probe without contending with touch (per
the shared GPIO24 reset polarity mismatch in docs/research/hdmi-hotplug.md
§1), record that finding and stop this task group here.
2026-10-09 source preflight: the existing driver rejects a node with
no remote DSI input and then attaches a DSI device on successful
probe. A DT-only standalone monitor is insufficient; see
docs/evidence/hdmi-hotplug/live-switch/source-preflight.md. The matching volatile monitor boot and real
unplug/replug now pass serial/sysfs checks on an unchanged boot ID,
with the panel connected/enabled throughout and the operator affirming
the panel/replug. This completes the named monitor/probe gate; real
touch and visible handoff remain unproved in task 4.3. No live-switch
result is claimed. The
status-only prototype now exposes /sys/bus/i2c/devices/*-003b/hpd,
masks the bridge’s HPD IRQ sources and leaves all DSI/GPIO ownership
unchanged; plug/unplug observations are required before task 4.2.design.md: keep panel and LT9611 attached,
give them separate non-cloning encoders on the single CRTC, and use
complementary connector detection with 250 ms HPD work and generic
DRM polling as fallback. Select each
consumer’s lane/PHY settings, preserve panel callbacks and splash
handoff, and mask LT9611 interrupt sources when no bridge IRQ exists.
Touch remains the sole owner of GPIO23/24 throughout; do not hand
those shared nets between drivers or tear down live DRM components.
Enable the existing input relay in the daily mainline system, choose
trackpad only for enabled HDMI scanout, and restore direct panel
mapping/calibration on return. Expose the combined tree through the
separate kernelMainlineDrmShellHotplugBootFiles trial bundle before
promoting it to normal boot/sdImage. Host proof:
nix build .#kernelMainlineDrmShellHotplugBootFiles --max-jobs 1 --cores 16,
matching compiled graph/boot-bundle inspection, plus native relay
cargo test and cargo clippy --all-targets. These do not prove 4.3.
2026-10-09: the first persistent-consumer bundle built, passed the
compiled graph and 15 inspector fixtures, and booted with the
operator confirming HDMI/trackpad → panel/direct touch → HDMI. Relay
44 unit and two integration tests plus Clippy passed. Exact tuple and
report: docs/evidence/hdmi-hotplug/live-switch/runtime-first-serial-boot.json
and runtime-first-operator-report.json. The faster 250 ms worker
passes object compilation, the full matching bundle build, compiled graph
and 15 inspector fixtures. The matching faster volatile trial is accepted
by the operator: HDMI replug takes a couple of seconds, panel return is
almost instant. See fast-host-checks.json, fast-runtime-serial-boot.json
and fast-runtime-operator-report.json in the same evidence directory.
The later navigation qualification is recorded under 4.3; precise
sampled latency is explicitly deferred by the operator; approximate
visible timing is not a sampled HPD measurement.docs/evidence/hdmi-hotplug/live-switch/.
2026-10-09: physical fast switching is accepted (HDMI a couple of
seconds, panel almost instant), and the response “it works great land it”
confirms the requested real-touch navigation checks. Matching state
retains the trial boot ID, portrait rotation and virtual touchpad.
fast-runtime-qualification.json records the exact question context.
The bounded watcher captured no cable transitions: fast-runtime-latency.json
correctly returns INCOMPLETE_OR_SLOW with an empty transition list.
The operator subsequently said “ignore latency measurement good enough
for now”. The named physical switching and
navigation gate is complete; precise timing is deferred, not performed
or passed. No failed measurement is inferred from the empty watch.
See docs/evidence/hdmi-hotplug/live-switch/closeout-2026-10-09.md.specs/display/hdmi/spec.md’s no-reboot requirement: either resolve
its <!-- UNVERIFIED --> marker against working board evidence, or
restate it as a known-infeasible-with-current-architecture finding
with the specific blocker named, so a future change does not have to
rediscover it.
2026-10-09: recorded working mainline no-reboot switching against the
accepted faster physical trial and exact qualification. The normal bundle
and default SD image now match that accepted candidate; persistent
installation and ordinary autoboot pass in
docs/evidence/hdmi-hotplug/live-switch/normal-hotplug-install-serial.json.
Precise sampled timing is explicitly deferred in 4.3; manual reboot scope is now canceled, landscape transfers to its successor,
and unrelated historical UNVERIFIED markers remain explicit.Original tasks 5.1–5.4 and their layout/physical requirements are preserved in
the-hdmi-shell-works-in-landscape, landed as a separate proposal before this
archive. Its implementation and real monitor gates remain unchecked. Shared
geometry work continues to belong to the-shell-adapts-to-output-resolution.
Task 5.1 now uses automatic switching and exclusive outputs rather than the
canceled reboot path, retaining its original rollback build command and adding
the shipping mainline bundle check. See the committed scope-decision report.
6.1 Validate this change and preserve every unresolved hardware
requirement as <!-- UNVERIFIED --> until its named evidence exists;
verify with
openspec validate plugging-in-hdmi-moves-the-display --strict.
2026-10-09: strict validation passed after recording the mainline
live workaround. Group 7’s HDMI trial is subsequently accepted;
automatic switching is subsequently physically accepted under 4.3; historical
probe/vendor-only limitations retain their UNVERIFIED markers.
6.2 Run python3 scripts/render_work_board.py > /dev/null, commit,
and hand off to the coordinator for an early merge to master per
AGENTS.md, independent of whether groups 3–5 have started — the
proposal and the research document are the reviewable deliverable at
this point, not a private preface to the board work.
*2026-10-09: the work-board renderer passed. The planning artifacts
were already landed at `94196f97`; the continuation commits preserve
the remaining source and physical gates for the landing handoff.*
The board now boots mainline 7.3.0-rc5 by default
(openspec/changes/archive/2026-10-08-the-board-boots-mainline-by-default/),
and there /sys/class/drm shows only card0-DSI-1: no HDMI. The mainline DRM
port already carries the K230 LT9611 driver (nix/patches/mainline/drm/lontium-lt9611-k230.c,
DRM_LONTIUM_LT9611=y) and drm_bridge_connector_init() in canaan_dsi.c.
The accepted automatic implementation runs on mainline. Landscape transfers
to its separate successor; the manual Settings reboot scope is canceled.
nix/patches/lt9611-dsi-port-b.patch does, because GPIO24/GPIO23 belong to the GT9895 touch. Proof: nix build .#kernelMainlineDrm.nix/dts/k230-tdisplay-mainline-drm-hdmi.dts (LT9611 on &i2c3 at 0x3b, DSI port@1 → LT9611 port@1 (Port B) → hdmi-connector, touch keeps GPIO24/23, no panel), a dtsFile parameter for nix/device-tree-mainline-drm.nix, and flake outputs deviceTreeMainlineDrmHdmi and kernelMainlineDrmShellHdmiBootFiles (the normal bundle with the HDMI DTB under k230-tdisplay.dtb). Proof: DTB builds and decompiles; host inspection of the bundle.
2026-10-09: the corrected full kernel and HDMI bundle build, DTB
graph/reset inspection, bundle identity inspection and 15 inspector
fixtures pass. Commands and immutable hashes are recorded in
docs/evidence/hdmi-mainline/fixed-host-checks.json,
fixed-dtb-check.json and fixed-bundle-inspection.json.
This is host proof, not a board boot.tools/coherent-shell-board-boot.py (a plain reboot returns to the panel). Record the HDMI-A-1 connector, EDID mode, LT9611 probe and hsfreqrange messages, a native grim capture, and the operator’s report of the picture and touch-as-trackpad. Tune canaan,hsfreqrange if the link fails. Proof: serial record and operator report in docs/evidence/hdmi-mainline/.
2026-10-09 continuation: the original trial recovered HDMI after
touch’s shared reset and the operator reported “screen works”.
The corrected kernel/bundle then built, staged and passed a matching
fresh volatile trial with automatic HPD, a 256-byte EDID, native
terminal/Home captures and the configured relay grabbing touch.
An ordinary protected panel reboot also passed serial checks.
Evidence is committed in docs/evidence/hdmi-mainline/README.md.
The operator subsequently accepted the fresh trial: “yeah hdmi works
great it’s perfect continue lmk what you need”. Exact report and
matching read-only state are in operator-acceptance.json; no
photograph, per-gesture trace or latency measurement is inferred.Describe the board-specific HDMI path, shared hardware constraints, qualification outputs and accepted automatic handoff between the monitor and handheld panel.
The board’s Lontium LT9611 DSI-to-HDMI bridge SHALL be confirmed present and
addressable on &i2c3 at 0x3b, alongside the existing GT9895 touch
controller at 0x5d on the same bus, through a read-only probe that drives
no GPIO differently from today’s normal panel boot.
Grounding: schematic T-Display K230_V1.0_NEW.pdf sheet “HDMI+ETH” places
the LT9611 (U18) on the net pair HDMI_CSCL/HDMI_CSDA, which sheet
“Video“‘s net-label table ties to I2C3_SCL/I2C3_SDA — the same bus as
touch (docs/dts-evidence.md, docs/research/board-capability-inventory.md).
No address collision (0x3b vs 0x5d).
Grounding: observed 2026-09-29 (docs/evidence/hdmi-hotplug/probe/lt9611-probe-2026-09-29.md):
&i2c3 is Linux adapter i2c-1. 0x3b acknowledges and returns chip ID
0x17 0x02 (rev 0xe2), and 0x5d is bound to gt9895. The ID read used the
mainline driver’s page-select writes. Touch input was not re-exercised in that
session.
i2cdetect -y is run against the &i2c3 adapter while the
board is booted normally, with touch active0x3b and 0x5d appear as answering addresses, and touch
continues to report input events normally afterwardThis project SHALL treat the DSI data lanes, clock, and the touch/LT9611 reset and interrupt GPIOs as literal shared electrical nets, not as independently controllable per-consumer signals, in every design and DT change this capability makes.
Grounding: schematic sheet “K230” wires the SoC’s MIPI_TX0_CLK_P/N and
MIPI_TX0_D0_P/N..MIPI_TX1_D3_P/N pins to net labels DSI_CLK_P/N and
DSI_D0_P/N..DSI_D3_P/N; sheet “HDMI+ETH” wires the LT9611’s MLRXB_*
MIPI-RX-port-B pins (49–58) to the identical net labels. Sheet “Video“‘s
net-label table ties HDMI_RSTN→TP_RST (LT9611 reset = touch reset,
GPIO24) and HDMI_INT→TP_INT (LT9611 interrupt = touch interrupt,
GPIO23) as single unbroken wires, not a jumper between two nets. The vendor
LT9611 DT node (k230-canmv-v3.dts:64,66, in the pinned kernel tree)
requests GPIO_ACTIVE_HIGH reset and IRQ_TYPE_EDGE_FALLING; our touch
node (nix/dts/k230-tdisplay.dts:200,224) requests GPIO_ACTIVE_LOW reset
and IRQ_TYPE_LEVEL_LOW on the same physical pins. No mux, switch IC, or
isolation component appears anywhere between the SoC, the panel connector,
and the LT9611 on the schematic. Full detail in
docs/research/hdmi-hotplug.md §1.
&dsi’s graph, differently from touch
or the panel’s existing behaviorThe separate HDMI-only qualification and recovery path SHALL expose an
HDMI-A-1 DRM connector through this board’s own LT9611 device-tree wiring,
loaded at boot. This fallback remains available alongside the combined
mainline runtime arrangement described in the no-reboot requirement.
The panel-only qualification tree retains its panel-only graph.
Historical baseline grounding: drivers/gpu/drm/canaan/canaan_dsi.c’s canaan_dsi_bind()
calls drm_of_find_panel_or_bridge(dsi->dev->of_node, 1, -1, &dsi->panel, &dsi->bridge) exactly once, at component-bind/boot time (line 695 in the
pinned Xuantie kernel tree); no code path re-invokes this lookup, and
canaan_dsi_detach() (line 560) only clears state when the attached child
device itself unregisters. Every vendor source found selects HDMI the same
way: LILYGO’s own abandoned board-specific merge attempt
(k230_bsp patch 0055-riscv-dts-add-rm69a10-hdmi-output-dtb.patch) and
their shipped, working fallback (patch
0062-riscv-dts-rm69a10-hdmi-use-sdk-v3-baseline.patch, which #if 0s the
merge attempt and #includes the unrelated k230-canmv-v3.dts instead)
both produce a separate DTB, never a merged one. Their shipped launcher
UI, k230_launcher/k230_phone_ui/src/ui_hdmi_test.c, switches by copying a
DTB file and calling reboot() (ui_hdmi_test.c:312-343). Full detail in
docs/research/hdmi-hotplug.md §3–§4.
The kernel’s DSI-bridge-attach code path SHALL create a working DRM connector for the bridge, as established by the group-2 host build and the accepted group-7 mainline trial.
Grounding: canaan_dsi_bind()’s bridge branch
(canaan_dsi.c:713-714) calls drm_bridge_attach(..., NULL, DRM_BRIDGE_ATTACH_NO_CONNECTOR) and nothing in canaan_dsi.c or
canaan_drv.c calls drm_bridge_connector_init() (checked by direct grep
of both files in the pinned kernel tree) — so an LT9611 node in any DTB we
build produces an attached bridge with no connector until this is patched.
Grounding: observed 2026-10-09 on the shipping mainline path: the group-7 kernel and
board-specific mainline HDMI tree passed a matching volatile boot, automatic
connected status and 256-byte EDID, native shell/cursor captures, and the
operator’s acceptance. See docs/evidence/hdmi-mainline/README.md. The
vendor kernel/tree pair above remains host-only; the obsolete Settings reboot requirement is canceled by the operator.
/sys/class/drm/card*-HDMI-A-1/status reports connected and
the monitor shows a real image, not only that the sysfs node exists/sys/class/drm/card*-DSI-1/status reports connected, touch
reports input events, and no LT9611-related kernel log line appears,
since that DTB carries no LT9611 nodeWith the combined mainline device tree, the system SHALL switch the active output to HDMI when a monitor is plugged in and return to the panel on unplug, without a reboot. It SHALL preserve the accepted HDMI portrait rotation and trackpad input, and restore direct touch when the panel becomes active again. The separately qualified HDMI-only and panel-only boot trees remain available for recovery; their presence does not require a manual Settings reboot control.
Grounding: docs/research/hdmi-hotplug.md §5 names three concrete,
schematic- and source-grounded blockers this goal must clear: the physical
HDMI hot-plug-sense pin is wired only to the LT9611 itself
(HDMI_HPD→HPD_GPIO2, schematic sheet “HDMI+ETH”), not to any
independent K230 GPIO, so detecting a plug event at all requires the LT9611
to already be a live, probed I2C device while the panel device tree is the
one running; the shared GPIO24 reset net (see “DSI lanes are shared wiring”
above) forbids independently resetting either chip after their initial
power-on reset; and canaan_dsi.c has no live panel/bridge re-attach path
in the surveyed baseline (see the HDMI-only qualification requirement
above). The runtime re-plan keeps both consumers registered and uses two
exclusive encoders with 250 ms HPD work and generic polling as fallback,
rather than adding live re-attachment.
Touch retains both shared pins; their unknown electrical drive type is not
used as an assumption for shared-IRQ operation.
Grounding: observed 2026-10-09: the first combined trial established both visible
switching directions with trackpad on HDMI and direct touch on return. The
matching faster kernel trial was accepted by the operator: HDMI replug took
“couple of seconds”, panel return was “almost instant”. A later “it works
great land it” confirms the requested cable/navigation checks; the qualification
records that question context rather than inventing per-gesture traces.
Read-only state before and after acceptance retains boot ID
cff529ad-6aa6-4a31-b9af-337bbc783521, enabled HDMI at the accepted portrait
transform and virtual touchpad. See
docs/evidence/hdmi-hotplug/live-switch/fast-runtime-operator-report.json,
fast-runtime-qualification.json and fast-runtime-qualified-state.json.
No-reboot switching works on this tested mainline arrangement. The matching
normal bundle is installed and ordinary autoboot is observed separately in
docs/evidence/hdmi-hotplug/live-switch/normal-hotplug-install-serial.json
and normal-hotplug-runtime-state.json. The separate
sampled HPD-to-connector ≤1s and HPD-to-enabled ≤3s targets remain unmeasured:
the bounded watcher captured no transitions. The operator explicitly deferred
precise latency measurement on 2026-10-09; no sampled result is claimed. See
docs/evidence/hdmi-hotplug/live-switch/closeout-2026-10-09.md.
Operator-visible approximate
timing is evidence for the 30s scenario ceiling, not those precise targets.
Touch’s reset (GPIO24) and interrupt (GPIO23) lines SHALL be treated as shared with the optional LT9611 HDMI bridge, not as touch-exclusive pins, by any future change to this capability. The panel’s own reset and enable lines (GPIO22/GPIO25) are not part of this sharing and are unaffected.
Grounding: schematic T-Display K230_V1.0_NEW.pdf sheet “Video” ties
HDMI_RSTN→TP_RST and HDMI_INT→TP_INT as single unbroken wires — the
LT9611’s reset and interrupt pins are the same physical nets as touch’s,
not merely the same GPIO number reused in a different device tree. The
vendor’s own LT9611 device-tree node (k230-canmv-v3.dts:64,66, pinned
kernel tree) requests GPIO_ACTIVE_HIGH reset and IRQ_TYPE_EDGE_FALLING
on these pins, while this board’s touch node
(nix/dts/k230-tdisplay.dts:200,224) requests GPIO_ACTIVE_LOW reset and
IRQ_TYPE_LEVEL_LOW — a real disagreement on the same wire, not a
cosmetic one. Full detail, including the specific schematic sheets and net
labels, in docs/research/hdmi-hotplug.md §1–§2.
The vendor baseline nix/dts/k230-tdisplay.dts carries touch only,
matching the vendor sources surveyed (docs/research/hdmi-hotplug.md §3).
The later mainline HDMI tree from task group 7 combines touch and LT9611
without giving the bridge reset/IRQ ownership: its polling bridge waits
for the touch driver to bind before programming the shared-reset device.
That matching trial and the operator’s acceptance are recorded in
docs/evidence/hdmi-mainline/README.md.
While an HDMI connector is the active display output, the GT9895 touchscreen’s raw
ABS_MT_* contact stream SHALL be exclusively grabbed (EVIOCGRAB) and
re-emitted through a virtual uinput device declared with touchpad
properties (INPUT_PROP_POINTER + INPUT_PROP_BUTTONPAD, BTN_TOOL_FINGER/
_DOUBLETAP/_TRIPLETAP, no INPUT_PROP_DIRECT), so that libinput
classifies it as a touchpad and provides pointer motion, tap-to-click,
two-finger scroll, and pinch/swipe gestures for the HDMI session, in place
of the panel-mode absolute touch-to-output mapping. Qualified two-contact shell gestures and three-contact bottom keyboard gestures
may instead translate to the existing logical touch policies through the bounded
shell gesture path; ordinary application center scrolling/pinch and pointer input
remain on the touchpad path. While the panel (not
HDMI) is the active output, the touchscreen SHALL be left ungrabbed and
unmodified, continuing to report absolute coordinates as
display/touch’s existing digitizer-range requirement already states.
Grounding: host relay/mode/ioctl tests and the independent Linux-header
comparison (cargo test); the earlier host udev classification in
docs/evidence/the-touchscreen-becomes-an-hdmi-trackpad/host-uinput-classification.md;
and the real contact/operator checkpoint plus installed-board service probes
in docs/evidence/the-touchscreen-becomes-an-hdmi-trackpad/board/.
The operator confirmed cursor motion, and Sway classifies the actual virtual
device as a touchpad with tapping enabled. The operator subsequently accepts the HDMI trackpad as working;
docs/evidence/proposal-closeout/2026-10-01/trackpad.md records that acceptance and earlier panel-return feedback.
The later accepted automatic cable cycle, matching unchanged boot identity
and normal installation are recorded in
docs/evidence/hdmi-hotplug/live-switch/fast-runtime-qualification.json,
docs/evidence/hdmi-hotplug/live-switch/normal-hotplug-install-serial.json and
docs/evidence/hdmi-hotplug/live-switch/normal-hotplug-runtime-state.json.
It does not manufacture individual per-gesture observations.
connected per /sys/class/drm/*/status
and a finger drags across the touchscreenArchived change · Archived
Snapshot 5836ef1d113d · 2026-10-17 08:22 UTC
Closed recordReview the archived record and cited scope
The board’s installed default is now the mainline 7.3.0-rc5 coherent shell
(docs/evidence/mainline-default-boot/, docs/evidence/mainline-sd-throughput/),
but nix build .#sdImage still produces the vendor 6.6 kernel with the older bar
session. A freshly flashed card would not match the board everyone tests on.
.#sdImage is built from nixosConfigurations.k230-mainline-drm-shell, with
that system’s mainline kernel and the mainline DRM device tree written as
k230-tdisplay.dtb. Stage 1 and the card layout are unchanged.mkBoardImage takes the device tree as an optional argument (default: the
vendor tree), so sdImage-coherent, sdImage-rvv-trial and the other vendor
images are unchanged..#sdImage is independent of the mainline build.Non-goals: the release tool’s sdImage-coherent target and published
releases; deleting the vendor images; changing stage 1.
system/kernel: the flashable default image ships the mainline kernel; the
mainline-isolation requirement no longer covers .#sdImage.flake.nix (mkBoardImage, sdImage). The image derivation changes; the
boot partition (112 MiB) holds the 43 MiB mainline Image and 27 MiB initrd.mkBoardImage cfg kernel (flake.nix) always used the vendor device tree
package. kernelMainlineDrmShellBootFiles already presents the mainline DRM
tree as k230-tdisplay.dtb for the installed board.
Goals: .#sdImage produces the same system, kernel, initrd and DTB the board
runs today. Every vendor image stays byte-identical.
Non-Goals: release tooling (sdImage-coherent) and stage-1 changes.
mkBoardImageWith { cfg, kernel, deviceTree ? vendor } is added, and
mkBoardImage becomes a wrapper for it, so existing callers keep the same
derivations. Tasks check this by comparing drvPaths.mainlineDrmDeviceTreeNormalName.
The boot bundle and the image share it, so they cannot drift.boot.kernelPackages.kernel.mkBoardImage an optional device tree and build .#sdImage from k230-mainline-drm-shell with its kernel and the mainline DRM DTB as k230-tdisplay.dtb. Proof: nix build .#sdImage, plus an inspection of the boot partition (kernel identity, DTB /chosen/bootargs init, stage-1 slot hashes) recorded in docs/evidence/mainline-sd-image/.
Image 20mxf9lr…; boot Image/initrd.uimg byte-identical to the installed bundle p3hh3j32…; DTB and bootargs.txt init= select installed system kp6ldmdx…; DTB has the SD sd_ref core clock; stage-1 slots equal .#stage1 (inspection)..#sdImage-coherent evaluates to the same derivation as on master. Proof: matching nix eval --raw .#sdImage-coherent.drvPath before and after.
sdImage-coherent i7sfnn3k… and sdImage-rvv-trial xqnk1nz1… drvPaths identical before and after.running, no failed units, root grown to 59 G (evidence).openspec validate --strict, CI run id, page revision.
Strict validate passes; landed e1334c83; CI/Pages run 37837179903 success; https://knewter.github.io/tdisplay-k230/work/ serves e1334c83f1ab. Change stays open for 2.1.nix build .#sdImage SHALL produce a card image whose root holds the
k230-mainline-drm-shell system and whose boot partition holds that system’s
mainline kernel, its initrd, and the mainline DRM device tree under the
filename stage 1 loads, with stage 1 unchanged.
.#sdImage and inspects its boot partitionImage is the mainline 7.3.0-rc5 kernel of k230-mainline-drm-shell, k230-tdisplay.dtb carries the mainline DRM tree with /chosen/bootargs selecting that system’s init, and the stage-1 slots match .#stage1
Grounding: host inspection 2026-10-08 (docs/evidence/mainline-sd-image/host-inspection.json): boot Image/initrd.uimg byte-identical to the installed mainline bundle, DTB /chosen/bootargs init selects kp6ldmdx…, stage-1 slots equal .#stage1.docs/evidence/mainline-sd-image/README.md): flashed over U-Boot ums, first power-on reached login on 7.3.0-rc5 with the three shell services active and no failed units.The project SHALL provide a mainline-Linux kernel, device-tree, and
boot-files build (.#kernelMainline, .#deviceTreeMainline,
.#kernelMainlineBootFiles) pinned to the newest mainline revision carrying
basic Canaan K230 support, built entirely separately from the pinned vendor
Xuantie kernel .#kernel uses. No vendor package or vendor
nixosConfigurations output SHALL depend on or be changed by this build
existing. .#sdImage deliberately ships the mainline system (see “The
flashable default image ships the mainline coherent shell”).
Grounding: nix/kernel-mainline-src.nix pins torvalds/linux at the
dereferenced v7.3-rc5 commit — the newest tag with
arch/riscv/boot/dts/canaan/k230.dtsi present, confirmed absent at v7.2
by direct tag diff. nix/kernel-mainline.nix and
nix/device-tree-mainline.nix share no code path with nix/kernel.nix or
nix/device-tree.nix; flake.nix’s new kernelMainline/
deviceTreeMainline/kernelMainlineBootFiles outputs are additive only.
nix build .#kernelMainline.#kernel has ever been built.#nixosConfigurations.k230.config.system.build.toplevel
or .#sdImage-coherentnix/kernel-mainline.nix, nix/kernel-mainline-src.nix,
nix/device-tree-mainline.nix, and this change’s other new files did not
existPowering on or rebooting the board SHALL boot the mainline kernel and the full coherent shell without operator intervention, and the vendor 6.6 kernel SHALL remain restorable as the default by a recorded, tested rollback.
docs/evidence/mainline-default-boot/README.md): ordinary reboot after install and after reinstall, and one reset-button power-on (reset-button-postboot.json), each 7.3.0-rc5, mainline system/profile, three services active, running, no failed units.docs/evidence/mainline-default-boot/README.md): install.py rollback PASS with every restored file re-hashed against its backup, then an ordinary boot on 6.6.36 with the vendor profile.This selection is board state installed from .#kernelMainlineDrmShellBootFiles;
.#sdImage ships the same mainline system for freshly flashed cards.
Archived change · Archived
Snapshot 5836ef1d113d · 2026-10-17 08:22 UTC
Closed recordReview the archived record and cited scope
The Apps catalog presents Foot Client, Foot Server, and Htop as equal generic “Installed application” cards. A person cannot tell which action is useful without launching it.
runtime/app-launcher: a curated, refreshable action catalog above desktop-entry discovery.None.
Userspace launcher/catalog and its host fixtures; no compositor, cards, video lifecycle, or hardware change. Board review is needed for optical/readability and real-finger proof.
Current native evidence shows generic page-two cards for Foot Client, Foot Server, and Htop. GLib remains the sole desktop-entry parser/launcher.
A curated entry can become stale; fixture coverage must test refresh, unknown entries, and a failed launch retaining controls.
python3 tests/test_desktop_catalog.py. Host proof (6/6): docs/evidence/launcher-curation/host.md.python3 tests/test_launcher_navigation.py && python3 tests/test_desktop_catalog.py. Host proof (4/4 and 6/6): docs/evidence/launcher-curation/host.md. Back recovery is tested in the page model only; its rendered visibility is checked in 2.2.nix build .#touch-launcher. Completed 2026-10-02 with the coordinator-owned build slot: six remaining derivations built and the riscv64 launcher artifact passed; exact source, command and output are recorded in docs/evidence/launcher-curation/cross-build.md. This does not complete the board gate in 2.2.python3 tools/capture-feature.py launcher-curation --provenance real-touch --duration 30 --description 'Curated Apps catalog and recovery' --output-dir docs/evidence/launcher-curation; inspect target geometry/readability before marking complete. Done 2026-10-08 by operator real-finger report in place of capture (operator request), native drawer capture and shell-log corroboration: docs/evidence/launcher-curation/operator-board-2026-10-08.md.Provide a refreshable portrait Apps catalog whose cards explain the action a person will take.
The shell SHALL present useful desktop applications with an action-oriented name and short description, and SHALL hide or demote known implementation endpoints that do not represent an independent person-facing task. It SHALL retain the existing built-in Terminal, Monitor, New terminal, and Help actions.
The catalog SHALL preserve page bounds, 56px-or-larger actionable targets, and visible Back/Apps recovery when a launch fails.
Archived change · Archived
Snapshot 5836ef1d113d · 2026-10-17 08:22 UTC
Closed recordReview the archived record and cited scope
On the board’s default mainline kernel the SD card reads at 6.1 MB/s, against
23.3 MB/s on the vendor 6.6 kernel with the same card, the same High-Speed 4-bit
3.3 V mode and the same CPU speed
(docs/evidence/mainline-sd-throughput/README.md). Every boot, package
activation and app launch pays for it. The SDHCI driver derives its base clock
from the core clock’s rate. Vendor binds core to a fixed 100 MHz clock;
our mainline DTS binds it to the 333 MHz HS_SD*_BASE_GATE, so the driver
divides by 8 and the card actually runs at about 12.5 MHz.
Three smaller mainline leftovers ride along: the PDMA driver takes its AXI gate
twice, the guarded trial tool’s “returned to normal” check still looks for a
6.6.36 banner that the new mainline normal never prints, and an intermittent
mmc1: Got command interrupt ... even though no command operation was in progress register dump appears on about 1 in 6 mainline boots.
core clock, as
the vendor tree does. The driver patch keeps holding HS_SD*_BASE_GATE under
a new base name, so no gate becomes unclaimed.k230-peridma.c drops the redundant single-clock claim; the bulk claim
already holds every PDMA clock.tools/mainline-drm-system-trial.py detects a premature return to normal
by the installed normal’s kernel string from the committed baseline rather
than a 6.6.36 literal.Non-goals: UHS/1.8 V signalling (both kernels cap at High-Speed 50 MHz), switching
.#sdImage to mainline, and the audible headset check.
system/kernel: SD storage and the SDIO radio run at the vendor kernel’s
clock rate under mainline.nix/dts/k230-tdisplay-mainline.dts, nix/patches/mainline/k230-sdhci-clocks.patch,
nix/patches/mainline/k230-peridma.c; the mainline kernel and boot bundle rebuild.tools/mainline-drm-system-trial.py and its tests.sdhci-of-kendryte.c (vendor driver forward-ported, nix/patches/mainline/) sets
SDHCI_QUIRK_CAP_CLOCK_BASE_BROKEN, so host->max_clk is clk_get_rate("core").
Vendor k230.dtsi binds core (and bus) to dummy_sd, a 100 MHz fixed-clock.
Our mainline DTS binds core to K230_HS_SD{0,1}_BASE_GATE, a child of the
333 MHz SD AXI source in mainline clk-k230.c. The driver therefore programs
/8 for 50 MHz. The measured 6.1 MB/s matches a 100 MHz reference divided by 8.
Earlier mainline work found that every SD gate must stay claimed, or
clk_disable_unused gates it.
Goals: vendor-equal SD card clock on both controllers with no gate released; remove the PDMA double claim; make the trial tool’s return-to-normal check track the installed normal.
Non-Goals: UHS modes, .#sdImage, upstreaming.
core, BASE_GATE kept as base. A new fixed-clock
node supplies the rate. The driver patch grows its bulk list from
axi/block/timer to base/axi/block/timer, so BASE_GATE stays prepared and
enabled exactly as today. We rejected re-pointing core alone (it would
release BASE_GATE to unused-clock cleanup), a fixed-factor child of the
gate (it encodes a false rate relation), and CLK_IS_CRITICAL (an extra clk
driver patch for what is a consumer description).dummy_sd.mainline-drm-system-trial.py already
loads rd.NORMAL_BASELINE, and the “Linux version ” check uses
its uname. Because normal and candidate now share 7.3.0-rc5, that banner
check alone cannot tell them apart; U-Boot SPL remains the primary signal.actual clock and data integrity (sha256 of a large file read twice).Build, then stage, trial-boot and install through the coherent tools (as in
docs/evidence/mainline-default-boot/). Rollback is the stage’s install.py rollback.
nix/dts/k230-tdisplay-mainline.dts for mmc_sd0/mmc_sd1 and extend k230-sdhci-clocks.patch to claim base; build .#kernelMainlineDrmShellBootFiles. Proof: build succeeds and the DTB decompiles with the new clocks.
Bundle p3hh3j32…; DTB has core=100 MHz sd_ref plus five gates on both controllers; host inspection PASS (b20be921).k230-peridma.c. Proof: kernel builds.
Kernel builds; PDMA claims all four DT clocks via one bulk call.tools/mainline-drm-system-trial.py use the baseline normal uname for its return-to-normal banner check, with a test. Proof: python3 tests/test_mainline_drm_system_trial.py.
39 tests pass incl. NormalBannerTests.mmc0/mmc1 ios, clk_summary for SD gates, dd throughput, a repeated read checksum match and PDMA audio playback without crash. Proof: serial record in docs/evidence/mainline-sd-throughput/.
23.8 MB/s (vendor 23.3), 50 MHz actual on mmc0/mmc1, all SD gates still enabled, checksum repeat match, Wi-Fi associated, PDMA playback exit 0 (evidence).running, no failed units, 23.4 MB/s, Wi-Fi up; baseline moved to postboot.json.Got command interrupt occurrences on this change’s boots, as fixed or as a known leftover. Proof: count in the evidence README.
Scope changed by the operator 2026-10-08 (“i don’t want a 10 reboot count”); originally a ≥10-reboot count. 0 occurrences on 2 boots (trial, installed); recorded as uncharacterised, not as fixed.openspec validate --strict, CI run id, page revision.
Strict validate passes; landed b7c96d28; CI/Pages run 37834870854 success; https://knewter.github.io/tdisplay-k230/work/ serves b7c96d28.Under the mainline kernel, the SD card and the SDIO radio SHALL be clocked at the same card-clock rate the vendor kernel uses (High-Speed, 50 MHz actual), and every SD controller clock gate SHALL stay claimed by its driver.
dd if=/dev/mmcblk1 of=/dev/null bs=4M count=32 iflag=direct on the installed mainline system/sys/kernel/debug/mmc1/ios reports an actual clock of 50000000 Hz and the read rate is within 15% of the vendor kernel’s 23.3 MB/s on the same cardArchived change · Archived
Snapshot 5836ef1d113d · 2026-10-17 08:22 UTC
Closed recordReview the archived record and cited scope
The full coherent shell now runs on the mainline kernel with display, touch,
power key, Wi-Fi, firewall, thermal and audio playback proven on the board
(docs/evidence/mainline-shell-parity-2026-10-06/), but every power-on still
boots the vendor 6.6 kernel. Until mainline is what the board boots by default,
people using the handheld do not get it, and each mainline result stays a trial.
/boot plus the system profile)
becomes the mainline full coherent shell, installed with the existing
rollback-retaining installer (tools/coherent-shell-board-install.py).Non-goals: deleting the vendor kernel or its configuration from the repo (it remains the rollback target and a buildable configuration), touching stage 1 (SPL/U-Boot/OpenSBI) or the DT selector files, upstreaming, and the items the parity change left open (audible headset check, GPU, second core, NPU, camera).
system/kernel: the default boot runs the mainline kernel, with a proven way
back to the vendor kernel.system/nixos-config: the installed daily system is the mainline coherent
shell, and the trial tooling guards that system as the protected normal.flake.nix gains a mainline coherent boot-files output (reusing
nix/coherent-shell-boot-files.nix)./boot mutable files (Image, initrd.uimg, k230-tdisplay.dtb,
bootargs.txt) and /nix/var/nix/profiles/system change; stage 1 and
fw_jump_add_uboot_head.bin/force_dtb/lcd_dtb/hdmi_dtb do not. Every
step needs the physical board and the serial console; the rollback drill and
install each need at least one reboot and possibly an operator reset.tools/ (vendor 6.6.36, vendor
system path) move to the installed mainline identities.ums path (tools/ums-session.py)
can restore /boot from the host if a boot fails before userspace.See proposal.md - Why. Stage 1 loads Image, initrd.uimg,
k230-tdisplay.dtb (bootargs embedded under /chosen) and bootargs.txt from
/boot (/dev/mmcblk1p1), plus fw_jump_add_uboot_head.bin and the
force_dtb/lcd_dtb/hdmi_dtb selectors. tools/coherent-shell-board-stage.py
prepares a host-inspected bundle on the board with a checked backup of the
normal files; tools/coherent-shell-board-boot.py runs a trial boot;
tools/coherent-shell-board-install.py installs a touch-qualified bundle
(replacing only the four mutable files and the profile, preserving rollback GC
roots and a journal) and has a rollback mode. The mainline full shell
(k230-mainline-drm-shell) has only been booted through volatile U-Boot
selection by tools/mainline-drm-system-trial.py.
Goals: reuse the existing stage/trial/qualify/install path unchanged where possible; prove rollback on the board before calling the switch done.
Non-Goals: new installer logic, stage-1 changes, removing the vendor path.
kernelMainlineDrmShellBootFiles by calling
nix/coherent-shell-boot-files.nix with cfg = k230-mainline-drm-shell and a
device-tree wrapper that presents the mainline DRM DTB as k230-tdisplay.dtb
(stage 1 loads that name). Rejected: changing stage 1’s file names or boot
script (touches the vendored chain and every rollback assumption)./boot by hand (no journal, no checked backup).install.py rollback, reboot, verify the vendor kernel and byte-identical
backups, then reinstall mainline and verify again. Recovery of last resort is
the U-Boot ums USB path.6.6.36./boot is written.kernelMainlineDrmShellBootFiles (coherent boot-files layout, mainline DTB presented as k230-tdisplay.dtb) and run the existing host inspection on it. Host proof: nix build .#kernelMainlineDrmShellBootFiles plus python3 tools/coherent-shell-boot-inspect.py on the result.
Bundle rqx0jajd…: host inspection PASS after allowing the k230-mainline-drm-shell configuration name (tests added). Vendor coherentShellBootFiles derivation unchanged.tools/coherent-shell-board-stage.py prepare, adapting tooling only where it pins vendor-only facts (with tests). Hardware proof: stage check passes on the board.
On-board prepare+check READY; staged state. Stage tool now accepts an imported, registered candidate (3 tests).tools/coherent-shell-board-boot.py and complete its touch qualification (operator present). Hardware proof: qualification record.
Trial PASS (7.3.0-rc5, three services). Qualification rests on the operator’s earlier on-glass session with the same system/kernel/shell, re-affirmed for install; the routes were not re-touched on this trial boot ID (see evidence).tools/coherent-shell-board-install.py install; reboot; verify 7.3.0-rc5, installed system booted, shell services active, no failed units; also verify one reset-button power-on. Hardware proof: install journal and post-boot serial checks.
Install PASS and ordinary reboot verified (7.3.0-rc5, running, no failed units, native Home). Reset-button power-on 2026-10-08: 7.3.0-rc5, mainline system/profile, three services active, running, no failed units (record).install.py rollback, reboot, verify vendor 6.6 with byte-identical backups; reinstall mainline and verify again. Hardware proof: rollback-result.json and both post-boot checks.
Rollback PASS, ordinary boot 6.6.36/p1a1hz…; reinstall PASS, ordinary boot 7.3.0-rc5 (evidence).6.6.36. Proof: affected tests pass.
NORMAL_BASELINE → postboot.json; normal system/uname read from it. Remaining 6.6.36 strings in tests are synthetic vendor banners (still valid rejection fixtures). Initrd-shell, system-trial, coherent boot/install/stage, pid1, debug and observer tests pass.openspec validate the-board-boots-mainline-by-default --strict, CI run id, page revision.
Strict validate passes; landed 538bcaeb; CI/Pages run 37647787229 build+deploy success; https://knewter.github.io/tdisplay-k230/work/ serves revision 538bcaeb8977.Powering on or rebooting the board SHALL boot the mainline kernel and the full coherent shell without operator intervention, and the vendor 6.6 kernel SHALL remain restorable as the default by a recorded, tested rollback.
The system profile and /boot mutable files SHALL select the mainline coherent
shell built from this repository, with stage 1 and the DT selector files
unchanged, and the board-side trial tooling SHALL treat that installed system as
the protected normal it verifies before and after every trial.
Archived change · Archived
Snapshot 5836ef1d113d · 2026-10-17 08:22 UTC
Closed recordReview the archived record and cited scope
The full coherent shell now boots on the mainline kernel and draws Home on the
panel, but it is not yet a system someone could use in place of the vendor
kernel: the firewall unit fails, the side button does nothing, there is no
sound and no Wi-Fi, touch has only been proven from evtest on the console
image (never inside sway), and two clock-table defects remain that could bite
the next driver. The console-only mainline kernel also still lacks the clock
fixes that made the DRM kernel boot. Closing these gaps is what stands between
“mainline boots” and “mainline could become the default”.
firewall.service starts on the mainline shell.sound/soc/canaan, dwc_canaan I2S and the peripheral DMA engine) is
forward-ported and playback completes as on the vendor kernel. The bare board
has no speaker; an audible check on the 3.5 mm jack follows when a headset is attached.mmc_sd0 (SDIO) is enabled with owned
clocks, and the RTL8189FTV out-of-tree driver is built against the mainline
kernel (or the trial records exactly why it cannot be, as a successor).evtest events.usb_480m/usb_100m
share 0x100 bit 0 (the vendor shares it too) and why the display clkext
gate stays unmodelled (no consumer; modelling it would expose it to cleanup).spi2axi and vpu_ddrcp2
critical-clock fixes it currently lacks.Non-goals: making mainline the default boot, upstream submission, GPU/VGLite, the second core, NPU/KPU, LoRa, Bluetooth, camera/ISP, and any change to the protected normal (vendor-kernel) system or its boot selection.
system/kernel: mainline variants carry the clock fixes and firewall config;
thermal is forward-ported; ADC/crypto disposition is recorded; clock-table
gates match the vendor map with recorded exceptions.system/nixos-config: the mainline full-shell variant starts every unit the
vendor-kernel system starts, except recorded non-goals.system/audio: audio plays under the mainline kernel.radio/wifi: Wi-Fi associates under the mainline kernel.display/touch: a deliberate finger interaction drives the sway shell under
the mainline kernel.runtime/shell: the power key reaches the shell under the mainline kernel.nix/kernel-mainline.nix, nix/kernel-mainline-drm.nix, new
forward-ported drivers under nix/patches/mainline/ (pwrkey, audio, thermal),
clock patches against drivers/clk/clk-k230.c, DT in
nix/dts/k230-tdisplay-mainline{,-drm}.dts.flake.nix mainline variants; the RTL8189FTV module derivation in
nix/hardware.nix built against the mainline kernel.tools/mainline-drm-system-trial.py touch retrieval.See proposal.md - Why. State on 2026-10-06 (archived
2026-10-06-the-board-runs-a-mainline-kernel): the DRM mainline kernel
(kernelMainlineDrm, 7.3.0-rc5) boots the full coherent shell
(k230-mainline-drm-shell) to the Home UI with ordinary unused-clock cleanup.
That required display/RTC/GPIO clock ownership, spi2axi and vpu_ddrcp2
CLK_IS_CRITICAL, and FOP_UNSIGNED_OFFSET in the canaan DRM fops. Those
critical-clock patches are wired only into nix/kernel-mainline-drm.nix; the
console kernel (nix/kernel-mainline.nix) still builds without them.
Observed gaps on the full-shell boot: firewall.service failed; no PMU
power-key input, sound card, thermal zone or Wi-Fi interface exists; touch was
proven only via evtest on the console image. The controller’s touch phase
timed out reading back ~240 KB of evtest text.
Every physical step uses the established pattern: guarded staging from the
protected normal system, volatile U-Boot selection, controller begin, camera
on the panel, then reboot from the candidate (or an operator reset on
failure) and the reviewed recovery checker. Display/console boots no longer
need operator resets when they pass.
Goals:
Non-Goals:
Move the clock patches to the base mainline kernel (kernel layer).
k230-clk-spi2axi-critical.patch and k230-clk-vpu-ddrcp2-dphy.patch move
from kernel-mainline-drm.nix to kernel-mainline.nix’s patch list so the
console kernel inherits them. Rejected: duplicating the list in both files
(drifts); clk_ignore_unused on the command line (hides future ownership bugs,
and the bisection already identified the specific gates).
Firewall: reuse nix/kernel-firewall.config (kernel config layer). The
vendor kernel appends this fragment; mainline gets the same fragment applied
through its structured config. Rejected: disabling the firewall unit on the
mainline variant (a silent security regression).
Power key: forward-port the vendored k230-pmu-pwrkey.c with a PMU DT node
(kernel + DT). The driver is ours already (LILYGO-vendored); port it
against 7.3 APIs and add the node from the vendor DT, claiming the PMU APB
gate the RTC fix already exposed. Rejected: a userspace GPIO poller (the key
is a PMU interrupt, not a GPIO).
Audio: forward-port sound/soc/canaan (kernel + DT), then verify through
the existing PipeWire session (userspace). Port the I2S/codec driver with
the external-I2S-switch patch and owned clocks (ls_audio_*, ls_codec_*
gates are currently unclaimed). Acceptance needs a heard tone; a USB
microphone recording on the host is acceptable evidence if the operator is
away. Rejected: claiming audio from a registered ALSA card alone.
Wi-Fi: enable mmc_sd0 SDIO with owned clocks (DT), then build the
existing RTL8189FTV out-of-tree module against the mainline kernel (Nix).
If the 6.6-era module does not compile against 7.3, record the first error
set and either patch minimally (API renames) or stop with a successor;
rejected: replacing it with the staging rtl8189fs fork of unknown
provenance without review. Secrets only via the protected path.
Touch in shell: camera-recorded deliberate tap on a Home target (userspace
evidence), compared with the same tap under the vendor kernel. The
controller’s touch retrieval switches to a bounded board-side summary
(counts of down/up/positions/SYN) printed as one framed line, keeping the
raw evtest log on the board for optional retrieval. Rejected: raising the
timeout (still scales with touch length).
Clock table (documentation, no kernel change). The vendor tree gates
usb_clk480 and usb_clk100 on the same 0x100 bit 0, so mainline’s shared
bit is faithful hardware, not an alias to fix. Mainline leaves the vendor
disp_clkext gate (0x74 bit 5) unmodelled; Linux never writes it, U-Boot’s
setting stands and the panel works. Rejected: adding a display_clkext
gate (with no consumer it would be gated by unused-clock cleanup, the bug
class this work removed) and splitting the USB bits (would model hardware
that does not exist). Commit the comparison table with these reasons.
Thermal (kernel + DT): forward-port canaan_thermal.c with the vendor
bounded-read-loop fix. ADC/PWM/crypto: inventory first; port only if a shipped
unit consumes them, else record non-goal.
clk_summary, hold/bisect) proven on the display.k230-clk-spi2axi-critical.patch and k230-clk-vpu-ddrcp2-dphy.patch into nix/kernel-mainline.nix and append nix/kernel-firewall.config to the mainline kernel config. Host proof: nix build .#kernelMainline .#kernelMainlineDrm --no-link and the built .config contains the firewall symbols.
Built 725cc92e: full-shell bundle 8bljkjxn…, console bundle bwvzapyq…; kernel config has NETFILTER_XTABLES/NF_TABLES/NFT_COMPAT/NFT_CT=y (structuredExtraConfig looped on NFT_COMPAT; seeded into defconfig instead).systemctl is-active firewall is active and systemctl --failed is empty. Hardware proof: guarded tools/mainline-drm-system-trial.py begin on kernelMainlineDrmShellTrialBootFiles, then recover.
2026-10-06 bundle 8bljkjxn…: controller qualified; serial console shows uname 7.3.0-rc5, firewall active, 0 failed units, shell/shell-ui/seatd active; board self-recovered (private capture ~/tmp/k230-bisect-PARITY12).clk: Disabling unused clocks, 0 failed units. Needed the SD five-clock ownership moved to the base kernel (first attempt stalled after initrd Basic System). Its reboot then stopped at “Restarting system” (restart handler was DRM-only), fixed in 6f86eed2: console bundle j05znfgq… then booted, rebooted itself into the normal system, and protected recovery passed with no operator reset.docs/research/ with the recorded reasons for the shared USB bit and the unmodelled clkext gate. Proof: committed file; openspec validate the-mainline-shell-reaches-parity --strict.
Comparison committed with the shared-USB-bit and clkext reasons.evtest read-back with a bounded board-side summary line in tools/mainline-drm-system-trial.py, with fixtures. Host proof: python3 tests/test_mainline_drm_system_trial.py and a new focused test.touch --real-touch reports complete contact; camera recording.
Board results: controller touch --real-touch complete contact (bounded summary, 4 taps) on the full mainline shell; operator reported the shell responded normally. Camera missed the taps (board lifted).k230-pmu-pwrkey.c to 7.3 with a PMU DT node claiming the PMU APB gate. Host proof: nix build .#kernelMainlineDrm and the object has the driver.
Kernel built (ky3ac6dg…); on the board K230 PMU Power Key registers (IRQ 175).evtest summary.
Same session: operator pressed the side button and reported the power sheet; camera still shows the sheet; sway journal logged the output power action; evtest saw no events because the shell holds the input grab.sound/soc/canaan with the external-I2S-switch patch and owned audio/codec clocks; DT nodes from the vendor tree. Host proof: kernel builds; aplay -l lists the card in a board boot log.
Kernel built with PDMA and audio; on the board /proc/asound/cards lists K230_I2S_INNO with playback and capture PCMs.
Partial: driver/DT/Kconfig forward-ported and compile-verified (module build + dtc). The DMA blocker is now also resolved: drivers/dma/k230_peridma.c forward-ported as nix/patches/mainline/k230-peridma.c (mainline dmaengine driver for canaan,k230-pdma, claims K230_SHRM_PDMA_AXI_GATE), wired into nix/kernel-mainline.nix, with a &pdma DT node and dmas/dma-names added to the i2s node in nix/dts/k230-tdisplay-mainline.dts — module-compile (W=1, zero warnings) and dtc/cpp validated, same evidence classes as the rest of this task. Board-proven (new finding): with the DMA blocker resolved, a trial boot found that starting ALSA playback against mainline’s generic sound/soc/dwc/dwc-i2s.c (compatible snps,designware-i2s, this task’s prior choice) freezes the whole SoC, even with clk_ignore_unused/pd_ignore_unused; the vendor 6.6 kernel’s own fork (sound/soc/dwc_canaan/, compatible canaan,snps,designware-i2s) does not freeze, and differs in real register programming, not just API currency (most likely cause: mainline’s generic driver unconditionally unmasks an IMR interrupt source this board’s i2s DT node has no handler for). Forward-ported that fork as nix/patches/mainline/dwc_canaan/{canaan-dwc-i2s.c,canaan-dwc-pcm.c,canaan-local.h,Kconfig,Makefile}, wired into nix/kernel-mainline.nix (CANAAN_SND_DESIGNWARE_I2S Kconfig symbol), and changed the i2s DT node’s compatible string accordingly — module-compile (W=1, zero warnings, two Kconfig configurations) and dtc/cpp re-validated. No full kernel build or board boot of THIS driver swap has been run yet: aplay -l proof, a full kernel build, and a non-frozen speaker-test run all remain open. See docs/research/mainline-audio-port.md and docs/evidence/mainline-audio-port/{pdma,dwc-canaan}-*.json.speaker-test -D plughw:0,0 -c1 -t sine -f 440 -l1 completes on the full mainline shell as on the vendor kernel (exit 0, same period/buffer sizes) and the console stays responsive. Hardware proof: trial boot and the command result. The audible headset check on the 3.5 mm jack is a follow-up for the operator, not part of this task.
2026-10-06 bundle lmzbqfsk… with ordinary cleanup: speaker-test exit 0, buffer 48000, 2.09 s/period (vendor 2.0 s), console responsive, 0 failed units (board results). Needed the vendor dwc_canaan I2S, PCM-before-DAI registration, and PDMA ownership of the SHRM APB/AXI-slave/SRAM gates. Audible headset check remains an operator follow-up.mmc_sd0 SDIO with owned clocks in the mainline DT and build the RTL8189FTV module against the mainline kernel. Host proof: nix build of the module for the mainline kernel, or a committed failure log with a successor task.
nix build .#k230-wifi-driver-mainline produces 8189fs.ko (vermagic 7.3.0-rc5); on the board the SDIO card enumerates, 8189fs/cfg80211 load and wlan0 is up.
Partial: &mmc_sd0 enabled with its base two clocks in nix/dts/k230-tdisplay-mainline.dts and the three extra K230_HS_SD0_{AXI,CARD,TIMER}_GATE clocks in nix/dts/k230-tdisplay-mainline-drm.dts (mirrors the existing &mmc_sd1 pattern), dtc/cpp-validated. Module-compile attempt against the pinned mainline dev tree found and fixed four real v7.3-rc5 API-drift classes (kbuild EXTRA_CFLAGS->ccflags-y, timer API rename, pppoe uapi flexible-array restriction, strncpy removal) as nix/patches/mainline/rtl8189fs-mainline-v7.3-rc5.patch, wired via a new extraPatches parameter on nix/k230-wifi-driver.nix and a new k230-wifi-driver-mainline flake output (vendor-kernel k230-wifi-driver unaffected). Committed failure log: the module does not link — CONFIG_CFG80211 is not set in the dev tree (added as a candidate module to nix/kernel-mainline.nix, itself unbuilt) and ioctl_cfg80211.c’s cfg80211_ops callbacks need a real net_device*->wireless_dev* port, out of this task’s rename-only scope. See docs/research/mainline-wifi-port.md and docs/evidence/mainline-wifi-port/*.json. No nix build, full kernel build, or board action was run.k230-wifi active; separately recorded associated=yes, ipv4=yes, gateway ping=yes using the existing protected credential path; no SSID or address recorded (private capture ~/tmp/k230-parity-wifi-thermal).canaan_thermal.c (bounded read loop) with its DT node. Host proof: kernel builds.
Kernel built; on the board canaan_thermal_zone reads 7218 (vendor kernel 7223).docs/research/mainline-kernel-inventory.md. Proof: committed inventory diff.
Inventory records ADC/PWM and crypto as non-goals (no shipped consumer) and power key, thermal, audio and Wi-Fi as ported.openspec validate the-mainline-shell-reaches-parity --strict, CI run id, page revision.
Independent branch review PASS (stale-comment corrections applied in a5d442d5); master a5d442d5; CI 37564415470 build/deploy PASS; work page serves a5d442d5 and the parity evidence page returns 200.On the mainline full shell, a deliberate finger tap or drag on the panel SHALL reach sway and change what the shell shows, as it does under the vendor kernel.
docs/evidence/mainline-shell-parity-2026-10-06/README.md): controller complete contact (4 taps) on the full shell; operator reported the shell responded. Camera did not capture the taps.On the mainline full shell, the RTL8189FTV radio SHALL appear as a wireless interface and join a protected network using the existing runtime-only secret path; credentials never enter the system closure, evidence or logs.
docs/evidence/mainline-shell-parity-2026-10-06/README.md): SDIO card enumerates, 8189fs/cfg80211 load, wlan0 up.docs/evidence/mainline-shell-parity-2026-10-06/README.md): associated, IPv4 assigned, gateway reachable, each checked separately; no identifiers recorded.On the mainline full shell, pressing the board’s power button SHALL produce the same shell response as under the vendor kernel (the power sheet), because the PMU power-key input device exists.
docs/evidence/mainline-shell-parity-2026-10-06/README.md): operator press brought up the power sheet; camera still and sway journal agree.On the mainline full shell, PCM playback to the board’s audio card SHALL complete the same way it does under the vendor kernel, through the DMA path, without freezing or otherwise disturbing the running system. The bare board has no speaker or buzzer (the MAX98357A amplifier is on an optional base board that is not fitted), so audible output is checked separately on the 3.5 mm jack when a headset is attached.
speaker-test -D plughw:0,0 -c1 -t sine -f 440 -l1 on the mainline shelldocs/evidence/mainline-shell-parity-2026-10-06/README.md): exit 0, 48000-frame buffer, 2.09 s periods with ordinary cleanup; console responsive.Each mainline kernel the repository builds (console and DRM) SHALL keep running the
clocks that physical bisection showed the SoC needs (spi2axi, the display DDR port
vpu_ddrcp2) and SHALL carry the same firewall kernel configuration as the vendor
kernel. The protected normal system is not changed by this.
docs/evidence/mainline-shell-parity-2026-10-06/README.md): console variant qualified login with cleanup, then rebooted itself to normal.systemctl is-active firewall reports active on the serial console
Grounding: observed on hardware 2026-10-06 (docs/evidence/mainline-shell-parity-2026-10-06/README.md): firewall active on the full mainline shell.Every mainline gate SHALL use the register bit the vendor clock tree uses, and any deliberate difference (a bit the vendor shares between clocks, or a vendor gate mainline leaves unmodelled) SHALL be recorded with the reason, so a driver claiming one clock cannot silently change another device.
usb_480m/usb_100m share 0x100 bit 0 exactly as the vendor usb_clk480/usb_clk100 do; the display clkext gate (0x74 bit 5) stays unmodelled because no Linux consumer exists and modelling it would expose it to unused-clock cleanup
Grounding: read from source 2026-10-06 (docs/research/k230-clock-gates-vendor-vs-mainline.md): mainline clk-k230.c against the vendor k230_clock_provider.dtsi, matched by register and bit.The mainline kernel SHALL expose the K230 thermal sensor so that a person at the console can read the SoC temperature, matching the vendor kernel’s reading within the sensor’s resolution.
docs/evidence/mainline-shell-parity-2026-10-06/README.md): 52.4 °C idle, 54.5 °C after 60 s load (vendor driver reports raw codes).ADC, PWM and crypto SHALL each be recorded as forward-ported, or as an explicit non-goal naming which shipped service would need them; none may be silently absent.
docs/research/mainline-kernel-inventory.md): no shipped unit, package or tool consumes ADC, PWM or the crypto engine.The k230-mainline-drm-shell variant SHALL start every systemd unit the
vendor-kernel coherent shell starts, except units listed as recorded non-goals
with their reason, and it SHALL remain an opt-in trial that never replaces the
protected normal system or its boot selection.
systemctl --failed on the serial console lists no units other than recorded non-goals
Grounding: observed on hardware 2026-10-06 (docs/evidence/mainline-shell-parity-2026-10-06/README.md): 0 failed units, firewall active (before the netfilter fragment it failed).Archived change · Archived
Snapshot 5836ef1d113d · 2026-10-17 08:22 UTC
Closed recordReview the archived record and cited scope
The original host milestones below are historical build records. Committed
physical trials in
docs/evidence/mainline-display/physical-2026-10-01/README.md observe Linux
7.3-rc5, DRM/fb0, Goodix input registration and photographed panel boot text,
but no usable mainline root or deliberate touch. Later PID1 shell probes
reached /bin/true; the minimal trial’s systemd reboot refusal did not reach
the kernel. The protected normal system was independently restored by an
operator power cycle, recorded in
docs/evidence/mainline-display/physical-2026-10-01/minimal-probe-recovery-2026-10-02/README.md.
These are partial boot/probe/recovery observations, not product acceptance.
Task 5d.4 now has physical proof for the targeted five-clock candidate
without clk_ignore_unused: ordinary clock cleanup, kernel restart → SPL →
protected normal return with fresh identity and unchanged boot hashes,
recorded in docs/evidence/mainline-sd1-clocks/physical-no-flag-2026-10-03/README.md.
The earlier global-clock comparison remains historical evidence. Task 5b.5
stays open for ordinary NixOS root activation and deliberate touch.
Today’s kernel is a pinned vendor fork, ruyisdk/linux-xuantie-kernel @
7d4e1f444f461dbe3833bd99a4640e7b6c2cd529 (Linux 6.6.36, nix/kernel-src.nix),
carrying eleven local patches (nix/kernel.nix) that exist only because that
tree is old, undermaintained upstream, and missing fixes this board’s bring-up
needed: a bounded DSI PHY wait, a bounded thermal loop, an RTC day-of-month
mask bug, a DCS-read backport, a touch driver backport, and more. Nobody
outside this project reviews that tree, security fixes land on it only if
someone backports them by hand, and every future Linux feature (newer
schedulers, newer DRM, newer RISC-V vector support) requires either a manual
backport or staying frozen at 6.6 forever.
Mainline Linux has been gaining real Canaan K230 support since late 2025:
arch/riscv/Kconfig.socs’ ARCH_CANAAN, a pinctrl driver
(drivers/pinctrl/canaan/pinctrl-k230-iomux.c, PINCTRL_K230), a reset
driver (drivers/reset/reset-k230.c, RESET_K230), a clock driver
(COMMON_CLK_K230), and a basic arch/riscv/boot/dts/canaan/k230.dtsi +
k230-canmv.dts/k230-evb.dts all merged for the v7.3 window (too late for
v7.2, confirmed: git show v7.2:arch/riscv/boot/dts/canaan/ lists only K210
files). A USB-PHY driver and its device-tree binding for K230 were also
accepted upstream (Vinod Koul, lkml.org/lkml/2026/2/27/1255) but the DT node
wiring it into k230.dtsi has not landed as of this writing. An SDHCI series
(sdhci-of-dwcmshc.c reuse, v5 as of March 2026, “tested successfully on
CanMV-K230-V1.1 with AP6212 SDIO on MMC0 and MicroSD on MMC1”) is still under
review on linux-riscv, not yet merged into any tagged or master tree
checked here. There is still no mainline display (canaan-drm/VO/DSI),
touch, audio, RTC, PMU/power-key, thermal, ADC, PWM, GPIO, or crypto driver
for this SoC — panel-canaan-universal.c, canaan_drv.c, rtc-k230.c,
canaan_thermal.c, k230-adc.c, k230-pmu-pwrkey.c, canaan_k230_inno.c
all return HTTP 404 from torvalds/linux today (checked directly via
gh api repos/torvalds/linux/contents/<path>, 2026-09-29); the GT9895 touch
driver this project backported (goodix_berlin) is, unusually, already
upstream on its own merits, since it was itself a v6.12 mainline driver we
backported onto the older vendor tree.
So mainline cannot run this handheld’s shell today, and won’t be able to for some time — the display stack alone is a from-scratch driver effort with no public work in progress found. But mainline can now be built for this SoC, and getting there — a real cross-build, a real device tree, a real forward port of what applies — is work worth doing in parallel with the vendor-kernel image, so that: (1) the day mainline gains a usable display driver, this project is not starting from zero; (2) our patches that fix generic-Linux bugs (not Canaan-driver bugs) have a known home; and (3) the board has a path to a maintained, security-patched kernel for its console/network/storage functions even before the display works.
docs/research/mainline-kernel-inventory.md) covering every function
docs/research/board-capability-inventory.md already names, with a fourth
column this project has not written before: mainline driver status,
cited by file existence (gh api .../contents/<path> returning 200 vs.
404) and, where a driver is genuinely missing, the exact in-review patch
series if one exists..#kernelMainline, .#deviceTreeMainline, and a boot-files output) pinned
to a specific mainline commit that carries basic K230 support
(v7.3-rc5, the newest tag with arch/riscv/boot/dts/canaan/k230.dtsi
present; there is no stable release with K230 support yet — v7.2 does not
have it). This does not touch .#kernel, .#deviceTree,
nixosConfigurations.k230, or .#sdImage — the shipped image keeps
booting the vendor Xuantie kernel unchanged.nix build .#kernelMainline, .#deviceTreeMainline) and names the actual
first hardware milestone as “boots to a serial console” — not “SD rootfs” —
because mainline has no merged storage driver for this SoC yet; SD rootfs
and USB networking are later milestones explicitly gated on upstream
patches this project does not control the timeline of.system/kernel requirements recording that a parallel mainline build
exists, that the default system is unaffected by it, and what its current
hardware ceiling is — the same pattern already used for the optional RVV
trial kernel in this same capability.gpio-k230.c), SD/MMC (sdhci-of-kendryte.c) and USB
(dwc2 parameter/register hunks) from the pinned vendor tree onto the
mainline pin, with matching device-tree nodes; add a full NixOS system
variant (nixosConfigurations.k230-mainline-console) that boots this
kernel, with the out-of-tree Wi-Fi kernel module excluded (no expectation
it compiles against a kernel seven major versions newer than its origin);
and produce matching boot files (Image, a DTB with this system’s real
bootargs baked in, and its initrd wrapped for U-Boot) so a future
one-shot boot attempt has everything staged. Two real vendor-to-mainline
API migrations were found (by a failed build, not by inspection) and
fixed against mainline’s own already-migrated reference drivers — see
docs/research/mainline-kernel-inventory.md and design.md decisions 7–10
for the full account. Still entirely host-only; no board action taken.system/kernel: adds requirements for the parallel mainline build
(existence, non-default status, and its recorded hardware ceiling).
Existing requirements (the vendor kernel is pinned and its patches
recorded; the RVV trial retains normal recovery; vector execution is
gated by kernel/context support) are unchanged.None. This is infrastructure inside the existing system/kernel capability,
not a new user-observable capability — nothing about what the shipped
handheld does changes.
nix/kernel-mainline-src.nix, nix/kernel-mainline.nix,
nix/dts/k230-tdisplay-mainline.dts, nix/device-tree-mainline.nix,
nix/kernel-mainline-boot-files.nix, nix/patches/mainline/{gpio-k230.c, sdhci-of-kendryte.c}, flake.nix (new package/nixosConfigurations outputs
only, no changes to existing ones), docs/research/mainline-kernel-inventory.md,
openspec/specs/system/kernel/spec.md. No change to nix/kernel.nix,
nix/kernel-src.nix, nix/device-tree.nix, nix/k230.nix,
nix/hardware.nix, nix/sd-image.nix, nix/shell.nix, or any existing
nixosConfigurations output — confirmed by git diff --stat against each
after every task group, including the milestone-1 continuation. The original
functional proof was host-only (cross-builds, including a full NixOS
system-closure build). Later physical trials obtained partial boot/probe
evidence as summarized above; usable root and deliberate touch remain named open gates for the board
operator; automatic restart is now physically proved for the targeted five-clock
candidate without the temporary clock bypass.
The isolated DRM continuation also provides k230-mainline-drm-trial and
kernelMainlineDrmTrialBootFiles: a console system built against the DRM
candidate, its matching initrd/bootargs and closure inventory, and an offline
root-stage/manual U-Boot procedure. nix/mainline-drm-trial.nix,
tools/mainline-drm-trial-inspect.py, and
docs/evidence/mainline-display-boot-preparation.md own this host-only
preparation. The normal system profile and boot files remain selected; card staging
and partial physical boot/probe evidence are now committed, while task
5b.5 remains open for usable root and deliberate touch.
A further bounded, coordinator-authorized continuation forward-ports the
vendor’s K230 genpd controller and binding into the optional DRM candidate
and wires the display domain before a physical trial. Prior vendor-board
DSI failure/resolution evidence grounds this dependency; mainline runtime
behavior remains UNVERIFIED. This touches only
nix/kernel-mainline-drm.nix, nix/patches/mainline/k230-power-domains.c,
the local power-domain binding header, the DRM DTB builder/DTS and candidate
DRM master’s runtime-PM error handling. Console/default variants and clock/
reset choices remain outside this continuation. Full candidate/DTB/boot-bundle
builds prove the source artifacts; task 5b.5 still requires the board.
A console operator cannot yet rely on a mainline diagnostic trial returning
itself to the protected normal system. The 2026-10-02 minimal trial reached
the initrd shell, but systemd refused its reboot request before the kernel
was called; subsequent normal recovery needed an operator power cycle.
The read source audit in
docs/evidence/mainline-display/physical-2026-10-01/mainline-restart-source-audit-2026-10-02.md
finds no advertised SBI SRST in the candidate logs and no restart handler in
mainline’s peripheral reset driver. This is a separate recovery dependency,
not an explanation for the missing usable NixOS root.
Group 5d adds the pinned vendor K230 restart register sequence to the
optional kernelMainlineDrm only, using the pinned mainline managed restart
API, checked probe-time mapping and registration, and device-owned cleanup.
The source/API object proof, complete kernel build, matching trial bundle,
and physical restart/normal recovery are separate gates. Record host proof
under docs/evidence/mainline-restart/; keep physical restart UNVERIFIED and
5b.5 open until their named observations exist.
This continuation owns nix/kernel-mainline-drm.nix and a narrow patch
under nix/patches/mainline/. No stage-1/OpenSBI change, userspace register
write, reboot-controller change, new reset address, mainline pin update, or
vendor/default/console-only kernel change is in scope. Board and serial work
belong to the reserved operator after review and matching bundle proof;
host work requires no board reservation.
The same-image Bash trial produces a fresh userspace prompt but cannot answer
one of eight bounded receipt attempts; ordinary NixOS startup remains unproved.
docs/evidence/mainline-system-trial/shell-pid1-physical-2026-10-03/README.md
records this physical boundary and distinct pending operator recovery. The next
increment provides a separate opt-in mainline kernel diagnostic to distinguish
cached driver receive progress, actual UART/timer interrupt accounting and
reporter scheduling without requiring foreground shell commands.
Add a runtime-gated, normal-priority finite kernel reporter, at most six samples across approximately thirty seconds. Validate UART0 binding inside the 8250 core, copy cached counters/state using nonblocking lifecycle/port try-locks, and obtain actual mapped UART and RISC-V timer IRQ identities. Release every lock before emitting one bounded fixed public SBI record per sample. Keep ordinary logging, clock/reset/interrupt settings, shell PID1/async policy and qualified controls unchanged. This experiment observes software state; it neither reads UART registers nor proves physical FIFO/baud or Bash delivery.
Source/API/object tests, optional complete kernel/matching bundle, unchanged existing derivations, host protocol tests and one protected physical comparison are separate gates (group 5f). No default image, stage 1, production fix, extra core bring-up, TTY polling/configuration, priority/affinity change or automatic recovery claim is included. Runtime output and interpretation are UNVERIFIED until this named operator trial. Ordinary-root/panel/glass task 5b.5 stays open.
The finite comparison recorded in
docs/evidence/mainline-uart-progress/physical-2026-10-03/README.md reached the
fresh matching kernel arguments and Bash prompt, attempted one receipt, and
captured neither a receipt nor any of six expected reports. DBCN capability
detection was printed. There are no UART/timer counters to interpret. The
first report follows worker scheduling, a five-second sleep, cached snapshot
and firmware output; that observation cannot distinguish those boundaries.
Group 5g adds a separately selected breadcrumb variant of the existing finite reporter. It attempts only two fixed public direct-SBI records: worker-entry before its first sleep and first-post-sleep before its first snapshot. Keep all six existing sample records, delays, cached getter behavior and normal priority unchanged. Both exact runtime gates are required for breadcrumbs; new named source/kernel/system/object/trial outputs preserve every existing package/source/trial identity. The normal card profile and boot selection stay protected. Typed controller qualification and strict parsing are a separate implementation task, not an implicit extension of the existing mode.
This is a kernel/Nix/controller observability refinement within the existing mainline change. No IRQ, TTY, PID1, clock/reset, firmware, console-policy or priority/affinity change is included. A visible record proves reaching its firmware call, not that it returned; absence leaves scheduling/output unknown. Native/source/object/full-artifact checks and one protected physical comparison remain separate gates. Breadcrumb output, RX delivery, automatic return and ordinary-root/panel/glass acceptance remain UNVERIFIED; task 5b.5 stays open.
The committed breadcrumb packet at revision 278769d0 records both worker points, a matched fresh receipt and numeric n0/n1, but no n2–n5 during the bounded 180-second capture. Its result is independently reviewed. The subsequent operator reset passed guarded fresh protected normal postflight and Home observation; its distinct recovery receipt does not qualify automatic return. A complete n1 line does not show its firmware call returning, or the worker reaching its third wakeup. No counter value, IRQ fault or ordinary-root result is inferred from that gap.
Group 5h adds a separately named layered diagnostic variant with two fixed public records: immediately after the n1 numeric SBI call returns, and after the n2 sleep/stop check before snapshot. Preserve the six samples, existing breadcrumbs, sleeps/getters/stop behavior, normal priority and every existing package/source/config/trial identity. A new exact runtime gate requires both existing progress/breadcrumb gates. Two single attempts bring the worker’s maximum to ten writes; no fallback, retry or wall-clock firmware guarantee.
This refines kernel/Nix/controller observability in the open mainline change. No IRQ/TTY/PID1, clock/reset, console, firmware, scheduler policy or production fix is included. Source/native/exact-object/full-artifact/controller and one protected physical comparison remain distinct gates. New output and recovery are UNVERIFIED; ordinary-root/panel/glass task 5b.5 remains open. The plan lands before source implementation, and only the reserved operator uses the board.
Group5h’s matching source/objects/full artifacts and positive controller gates passed. Its independently reviewed physical capture reached worker-entry/Bash, but no receipt, numeric samples or new points in180.0975s; the committed physical packet and deployment receipt preserve that incomplete result. The subsequent NEW operator reset passed guarded fresh normal postflight and reviewed Home evidence. No return from entry’s output, first sleep completion or later point is proved. This leaves the ordinary mainline acceptance requirement and task5b.5 open.
The PostSample capture reached worker-entry/Bash but no receipt or later samples/points, unlike the prior n0/n1 result. Group5i adds a separately selected intervention: preserve six sleeps/cached snapshots/stop checks, suppress all worker output, record progress in ordinary memory and let one independent observer attempt a final summary. Read source and limits show firmware console locking and unbounded UART polling as possible dependencies, not a diagnosed cause or proven installed-firmware identity. No new MMIO, IRQ/TTY/PID1/firmware/console-policy/scheduler change. New comparison remains UNVERIFIED; ordinary root/panel/glass task5b.5 stays open. Fresh protected normal recovery is required before another trial. Land this plan before source work.
The Memory physical capture records fresh args/Bash, one attempted stimulus and no receipt/summary in 180.1021s. Group 5j adds a separately typed controller-only zero-stimulus comparison against the SAME qualified lznjjfx1 image/dev/source/config/DT and identical volatile bootargs. No kernel rebuild or runtime firmware/IRQ/TTY/timer change. Strict summary and protected normal gates remain; receipt becomes NOT_REQUESTED and RX NOT_TESTED. A difference under withheld input is not its cause or RX acceptance. Missing summary remains unknown; fresh operator recovery is required first. Land this bounded plan before implementation; 5b.5 stays open.
The zero-input capture
reached Bash but no summary in 180.0995s with zero stimulus. Group 5k adds one
separately typed idle-polling comparison: append only bare volatile nohlt to
that same Memory image’s qualified bootargs and retain zero candidate input.
Read source/config/linked setup
support this bounded discriminator without a rebuild. No IRQ/MMIO/firmware,
worker/observer, affinity/priority or production power-policy change. A result
can show idle/tick-policy dependence, not its cause. New runtime selection,
summary and recovery remain UNVERIFIED; ordinary task 5b.5 stays open. Fresh
normal recovery and actual host qualification precede one boot. Land this plan
before controller implementation.
Polling received nohlt/Bash but no summary in 180.0929s; subsequent NEW reset restored protected normal/Home. The timer/backend audit found no grounded timer-DT switch and observed a registered Linux8250 ttyS0 console. Group 5l adds a separately gated source/controller variant: retain Memory progress and observer wait/snapshot, replace its one final explicit DBCN attempt with one ordinary KERN_INFO Linux-console summary in a distinct K230_UMK1 namespace. A leading newline in that same call separates the summary from Bash prompt output; timestamp-prefixed complete-line parsing stays strict. Baseline zero-input policy remains; no combined nohlt, raw MMIO, force/emergency printing, fallback, retry, IRQ/firmware/priority change or production fix. This requires a new matching kernel build and exact artifact/controller proof; all previous package/source/config/trial identities remain unchanged. Native, target-object, full build, physical output and recovery are separate. A record supports observer progress through the changed output path, not cause or API return. Silence remains unknown; ordinary 5b.5 stays open. Land this plan first.
The MemoryPrintk physical capture
reached Bash with exact arguments and a registered Linux console, but no observer
record or automatic normal return in 180.1019 seconds. Group 5m tests one remaining
tick-policy dependency using the same already-built p2 MemoryPrintk image: append
only volatile nohz=off, retaining zero candidate input. The
source/config/Image audit
grounds this option. It disables tickless activation; high-resolution timers and
the RISC-V oneshot/SBI timer path remain. Earlier nohlt already restarts idle
ticks, so its negative result limits this hypothesis without testing the global
nohz activation policy. No kernel/initrd/DT rebuild or firmware/IRQ/MMIO change.
Land typed controller planning first; actual host qualification and NEW protected
normal recovery precede one physical comparison. Runtime policy, observer output
and recovery remain UNVERIFIED; ordinary task 5b.5 stays open.
The same-image nohz-off capture reached Bash readiness but no observer record in 180.025 seconds. Group 5n observes userspace directly: the same p2 Image/initrd/DT runs a fixed Bash-PID1 script that checks PID1/UID0, emits a fresh begin record, sleeps once for five seconds and emits end on success, then attempts an interactive shell. Every reporter/trace/nohz/nohlt gate is absent; no received command is needed. The read source/archive/quoting scout grounds a 503-byte transport, while explicitly leaving native parser execution unproved. Native exact Hush and selected Linux argv proof are mandatory before physical use; do not weaken the generic transport policy or offer arbitrary scripts. No new kernel/initrd/DT build, IRQ/MMIO/firmware change, production fix or ordinary-root claim. Land this bounded plan first. Actual host qualification and NEW protected normal recovery precede one 60-second passive comparison. Missing output remains unknown and ordinary task 5b.5 stays open.
The current p2 ordinary comparison reaches mounted sysroot and starts closure lookup without a usable login. Add one typed logging-only comparison so the operator can distinguish queued dependencies, main-process spawn/exec failure, running closure lookup and completion before activation. Use the same artifacts and protected recovery; no kernel rebuild or new masks/targets. This requires the physical board for its result. Nested shell/syscall tracing and ordinary boot acceptance are outside this diagnostic. Scope and source grounding.
The debug/console run did not provide a systemd banner or usable login. Plan one fixed child comparison lowering only the log level to info, retaining destination, artifacts and all guards. Its result requires the board; kernel rebuilds, new boot targets/masks, tracing and causal claims are outside scope. See observed boundary and plan.
The info/console capture still gave no systemd startup or login. Group5q changes only the logging destination to kmsg at the same info level and immutable build. This needs physical UART evidence; backend selection is a diagnostic comparison, not a console-stall diagnosis or ordinary boot acceptance. Keep all guards and land this plan before source. No rebuild, added tracing/targets/masks or verbosity compensation. Observed boundary and selected-source scope.
The info/kmsg capture still gave no systemd startup or login. Group5r repeats one existing quiet ordinary policy before another intervention, because that policy previously reached closure lookup. No controller selector or artifact changes are needed. This requires the board, reviewed actual qualification and NEW protected recovery; no logging, tracing, target, timer/IRQ or build intervention. Observed boundary and bounded roadmap.
The unchanged quiet repeat did not reach its former closure boundary. Group5s adds one optional finite signed-return record after the selected ramdisk init exec attempt, preserving original init/argv/env and error/fallback behavior. It requires an additive kernel build and physical UART proof; successful exec setup is not userspace execution. Closure and systemd-main instrumentation are outside this bounded change. Observed boundary and source/proof plan.
The built optional outputs were later absent at the pre-UART staging check. Restore and retain the exact pinned host artifacts in5s.2a before physical work; keep earlier successful proof and the current availability failure distinct.
The physical exec-return capture recorded successful exec setup but no systemd startup or login. Group5t adds an optional child kernel variant with two finite PID1 witnesses: after kernel_init returns, and at the first successfully entered userspace syscall. This can separate earlier output-return/kernel-init completion from positive user-mode execution without changing the init executable or adding logging to the unsafe post-exit assembly path. It requires a new matching build and physical UART capture after NEW protected recovery; all outcomes remain UNVERIFIED until then. No systemd instrumentation, kernel return-path bypass, timer/IRQ/MMIO changes, extra log policy, production kernel replacement or ordinary-root acceptance. Source sites, interpretation limits and proof gates are in design.md group5t.
The original host milestones below are historical build records. Committed
physical trials in
docs/evidence/mainline-display/physical-2026-10-01/README.md observe Linux
7.3-rc5, DRM/fb0, Goodix input registration and photographed panel boot text,
but no usable mainline root or deliberate touch. Later PID1 shell probes
reached /bin/true; the minimal trial’s systemd reboot refusal did not reach
the kernel. The protected normal system was independently restored by an
operator power cycle, recorded in
docs/evidence/mainline-display/physical-2026-10-01/minimal-probe-recovery-2026-10-02/README.md.
These are partial boot/probe/recovery observations, not product acceptance.
Task 5d.4 now has physical proof for the targeted five-clock candidate
without clk_ignore_unused: ordinary clock cleanup, kernel restart → SPL →
protected normal return with fresh identity and unchanged boot hashes,
recorded in docs/evidence/mainline-sd1-clocks/physical-no-flag-2026-10-03/README.md.
The earlier global-clock comparison remains historical evidence. Task 5b.5
stays open for ordinary NixOS root activation and deliberate touch.
See proposal.md and docs/research/mainline-kernel-inventory.md (the full
inventory this design was decided from). Grounding, per
.skills/k230-spec-change/SKILL.md’s ordering:
torvalds/linux, checked directly with
gh api repos/torvalds/linux/contents/<path> (200/404) for every
present/missing driver claim, not inferred from changelogs or Kconfig menu
text alone.raw.githubusercontent.com/torvalds/linux/master/... and from the pinned
tag’s tree (git show v7.2:...), not summarized secondhand.nix/dts/k230-tdisplay.dts) and inventory
(docs/research/board-capability-inventory.md), for every claim about
what our board’s console/memory/pinmux already is.Goals: a second, clearly-separate kernel/DTB/boot-files build pinned to the newest mainline revision with basic K230 support; an honest, patch-by-patch accounting of which of our eleven vendor-kernel patches port (answer: none, and why); a phased plan whose first hardware milestone is named correctly (“reaches the serial console”, not “SD rootfs”, because SD is not yet mainlined for this SoC) so a later change is not surprised by that when it tries to prove it.
Original non-goals (superseded by the later bounded continuations):
booting anything on the board (initially host-only, with hardware gates
deferred); changing .#kernel,
.#deviceTree, any nixosConfigurations output, or .#sdImage; forward-
porting the SDHCI or USB-PHY-DT-node patches (named as the next change’s
work, not this one’s); attempting the display/audio/RTC/power-key/thermal
driver gap (no upstream starting point exists to port from, and writing one
from scratch is a project-sized effort of its own, explicitly out of scope
here); adding an initramfs/busybox rootfs (named as a cheap next step, not
built here, to keep this change’s own build scope to “does it compile”).
Pin v7.3-rc5, not v7.2.8 (“latest stable”) or a moving master.
v7.2.8 is what kernel.org calls “latest stable”, but it has zero K230
support — checked directly (git show v7.2:arch/riscv/boot/dts/canaan/
lists only K210/Sipeed files). Basic K230 support merged for the v7.3
window; v7.3-rc5 is the newest tag that exists as of this research,
pinned by its dereferenced commit hash so the build is reproducible
rather than tracking whatever master happens to be on a later day.
Rejected: pinning master directly (moves under us, defeats the purpose
of a pin); waiting for a stable v7.3 (unknown timeline, and the
inventory this change produces is valuable now).
A fully parallel Nix surface, not an .override of the existing
kernel. nix/kernel.nix’s vendor tree and mainline are different
source trees, different defconfigs (k230_defconfig doesn’t exist
upstream), and different Kconfig symbol sets entirely — there is no
sensible “override” relationship the way kernel-rvv-trial.nix overrides
kernel.nix (same tree, same defconfig, one Kconfig+patch delta).
nix/kernel-mainline-src.nix and nix/kernel-mainline.nix mirror the
shape of nix/kernel-src.nix/nix/kernel.nix (a split pin + builder,
for the same device-tree-without-a-kernel-build reason) without sharing
any code path with them.
The board .dts reuses mainline’s own k230-evb.dts as its template,
not k230-canmv.dts. k230-canmv.dts wires pinmux groups for buses
(I2C, SPI, PWM, I2S, a second MMC) that have no matching controller node
in this pin’s k230.dtsi at all — copying it would mux pins for
hardware nothing in this tree can drive, and would invite a false
impression that this change wired up more than it did. k230-evb.dts is
the minimal, honest template: console + memory + the one two-clock
sysclk override, nothing this SoC/tree combination cannot actually
back. Our board’s memory size (1 GiB, 0x40000000) is taken from our
own existing nix/dts/k230-tdisplay.dts, not guessed.
defconfig = "defconfig", not a copied/trimmed vendor defconfig.
Mainline’s own generic RISC-V defconfig is what every other mainline
RISC-V board uses; inventing a K230-specific one here would be
maintaining a defconfig fork for no benefit this early, when the actual
open question is whether the three K230 driver symbols compile against
this base at all. autoModules = false still applies (nix/kernel.nix’s
own reasoning: build what is asked for, not everything nixpkgs’ module
auto-detection can find against a tree this unfamiliar).
No initramfs, no rootfs, in this change’s ORIGINAL scope. Getting
.#kernelMainline and .#deviceTreeMainline to compile was that
scope’s actual, provable deliverable, and building a busybox initramfs
was deliberately deferred as a separate, later task.
Superseded, task group 5: the coordinator directed continuing this
same change into the actual boot-critical porting (“do the actual
porting … so it can mount our SD rootfs”, after merging c5158fa8 to
master) rather than opening a fresh change for it. Rather than a
from-scratch busybox initramfs, task group 5 forward-ports real
GPIO/SD-MMC/USB drivers so the system’s OWN NixOS-generated initrd (the
same mechanism nix/sd-image.nix already uses for the vendor image)
can do the real work — switch-root onto the SD card’s existing,
already-populated ext4 root partition — rather than substituting a
toy ramdisk rootfs that would prove less and still need replacing
later. This is a strictly larger, more capable deliverable than the
minimal initramfs originally sketched, not a smaller one.
Every one of the eleven vendor patches gets an individual disposition
in the inventory, not a summary “none port”. .skills/k230-spec-change/ SKILL.md’s evidence rule applies as much to a negative finding as a
positive one — “cannot port” is a claim exactly like “ported”, and needs
the same file-existence citation per patch, not one blanket assertion
covering all eleven. Rejected: writing only the aggregate conclusion,
which would make a future re-check (once mainline gains, say, an RTC
driver) have to redo this whole inventory instead of updating one row.
Forward-port the vendor’s exact ctl-reg/dwc2_set_k230_params() USB
mechanism, not mainline’s own separately-accepted
phy-k230-usb.c/canaan,k230-usb-phy generic-PHY-framework driver.
Both exist for the same HiSysConfig USB control registers at
0x91585000+; they are not interoperable (different init sequences,
different DT binding shape — phys/#phy-cells vs. a bare ctl-reg
property). The vendor’s mechanism is what this board’s own working
image already runs; the upstream PHY driver has never been exercised
against this board by anyone, as far as this research found. Rejected:
wiring the “more upstream-correct” phy-framework driver instead, which
would mean debugging TWO unproven things at once (a new PHY driver AND
a new DT binding) on the very first hardware attempt, rather than one.
k230-mainline-console, not the coordinator’s suggested
k230-coherent-shell-mainline. The coordinator’s own instruction
named this as an example (“e.g.”), not a requirement. Extending
k230-coherent-shell would pull in Sway/wlroots wanting a DRM/KMS
device (/dev/dri/card0) that does not exist under mainline at all
(no canaan-drm — see the inventory), so the build would either fail
outright on a missing dependency or succeed into a system whose shell
service cannot ever start, silently misrepresenting what this milestone
reaches. k230-console (shell off, already the deliberately minimal
variant system/nixos-config requires) is the honest base. Flagged
explicitly rather than silently substituted.
boot.extraModulePackages/boot.kernelModules force-cleared, not
left alone. nix/hardware.nix’s k230WifiDriver builds the
out-of-tree RTL8189FTV module against config.boot.kernelPackages.kernel
dynamically and unconditionally (not gated by k230.shell.enable), so
swapping the kernel without addressing this would have tried to compile
a driver written against 6.6-era vendor headers against a v7.3-rc5
kernel seven major versions newer, most likely failing the entire
system build. There is also no SDIO DT node enabled for it to bind to
in this milestone regardless (&mmc_sd0 stays disabled — see the
inventory table’s Wi-Fi row). lib.mkForce [ ] on both options, plus
forcing the always-instantiated k230-wifi systemd service off, is the
narrowest fix that keeps the toplevel buildable; the module itself is
simply never evaluated as a build target once mkForce wins the
option merge (k230WifiDriver’s let-bound derivation is never
forced).
Boot files carry no hardcoded root= device path. The system’s
fileSystems."/" (inherited unchanged from nix/hardware.nix) is
{ device = "/dev/disk/by-label/NIXOS_SD"; fsType = "ext4"; }, and
nix/sd-image.nix’s own rootfsImage is built with exactly that
volume label — so the vendor image’s own proven boot flow already
resolves root by ext4 label through the initrd’s generated fstab, not
a raw device node, and its own bootargs construction carries no
root= override either. nix/kernel-mainline-boot-files.nix copies
that same construction. Rejected (and actually shipped once, then
corrected before this change’s evidence was recorded): hardcoding
root=/dev/mmcblk0p2 — a guess about MMC enumeration order that the
label mechanism makes entirely unnecessary, and that would have
silently fought the root=fstab token NixOS’s own kernelParams
already contributes.
RTC ported as a small, real proof the methodology generalizes; the
full DRM display stack scoped but NOT ported, and NOT left half-done
in the committed tree. After milestone 1, the same “copy the vendor
file, build, fix what the compiler names” methodology was applied to
the smallest, most self-contained item in the coordinator’s milestone
3 (RTC) as a genuine additional deliverable, and to the coordinator’s
milestone 2 (display) as scoping only. RTC built cleanly after one
trivial fix; the display stack’s very first file hit a structural DRM
allocation-model change (drm_panel_init() → devm_drm_panel_alloc())
after two Kconfig fixes, and porting all ~3,900 lines plus re-applying
this project’s own ~10 existing panel/DSI/VO patches on top is a
materially larger, multi-file, actively-churned-subsystem task than
anything attempted so far. Rejected: continuing to force a
build-error-driven port of the whole display stack within this same
pass, which risked either running out of budget mid-port (leaving
.#kernelMainline broken, violating this change’s own spec
requirement that it stays buildable) or producing a large amount of
code no one could verify compiles cleanly, let alone runs correctly,
within this session. The scratch trial was reverted
(git checkout -- nix/kernel-mainline.nix, the trial’s
nix/patches/mainline/drm/ directory deleted) rather than committed
as WIP, matching the project’s own convention that a task group ends
with the command that proves it — an unbuildable derivation proves
nothing.
-rc pin, not a stable release. Accepted: the alternative is no
K230 support at all until an unknown future stable tag. The pin is
explicit about this (nix/kernel-mainline-src.nix’s own header) so a
later reader does not mistake it for a release-quality target..dts’s console-pin assumption is unverified. Both trees’
device trees leave UART0 pinmux entirely to U-Boot’s FPIOA table (neither
programs a pinctrl consumer group for it), and our board’s existing
vendor .dts already asks for serial0 as its console the same way —
but “neither tree touches the mux” is not the same claim as “U-Boot
configures the pins mainline’s UART0 driver expects”, and only a board
boot settles that. Named explicitly as this change’s first open hardware
gate, not asserted as working.struct gpio_chip’s generic-chip fields (bgpio_init()/.read_reg/
.write_reg/.bgpio_lock) were replaced by struct gpio_generic_chip
sometime after this file’s 6.6-era vendor origin, and
sdhci_pltfm_free() was removed outright. Both were fixed against
mainline’s own already-migrated reference drivers
(gpio-dwapb.c/sdhci-of-dwcmshc.c), not guessed — but this is a real
signal that forward-porting a 6.6-era file onto a v7.3 tree is not a
mechanical copy in general, only in the specific cases checked here.
USB’s dwc2/{params.c,core.h,core.c} hunks happened to need no such
migration (confirmed by a clean build), but that is a fact about this
one function/struct pair, not a general property of the USB subsystem;
a future forward-port (touch’s I2C plumbing, say) should expect to hit
the same class of problem and budget for it.nix/dts/k230-tdisplay-mainline.dts are a best-effort mapping from ID
names alone (e.g. K230_HS_SD0_BASE_GATE for the SDHCI functional
clock, K230_HS_SD0_AHB_GATE for the register-bus clock), not confirmed
against any vendor clock-tree documentation or working configuration.
They are syntactically valid and let each driver’s mandatory clk_get
calls succeed at probe time, which is as far as a host build can check.
Wrong gate/reset selection would surface as a probe failure or a
hung/misbehaving peripheral on the board, not a build failure — squarely
the first hardware milestone’s job to find, not this one’s.The original task 5a.2 records why the first milestone-3 display trial was
reverted. The coordinator later authorized continuing that port as a
separate, opt-in kernelMainlineDrm derivation. Its DRM, DSI, universal
panel, and LT9611 sources live under nix/patches/mainline/drm/, copied
from the vendor-derived working port and kept out of kernelMainline and
all default outputs. The pin is still Linux v7.3-rc5; this does not change
the kernel source pin or claim that pin is the latest kernel.org release.
The first source/API increment replaces removed generic fbdev setup with
the pinned tree’s DMA fbdev/client API, updates the changed atomic helper
and platform remove signatures, and removes drm_driver.date. The exact
prepared-header external-module result is in
docs/evidence/mainline-display-api-compile.md. This is useful compiler
feedback, but the unresolved modpost symbols mean it is not a complete
in-tree kernel build. The opt-in deviceTreeMainlineDrm source and matching
kernelMainlineDrmBootFiles collector now exist. Host cpp/dtc/round-trip
proof is recorded in docs/evidence/mainline-display-dtb.md. The full kernel,
DTB, and boot-files derivations now build successfully; their paths and the
first link failure/correction are recorded in
docs/evidence/mainline-display-nix-build.md. The initial host candidate omitted the vendor display power domain because
the pin has no upstream sysctl_power provider; the locally forward-ported
continuation below addresses that source gap. Physical probe, panel, and
touch behavior remain open tasks.
k230-mainline-drm-trial extends the mainline console profile with the
separate DRM kernel, retaining its disabled out-of-tree Wi-Fi module and
label-based root configuration. It supplies the candidate’s own NixOS
initrd and exact system init= path through
kernelMainlineDrmTrialBootFiles. The recipe writes both DTB bootargs and a
volatile U-Boot environment import file because the vendor stage 1 can
overwrite DTB bootargs (nix/sd-image.nix and
docs/evidence/hardware-boot.txt). The root-stage procedure copies the exact
closure beside the normal system and leaves its selected profile and normal
boot files untouched. The Image+DTB-only collector remains available.
Rejected: pairing the DRM Image with an arbitrary existing initrd/system or
changing the normal card’s boot selectors. These hide the kernel/system
boundary or undermine the recoverable trial. Host build and artifact matching
are recorded in docs/evidence/mainline-display-boot-preparation.md.
The committed October 1/2 records now establish card staging, partial
boot/probe/photographed boot text, and distinct protected normal recovery;
usable mainline root and deliberate touch remain unperformed.
Layer: kernel genpd provider, candidate DRM runtime PM, and candidate device
tree. Forward-port drivers/soc/canaan/k230-power-domains.c and
include/dt-bindings/soc/canaan,k230_pm_domains.h from the pinned vendor
revision 7d4e1f444f461dbe3833bd99a4640e7b6c2cd529. Preserve the full five-domain
one-cell ABI, register offsets, enable/write-enable bits and AI repair logic.
Use per-device state, checked genpd registration with partial-failure cleanup,
and omit unused hardlock variables/property reads: the vendor reads them but
never uses them. Keep the vendor controller compatible string on both sides.
Only the DRM candidate selects the provider and adds its DT binding header.
The existing DRM master already pins DISP at probe, before modesetting. Use a
checked runtime-PM acquisition, keep that reference throughout successful
binding, and release it on probe failure/removal. The logical display master
receives the vendor DISP domain; VO/DSI clock/reset wiring stays as before.
The prior board observation in docs/evidence/dsi-phy-hang.md establishes why
this boundary matters. It does not prove the new provider executes correctly
under the mainline pin. Host proofs and the exact source changes belong in
docs/evidence/mainline-display-power-domain.md.
Rejected: relying on U-Boot to leave DISP powered (not a maintained runtime reference), claiming an initrd change fixes power (it does not), changing the console/default kernels, or guessing new clock/reset mappings. The complete candidate kernel, DTB and matching trial bundle must build before handoff; the physical serial/panel/touch/normal-restoration gate remains unchecked.
Layer: optional kernel reset driver and Nix patch application. Grounding is
the committed restart source audit and the read vendor
drivers/reset/reset-k230.c at
7d4e1f444f461dbe3833bd99a4640e7b6c2cd529. Its restart callback writes
bits 0 and 16 to SYSCTL_BOOT_BASE_ADDR + CPU0_RST_CTL
(0x91102000 + 0x60), then waits indefinitely; its probe registers a
priority-128 restart notifier. The normal vendor boot transcript records
restart reaching U-Boot SPL. Mainline’s canaan,k230-rst controller instead
implements peripheral reset operations only. The boot-control register is
outside its reset-controller resource; do not reinterpret the peripheral
CPU0 reset ID as the system restart operation.
Forward-port only that restart sequence alongside mainline’s existing reset
implementation in the separate DRM derivation. Map the vendor-defined four
bytes at probe time with managed lifetime; check mapping and restart
registration failures. Use devm_register_sys_off_handler() with
SYS_OFF_MODE_RESTART and vendor priority 128, preserving the ordering while
adapting the callback to struct sys_off_data. The pinned
include/linux/reboot.h declares this API; the convenience
devm_register_restart_handler() fixes the priority to zero, so it would
change the vendor ordering. Keep the vendor write mask and terminal wait,
with cpu_relax() in the wait. Do no allocation or mapping inside the
atomic restart callback. Managed actions unregister the handler before its
mapping and per-device state are released on failed probe or removal.
Register only after the peripheral reset controller has registered, checking
all results. No DT change is needed if this vendor-defined mapping is
available independently of the existing peripheral resource.
Rejected: an initrd script writing registers (bypasses the kernel recovery boundary), direct SBI SRST calls without advertised support, changing loaded OpenSBI/stage 1 in the same increment, borrowing a different platform’s reset handler, or inferring restart success from a built object or the systemd refusal. This write’s physical behavior under the mainline kernel remains UNVERIFIED. Preserve the existing usable-root/display/touch gate 5b.5.
First compile the changed reset object against the exact pinned prepared
headers and evaluate/apply the optional Nix source patch. Then, under the
single shared build slot, build .#kernelMainlineDrm, build and inspect its
matching .#kernelMainlineDrmTrialBootFiles, and compare default and
console-only derivation identities to the base revision. Only the operator
may perform the recoverable physical trial: preserve a serial log showing a
kernel reboot request reaching stage 1 and a fresh normal boot identity,
protected normal hashes and shell postflight. A systemd refusal is a failed
prerequisite; an operator power cycle records recovery but does not prove
mainline automatic restart. The actual controller invocation and artifact
identity must accompany that physical evidence.
Following the bounded serial-only and retained-SBI trials, add a separate
kernelMainlineBootTrace derivation and matching ordinary-init system/bundle.
The current DRM/restart/five-clock source remains its base; existing kernel,
console, observer and default outputs stay unchanged. The optional system
removes exactly tty0 from the base console arguments and adds
k230.boot_trace=1, with no retained boot console or clock bypass. Keep the
ordinary controller’s qualified controls and identity/protected recovery gates.
Use fixed paired markers around basic setup/initcalls, initramfs readiness, root-console opening, init accessibility/namespace, integrity keys, async completion, initmem/readonly cleanup and init exec. Enable only the exact runtime value 1; disabled calls have no output/emergency side effect. Keep the helper/state outside freed init sections and cap output at 32 public records. Briefly enter nbcon emergency state for each individual printk, then leave it before the bracketed work. This can perturb flushing and a marker can itself block; an enter-only marker is a last visible boundary, not a stack or cause. Namespace and fallback-exec markers preserve the original conditional paths.
Host proof is in
docs/evidence/mainline-system-trial/boot-boundary-host-2026-10-03.md.
Full matching kernel/artifact proof and operator-controlled physical output,
ordinary root/login, automatic recovery and real touch remain UNVERIFIED.
This diagnostic increment preserves task 5b.5 and all existing acceptance
requirements; it adds no shipped capability.
Layer: optional kernel source/configuration and matching Nix system/bundle;
reserved operator/controller evidence. The physical Bash prompt followed by
zero receipt replies grounds this diagnostic boundary. The committed source/DT
receipt compares eight exact files and thirteen properties, not whole kernels
or runtime equivalence. Pinned source 26hzn5… locates RX accounting/filtering
in 8250_port.c:1627–1690, actual timer IRQ mapping in
timer-riscv.c:167–183, and thread-context aggregate IRQ accounting in
irqdesc.c:1066–1073. Linux IRQ numbers must come from those live bindings;
PLIC source 16 is not a guessed Linux IRQ number.
A separate runtime opt-in creates one normal-priority kernel thread from late init, with at most six samples and finite sleeps over approximately thirty seconds. No priority/affinity/tick-policy change or RT/busy loop. State, worker and static aligned/page-contained output buffers must survive init cleanup. Disabled mode starts no observer and has no output side effect.
A narrow internal 8250 snapshot validates line0, selected device/mapbase and
hardware interrupt binding; it does not misuse the runtime-PM-only
serial8250_get_port() interface. Protect registration/removal lifetime with
nonblocking acquisition, then make one port try-lock attempt and copy only
cached RX/TX/error/failed-flip counts, IER/read/ignore masks and uartclk. Mark
busy/unavailable/changed binding explicitly, without waiting or dereferencing
a stale device. Obtain UART/timer IRQ aggregate counters through safe live
identity and thread-context APIs. Release all locks before formatting or a
single SBI write; no printk/emergency fallback, retry, MMIO or register writes.
Buffer/format/frame count and page bounds require actual target object proof.
Records contain fixed version/sample/state and numeric public fields, no raw addresses, proc text, UUIDs, private data or credentials. Reporter sequence proves scheduling; jiffies/ktime are timekeeping observations. Actual timer IRQ increments show accounted interrupts, which may be caused by the reporter’s own wakeups. RX increments count 8250-processed RX/break handling, including synthesized break handling without a data byte; they do not prove a physical FIFO read per increment or successful TTY/Bash delivery. Failed-flip counts do not prove successful Bash reads. UART IRQ growth may include shared/spurious activity. Absence, busy state or a missing final record is unknown, not a timer/UART fault or proof that the last firmware call returned. Finite sample count is not a guaranteed wall-clock bound if sleep/SBI stalls.
The matching controller retains shell PID1, async=0, marker suppression, sole console and existing three controls. It sends at most one qualified fresh builtin receipt stimulus, then captures bounded passive records, preserving partial/duplicate/missing/unknown results. No command or reboot after unknown. Require fresh protected normal preflight and independent postflight/operator recovery; records and heartbeat never supply recovery or ordinary-root proof.
Rejected: another blind shell retry, a systemd-dependent observer before
systemd startup, IRQ/PID1-path output, guessed MMIO/mapping fixes, TTY poll
(n_tty.c:2443 flushes work), and first-probe TIOCINQ (2488–2494 takes a
semaphore). These change or depend on the boundary being investigated.
Diagnostic timing can perturb progress; a successful trial alone is not a
production fix. Existing default/console/diagnostic output identities remain
unchanged; only a new named kernel/system/bundle is eligible for this probe.
Layer: separate optional kernel reporter source and matching Nix outputs,
followed by a separately reviewed typed host-controller selection. Physical
zero-report grounding is the finite packet in
docs/evidence/mainline-uart-progress/physical-2026-10-03/README.md and its fixed
result. It establishes exact candidate arguments, Bash prompt, one stimulus,
no receipt and no complete report, not an IRQ/timer fault. DBCN detection is
availability detection only. The actual selected source
4av3w0kigacwah6w04zfpnky4gsh0k59 places the first sleep at
drivers/soc/canaan/k230-uart-progress.c:37–43, snapshot/time formatting at
43–65 and the single sample write at67. Worker creation follows the runtime
and DBCN gates at72–78. The initial visible output therefore conflates worker
scheduling, sleep/wakeup, snapshot and firmware progress.
Add only a new layered source/kernel family, tentatively
kernelMainlineUartProgressBreadcrumbs, optional configuration
k230-mainline-uart-progress-breadcrumbs, toplevel/trial bundle and
kernelMainlineUartProgressBreadcrumbsExactObjects. Layer over the existing
reporter source rather than changing its recipe or C file. Keep all existing
package derivations, kernel source/config identities, ordinary trial families
and default system/image identical to the landed baseline. Inherit the original
serial-only ordinary-init artifact parameters with both trace tokens; add no
runtime reporter/breadcrumb flag to the artifact. Matching selected kernel.dev
headers, actual config, source layering and complete hardware DT identity after
only chosen bootargs removal require distinct host proof.
The new setup flag is exact k230.uart_progress_breadcrumbs=1; absent, bare or
invalid values retain the original six-sample behavior without breadcrumbs.
The existing exact k230.uart_progress=1 remains required to start the worker,
and existing CONFIG_RISCV_SBI/DBCN availability gates still apply. Setup code
alone is init-lifetime; helper/flag and two aligned static const byte strings
use ordinary lifetime. Each string is at most64 bytes, aligned64 and contained
within an actual configured 4KiB page, never a stack/VMAP_STACK or freed init
buffer. Call exactly once per point, passing literal length excluding NUL.
No formatting, printk/emergency, retry, fallback or counter query is added.
Fixed wire bytes (leading and trailing newline; the backslashes below denote those literal LF bytes):
\nK230_UPB1 point=worker-entry\n
\nK230_UPB1 point=first-post-sleep\n
Worker-entry occurs only on sample0 after the existing first stop check and
immediately before its msleep(5000). First-post-sleep occurs only on sample0
after that sleep and the existing second stop check, immediately before the
cached snapshot. Both execute solely in the normal-priority worker and outside
all snapshot locks. No IRQ, TTY, PID1/init, priority/affinity/tick change is
permitted. Six existing samples, format/state semantics, stop checks and delay
sequence remain unchanged. The whole worker attempts at most eight SBI writes:
two breadcrumbs plus six samples. Firmware results are deliberately discarded.
One invocation is not a wall-clock firmware bound; sleep/scheduling may stall.
The write API in the same source’s arch/riscv/kernel/sbi.c:591–617 performs an
availability check, static-buffer physical conversion, page clamp and one ECALL;
full/partial/zero/error returns do not trigger a second attempt.
A separate explicit --uart-progress-breadcrumbs selector requires minimal
mode plus --same-image-shell-pid1 --uart-progress. It qualifies the new exact
manifest/kernel/dev/source/ordinary artifact policy before UART, preserves the
same async=0, marker suppression, rdinit/Bash and three qualified controls, and
adds only the exact new volatile gate alongside the existing reporter gate.
Existing modes and numeric sample parsing remain unchanged. Protected normal
pre/postflight and registration-absence checks remain mandatory.
Accept each of the two exact complete breadcrumb lines at most once; reject unknown versions/points, extra fields, duplicates, reordered observed points, truncation, echo/stale lines and inserted kernel text. Preserve raw private bytes; do not strip printk or repair a split marker. Retain the whole bounded fresh boot phase so early direct output is not lost merely because printed kernel banners lag. Associate records only after fresh selected Linux/received argument qualification for that boot attempt; old buffers or an unqualified prompt do not establish freshness. Breadcrumbs never authorize input. The one receipt stimulus still requires the existing fresh init-entry/primary-prompt and exact received arguments; afterward input remains stopped, including when receipt or any record is unknown. No candidate reboot is added.
Report breadcrumb presence/completeness separately from receipt and the six numeric samples. Host arrival before/after stimulus is not per-byte RX timing. Entry alone proves worker reach to the entry output call, not return from it, sleep completion or failure location. First-post-sleep proves the first sleep and both stop checks passed and the earlier entry call returned, not that its output was complete. A later sample proves progress past the post-sleep call and snapshot/formatting, not firmware count, healthy RX or Bash delivery. Missing entry/wake/sample may reflect scheduling, blocked/failed/partial output or later work; none alone identifies a cause. Missing/malformed breadcrumbs remain incomplete/unknown even if numeric samples or protected recovery appear. Automatic return and independent protected operator recovery remain separate.
Rejected: another identical sleeping-worker retry; dropping its first sleep; IRQ/PID1/TTY instrumentation; a printk/earlycon fallback; polling/retry; and loosening existing parsers to remove arbitrary console text. These introduce additional dependencies or change the boundary being compared. Source/object, full build, typed protocol and physical proof tasks stay distinct. Diagnostic calls can perturb timing and successful output is not a production fix.
Layer: a new optional reporter-source/Nix family and separately reviewed typed
controller selection. The committed breadcrumb packet
and result
at revision 278769d0 record both worker points, a matched fresh receipt and
complete n0/n1, then no n2–n5 in 180s. CI 37171186624 and exact publication passed;
the subsequent operator reset passed guarded fresh protected normal recovery
and Home observation, recorded in the packet’s distinct recovery receipt.
Automatic return remains unverified. No guessed counter/IRQ diagnosis
is used. The immutable
selected source k5a5zrhqy9ypr3mja1r50mdlcgi74i1f has worker sleep/stop at
drivers/soc/canaan/k230-uart-progress.c:67–70, snapshot at 74 and numeric SBI
write at 98. A complete n1 frame leaves that call’s return and the following
iteration/sleep/snapshot/output unproved.
Layer only a new reporter patch over the current Breadcrumbs source. Name the
new family kernelMainlineUartProgressPostSample, configuration
k230-mainline-uart-progress-post-sample, matching toplevel/trial bundle and
kernelMainlineUartProgressPostSampleExactObjects. Preserve every old package,
source/config, object and trial derivation identity, including original reporter
and Breadcrumbs outputs. Inherit original serial-only ordinary-init artifact
parameters; bake in no reporter/breadcrumb/post-sample runtime flag. Exact
selected-dev config/headers, applied source, compiled Image and complete hardware
DT comparison remain separate host gates.
Only exact k230.uart_progress_post_sample=1, alongside exact existing
k230.uart_progress=1 and k230.uart_progress_breadcrumbs=1, CONFIG_RISCV_SBI
and actual DBCN availability enables the new records. Absent/bare/invalid new
values preserve the current selected variant’s behavior. Setup alone has init
lifetime; helper/flag and two static const arrays have ordinary lifetime. Each
array is aligned 64, sizeof<=64 including NUL and page-contained under actual
4KiB configuration; pass literal length excluding NUL, not a stack/VMAP_STACK
or freed init buffer. Each point attempts the existing SBI write API once.
Fixed new bytes, with literal leading/trailing LF:
\nK230_UPP1 point=after-n1-write\n
\nK230_UPP1 point=third-post-sleep\n
After-n1-write is only sample index1, immediately after the existing numeric SBI call returns, before loop advancement. Third-post-sleep is only index2, after the unchanged third sleep and second stop check, immediately before snapshot. No added stop check, delay, counter query, formatting, retry, printk/emergency/fallback, priority/affinity/tick change or IRQ/TTY/PID1 output. Existing six samples and two breadcrumbs remain unchanged. At most ten attempts occur if calls return: six numeric, two old breadcrumbs, two new records. Full/partial/zero/error counts remain discarded. One attempt is not a deadline; firmware and sleep/scheduling can block, and the added calls can perturb timing.
Explicit --uart-progress-post-sample requires minimal mode and all existing
--same-image-shell-pid1 --uart-progress --uart-progress-breadcrumbs selectors.
Qualify the new exact manifest/kernel/dev/source and unique linked marker/gate
bytes before UART. Preserve exact original artifact qualification, marker-free
async=0/Bash/sole console/three controls, protected normal/registration-absence
checks and the single fresh receipt stimulus. Add only the new volatile gate.
No further candidate input or reboot follows that stimulus, irrespective of
receipt/record completeness. Existing selectors/parsers retain their behavior.
Accept only the two exact complete fresh lines, at most once and in source order when both appear. Unknown/extra/stale/echo/duplicate/reordered/truncated/ interleaved records remain incomplete/unknown; retain private raw bytes, never repair or strip arbitrary console text. Capture the whole qualified fresh boot phase. Preserve independent facts for receipt, old breadcrumbs, new points, six samples and protected recovery; a new point never authorizes input.
A visible after-n1-write proves the numeric n1 call returned, not its full write count or this new call’s return. A visible third-post-sleep proves the prior point’s call returned and the third sleep/stop checks passed, not snapshot or n2 output. A later n2 record proves progress past that second point and snapshot/formatting, not firmware count or physical RX delivery. Missing points cannot distinguish blocked/failed/partial output, scheduling or later work; do not name a fault from the last line. Independent protected normal recovery remains a separate gate; no automatic-return or root/touch claim.
Rejected: another identical eight-call trial, shortened/removed sleeps, IRQ/TTY/PID1 output, changed console/SBI fallback, polling/retry, and parser loosening. These change other dependencies or repeat the same unresolved boundary. Group 5h separates planning, source/native identity, full build, exact objects, typed protocol and physical/recovery evidence.
Group5h’s matching source/objects/full artifacts and positive controller gates passed. Its independently reviewed physical capture reached worker-entry/Bash, but no receipt, numeric samples or new points in180.0975s; the committed physical packet and deployment receipt preserve that incomplete result. The subsequent NEW operator reset passed guarded fresh normal postflight and reviewed Home evidence. No return from entry’s output, first sleep completion or later point is proved. This leaves the ordinary mainline acceptance requirement and task5b.5 open.
Group5h’s independently reviewed actual capture reached only entry/Bash, with no matching receipt, samples or new points. Group5g reached n1. Missing serial output cannot identify execution or firmware return. The source audit in the memory comparison note grounds a distinct intervention rather than another per-boundary ECALL chain.
Add separately named Memory reporter/kernel/system/bundle/exact-object outputs;
keep all existing package/source/config/trial identities. Explicit
k230.uart_progress_memory=1 requires exact existing progress opt-in and actual
SBI/DBCN support. In that variant and gate only, suppress ALL worker output,
including numeric, Breadcrumbs and PostSample calls, retaining six5000ms sleeps,
cached snapshots, existing stop checks, normal priority/affinity and termination.
Absent/bare/invalid gate retains inherited worker behavior. Do not combine
runtime Breadcrumbs/PostSample selectors with this comparison.
Publish a finite consistent ordinary-memory state: stage before/after each sleep, completion bitmap and last completed index. Publication/read ordering must be explicit, bounded, and free of locks across sleep or firmware calls. No snapshot/getter gains MMIO. An independently created normal-priority observer waits once with finite kernel timeout (45 seconds), copies a consistent bounded state, then attempts ONE final <=256-byte aligned page-contained ordinary-buffer DBCN summary. No retry/printk/fallback/IRQ output; observer creation failure must be explicit and bounded. Timeout depends on kernel execution; it is not a firmware wall-clock guarantee. Existing modes must not create this observer.
Freeze the exact public grammar/stage encoding during source/controller review, validate completion bitmap/index/stage consistency and fixture exact/absent/ invalid gates, sleep/stop/publication ordering, observer completion/timeout, allocation failure and full/partial/zero/error one-call behavior. Independently inspect actual selected headers/objects/linked strings/lifetime/config, original artifact policy and complete hardware DT before physical use.
Typed --uart-progress-memory requires minimal/same-image-shell-PID1/progress
and rejects Breadcrumbs/PostSample or conflicting flags. Its actual preparation
qualifies reviewed source/dev/Image/manifest/archive, adds only the new volatile
gate, preserves fresh exact args/Bash readiness and protected normal guards,
and sends at most one fresh receipt followed by passive180-second capture.
The summary never authorizes another command or candidate reboot. Strict parser
accepts one complete exact fresh summary, keeping receipt/recovery distinct.
Unknown/duplicate/echo/stale/truncated/inconsistent output stays unknown.
A received summary proves its recorded progress BEFORE the final firmware call; completion supports progress under removed repeated output, not an IRQ/firmware fault or this call’s return. Missing summary cannot distinguish worker, observer, timeout, M-mode or serial failure. An M-mode stall on the only executing hart can prevent S-mode observer progress. Protect normal profile/boot selection and require separate fresh normal recovery. Ordinary root/glass and5b.5 stay open.
Rejected for this bounded comparison: direct UART polling without LSR/nbcon ownership proof, firmware replacement, and repeated ECALL point chains.
Memory’s completed 180.1021-second capture has one stimulus but no receipt/summary.
Preserve its exact selected lznjjfx1 bundle/307d7c source/dev/config/Image/DT,
all manifests/archive/load guards and identical volatile Memory bootargs. Add
--uart-progress-memory-no-stimulus requiring Memory, minimal, same-image-shell
PID1 and progress; reject conflicting comparison selectors before UART access.
This is only a controller input policy, never an appended kernel argument.
After the candidate boot command, use only read/pump/passive bounded 180-second capture: no receipt, CR, Ctrl-U/Ctrl-C, retries, guards/uploads/proc commands, reboot or finally/error-path input. Retain strict exact fresh summary parsing, early-record argument qualification, banner/binsh/primary-prompt observations. Record stimulus_attempts=0, receipt_observed false, receipt_status NOT_REQUESTED and RX NOT_TESTED. Keep summary validity, worker completion and recovery separate. A valid completed summary may qualify diagnostic observation without a receipt in this explicit mode, never ordinary-root or receive acceptance. Default Memory mode still sends exactly one stimulus and uses its existing receipt requirement.
Only existing ordered fresh SPL→6.6.36→login→normal-prompt qualification can authorize protected NORMAL postflight writes; exact identities/eight hashes/ services/registration absence and distinct boot checks remain mandatory. No summary is inconclusive; no normal return requires separate operator recovery. An observed difference supports changed behavior under removed input attempt, not a UART/IRQ/firmware fault or timing-independent causal conclusion.
Fixtures use transport write spies across prompt/summary/no prompt/no summary, malformed/duplicate/truncated/stale/echo, timeout/read error/overflow and wrong args, with zero candidate bytes throughout. Candidate normal-looking text cannot authorize helper writes. Test same args, pre-open selector rejection, default one-stimulus regression and separate actual protected recovery. Requalify actual existing artifacts before physical use; no new kernel or full build is required.
Add typed --uart-progress-memory-poll-idle, requiring minimal/same-image/
progress/Memory AND no-stimulus selectors. Reject conflicts/types/modes before
UART. Reuse the exact lznjjfx1 bundle, 1pvqbm4 dev, 307d7c source, Image/config/DT,
archive/manifest/load checks. Qualify CONFIG_GENERIC_IDLE_POLL_SETUP=y and the
linked NUL-terminated nohlt setup. The sole bootarg difference is one trailing
bare nohlt; reconstruct the exact literal argument transform and reject
hlt, duplicate/value-form tokens or arbitrary additions. Both previous Memory
policies and all other default transports remain unchanged. No kernel rebuild.
After boot, preserve strict zero-write behavior on success/timeout/error/finally, 180-second passive capture, fresh argument/summary parsing, NOT_REQUESTED receipt, zero attempts and RX NOT_TESTED. Normal postflight writes require the existing ordered fresh SPL→6.6.36→login→normal-prompt gate and independent protected identities/eight hashes/three services/registration absence/distinct boot checks. No candidate reboot or persistent environment/card/profile change.
The source audit
shows nohlt forces IRQ-enabled polling and restarts the tick. A summary supports
an idle/tick-policy-dependent difference only; absent output retains all worker,
observer, timer, scheduler and final-firmware-output limits. This is neither a
production power policy nor ordinary /init/root/panel/glass acceptance.
Rejected: cpuidle.off alone (default WFI remains), extra firmware-output markers,
new MMIO/IRQ/firmware/scheduler modifications and an unnecessary full build.
Fixtures must test typed pre-open dependencies/conflicts, exact sole argument change, unchanged default/no-stimulus transports, unsupported/mismatched actual config/Image gates, stale/wrong received args, strict valid/malformed/duplicate/ truncated summaries and zero candidate writes on read error/overflow/timeout. Run actual existing-artifact preparation before the one physical comparison; preserve fresh recovery or explicit pending operator reset separately.
Layer a separately named MemoryPrintk source/kernel/trial/exact-object variant
above unchanged Memory. New exact runtime gate
k230.uart_progress_memory_printk=1 requires existing progress and Memory gates.
Preserve existing invalid/absent behavior and every prior derivation/source/
config/trial identity. New controller selector --uart-progress-memory-printk
requires minimal/same-image/progress/Memory/no-stimulus; reject nohlt/point/trace
selectors and type/mode conflicts before UART. Configuration/autoconf and hardware
DT match baseline Memory; only the reviewed source/Image and matching artifacts
change. Never select this code through an old artifact/namespace.
Keep worker sleeps, cached getters, stop checks, publication and observer
allocation/failure/completion/one acquire unchanged. Suppress all worker output.
With the new gate, observer performs ONE ordinary KERN_INFO/pr_info call instead
of final explicit DBCN, with fixed format
\nK230_UMK1 s=%u n=%u m=%02x l=%u w=%u\n and the existing bounded state rules.
The single call includes a leading newline: printk prefixes an empty line first,
separating any existing Bash prompt from the following timestamped summary.
The parser accepts only that following complete line; never strip a shell prompt.
No emergency priority, force flush, raw register access, firmware fallback,
second channel or retry. The normal registered Linux console owns its IER/
locking/nbcon behavior; one attempt is not a firmware or console wall-clock bound.
Qualify actual PRINTK/PRINTK_TIME/8250 console/DW support, disabled PRINTK_CALLER, reviewed new source and unique linked format/setup; target object must show ordinary printk API use plus unchanged atomic/completion behavior. Exact config and DT/archive/load/CRC guards remain. Literal args add only the new gate to base zero-input Memory; no nohlt, earlycon, keep_bootcon, quiet or logger-format override. Received exact args and fresh Linux ttyS0 registration/console-enable markers must ground the backend.
Accept only fresh K230_UMK1 with the observed timestamp-only six-decimal kernel console prefix/CRLF convention and bounded fields; do not repair embedded CR or invent execution-context prefixes. Reject old UMP/wrong-channel, duplicates, malformed/truncated/stale/echoed records and wrong received args. Keep one coherent summary, validity and worker-completion facts separate. Retain zero candidate writes on all capture/error/finally paths, NOT_REQUESTED receipt/RX NOT_TESTED, 180-second passive capture and independently gated protected normal recovery.
A record establishes observer snapshot/formatting reached changed Linux output; not printk return, prior DBCN failure or ordinary root. Absence retains observer, timeout/scheduling/console/UART limits. Rejected: unsupported timer-DT switches, extra SBI markers, simultaneous nohlt, MMIO polling and force-console bypasses. Source/backend grounding and limits are in the linked research note. First land native/source identity proof, then freeze matching full build, target object and actual artifact/controller gates before one reserved physical boot.
Layer a typed controller-only --uart-progress-memory-printk-nohz-off selector
on the existing MemoryPrintk policy. Require minimal/same-image/progress/Memory/
no-stimulus/MemoryPrintk and reject invalid types, modes and competing polling,
point, clock, trace or timer selectors before opening UART. Reuse the actual
p2kdar89 bundle, xna7x12 kernel, 24hbalyl dev and 0l4mgw9 source. No kernel,
initrd, DT build or new transfer is necessary. The board operator still verifies
existing staged artifacts and fresh protected normal state before use.
Keep matching source/config/Image/archive/manifest/load/CRC/DT guards and all
previous package identities/default transports. Require actual NO_HZ_COMMON and
NO_HZ_FULL, HIGH_RES_TIMERS, HZ=250, RISCV_TIMER and RISCV_SBI configuration,
matching config/Image hashes and one linked NUL-terminated nohz= setup. Do not
require the unset legacy CONFIG_NO_HZ symbol. Reconstruct the exact qualified
MemoryPrintk baseline and append ONLY trailing nohz=off: literal U-Boot
transport changes 416 to 425 bytes within the existing 512-byte bound. Reject
original nohz/nohz_full tokens, bare/empty/alternate/duplicate nohz forms and
arbitrary bootarg syntax or changes; do not expose a general option editor.
Retain worker/observer/source/format, fresh exact received args and Linux ttyS0 backend proof, strict complete-line UMK namespace and bounded state parsing, and the qualified optional Readline prompt prefix. Capture remains 180 seconds with zero candidate writes on success/error/finally, NOT_REQUESTED receipt, zero attempts and RX NOT_TESTED. Only independently ordered fresh normal boot markers and protected normal postflight authorize recovery writes. No candidate reboot, flash or persistent environment/profile/card change.
The read source and actual config/Image show this inhibits global tickless activation, without disabling high-resolution timers or guaranteeing hardware timer interrupts. nohlt already restarts ticks in its poll arm; do not relabel that previous test as a tickless-off test. Exact received token and compiled parser support do not separately observe runtime activation. A valid record supports progress under changed tick policy, not an IRQ cause or printk return. Silence retains scheduling, sleep/wakeup and output unknowns. Ordinary /init/root/panel/glass acceptance remains separate.
Fixtures cover pre-open dependency/type/conflict rejection; sole exact transform and unchanged defaults; unsupported/mismatched actual config/Image; stale/wrong args, valid/malformed/duplicate/truncated/wrong-channel records; zero writes on all timeout/error paths and independently guarded recovery. Commit an executed actual-artifact qualifier and safe receipts before physical use. Rejected: combined nohlt/highres/clock options, new markers, raw IRQ/MMIO intervention and unnecessary full builds. A fixed Bash-PID1 autonomous probe is a separately planned fallback, not authorization to pass arbitrary scripts through this selector.
This controller/userspace comparison uses existing p2/xna/24h/0l4 artifacts. Add
only typed --autonomous-bash-pid1, requiring minimal and same-image-shell-PID1.
Reject every progress/breadcrumb/post-sample/Memory/no-stimulus/polling/Printk/
nohz/clock/trace/shutdown selector and invalid types/modes before preparation,
output creation or UART. Retain all defaults and generic transport restrictions.
The new helper reconstructs one exact fixed script from a controller-generated
32-character lowercase hex nonce; it is not a script/args editor. Retain original
sole init token, rdinit=/bin/sh, async0, fsck skip and the two service masks.
Use the exact 154-byte script and old-Hush transport in the scout. The only new argv after — are -c and that script. Remove all reporter and trace gates so the read source returns before creating either reporter thread. Native execution of the exact selected Hush lexer/variable/quote/command handling must show one volatile setenv bootargs call, the exact 477-byte result, zero expansion or extra/persistent command execution. Use the pinned parser source/hash and qualify configuration/version facts with their installed-identity limits. Native selected Linux next_arg plus repair/set_init_arg handling must show exactly -c and the complete script after init/rdinit clearing and post— parsing. A Python model or POSIX/shlex surrogate alone is insufficient.
The old Hush syntax requires a single-quoted complete data argument with no embedded single quote, raw dollars protected and every script backslash doubled. Linux strips its outer script doublequotes but cannot escape inner doublequotes; the fixed body has none. With the actual system path this yields one 503-byte command, 504 with CR, within the unchanged strict 512-byte transport bound. Reject nonce changes in shape, script/quote/backslash damage, extra args/gates/options and all arbitrary syntax before UART. Actual printenv equality must pass before boot; fresh exact kernel arguments, new 7.3 phase, registered Linux ttyS0 and /bin/sh entry qualify records. Commandline/echoed script text is never a record.
Requalify same source/config/Image/DT/archive/manifest/load/CRC identities and actual archived executable /bin/sh and /bin/sleep, their RISC-V ABI/loader hashes and Bash printf/test/exec builtins. Commit executed actual-artifact qualifier, native parser proof and safe receipts. No implicit build/transfer or hardware claim follows from host execution.
The fixed script checks $$=1 and EUID=0, emits newline-delimited K230_BP1::B, runs exactly one absolute /bin/sleep 5 and emits E only after prior successful returns. Outside that conditional chain it execs /bin/sh -i, including after a failed test/sleep; it deliberately does not exit PID1 or issue a reboot. Runtime exec failure/EOF/output blockage remain possible. Capture is 60 seconds, zero candidate bytes on success/error/finally, no receipt/RX test, no shell commands/retries/recovery attempts based on marker presence. Existing ordered fresh normal-return markers and protected identities/eight hashes/three services/distinct boot/registration checks alone permit normal postflight.
Accept only complete fresh raw B then E lines with the exact nonce, strict CRLF handling and no prompt/ANSI/kernel-text repair. Reject malformed record-prefixed lines, stale/wrong/duplicate/reversed/truncated/interleaved records. Preserve begin/end/prompt separately and keep absence unknown. Begin supports limited PID1/UID0 tests and output reached; end supports earlier printf/sleep success, not its own printf return. A later interactive prompt adds progress through that return/exec. This is not a proc/kernel/initrd full identity guard, RX, ordinary /init/root/panel/glass acceptance or a single-fault isolation. Host wall time does not prove kernel-clock progress. Recovery remains independent.
Rejected: generic script flags, POSIX-only quoting models, kernel observer markers in this comparison, unconditional exit/reboot, another kernel build and multiple timer/IRQ interventions. Preserve the zero-input result even on incomplete capture and record separate operator recovery or explicit NEW reset.
Userspace controller only: begin-only --initrd-debug-logging requires the
existing synchronous-initramfs and marker-free selectors. Append exactly
rd.systemd.log_level=debug rd.systemd.log_target=console; reject inherited
plain/initrd log settings and underscore/hyphen aliases, duplicate/conflicting
values, wrong types and other phases before UART. Save the typed selection;
old state defaults false. Pure policy gives 356 argument / 374 command bytes.
Retain p2 Image/initrd/DT/source/config/manifest, all five load/CRC checks, sole console, exact init/root/masks and 180-second passive readiness. Preserve the complete private log even past rolling-buffer capacity, split fresh milestones and unknown-no-input behavior. Debug output may change timing/console pressure. Reject global tracing, journal forwarding, udev verbosity, extra masks/targets, alternate PID1 or a new build for this first comparison. Manager state/ExecStart logs cannot pinpoint silent shell subcommands; narrower helper instrumentation would need separate scope. Physical results and recovery remain unverified. See read archive/source and current physical boundary.
Userspace controller: typed begin-only --initrd-info-logging requires both
existing synchronous-initramfs/marker-free selectors and excludes the debug
selector. Select exactly rd.systemd.log_level=info rd.systemd.log_target=console.
This changes only one previous value: 355 argument / 373 literal command bytes.
Persist/restore the typed choice; old states default false. Reuse alias/type/
pre-UART guards while keeping old defaults and debug mode unchanged. Retain
same source/config/Image/initrd/DT, normal/artifact/load/CRC/argument gates and
180-second passive readiness/full private logging/unknown-no-input policy.
Reject compensating kernel verbosity, debug+kmsg, extra masks/targets, global tracing and rebuilds for this comparison: each changes additional boundaries. Changed observed progress is sensitivity to one value, not a proven call/cause. A silent run cannot distinguish earlier PID1 setup from console open/write. Source/physical scope; NEW recovery and actual qualification remain required.
Userspace controller: begin-only --initrd-info-kmsg-logging requires synchronous
initramfs and marker-free ordinary init, excluding both debug and info-console.
Append exactly rd.systemd.log_level=info rd.systemd.log_target=kmsg: the sole
changed value is console→kmsg,352 raw argument/370 literal command bytes.
Preserve old defaults/profiles, typed saved continuation with old missing=false,
pre-UART alias/type/conflict guards and the unchanged transport bound. Retain
same p2/24h source/config/Image/DT/archive/system init, masks/root/console,
five loads/CRCs, normal and live argument guards,180-second passive capture,
full private logging and unknown-no-input policy.
Kmsg selection may fall back to console or drop/filter records. Eligible INFO severity is not proof of delivery or absence of console calls. Changed progress means backend-selection sensitivity; silence does not localize a failing call. Reject debug+kmsg, verbosity compensation, arbitrary logging controls, tracing, new masks/targets/PID1 or builds: each adds another intervention. Require reviewed source/actual host gates and NEW protected recovery before one board capture, then independent recovery or explicit NEW reset. Pinned source audit.
Userspace orchestration/evidence only. Existing begin selectors
--wait-initramfs-in-initcall --without-boot-markers select the quiet policy;
all three logging selectors remain false. Preserve exactly299 raw argument/
317 literal bytes, p2/24h source/config/Image/DT/archive/init/root/three controls,
five loads/CRCs, normal helper and printed/live arguments. Actual preparation
must show equality with the earlier quiet command, not merely removing an
arbitrary suffix from a captured string. No new selector or source change.
Require NEW verified recovery after5q, actual artifact qualification and independent review before one180-second passive capture. Keep full private coverage and no candidate input on unknown readiness; commit independent recovery or explicit pending NEW reset. A repeat tests reproducibility before new interventions; either outcome does not establish a single logging cause. Retain ordinary5b.5 and all runtime/glass/cause limits. Reject multiple repeats, compensating verbosity, tracing, targets/masks/PID1/IRQ/MMIO and builds in this group. Helper instrumentation is a separately scoped possible follow-up only if the original closure boundary reproduces. Read archive/source roadmap.
Use a separately gated, default-disabled child of p2. Emit at most one fixed versioned INFO record with the signed return value immediately after the selected ramdisk run_init_process call, before its unchanged success/error conditional. Existing boot markers stay disabled; do not add generic fallback records, force console delivery, change printk mechanics, argv/env, init or existing branches. A typed begin-only controller selection must reject conflicts/aliases/types before UART, validate exact expected new arguments and manifests, and preserve all protected preflight/load/CRC/normal/unknown-no-input guards and180s bound.
Old Nix outputs retain their identities. New kernel/dev/source/system/bundle identities and every necessary archive dependency delta require actual proof; retain exact config, DT hardware and archived systemd/init/Bash/loader/helper bytes. Require source/control-semantic fixtures, selected RISC-V object review, actual artifact qualification and independent review before physical capture. A record with return value zero shows exec setup success, not user-mode transition/loader/main. Missing/partial records and output-call return remain unknown; never label them a located instruction or hardware cause. Recovery is independently guarded or explicitly pending NEW reset. Pinned source and alternative analysis.
Host artifact availability is a separate staging prerequisite: retain the optional source/kernel/dev/bundle with persistent Nix roots after realization. If outputs are absent later, preserve the historical successful receipt, restore the same pinned identities with a new receipt, and recheck actual hashes/qualification before any UART operation. Missing files are not evidence that source was lost or that the board failed. Group5s.2a covers the observed availability gap.
Layer: optional Linux source/kernel plus additive Nix/controller variant. The
selected realized source is
/nix/store/dsgrv7744lzh418z22gb865c0j09g1qs-linux-mainline-k230-init-exec-return-src.
Read sites: init/main.c1704–1708; arch/riscv/kernel/process.c228–233;
arch/riscv/kernel/entry.S363–370 and return sret; arch/riscv/kernel/traps.c325–345;
include/linux/entry-common.h185–208 and338–345. These are source analysis,
not physical proof. The parent capture’s one ret0 record does not establish
that its printk returned or that kernel_init returned.
Keep the parent’s exec-return record unchanged. Add exact-value1 boot gate
k230.init_exec_transition=1, ordinary-lifetime storage (not freed initdata),
and an arm set only on selected ramdisk exec success with both exact runtime
gates enabled (k230.init_exec_return=1 and k230.init_exec_transition=1).
Emit at most two new fixed
versioned INFO records for PID1, consuming each one-shot before its output call:
K230_INIT_EXEC_TRANSITION_V1 point=kernel-init-return.K230_INIT_EXEC_TRANSITION_V1 point=first-user-ecall.These sites retain instrumentable kernel context. No printk/current/RCU helper is added after syscall_exit_to_user_mode: that path has disabled interrupts and already transitioned context tracking to USER. Do not alter assembly, sret, exit work, scheduler/interrupt/timer/vector state or syscall results. Scope each record to armed PID1; never arm fallback execs or emit from other tasks, and never retry a consumed point. Implementation review must verify source context, ordinary storage lifetime and selected compiled RISC-V objects.
A kernel-init-return record proves the original selected kernel_init and its exec-return printk returned; it does not prove its own printk returned or a user instruction ran. A first-user-ecall record proves a user ECALL instruction and successful kernel re-entry setup; it does not prove dispatch/handler completion, loader completion, constructors or systemd main. Missing records are unknown. A qualified ecall after the return record proves that earlier new output call returned. Records that are present must follow exec-result0, kernel-init-return, first-user-ecall order, with full fresh banner/arguments/init qualification; duplicates, malformed, stale, unarmed or reversed observations are errors. Missing earlier records remain an incomplete/unknown capture and are never repaired or inferred. An independently valid first-user-ecall still proves a user ECALL and entry setup if an earlier frame was not captured; it does not grant complete sequence or readiness. No record alone grants candidate input or claims a failed instruction/hardware cause.
Implement a typed begin-only selector —init-exec-transition as a separately qualified child of —init-exec-return; require synchronous initramfs and marker-free ordinary init, reject conflicting comparisons before UART, and treat missing saved state as false while rejecting invalid types. New volatile args contain exactly the two gates, preserving masks/console/other arguments; validate actual encoded sizes and existing transport bounds rather than relaxing them. Old Nix outputs retain derivation identities. Build new kernel/dev/source/system/ bundle separately; qualify actual config, Image literals, DT hardware and archived init/systemd/Bash/loader/helper bytes, permitting only proven necessary module-tree relocation. Retain registered GC roots and new failure receipts. Source review, actual build and artifact qualification precede any board action.
The operator first obtains NEW protected normal recovery, then guards candidate staging and performs ONE180-second passive capture with sole board/UART ownership, complete private logging, exact load/CRC/arguments/normal identity checks and the existing unknown-no-input behavior. Recovery is separately verified or explicitly pending a NEW reset. Ordinary root/panel/glass task5b.5 remains open. Reject generic per-syscall traces, userspace wrappers, systemd rebuilds and post-exit assembly logging: they add more changes or unsafe context before this narrower boundary has been observed.
The group5t capture and the earlier 5s capture both end with systemd 261.2’s
query_term_for_tty("/dev/console") DCS query (src/core/main.c:1727,
src/basic/terminal-util.c terminal_get_terminfo_by_dcs) and then 180 seconds
of UART silence. On the normal boot the same code returns within its 333 ms
fd_wait_for_event bound and emits ESC[18t next. Earlier groups established
that mainline userspace can complete a timed wait (5n sleep 5) and that a
periodic sampler stopped after its second sample (breadcrumbs). No capture has
ever observed whether the kernel remains alive after the UART goes silent:
hung-task, soft-lockup and RCU stall reports are themselves tick-driven and share
the UART console.
Repeat the identical reviewed 5t operator command once, unchanged, against the
already staged jx56x86… bundle (no build, transfer, source or controller change)
with fresh private state/log/result paths, while the host records the panel with
the bench camera (/dev/video0, MJPEG 1280x720, stream copy) from before the
candidate bootm until the capture ends. Under this kernel the mainline DRM/fbdev
console showed boot text on the panel (10-01 photograph), so the panel is an
output path independent of UART0.
Classify by inspecting raw frames and frame differences over the panel region after the last UART byte: (a) periodic change (fbcon cursor blink, which is timer/workqueue driven) or new panel text after UART silence → kernel timers and workqueues alive, stall is local to PID1/console/tty; (b) a static panel after change was observed earlier in the same recording → consistent with system-wide stop, not proof of it; (c) no panel change at any point → inconclusive. Camera observation is its own evidence class; it cannot identify a cause, an instruction, or prove that a specific timer fired. The UART result remains classified by the unchanged controller. Recovery requires a NEW operator reset and the reviewed recovery checker pattern. The next probe (for example an SBI-console hrtimer heartbeat reporting IRQ counts and PID1 state) is planned only from this outcome. Task5b.5 remains open.
Retained UART logs show every mainline stall following clk: Disabling unused clocks, immediately when cleanup lands inside the 0.35 s panel prepare window
(see the 5u camera-repeat evidence). The mainline DT gives vo/dsi no clocks
and the canaan VO/DSI drivers request none, while the K230 display gates use
plain clk_gate_ops. As with the SD1 restart fix, the consumers must own their
clocks: vo takes the display AHB/AXI/DPIP gates, dsi the AHB/CFG/REF gates
(the vendor disp_hclk/disp_aclk/dpipclk/cfgclk/refclk tree at sysctl 0x74),
each enabled from probe with devm_clk_bulk_get_all_enabled() before cleanup
can run. GPU and the DPHY test gate are not claimed. Enabling an already running
gate does not change rates. This is a fix candidate: it is accepted only by a
physical ordinary capture under the quiet policy that reproducibly stopped
(5r/5t/5u) reaching the qualified login. If it fails, the next step is the
cmdline ablation clk_ignore_unused pd_ignore_unused on the same bundle.
git show v7.2:arch/riscv/boot/dts/canaan/ vs.
master). Recorded in
docs/research/mainline-kernel-inventory.md (“Target version”).gh api repos/torvalds/linux/contents/<path>, 200/404) rather than
inferring from changelogs. Recorded in the same document’s
“Inventory” table.nix/kernel-mainline-src.nix
(fetchFromGitHub torvalds/linux, dereferenced v7.3-rc5 commit
72d3fcf802c45d00b300f25b848a93c3a2bd7c7e), hash obtained with
nix run nixpkgs#nix-prefetch-github -- torvalds linux --rev 72d3fcf802c45d00b300f25b848a93c3a2bd7c7e.nix/kernel-mainline.nix: defconfig = "defconfig",
autoModules = false, ARCH_CANAAN/PINCTRL_K230/RESET_K230/
COMMON_CLK_K230 turned on, an initrd-capable config
(BLK_DEV_INITRD/RD_GZIP/RD_ZSTD) with no initramfs content
supplied yet. Wire packages.kernelMainline in flake.nix via
pkgsCross.linuxPackagesFor, parallel to but independent of
k230Kernel/packages.kernel.
Proven: nix build .#kernelMainline --out-link result-kernelMainline --max-jobs 2 --cores 8 --print-out-paths exited 0, producing
/nix/store/7idv37hka94mcgnkw0cf6ggrdp8aypky-linux-riscv64-unknown-linux-gnu-7.3.0-rc5
(rooted at result-kernelMainline in this worktree) — a real
file-confirmed “Linux kernel RISC-V boot executable Image,
little-endian”, 38 504 448 bytes, plus System.map and a dtbs/
tree. The generated .config was checked directly and carries
CONFIG_ARCH_CANAAN=y CONFIG_PINCTRL_K230=y CONFIG_RESET_K230=y CONFIG_COMMON_CLK_K230=y CONFIG_BLK_DEV_INITRD=y. Build proof
only — no board exists this could have booted on yet.nix/dts/k230-tdisplay-mainline.dts (mainline’s own
k230-evb.dts as template; our board’s own 1 GiB memory size and
model/compatible strings, per design.md decision 3) and
nix/device-tree-mainline.nix (same dtc-invocation shape as
nix/device-tree.nix, against kernelMainlineSrc headers). Wire
packages.deviceTreeMainline in flake.nix.
Proven: nix build .#deviceTreeMainline --out-link result-deviceTreeMainline --max-jobs 2 --cores 8 --print-out-paths
exited 0, producing
/nix/store/0bwb48mn4dzz8ihhsvh9mrhx6gvixd5a-k230-tdisplay-mainline.dtb,
and the derivation’s own round-trip check (dtc -I dtb -O dts)
passed as part of that same build. Independently re-decompiled after
the build (dtc -I dtb -O dts result-deviceTreeMainline/k230-tdisplay-mainline.dtb)
to confirm by hand: compatible = "lilygo,t-display-k230", "canaan,kendryte-k230", ddr: memory@0 { reg = <0x00 0x00 0x00 0x40000000>; } (1 GiB, matching the vendor board file, not the
512 MiB k230-evb.dts default), aliases { serial0 = "/soc/serial@91400000"; }, and uart0’s status = "okay". Build
proof only.packages.kernelMainlineBootFiles in flake.nix: a plain
directory collecting Image-mainline and
k230-tdisplay-mainline.dtb under clear names (not the vendor
blinux flow’s fixed /Image//force.dtb, since this is a different,
manual ext4load flow the coordinator will drive — see design.md
decision 5 for why no initrd is bundled yet).
Proven: nix build .#kernelMainlineBootFiles --out-link result-kernelMainlineBootFiles --max-jobs 2 --cores 8 --print-out-paths exited 0, producing
/nix/store/23civ9kg8yr675wmlmdjbc718m0hjffv-k230-mainline-boot-files
containing exactly Image-mainline (38 504 448 bytes) and
k230-tdisplay-mainline.dtb (4660 bytes). Build proof only.Coordinator-directed continuation, after the coordinator merged c5158fa8
to master: “do the actual porting … so it can mount our SD rootfs.”
drivers/gpio/gpio-k230.c), SD/MMC
(drivers/mmc/host/sdhci-of-kendryte.c) and USB
(drivers/usb/dwc2/{params.c,core.h,core.c} hunks) from the pinned
vendor tree, plus the matching DT nodes in
nix/dts/k230-tdisplay-mainline.dts (real &sysclk/&rst phandles
from mainline’s own <dt-bindings/clock/canaan,k230-clk.h>/
<dt-bindings/reset/canaan,k230-rst.h>, replacing the vendor tree’s
unimplemented &dummy_sd/&clk_dummy stub clocks). Two real
vendor-to-mainline API migrations found via failed builds and fixed
against mainline’s own already-migrated reference drivers
(gpio-dwapb.c, sdhci-of-dwcmshc.c) — see the new spec requirement
“Forward-ported drivers are grounded in the vendor tree and checked
against the pinned mainline API” for the exact citations.
Proven: nix build .#kernelMainline --out-link result-kernelMainline --max-jobs 2 --cores 8 --print-out-paths exited 0, producing
/nix/store/appd6jgmwfr6rg4k18zjv155xc5841lm-linux-riscv64-unknown-linux-gnu-7.3.0-rc5
(38 522 368-byte Image). The generated .config carries
CONFIG_GPIO_K230=y CONFIG_MMC=y CONFIG_MMC_SDHCI=y CONFIG_MMC_SDHCI_PLTFM=y CONFIG_MMC_SDHCI_OF_DWCMSHC_KENDRYTE=y CONFIG_USB=y CONFIG_USB_DWC2=y, confirmed by direct grep. Also
confirmed: nix build .#deviceTreeMainline still exits 0 and its
DTB’s gpio0/gpio1/usb0/usb1/mmc_sd0/mmc_sd1 nodes
round-trip with resolved &sysclk/&rst phandles (dtc -I dtb -O dts, checked by hand). Build proof only — none of this has probed
real hardware; the clock-gate/reset-ID choices for these three
peripherals are UNVERIFIED best-effort mappings, named as such in
nix/dts/k230-tdisplay-mainline.dts’s own header.nixosConfigurations.k230-mainline-console, substituting
kernelMainline for the vendor kernel via the same specialArg
mechanism k230-rvv-trial already uses, based on the shell-off
k230-console (not the coordinator’s suggested
k230-coherent-shell-mainline name — deviation flagged in
flake.nix’s own comment and in this change’s report: the graphical
shell’s Sway/wlroots stack wants a DRM/KMS device mainline does not
provide yet, and its build would either fail or produce services
that cannot start). boot.extraModulePackages/boot.kernelModules
force-cleared to drop the out-of-tree RTL8189FTV module, which
nix/hardware.nix builds against config.boot.kernelPackages.kernel
dynamically and has no expectation of compiling against a kernel
seven major versions newer than its 6.6-era origin.
Proven: nix build .#toplevel-mainline-console --out-link result-toplevel-mainline-console --max-jobs 2 --cores 8 --print-out-paths exited 0, producing
/nix/store/d488a1cibw8r7ip7hbbb9j52hy0kzb0h-nixos-system-nixos-26.11.20260919.20b1ddd.
The build log confirms no k230-wifi-driver derivation was built at
all (the mkForce [ ] overrides took effect) and that
unit-k230-wifi.service-disabled.drv was built instead of the
enabled unit. Build proof only.nix/kernel-mainline-boot-files.nix and wire
packages.kernelMainlineConsoleBootFiles: Image, a DTB with this
system’s real bootargs baked into /chosen (fdtput, same mechanism
nix/sd-image.nix already uses — cfg.boot.kernelParams +
init=${toplevel}/init, deliberately with no hardcoded root=
device path, since this system’s inherited fileSystems."/" = { device = "/dev/disk/by-label/NIXOS_SD"; } already resolves root by
ext4 label through the initrd’s own fstab — matching the vendor
image’s own proven mechanism instead of guessing an mmc_sd1 device
node path), and the system’s initrd wrapped as a U-Boot ramdisk image
(mkimage, same invocation shape as nix/sd-image.nix’s
initrd.uimg).
Proven: nix build .#kernelMainlineConsoleBootFiles --out-link result-kernelMainlineConsoleBootFiles --max-jobs 2 --cores 8 --print-out-paths exited 0, producing
/nix/store/d0idhc2j28n3nn4q1cwq2lin69rnx76r-k230-mainline-console-boot-files
containing Image-mainline (38 522 368 bytes), k230-tdisplay-mainline.dtb
(7974 bytes, /chosen/bootargs confirmed by dtc -I dtb -O dts:
"console=tty0 consoleblank=0 console=ttyS0,115200n8 root=fstab loglevel=4 lsm=landlock,yama,bpf loglevel=7 init=/nix/store/d488a1cibw8r7ip7hbbb9j52hy0kzb0h-.../init"), and
initrd.uimg (file-confirmed “u-boot legacy uImage, initrd,
Linux/RISC-V, RAMDisk Image”, 27 313 961 bytes uncompressed, CRCs
present). Build proof only.nix flake check --no-build still passes with all new
outputs (it does: nixosConfigurations.k230-mainline-console and
every new package evaluate cleanly) and that no existing output’s
derivation changed:
git diff --stat 4ffe809a1b448f98379ea1165d7bca067d01cfdb -- nix/kernel.nix nix/kernel-src.nix nix/device-tree.nix nix/k230.nix nix/hardware.nix nix/sd-image.nix nix/shell.nix returns empty.What remains stubbed after this task group: no rootfs population step —
this milestone produces the boot files, not a card image, and does not
place this system’s own closure/profile symlink onto the physical card’s
root partition (an explicit non-goal, since a re-flash is out of scope
here per the task’s hard rules). No board boot has been attempted or
claimed. &mmc_sd0 (Wi-Fi SDIO) stays disabled — no driver forward-ported
for it in this task group. Display, touch, audio, PMU/power-key, thermal,
ADC, and crypto remain exactly as inventoried (no mainline driver to port
from); RTC is picked up in task group 5a below.
Coordinator’s milestone 3 named touch/RTC/PMU/thermal/ADC/audio “each forward-ported from the vendor tree with our patches applied.” RTC is the one attempted in this pass — smallest, most self-contained, most API-stable (RTC-class subsystem) of the group, and a genuine, small proof that milestone 1’s methodology extends.
drivers/rtc/rtc-k230.c from the pinned vendor
tree to nix/patches/mainline/rtc-k230.c, carrying this project’s
own already-board-proven k230-rtc-mday-mask.patch fix forward
directly in the copied file (0xf → 0x1f day-of-month mask) rather
than reintroducing a bug already found and fixed once. One trivial
fix needed beyond that: .remove_new (a transitional
struct platform_driver field from this file’s 6.6-era origin)
does not exist at v7.3-rc5 — renamed to .remove (the function
already had the matching void(*)(struct platform_device *)
signature). Built cleanly otherwise, on the first attempt. Added
rtc@91000c00 to nix/dts/k230-tdisplay-mainline.dts
(compatible = "canaan,k230-rtc", status = "okay", no
clocks/resets property — the driver calls neither devm_clk_get()
nor devm_reset_control_get() anywhere) and RTC_DRV_K230 = yes;
in nix/kernel-mainline.nix.
Proven: nix build .#kernelMainline --out-link result-kernelMainline --max-jobs 2 --cores 8 --print-out-paths exited 0, .config
confirmed to carry CONFIG_RTC_DRV_K230=y by direct grep;
nix build .#deviceTreeMainline still exits 0 and round-trips with
rtc@91000c00 present (dtc -I dtb -O dts, checked by hand); nix build .#toplevel-mainline-console and
.#kernelMainlineConsoleBootFiles both still exit 0 with RTC
included; nix flake check --no-build passes. Build proof only.canaan_drv.c/canaan_vo.c/
canaan_dsi.c/canaan_phy.c/canaan_plane.c + panel-canaan- universal.c (~3,900 lines, before re-applying this project’s own
~10 existing patches against the panel/DSI/VO files) was attempted
as scoping, not as a claimed forward-port. Findings: one Kconfig fix
(a driver below if DRM cannot itself select DRM — circular
dependency; depends on DRM instead), one already-removed Kconfig
symbol (DRM_KMS_DMA_HELPER), and then a real, structural DRM API
change on the very first file checked: drm_panel_init() was
replaced upstream by a refcounted devm_drm_panel_alloc()
allocation model (include/drm/drm_panel.h), changing how the
panel struct itself is allocated, not just a symbol name. This is a
materially larger class of problem than GPIO/SD-MMC/USB/RTC (DRM
atomic-modeset/bridge/connector/component-framework churn across
five interconnected files, plus re-applying this project’s own
panel/DSI/VO patches on top of whatever the ported base ends up
looking like) and was not carried to completion — the trial was
reverted (git checkout -- nix/kernel-mainline.nix, the scratch
nix/patches/mainline/drm/ directory deleted) rather than committed
half-working, since .#kernelMainline must stay buildable per this
change’s own spec requirement. git status/git diff confirm the
revert is complete and the tree matches the previous commit exactly
for nix/kernel-mainline.nix.docs/evidence/mainline-display-api-compile.md and its log. After the full-build link exposed missing bridge-helper selections, Canaan Kconfig selects DRM_DISPLAY_HELPER/DRM_BRIDGE_CONNECTOR; the rerun resolved both symbols and compiled the modules. See docs/evidence/mainline-display-api-compile.log and docs/evidence/mainline-display-full-build.log.nix build .#kernelMainlineDrm --print-out-paths; the combined build completed successfully and produced /nix/store/qa041skh6iy7rmx86c5zfn2xyq036f0g-linux-riscv64-unknown-linux-gnu-7.3.0-rc5 (docs/evidence/mainline-display-full-build.log).docs/evidence/mainline-display-dtb.md and its log.nix build .#deviceTreeMainlineDrm --print-out-paths; the combined build produced /nix/store/8v2v53z2qpxapsq507nvxsmld4y24d13-k230-tdisplay-mainline-drm.dtb (docs/evidence/mainline-display-full-build.log).nix build .#kernelMainlineDrmBootFiles --print-out-paths; /nix/store/bpbr6vldkm1y48k6wrdh7s6yv5szqa0k-k230-mainline-drm-boot-files contains only the candidate Image and DTB, byte-identical to the derivation outputs (docs/evidence/mainline-display-artifact-inspection.log).nix build .#kernelMainlineDrmTrialBootFiles --no-link --print-out-paths --max-jobs 1 --cores 4 and nix shell --inputs-from . nixpkgs#dtc --command python3 tools/mainline-drm-trial-inspect.py <output-path>. The built bundle is /nix/store/9v5jwcg97kp96jfj6nll4a4yixxzqh2x-k230-mainline-drm-trial-boot-files; see docs/evidence/mainline-display-boot-preparation.md and its log. This does not stage a physical card or satisfy 5b.5.docs/evidence/mainline-display-boot-preparation.md (the built kernelMainlineDrmBootFiles contains only the Image and DTB, with no initrd or root filesystem), reserve the board and perform a recoverable manual U-Boot trial. Capture the serial log with flock /tmp/k230-board.lock python3 tools/console.py /dev/ttyACM0 --wait=10, plus a panel photograph and deliberate touch interaction. The candidate’s display power-domain behavior remains UNVERIFIED until observed on hardware; the locally forward-ported provider planned in group 5c does not turn a host build into physical proof.
Next current-image ordinary comparison: bounded handoff; existing begin selectors, no new build. Fresh recovery/actual preparation passed; physical capture reached mounted sysroot/starting closure lookup but no login in 180s. Subsequent NEW recovery passed; group 5o plans manager logging.
Full shell, display and touch evidence: the guarded system-trial controller replaced the manual U-Boot/console.py procedure. Ordinary root qualified (candidate-ready-qualified-ordinary-init) for the console and full coherent-shell variants; panel photographed (console, then Home matching the normal system); deliberate real-finger touch recorded by evtest (533 MT events) with camera. Display power domain observed on (disp_domain on, display-subsystem active). Limits: controller touch retrieval timed out (counts from raw capture); touch inside sway, audio, power key and Wi-Fi not verified.sysctl_power/K230_PM_DOMAIN_DISP provider, so the initial host candidate omitted that unsupported phandle (see docs/evidence/mainline-display-dtb.md). Group 5c now adds an isolated local provider; physical display power remains UNVERIFIED.The coordinator authorized this bounded continuation after the source audit
found prior vendor-board evidence (docs/evidence/dsi-phy-hang.md) of DSI
all-ones reads and DCS timeouts without a held DISP runtime-PM reference.
Upstream at the pin still lacks the provider; a local port is opt-in only.
drivers/soc/canaan/k230-power-domains.c and its five-domain binding/table into the separate DRM candidate. Keep vendor register/repair semantics; remove unused hardlock state, make controller/domain state per-device, check genpd setup/provider errors and clean up partial registration. Enable only in kernelMainlineDrm. Host proof: nix build .#kernelMainlineDrm --no-link --print-out-paths and record the source/API/build limits in docs/evidence/mainline-display-power-domain.md and its log.0x91103000 register range and connect only the candidate’s logical display subsystem to K230_PM_DOMAIN_DISP. Retain existing clock/reset choices. Host proof: nix build .#deviceTreeMainlineDrm --no-link --print-out-paths, round-trip the DTB, and inspect the provider reg/cells and consumer phandle in the evidence log. Passed: /nix/store/nxbrd4smrcmknipjn4hjk32n87p4g9k6-k230-tdisplay-mainline-drm.dtb; provider phandle 0xd, consumer <0xd 2>, register tuple <0 0x91103000 0 0x1000>, one domain cell, two existing single-child graph warnings.nix build .#kernelMainlineDrm --no-link --print-out-paths; source/API/build proof only. Passed: /nix/store/i77i3ppi72k9hw0v2xmnhilc3q7rvv50-linux-riscv64-unknown-linux-gnu-7.3.0-rc5; full kernel log includes the provider and DRM master object compilations.nix build .#kernelMainlineDrmTrialBootFiles --no-link --print-out-paths and run nix shell --inputs-from . nixpkgs#dtc --command python3 tools/mainline-drm-trial-inspect.py <output-path>. Record exact bundle/system/kernel paths, unchanged default/console inputs, and the retained 5b.5 physical gate. Validate with openspec validate the-board-runs-a-mainline-kernel --strict. Passed: bundle /nix/store/gf3aqks2dg0z3ksz33ysfprnlbk83vw3-k230-mainline-drm-trial-boot-files, system /nix/store/k9f4r2i9k9qj58z8z4l2kssy9rpwxxm1-nixos-system-nixos-26.11.20260919.20b1ddd, kernel i77i3ppi72k9hw0v2xmnhilc3q7rvv50; matching artifact/CRC checks and nix flake check --no-build passed. Source/build evidence only; 5b.5 remains unchecked.The source audit is committed in
docs/evidence/mainline-display/physical-2026-10-01/mainline-restart-source-audit-2026-10-02.md.
The vendor restart sequence is read-source grounding; its behavior in this
mainline candidate remains UNVERIFIED. This group does not close 5b.5.
kernelMainlineDrm only. Preserve the vendor 0x91102060 register, bits 0/16, priority 128 and terminal wait; use the pinned managed sys-off API, checked probe-time mapping/registration and cleanup. Compile the changed reset object against pinned prepared headers and prove Nix patch application/evaluation; record exact reproducible commands, source hashes and limits in docs/evidence/mainline-restart/README.md. Proof: bash docs/evidence/mainline-restart/object-check.sh and nix build .#kernelMainlineDrm.src --no-link --print-out-paths (source derivation only; not a complete kernel or hardware reset). Passed on 2026-10-02: patched source vnzm30w6v4na0ylpw8vclyn7dn9vvkf0, host LLVM 22.1.8 prepared-header RISC-V object with W=1 and no warnings; exact commands/hashes/limits are committed in the named evidence. The first full GCC run found -Werror=return-type; the vendor unreachable zero return is restored as NOTIFY_DONE, and corrected source jvz4v73g8a67pqwm06v079h6s1cpqr9s passes the pinned GCC 15.3.0 object check with W=1. The failed complete run remains recorded separately.flock /tmp/k230-nix-build.lock nix build .#kernelMainlineDrm --no-link --print-out-paths --max-jobs 1 --cores 16; preserve the full log, Image SHA-256, store path and effective reset config. Full Nix build proof only. Passed: corrected kernel 4wkhxf55y1abg1kg2xd0acsfjqr64j0h, Image SHA-256 70a81b2172710c64463b53693e2e505a4d82ae2f7b644b2fc93cee9016b05330; full corrected and failed GCC logs are committed separately.flock /tmp/k230-nix-build.lock nix build .#kernelMainlineDrmTrialBootFiles --no-link --print-out-paths --max-jobs 1 --cores 16, then nix shell --inputs-from . nixpkgs#dtc --command python3 tools/mainline-drm-trial-inspect.py <bundle-path> and openspec validate the-board-runs-a-mainline-kernel --strict. Record exact kernel/system/initrd/DTB/bundle identities and unchanged default outputs in docs/evidence/mainline-restart/README.md. Passed: bundle asj7l4zj5jrjkgng4nrcx3y72p7jf7aa, system v9qc1sf0iz53s3x6g6vwfyaxghkfpnyk; inspector verifies Image/DTB/initrd/CRC and 629-path inventory. Nine base-relative vendor/default/console derivation identities match; corrected-source flake evaluation and strict OpenSpec validation pass. This does not stage or boot the board.flock /tmp/k230-board.lock python3 tools/console.py /dev/ttyACM0 --wait=10, plus the exact named controller invocation and matching artifact hashes. Require a real kernel restart request, subsequent U-Boot SPL/normal-system boot, a fresh boot ID, protected normal identities/hashes and shell postflight. Commit transcript/timestamps/limits under docs/evidence/mainline-restart/. A systemd chroot refusal, manual power cycle or host build does not satisfy automatic restart; physical restart stays UNVERIFIED until observed. Keep 5b.5 open for usable mainline root and deliberate touch.
Physical proof on 2026-10-02: the exact named minimal runtime-trace comparison with volatile clk_ignore_unused returned a real kernel restart, subsequent SPL/normal boot, fresh boot ID, exact protected identities, three active shell services and eight unchanged hashes. Controller exit 0; command, selected artifacts, transcript excerpt, raw hash/timestamp and reviewed normal Home are committed in docs/evidence/mainline-restart/physical-clock-comparison-2026-10-02/README.md. This qualifies the diagnostic boot only: baseline without the flag still stalls, permanent global bypass is not enabled, and proper SD1 clock consumers plus restart without the flag remain necessary before usable-root/touch task 5b.5 can close.
Subsequent no-bypass physical proof: the targeted five-clock candidate 9vdk79… / 5yqilsfy… / 9gdms… passed ordinary unused-clock cleanup, runtime tracing and real automatic restart → SPL → protected normal postflight with controller exit0, fresh bootID, three services and eight unchanged hashes, without clk_ignore_unused. Exact command/artifacts/transcript/hash/timestamp are committed in docs/evidence/mainline-sd1-clocks/physical-no-flag-2026-10-03/README.md. Ordinary root and deliberate touch stay open in5b.5.
Host preparation on 2026-10-02: minimal-only --debug-shutdown adds volatile initcall_debug loglevel=8 to the existing exact asj7l4zj5jrjkgng4nrcx3y72p7jf7aa bundle, with exact printed-bootargs validation and a fresh rolling recovery buffer. The 71-test controller suite and strict change validation pass; source checkpoints, operator command, and host-only limits are recorded in docs/evidence/mainline-restart/shutdown-debug-host-preparation-2026-10-02.md. This does not perform or complete automatic restart verification..#kernel, .#deviceTree, and
.#nixosConfigurations.k230.config.system.build.toplevel are
unaffected: git diff --stat 4ffe809a1b448f98379ea1165d7bca067d01cfdb
against this change’s base revision shows exactly 11 files changed,
917 insertions(+), 0 deletions(-) — six new files
(docs/research/mainline-kernel-inventory.md,
nix/device-tree-mainline.nix, nix/dts/k230-tdisplay-mainline.dts,
nix/kernel-mainline-src.nix, nix/kernel-mainline.nix, plus
additive-only lines in flake.nix) and five new OpenSpec change
files. git diff --stat ... -- nix/kernel.nix nix/kernel-src.nix nix/device-tree.nix nix/k230.nix nix/hardware.nix nix/sd-image.nix
returns empty. Confirmed by direct inspection, not by rebuilding
those unaffected derivations (their own existing evidence already
covers them; a change that touches none of their inputs cannot
invalidate it).openspec validate the-board-runs-a-mainline-kernel --strict, checking the exit code directly (never via a pipe), per
AGENTS.md.nix//flake.nix files together on
feat/mainline-kernel, and report the branch/base/commit hash to the
coordinator for an early merge to master, per AGENTS.md’s “keep
changes moving”.Reaching a serial console — and now, potentially, a full NixOS login prompt
over SD — on real hardware is a hardware milestone, not a host build,
per .skills/k230-spec-change/SKILL.md’s QEMU-vs-hardware distinction.
This change does not touch /dev/ttyACM0, does not request a board slot,
and does not claim either gate. The operator command a future change (or
the coordinator, directly) would run once a board slot is free:
flock /tmp/k230-board.lock python3 tools/console.py /dev/ttyACM0 --wait=10
Two staged artifacts now exist, testing two different claims — do not conflate them:
result-kernelMainlineBootFiles (task group 4): console-only,
no drivers beyond UART0. ext4load its Image-mainline and
k230-tdisplay-mainline.dtb, bootm/booti, expect OpenSBI + Linux
boot output and then a panic for lack of a root filesystem (no rootfs
staged; this is a legible-boot-output test, not a login test).result-kernelMainlineConsoleBootFiles (task group 5): the
milestone-1 candidate, with GPIO/SD-MMC/USB forward-ported and this
system’s bootargs+initrd baked in. ext4load its Image-mainline,
k230-tdisplay-mainline.dtb, and initrd.uimg, bootm/booti all
three. Its pass condition is a real login prompt over the SD card’s
existing NIXOS_SD-labeled root partition — genuinely unverified
whether the by-label root resolves, whether &mmc_sd1 actually probes
with the clock/reset IDs nix/dts/k230-tdisplay-mainline.dts guessed,
and whether this system’s own toplevel closure/profile even exists on
that partition (see nix/kernel-mainline-boot-files.nix’s own header:
this derivation does not populate the card, only produces what a
separate staging step would load). A failure here is expected to be
informative (which stage failed) rather than a clean pass on the first
try, and should be recorded as such rather than retried silently.No rootfs is staged by test 1; a kernel panic for lack of one, with
legible OpenSBI + Linux boot output first, is that test’s actual pass
condition (see docs/research/mainline-kernel-inventory.md’s phased plan,
milestone 2).
Exact matching bundle rebuilt, staged as a registered GC-rooted closure, and manually booted with per-load count/CRC checks. Linux 7.3.0-rc5, DRM/fb0 and photographed boot text are observed; Goodix registers. Both temporary boots stop in initrd before root login, including a repeat with direct initrd console diagnostics; no deliberate touch events were obtained. See docs/evidence/mainline-display/physical-2026-10-01/README.md and result.json; task 5b.5 stays unchecked pending usable root, physical touch and committed normal restoration. No persistent normal boot selection was changed.
The first bounded rdinit=/bin/sh diagnosis reached the PID1 shell but
failed command resolution because PATH was absent; its partition-label value
is invalid as hardware evidence. The controller now supplies volatile PATH
and an absolute reboot command. One corrected-path trial then reached the
Linux 7.3.0-rc5 banner but did not return its complete fresh-token probe
marker. One standalone K230_PROC marker appeared; later proc/device/label
and reboot markers did not. No disk or IRQ conclusion follows. A subsequent
physical power-cycle was checked against the protected normal system and all
eight hashes. The controller, sanitized attempt record and proof limits are
recorded in
docs/evidence/mainline-display/physical-2026-10-01/initrd-shell-diagnostic.md.
The 2026-10-02 physical power-cycle after the corrected-path trial restored
the selected normal system with a fresh boot ID, exact system/profile/kernel/
init, three active shell services and eight unchanged protected hashes. See
docs/evidence/mainline-display/physical-2026-10-01/corrected-probe-recovery-2026-10-02/README.md for committed identity and reviewed visible Home proof. Mainline task 5b.5 stays open
for usable root login and deliberate touch evidence. These captures show the
normal vendor-kernel system, not a working mainline shell.
The host controller now waits for one of at most eight fresh-token built-in
receipt attempts, then requires /bin/true, volatile /proc directory setup,
and proc mount RC success before reading uptime or requesting reboot. Failed
prerequisites stop with a structured recovery-required result; the full device
survey requires explicit mode. This source/test follow-up has not been run on
hardware and does not change task 5b.5 evidence status. The preceding physical
minimal attempt remains documented as failed, with later independent normal recovery verified, in
docs/evidence/mainline-display/physical-2026-10-01/minimal-probe-2026-10-02/README.md.
Task 5b.5 remains unchecked. The explicit candidate selector and gated
--mode label controller now pass 49 host tests, including actual sh/bash
execution of the generated device-mount payload against isolated fixtures.
Evidence: docs/evidence/mainline-display/physical-2026-10-01/candidate-controller-host-2026-10-02.md
and docs/evidence/mainline-display/physical-2026-10-01/label-controller-host-2026-10-02.md.
The label mode accepts one read-only root-partition label check only after
receipt, external-command, proc/uptime, devtmpfs and block-node gates. Unknown
completion stops input and leaves recovery unverified. The optional
--ignore-unused-clocks flag adds only a volatile argument for the published
source-audit comparison; it is not a permanent clock policy.
No new board trial or usable-root/touch proof is supplied by these host checks.
The operator must first review the matching restart bundle and prove its
automatic protected-normal return before relying on recovery for label trials.
The bounded --mode root-mount follow-up repeats the minimal/device/label gates
before one ro,noload root mount, strict mount-flag checks and executable
lookups for the selected system’s init/prepare-root, without executing either.
Known mounts receive one bounded unmount; unknown completion stops all input
and leaves recovery unverified. Its 62 host tests include actual isolated sh/bash
mount-table and stub-utility execution. Evidence:
docs/evidence/mainline-display/physical-2026-10-01/root-mount-controller-host-2026-10-02.md.
This does not perform ordinary /init activation or close task 5b.5; matching
bundle review and physical automatic recovery remain prerequisites for the
operator’s root-mount trial. The optional clock flag remains label-only.
Task 5b.5 remains unchecked. The targeted five-clock candidate now passes the
whole corrected --mode root-mount protocol without a clock-ignore flag:
read-only/no-journal mount, exact flags, selected init/prepare-root executable
lookups, unmount and one automatic protected-normal return. Command and
physical result are committed in
docs/evidence/mainline-sd1-clocks/physical-no-flag-2026-10-03/README.md.
The earlier paused session needed the user’s reset after fresh UART checks
received no response; that separate recovery is recorded explicitly.
The reviewed ordinary-init controller (tools/mainline-drm-system-trial.py)
has landed with host proof and protected begin/touch/finish phases; the
coordinator independently passed 122 combined tests. Its physical trial is
separate from the returned read-only prerequisite. Ordinary NixOS activation,
deliberate glass touch and protected recovery remain required before 5b.5
can close. Neither the initrd shell nor host tests establish those outcomes.
The first physical ordinary-init attempt subsequently reached initrd
systemd/udev and timed out after 180 seconds without login. No touch or
reboot retry was sent; recovery is pending operator reset and protected
postflight. See docs/evidence/mainline-system-trial/physical-2026-10-03/README.md.
This failure leaves task 5b.5 open.
The user subsequently reset the ordinary-trial board; fresh protected normal postflight passed exact identities, three services and eight unchanged boot hashes. That operator recovery is now recorded in the same physical packet. The full mainline initrd stopping point remains unresolved; 5b.5 stays open.
The same candidate now passes one bounded udevadm test-builtin blkid on the
verified SD1 root partition, including unique ext4/NIXOS_SD properties,
private raw-output preservation and one automatic protected-normal return.
Exact operator command and physical result are in
docs/evidence/mainline-blkid-trial/physical-2026-10-03/README.md.
This narrows the unresolved ordinary-init/coldplug boundary; it does not prove
whole-device discovery or close 5b.5. The source-supported next observation is
docs/research/mainline-initrd-debug-console-2026-10-03.md; its controller and
physical initrd state/recovery proof are separate required work.
The bounded debug controller reached the fresh mainline/systemd primary shell
prompt, but asynchronous boot messages followed it immediately. Its tail-only
readiness check timed out before sending any diagnostic command. The user reset;
protected normal recovery and qualified Home IPC passed. Exact command, result
and limits are in
docs/evidence/mainline-system-trial/debug-readiness-physical-2026-10-03/README.md.
The prompt-recognition correction needs host review and a separate physical
rerun; initrd unit/worker state is still UNVERIFIED and 5b.5 stays unchecked.
The corrected debug readiness check recognizes the fresh primary prompt, but
the first framed receipt has no command echo or reply within ten seconds. No
identity guard, snapshot or reboot followed. The user reset; protected normal
postflight and Home IPC passed. See
docs/evidence/mainline-system-trial/debug-receipt-physical-2026-10-03/README.md.
Debug-terminal setup and the exact UART receive boundary need source comparison
before another physical retry; no IRQ/clock/terminal cause is claimed. Ordinary
root, deliberate touch and 5b.5 remain open.
The separately built observer bundle passed actual Image/DTB/ramdisk/archive
and closure inspection, staging and protected normal preflight. Its physical
trial produced one complete fresh READY frame, then no counter frame, primary
prompt or return. The host sent zero receipt commands; the bounded passive
wait ended without automatic recovery. The user reset; protected normal postflight
and qualified Home IPC passed. Automatic return remains UNVERIFIED. Exact
artifacts, command, timestamps,
raw-log digest and limits are in
docs/evidence/mainline-system-trial/uart-observer-physical-2026-10-03/README.md.
No helper, UART, console or kernel cause is inferred. Ordinary usable root,
panel photograph, deliberate glass touch and task 5b.5 remain open.
The reviewed controller removed only volatile console=tty0 while retaining
the same built/staged Image, hardware DT, initrd and helper. Protected normal
preflight, loads/CRCs and exact printed arguments passed. Linux reached display
and Goodix registration, then clock/power-domain/ALSA milestones; no init or
systemd banner, observer frame or automatic return was observed. Zero receipt
commands were sent. The user reset; protected normal postflight and qualified
Home IPC passed. Automatic return remains UNVERIFIED. Exact
command/artifacts/timestamps/limits are in
docs/evidence/mainline-system-trial/uart-observer-serial-console-physical-2026-10-03/README.md.
No clock, power-domain, UART or console cause is claimed; further source
discrimination is required. Usable root, panel/touch and task 5b.5 stay open.
The user authorized the same-image comparison before a diagnostic kernel
rebuild. The observer controller now accepts explicit --sbi-boot-console
only with --serial-console-only, adding exactly volatile
earlycon=sbi keep_bootcon while retaining all artifact, identity, printed
argument and recovery gates. Strict observer parsing is unchanged; duplicate
readiness still sends zero receipts. The 38 focused tests and actual selected
artifact preparation pass. Commands and limits are in
docs/evidence/mainline-uart-observer-trial/sbi-boot-console-host-2026-10-03.md.
Host proof does not diagnose the boot stall or prove automatic return; the
separate physical comparison and task 5b.5 remain open.
The same-image serial-only comparison with volatile earlycon=sbi keep_bootcon
passed protected normal preflight, loads/CRCs and printed arguments. Fresh
mainline output confirmed SBI DBCN detection and actual SBI boot-console
enablement; subsequent messages were duplicated. Output ended at the ALSA
milestone (3.838138), with no visible init launch, systemd, observer frame or
automatic return. Zero receipts were sent; the bounded passive trial exited 2.
The user reset; protected normal postflight, qualified Home IPC and a private
camera observation of Home passed. Automatic mainline return remains
UNVERIFIED. Exact command, artifact hashes, sanitized
observations and limits are in
docs/evidence/mainline-system-trial/uart-observer-sbi-boot-console-physical-2026-10-03/README.md.
The trial does not identify a cause; optional kernel boundary markers are the
next source-supported diagnostic. Task 5b.5 stays unchecked.
Within open task 5b.5, the user authorized finite paired kernel markers after
same-image console comparisons failed to reach usable init. Separate
kernelMainlineBootTrace, k230-mainline-boot-trace and
kernelMainlineBootTraceTrialBootFiles outputs add serial-only ordinary init
and exact k230.boot_trace=1; existing outputs/controllers are unchanged.
Seven native flag/emergency/cap tests, zero-fuzz source application, a real
RISC-V main.o API/lifetime check, narrow Nix evaluation and nine unchanged
existing derivation identities passed. Commands, pins and limitations are in
docs/evidence/mainline-system-trial/boot-boundary-host-2026-10-03.md.
Full kernel build/artifact inspection and physical marker/init/root/recovery/
touch proof remain UNVERIFIED. An enter-only marker is only the last visible
boundary; the marker itself can block. Task 5b.5 stays unchecked.
The opt-in kernelMainlineBootTraceTrialBootFiles full build passed at source
7e1e3a60d7ebf607a8312324ae890b97f089b3d1, producing cr8bv4s6… with kernel
908wxcz… and system dxwjvz…. Exact Image/initrd/DT/CRC/closure inspection
and actual ordinary controller preparation passed. The actual built config
has KUnit disabled; the five-clock hardware DT is unchanged except bootargs.
See docs/evidence/mainline-system-trial/boot-boundary-build-2026-10-03/README.md
and its result JSON for commands, paths, hashes and remaining physical gates.
No board was used for this increment; marker output/root/touch/return remain
UNVERIFIED and task 5b.5 remains unchecked.
The exact optional trace bundle passed staging and protected normal preflight,
then emitted basic-setup-enter, initcalls-enter and initcalls-exit on the board.
It produced no next marker or ordinary login within 180 seconds; controller exit 1
closed UART without further candidate input. There is no original blocking work
between the visible post-initcall marker and the missing basic-setup-exit marker,
but the visible marker’s own return/flush/scheduling is not proved. See
docs/evidence/mainline-system-trial/boot-boundary-physical-2026-10-03/README.md
and result JSON. The user pressed reset and protected normal recovery is verified: fresh boot,
exact normal identities, three active services, eight unchanged files and
registration absent. Automatic return remains UNVERIFIED; ordinary root/panel/
glass touch and task 5b.5 stay open.
The reviewed optional kernelMainlineBootTraceSbiTrialBootFiles source adds
four single-attempt public DBCN records around the two printk marker calls
identified by the physical attempt. It preserves all twelve existing output
identities, including the original trace kernel/system/bundle; there is no new
console registration or retry/fallback loop. Ten focused native tests, actual
RISC-V object/API/lifetime/alignment proof and Nix/strictspec checks passed.
See docs/evidence/mainline-system-trial/boot-boundary-sbi-host-2026-10-03.md
for exact commands, source paths and interpretation limits. Full matching build
and physical direct-SBI output/root/login/touch/return remain UNVERIFIED; the
user-reset recovery of the previous diagnostic is verified. Task5b.5 stays open.
kernelMainlineBootTraceSbiTrialBootFiles built successfully at source 007410ee,
producing j0ad6h3s… with kernel f7h2n15… / system zcsfgwk…. Matching Image/
initrd/DT/CRC/closure inspection and actual ordinary-controller preparation
passed. Four public SBI record strings are linked; actual RISCV_SBI/64BIT/
VMAP_STACK/4KiB/KUnit disabled config and hardware DT equality are recorded in
docs/evidence/mainline-system-trial/boot-boundary-sbi-build-2026-10-03/README.md.
No board was used for this increment. Physical direct-SBI output/root/touch/
return stay UNVERIFIED and task 5b.5 stays unchecked.
The exact direct-SBI bundle passed staging and protected normal preflight,
then emitted all four direct records plus legacy seq1–4. Both suspect marker
helpers and do_basic_setup() returned; the final basic-after ECALL return
and entry to the next marker/initramfs wait remain unknown. No login arrived
within 180 seconds; controller exit1 closed UART without further input. See
docs/evidence/mainline-system-trial/boot-boundary-sbi-physical-2026-10-03/README.md
and result JSON. The subsequent user-confirmed reset received zero UART bytes
in90seconds and no fresh normal prompt; no Linux command was sent. The camera
shows a dark panel with observation limits. operator-reset-check.json records
this failed check; power-cycle confirmation is pending. Protected recovery,
ordinary root/panel/glass/production and task 5b.5 remain open.
The reviewed optional kernelMainlineBootTraceSbiOnlyTrialBootFiles layers
over the original trace source and selects single-attempt fixed public SBI
records at all twenty existing diagnostic sites. Enabled mode skips only
the diagnostic helper’s printk/emergency operations; regular kernel logging
is unchanged. Eleven focused /28 combined native tests, actual RISC-V object/
lifetime/table layout, exact source order, narrow Nix evaluation and all
fifteen previous derivation identities passed. See
docs/evidence/mainline-system-trial/boot-boundary-sbi-only-host-2026-10-03.md.
The source has landed; full matching bundle build and physical output/root/
touch/return remain UNVERIFIED. The preceding reset check failed with zero
UART bytes; protected normal recovery must pass before another board trial.
Task5b.5 stays open; visible SBI bytes do not prove the last ECALL returned.
The user’s second confirmed reset passed fresh protected normal postflight,
unchanged identities/eight files, three active services and registration
absence. Home IPC returned RC0 and reviewed private camera shows normal Home;
see docs/evidence/mainline-system-trial/boot-boundary-sbi-physical-2026-10-03/operator-reset-recovery.json.
This is operator recovery; automatic return from the failed trial stays
UNVERIFIED. The matching SBI-only bundle brmp1qf9… built successfully,
with actual config/source/all20 linked strings, hardwareDT, Image/initrd/CRC/
closure and ordinary-controller host preparation checks passed. See
docs/evidence/mainline-system-trial/boot-boundary-sbi-only-build-2026-10-03/README.md.
SBI-only physical output/login/root/glass/automatic return remain UNVERIFIED;
5b.5 stays open before the separately reserved board attempt.
The matching SBI-only bundle passed staging and protected normal preflight,
then emitted five complete fixed labels through initramfs-wait-enter, with
zero legacy markers. No exit/login followed within 180 seconds; controller exit 1
released UART with no further input. The preceding basic-setup SBI call
returned; the last ECALL return and actual wait entry remain unknown. The
external Unpacking initramfs... printk was visible, with no completion proof.
See docs/evidence/mainline-system-trial/boot-boundary-sbi-only-physical-2026-10-03/README.md
and result JSON. Operator reset recovery is pending; automatic return,
ordinary root/panel/glass and 5b.5 remain open. Read-only audit is evaluating
a same-Image initramfs_async=0 comparison before another kernel rebuild.
Independent source audit supports one volatile initramfs_async=0 token
as the next bounded discriminator: the same worker is scheduled, then the
rootfs initcall joins it before later initcalls. The controller’s reviewed
begin-only --wait-initramfs-in-initcall preserves exact artifact/identity/
CRC/argument/state/recovery gates and the 180-second passive deadline.
Corrected focused 29 tests, actual matching-bundle prepare/unchanged drv,
strict/all validation and whitespace checks passed. Evidence and exact
operator command: docs/evidence/mainline-system-trial/initramfs-initcall-controller-host-2026-10-03.md.
This is host proof only. Current candidate reset recovery and the new
physical comparison remain UNVERIFIED; ordinary root/glass/return and 5b.5
stay open. No kernel rebuild, board command or production fix is claimed.
The user hit reset and fresh protected normal postflight passed exact
identities, three services, all eight unchanged files and registration
absence. Home IPC returned RC0; reviewed private camera shows normal Home.
See docs/evidence/mainline-system-trial/boot-boundary-sbi-only-physical-2026-10-03/operator-reset-recovery.json.
Automatic return from the failed candidate remains UNVERIFIED. Reviewed
controller 1846fd3e and its29 focused tests passed CI; the same-image
initramfs comparison is ready for a separately reserved physical attempt.
Ordinary root/glass/production and5b.5 remain open.
The exact same staged bundle with one volatile initramfs_async=0 argument
passed protected preflight/loads/CRCs/printed arguments and emitted18 fixed
records through init-exec-exit, including the earlier rootfs join and later
initramfs wait completion. No login arrived in180seconds; controller exit1
released UART without further input. kernel_execve() returned but retval,
last SBI return and first userspace instruction are unknown. See
docs/evidence/mainline-system-trial/initramfs-initcall-physical-2026-10-03/README.md
and result JSON. Operator reset recovery is pending; ordinary root/panel/
glass/automatic return and5b.5 stay open. Read-only source audit recommends
a same-image no-marker comparison preserving async=0 and normal logging;
reviewed controller support is required before another boot.
The user reset after the failed18-record comparison. Fresh protected normal
postflight, exact identities/eight files/three services/registration absence
passed; Home IPC returned RC0 and a newly reviewed private camera shows Home.
See docs/evidence/mainline-system-trial/initramfs-initcall-physical-2026-10-03/operator-reset-recovery.json.
This proves operator recovery only; automatic return, mainline root/panel/glass
and task 5b.5 remain UNVERIFIED. Board/UART and camera are released.
The begin-only --without-boot-markers opt-in requires the earlier initramfs
join selector and removes both original qualified trace-enable tokens only.
Same Image/closure/DT/logging/controls and exact identity/CRC/arguments/typed
resume/recovery/180-second unknown gates remain. Literal transport is safe
and below 512 bytes before first input. 36 focused tests passed independently;
actual realized-bundle prepare differs only by the two removed tokens and
uses 317 bytes. Narrow proof and operator command:
docs/evidence/mainline-system-trial/marker-free-controller-host-2026-10-03.md.
Host proof only; physical root/panel/glass/return and 5b.5 remain UNVERIFIED.
Same staged Image/initrd/DT/closure with initramfs_async=0 retained and both
marker flags removed passed preflight, five loads/CRCs and exact printed plus
kernel-received arguments. No diagnostic records, as expected; unpacking,
initrd-free and unused-kernel-image-free messages appeared, but no systemd/login
within 180 seconds. Exit 1 released UART without further input. New private
camera appears dark with documented limits. See
docs/evidence/mainline-system-trial/marker-free-physical-2026-10-03/README.md
and fixed result JSON. Another operator reset/protected normal postflight is
pending. Source audit suggests a separately reviewed same-initrd Bash-PID1
comparison, not ordinary-root acceptance. 5b.5 remains unchecked; mainline
root/panel/glass/automatic return and production remain UNVERIFIED.
The user pressed reset after the failed marker-free trial. Fresh protected
normal postflight passed exact identities, all eight files, three services
and registration absence; Home IPC returned RC0 and a new reviewed private
camera shows normal Home. See
docs/evidence/mainline-system-trial/marker-free-physical-2026-10-03/operator-reset-recovery.json.
This is operator recovery only. Automatic return, mainline ordinary root,
panel/glass and task 5b.5 remain UNVERIFIED. Board/UART/camera are released;
the next guarded same-image Bash-PID1 controller increment is host work.
The explicit minimal-only --same-image-shell-pid1 selector uses the same
qualified marker-free/async=0 bundle and three controls, adding only
rdinit=/bin/sh. Original artifacts, archived Bash/systemd/common loader,
safe literal transport before UART and exact printed arguments are checked.
Fresh Linux/init-entry/prompt/receipt precede proc/uptime and strict PID1/root/
Bash/kernel/cmdline/new-boot/initrd guards, renewed before one acknowledged
reboot. Both protected normal phases assert registration absence. Unknown
stops input; ordinary init is NOT_ATTEMPTED. Independent review approved;
14 focused and all 214 existing trial tests passed, strict/all56 validation
and exact realized-bundle single-variable preparation passed. Narrow commands
and operator gate:
docs/evidence/mainline-system-trial/shell-pid1-controller-host-2026-10-03.md.
CI covers ordinary/minimal/new focused tests. Physical shell receipt/automatic
return are still UNVERIFIED; ordinary root/panel/glass and task 5b.5 stay open.
Reviewed source/CI bfce9f8b passed a reserved single trial’s protected preflight,
five loads/CRCs and exact printed plus kernel-received arguments. Fresh Linux,
Run /bin/sh and primary sh-5.3 prompt prove Bash userspace startup. Eight bounded
builtin receipt attempts produced no replies/echoes; exit 2 at reception
released UART with no further input. True/proc/uptime/full identity/reboot were
NOT_ATTEMPTED. See
docs/evidence/mainline-system-trial/shell-pid1-physical-2026-10-03/README.md
and fixed result JSON. New private camera appears dark with explicit limits;
serial startup proof is separate. A subsequent new user reset and checker
exit 0 proved a fresh protected normal boot, exact system/profile/kernel/init,
eight unchanged files, three active services and registration absence. Home
IPC completed with exit 0 and a new privately reviewed camera frame shows
normal Home; see the packet’s operator-reset-recovery.json. Board/UART and
camera are released. This proves operator recovery, not automatic return.
Read-only audits recommend a finite independent cached UART/IRQ/time reporter,
not a blind shell retry or TTY poll. Ordinary root/panel/glass/automatic return
and task 5b.5 remain UNVERIFIED; no archive or production fix is claimed.
python3 tests/test_mainline_uart_progress.py.
Twelve actual-code native fixtures pass; the optional effective Kconfig
resolves built-in reporter/dependencies and 22 existing output identities
are unchanged. Source/config/object evidence.
At this initial source proof, the full matching build and physical observations were UNVERIFIED; later host build proof is recorded in 5f.2–3.nix build .#kernelMainlineUartProgressExactObjects --no-link --print-out-paths.
Three changed RISC-V objects compile against immutable installed base
headers plus an explicit reporter overlay; preliminary layout/API proof passed.
ExactObjects subsequently passed against the actual selected kernel.dev
config/autoconf without an overlay; all three ELF/lifetime/layout checks
passed. Exact/full host proof.nix build .#kernelMainlineUartProgressTrialBootFiles --no-link --print-out-paths
followed by python3 tools/mainline-drm-trial-inspect.py BUNDLE.
Root’s frozen 35e93757 matching build passed; gmsmqk bundle inspection,
Image/system/initrd/DT/CRCs/closure/config checks and hardware-DT comparison
passed. Existing identity receipts remain separate from physical proof;
no UART/receipt/root/touch/recovery result is claimed.python3 tests/test_mainline_uart_progress_controller.py and
python3 -m unittest discover -s tests -p 'test_mainline_drm*trial.py'.
Controller source/fixture preparation is recorded in
docs/evidence/mainline-uart-progress-controller/README.md; this task
actual matching bundle/config qualification subsequently passed.
Matching controller host proof.python3 tools/mainline-drm-initrd-shell-trial.py --mode minimal --same-image-shell-pid1 --uart-progress --bundle BUNDLE --manifest PRIVATE_MANIFEST --normal-report PRIVATE_NORMAL --log PRIVATE_LOG --result PRIVATE_RESULT.
Commit fixed records/stimulus/interpretation and protected normal
postflight or explicit pending operator recovery. This proves only the
observations obtained, not full root/panel/glass acceptance.
Physical finite observation: exact received arguments and Bash prompt, one stimulus,
zero receipts and zero records; subsequent protected operator reset/postflight verified
(fresh boot, exact identities, eight files, three services, registration absence).
This is observation-only, not successful diagnostic/root/touch acceptance.openspec validate the-board-runs-a-mainline-kernel --strict.
Zero-report limits and manual protected recovery are committed in the
physical packet.
Recovery revision 5cdff03b passed CI 37166330080 and published work/evidence
checks; the reviewed continuation is preserved as planned group 5g below.
No ordinary-root/touch/automatic-recovery result is inferred.python3 tests/test_mainline_uart_progress_breadcrumbs.py.
Source-host increment: thirteen actual patched-worker native fixtures and
twelve original source/API fixtures passed; evaluation preserves all 91
existing package identities and ten kernel source/config pairs. Exact
original-source layering and inherited config/params are recorded in
source-host evidence.
This is not a full matching build, actual configured object or physical proof.nix build .#kernelMainlineUartProgressBreadcrumbsTrialBootFiles --no-link --print-out-paths
then python3 tools/mainline-drm-trial-inspect.py BUNDLE.nix build .#kernelMainlineUartProgressBreadcrumbsExactObjects --no-link --print-out-paths.
Actual host proof: coordinator frozen 2a548135 resumed build returned 0;
verifier source 071086bc exact-object command returned 0 under shared lock.
Selected dev config/autoconf, three RISC-V objects/regular aligned storage,
source 7207, full bundle hashes/CRCs/closure and complete hardware DT equality
passed. Exact/full host evidence.
The initial coordinator session 143/broken-pipe interruption is distinct
from the successful completion receipt. No hardware/RX/return result is
inferred; tasks 5g.5–6 and task 5b.5 remain open.python3 tests/test_mainline_uart_progress_breadcrumbs_controller.py
and python3 -m unittest discover -s tests -p 'test_mainline_drm*trial.py'.
Controller host preparation is recorded in
docs/evidence/mainline-uart-progress-breadcrumbs/controller/README.md.
Pre-UART qualification additionally ties the same kernel drv to its
immutable reviewed worker source and unique compiled Image marker/gate
bytes, rejecting the old reporter even with CONFIG=y. Actual matching
bundle/dev/source preparation passed on 2026-10-04UTC against mhq10143…,
as recorded in
docs/evidence/mainline-uart-progress-breadcrumbs/positive-controller-host/README.md
and result.json; the named fixture commands also passed, preserving a
separate quota failure and bounded ~/tmp rerun. This is host-only proof;
group5g.5 and task 5b.5 remain open, without candidate reboot or hardware claim.
Integrated source/controller checks include strict CRLF/embedded-CR framing and CI coverage.python3 tools/mainline-drm-initrd-shell-trial.py --mode minimal --same-image-shell-pid1 --uart-progress --uart-progress-breadcrumbs --bundle BUNDLE --manifest PRIVATE_MANIFEST --normal-report PRIVATE_NORMAL --log PRIVATE_LOG --result PRIVATE_RESULT.
No further input or candidate reboot after the single stimulus; this is
observation only, not ordinary-root/touch or automatic-return acceptance.
Actual comparison: matching mhq10143 bundle staged with return 0; fresh
protected preflight/load checks passed. Both fixed breadcrumbs, one
matching Bash receipt and samples 0/1 arrived; samples 2–5 and normal return
did not arrive in 180.084 seconds. No further input or candidate reboot.
Physical evidence
records fixed facts/deltas, firmware-return limits and distinct operator-reset
recovery verified after the capture. This is observation proof only; task 5b.5 stays open.openspec validate --all.The group 5g observation and interpretation landed as 278769d0. CI run
37171186624 passed build/deploy; both published work and physical evidence pages
returned HTTP 200 with exact revision 278769d0. The committed deployment receipt
is docs/evidence/mainline-uart-progress-breadcrumbs/physical-2026-10-03/deployment.json.
Independent review matched the fixed public facts/deltas to the private capture.
Both markers and receipt are proven; later sample/firmware-return/normal-return
remain unknown. The separately proposed next discriminator targets the sample 1
write return versus third sleep. The subsequent user reset passed fresh protected
normal postflight and Home IPC, with separately reviewed camera Home;
docs/evidence/mainline-uart-progress-breadcrumbs/physical-2026-10-03/operator-reset-recovery.json
records exact limits. Automatic return and task 5b.5 stay open.
python3 tests/test_mainline_uart_progress_post_sample.py plus unchanged-output/source/config identity evaluation.
Native 15 new fixtures and 13/12 prior fixtures passed; all 95 prior
package identities and 11 exposed kernel source/config pairs were equal.
Source-only/native/pure-evaluation receipt: source host proof.
No matching full build, target object or physical claim follows.nix build .#kernelMainlineUartProgressPostSampleTrialBootFiles --no-link --print-out-paths
then python3 tools/mainline-drm-trial-inspect.py BUNDLE.
Matching full build from frozen 75cc49df returned 0; actual inspector,
installed config, source layering, linked Image and complete hardware DT
comparison passed. Exact/full host proof; no physical claim.nix build .#kernelMainlineUartProgressPostSampleExactObjects --no-link --print-out-paths.
Narrow offline exact-object build from source checkpoint e3edc5e6
returned 0 against actual selected dev, without overlay; three RISC-V
objects, four aligned ordinary-rodata records, original 256-byte buffer
and unchanged getter dependencies passed inspection. Same host proof;
controller/physical/receipt/recovery gates remain separate and open.--uart-progress-post-sample requiring all
previous comparison selectors. Preserve exact pre-UART artifact/source/
linked Image/dev checks, sole new volatile gate, received args/freshness,
protected normal checks, one stimulus and no later input/reboot. Strict
record tests cover split transport, complete/partial, stale/echo/extra/
duplicate/reorder/interleave and missing-point/numeric/receipt facts.
Host-only proof: python3 tests/test_mainline_uart_progress_post_sample_controller.py
plus existing minimal/progress/breadcrumb controller regression commands.
Keep this task unchecked until actual NEW matching bundle/dev/source/Image
positive preparation passes. Fixtures and old-artifact rejection alone
do not satisfy that gate or establish a performed protected board check.
Preparation evidence: PostSample controller host note
records 20 focused tests plus unchanged 18 breadcrumb/20 progress/100
minimal/14 shell/36 ordinary tests, the strict source/Image/config gate,
and actual old matching artifact rejection before UART access. Actual NEW
positive preparation now passed against frozen 75cc49df and realized fjmxf6
bundle/js4by9 dev: positive host proof.
Same-drv config, reviewed aee68 source, linked unique Image strings, actual
archived executables/common loader and exact sole additional gate passed;
literal transport 419 bytes versus 386. No UART/build or performed protected
board check by this qualifier. One fresh stimulus is followed only by
passive bounded capture; no candidate reboot, extra input or physical claim
is authorized by marker presence. Tasks 5h.5–6 and 5b.5 remain open.python3 tools/mainline-drm-initrd-shell-trial.py --mode minimal --same-image-shell-pid1 --uart-progress --uart-progress-breadcrumbs --uart-progress-post-sample --bundle BUNDLE --manifest PRIVATE_MANIFEST --normal-report PRIVATE_NORMAL --log PRIVATE_LOG --result PRIVATE_RESULT.
Missing output remains unknown; no further input or candidate reboot.
This is diagnostic observation, not ordinary-root/touch/automatic return.
Actual fjmxf6 comparison completed: physical capture.
Fresh args/Bash/worker-entry, one stimulus, no receipt/samples/new points
during 180.0975s; no protocol errors or candidate reboot. New operator
reset subsequently passed fresh guarded normal postflight and reviewed
Home: reset receipt.openspec validate the-board-runs-a-mainline-kernel --strict.Group5h source, exact/full artifacts, actual positive preparation and physical capture are complete. Independent review matched private facts/hash. Evidence 08ea7370 passed CI37175128998; work and physical pages returned HTTP200 with that exact revision: committed physical deployment.json. Only worker-entry arrived; neither entry ECALL return nor first sleep/output is established. The subsequent NEW reset passed guarded fresh normal postflight/Home evidence; automatic return and5b.5 stay open. Group5i is a separate output-removal intervention, not a claimed cause or silent scope completion of ordinary mainline acceptance.
python3 tests/test_mainline_uart_progress_memory.py.
Actual-code 13 fixtures and prior 15/13/12 fixtures passed; all 99 prior
package drv identities and 12 exposed kernel source/config pairs equal.
Source/native/pure-evaluation proof; no matching full artifact, target-object,
controller or physical claim follows. Other 5i gates stay open.nix build .#kernelMainlineUartProgressMemoryTrialBootFiles .#kernelMainlineUartProgressMemory.dev --no-link --print-out-paths
then python3 tools/mainline-drm-trial-inspect.py BUNDLE.
Matching frozen 7af8f7b8 full build returned0; actual selected source,
config/Image/initrd/CRCs/closure/original args/full hardware DT passed.
Exact/full host proof; no physical claim.nix build .#kernelMainlineUartProgressMemoryExactObjects --no-link --print-out-paths.
Offline narrow build from source checkpoint 29979175 returned0 against
actual selected dev, no overlay; three RISC-V objects, Memory observer/
state/completion/256-aligned buffer, target acquire/release/API and
inherited buffers/getters passed. Same host proof; concurrency/physical
output/receipt/recovery remain unverified.python3 tests/test_mainline_uart_progress_memory_controller.py.
Preparation: Memory controller host proof
records 20 exact-summary/real-pump/transport/qualification fixtures plus
unchanged 20 PostSample/18 Breadcrumbs/20 numeric/100 minimal/14 shell/36
ordinary checks. Actual fjmxf6 old artifact fails the new reviewed worker
gate before UART. Consistent incomplete/timeout summary, worker completion,
receipt and protected return remain independent facts; no candidate reboot
or extra input follows. Actual NEW positive host proof
now passes against frozen 7af8f7b8, realized lznjjfx1 bundle/1pvqbm4 dev,
same-drv config, reviewed 307d7c source, unique linked summary format/setup,
actual archived executables/shared loader and sole additional gate
(353 to 381-byte literal command). No UART/build or performed protected
board check by this qualifier. Tasks 5i.5–6 and 5b.5 remain open.python3 tools/mainline-drm-initrd-shell-trial.py --mode minimal --same-image-shell-pid1 --uart-progress --uart-progress-memory --bundle BUNDLE --manifest PRIVATE_MANIFEST --normal-report PRIVATE_NORMAL --log PRIVATE_LOG --result PRIVATE_RESULT.
Memory progress/output/receipt/recovery remain separate; 5b.5 stays open.
Actual lznjjfx1 comparison completed: physical capture.
Fresh banner/args/Bash, one stimulus, no receipt or summary in 180.1021s;
no errors or candidate reboot. Subsequent NEW operator reset passed protected
normal postflight/Home camera checks: recovery receipt.openspec validate the-board-runs-a-mainline-kernel --strict.
Independent physical review passed; master 136dbf91, CI37178946290
PASS and exact published work/evidence revision verified HTTP200:
publication receipt.
Subsequent NEW reset recovery is verified; ordinary acceptance 5b.5 stays open.python3 tests/test_mainline_uart_progress_memory_no_stimulus_controller.py.
Host implementation/15 real-pump fixtures and 228 previous controller tests
passed; independent source review PASS. Host proof.
Physical no-stimulus capture/recovery remain UNVERIFIED.prepare_trial + prepare_uart_progress(..., uart_progress_memory=True)
and exact equality with selected no-stimulus transport. No kernel rebuild.
Actual existing lznjjfx1/1pvqbm4 preparation PASS on c62ad389; exact same
source/Image/config/archive/manifest and 381-byte Memory transport, no added
token/build/UART. Executed qualifier and safe receipt.
Historical baseline acceptance is host-only; fresh physical preflight and
no-stimulus capture/recovery remain UNVERIFIED.python3 tools/mainline-drm-initrd-shell-trial.py --mode minimal --same-image-shell-pid1 --uart-progress --uart-progress-memory --uart-progress-memory-no-stimulus --bundle BUNDLE --manifest PRIVATE_MANIFEST --normal-report PRIVATE_NORMAL --log PRIVATE_LOG --result PRIVATE_RESULT.
No RX, root/glass or cause inference; 5b.5 stays open.
Actual zero-input capture:
fresh banner/args/Bash, zero attempts/NOT_REQUESTED/RX NOT_TESTED, no summary
in 180.0995s, no protocol error or normal return. Subsequent NEW operator
reset passed protected normal/Home checks: recovery receipt.openspec validate the-board-runs-a-mainline-kernel --strict.
Independent physical review PASS; master 691279d0, CI 37180546857
PASS and exact published work/evidence revision HTTP 200 verified:
publication receipt.
Subsequent NEW recovery is verified; ordinary acceptance 5b.5 stays open.python3 tests/test_mainline_uart_progress_memory_poll_idle_controller.py.
Typed one-token comparison/14 focused fixtures and 243 prior controller
tests PASS; independent source review PASS. Host implementation proof.
Actual preparation and physical comparison/recovery remain separate gates.prepare_trial, prepare_uart_progress(..., uart_progress_memory=True)
plus typed polling preparation and exact previous-proof artifact equality.
Actual existing artifact qualification PASS on d10b8fa0; same lznjjfx1/
1pvqbm4 source/Image/config/DT/archive/manifest, singleton supported setup
and exact381→387-byte transform. Safe receipt/executed qualifier.
Initial host harness comparison failure is preserved; corrected gate PASS.
No build/UART/live preflight. Physical polling/recovery remain UNVERIFIED.python3 tools/mainline-drm-initrd-shell-trial.py --mode minimal --same-image-shell-pid1 --uart-progress --uart-progress-memory --uart-progress-memory-no-stimulus --uart-progress-memory-poll-idle --bundle BUNDLE --manifest PRIVATE_MANIFEST --normal-report PRIVATE_NORMAL --log PRIVATE_LOG --result PRIVATE_RESULT.
No cause/RX/ordinary-root inference; 5b.5 stays open.
Actual polling capture and subsequent protected recovery:
exact nohlt args/Bash, zero input, no summary/normal return in 180.0929s;
no protocol error. Subsequent NEW reset passed normal/Home checks; normal
system restored. Automatic return and ordinary acceptance remain UNVERIFIED.openspec validate the-board-runs-a-mainline-kernel --strict.
Independent physical/recovery review PASS; master e2a02cb0, CI
37182761318 PASS and exact published work/evidence revision HTTP 200
verified: publication receipt.
Normal is restored; no timer/firmware cause or ordinary acceptance inferred.python3 tests/test_mainline_uart_progress_memory_printk.py;
evaluate every prior package/source/config/trial identity and new source only.
Preparation: corrected leading-LF one-call source and 10 actual-code native
tests passed; the inherited worker/init tail and atomic/completion behavior
are unchanged. All 103 previous package drv identities and 13 kernel
source/config pairs equal; corrected source realized and hash independently
reviewed. Source/native/evaluation proof.
Exact/full/controller/physical gates remain separate and unchecked.nix build .#kernelMainlineUartProgressMemoryPrintkTrialBootFiles .#kernelMainlineUartProgressMemoryPrintk.dev --no-link --print-out-paths -L.
Preserve full build receipt and actual config/DT/Image/initrd/archive identities.
Performed: coordinator full matching build at frozen 1c59f856 returned 0;
actual p2kdar bundle and 24hbal dev pass Image/system/kernel/initrd/CRC/closure
inspection, original arguments and complete hardware-DT comparison. Installed
config/autoconf bytes equal the Memory parent; PRINTK_CALLER is disabled.
Actual exact/full host proof.nix build .#kernelMainlineUartProgressMemoryPrintkExactObjects --no-link --print-out-paths -L.
Performed: only the named offline exact-object output built under a nonblocking
shared lock from source revision bd092485; actual selected dev headers/config,
three GCC RISC-V objects, ordinary lifetimes, acquire/release/completion APIs and
unique regular-rodata leading-newline KERN_INFO format passed. The target observer
has the ordinary printk call; source/native proof establishes selected return
without DBCN fallback. Pahole-version warning retained, no C warning observed.
Host object proof does not establish console/timer/observer execution.python3 tests/test_mainline_uart_progress_memory_printk_controller.py.
Then run actual matching artifact/controller preparation and commit safe
receipt/executed qualifier; no UART or implicit build. Source hash must be
the independently reviewed realized variant, not an unknown placeholder.
Controller preparation/20 corrected fixtures and prior controller regressions
PASS; root independent review PASS. Host preparation.
Actual new bundle p2kdar89 / dev 24hbalyl / reviewed worker 30e8eb1e
qualification PASS (2026-10-04 07:15 UTC, exit 0): same-derivation actual
config, linked Image/format/setup, DT/archive/load/CRC and sole gate
transport 381→416 bytes; no UART/build/new board preflight.
Executed qualifier and safe receipt.
Historical protected normal report is a host anchor only; physical
observation/recovery and ordinary root/touch remain UNVERIFIED.python3 tools/mainline-drm-initrd-shell-trial.py --mode minimal --same-image-shell-pid1 --uart-progress --uart-progress-memory --uart-progress-memory-no-stimulus --uart-progress-memory-printk --bundle BUNDLE --manifest PRIVATE_MANIFEST --normal-report PRIVATE_NORMAL --log PRIVATE_LOG --result PRIVATE_RESULT.
No output-return/cause/RX/ordinary-root inference; 5b.5 stays open.
Actual new-channel capture:
fresh exact args/registered Linux backend/bin-sh entry, zero input, no UMK
or normal return in 180.1019s. Original prompt classification misses the
observed Readline prefix; later host-only correction preserves original
physical result. Subsequent NEW reset passed protected normal/Home recovery;
follow-up receipt.openspec validate the-board-runs-a-mainline-kernel --strict.
Independent physical-packet review PASS; master adf3ac81, CI
37186803102 PASS and exact published work/physical/readiness evidence
revision HTTP 200 verified: publication receipt.
Publication receipt reflects recovery pending at that revision; subsequent
NEW protected recovery is recorded separately. No ordinary acceptance inferred.--uart-progress-memory-printk-nohz-off and focused fixtures.
Require existing minimal/same-image/progress/Memory/no-stimulus/MemoryPrintk;
reject conflicts/types/modes before UART. Qualify actual compiled config/Image
setup; append only trailing nohz=off. Preserve defaults, strict parsing,
zero candidate writes and protected recovery. No build/UART. Narrow proof:
python3 tests/test_mainline_uart_progress_memory_printk_nohz_off_controller.py.
Source/fixture proof:
13 focused plus 23 MemoryPrintk/14 polling/15 no-stimulus PASS; actual
existing-artifact gate remains pending under 5m.2. No UART/build.python3 docs/evidence/mainline-uart-progress-memory-printk/nohz-off-host/qualification-command.py --bundle BUNDLE --dev DEV --normal-report PRIVATE_NORMAL.
The executed private copy records its frozen source/worktree and private
output directory; no implicit build or UART. Freeze and review its exact
code/parameters before physical use.python3 tools/mainline-drm-initrd-shell-trial.py --mode minimal --same-image-shell-pid1 --uart-progress --uart-progress-memory --uart-progress-memory-no-stimulus --uart-progress-memory-printk --uart-progress-memory-printk-nohz-off --bundle BUNDLE --manifest PRIVATE_MANIFEST --normal-report PRIVATE_NORMAL --log PRIVATE_LOG --result PRIVATE_RESULT.
No cause/RX/output-return/ordinary-root inference; 5b.5 stays open.
Actual same-image nohz-off capture:
fresh exact args/backend/Bash readiness, zero input, no UMK/normal return
in 180.025s, no protocol error. Prior NEW recovery verified; another NEW
reset after this capture remains explicitly PENDING. Same-source-only
restoration and fresh host requalification are recorded separately.openspec validate the-board-runs-a-mainline-kernel --strict.
Independent physical/recovery review PASS; master b04ac4d0, CI
37245257792 PASS and exact work/new physical/previous recovery publication
HTTP 200 verified: publication receipt.
Subsequent NEW nohz-off protected recovery passed: distinct boot, exact identities/eight hashes/three services/registration absence. Automatic return and 5b.5 stay UNVERIFIED. 5n.1 Establish native exact Hush lexer/variable/quote/command execution and
selected Linux next_arg/repair/set_init_arg argv proof for the fixed scout
script/transport. Verify one volatile setenv, exact 477-byte result/two argv,
zero expansion/extra/persistent commands and unchanged 512-byte bound.
Source models/shlex alone do not pass. No UART/kernel build. Narrow proof:
python3 tests/test_mainline_autonomous_bash_pid1_argv.py.
Native host proof: 12 tests PASS; full unchanged pinned Hush dispatch and
exact selected Linux argv functions recover 477-byte bootargs and two argv.
Receipt
records hooks/registration adapters and installed/target/physical limits.
5n.2 Implement only typed --autonomous-bash-pid1 requiring minimal/same-image
and rejecting competing selectors/types/modes/altered syntax before UART.
Add strict fresh-nonce begin/end parsing and 60-second zero-input capture, separate
prompt/unknown/normal recovery, unchanged defaults and failure/finally write
spies. Narrow proof: python3 tests/test_mainline_autonomous_bash_pid1_controller.py.
Host source checkpoint: controller preparation; 16 focused fixtures PASS, strict/affected regressions PASS. No UART/build; actual artifact/native qualification remains 5n.3 and physical 5n.4 remains open.
5n.3 Execute actual same p2/24h artifact/controller preparation and qualify
source/config/Image/DT/archive/manifest/loads, executable sh/sleep ABI/loader
and Bash builtins. Commit executed qualifier and safe receipt, exact fixed
args/503-byte transport and native proof; no implicit build/UART. Command:
python3 docs/evidence/mainline-autonomous-bash-pid1/host/qualification-command.py --bundle BUNDLE --dev DEV --normal-report PRIVATE_NORMAL.
Actual host qualification PASS on corrected root82b27a36: same p2/24h/0l4 artifacts/archive/loader/Bash exports, committed native receipt/fixtures/selected Linux/vector, exact154/477/503 bytes, historical normal anchors only. No UART/build; 5n.4 requires NEW protected recovery and remains open.
5n.4 After NEW protected recovery plus reviewed native/controller/actual host
gates, reserve board/UART for one 60-second passive comparison and commit fixed
records/facts plus independent recovery or explicit pending NEW reset.
Command: python3 tools/mainline-drm-initrd-shell-trial.py --mode minimal --same-image-shell-pid1 --autonomous-bash-pid1 --bundle BUNDLE --manifest PRIVATE_MANIFEST --normal-report PRIVATE_NORMAL --log PRIVATE_LOG --result PRIVATE_RESULT.
Keep RX/output-return/cause/ordinary-root limits; 5b.5 stays open.
Physical autonomous capture: strict B then E and later primary prompt in60.035s, exact candidate arguments/backend/bin-sh entry, zero input/errors. Selected sleep returned; RX and ordinary init/root/glass remain UNVERIFIED. Capture complete; subsequent NEW protected recovery is verified in recovery.json, independently reviewed. No prior reset reused.
5n.5 Independently review parser/execution/recovery limits, land/push evidence
and inspect exact CI/published revision. Planning proof:
openspec validate the-board-runs-a-mainline-kernel --strict.
Independent raw/parser/load/recovery-limits review PASS; physical evidence master ad746e5b, CI37250588096 PASS, exact work/autonomous/nohz-recovery publication HTTP200 verified: [publication receipt](../../../../docs/evidence/mainline-autonomous-bash-pid1/physical-2026-10-05/publication.json). Subsequent NEW [autonomous recovery](../../../../docs/evidence/mainline-autonomous-bash-pid1/physical-2026-10-05/recovery.json) passed exact identities/eight boot hashes/three services/registration absence with a distinct boot; automatic return and ordinary init/root/panel/glass task5b.5 stay UNVERIFIED.
python3 tests/test_mainline_initrd_debug_logging.py.
Host controller proof: 13 focused plus 36 existing tests PASS, independently rerun; reviewed source integrated ec121e6d, CI37255138757 PASS. No UART/build.python3 docs/evidence/mainline-initrd-debug-logging/host/qualification-command.py --bundle BUNDLE --dev DEV --normal-report PRIVATE_NORMAL.
Executed actual preparation exit0 on ec121e6d, same artifacts/archive, exact356/374 vs317 bytes and fresh preceding recovery anchor; independent review PASS. No live preflight/UART/build.python3 tools/mainline-drm-system-trial.py begin --wait-initramfs-in-initcall --without-boot-markers --initrd-debug-logging --bundle BUNDLE --manifest PRIVATE_MANIFEST --normal-report PRIVATE_NORMAL --state NEW_PRIVATE_STATE --log PRIVATE_LOG --result PRIVATE_RESULT.
No nested-command/call/cause or ordinary-root inference; 5b.5 stays open.
Actual passive capture: same artifacts/exact args, fresh Linux/Run init announcement but no systemd/closure/login in 180s, exit1, zero later input in source/annotations; independent full review PASS. Subsequent NEW protected recovery passed; see recovery.json.openspec validate the-board-runs-a-mainline-kernel --strict.
Independent physical/parser/load/argument/no-input review PASS; master50daca22, CI37256024917 PASS and exact work/host/physical publication HTTP200 verified: publication receipt. Subsequent NEW protected recovery passed; automatic return and5b.5 stay UNVERIFIED.python3 tests/test_mainline_initrd_info_logging.py.
Source/controller proof: exact selected261.2 source pin/patch scope checked; 10 new+13debug+36ordinary tests PASS, independently rerun; reviewed source integrated94c78157. No UART/build.python3 docs/evidence/mainline-initrd-info-logging/host/qualification-command.py --bundle BUNDLE --dev DEV --normal-report PRIVATE_NORMAL.
Actual same-artifact qualification exit0 on94c78157, exact355/373 versus356/374, latest NEW protected recovery bound; independent review PASS. No live preflight/UART/build.python3 tools/mainline-drm-system-trial.py begin --wait-initramfs-in-initcall --without-boot-markers --initrd-info-logging --bundle BUNDLE --manifest PRIVATE_MANIFEST --normal-report PRIVATE_NORMAL --state NEW_PRIVATE_STATE --log PRIVATE_LOG --result PRIVATE_RESULT.
No syscall/cause or ordinary-root inference;5b.5 stays open.
Actual passive info/console capture: exact args/source/same artifacts, freshLinux/Run init announcement but no systemd/closure/login within180s; no later candidateinput insource/annotations; independent fullreview PASS. Subsequent NEW armed protected recovery passed; initial zero-byte failed check preserved.openspec validate the-board-runs-a-mainline-kernel --strict.Independent physical and subsequent armed recovery review PASS. Physical revision f03ff3ce, CI37257736256 PASS and exact work revision/published capture HTTP200 verified: publication receipt. Automatic return and ordinary task5b.5 remain UNVERIFIED.
python3 tests/test_mainline_initrd_info_kmsg_logging.py.
Controller source proof:9 new+10info+13debug+36ordinary tests PASS, independently rerun; source0ba47bc0 reviewed PASS. No UART/build.python3 docs/evidence/mainline-initrd-info-kmsg-logging/host/qualification-command.py --bundle BUNDLE --dev DEV --normal-report PRIVATE_NORMAL.
Executed actual preparation exit0 on0ba47bc0; same artifacts/archive, sole destination delta352/370 and NEW armed recovery binding; independent review PASS. No live preflight/UART/build.python3 tools/mainline-drm-system-trial.py begin --wait-initramfs-in-initcall --without-boot-markers --initrd-info-kmsg-logging --bundle BUNDLE --manifest PRIVATE_MANIFEST --normal-report PRIVATE_NORMAL --state NEW_PRIVATE_STATE --log PRIVATE_LOG --result PRIVATE_RESULT.
Preserve fallback/drop/cause limits; ordinary task5b.5 stays open.
Actual passive capture: exact same artifacts/args/source, fresh kernel/pre-exec init only, no systemd/closure/login in180s; independent full review PASS. Subsequent NEW confirmed recovery passed independently; expired passive listener0bytes/no postflight remains separate.openspec validate the-board-runs-a-mainline-kernel --strict.Independent full capture/recovery-limit review PASS. Physical revision236f6bca, CI37259813601/deployment PASS and exact work revision/published capture HTTP200 verified: publication receipt. Subsequent NEW confirmed recovery passed; automatic return and ordinary5b.5 remain UNVERIFIED.
python3 docs/evidence/mainline-system-trial/current-p2-baseline-repeat-host-2026-10-05/qualification-command.py --bundle BUNDLE --dev DEV --normal-report PRIVATE_NORMAL.
Executed same-artifact qualification exit0 on3d2a080c; exact original299/317, unchanged source/helpers/artifacts and NEW kmsg recovery binding; independent review PASS. No live preflight/UART/build.python3 tools/mainline-drm-system-trial.py begin --wait-initramfs-in-initcall --without-boot-markers --bundle BUNDLE --manifest PRIVATE_MANIFEST --normal-report PRIVATE_NORMAL --state NEW_PRIVATE_STATE --log PRIVATE_LOG --result PRIVATE_RESULT.
No new intervention, helper trace or cause/root/glass acceptance;5b.5 open.
Completed unchanged quiet capture: same299/317/source/artifacts, freshLinux/pre-exec init only, no systemd/closure/login within180s. Original closure boundary did not reproduce; independent full review PASS. Subsequent NEW protected recovery passed independent review; no previous reset reused.openspec validate the-board-runs-a-mainline-kernel --strict.Independent source/actual host/full physical/parser/recovery-limit/publication review PASS. Exact94920520 CI37261983348/deployment and published work revision/capture timestamps verified: publication receipt. Subsequent NEW protected recovery passed independent review; ordinary5b.5 stays UNVERIFIED.
python3 tests/test_mainline_init_exec_return.py.
Reviewed source/native/object/evaluation proof:15 focused and68 old regressions PASS; exact realized source/config and actual RISC-V object verified, runtime gate in ordinary .sbss. Peer review PASS; root removed duplicate identical helper definitions through reviewed67d40217 and reran15 focused after integration.107 old package derivations unchanged. Full matching headers/link/build/positive artifact qualification remain5s.2; no UART claim.python3 tools/mainline-init-exec-return-qualify.py --bundle BUNDLE --dev DEV --normal-report PRIVATE_NORMAL.
Actual full build/new-header object/positive qualifier PASS, independently reviewed7a99b32d. Same config/userspace/DT hardware, only identical17-entry module-tree relocation; exact323/341 one-gate policy. Offline build and initial qualifier failures preserved. Root integrated reviewed narrow correctiond361f364 and reran17 focused; no UART/live-preflight claim.flock /tmp/k230-nix-build.lock nix build --no-write-lock-file --out-link PRIVATE_ROOT --max-jobs 1 --cores 16 .#kernelMainlineInitExecReturn.src .#kernelMainlineInitExecReturn .#kernelMainlineInitExecReturn.dev .#kernelMainlineInitExecReturnTrialBootFiles.
Historical pre-UART availability failure preserved. Exact restoration/registered roots/fresh qualifier PASS with identical bytes/manifest151a; independent reviewb903ceb7 PASS. No source/default or board change.python3 tools/mainline-drm-system-trial.py begin --wait-initramfs-in-initcall --without-boot-markers --init-exec-return --bundle BUNDLE --manifest PRIVATE_MANIFEST --normal-report PRIVATE_NORMAL --state NEW_PRIVATE_STATE --log PRIVATE_LOG --result PRIVATE_RESULT.
No loader/main, failed-instruction, output-call-return or ordinary-root/glass
claim from the record;5b.5 stays open.
Reviewed guarded staging and physical capture PASS: exact323/341 arguments, all load/CRC guards, one ret=0 at4.548457 and no qualified login within180s. Full private parser/no-input/identity/hash/time review PASS. Exec setup succeeded; userspace transition and the probe output call return remain UNVERIFIED. Subsequent NEW protected recovery passed the checker and independent complete recovery review. No earlier reset is reused.openspec validate the-board-runs-a-mainline-kernel --strict.
Independent review PASS; physical revision3fbf380d, CI37357725932/deployment PASS and exact work revision, capture timestamps and staging publication HTTP200 verified: publication receipt. Subsequent NEW protected recovery checker and independent complete review PASS. Ordinary task5b.5 stays open.openspec validate the-board-runs-a-mainline-kernel --strict.
See design.md group5t; independent exact-source/context/order/both-gate planning review PASS and strict validation PASS. Implementation/build/physical outcomes remain UNVERIFIED.python3 tests/test_mainline_init_exec_transition.py.
Source/native/RISC-V parent-header proof and controller/qualifier source proof implemented and independently reviewed. Root reran17 transition and10 actual patched-site tests PASS after integration. Complete base-package identity comparison passed with all110 prior attrs unchanged, equal selected kernel/config/params, and matching independently evaluated new outputs. Root reviewed the actual assertion expression, source hashes and object sections/references. Matching full artifacts remain5t.3–4 and physical outcome5t.5.nix build .#kernelMainlineInitExecTransition .#kernelMainlineInitExecTransition.dev --no-link --print-out-paths --max-jobs 1 --cores 4.
Actual host proof: frozen revision a60b0eae full build return0 with retained source/kernel/dev roots; actual new-header three-object W=1 compile zero warnings with config/autoconf unchanged and verified sections/references. No build failure occurred. Independent source and controller actual-host reviews PASS. Physical outcome remains5t.5.nix build .#kernelMainlineInitExecTransitionTrialBootFiles --no-link --print-out-paths --max-jobs 1 --cores 4, then
python3 tools/mainline-init-exec-transition-qualify.py --bundle BUNDLE --dev DEV --normal-report PRIVATE_NORMAL.
Actual qualification returned0 for retained bundle/system: four source pins, linked Image/config/dev, archive/DT/init/loader/helper/checksum/CRC/transport verified; 351-byte args, 369-byte literal command. Independent actual-host review PASS. Normal report is an historical host anchor, not live preflight.python3 tools/mainline-drm-system-trial.py begin --wait-initramfs-in-initcall --without-boot-markers --init-exec-return --init-exec-transition --bundle BUNDLE --manifest PRIVATE_MANIFEST --normal-report PRIVATE_NORMAL --state NEW_PRIVATE_STATE --log PRIVATE_LOG --result PRIVATE_RESULT.
No record grants input or proves its own output return, handler/loader/main,
ordinary root/glass or cause. Task5b.5 remains open.
Physical capture: guarded staging PASS; ONE capture 20:24–20:28 UTC, exit1 readiness unknown; ordered return, kernel-init-return and first-user-ecall records, then only a DCS XTGETTCAP “name” query and silence for 180s. NEW operator reset recovery verified. Independent staging, capture and recovery reviews PASS. Handler/loader/main, emitter of trailing bytes and cause remain UNVERIFIED.openspec validate the-board-runs-a-mainline-kernel --strict plus
committed physical/recovery/publication bindings and limits.
Independent public-packet review PASS. Publication receipt: CI 37385743786 build/deploy success; work page serves a6900de7 and the physical/actual-host pages return200. Ordinary root/panel/glass5b.5 remains open.openspec validate the-board-runs-a-mainline-kernel --strict.
Landed 3e9edb3b (no separate plan review; no source involved).python3 tools/mainline-drm-system-trial.py begin --wait-initramfs-in-initcall --without-boot-markers --init-exec-return --init-exec-transition --bundle BUNDLE --manifest PRIVATE_MANIFEST --normal-report PRIVATE_NORMAL --state NEW_PRIVATE_STATE --log NEW_PRIVATE_LOG --result NEW_PRIVATE_RESULT
with ffmpeg -f v4l2 -input_format mjpeg -video_size 1280x720 -i /dev/video0 -c copy PRIVATE_VIDEO.
Camera evidence does not identify cause; task5b.5 remains open.
Camera repeat: UART identical to 5t; camera inconclusive (candidate never lit the panel); exposed panel-init/unused-clock-cleanup timing pattern. NEW reset PENDING.vo and AHB/CFG/REF on dsi
and enable them from probe with devm_clk_bulk_get_all_enabled(), so late
unused-clock cleanup cannot gate them. Host proof: DTB build plus
nix build .#kernelMainlineDrmTrialBootFiles .#toplevel-mainline-drm-trial.
Done: ad627a2b, plus RTC c73f6ea2, GPIO clock-names f2403a13 and
spi2axi CLK_IS_CRITICAL 0b327025 found by physical bisection; builds PASS; reviews PASS.python3 tools/mainline-drm-system-trial.py begin --wait-initramfs-in-initcall --without-boot-markers --bundle BUNDLE --manifest PRIVATE_MANIFEST --normal-report PRIVATE_NORMAL --state NEW_PRIVATE_STATE --log NEW_PRIVATE_LOG --result NEW_PRIVATE_RESULT.
Pass needs panel prepare completion, systemd progress beyond the DCS query
and the controller’s qualified login/prompt; record camera stills of the panel.
Clock-ownership evidence:
the quiet SBI-only policy needs a separate variant build, so the plain ordinary
policy was used. Final 0b327025 bundle reached candidate-ready-qualified-ordinary-init
with normal unused-clock cleanup; recovery verified. Camera showed only the boot splash.vpu_ddrcp2 CLK_IS_CRITICAL) and fix the
aliased dphy_dft gate; camera-judged bisection over a full live clk_summary.
Proof: console visible on the panel with normal cleanup (evidence).k230-mainline-drm-shell and fix canaan DRM fops FOP_UNSIGNED_OFFSET
so userspace can open /dev/dri/card0. Proof: qualified full-shell boot with
sway active and the Home UI on the panel; recovery verified.The project MAY provide a separately named mainline DRM device tree and boot-files candidate for the RM69A10 panel. This candidate SHALL remain outside the vendor/default outputs and SHALL NOT claim panel operation from source/API compilation or a host DTB check. Its display power-domain behavior remains UNVERIFIED until physical probe/panel evidence exists. The pinned upstream source has no K230 display power-domain provider; an optional local forward-port SHALL remain isolated and SHALL NOT substitute build proof for runtime power evidence.
Grounding: the board panel wiring and init sequence are transcribed from
nix/dts/k230-tdisplay.dts and
nix/dts/display-rm69a10-568x1232.dtsi. The opt-in DTS is
nix/dts/k230-tdisplay-mainline-drm.dts; host compilation and its limits are
recorded in docs/evidence/mainline-display-dtb.md. The vendor-derived
local genpd provider, checked probe-time power acquisition, and host build
proof are recorded in docs/evidence/mainline-display-power-domain.md, with
prior vendor-board grounding in docs/evidence/dsi-phy-hang.md. Later
docs/evidence/mainline-display/physical-2026-10-01/README.md commits DRM/fb0
probe and photographed panel boot text. Those observations do not establish
a usable mainline system, successful DCS readback or deliberate touch; the
remaining gate 5b.5 stays open.
The project MAY describe the board’s Goodix-compatible touch controller in the opt-in mainline DRM device tree. It SHALL preserve the candidate’s reported digitizer dimensions and GPIO/interrupt source from the board DTS, and SHALL record serial probe evidence separately from physical touch acceptance. Coordinate mapping and physical touch behavior remain UNVERIFIED until deliberate on-panel interaction is recorded.
Grounding: the candidate node in
nix/dts/k230-tdisplay-mainline-drm.dts follows the board wiring recorded in
nix/dts/k230-tdisplay.dts; the exact host DTB check and limits are in
docs/evidence/mainline-display-dtb.md. The pinned mainline Goodix Berlin
I2C driver includes goodix,gt9916, and the later committed
docs/evidence/mainline-display/physical-2026-10-01/README.md records Goodix
input registration. Registration is partial probe evidence; it does not prove
coordinate mapping or deliberate finger interaction.
The project SHALL provide a mainline-Linux kernel, device-tree, and
boot-files build (.#kernelMainline, .#deviceTreeMainline,
.#kernelMainlineBootFiles) pinned to the newest mainline revision carrying
basic Canaan K230 support, built entirely separately from the pinned vendor
Xuantie kernel .#kernel uses. No existing package, nixosConfigurations
output, or .#sdImage SHALL depend on or be changed by this build existing.
Grounding: nix/kernel-mainline-src.nix pins torvalds/linux at the
dereferenced v7.3-rc5 commit — the newest tag with
arch/riscv/boot/dts/canaan/k230.dtsi present, confirmed absent at v7.2
by direct tag diff. nix/kernel-mainline.nix and
nix/device-tree-mainline.nix share no code path with nix/kernel.nix or
nix/device-tree.nix; flake.nix’s new kernelMainline/
deviceTreeMainline/kernelMainlineBootFiles outputs are additive only.
nix build .#kernelMainline.#kernel has ever been built.#nixosConfigurations.k230.config.system.build.toplevel
or .#sdImagenix/kernel-mainline.nix, nix/kernel-mainline-src.nix,
nix/device-tree-mainline.nix, and this change’s other new files did not
existThe project SHALL provide a full NixOS system variant
(nixosConfigurations.k230-mainline-console) that substitutes the
mainline kernel for the vendor kernel via the same k230Kernel specialArg
substitution mechanism the existing k230-rvv-trial variant already uses,
built from the shell-off k230-console base rather than the graphical
k230-coherent-shell base, and SHALL exclude any out-of-tree kernel module
that is not expected to compile against the mainline pin. No existing
nixosConfigurations output SHALL be changed by this variant existing.
Grounding: flake.nix’s k230-mainline-console extends k230-console
with specialArgs.k230Kernel = self.k230MainlineKernel and force-clears
boot.extraModulePackages/boot.kernelModules (the out-of-tree RTL8189FTV
module nix/hardware.nix builds against config.boot.kernelPackages.kernel
dynamically, with no reason to expect it compiles against a v7.3-rc5 API
seven major versions newer than its 6.6-era vendor origin, and no SDIO DT
node enabled for it to bind to regardless). Proven:
nix build .#toplevel-mainline-console exits 0, producing
/nix/store/d488a1cibw8r7ip7hbbb9j52hy0kzb0h-nixos-system-nixos-26.11.20260919.20b1ddd.
Deviates from the coordinator’s suggested “-shell-” name for the reason
above; flagged rather than silently decided.
nix build .#toplevel-mainline-consolekernelMainline, independent of whether any other nixosConfigurations
output has ever been builtThe project SHALL record, per hardware function, whether mainline Linux at the pinned revision can drive it, citing direct file-existence or device-tree-content checks rather than changelog summaries. Hardware functions with no mainline driver SHALL be recorded as blocked rather than silently omitted, and any of this project’s own vendor-kernel patches that cannot be forward-ported to mainline SHALL be recorded individually with the reason, not summarized as a single negative finding.
Grounding: docs/research/mainline-kernel-inventory.md’s Inventory table
(each row cites gh api repos/torvalds/linux/contents/<path> returning 200
or 404) and its per-patch disposition list (all eleven vendor-kernel patches
checked individually; ten target files absent upstream, one already fixed
upstream independently, none require porting as a patch today).
docs/research/mainline-kernel-inventory.md’s
panel rowkernelMainlineDrm
continuation without claiming that continuation is completenix/kernel.nix applies
to the mainline buildWhere this project forward-ports a vendor-tree driver onto the mainline pin so a boot-critical function (GPIO, SD/MMC, USB) is available, the ported file or hunk SHALL be traceable to its exact vendor-tree origin by path, and any API difference between the vendor tree’s kernel version and the pinned mainline revision that required a code change (not just a Kconfig/Makefile wiring change) SHALL be recorded with what changed and how it was confirmed, rather than silently patched around.
Grounding: nix/patches/mainline/gpio-k230.c and
nix/patches/mainline/sdhci-of-kendryte.c are forward-ported from
ruyisdk/linux-xuantie-kernel @ 7d4e1f444f461dbe3833bd99a4640e7b6c2cd529;
nix/kernel-mainline.nix’s postPatch carries the drivers/usb/dwc2/ {params.c,core.h,core.c} hunks from the same tree. Two real API
migrations were found and fixed this way, each only after a failed build
named the exact missing symbol: struct gpio_chip’s .read_reg/
.write_reg/.bgpio_lock and bgpio_init() were replaced upstream by
struct gpio_generic_chip/gpio_generic_chip_init()
(include/linux/gpio/generic.h), confirmed against mainline’s own
already-migrated gpio-dwapb.c; sdhci_pltfm_free() was removed upstream
entirely, confirmed against mainline’s own sdhci-of-dwcmshc.c, whose
probe error paths and .remove call no equivalent function.
nix build .#kernelMainline fails with an unknown-symbol or
missing-member compiler error in a forward-ported fileReaching a mainline-booted serial console, rootfs, or any further hardware milestone on the physical board SHALL be treated as hardware evidence, never inferred from a successful cross-build. A change that only cross-builds the mainline kernel/device-tree SHALL say so explicitly and SHALL NOT claim any hardware milestone until a board console transcript exists.
Grounding: this change’s own tasks.md “Remaining evidence gate” section
names the exact operator command
(flock /tmp/k230-board.lock python3 tools/console.py /dev/ttyACM0 --wait=10) and the manual U-Boot ext4load steps it depends on, without
performing them.
.#kernelMainline has booted on the T-Display-K230docs/evidence/, or states plainly that none exists yetThe project MAY provide an opt-in mainline DRM candidate, but it SHALL
remain a separate derivation from the console-only kernelMainline and
SHALL NOT change the vendor kernel, default device tree, system
configuration, or image outputs. Source/API checks, complete kernel builds,
DTB checks, and physical display/touch observations SHALL be recorded as
distinct evidence; one class SHALL NOT be described as proof of another.
Grounding: nix/kernel-mainline-drm.nix builds the copied Canaan DRM/DSI,
RM69A10 panel, and LT9611 code as a separate override of
kernelMainline. nix/device-tree-mainline-drm.nix and the separate
kernelMainlineDrmBootFiles output pair the candidate DTB/Image without
changing default outputs. docs/evidence/mainline-display-api-compile.md,
docs/evidence/mainline-display-dtb.md, and
docs/evidence/mainline-display-nix-build.md record the prepared-header
external-module, host DTS, and complete Nix kernel/DTB/boot-files checks,
with their limits and the absent hardware results.
docs/evidence/mainline-display-boot-preparation.md records the matching
opt-in trial system/initrd/bootargs and closure inventory, and the recoverable root staging/U-Boot
procedure. Later committed October 1/2 physical trials at
docs/evidence/mainline-display/physical-2026-10-01/README.md establish
partial boot/probe/photographed boot text and distinct normal recovery, but
no usable mainline root or deliberate touch. The DRM driver sources in the pinned
upstream source output are absent; this candidate forward-ports them from
the vendor-derived implementation. The initial candidate omitted display power-domain wiring because the
pinned source has no provider; the DRM-only local provider continuation
remains gated by separate source/build and physical runtime evidence
(docs/evidence/mainline-display-power-domain.md).
nix build .#kernelMainlineThe optional DRM mainline kernel SHALL provide a documented restart mechanism traceable to the pinned vendor source, isolated from vendor/default and console-only mainline outputs. Source/API object proof, complete candidate kernel build, matching trial-bundle proof and physical restart/recovery SHALL be recorded separately. Physical automatic restart remains UNVERIFIED until a committed console transcript shows a kernel restart request reaching stage 1 and the protected normal system returning with a fresh boot identity.
Grounding: the read vendor drivers/reset/reset-k230.c at
7d4e1f444f461dbe3833bd99a4640e7b6c2cd529 registers a priority-128
restart handler and writes bits 0/16 at 0x91102060. The source audit at
docs/evidence/mainline-display/physical-2026-10-01/mainline-restart-source-audit-2026-10-02.md
records the mainline peripheral-only reset driver, absent advertised SBI
SRST, the systemd refusal and distinct operator recovery. Group 5d owns the
kernel/Nix continuation and its separate evidence gates.
docs/evidence/mainline-restart/README.md records the initial GCC failure,
corrected source/object/full-kernel/matching-bundle proof and unchanged
base-relative default outputs; its host checks do not provide physical restart proof.
Physical grounding: docs/evidence/mainline-restart/physical-clock-comparison-2026-10-02/README.md
records a real candidate kernel restart → SPL → protected normal return,
fresh boot ID, matching identities, active shell services and eight unchanged
hashes with temporary clk_ignore_unused. This proves that diagnostic
selection only; the baseline still stalls and restart without the flag
requires a separate clock-consumer fix and physical proof.
Further physical grounding: docs/evidence/mainline-sd1-clocks/physical-no-flag-2026-10-03/README.md
records the targeted five-clock candidate with ordinary clock cleanup, no
clk_ignore_unused, real kernel restart → SPL → protected normal boot,
fresh boot identity, three active shell services and eight unchanged hashes.
The full initrd-shell result and artifact identities are committed; ordinary
root activation and deliberate touch remain separately unverified.
The project MAY provide a separately named runtime-opt-in kernel diagnostic for the observed userspace-prompt/no-receipt boundary. It SHALL record bounded cached UART/IRQ/time progress independently of foreground shell input, with explicit unavailable/busy/unknown states and no UART register/settings changes. Observer source/API/object, matching artifact and physical results SHALL be separate. Existing default and diagnostic outputs SHALL remain unchanged; finite reporter output SHALL NOT establish ordinary root, Bash receipt, physical timer health, automatic recovery or a production fix.
Grounding: docs/evidence/mainline-system-trial/shell-pid1-physical-2026-10-03/README.md
observes fresh Linux/init entry/Bash prompt and missing bounded receipt.
Its uart-source-equality.json records narrow host source/DT comparison only.
Read pinned 8250 RX accounting, RISC-V timer IRQ mapping, IRQ descriptor
accounting and n_tty lock/flush paths as cited in group 5f’s design.
The project MAY provide a separately selected finite reporter variant for the observed zero-report boundary. It SHALL preserve every existing package/source/ trial identity and attempt only fixed worker-entry and first-post-sleep public SBI records in its normal-priority worker, with ordinary aligned page-contained storage and no IRQ/TTY/PID1 instrumentation. Both exact runtime opt-ins and actual DBCN availability SHALL gate breadcrumbs; absent/invalid breadcrumb selection SHALL retain the original six-sample behavior. The six numeric sample formats, sleeps, getter semantics and stop checks SHALL remain unchanged.
The explicit controller selection SHALL keep exact candidate/argument and protected normal qualification, accept only bounded complete fresh fixed records, and distinguish breadcrumb presence, numeric samples and receipt. Missing/malformed output SHALL remain unknown and SHALL NOT cause another stimulus or candidate reboot. Neither breadcrumb presence nor absence SHALL be described as a causal diagnosis, ordinary-root acceptance or recovery.
Grounding: docs/evidence/mainline-uart-progress/physical-2026-10-03/README.md
and result.json record one stimulus, no receipt, zero reports and DBCN
detection. The realized source 4av3w0… reporter’s worker at27–69 first sleeps,
then snapshots/formats/writes, as detailed in group5g’s design. Existing
docs/evidence/mainline-uart-progress/exact-full-host-2026-10-03.md is host proof
of the original reporter, not this new physical comparison.
The project MAY provide a separately selected reporter variant for the observed n1/no-n2 boundary. It SHALL preserve all existing package/source/config/trial identities, samples, sleeps, cached getters, stop checks and normal priority. It SHALL attempt only two additional fixed public SBI records: after the n1 numeric call returns, and after the third sleep/stop check before snapshot. Ordinary aligned page-contained storage, the new exact opt-in plus both existing opt-ins, CONFIG_RISCV_SBI and DBCN availability SHALL gate the records. At most ten one-call attempts SHALL occur; absent/invalid new selection SHALL retain current behavior without a retry, fallback or IRQ/TTY/PID1 instrumentation.
The separately typed controller SHALL preserve exact candidate/argument and protected normal qualification, one fresh stimulus and private bounded capture. It SHALL accept only exact bounded complete fresh records and keep new-point, old-breadcrumb, numeric-sample, receipt and recovery facts distinct. Missing or malformed output SHALL remain unknown without another stimulus or candidate reboot, and SHALL NOT establish a causal fix, root/touch or automatic return.
Grounding: committed physical packet and result at revision 278769d0 record both Breadcrumbs points, a matched receipt and n0/n1 but no n2–n5 in 180 seconds. The subsequent operator reset passed guarded fresh protected normal postflight and Home observation; automatic return remains unverified. The read immutable k5a5zrhq… worker at 67–74 sleeps/checks before snapshot and at 98 calls SBI, as detailed in group 5h’s design. This is a source-supported next boundary, not committed proof of the new diagnostic or a fault.
Subsequent actual PostSample packet records matched args/Bash/worker-entry only, one stimulus and no receipt/samples/ new points in180.0975s. It does not prove reaching either new point or entry-call return; subsequent NEW operator reset passed guarded fresh normal postflight and Home observation. Host and incomplete capture completion do not satisfy the scenarios above or ordinary-root task5b.5.
The project MAY provide a separately selected explicit memory-progress reporter. It SHALL retain existing outputs/identities and, only under its exact opt-in, preserve six sleeps/cached snapshots/stop checks while suppressing every worker output call and publishing finite consistent ordinary-memory progress. A separate normal-priority observer SHALL use one finite kernel wait and at most one aligned bounded-size DBCN summary attempt. It SHALL NOT add MMIO, IRQ/TTY/PID1 output, retry/fallback, firmware/console-policy or scheduler changes. Gate absence or invalid values SHALL retain inherited behavior without observer creation.
The typed minimal controller SHALL qualify exact host artifacts/source/config, fresh received arguments/Bash readiness and protected normal state. It SHALL send at most one receipt then bounded passive capture, with no further input or candidate reboot. Summary, receipt and recovery SHALL remain independent facts; missing output SHALL NOT identify a cause or prove ordinary root/glass.
Grounding: PostSample capture and read-source audit record variable reporter progress and firmware output dependencies, not causation.
The controller MAY provide an explicit Memory-only no-stimulus comparison. It SHALL require minimal/same-image/progress/Memory selectors, preserve exact candidate/source/config/archive/load guards and identical volatile bootargs, and reject conflicts before UART access. After candidate boot it SHALL send zero candidate bytes on success/error/timeout/finally paths and retain bounded passive capture and strict fresh summary parsing. It SHALL record receipt NOT_REQUESTED, stimulus_attempts=0 and RX NOT_TESTED rather than infer receive or ordinary-root acceptance. Default one-stimulus behavior SHALL remain unchanged.
Only the existing ordered fresh normal-recovery qualification SHALL permit protected normal postflight writes; recovery remains independent of summary completeness. Missing output SHALL stay unknown and SHALL NOT establish input causation, an IRQ/timer/firmware fault or ordinary mainline acceptance.
Grounding: Memory physical packet records one input attempt with no summary/receipt; withholding that dependency is a distinct controller intervention using existing immutable artifacts.
The controller MAY offer a typed Memory polling-idle comparison. It SHALL
require minimal/same-image/progress/Memory/no-stimulus selectors and reject
conflicts before UART access. It SHALL qualify the same realized source/config/
Image/archive/manifest and append exactly one bare volatile nohlt after
checking the selected built-in polling setup. It SHALL reject hlt, duplicates,
value variants and arbitrary bootarg changes; defaults SHALL remain unchanged.
After boot it SHALL send zero candidate bytes and retain bounded passive capture, strict fresh args/summary parsing, receipt NOT_REQUESTED, zero stimulus attempts and RX NOT_TESTED. Protected normal recovery SHALL remain independently gated. A difference SHALL be described only as idle/tick-policy dependence, without inferring WFI/IRQ/timer/firmware cause, ordinary-root acceptance or a production power policy. Missing output SHALL remain unknown.
Grounding: zero-input physical result and read source/config/linked setup. The already-built setup is host evidence; runtime polling and usable boot are unverified.
The diagnostic MAY offer a separately built MemoryPrintk variant with an exact gate requiring existing Memory/progress gates. It SHALL retain six worker sleeps/ cached snapshots/atomic publication and one observer completion wait/acquire, suppress worker output, and replace its one final explicit DBCN attempt with one ordinary KERN_INFO fixed K230_UMK1 summary. The same call SHALL begin with a newline to separate an existing shell prompt from the timestamped summary line; the parser SHALL not strip prompts to recover malformed records. It SHALL not force console ownership, use emergency/raw-MMIO/fallback/retry output or change IRQ/firmware/priority policy. Every prior source/config/package/trial identity SHALL remain unchanged.
The typed controller SHALL require minimal/same-image/progress/Memory/no-stimulus and reject combined idle/point/trace selectors before UART. It SHALL qualify the new actual source/config/Image/format/setup and exact DT/archive/load guards, receive exact arguments and fresh Linux8250 ttyS0 registration/console markers. It SHALL parse only the observed timestamp-prefixed fixed new namespace and bounded coherent fields, rejecting old/wrong-channel/stale/malformed/duplicate/ truncated records. It SHALL keep zero input, NOT_REQUESTED/RX NOT_TESTED, bounded capture and independent protected normal recovery.
A record SHALL establish only observer progress through the changed output channel, not output-call return, DBCN causation, ordinary-root or glass acceptance. Missing output SHALL remain unknown. Native, target object, full artifact, controller qualification, physical observation and recovery SHALL stay separate.
Grounding: polling result and recovery and actual timer/backend/source audit. The registered backend is observed; future UMK output and useful mainline boot are unverified.
The controller MAY offer a typed MemoryPrintk nohz-off comparison. It SHALL
require minimal/same-image/progress/Memory/no-stimulus/MemoryPrintk selectors
and reject type/mode/competing selector conflicts before UART access. It SHALL
qualify the same actual source/config/Image/archive/manifest/DT/load identities,
NO_HZ_COMMON/NO_HZ_FULL/HIGH_RES_TIMERS/HZ=250/RISCV_TIMER/RISCV_SBI support
and unique linked nohz setup. It SHALL append exactly one trailing nohz=off
to the qualified baseline, reject original/alternate/bare/empty/duplicate nohz
forms and arbitrary additions, and preserve all existing default transports.
The diagnostic SHALL keep its source/worker/observer/output gate and fresh exact arguments/backend/strict UMK parsing. It SHALL send zero candidate bytes through bounded capture/error/finally, record NOT_REQUESTED and RX NOT_TESTED and keep protected normal recovery independently gated. A valid record SHALL support progress under changed tickless policy only, without inferring hardware periodic interrupts, a timer/IRQ/firmware cause, printk return or ordinary boot acceptance. Missing output SHALL remain unknown. Runtime policy observation SHALL remain distinct from compiled parser support and received-token evidence.
Grounding: MemoryPrintk capture and selected config/Image/source audit. The compiled option is grounded; new output and usable mainline boot are unverified.
The controller MAY offer a separately typed autonomous Bash-PID1 comparison using the same actual Image/initrd/DT. It SHALL require minimal/same-image-shell selectors and reject all diagnostic progress/timer/trace/shutdown conflicts before UART. It SHALL reconstruct only the reviewed fixed script and fresh 32-hex nonce, remove reporter gates, preserve qualified original init/rdinit and boot controls and enforce the unchanged literal transport bound. It SHALL not expose arbitrary scripts or weaken existing transport/default policies.
Before physical use it SHALL establish native exact Hush lexer/variable/quote/ command execution and selected Linux argv handling, actual artifact/archive sh/sleep/Bash builtin proof and exact printed bootargs. Source models alone SHALL NOT satisfy native execution. Fresh candidate phase/args/backend/bin-sh entry SHALL qualify only complete exact-nonce begin/end records; echoed scripts and commandline text SHALL NOT count. Malformed/stale/duplicate/reversed/ truncated records SHALL retain unknown facts without repair.
The script SHALL check PID1/UID0, attempt begin, one five-second sleep and end after success, then attempt an interactive exec independently of that chain. It SHALL deliberately issue no exit/reboot. The controller SHALL keep a bounded 60-second zero-input capture on all paths, RX NOT_TESTED and independent protected normal recovery. Record presence SHALL NOT authorize candidate input, prove that record’s own output-call return, a full runtime identity guard, a timer/IRQ cause or ordinary boot/touch acceptance. Missing output SHALL remain unknown.
Grounding: nohz-off capture and read kernel/Hush/archive scout. Native parser execution and autonomous board records remain unverified.
The system trial controller SHALL offer typed begin-only --initrd-debug-logging
requiring synchronous-initramfs and marker-free ordinary init. It SHALL append
only rd.systemd.log_level=debug rd.systemd.log_target=console, reject inherited
conflicting logging keys including underscore/hyphen aliases and invalid
types/combinations before UART, retain unchanged defaults and transport bound,
and preserve the selected policy through guarded continuation.
It SHALL retain exact artifact/load/CRC/printed/live-argument and normal identity guards, a 180-second passive readiness bound and complete private logging past rolling-buffer capacity. Unknown readiness or I/O SHALL send no candidate input. Manager job/ExecStart state SHALL NOT be reported as nested command or syscall tracing, ordinary-root acceptance or protected recovery.
Grounding: current ordinary physical boundary and selected archive/pinned systemd source. Controller and actual host qualification and bounded physical result plus NEW recovery are recorded. No systemd startup/login was observed; ordinary boot acceptance remains unverified.
The system trial controller SHALL offer typed begin-only --initrd-info-logging,
requiring synchronous initramfs and marker-free ordinary init, excluding debug
logging, and selecting only rd.systemd.log_level=info rd.systemd.log_target=console.
It SHALL preserve old/default/debug behavior, typed resumed selection, pre-UART
alias/conflict/type rejection, the transport bound and all immutable artifact,
normal identity, load/CRC and exact printed/live argument guards.
The comparison SHALL keep a 180-second passive readiness bound, complete private logging and unknown-no-input behavior. Changed observed progress SHALL NOT be reported as a blocked output-call diagnosis, ordinary boot acceptance or recovery.
Grounding: debug/console physical result and bounded child/source analysis. Actual host qualification and physical capture passed their bounded review; no systemd startup/login was observed.
The userspace trial controller SHALL offer typed begin-only
--initrd-info-kmsg-logging, requiring synchronous initramfs and marker-free
ordinary init, excluding debug and info-console. It SHALL select exactly
rd.systemd.log_level=info rd.systemd.log_target=kmsg, preserve existing
profiles/defaults and typed saved continuation with old missing=false, and
reject aliases/conflicts/types before UART.
It SHALL preserve the immutable artifacts, normal identity, five load/CRC, printed/live argument and transport guards,180-second passive readiness, complete private logging and unknown-no-input behavior. It SHALL NOT report kmsg selection as proof that console was unused, every record was delivered, a blocked call was identified, ordinary root worked or recovery succeeded.
Grounding: physical info/console result and selected-source backend audit. Controller and executed actual host qualification passed independent review; no physical delivery is claimed.
The operator SHALL be able to repeat one unchanged quiet p2 ordinary policy with existing synchronous-initramfs and marker-free selectors, without any logging selector or new artifacts. Actual qualification SHALL establish exact 299-byte arguments/317-byte literal command and unchanged immutable/root/init/ mask/console/helper/load/CRC guards after NEW protected recovery.
The repeat SHALL retain the180-second passive readiness bound, complete private logging and unknown-no-input policy. Its outcome SHALL be reported as a reproducibility control, not a logging cause, ordinary-root acceptance, glass proof or automatic recovery. Subsequent recovery SHALL be independently verified or explicitly pending a NEW operator reset.
Grounding: previous quiet ordinary boundary, silent kmsg capture and read archive/source control plan. Actual unchanged-baseline preparation and NEW protected recovery passed independent review. Completed physical repeat passed independent review; subsequent NEW protected recovery passed independent review.
An additive default-disabled diagnostic SHALL emit at most one fixed versioned INFO record containing only the signed return value after the selected ramdisk init exec attempt, before the original success/error branch. It SHALL preserve original init bytes/ABI/argv/env, return/fallback behavior, old Nix outputs and protected root/console/mask/load/CRC/identity guards. Its typed begin-only selection SHALL reject aliases/conflicts/types before UART and require exact new source/build/archive/arguments/manifests with independent review.
The physical trial SHALL retain the180-second passive readiness bound, full private coverage and unknown-no-input policy. Zero SHALL indicate successful exec setup only, not user-mode transition, loader, constructors or systemd main. Missing/partial records SHALL remain unknown. Record presence SHALL NOT imply its own output call returned, a failing instruction was found, ordinary root worked or recovery succeeded. Recovery SHALL be independently verified or explicitly pending NEW reset.
Grounding: independently reviewed quiet repeat and selected source/alternative/proof plan. Source/native/object/evaluation proof passed independent review. Actual full build/new-header object/artifact qualification passed independent review. Restoration with retained roots and fresh qualification passed independent review after the later availability failure. Reviewed physical capture and exact publication establish exec setup success only. Subsequent NEW protected recovery passed independent review. Userspace execution, output-call return and ordinary acceptance remain UNVERIFIED; this is not a shipped capability.
An additive default-disabled child of the selected init exec-return diagnostic SHALL preserve the parent record and offer at most two additional fixed versioned INFO records, scoped to armed PID1: after kernel_init returns before user-exit preparation, and after successful syscall entry from user mode before dispatch. The arm SHALL be set only for selected ramdisk exec success with both exact parent and transition runtime gates enabled. Ordinary-lifetime exact1 gate and consumed-before-output one-shots SHALL prevent fallback/task/ retry output. The diagnostic SHALL NOT modify init/argv/env, return values, assembly/sret, IRQ/timer/vector/exit-work state or existing Nix output identities.
A typed begin-only selection SHALL require exact parent/new gates, synchronous initramfs and marker-free ordinary init, reject conflicting/invalid selection before UART, and require independently reviewed source/context/object plus actual build/config/DT/archive/arguments/manifest qualification. Records SHALL be fresh and strictly ordered among present records; duplicates, malformed or reversed observations SHALL fail closed. Missing earlier frames SHALL remain incomplete/unknown without negating an independently valid later user ECALL witness or fabricating missing observations. The physical capture SHALL preserve complete private logging, protected staging/normal/load/CRC guards,180-second passive readiness and unknown no-input behavior. Recovery SHALL be independently verified or explicitly pending NEW reset. Ordinary root/panel/glass acceptance SHALL remain separate.
Grounding: physical exec setup success without readiness and read exact Linux source sites/context restrictions in design.md group5t. Implemented source/native/parent-header object proof and controller/qualifier fixtures passed independent review. All110 prior package derivation identities are unchanged with equal config/parameters: complete evaluation. Physical witness behavior remains UNVERIFIED.
Archived change · Archived
Snapshot 5836ef1d113d · 2026-10-17 08:22 UTC
Closed recordConfirm the URL serves the site. Verify by fetching https://knewter.github.io/tdisplay-k230/ and finding the unverified count in it
This repository’s specs answer a question nobody can currently ask it: what does this board actually do, as opposed to what is hoped for it?
That distinction is the whole discipline here. The house rule is that an
observation on the board outranks vendor source and that a datasheet grounds
nothing, so every requirement is either backed by a committed boot log, a
photograph and a cited vendor file — or it carries an <!-- UNVERIFIED -->
marker. Those markers are the honest inventory of what this project has not
pinned down.
Today that inventory is only visible by grepping a tree of Markdown. It should be the first thing a reader sees, including the reader who wrote it and has forgotten — and it should be at a URL, because an inventory that requires a checkout and a command is one nobody consults.
openspec/specs/, one page per capability, built
by a command that runs on a laptop as readily as in CI.docs/evidence/…, the site links to it, so the boot log or photograph behind
a requirement is one click away. Evidence that cannot be linked is treated as
a defect in the requirement.https://knewter.github.io/tdisplay-k230/, so the count a reader sees is the
count the specs currently say.Non-goals. Rendering openspec/changes/ — in-flight proposals are for
people working on them, and publishing drafts invites reading them as
decisions. Search, theming, or navigation beyond what a handful of capabilities
needs. Reproducing the Dozer renderer in ../truck, which at 742 lines carries
a journey atlas, a design gallery and a product story this project has no use
for. Start small and grow toward it only where there is a reason.
docs/spec-site: how these specifications reach a reader, and what the
rendering is obliged to show.None.
Adds site/ (an Astro project), a data pass and a build command under
scripts/, their tests under tests/, and a GitHub Actions workflow under
.github/workflows/. Generated output — site/dist/, site/node_modules/,
site/src/data/specs.json — is gitignored.
Creates a coupling worth naming: the data pass parses the <!-- UNVERIFIED -->
convention and the *Grounding: …* citation form out of spec prose. Both are
established by .skills/k230-spec-change/SKILL.md, and a change to either
breaks the site quietly — so the build is obliged to fail loudly rather than
render a requirement whose status it could not determine.
Adds one thing the repository did not have: a dependency on Node and npm, for the site only. Nothing in the image, the system or the board build touches it.
See proposal.md — Why. What shapes the approach:
../truck solves this already with scripts/render-specs.py and a
task spec-site target rendering into public/. It is 742 lines and imports
a journey atlas, a design review gallery, a product story workbench and
marketing research — all Dozer concerns. It also carries measured budgets
(MAX_CLEAN_GENERATION_SECONDS = 8.0, a size ceiling raised deliberately
once) that are worth copying as a habit..skills/k230-spec-change/SKILL.md, not structured data. Anything reading
them is coupled to them.Goals:
main updates what the reader sees.Non-Goals:
Which layer does what: Python reads the specs, Astro draws them.
scripts/render_specs.py parses openspec/specs/, classifies every
requirement, checks cited evidence, and writes site/src/data/specs.json.
Astro reads that JSON and owns presentation and deployment and nothing else.
The alternative — Astro content collections reading the Markdown directly —
was rejected. It would have put the classification, the <!-- UNVERIFIED -->
parsing and the evidence checking into TypeScript, in a second language, with
a second set of tests, for no gain: Astro’s Markdown pipeline does not
understand these conventions and would have needed the same hand-written
parsing either way. The classifier is the one part of this that must not be
wrong, so it stays in one place with unit tests around it.
A hand-rolled HTML writer was built first and then replaced. It worked,
and the design of the pages survived into Astro almost unchanged — the
stylesheet moved across verbatim. What it could not do was deploy itself. The
markup, the layout and the budget habit were the valuable part; the write this string to that file half was thrown away. Its parsing half is what
render_specs.py still is.
Parse the conventions, and fail when they do not parse. The alternative, treating an unrecognised requirement as grounded, was rejected: the unverified count is the site’s entire product, and a count that silently under-reports is worse than no site. Failing loudly also makes the coupling to the skill document visible the moment someone changes the convention.
Failing does not mean withholding the site. An unclassifiable requirement
makes scripts/build_site.py exit non-zero and name the file and the
requirement; it also renders that requirement on the site in a third colour,
as a defect. A build failure that produces nothing hides the defect from the
only person positioned to fix it. CI reads the exit code; a person reads the
page. This is a change to the requirement as originally written, and the
requirement was amended to say so rather than left disagreeing with the code.
Quoting a convention is not using it. docs/spec-site is the one
capability whose prose must discuss <!-- UNVERIFIED -->, and the first real
build read the quoted marker as a real one and reported two grounded
requirements as unverified. Code spans are masked, with offsets preserved,
before either the marker or the grounding line is looked for. The count being
wrong in that direction is exactly the failure this change exists to prevent.
Render specs/ only. Publishing changes/ would put proposals in front
of readers as though they were decided. Truck makes the same split. This is
enforced by the loader, which walks only openspec/specs/, and asserted
against the built output.
Budgets from the first commit, set above current output. Truck’s history shows the alternative: a budget set at what the tree happened to produce goes red on ordinary growth and gets raised reflexively until it means nothing. The budgets are on the whole build — the data pass plus Astro — because that is what a person waits for and what CI pays for.
One deployment, one base path. GitHub Pages serves this repository under
/tdisplay-k230/. npm run build sets ASTRO_BASE to that path; npm run dev and npm run build:local leave it unset so a local preview is
served from the root with nothing to reason about. A GitLab Pages job was
asked for and then withdrawn; with one forge there is no per-forge
indirection to carry, and every link in the site resolves through Astro’s
BASE_URL rather than a hardcoded prefix.
The data pass does not know where the site is served from, and should not:
it emits @@BASE@@ in the HTML it hands Astro, and Astro substitutes
import.meta.env.BASE_URL before rendering.
UNVERIFIED markers are added faster than they are resolved, and the
landing page becomes noise. → Accepted. A large honest number is the
correct output for a project at this stage, and hiding it would defeat the
purpose.site/ is the only thing that needs it, and nothing
in the image, the system or the board build touches it. The data pass runs
on the standard library alone, so the specs can still be checked without npm.configure-pages with enablement: true), which fails if the repository’s
Actions token is read-only. Recorded in tasks.md as the one manual step.None outstanding. Whether to render evidence files into the site or link to them in the repository is settled: they are rendered, because a link into a checkout is not a link for a reader on the web.
This change needs no hardware. Every command below runs on the build host.
The pieces: scripts/render_specs.py reads the specs and writes
site/src/data/specs.json; site/ is the Astro project that renders it;
scripts/build_site.py is the one command that runs both and enforces the
budgets; .github/workflows/spec-site.yml publishes to GitHub Pages. Tests
are tests/test_render_specs.py (the data pass, stdlib only) and
tests/test_site_output.py (assertions against the built site).
1.1 Parse openspec/specs/ into capabilities and requirements, classifying each as grounded or unverified, and failing on any requirement that cannot be classified. Verify with a unit test covering a grounded requirement, an UNVERIFIED one, and one that is neither — asserting the third raises
python3 -m unittest discover -s tests -p 'test_render_specs.py' — 18 tests.
classify() returns grounded only on a *Grounding: ...* citation, returns
unverified on an <!-- UNVERIFIED --> marker keeping its reason, and raises
UnclassifiedRequirement naming the file and the requirement when neither
is present. A sixth test covers the bug the first real build found: a marker
quoted in a code span is not a marker.
1.2 Extract docs/evidence/ citations from requirement prose and check each path exists, failing with the requirement name and the missing path. Verify with a unit test for a present path and an absent one
Same suite, TestEvidenceCitations — covering a present path, an absent one
(the failure names both the requirement and the path), prose that is not a
citation (/dev/ttyACM0, openspec/specs/), and a path named only inside
an UNVERIFIED marker, which is an intention rather than a citation.
2.1 Render one page per capability, showing each requirement’s status and its reason where unverified. Verify by running the renderer over the current tree and confirming a page exists for every openspec/specs/**/spec.md
tests/test_site_output.py::test_a_page_for_every_capability_spec walks the
real openspec/specs/ and asserts site/dist/c/<group>-<name>/index.html
exists for each. scripts/build_site.py runs it after every build.
2.2 Render a landing page stating the unverified count before any capability prose. Verify by asserting in a test that the count appears before the first capability heading in the generated HTML
test_the_count_comes_before_any_capability_prose asserts the count’s
offset in the built HTML precedes every section heading and every capability
name. test_the_count_matches_the_specs then re-derives the number from the
spec tree and asserts the page prints that one — the headline figure is
checked, not trusted.
2.3 Turn evidence citations into working links. Verify by generating the site and confirming every docs/evidence/ link resolves to a committed file
test_every_internal_link_resolves walks every built page and resolves
every href and src against site/dist, base prefix included.
test_every_cited_evidence_file_has_a_page asserts a cited path has one.
2.4 Confirm nothing from openspec/changes/ appears in the output. Verify with a test that greps the generated tree for the id of an in-flight change and expects no match
test_nothing_from_an_in_flight_proposal_is_published enumerates the open
change ids from the filesystem and asserts none appears in any built index
or capability page. The loader only ever walks openspec/specs/.
3.1 Measure generation time and output size on the current tree, and set budgets above both with the measured values recorded. Verify by committing the measurements alongside the budgets and noting the date and machine
docs/evidence/spec-site-build.txt: 2026-09-20, solomon, Linux
7.1.9-1-MANJARO x86_64, Ryzen 9 5950X, Python 3.14.7, Node 26.7.0, Astro
5.18.2. Measured 6.7 s and 43 KiB for the whole build — data pass
plus Astro. Budgets in scripts/build_site.py are 120 s and 8 MiB, which is
~18x and ~193x. High on purpose: a cold CI runner is slower than a warm
5950X, and the taxonomy allows fifteen capabilities where this tree has a
handful.
3.2 Fail the build when either budget is exceeded, reporting measured against budget. Verify with a test that forces a breach and asserts the failure names both numbers
TestBudgets asserts the message carries the measured value and the budget
for time and for size. ./scripts/build_site.py --max-bytes 1 exits 2 and
prints output is 43371 bytes against a budget of 1 bytes.
4.1 Expose the build as one command that a person and CI both run. Verify by running it from a clean checkout
./scripts/build_site.py — data pass, Astro, budgets, assertions, in that
order, with a non-zero exit on any failure. It is the only build step in the
workflow. npm install --prefix site is needed once; the data pass itself
imports nothing outside the Python standard library, so the specs can be
checked with no npm at all.
(This task originally read “add markdown to the development shell”. The
dependency was never added: spec prose needs paragraphs, bullets, code,
*em* and **strong**, which is about forty lines of re. And flake.nix
is owned by another change in flight, so the site’s Node dependency lives in
site/package.json rather than in the development shell.)
4.2 Gitignore the generated output and document the command in README.md. Verify with git status clean after a build, and by following the README’s instruction from scratch
/site/node_modules/, /site/dist/, /site/.astro/,
/site/src/data/specs.json and /site/public/evidence/ are ignored;
git status is clean of build output after a run. README gained a Reading
the specs section under Planning with the URL, the local commands, what
grounded and unverified mean, and how the build fails.
4.3 Resolve the UNVERIFIED markers in docs/spec-site against the working site. Verify with openspec validate --all
Five of the six requirements are grounded in the build, its tests and
docs/evidence/spec-site-build.txt. The sixth — the published site being
current — stays UNVERIFIED, because the deployment has not succeeded yet
(see 5.2). Marking it grounded on the strength of a workflow file that has
never deployed is exactly the move this capability exists to prevent.
5.1 Build and deploy from GitHub Actions to GitHub Pages on every push to the default branch. Verify by pushing and confirming the workflow builds the site
.github/workflows/spec-site.yml. Run
35537228320
installed the dependencies, ran the data-pass tests, built the site with its
budgets and assertions, and uploaded the Pages artifact — every step of the
build job green on ubuntu-latest.
5.2 Confirm the URL serves the site. Verify by fetching https://knewter.github.io/tdisplay-k230/ and finding the unverified count in it
Blocked on one manual step, which cannot be done from CI. The build
job passes and uploads the artifact; the deploy job fails at
actions/deploy-pages. GitHub Pages has never been enabled on the
repository, and an earlier attempt to enable it from the workflow
(actions/configure-pages with enablement: true) was refused — the
Actions token is not permitted to create a Pages site. That step was then
removed, so a repository setting no longer fails the build itself.
What has to be clicked, once:
main also works.Once a deployment completes, this box and the UNVERIFIED marker on The
published site is current without anyone maintaining it are resolved
together, grounded by the deployment and the fetched page.
Defines how this project’s specifications are published for reading, and what the rendered site is obliged to tell a reader about how much of it is proven.
The site SHALL be generated from openspec/specs/, and SHALL NOT be
hand-maintained. It SHALL NOT publish in-flight proposals: a proposal is a
draft, and a published draft is read as a decision.
Building SHALL be a single command, and it SHALL be the same command locally and in CI, so that what a person sees before pushing is what gets published.
Grounding: scripts/render_specs.py walks openspec/specs/**/spec.md and
reads nothing else, on the Python standard library alone.
scripts/build_site.py is the one command; the workflow runs it and nothing
else. docs/evidence/spec-site-build.txt records both. A test renders the
real repository and asserts that no in-flight change identifier appears in any
published index or capability page.
Every requirement SHALL be shown as either grounded or unverified. The landing page SHALL state how many requirements are unverified before it presents anything else.
This is the site’s reason to exist. On this board the documentation and the hardware disagree routinely — a datasheet described a working radio whose enable line is never driven, and a vendor page described the Wi-Fi as an ESP32-S3 that the schematic contradicts. A reader’s first question is which claims have been observed, and the site SHALL answer it without being asked.
Grounding: the landing page’s <h1> is the count itself, emitted before any
capability is named. Tests against the built site assert that the count’s
position in the HTML precedes every capability name and every section heading,
and that the number printed matches what the spec tree actually contains
rather than what the page claims. Status is carried as a colour on every
requirement and as one proportional bar summarising the whole tree, in both
light and dark.
Where a requirement cites a path under docs/, the site SHALL link to that
file. A boot log or photograph that grounds a requirement SHALL be one click
from it, for a reader on the web and not only in a checkout.
A path named only inside an <!-- UNVERIFIED --> marker is not a citation.
Those markers routinely name the evidence that would ground a requirement,
which has not been captured yet, and treating that as a citation would report
a missing file for every requirement honestly waiting on one.
Grounding: cited files are rendered into the site as pages of their own, and
listed on the landing page under “Evidence on file”. A test walks every built
page and asserts that every link resolves to a file that exists. Another
asserts that a cited path has a page. docs/rtsmart-boot-log.txt reaches the
site with the two NUL bytes a serial capture left in it shown rather than
removed.
The site depends on conventions carried in prose — the <!-- UNVERIFIED -->
marker and the citation of a read path as grounding. Where the build cannot
determine a requirement’s verification status, it SHALL fail and name the file
and the requirement, rather than rendering it as grounded.
A silent default would make the count of unverified requirements untrustworthy, and that count is the only reason to build this.
Failing SHALL mean a non-zero exit that names every such requirement. It SHALL NOT mean withholding the site: the output is still written, and a requirement that declared no status is shown on it as a defect, in its own colour, with the capability it came from. A front door that reports “three requirements never said” is more useful than no front door, and a defect nobody can see is one nobody fixes.
Quoting a convention SHALL NOT count as using it. A requirement discussing the marker inside a code span is not thereby unverified.
Grounding: docs/evidence/spec-site-build.txt records a run over a staged
tree in which three requirements declare neither a marker nor a citation: the
command names each one and exits non-zero, and the page it wrote carries them
under “Build defects”. Unit tests assert that the classifier raises on a
requirement carrying neither rather than returning grounded, and that a marker
quoted in a code span is not read as a marker — a bug the first real build
produced, which reported two grounded requirements as unverified.
Generation SHALL complete within a recorded time budget and the output SHALL stay within a recorded size budget, both enforced by the build. The budgets SHALL be set above what the tree currently produces, so that a breach means something changed rather than that the numbers were always tight.
Grounding: docs/evidence/spec-site-build.txt records the date, the machine,
the Python, Node and Astro versions, and the measured build. The budgets in
scripts/build_site.py are set well above it, with the headroom stated and
the reason for it. A test forces a breach and asserts the failure names the
measured value and the budget.
The site SHALL be published at a URL, and that URL SHALL be rebuilt from
openspec/specs/ on every push to the default branch. A reader SHALL NOT have
to clone the repository or run anything to learn what is unproven.
A build that fails SHALL NOT be published. The count on the URL is only worth reading if it could not have been published while the specs were in a state the build rejects.
openspec archive adds a capability and the commit reaches the default branchArchived change · Archived
Snapshot 5836ef1d113d · 2026-10-17 08:22 UTC
Closed recordReview the archived record and cited scope
Readers can see accepted specifications and scattered progress notes, but cannot see which proposals are planned, being implemented, awaiting review or physical proof, or complete. The current spec site intentionally excludes in-flight changes, so it needs a clearly separate work view that does not present drafts as accepted capabilities.
/work/ board linked from the front door and handheld page. Its lanes distinguish planned, in progress, verification/review, and shipped/archived work.Non-goals: Live agent or GitHub issue telemetry, automatic inference that checked boxes mean a deployed feature, a task-editing UI, or new hardware behavior. The detail view reads only the committed snapshot; it does not fetch source from GitHub at click time. No physical board or Nix build is needed for this documentation change.
None.
docs/spec-site: permit a separately labeled proposal/work board alongside the accepted-spec ledger, with deterministic status generation and evidence-aware claims.The site data pass, Astro page and navigation, focused tests, and site build checks change. The generated board may link to committed proposal and evidence pages, but neither alters the OpenSpec source tree nor the spec ledger’s accepted requirement count. The existing 8 MiB site budget remains in force.
See proposal.md. The existing userspace site build renders archived openspec/specs/ through scripts/render_specs.py; its accepted-spec index intentionally rejects active proposal IDs. OpenSpec tasks and archive directories are committed repository data, while source-landed, review, and physical-proof states are not always represented by checkboxes. The current site has an 8 MiB output budget and is statically published.
Goals: A legible public snapshot that answers what is planned, underway, awaiting evidence, or shipped; every claim traceable to a committed revision and accessible source. Preserve the accepted-spec ledger’s meaning.
Non-goals: Live worktree or agent tracking, auto-promoting checklist completion to deployed status, querying private CI/board state at page load, editing tasks from the browser, or new device behavior. Layer: documentation userspace and its static build, not Nix image or board runtime.
Separate generator and page. Add a deterministic work-data pass beside render_specs.py, reading committed active changes, archived changes, and a small reviewed status file. Render /work/ from generated data in Astro; link it from index and handheld. The accepted-spec generator and requirement tally remain sourced solely from openspec/specs/. Rejected alternative: inserting active proposals into the existing spec index, which would make drafts look accepted and weaken its current test.
Stable lane classification with an explicit exception file. Archive means shipped/archived only when committed proof and deployment state are recorded; archived status alone means the OpenSpec work closed, so the card should name any residual deployment limit. Active zero-progress proposals are planned. Active checked tasks with incomplete work are in progress unless a reviewed status record identifies a specific review or evidence gate, when they enter verification/review. The override records change ID, lane, source state, physical state (or not applicable), next action, dependency IDs, evidence links, rationale, and review revision. Task totals and links are derived, never duplicated. Schema validation rejects unknown IDs, stale paths, empty next steps, contradictory archived state, and unsupported status terms. Rejected alternative: checkbox ratios as shipment state, because several changes land source before physical verification.
Committed snapshot provenance. Embed the source Git revision and UTC build time in generated data and page. Read tracked files at the build revision rather than neighboring worktrees or live process state. Stable sort by lane, priority/updated date, then ID; a content diff should reflect a source or reviewed override change. Rejected alternative: live GitHub API or agent telemetry, which adds network dependence and can reveal private work.
Links and public safety. Link proposal pages, accepted capability pages, and published docs/evidence/ pages through existing URL helpers. Use only repository-relative, tracked paths; reject absolute paths, traversal, remote private URLs, and known secret-bearing fields. The source override carries display-safe text, and the generated JSON is inspected by a test. Do not mirror uncommitted task logs. Existing site link checks include the work page. A proposal link is a labeled draft and never added to the accepted index. Rejected alternative: raw Markdown task dump, which is hard to scan and can expose local details.
Responsive Kanban layout. On wide screens, four aligned columns allow comparison; at narrow widths, lanes stack in document order with scroll position and clear headings. Each card shows its title, badge, done/total, separate source/physical status if relevant, next gate, dependencies, and compact links. Use native links and CSS; no drag-and-drop or client data fetch is required. Preserve keyboard focus, contrast, and comfortable tap targets. Rejected alternative: horizontally clipped four-column board on the 568-pixel panel.
In-dashboard card detail. Include proposal, design, task and delta-spec text from the same committed Git snapshot in generated data. Render it at build time with the site’s existing Markdown processor, escaping raw HTML and resolving repository-relative evidence links to local evidence pages when published. Missing or oversized source inputs fail with the item/path named; do not fetch Markdown at click time. Each card is one native link with a direct detail URL; normal click or keyboard activation opens an accessible native dialog, while open-in-new-tab remains available. Move secondary proposal, task, evidence, dependency and status-source links into the dialog so cards contain no nested controls. The dialog displays summary, progress and scrollable labeled document sections. Close button, Escape and browser Back restore focus to the card and preserve board scroll position. A ?work=<id> URL can reopen the selected card directly; invalid IDs return to the board without a broken modal. Keep pinned GitHub source references in a secondary “source files” area. Rejected alternative: primary card clicks navigating to GitHub, which interrupts the board and makes comparison difficult; rejected alternative: raw preformatted Markdown, which hides headings, tables and links.
The first board is published. Land this refinement to the proposal promptly, then implement and validate the committed document pass and accessible dialog. Build with python3 scripts/build_site.py, inspect selected-card and close behavior at mobile and desktop widths, then merge/push and inspect the revised published /work/ URL at the landed revision. No board or Nix build reservation is required. If deployment fails, the prior published site remains in place while the failed revision is corrected.
The named work-board generator and test commands are implemented host checks. Publication is recorded separately below.
python3 tests/test_work_board.py on real and synthetic fixture trees.python3 tests/test_work_board.py.python3 tests/test_work_board.py.Proof: python3 tests/test_work_board.py is host repository-data proof only; it does not assert device behavior.
/work/ with four clear lanes, task progress, next gates, dependencies, draft/accepted labels, links, and source/physical distinctions; verify rendered HTML assertions with python3 tests/test_work_board.py.python3 scripts/build_site.py./work/; add a focused regression assertion and run python3 scripts/build_site.py within the existing 8 MiB budget.python3 tests/test_work_board.py with dirty-checkout and failure fixtures.python3 tests/test_work_board.py and a browser interaction check.python3 scripts/build_site.py and its built-link/8 MiB assertions.Proof: python3 tests/test_work_board.py and python3 scripts/build_site.py prove a host site build and link/size checks, not publication.
openspec validate the-site-shows-a-public-work-board --strict and python3 scripts/build_site.py at the exact candidate revision./work/ URL and its front-door/handheld links at the landed revision, record URL, revision, UTC timestamp, and any deployment failure in docs/evidence/spec-site-work-board/README.md; verify with python3 scripts/build_site.py./work/ URL at its new revision, directly open an item and verify its local documents/links and close behavior; record URL, CI run, UTC observation and limits in docs/evidence/spec-site-work-board/README.md, then run python3 scripts/build_site.py.openspec validate --all --strict, sync the delta and archive the change. Keep it open if publication or evidence remains unverified; inspect the archive push’s CI and Pages revision as handoff follow-through.Proof: the exact host commands above and published URL inspection. No physical board or Nix build is required for this documentation capability.
The accepted-spec ledger SHALL be generated from openspec/specs/ and SHALL NOT be hand-maintained. A separately labeled public work board MAY show committed in-flight proposals, but SHALL identify them as drafts and SHALL NOT include their requirements in the accepted-spec ledger or its verification tally.
Building SHALL be a single command, and it SHALL be the same command locally and in CI, so that what a person sees before pushing is what gets published.
Grounding: scripts/render_specs.py walks openspec/specs/**/spec.md and
reads nothing else, on the Python standard library alone.
scripts/build_site.py is the one command; the workflow runs it and nothing
else. docs/evidence/spec-site-build.txt records both. The existing accepted
ledger test excludes in-flight change identifiers from index and capability
pages. docs/evidence/spec-site-work-board/README.md records the focused
work-board tests and the published page at revision 95595a8e.
Grounding: docs/evidence/spec-site-work-board/README.md records the host layout and link checks and the published four-lane page at revision 95595a8e.
The documentation site SHALL provide a touch-readable work board with planned, in-progress, verification/review, and shipped/archived lanes. Each work item SHALL show its task progress, next concrete action or evidence gate, dependencies, and links to committed proposal, accepted spec, or evidence where available. Where source code has landed but physical proof remains, the two states SHALL be distinct. A checked task count alone SHALL NOT imply shipment, deployment, or physical verification.
Grounding: docs/evidence/spec-site-work-board/README.md records the committed generator tests, exact build, published revision and link observations.
The work board SHALL be generated from committed repository state at an identified revision and build time. Any status that cannot be derived from proposal, task, archive, or evidence files SHALL come from a reviewed committed override with a rationale and source link. Missing or inconsistent overrides and broken links SHALL fail the build. The page SHALL describe itself as a dated snapshot, not live task or agent telemetry, and SHALL exclude private workstation paths, addresses, credentials, and uncommitted work.
Grounding: docs/evidence/spec-site-work-board/README.md records the bounded source and Markdown tests, browser interaction checks, and successful Pages deployment of the whole-card detail at revision a8b3c747.
The work board SHALL make each entire card a single keyboard-accessible control that opens its committed proposal, design, tasks and delta specification inside the dashboard, with readable headings, tables, code and links rather than raw source text. The detail SHALL identify the same status, task progress and snapshot revision as the card. Published evidence links SHALL remain on the site where a local evidence page exists, and pinned external source links SHALL be secondary. The reader SHALL be able to close the detail with touch, keyboard Escape or browser Back and return focus to the selected card; a direct detail URL SHALL reopen the item. The detail SHALL use only committed content from the displayed snapshot, without a live GitHub fetch.
Archived change · Archived
Snapshot 5836ef1d113d · 2026-10-17 08:22 UTC
Closed recordArchived after matching normal artifacts, ordinary autoboot, physical power-swap recovery and accepted Home/Apps/Overview/Terminal navigation.
The latest verified shell fixes run only after runtime activation: reboot still selects an older system. A matching-current-kernel manual boot reaches Linux but has unresolved visible navigation acceptance, so selecting it persistently would lose the usable handheld.
Mainline kernel adoption, Linux SMP, GPU acceleration, theme/performance redesign, whole-card reflashing or routine flash readback. This change repairs normal deployment consistency only. Host inspection can proceed independently; panel and ordinary reboot acceptance require the reserved physical board.
None.
system/nixos-config: add coherent selected-system boot and safe physical rollback requirements alongside the existing console boot capability.flake.nix, a bounded normal boot bundle derivation under nix/, a bundle inspector and board operator controller under tools/, and committed docs/evidence/boot-verification/. Existing external-bootloader no-op activation is preserved until an explicit install is qualified. Normal selectors and stage 1 are preserved. Evidence baseline: docs/evidence/boot-verification/2026-10-01/README.md.
The 2026-10-01 matching vendor trial booted /nix/store/xphf8zb00gz9hiyqkkh399rldr2ljykb-nixos-system-nixos-26.11.20260919.20b1ddd and its selected 03zyl0… kernel, but camera output initially appeared dark after compositor startup. Native output later showed Foot, so a dark photograph alone cannot establish a dead display. Working-kernel userspace activation showed Home after explicit navigation. Normal restoration with the original p6z5nsr… Image was photographed. Persistent bootargs and profile remained older. See committed baseline evidence; neither service-active state nor common scan-out debug messages prove panel acceptance.
/nix-path-registration must remain absent to avoid bootstrap profile replacement. Use CR-only U-Boot commands and inspect each load count and CRC.Matching vendor candidate and protected baseline now pass the same manual load path and show photographed Home. The operator accepts candidate navigation in docs/evidence/boot-verification/coherent-manual-candidate/operator-navigation.json; no display-driver root cause was established for the earlier ambiguity. Ordinary autoboot after persistent install and a later physical power swap select the matching normal system, with all eight protected hashes retained and visible Home. docs/evidence/boot-verification/coherent-ordinary-boot/operator-navigation.json accepts the three requested post-reboot touch routes. Physical failed-write rollback remains unperformed; the installer’s interruption window and retained serial recovery procedure stay documented. A host build cannot establish display readiness. Injected board events retain their own evidence class. Failed boot/recovery remains documented alongside successful runs.
docs/evidence/boot-verification/2026-10-01/{README.md,result.json,normal-boot-candidate.txt,normal-boot-restore.txt,restore-verify.txt}. No persistent selection or new finger acceptance is claimed.nix build .#coherentShellBootFiles --no-link --print-out-paths --max-jobs 1 --cores 4, then python3 tools/coherent-shell-boot-inspect.py <bundle>, and 13 tamper tests. Selected kernel/initrd payloads, complete board DTB, DT/env init, CRCs and closure registration pass; see docs/evidence/boot-verification/coherent-bundle-host/README.md. Host proof only.docs/evidence/boot-verification/coherent-manual-comparison/README.md, its baseline.json and candidate.json. Commands use the reserved CR-only controller with --baseline, then without it. No root cause inferred from shared warnings.1. good. explicitly accepts Home→All apps, bottom handle→Overview and Terminal open/return. Proof: comparison evidence and docs/evidence/boot-verification/coherent-manual-candidate/operator-navigation.json; accepted exact bundle, system/kernel and Rust ELF retained. 3.1 Installed the qualified bundle’s four normal boot artifacts, selected the matching persistent profile and retained checked root backups/GC roots. The controller’s --install mode passed on the reserved board; docs/evidence/boot-verification/coherent-ordinary-boot/boot-result.json records all eight pre/post hashes and installation methods. Stage 1, selectors, root layout and runtime secrets were preserved. Root-backed replacement was necessary for Image/initrd; its limits and exact recovery/rollback commands are documented in that evidence README. No whole-card flash occurred.
3.2 Reboot through untouched normal autoboot and record booted kernel, /proc/cmdline init path, /run/current-system, persistent profile, active shell services, photographed Home and usable touch navigation. Proof: flock /tmp/k230-board.lock python3 tools/console.py /dev/ttyACM0 --wait=5 'readlink -f /run/current-system; readlink -f /run/booted-system/kernel; cat /proc/cmdline' plus committed visible observation. Identity, eight unchanged hashes and photographed/native Home are committed in docs/evidence/mainline-display/physical-2026-10-01/power-swap-recovery-2026-10-02/README.md; user report “yeah it seems great let’s go” accepts the explicitly requested three routes in docs/evidence/boot-verification/coherent-ordinary-boot/operator-navigation.json. Remembered appearance was separately checked in the ordinary-boot evidence; this is not all Omarchy acceptance.
3.3 Strict validation passed; source and ordinary-boot proof landed/pushed through 779de082d55b0089a044442c6873017da9de2bd2. Matching CI/Pages run 36963714103 passed build/deployment. Post-reboot touch gate 3.2 is now accepted in the committed operator report; all seven tasks are complete.
Grounding: docs/evidence/boot-verification/coherent-bundle-host/README.md binds the kernel, initrd, DTB and init to one configuration. docs/evidence/boot-verification/coherent-ordinary-boot/README.md records installation and uninterrupted ordinary autoboot with matching system/profile/kernel/init and active shell services. docs/evidence/mainline-display/physical-2026-10-01/power-swap-recovery-2026-10-02/README.md independently verifies the same normal selection after physical reset; docs/evidence/boot-verification/coherent-ordinary-boot/operator-navigation.json records operator acceptance of Home→All apps, handle→Overview and Terminal open/return after that reboot.
The system SHALL provide matching kernel, initrd, board device tree and explicit boot init for the selected coherent-shell configuration. After ordinary boot the person SHALL see a usable shell on the panel and the serial console SHALL report that exact selected system, rather than an older boot generation.
Grounding: docs/evidence/boot-verification/2026-10-01/README.md records a failed candidate and restored normal system with photographed Home. docs/evidence/boot-verification/coherent-ordinary-boot/README.md records checked root-backed boot backups, retained GC roots, serial manual recovery, successful persistent installation and its interruption window. The later physical power-swap recovery verifies all eight protected hashes and visible normal Home. Physical failed-write rollback and power-cut installation testing remain unperformed and are not claimed.
The system update procedure SHALL retain a usable normal boot backup and serial recovery before selection. A failed candidate SHALL remain unaccepted until the normal system is restored and its visible shell and protected identities are observed.
Archived change · Archived
Snapshot 5836ef1d113d · 2026-10-17 08:22 UTC
Closed recordScoped theme coverage and native dark/light rollback are complete; continue broader theme-picker, persistent deployment and shell polish in their owning proposals.
Settings and the notification shade already render in the Rust shell, but the remaining theme proposal still describes the data helpers as separate UI clients and their compatibility reports do not name the roles actually painted. That makes theme coverage and unsupported states difficult to verify or close.
tests/test_handheld_theme_rendering.py --surface system
check: generated payload/report checks plus actual Rust renderer pixel checks,
with no missing-renderer skip.Non-goals: redesigning Settings or notifications, another theme chooser, new palette roles, separate fake appearance endpoints, kernel or boot changes.
runtime/shell-themes: adds the distinct Settings/notification coverage
requirement through an ADDED delta. The canonical capability is not yet
present; its parent theme change remains open for separate outstanding
proof. Archiving this bounded change must retain the parent’s pending
requirements and cannot imply the whole theme proposal is complete.Userspace only: tools/theme_tokens.py, tools/theme_activate.py,
tools/theme_catalog.py, Rust rendering/compatibility parsing, host tests and
committed board evidence. nix/handheld-settings.nix invokes a JSON/action
helper and nix/handheld-notifications.nix invokes notification data/actions;
neither paints a Wayland surface. Settings and Shade share the existing Rust
appearance receiver, so the two-phase Rust/deck transaction already covers
both atomically. Host tests do not certify the physical panel.
Read end to end on 2026-10-01:
nix/handheld-settings.nix exports helper executable paths and runs
tools/device_settings.py; nix/handheld-notifications.nix exports Sway IPC
and runs tools/notification_center.py. These are JSON/action helpers, not
rendered clients. The real Settings and Shade surfaces are Route::Settings
and Route::Shade in nix/rust-shell-client/src/render.rs, driven by
main.rs’s service snapshots and layer-shell overlay.
The Rust process owns both surfaces and already reads startup appearance and
handles prepare/commit/rollback through appearance.rs and main.rs. Shared
RendererCache::set_appearance invalidates their rendered caches; deferred ACK
waits for presentation readiness. Reuse this Rust/deck transaction rather than
adding independent Settings/notification endpoints for surfaces with the same
owner. The old assumed additional-endpoint task is superseded by proof of this
actual owner, preserving all-or-nothing semantics.
Settings panel/row backgrounds use controls.background if authored, otherwise
menu.background, otherwise palette.background. Normal text/tint consumes
controls.normal-color; selected tint consumes selected-color with a normal
fallback; normal/selected fills consume their alpha tokens. Selected outlines
consume the selected brush/width; ordinary row outlines remain omitted under
the accepted border-light design. Shared readable secondary text/accent/error
uses the palette. Notifications consumes its background and authored alpha,
text, countdown/accent and shared controls tints. Scalar text roles adapt the
first brush stop; full background/fill brushes retain gradients and alpha.
Every generated controls/notifications role must be reported, including absent
hover/focus, normal outlines, pressed/selection-specific states and notification
outlines as unavailable where no painted equivalent exists. Unknown custom
roles remain unknown. Report fallback role adaptation explicitly.
Rejected: pretending data helpers can repaint, creating extra acknowledgments for one shared UI owner, calling every compiled token painted, restoring unnecessary outlines to justify a coverage claim, or accepting a host screenshot as physical proof.
The named system test runs generation/role-report regressions plus actual Rust Cairo renderer pixel tests. It fails when Cargo/the native renderer test cannot run. Normal startup/prepare/commit/rollback parser and rendering tests and the existing two-receiver transaction suite establish host behavior only. Task group 4 retains the full coherent closure build and physical dark/light native captures with rollback. No fresh real-finger usability trial is needed for this theme-only scope; injected commands and native screenshots are labeled.
No surface-owner question remains. Task 4.2’s six native physical-board captures
now establish dark/light presentation and same-surface rollback. See
docs/evidence/omarchy-themes/settings-notifications-themed/board/README.md.
This scoped change needs no additional boot or finger gate.
Settings and Shade rollback was visible at eb38af2a, but Home’s independent
cached layer did not receive a repaint when the renderer changed appearance.
Mark that layer dirty on optimistic adoption, commit/rollback and failed-commit
restoration too. Repeat the native trial on the rebuilt source and compare the
dock as well as the scoped Settings/notification colors. Do not use the earlier
partially stale frames as proof of a coherent rollback.
The repeat at 288535289172c8465c4fa408eaa8ba2c7ab8a5ac passed: Home dock
pixels as well as Settings and Shade returned to dark. The matching full
coherent system built successfully. Normal services and the original active
generation were restored; this was a recoverable component trial, not full
system activation. The larger theme/polish proposals retain their own gates.
Surface ownership reconciled 2026-10-01 after reading the helpers and actual Rust renderer. This supersedes the assumed extra-endpoint plan without dropping startup, commit/rollback, role coverage, full-build or physical proof.
nix/handheld-settings.nix and nix/handheld-notifications.nix
end to end. Record, in this change’s own design.md (updating its “Open
Questions” section rather than guessing here), whether each is a rendered
surface at all today, or purely a command wrapper with nothing to repaint.
If either has no rendered surface, say so before task 2 assumes one.theme_tokens.py’s existing
sections["controls"]/sections["notifications"] output (already
asserted present by tests/test_handheld_theme_rendering.py:: test_real_helper_output_becomes_bounded_native_payload) so this task adds
no new palette role.Proof: 1.1/1.2 are a reading exercise; record findings in design.md, not a
command.
python3 -m unittest tests.test_omarchy_theme_transaction and
cargo test --offline --manifest-path nix/rust-shell-client/Cargo.toml.appearance.json on startup and on the existing commit/rollback signal,
the same way the Rust shell and Sway deck already do. If task 1 found no
rendered surface at all for one of them, this task’s own scope is limited
to giving it the minimal surface needed to be themed, not a redesign.Proof: python3 -m unittest tests.test_omarchy_theme_transaction and the
relevant client’s own unit tests (host).
--surface system flag to
tests/test_handheld_theme_rendering.py that the-shell-loads-omarchy- themes’s own task 3.3 named but never implemented. It SHALL assert every
Settings/notifications role this change claims and fail (not skip) on one
left unthemed.applied/adapted/
unavailable/unknown) names each Settings/notifications role by name;
add a host regression for a role with no themeable equivalent reporting
unavailable rather than being silently omitted.Proof: python3 tests/test_handheld_theme_rendering.py --surface system
and the added compatibility-report regression, both host-only.
nixosConfigurations.k230-coherent-shell toplevel; record the exact
closure and source identities. Needs no board.grim screenshots showing each surface’s colors
match the active generation, and that a rollback restores the previous
generation’s colors on the same surface. Commit the captures and the
exact commands under docs/evidence/omarchy-themes/settings-notifications- themed/.Proof for 4.1: the named nix build/toplevel evaluation. Proof for 4.2: the
committed native captures and exact board commands; a host test does not
establish this by itself.
Host task groups 2–3 passed 2026-10-01: docs/evidence/omarchy-themes/settings-notifications-themed/host.md. Build and native physical-board groups passed: docs/evidence/omarchy-themes/settings-notifications-themed/board/README.md. All eight scoped tasks are complete; broader theme/polish and persistent deployment remain with their owning proposals.
The userspace shell applies resolved theme roles to Settings and notification Shade surfaces, reports unsupported roles explicitly, and restores their colors when a shared appearance transaction rolls back.
Grounding: docs/evidence/omarchy-themes/settings-notifications-themed/board/README.md records the physical dark/light Settings and Shade presentation, named compatibility reports and forced rollback on the same Rust renderer.
The system SHALL make the Rust shell’s Settings and notification Shade surfaces read
the active generation’s resolved colors the same way the shell, drawer, and
card renderers already do, and repaint on the existing commit/rollback
signal theme_transaction.py’s receiver fan-out already sends. It SHALL
report their coverage in the existing applied/adapted/unavailable/
unknown compatibility view by name, rather than silently inheriting
hardcoded defaults, per the-shell-loads-omarchy-themes’s own
“Compatibility and physical completion are explicit” requirement. This
requirement adds no new palette role: it wires up theme_tokens.py’s
existing sections["controls"]/sections["notifications"] output.
notifications section (or relies on documented fallback) and a
notification is shownnotifications section, and the compatibility report names it
applied or adapted rather than silently defaultingunavailable rather
than omitting it or claiming coverage--surface system is exercisedpython3 tests/test_handheld_theme_rendering.py --surface system runs against a built packageArchived change · Archived
Snapshot 5836ef1d113d · 2026-10-17 08:22 UTC
Closed recordFunctional live-card UI accepted. Performance acceptance and selected system/non-fixture QEMU integration gates are closed in 2026-10-10-the-card-deck-still-misses-its-frame-budget.
A person can launch and switch applications today, but cannot see or directly manipulate their running work as a coherent handheld surface. The existing metadata overview is deliberately text-only, so it cannot provide the live, finger-following card interaction requested for the shell.
the-shell-has-a-card-composition-plan architecture decision. That decision
chooses the composition boundary; this proposal does not assume a client,
compositor change, GPU path, or second core.Non-goals: boot work, a notification ecosystem, application search, multitasking policy beyond this deck, gestures beyond card entry/deck/close, and animation systems beyond direct shrink, drag, deck, expand, and throw-close behavior.
runtime/card-shell: live application-card presentation, manipulation,
privacy/unavailability handling, and bounded recovery for the handheld.None.
The eventual implementation may affect userspace shell composition, Sway or a new composition boundary selected by the sibling architecture change, launcher integration, Nix packaging, tests, and board evidence. Host model tests and a narrow derivation build can proceed before hardware, but live content, touch, readability, frame cost, and recovery require physical-board evidence. No kernel, boot, second-core, or GPU dependency is assumed by this proposal.
The operator authorized archiving the functional live-card UI and waived
additional difficult camera captures. Existing injected-board proof plus their
physical acceptance are recorded in docs/evidence/proposal-closeout/2026-10-01/live-card-ui.md. Privacy/refusal/timeout coverage
remains injected evidence; no fresh per-case finger or reliability trial is
claimed. This supersedes the original mandatory-camera acceptance route.
The existing the-card-deck-still-misses-its-frame-budget now solely owns
original tasks 4.2 and 5.1, with their full measured-budget, real integrated
closure and non-fixture QEMU requirements intact. Historical failed costs
remain failures and budget acceptance remains UNVERIFIED. This parent archive
accepts functional UI only, not timing or full-image proof.
See proposal.md and the delta specs. The current shell is a Sway/Pixman
session with a persistent touch bar, keyboard, and launcher. Its implemented
window overview carries metadata only; it is not a live application surface.
The physical panel is 568x1232 RGB565, and the default compositor path is CPU
Pixman. Existing gesture timing is specific to launcher cards and cannot be
reused as a live-composition result.
This change is userspace work. It does not assign work to stage 1, the kernel, or the device tree. Nix owns packaging and image integration after an architecture decision; the shell owns its control handoff; the board owns acceptance of panel, touch, and live-content behavior.
Goals:
Non-Goals:
the-shell-has-a-card-composition-plan decision.Gate the composition boundary, not the whole change. The sibling architecture proposal must land with a decision and evidence before code that captures or composes live application content is integrated. It can select a Wayland-client or compositor boundary within the single-owner display path, and must establish ownership, input/focus semantics, source availability, privacy, and failure behavior. State-machine tests, deck policy, and recovery contracts can proceed without that choice.
Consume the whole-shell UX audit as an interaction contract. The
the-handheld-has-a-coherent-ux-plan audit must supply its applicable visual
and interaction findings before final card visual hierarchy, motion constants,
and close gesture behavior are accepted. It is not a dependency on completing
all of the audit’s successor changes: the card deck remains a bounded core
deliverable.
The UX audit has not yet arrived at proposal time; this is a gate on final card visual and motion acceptance, not a claim that its findings have been incorporated.
Use live content only where the selected boundary can represent it safely. Eligibility is explicit. An unavailable or private surface gets a non-live card and recovery path; it is never replaced by another application’s pixels. A text-only overview was rejected because it cannot meet the requested visual-card behavior.
Separate direct manipulation from decorative animation. Finger position maps to the selected card while held; the deck is horizontal; release resolves to a card or returns to a stable deck. An upward throw requests graceful close. No springs, blur, thumbnail effects, or general animation framework belong in this change.
Make performance a decision gate. The implementation declares its frame/update, input-to-visible-update, and additional-memory budgets before board acceptance. If the default Pixman implementation misses, the result is a recorded choice among reduced behavior, a specifically justified composition optimization, or rejection. Any reduction retains live visual cards, finger-following, deck selection, tap expand, and recoverable throw-close; otherwise the work stays open or becomes an explicitly authorized successor. An optional VGLite trial is measured separately; it does not change the default acceptance requirement.
The sibling architecture decision must resolve the composition boundary and which live-surface classes are available. The UX audit must resolve the applicable card hierarchy and motion contract. Those questions change the implementation route, so they are explicit gates rather than assumptions.
The coordinator reviewed and landed the opt-in source-built Sway probe in
801af92. The selected owner is pinned Sway 1.12, with wlroots 0.20.2
scene-surface mirrors inside its single DRM/KMS and Pixman presentation path.
The committed architecture contract is
docs/research/card-composition-architecture.md; actual cross-built Sway,
independent subsurfaces, input/focus lifecycle and failure tests are recorded in
docs/evidence/card-composition-headless/README.md. These are headless QEMU user
emulation and injected-input results, not board proof. The architecture change’s
entire physical evidence group 3 remains open. This decision permits the next
separate opt-in product package; default image integration and physical product
acceptance remain gated by the named board checks.
The product adapter consumes the separate host-testable C policy in
nix/card-shell-policy/. Sway owns stable container IDs and live-view
revalidation, client-buffer references, scene lifetime, global touch routing,
keyboard focus and graceful close dispatch. The policy owns horizontal deck
selection, direct finger offsets, entry recognition, normalized recovery states
and bounded close waiting. The adapter must consume actual complete-stream
touch cancellation separately from a locally rejected gesture that still has
pending hardware releases. An unmap is a source-removal observation, not proof
that a process exited; a still-mapped timeout is not a protocol refusal reply.
The bounded initial product package enumerates mapped XDG toplevels dynamically,
not the probe’s two-app allowlist. Only source-audited, supported SHM surface
trees may be shown live. Unsupported/unavailable sources receive a non-live
card. A session exclusion (SWAY_K230_CARD_PRIVATE_APP_IDS, exact app IDs
separated by colons) or compositor mark k230_card_private produces a fixed
private placeholder, without reading/rendering that app’s title or pixels.
k230_card_unavailable provides an explicit unavailable state. A caller must
classify an unknown source as unavailable rather than assume it is live; no
unimplemented protected-content protocol is claimed. Privacy changes must
release existing mirror references before the next composed frame. No private
or unavailable card may display another app’s pixels. Only graceful XDG close
is allowed; timeout/refusal retains the source and existing recovery controls.
The coordinator’s accepted UX audit is archived at
openspec/changes/archive/2026-09-23-the-handheld-has-a-coherent-ux-plan/ and its
synced capability is openspec/specs/docs/handheld-ux-plan/spec.md. The applicable
accepted contract and review are docs/research/handheld-ux/interaction-contract.md
and docs/research/handheld-ux/design-review.md. Their adopted product constraints
are: preserve the existing 56px top bar; title role 40–44px, card title 30–34px
and state/hint 19–22px; at least 24px content inset and 56px control height;
selected/pressed/error states have visible non-color cues; reserve actual
keyboard space and keep Back above it. Use direct finger tracking and immediate
stable endpoints; reduced motion must preserve live cards, selection, expansion,
close/refusal and button recovery. The card deck is horizontal. Entry has an
upward edge gesture and a persistent Cards/Back button; Previous/Next and Close
buttons provide alternatives to browsing and throwing. Existing top-bar control
touches first restore normal Sway routing, so Apps, Windows/Home, Keyboard,
System, Help, terminal, monitor and Back keep their current command owners.
The launcher mapping also returns the card surface to normal application state.
The shared policy’s initial edge, tap and throw constants are provisional source values, not measured physical thresholds. The adapter and runtime fixtures must use the same constants. The accepted audit’s 200ms settled-release ceiling does not replace the separate finger-tracking/input/frame/memory budget declaration or the physical review. The product remains opt-in, Pixman-only and independent of the separate VGLite renderer experiment. Failure disables/restores only the card scene; the known normal shell package is unchanged.
The operator authorized archiving the functional live-card UI and waived
additional difficult camera captures. Existing injected-board proof plus their
physical acceptance are recorded in docs/evidence/proposal-closeout/2026-10-01/live-card-ui.md. Privacy/refusal/timeout coverage
remains injected evidence; no fresh per-case finger or reliability trial is
claimed. This supersedes the original mandatory-camera acceptance route.
The existing the-card-deck-still-misses-its-frame-budget now solely owns
original tasks 4.2 and 5.1, with their full measured-budget, real integrated
closure and non-fixture QEMU requirements intact. Historical failed costs
remain failures and budget acceptance remains UNVERIFIED. This parent archive
accepts functional UI only, not timing or full-image proof.
The operator authorized functional UI archive and transfer of unresolved budget
and integrated image/QEMU work to the existing performance successor. The
completed handoff tasks below replace the original measurement/boot tasks;
their original requirements remain unchecked in the successor. Historical
progress notes below describe the evidence state at their recorded revisions,
not current ownership. See docs/evidence/proposal-closeout/2026-10-01/live-card-ui.md.
the-shell-has-a-card-composition-plan; record the chosen owner, live-surface eligibility, input/focus handoff, privacy behavior, and failure boundary in this change before implementing live capture or composition; verify with openspec validate the-shell-has-a-card-composition-plan --strict and review its committed evidence.the-handheld-has-a-coherent-ux-plan findings and record the accepted card hierarchy, direct-manipulation behavior, and throw-close feedback in this change; verify the resulting interaction contract with openspec validate docs/handheld-ux-plan --type spec --strict and the committed coordinator review in docs/research/handheld-ux/design-review.md. This does not wait for all audit successor changes.python3 tests/test_card_shell_state.py. Coordinator proof: docs/evidence/card-shell-policy-host.md.python3 tests/test_card_shell_recovery.py plus existing python3 tests/test_touch_menu.py.python3 tests/test_card_shell_composition.py using eligible and denied fixture surfaces.python3 tests/test_card_shell_gestures.py and native test surface traces.nix build .#card-shell and record its closure difference from the current system.tools/card-shell-benchmark.py and verify its parser with python3 tools/card-shell-benchmark.py --self-test.the-card-deck-still-misses-its-frame-budget tasks 4.2a–e under the operator-authorized 2026-10-01 scope split. Verify the retained criteria/commands and ownership against docs/evidence/proposal-closeout/2026-10-01/live-card-ui.md and openspec validate the-card-deck-still-misses-its-frame-budget --strict. This is a completed scope handoff, not a passing measurement.python3 tools/card-shell-benchmark.py --board --renderer vglite --output docs/evidence/card-shell/vglite.json. If not pursued, record that decision in the Pixman evidence so this optional path does not remain an archive gate.tools/qemu-k230.sh --card-shell-smoke in the existing performance successor task 5.1 under the operator-authorized split. Verify retained build/QEMU commands and dependency against docs/evidence/proposal-closeout/2026-10-01/live-card-ui.md. No image or non-fixture boot success is claimed.python3 tools/card-shell-acceptance.py --execute --provenance injected-touch --output docs/evidence/card-shell/injected.docs/evidence/proposal-closeout/2026-10-01/live-card-ui.md against ordinary-cards.md, card-composition.md and the operator closeout instruction. No new real-touch camera trial is claimed.openspec validate the-shell-manages-apps-as-cards --strict. Passed 2026-09-28 on close/shell-umbrella. Each requirement’s marker now names its injected-touch or failing board-cost evidence and keeps real-finger use and the budget decision UNVERIFIED (tasks 4.2 and 5.3). Validation must be rerun before archive.Host implementation evidence for tasks 2.2 and 3.1–3.3: docs/evidence/card-shell/headless/README.md. Actual compositor runtime and narrow build pass; diagnostic headless frame-interval budget fails and isolated session memory is incomplete. Product board cost, every physical control route, image integration, and real-finger acceptance remain open in groups 4–5.
Coordinator reran the final adapter through actual wlroots touch routing (17
checks) and the independent native Wayland receiver pairing suite (7 checks).
Review and exact artifacts: docs/evidence/card-shell/coordinator-review.md.
Budget declaration/parser and actual producer integration complete 4.1; the
recorded headless cadence failure and all board cost/physical gates remain open.
Task 5.2: docs/evidence/card-shell/injected/README.md records thirteen observed
injected interaction checks and coordinator review of native captures from the
opt-in product package on DSI-1 RGB565. Both live parent/child surfaces are
visible during a held drag, expansion/privacy/close recovery and persistent
controls are covered, and normal-shell restoration passed. The first failed
trial remains committed. The repeat uses the old telemetry producer, so cost
parsing still rejects it; tasks 4.2, 5.1 and 5.3 remain open.
Task 4.2 remains open: docs/evidence/card-shell/board-cost/long-trace/README.md
records adequate frame coverage but failed CPU/tracking budgets. Twelve repeated
interaction checks were observed; upward throw missed once, so repeatability
also remains unresolved despite the earlier successful task 5.2 evidence.
The source-timestamp correction now has a failing old-adapter negative control,
passing delayed-input/native-routing tests and one board repeat observing all
13 interaction checks. docs/evidence/card-shell/touch-timestamps/board/README.md
retains the repeat’s still-failing frame costs. Tasks 4.2, 5.1 and 5.3 stay open;
one injected repeat does not establish physical throw reliability.
The repeated-millisecond velocity correction is independently reproduced against
old policy/runtime and passes new sanitizer/native-routing checks. Three normal
board repeats observe all 13 injected checks apiece; evidence and retained
budget failures are in docs/evidence/card-shell/throw-sampling/README.md.
This does not establish historical failure attribution or physical-finger
reliability. Tasks 4.2, 5.1 and 5.3 remain open.
The following repaint-stage profile correlates all 268 submitted board frames
and attributes about 98% of repaint CPU to output-state construction/painting.
docs/evidence/card-shell/repaint-stages/README.md records both failed cost
budgets and a renewed upward-throw check failure (12/13 observed checks), with
successful normal-system restoration. This diagnostic does not establish the
failure’s cause or accept performance; task 4.2 remains open.
The corrected fixture now waits for live classification before starting its
throw. docs/evidence/card-shell/throw-fixture-sync/README.md preserves two
setup failures and the following same-package board run with all 13 checks
observed, 277 fully correlated submitted frames, and independent normal-system
restoration. Frame CPU and tracking budgets still fail; this supports the
fixture-race diagnosis without completing performance or physical-touch gates.
The same-package scaled-cache off/on physical pair observed all 13 checks in
both arms, but increased p95 CPU cost and left tracking cadence unchanged.
docs/evidence/card-shell/scaled-cache-board/README.md preserves all 662
submitted frames and independent normal-system restoration. The cache remains
disabled; task 4.2 is still open with unchanged limits.
Task 4.3: docs/evidence/card-shell/renderer-decision.md and
docs/evidence/card-shell/renderer-decision.json record the decision not to pursue the
optional GPU path within this card acceptance change. Existing GPU synthetic
scene measurements are explicitly not represented as a card comparison. The
separate GPU proposal retains every open gate; task 4.2 and image/real-finger
acceptance remain incomplete. The separate user-authorized RVV promotion is
unaffected.
Defines a touch-first live-card surface that lets a handheld user see, resume, and safely close eligible running applications.
Grounding: docs/evidence/proposal-closeout/2026-10-01/live-card-ui.md records functional operator acceptance, supplemented by injected-board proof in docs/evidence/card-shell/injected/README.md. No new camera or per-case physical trial is claimed.
The card shell SHALL be enterable from an arbitrary eligible running
application through a dedicated edge gesture. It SHALL also provide a
persistent button route for entry or recovery, without requiring the Apps
launcher to be open. While the card shell is active, dismissed, unavailable,
or recovering from a close request, Apps, Windows/Home, Keyboard, System,
Help, terminal, monitor, and Back SHALL remain usable through their existing
shell routes.
Grounding: docs/evidence/proposal-closeout/2026-10-01/live-card-ui.md records functional operator acceptance, supplemented by injected-board proof in docs/evidence/card-shell/injected/README.md. No new camera or per-case physical trial is claimed.
The card shell SHALL present eligible running applications as live visual cards,
not title-only substitutes. Entering the card shell SHALL shrink the active
application into a card, keep a horizontal deck of eligible cards, move the
selected card with a single finger, and expand the tapped card back to the
active application.
The card shell SHALL identify an application whose live surface is unavailable, protected, or excluded by the session privacy policy without exposing its content. It SHALL provide a clear non-live card state and a route back to the existing Apps or Windows/Home controls.
The card shell SHALL treat an intentional upward throw of an eligible card as a request for that application to close gracefully. If the application refuses, times out, or fails to close, the shell SHALL retain or restore a usable card and make an existing recovery route available; it SHALL NOT silently discard application state.
The card shell SHALL record input-to-visible-update latency, frame/update cost, and incremental memory use at the panel’s native portrait mode on the default Pixman path. If a declared interaction budget is missed, the implementation SHALL record the result. A reduced-refresh or optimized path is acceptable only when it still preserves live visual cards, finger-following, deck selection, tap-to-expand, and recoverable throw-close. If it cannot, the change SHALL remain open or move to an explicitly authorized successor; it SHALL NOT be archived as accepted card-shell behavior.
Archived change · Archived
Snapshot 5836ef1d113d · 2026-10-17 08:22 UTC
Closed recordReview the archived record and cited scope
A person cannot download the latest coherent handheld image from GitHub without rebuilding it and manually reconstructing its provenance. Publishing a source-pinned development snapshot should be a repeatable local task with auditable assets.
image/releases: Downloadable development image snapshots with exact source and validation provenance.None.
Host tooling in tools/release-image.py, host tests, release documentation and GitHub Releases. Uses Git, pinned Nix, Python, xz and authenticated gh. No board access is needed; the published image’s physical acceptance remains separate.
See proposal.md. There is no existing task runner or release script; repository tasks are direct Python tools. The flake’s sdImage-coherent selects k230-coherent-shell with the normal vendor kernel; sdImage remains the old bar-session rollback. Work lands in host tooling and documentation, with no stage 1, kernel, device tree, Nix or userspace changes.
Goals: one manual command with separate stage and publish modes, pinned Git revision, outside-repo assets, and verification before and after upload.
Non-Goals: changing runtime boot selection, using mainline/SMP/RVV trial outputs, automatic releases or obtaining board proof.
git+file://<repo>?rev=<full-sha> with the committed lock; the task records source SHA independently from later documentation/tool commits.sdImage-coherent, system, kernel and device tree with outside-repo out-links so Nix registers GC roots. Stage xz image, JSON provenance, SHA256SUMS and Markdown notes under ~/tmp by default.--finish-draft can finish only the locally recorded transaction after complete verification, without re-uploading assets.python3 tests/test_release_image.py.python3 tools/release-image.py --help and openspec validate the-image-has-a-repeatable-github-release --strict.python3 tools/release-image.py stage --revision <full-master-sha> --directory ~/tmp/k230-release-<sha>; its recorded nix build <pinned-flake>#sdImage-coherent --max-jobs 1 --cores 8 proves host cross-build only.python3 tools/release-image.py publish --directory ~/tmp/k230-release-<sha>; commit release URL, sizes, hashes and actual limits in docs/evidence/image-releases/. This proves publication and downloaded-byte integrity, not QEMU or hardware boot.openspec validate the-image-has-a-repeatable-github-release --strict; archive and sync only after committed publication evidence and all above tasks are complete. Physical image acceptance is explicitly outside this change and remains open in the coherent boot-selection proposal.Let people download source-pinned development handheld images and inspect their checksums, system selection and actual validation limits.
The host release task SHALL build an explicit committed source revision using the pinned flake’s coherent Rust-shell image and normal vendor kernel. It SHALL publish a fresh GitHub prerelease with a compressed image, SHA256SUMS and machine-readable provenance identifying the source revision, image derivation, system and kernel. Artifacts SHALL remain outside Git.
Host publication evidence: docs/evidence/image-releases/2026-10-01/README.md; this does not establish physical image acceptance.
The host release task MUST reject dirty tracked source, staging inside the repository, source/provenance mismatches, and existing release or tag names for a fresh publication. Explicit continuation SHALL be permitted only for the locally recorded draft transaction with matching source, release ID and asset digests, and MUST NOT upload or replace assets. It SHALL retain GC roots through publication and verify uploaded asset sizes and SHA256 digests.
Archived change · Archived
Snapshot 5836ef1d113d · 2026-10-17 08:22 UTC
Closed recordVolume UI/backend accepted and archived; headphone listening remains open in audio task 5.6.
A person on this handheld has no on-screen way to see or change how loud
anything is. Volume can only move by editing an ALSA mixer control from a
console, and nothing on the panel shows the current level, which app is
making noise, or which output device is in use. the-brightness-control-is-a- slider gave the shade and Settings a shared Material-3 slider component for
brightness; the same review that asked for that
(docs/design/shell-polish-review-2026-09.md) compares this shell’s Quick
Settings surface to Android’s throughout, and Android’s own Quick Settings
shade puts a volume slider directly under the brightness one, plus a
key-triggered HUD for out-of-band changes. Nothing here plays that role yet.
Before this change, the image also does not run a sound server at all:
grep -rn pipewire nix/ finds one pipewireSupport = false in
nix/video-probe.nix (mpv’s own build) and nothing else. mpv talks to ALSA
directly (alsaSupport = true, pipewireSupport = false,
pulseSupport = false in that same file), which is fine for one process
owning the one Inno-codec ALSA device outright, but gives no place for a
shell-level volume control to live, no way to see per-app streams, and no
way to route to more than one output. This change adds PipeWire +
WirePlumber (nix/shell.nix, gated on k230.shell.coherentShell the same
as every other per-session daemon there) as plain system-level systemd
services running as the shell user — not the services.pipewire/
services.wireplumber NixOS modules, which wire into a systemd --user
instance this image never starts (no login manager, no session lingering;
Sway itself already runs as a plain system unit). mpv is not rebuilt; it
keeps talking to ALSA, and two installed ALSA plugin config files
(${pipewireLean}/share/alsa/alsa.conf.d/{50-pipewire,99-pipewire- default}.conf — pipewireLean, not the stock pkgs.pipewire; see below)
transparently redirect that ALSA traffic through PipeWire, so mpv’s own
output becomes an ordinary PipeWire stream node with no change to
nix/video-probe.nix at all. pipewireLean/wireplumberLean disable six
optional PipeWire backends (Bluetooth, Vulkan, X11, RAOP, ROC, mDNS) this
board’s volume UX never uses and this board has no onboard Bluetooth at
all (docs/research/bluetooth-onboard.md) — measured directly
(docs/evidence/volume/closure-size.md) to produce no net reduction
in this board’s actual whole-system closure for two independent, traced
reasons recorded there, kept anyway because every process this change
itself runs still uses the trimmed package (design.md Decision 9).
the-handheld-plays-through-its-speaker (open, not yet archived) adds a
system/audio capability describing the Inno codec’s default route and an
opt-in external-I2S switch for an optional MAX98357A amplifier; both are
board-side (kernel/device-tree) concerns, unaffected by this change. This
proposal adds its own system/audio requirements alongside that change’s,
for the PipeWire/WirePlumber layer and the shell surfaces built on it —
volume control, live-graph awareness, the HUD, and an output device picker.
nix/shell.nix
gains systemd.services.pipewire/wireplumber/pipewire-pulse, each a
plain system unit (User = "shell", XDG_RUNTIME_DIR=/run/shell),
bindsTo/partOf on shell.service the same way shell-notifications
and theme-helper already are. No security.rtkit.enable (module-rt
falls back to asking for RT scheduling directly and logs a warning
instead) — exactly the three processes the task asks for, nothing more.
Two ALSA plugin config files redirect mpv’s existing direct-ALSA output
through PipeWire without touching the mpv derivation.slider.rs’s existing Material-3 track/thumb painter
and touch-band machinery rather than forking it. slider.rs gained a
floor-parameterized form (clamp_percent_with_floor,
value_at_x_with_floor, Drag::start_with_floor) alongside its existing
brightness-only wrappers, so brightness’s 3%-floor behavior is unchanged
and the volume slider’s own floor is 0 (true silence is a reachable
value; muting is a separate flag — volume::VolumeState). A tap on the
speaker glyph toggles mute without disturbing the remembered level.volume::percent_to_linear/linear_to_percent implement the cubic taper
(linear = (percent/100)^3) Android’s own volume-curve tables approximate,
so equal slider steps read as roughly equal loudness steps. wpctl’s own
set-volume/get-volume were checked directly against this board’s dev
host (wpctl set-volume ID 0.58 produces a PipeWire channelVolumes of
0.195114; 0.58^3 = 0.195112), confirming wpctl itself already applies
this exact curve — this module’s own curve is for the shell’s live-drag
writes, which bypass wpctl for cost reasons (below), and must agree with
it or a drag and the following authoritative commit would visibly jump.pw-cli writer, not a process per change. A live
drag’s throttled writes (slider::live_write_due’s ~25/s cadence, reused
unchanged) go to one long-lived pw-cli child’s stdin
(pipewire_ipc::WriterHandle, a set-param <id> Props '{ "channelVolumes": [...] }' line per write, verified against a real PipeWire session:
pw-cli’s interactive/stdin command mode needs roughly one second after
connecting for its registry to sync before a set-param/info targeting
an existing id succeeds — pw-cli’s one-shot CLI-argument form waits out
that sync internally, but the persistent stdin form does not, which only
matters once at this shell’s own startup, not per write). A drag’s
release, a mute toggle, a hardware volume key and the device picker all
go through short-lived, human-percent wpctl set-volume ID <percent>%/
set-mute ID 0|1|toggle/set-default ID calls instead — rare,
user-paced events, not per-sample — mirroring the brightness slider’s own
“throttled direct write while dragging, one authoritative call on
release” split (docs/evidence/volume/ has the exact commands and
captured wpctl/pw-dump output this was checked against).pw-dump --monitor child (pipewire_ipc::spawn_monitor) is read
incrementally off its stdout pipe (serde_json’s own streaming
deserializer, already a pinned dependency — no new crate). pw-dump --monitor prints one full array at connect and, from then on, only the
objects that changed on each event (confirmed directly against upstream
pw-dump.c’s dump_objects(), and against a live capture: a wpctl set-volume/set-mute on this dev host’s own PipeWire session produced a
1-2 object array, never a full re-dump), and a removed object appears as
{"id": <id>, "info": null} rather than being omitted (also captured
directly). pipewire_ipc::Accumulator keeps one running graph across the
child’s whole life for exactly this reason — an earlier draft of this
parser treated every array as a complete snapshot and silently dropped
every sink/stream a given change did not itself touch.volume::Hud): a vertical pill on the
right edge, shown for any change this shell did not itself just make on
its own visible slider (volume::ChangeOrigin::raises_hud — a hardware
key or an external graph change raises it; the shade/Settings slider’s own
drag does not, since it is already its own visible feedback, mirroring the
brightness slider’s own toast suppression). Auto-hides after 2.5s
(volume::HUD_AUTO_HIDE_MS, the middle of the task’s “about 2-3s”), can be
dragged along the edge (Hud::start_drag/drag_to/end_drag, touch-id
owned the same way slider::Drag/Carousel/PanelClose already are),
and expands via a ”…” affordance to a per-stream list — one row per
PipeWire Stream/Output/Audio node, each with its own slider, app name
(application.name) and icon (application.icon-name, the real
PW_KEY_APP_ICON_NAME — checked directly against this machine’s
installed pipewire/keys.h, not the underscored spelling a first guess
might reach for) where resolvable, falling back to the node’s own name.bindsym
(XF86AudioRaiseVolume/LowerVolume/Mute) straight to wpctl, not
through a private signal to the Rust client — the client’s own graph
watcher picks up the resulting change exactly the same way it would pick
up any other external change, so hardware keys need no separate plumbing.
docs/research/board-capability-inventory.md documents no dedicated
volume buttons on the main board and no landed keymap for the optional
keyboard/nRF9151 base’s TCA8418 matrix that would emit these keysyms;
this remains a hook for a keyboard that does, not a claim this board’s own
keys exist.Audio/Sink: the Inno codec line-out always, and the
external-I2S route from the-handheld-plays-through-its-speaker if and
when that change’s kernel patch lands and WirePlumber exposes it as a
separate node/profile — modeled as an ordinary sink pick
(wpctl set-default ID), not a new Settings toggle, so the two changes
compose without either needing to know about the other’s UI. Whether the
external route in fact appears as a separate WirePlumber sink or only as
the ALSA-level “External I2S Output Switch” control that change adds is
still open and is recorded, not assumed, in docs/evidence/volume/.the-handheld-plays-through-its-speaker’s
own, still-open UNVERIFIED claim. The headphone listening task is retained in the audio proposal (5.6); the external route remains there too.theme_ui.rs, theme_carousel.rs,
theme_thumbnails.rs, theme_catalog.rs, appearance.rs) or the app
drawer (navigation.rs’s drawer paths, the drawer render, drawer_close_ drag_zone) — both owned by other concurrent work.pipewire-rs/native-protocol client and no security.rtkit.enable;
see design.md for why each was rejected.system/audio: this change’s own delta adds the PipeWire/WirePlumber
session layer and the shell-side volume UX built on it (slider, HUD,
device picker, live-graph awareness) as ADDED Requirements against this
not-yet-archived capability — the same posture
the-handheld-plays-through-its-speaker takes for its own, disjoint
Inno-codec/external-I2S requirements. Whichever of the two changes
archives first is the one that actually creates
openspec/specs/system/audio/spec.md; the other’s archive then lands as
an ordinary further ADDED Requirements delta against the now-existing
capability. Neither change modifies or removes a requirement the other
owns.The user delegated board self-verification and accepted closing the UI after the real sink/stream/HUD checks. docs/evidence/volume/closeout-2026-10-01/README.md records 15 physical-board assertions using injected contacts, actual PipeWire/ALSA state and native captures; these are not new human-finger or listening observations. The independent HUD and hardware Device Route fixes supersede earlier implementation limitations. The user explicitly moved the unperformed headphone/line-out listening test into the-handheld-plays-through-its-speaker, task 5.6. No audible output, absent external add-on or physical audio-key result is claimed.
Userspace: NixOS session services (nix/shell.nix) plus the Rust shell
client (nix/rust-shell-client) and its two new PipeWire-facing child
processes. No kernel, device tree, or Nix module outside nix/shell.nix
changes; the audio hardware/device-tree layer is
the-handheld-plays-through-its-speaker’s, untouched here.
services.pipewire/wireplumber NixOS modulesThose modules wire pipewire.socket/pipewire.service/wireplumber. service/pipewire-pulse.{socket,service} into systemd.user.services,
which needs a systemd --user instance for shell to actually run. That
instance is normally started by pam_systemd on login or by lingering
(loginctl enable-linger); this image has neither — there is no login
manager, every getty on tty1 is masked (nix/shell.nix’s own comment on
systemd.services."getty@tty1"), and Sway itself already runs as a plain
system unit with User = "shell", not through a user session. Rather than
add lingering (systemd.tmpfiles.rules touching /var/lib/systemd/linger/ shell) purely to make one NixOS module’s chosen wiring work, three plain
system services (pipewire, wireplumber, pipewire-pulse), each User = "shell", bindsTo/partOf/after = [ "shell.service" ], match every
other per-session daemon already in this file (shell-notifications,
theme-helper, shell-session-bus) and need nothing from systemd- logind at all. The only other thing that module would have added —
the two ALSA plugin files redirecting plain ALSA clients through PipeWire
— are installed the same way it installs them
(${pkgs.pipewire}/share/alsa/alsa.conf.d/{50-pipewire,99-pipewire- default}.conf), by hand.
Rejected: security.rtkit.enable. pipewire’s module-rt asks for
realtime scheduling directly and falls back to logging a warning if
refused (harmless on a single-user board with no other realtime
contention); adding a fourth daemon purely for a priority bump contradicts
the task’s own “no extra daemons beyond pipewire, wireplumber and
pipewire-pulse.”
pw-cli/wpctl child processes, not pipewire-rs or a hand-rolled native clientsway_ipc.rs hand-rolls Sway’s own IPC framing because that wire format is
small, stable and documented (sway-ipc(7)). PipeWire’s native protocol is
a much larger binary RPC (fds, SPA pods, an object/permission model) with
no equivalently small stable spec to hand-roll, and Cargo.toml pins a
short, deliberately narrow dependency list (no libspa/libpipewire FFI
binding already vetted for this repo’s riscv64 cross toolchain). pw-dump,
pw-cli and wpctl are already present the moment services.pipewire-
equivalent config ships (they are the same pkgs.pipewire/pkgs. wireplumber outputs the systemd units above already pull in), so this
reuses binaries the system already needs, at the cost of one JSON/text
parsing layer instead of an FFI binding. This was checked, not assumed to
cross-compile: pipewire-riscv64-unknown-linux-gnu-1.6.8 is already built
and cached on the shared build host from unrelated prior work on this
machine, so the cross-compilation risk this design accepts is not
hypothetical — it is already known to succeed at this exact pin.
Cost: two long-lived children, not one process per change. pw-dump --monitor sits blocked in a read() and only wakes when the graph
actually changes — confirmed directly (a 3-second idle capture on a real
desktop PipeWire session produced no output past the initial dump; a
wpctl set-volume/set-mute during a second capture produced exactly one
small array per change). The persistent pw-cli writer sits blocked
waiting on its stdin pipe and only wakes when this shell sends it a
line. Both are far cheaper than spawning wpctl set-volume per drag
sample: a fresh wpctl process pays dynamic linking, a new PipeWire
client connection/handshake and process teardown on every sample, all
avoided here. Reading the graph is genuinely free of polling: the reader
thread’s own read() call is the only wait, and it wakes exactly when
PipeWire has something to say, never on a timer. The one caveat found
directly, not assumed: pw-cli’s interactive (piped-stdin) command mode
needs on the order of one second after connecting for its own registry to
sync before a set-param/info against an existing global id succeeds
(its one-shot CLI-argument form waits out this sync internally; the
persistent stdin form does not). This only matters once, at this shell’s
own startup — by the time a person’s first drag can possibly happen, the
writer has been alive far longer than that.
Rejected: pipewire-rs. Not vetted for this cross toolchain, and its own
dependency surface (bindgen against libpipewire/libspa C headers) is a
larger, riskier addition than two already-present CLI tools for a shell
this narrow in scope. Revisit if a future change needs finer-grained
native events this text/JSON interface cannot express.
--monitor array as a complete snapshotRead directly from PipeWire’s own pw-dump.c (dump_objects()): every
dump, including each one --monitor prints after the first, walks the
entire known object list but skips any object whose internal changed
counter is zero. In monitor mode this means each printed array holds only
what changed since the previous one, confirmed against a live capture (a
single wpctl set-volume produced a two-object array: the changed sink
plus an unrelated ALSA device renegotiation event that happened to land in
the same event). pipewire_ipc::Accumulator keeps one running map across
the monitor child’s entire lifetime for exactly this reason. An earlier
version of this parser applied each array against fresh, empty state,
which silently dropped every sink and stream a given change did not
itself touch — one node’s volume changing made every other node vanish
from the shown state on that update. This is the load-bearing reason the
read side is stateful; it is not incidental accumulation.
Removal has its own shape, also checked directly: an object that
disappears from the graph is reported as {"id": <id>, "info": null},
not by omission (omission means “unchanged”). Captured live: a wpctl
invocation’s own transient PipeWire client connect/disconnect produced
exactly this shape for its Client object.
Android’s AudioService volume-curve tables approximate a cubic taper
rather than a linear gain, because loudness perception is roughly
logarithmic and a linear fader puts most of the audible change in the
bottom quarter of the track. volume::percent_to_linear
(linear = (percent/100)^3) reproduces that shape. This was checked
against wpctl itself, not assumed to match it: on a real desktop
PipeWire session, wpctl set-volume ID 0.58 (and separately 0.57)
produced a channelVolumes of 0.195114 (0.42, 57, 42 produced
equally exact cubes) — wpctl’s own VOL[%] argument is already this
same cubic-perceptual value, not a raw linear gain, which is why the
authoritative commit path (release, mute, hardware keys, device picker)
can hand wpctl a plain percent and rely on it to apply the identical
curve, while the throttled live-drag path (writing raw channelVolumes
directly, for cost reasons — Decision 2) must compute
percent_to_linear itself so the two paths never visibly disagree at the
handoff between a drag and its own release.
muted flag, not “volume clamped to zero”Mirrors Android’s own panel: dragging the slider to its very bottom (0)
sets VolumeState::muted and keeps the last non-zero level remembered,
so tapping the speaker glyph to unmute restores exactly that level, never
a default. An external report of 0 (someone else silenced the sink) is
treated the same way, so a genuinely-silent external sink shows as muted
here too, not as a zero-but-unmuted slider a person would then have to
drag back up from nothing. This is the reason VolumeState is not simply
a u8 percent: brightness’s own slider has no equivalent need (a real
sysfs read is always shown as-is with no separate mute concept), but
volume’s Android-parity requirement does.
Mirrors the brightness slider’s own toast suppression
(main.rs::suppresses_action_message, commit “Suppress the brightness
slider’s own success toast”): a gesture already on screen (dragging the
shade’s or Settings’ own slider) needs no second surface telling the
person what they can already see happening. volume::ChangeOrigin
enumerates exactly the origins this shell can distinguish
(OwnSlider/HardwareKey/ExternalGraph) and raises_hud() is the one
place that decision lives, so main.rs never re-derives it ad hoc at each
call site.
Known, still-open gap (tasks.md 4.3): the HUD’s own visibility
state and touch dispatch are fully route-independent, but the surface it
paints onto today is not — render.rs’s draw_with_hud only runs while
the overlay layer (Drawer/Shade/Settings) is already mapped. A hardware
key pressed with nothing open updates the graph/slider state correctly but
shows no HUD until some sheet happens to be open. Closing this needs the
overlay layer to map itself purely because the HUD wants to show,
regardless of route — left as a named follow-up, not solved here.
wpctl, not through a private signal to the Rust clientSway’s own bindsym XF86AudioRaiseVolume/LowerVolume/Mute each exec a
wpctl set-volume/set-mute call directly. No new socket, IPC message or
signal from Sway to the Rust client exists or is needed: the client’s own
pw-dump --monitor reader (Decision 2/3) observes the resulting Props
change exactly the way it would observe any other external app’s change,
and ChangeOrigin::ExternalGraph (Decision 6) raises the HUD from that one
code path. A hardware key is, from this shell’s point of view, simply
another external graph change with a very short causal chain.
Rejected: a dedicated k230-volume-key helper that both changes the
volume and signals the shell directly (e.g. over SWAYSOCK or a new
Unix socket). This would duplicate the exact update path the graph
watcher already provides, for no benefit — the graph watcher’s own
latency (an OS-scheduled wake on the monitor child’s pipe becoming
readable) is not meaningfully slower than a purpose-built signal would be,
and a second path is a second thing that can disagree with the graph.
Whether the-handheld-plays-through-its-speaker’s external-I2S switch
ever surfaces as its own WirePlumber node/profile (as opposed to only an
ALSA-level “External I2S Output Switch” mixer control with no separate
PipeWire-visible sink) is that change’s own open question, not decided
here. This change’s device picker only ever lists whatever Audio/Sink
nodes WirePlumber actually exposes and calls wpctl set-default ID on the
one a person picks — it adds no separate Settings toggle for the
external route, so the two changes compose regardless of which way that
question resolves. If the external route never becomes a separate sink,
the picker simply never shows a second entry, and that mixer switch stays
the-handheld-plays-through-its-speaker’s own Settings-toggle decision to
make, not something this change should pre-empt.
pipewire.override, not the stock nixpkgs packageMeasured directly (docs/evidence/volume/closure-size.md — via
nix-store -q --size summed over a nix-store -qR closure listing; that
file also records why nix path-info -rS reported grossly wrong per-path
sizes on this specific store and should not be trusted here): nixpkgs’
stock pipewire package cross-compiled for this board builds with every
optional backend on — Bluetooth (bluez plus its LC3/LDAC/aptX codec
libraries), Vulkan, X11 (which also pulls in libcanberra/libmysofa),
RAOP/AirPlay, ROC network streaming, and mDNS/Avahi discovery — and its
own package closure is about 0.44 GiB on this toolchain. None of that is
used by this board’s volume UX (ALSA line-out plus the PulseAudio-compat
shim for mpv), and this board has no onboard Bluetooth at all
(docs/research/bluetooth-onboard.md), so a Bluetooth-capable audio server
would be actively misleading about what this hardware can do, not merely
wasteful. nix/shell.nix’s own pipewireLean binding disables the six
backends nixpkgs exposes as plain override booleans
(bluezSupport/vulkanSupport/x11Support/raopSupport/rocSupport/
zeroconfSupport), and wireplumberLean = pkgs.wireplumber.override { pipewire = pipewireLean; } (WirePlumber links against PipeWire
directly, so it needed the same override, not just the systemd units’
own ExecStart/PATH references) — the same “measure a real cost, then
cut what this board doesn’t use” reasoning swayBase’s own
Xwayland-disabled override already established in this file.
Measured just as directly: this override pair produces no net reduction
in this board’s actual whole-system closure. Three full toplevel builds
(docs/evidence/volume/closure-size.md) traced why: bluez and the other
disabled backends’ own dependencies are already reachable from elsewhere in
this image regardless of pipewire (hardware.bluetooth.enable = true,
landed separately by the-handheld-talks-bluetooth, most directly), and a
NixOS-internal ALSA-plugins aggregate this repo’s own nix files do not
build or control still pulls in the stock, untrimmed pipewire package
independent of what pipewireLean/wireplumberLean or any service unit
here actually run — confirmed by finding the stock package still present,
referenced from an all-plugins derivation, in the final closure. Kept
anyway: every process this change itself spawns (the three systemd units,
and the persistent pw-cli/pw-dump children pipewire_ipc.rs spawns)
genuinely runs the trimmed package, which stays the architecturally correct
and more honest choice (a board with no onboard Bluetooth should not run a
Bluetooth-capable sound server, whatever a different, out-of-scope NixOS
aggregation mechanism does elsewhere in the same image) even though the
board-wide closure number did not move. Fully closing that remaining gap
is a named, open follow-up (docs/evidence/volume/closure-size.md’s own
last section), not something this change claims to have solved.
Separately not eliminated: ffmpeg/gstreamer support and the docs/
installed_tests outputs. Nixpkgs 1.6.8’s own package.nix hardcodes
(lib.mesonEnable "ffmpeg" true)/(lib.mesonEnable "gstreamer" true) in
its mesonFlags list rather than exposing them as override parameters, and
ffmpeg-headless/gst_all_1.gstreamer are unconditional (not
lib.optional-gated) build inputs — trimming them means forking the
derivation’s own mesonFlags/buildInputs construction, not a supported
override, and was judged not worth that fragility (a nixpkgs version bump
could silently re-widen or break a hand-patched flags list with no build
failure to notice it).
shell user’s own group membership, and absolute-path env vars, not PATH aloneBoard evidence (docs/evidence/volume/board/pipewire-services-active.md)
found two gaps a host build/QEMU capture could never have caught: /dev/ snd/* ships root:audio 0660, so WirePlumber’s ALSA monitor could not
open the real card without shell being in the audio group (fixed via
users.users.shell.extraGroups, not a per-unit SupplementaryGroups,
since every PipeWire-adjacent process here already runs as that user); and
wpctl was unreachable from the running client despite the unit’s own
generated PATH already including it (path = [...] alone was not
sufficient in practice, for a reason this change could not fully pin down
remotely). K230_WPCTL/K230_PW_DUMP/K230_PW_CLI environment variables
passing absolute store paths — the same convention K230_SETTINGS/
K230_SWAYMSG already use — are now the authoritative, PATH-independent
way main.rs finds these three binaries; path stays only as a fallback.
Also added: DBUS_SESSION_BUS_ADDRESS on all three PipeWire units,
connected to the existing shell-session-bus, so module-rt’s own
“cannot reach a session bus” warning becomes a real (still harmless,
still-no-RTKit) bus round trip instead of no bus at all.
The user delegated board self-verification and accepted closing the UI after the real sink/stream/HUD checks. docs/evidence/volume/closeout-2026-10-01/README.md records 15 physical-board assertions using injected contacts, actual PipeWire/ALSA state and native captures; these are not new human-finger or listening observations. The independent HUD and hardware Device Route fixes supersede earlier implementation limitations. The user explicitly moved the unperformed headphone/line-out listening test into the-handheld-plays-through-its-speaker, task 5.6. No audible output, absent external add-on or physical audio-key result is claimed.
All tasks below name the narrowest real command that proves them. Host
build and QEMU capture are one evidence class; a console transcript, an
audible check, or a real-finger/real-key observation from the physical
board is a different one, and no task here claims the second from the
first. Board evidence, once it exists, is stored under
docs/evidence/volume/board/ with commands, timestamps and limits; the
host/QEMU evidence already produced by this worktree lives at
docs/evidence/volume/.
systemd.services.pipewire/wireplumber/pipewire-pulse
to nix/shell.nix (k230.shell.coherentShell-gated, plain system
units with User = "shell", bound to shell.service’s lifecycle),
and the two ALSA plugin config files that redirect mpv’s existing
direct-ALSA output through PipeWire without rebuilding mpv. Proven:
nix build .#nixosConfigurations.k230-coherent-shell.config.system. build.toplevel --max-jobs 1 --cores 6 --no-link --print-out-paths
(task 7.2) includes these units in the closure.XF86AudioRaiseVolume/LowerVolume/Mute) to the generated Sway
config, calling wpctl directly with no separate signal to the
Rust client. Proven: same closure build; docs/research/board- capability-inventory.md cited for what this board’s own inputs are
known (and not known) to emit.pipewire’s own closure: nix/shell.nix’s pipewireLean
override disables bluezSupport/vulkanSupport/x11Support/
raopSupport/rocSupport/zeroconfSupport (design.md Decision 9)
— this board has no onboard Bluetooth
(docs/research/bluetooth-onboard.md) and none of the other four
backends are used by this board’s volume UX. ffmpeg/gstreamer
support stay on (nixpkgs 1.6.8 hardcodes both, not exposed as
override parameters); the remaining cost is recorded, not hidden,
in docs/evidence/volume/closure-size.md. Proven: task 6.4’s
second toplevel build (with the override) succeeds and that
evidence file’s own before/after numbers.docs/evidence/volume/closeout-2026-10-01/README.md and result.json. shell, seatd, PipeWire, WirePlumber and pipewire-pulse are active; this supersedes the earlier Dummy Output diagnosis.slider.rs’s brightness-only floor into
clamp_percent_with_floor/value_at_x_with_floor/Drag:: start_with_floor, keeping the existing MIN_PERCENT-floor
wrappers unchanged for brightness’s own call sites. Proven:
cargo test --lib (slider::tests::*, including the brightness-
floor-equivalence and volume-floor-reaches-zero cases).volume.rs: the cubic percent<->linear curve
(percent_to_linear/linear_to_percent/percent_to_db),
VolumeState (level + separate mute flag, drag-to-mute, icon-tap
mute toggle, external-report reconciliation), IconState,
ChangeOrigin, and Hud (visibility timing, expand/collapse,
draggable position). Proven: cargo test --lib (volume::tests::*,
27 tests covering the curve, mute semantics, HUD timing/expand/
drag).pipewire_ipc.rs: parse_dump/Accumulator (a running
graph model that survives per-change deltas without losing
untouched sinks/streams), spawn_monitor/run_monitor_reader (the
persistent pw-dump --monitor reader thread), and Writer/
WriterHandle (the persistent pw-cli writer child plus its
command queue) and set_volume_command. Proven: cargo test --lib
(pipewire_ipc::tests::*, including a real child-process round
trip for the writer and fixture-replay tests against captured JSON
shapes).pw-dump/pw-dump --monitor/wpctl output on a
development host’s own PipeWire session (not this board) to ground
the parser’s object schema and the cubic-curve claim, and record it
in docs/evidence/volume/wpctl.md and the fixtures under
tests/fixtures/pipewire/. Proven: the recorded captures plus the
application.icon-name (not -icon_name) key confirmed directly
against this machine’s installed pipewire/keys.h
(PW_KEY_APP_ICON_NAME).service_ui.rs
(slider_band’s existing Settings-row/Shade-header convention,
shifted for the added row) and fold it into
shade_panel_close_zone’s existing carve-out, so a horizontal drag
on the volume slider is never promoted into a close drag, matching
the brightness slider’s own guarantee. Proven: cargo test --lib
(volume_slider_band_owns_its_row_and_is_excluded_from_the_close_ drag_candidacy, alongside the pre-existing brightness case).main.rs’s touch
handlers (a sibling branch beside the existing brightness-slider
arm), wire the speaker-glyph mute tap (own touch-id-owned zone, so
a tap on the icon can never be read as a drag to 0) and the HUD’s
own show/hide/expand/drag touch handling, plus a VOLUME_ECHO_ GRACE_MS window so this shell’s own wpctl commits (mute tap,
device pick) are never mistaken for an external change and do not
spuriously raise the HUD. Proven: cargo test --lib (whole crate,
283 passed / 0 failed) and cargo clippy --lib/--all-targets
report no warning attributable to main.rs/service_ui.rs/
render.rs/service_data.rs/slider.rs/volume.rs/
pipewire_ipc.rs (the two pre-existing warnings --all-targets
surfaces, in main.rs::running_con_id and the unrelated,
already-broken tests/theme_catalog_module.rs integration test,
are confirmed pre-existing on master by a stash-and-rebuild
check, not introduced here, and are out of this change’s owned
paths).paint_slider_track, a mute-aware
speaker glyph in place of the sun glyph), and paint the HUD
(collapsed pill, expanded per-stream/sink list with a default-sink
marker dot) via render.rs’s shared RendererCache:: paint_hud_overlay (task: “render the HUD only while visible” — an
early return before any Cairo work when !hud.is_visible), reached
two ways: draw_hud (its own isolated canvas, used by that
function’s own unit tests) and draw_with_hud (composited directly
onto draw()’s live canvas — the one main.rs actually attaches
to a Wayland surface; draw() itself stays a thin wrapper calling
draw_with_hud with a never-shown Hud::default(), so none of
this module’s other ~45 pre-existing renderer.draw(...) call
sites needed touching). First QEMU capture attempt
(tests/volume_hud_qemu.py) found draw_hud was written but never
actually called from main.rs at all — the HUD state machine and
touch dispatch were real and tested, but nothing painted it onto
the surface a person would actually see; draw_with_hud/the
main.rs wiring above is that fix, not a pre-existing feature.
Proven: cargo test --lib (render::tests::draw_hud_* plus the
new draw_with_hud_composites_the_pill_on_top_of_the_live_settings_ scene, which specifically catches a regression back to “painted
but never reaches the live canvas”).
Historical gap, resolved by task 10.1 and the committed 2026-10-01 board proof: draw_with_hud only paints while the
overlay layer surface is already mapped (a Drawer/Shade/Settings
sheet open) — main.rs’s touch dispatch (hud_touch_down) is
already fully route-independent, but nothing yet forces this layer
surface to exist purely because the HUD wants to show while the
Home screen alone is visible with nothing else open (render.rs’s
own doc comment on draw() names this precisely). A hardware
volume key pressed with nothing open would today update service_ view.audio/the Settings-row slider correctly but show no HUD until
some other route happens to open. Left open rather than
papered over; the QEMU capture below exercises the case that does
work (shade open) since that is what could actually be proven
inside this remaining budget.main.rs’s own event
loop: pipewire_events/pipewire_writer are spawned once at
startup (pipewire_ipc::spawn_monitor/WriterHandle::spawn) and
drained via try_recv on the loop’s own existing wake cadence
(the same opportunistic-drain convention services/wifi_worker/
themes already use — no dedicated polling thread or timer of
its own). Proven: cargo test --lib (apply_pipewire_event’s own
HUD-suppression logic exercised indirectly via volume::Hud/
ChangeOrigin unit tests; the process-spawning half is exercised
by pipewire_ipc’s own real-child-process tests).service_ui::settings_output_ picker_hit) expands the same HUD panel tap_hud_row’s sink rows
already drive, rather than a second, duplicate list (design.md’s
“one picker, two entry points”). Proven: cargo test --lib
(settings_output_picker_hit_is_settings_only_and_needs_a_default_ sink).pipewire_ipc::GraphSnapshot::sinks in the expanded HUD
panel (paint_hud_row’s ExpandedRow::Sink arm: description text
plus a filled/hollow default-marker dot) and reach the same panel
from Settings (task 4.5), calling wpctl set-default ID on a pick
(main.rs::pick_output_sink). Proven: cargo test --lib
(draw_hud_expanded_panel_is_taller_and_wider_than_the_collapsed_ pill exercises a sink row’s own paint path; tap_hud_row’s sink
branch is a direct, small function reachable from the same tests
that cover its stream-row sibling).cargo test for nix/rust-shell-client: --lib (284 passed /
0 failed), plus appearance_module/background_decode_module/
service_data_module (21 + 8 + 11 passed / 0 failed) — run in
the foreground. tests/theme_catalog_module.rs fails to compile
on this branch and on unmodified master (a stash-and-rebuild
check confirmed this before touching anything) — pre-existing
breakage in a file this change does not own or touch, not a
regression from this work.cargo clippy --lib and cargo clippy --all-targets report no
warning attributable to this change’s files (see 4.2’s own note on
the two pre-existing warnings --all-targets surfaces elsewhere).
One real regression this change itself introduced was caught and
fixed here: adding SettingsSnapshot::volume pushed ServiceResponse
over clippy’s large_enum_variant threshold; Settings is now
Box<SettingsSnapshot> (service_data.rs), with its two call
sites updated.nix build .#handheld-shell-rust --max-jobs 1 --cores 6 --print-out-paths — run in the foreground three times across this
work (mid-work, after the closure-trimming override, and against
the final staged source including the draw_with_hud fix): final
store path /nix/store/7imslxpfxnam1zwmcvfng048hwl3z7a1-k230-shell- rust-riscv64-unknown-linux-gnu-0.1.0.nix build .#nixosConfigurations.k230-coherent-shell.config. system.build.toplevel --max-jobs 1 --cores 6 --no-link --print-out-paths — run in the foreground four times: three
across the pipewireLean/wireplumberLean closure-trimming work
(design.md Decision 9: /nix/store/gwl36r94h1vjh0038d0nm3c7ikzlgl6m-...
untrimmed, /nix/store/qcd1vqsip5ha0cdv3ag30qc8j7laxjzs-...
pipewire trimmed only, /nix/store/2yhpy7fg6l5hl0dij41si99xfw0 spyj5-... both trimmed) and a fourth, final run against the fully
staged source including the draw_with_hud live-canvas fix (task
4.3): /nix/store/s32hb4i8mfm15w7bacskjyr8spk3bgcs-nixos-system- nixos-26.11.20260919.20b1ddd. docs/evidence/volume/closure- size.md has the full, honest closure-size result from the first
three: the override is correct (every unit/process this change
spawns runs the trimmed package) but produced no net closure-size
reduction, for two independent, traced reasons recorded there (a
pre-existing hardware.bluetooth.enable=true already keeping
bluez/etc. reachable regardless, and a NixOS-internal ALSA-
plugins aggregate this change does not control still pulling in the
stock pipewire) — left as a named, open follow-up rather than
claimed solved.tests/volume_hud_qemu.py (a narrow, purpose-built extension of
rust_service_surface_qemu.py’s own harness, importing its
Broker/SETTINGS_FIXTURE/wait_for rather than duplicating them)
captures: the shade with both the brightness and volume sliders
(shade-both-sliders.png), the HUD raised by a synthetic external
PipeWire change and shown collapsed (hud-collapsed.png), and the
HUD expanded to its per-stream/per-sink device-picker panel
(hud-expanded.png). Screenshots and blob-inventory rows committed
under docs/evidence/volume/ (README.md has the full narrative,
including the real draw_with_hud wiring gap this capture attempt
itself found and task 4.3 above then fixed). python3 tools/ blob-scan.py --no-vendor exits 0.openspec validate --strict the-handheld-controls-volume and
python3 scripts/render_work_board.py > /dev/null both re-run
after task 7.1’s evidence landed: both exit 0. Rerun once more
before archiving, in case anything lands between now and then.docs/evidence/volume/closeout-2026-10-01/. On 2026-10-01 the user explicitly authorized moving the unperformed headphone listening test to the existing audio proposal, task 5.6. This is a scope transfer, not audible acceptance.9.1 User-delegated board self-verification passed Settings/Shade held live drag, zero-mute and remembered-level icon toggles against the hardware mixer. Evidence explicitly distinguishes injected contacts from a new human-finger test.
9.2 MOVED, not performed: the user authorized preserving the full line-out/headphone listening test in the-handheld-plays-through-its-speaker, task 5.6, before archiving the verified volume UI. Audibility remains UNVERIFIED.
9.3 Not applicable: the user explicitly has no external audio add-on. The separate speaker/audio proposal stays open and no external-I2S audibility or separate sink is claimed.
9.4 Not applicable: no attached keyboard emitting XF86AudioRaiseVolume/LowerVolume/Mute is confirmed. Generated bindings remain host/build-verified; no physical key press is invented.
9.5 Physical-board popup proof passes above Home and a mapped Foot app, held-contact behavior, auto-hide, repositioning, real named stream slider/mute and actual sink selection. Correct metadata is shown with generic icon fallback; the native-capture elapsed wait is not treated as precise timer measurement. See the same closeout report.
Define the PipeWire/WirePlumber session layer this shell runs, and the
volume control, live-graph awareness, HUD and output-device-picker surfaces
built on it. Disjoint from the-handheld-plays-through-its-speaker’s own
Inno-codec/external-I2S-route requirements for the same system/audio
capability; see that change for the board’s ALSA/kernel-level audio path.
Grounding: docs/evidence/volume/closeout-2026-10-01/README.md and result.json: installed physical-board UI/backend verification using injected contacts, real sink/stream state and native captures. Headphone audibility is retained as UNVERIFIED audio task 5.6; no new human-finger test is claimed.
Host build proof: nix build .#handheld-shell-rust and the full
k230-coherent-shell system closure cross-build succeed with
systemd.services.pipewire/wireplumber/pipewire-pulse present in the
closure. Host/build proof only — whether these units actually reach
active on the board is a separate, open task (see tasks.md); no task here
claims that from a host build.
When k230.shell.coherentShell is enabled, the system SHALL run pipewire,
wireplumber and pipewire-pulse as plain systemd system services under
the shell user, bound to shell.service’s own lifecycle, and SHALL
install the PipeWire ALSA-compat plugin files so an existing plain-ALSA
client (mpv, unchanged) is transparently redirected through PipeWire. No
additional daemon beyond these three SHALL be added for this purpose.
Grounding: nix/shell.nix’s systemd.services.pipewire/wireplumber/
pipewire-pulse, each bindsTo/partOf/after = [ "shell.service" ],
User = "shell"; environment.etc."alsa/conf.d/{50-pipewire,99-pipewire- default}.conf" sourced from ${pkgs.pipewire}/share/alsa/alsa.conf.d/.
Design.md Decision 1 records why the services.pipewire/wireplumber
NixOS modules were not used instead.
k230.shell.coherentShell is enabled and the system closure is builtpipewire, wireplumber, pipewire-pulse and their two ALSA plugin config files, wired to start with the shell sessionGrounding: docs/evidence/volume/closeout-2026-10-01/README.md and result.json: installed physical-board UI/backend verification using injected contacts, real sink/stream state and native captures. Headphone audibility is retained as UNVERIFIED audio task 5.6; no new human-finger test is claimed.
Host build proof: cargo test/cargo clippy --all-targets for
nix/rust-shell-client pass; slider.rs’s floor-parameterized functions
(clamp_percent_with_floor, value_at_x_with_floor,
Drag::start_with_floor) and volume.rs’s own unit tests cover the mapping,
clamping and drag-to-mute behavior below. These are host/build proofs only;
see the open real-finger task for physical acceptance.
The Settings screen and the pull-down shade SHALL each present a volume
control directly under the existing brightness slider, using the same
shared Material-3-style track/thumb component (slider.rs) rather than a
forked copy. Unlike brightness, the volume slider’s floor SHALL be 0
(true silence is a reachable value); a drag to the very bottom SHALL engage
mute, and a drag anywhere above 0 SHALL clear mute and set the level,
matching Android’s own slider. A tap on the leading speaker glyph SHALL
toggle mute without changing the remembered level, so unmuting restores the
level active before the mute.
Grounding: nix/rust-shell-client/src/slider.rs’s MIN_PERCENT-vs-floor
split (Decision unchanged from the-brightness-control-is-a-slider, only
generalized); volume::VolumeState::{set_from_drag,toggle_mute, displayed_percent}.
wpctl itselfGrounding: docs/evidence/volume/closeout-2026-10-01/README.md and result.json: installed physical-board UI/backend verification using injected contacts, real sink/stream state and native captures. Headphone audibility is retained as UNVERIFIED audio task 5.6; no new human-finger test is claimed.
Host build proof: volume::tests::percent_to_linear_is_cubic_not_linear
and linear_to_percent_round_trips_percent_to_linear (unit tests only);
docs/evidence/volume/wpctl.md records the live wpctl/pw-dump capture
this curve was checked against on a development host (not this board).
A UI slider percent SHALL map to a linear PipeWire volume amplitude through
linear = (percent/100)^3 (and the exact inverse when reading a linear
value back to a percent for display), not a straight linear map. This SHALL
hold both for this shell’s own throttled live-drag writes (which set
channelVolumes directly and so must compute this curve themselves) and be
consistent with wpctl set-volume’s own percent argument, which already
applies the same curve internally.
Grounding: volume::percent_to_linear/linear_to_percent;
docs/evidence/volume/wpctl.md’s captured wpctl set-volume ID 0.58 ->
channelVolumes: [0.195114, 0.195114] (0.58^3 = 0.195112), and a second,
independent data point at 0.57/0.185185.
Grounding: docs/evidence/volume/closeout-2026-10-01/README.md and result.json: installed physical-board UI/backend verification using injected contacts, real sink/stream state and native captures. Headphone audibility is retained as UNVERIFIED audio task 5.6; no new human-finger test is claimed.
Host build proof: pipewire_ipc::tests::writer_handle_delivers_commands_ in_order_to_a_real_child_process spawns a real child process (a test
double, not pw-cli itself) and confirms ordered delivery over a real
pipe; set_volume_command_formats_a_scriptable_pw_cli_line covers the
exact command text. Host/build proof only.
While a volume slider drag is in progress, the system SHALL send writes at
roughly the same throttled cadence the brightness slider already uses
(slider::LIVE_WRITE_INTERVAL_MS), each written to one already-running
pw-cli child process’s stdin (no process spawned per write), never
blocking the Wayland/UI thread. The drag’s release SHALL always send one
additional, authoritative wpctl set-volume ID <percent>% call regardless
of the live-write throttle’s own timing, so the committed value is always
the one wpctl itself computed and PipeWire/WirePlumber actually holds.
Grounding: pipewire_ipc::{Writer,WriterHandle,set_volume_command};
design.md Decision 2’s cost accounting and Decision 4’s curve-agreement
reasoning.
pw-cli process at roughly the brightness slider’s own throttled rate, and no new process is spawned per writewpctl set-volume callGrounding: docs/evidence/volume/closeout-2026-10-01/README.md and result.json: installed physical-board UI/backend verification using injected contacts, real sink/stream state and native captures. Headphone audibility is retained as UNVERIFIED audio task 5.6; no new human-finger test is claimed.
Host build proof: pipewire_ipc::tests::a_delta_that_only_touches_one_ node_does_not_wipe_the_others, a_removal_delta_drops_only_the_named_ object, and the fixture-replay tests against tests/fixtures/pipewire/*
(captured-shape JSON, not live board output) all pass. Host/build proof
only — see the open task for whether this board’s own WirePlumber
actually names its sinks/streams the way these fixtures assume.
The system SHALL run one persistent pw-dump --monitor process for the
life of the shell session and apply every array it prints — the initial
full dump and every subsequent per-change delta — onto one running graph
model, never discarding a sink or stream a given delta did not itself
mention. An object reported as {"id": <id>, "info": null} SHALL be
removed from that model. The shade’s and Settings’ own sliders, the HUD,
and the expanded per-stream panel SHALL all reflect this same running
model, so an external app, wpctl from a console, or a hardware key
changing the default sink’s volume or mute state is shown without polling.
Grounding: pipewire_ipc::{spawn_monitor,run_monitor_reader,Accumulator};
design.md Decision 3, citing upstream pw-dump.c’s dump_objects()
directly and a live capture of the exact array shapes involved.
Grounding: docs/evidence/volume/closeout-2026-10-01/README.md and result.json: installed physical-board UI/backend verification using injected contacts, real sink/stream state and native captures. Headphone audibility is retained as UNVERIFIED audio task 5.6; no new human-finger test is claimed.
Host build proof: volume::tests::hud_is_hidden_until_shown_and_ autohides_after_its_window, hud_toggle_expand_flips_state_and_refreshes_ the_timer, hud_drag_is_owned_by_the_touch_that_started_it, and
change_origin_only_the_own_slider_suppresses_the_hud all pass.
QEMU capture: docs/evidence/volume/ shows the HUD collapsed and expanded.
Host/QEMU proof only — see the open real-finger and hardware-volume-key
tasks.
A hardware/keyboard volume key or any external PipeWire graph change to the
default sink’s volume/mute SHALL raise a vertical pill HUD on the panel’s
right edge; a drag on the shade’s or Settings’ own volume slider SHALL
NOT, since that slider is already its own visible feedback (mirroring the
brightness slider’s own commit-toast suppression). The HUD SHALL auto-hide
about 2.5 seconds after its last change, SHALL be draggable along the
edge, and SHALL expand via a ”…” affordance into a per-stream list: one row
per PipeWire Stream/Output/Audio node, each with its own slider, and the
app’s name and icon where application.name/application.icon-name are
present, falling back to the node’s own name.
Grounding: volume::{Hud,ChangeOrigin,HUD_AUTO_HIDE_MS};
pipewire_ipc::GraphSnapshot::streams supplies the expanded panel’s rows.
Host build proof: the Sway config fragment is part of the
k230-coherent-shell closure build. docs/research/board-capability- inventory.md is cited, not re-derived, for what this board’s own inputs
are known to emit. Host/build proof only; see the open task for whether any
attached keyboard actually sends these keysyms on this board.
When a bindsym-recognized volume key event reaches Sway, the system
SHALL run the corresponding wpctl set-volume/set-mute command against
the default sink directly, with no separate signal from Sway to the Rust
shell client — the shell’s own PipeWire graph watcher SHALL be the sole
mechanism that notices the resulting change and raises the HUD, the same
way it would for any other external change. Whether
this board’s main unit or its optional keyboard/nRF9151 base emits any of
these keysyms today is not established from source; these bindings are
inert until a keyboard that emits them is attached.
Grounding: nix/shell.nix’s bindsym XF86AudioRaiseVolume/LowerVolume/ Mute lines (k230.shell.coherentShell-gated); design.md Decision 7.
XF86AudioRaiseVolume/LowerVolume/Mute key eventwpctl changes the default sink directly, and the Rust shell client’s own graph watcher (not a message from Sway) is what notices and raises the HUDGrounding: docs/evidence/volume/closeout-2026-10-01/README.md and result.json: installed physical-board UI/backend verification using injected contacts, real sink/stream state and native captures. Headphone audibility is retained as UNVERIFIED audio task 5.6; no new human-finger test is claimed.
Host build proof: cargo unit tests over pipewire_ipc::GraphSnapshot:: sinks/Sink::is_default. QEMU capture under docs/evidence/volume/.
Host/QEMU proof only; the second (external-route) sink’s actual existence
on hardware is the-handheld-plays-through-its-speaker’s own open
question, not decided or claimed here.
The expanded HUD panel and the Settings screen SHALL each list every
PipeWire Audio/Sink node currently known (at minimum the Inno codec line-
out), marking the current default, and SHALL let a person pick a different
one via wpctl set-default ID. Whether the-handheld- plays-through-its-speaker’s external-I2S route ever appears as a second,
separate sink here, versus remaining only an ALSA-level mixer switch with
no distinct PipeWire node, is not established and this requirement does
not assume either outcome — the picker simply shows however many sinks
WirePlumber actually reports.
Grounding: pipewire_ipc::{GraphSnapshot,Sink}; design.md Decision 8.
Audio/Sink node is known and a person picks one that is not currently defaultwpctl set-default is called with that sink’s id, and the graph watcher’s next update shows it as the new defaultArchived change · Archived
Snapshot 5836ef1d113d · 2026-10-17 08:22 UTC
Closed recordReview the archived record and cited scope
Accepted card, Wi-Fi and Home closeouts contain committed proof but use HTML comments for grounding. The site recognizes the documented Grounding citation format, so these archives currently block publication.
Normalize verification citations in the existing accepted requirements, preserving every behavioral requirement, scenario, evidence limit and unavailable-hardware marker. Reconcile archived dashboard IDs and record the mainline source checkpoint.
radio/wifi: retain accepted Settings behavior with recognizable grounding.runtime/card-composition-plan: cite the accepted source, board and operator reports.runtime/home-screen: cite committed folder, paging and widget proof.Documentation and generated site only; no new board capability or measurement.
The site parser intentionally requires a Grounding citation or an UNVERIFIED marker. Its failed CI log identifies the malformed closeout citations.
Use existing committed proof and the parser’s established Markdown Grounding format. Apply MODIFIED deltas through OpenSpec archive; never hand-edit accepted main specs. Keep operator, injected board, QEMU and unavailable-battery evidence limits explicit.
A documentation fix must not turn an unmeasured timing or unavailable attached-battery result into a new claim. Existing wording and limits are retained.
Strict OpenSpec, render_specs, render_work_board and site build; exact master deployment is verified separately.
Grounding: docs/evidence/wifi-settings/closeout-2026-10-01/README.md; operator acceptance plus independently injected board eye/keyboard checks, with explicit limits. The system’s shell userspace SHALL let a person open Network from Settings, refresh and scroll a bounded list of nearby networks, distinguish current and saved connections, select an open or WPA2-Personal network by touch, and return without changing connection. It SHALL show scanning, empty, unavailable, stale, and failed states without presenting a stale scan as current. It SHALL not equate association with Internet reachability.
Grounding: docs/evidence/wifi-settings/closeout-2026-10-01/README.md; operator acceptance plus independently injected board eye/keyboard checks, with explicit limits. The shell userspace SHALL offer masked password entry for a selected supported secured network using the same system keyboard every other text field in the shell uses (not a separate in-app keypad), mask entered characters by default, permit correction and cancellation, and show a bounded Connect pending state with a useful failure and retry route. The password field SHALL take real keyboard focus only for its own lifetime and release it immediately on Connect, Cancel, or leaving the page, so the system keyboard never contests focus with an application the rest of the time. Cancel/Connect SHALL remain reachable above the raised keyboard rather than hidden beneath it. The system SHALL pass a credential only through a private runtime channel to a privileged Wi-Fi service; neither side SHALL put the secret or a network identifier in command arguments, environment, Nix closure, tracked files, ordinary logs, or committed evidence. The shell SHALL NOT receive saved passwords back from the service.
Grounding: docs/evidence/wifi-settings/closeout-2026-10-01/README.md; operator acceptance plus independently injected board eye/keyboard checks, with explicit limits. The system SHALL save an accepted connection only in the existing root-controlled Wi-Fi credential location outside the image closure and use the existing runtime credential service to reconnect on later boots. Settings SHALL expose saved state and an explicit Forget action that removes the selected saved credential and stops automatic reconnect for that network. A failed, cancelled, or stale attempt SHALL NOT overwrite the last confirmed saved configuration.
The system SHALL retain one Sway-owned DRM/KMS presentation path while a card experiment is active. Before a visual-card implementation is selected, the project SHALL compare existing client/protocol and narrow compositor routes using pinned source evidence for application-surface composition, touch routing, focus return, frame completion, and presentation reporting. A client-only metadata overlay SHALL NOT be represented as live application-card composition.
Grounding: docs/research/card-composition-source-audit.md and docs/evidence/card-composition-board/README.md ground the selected Sway/Pixman route.
Grounding: docs/evidence/proposal-closeout/2026-10-01/card-composition.md and docs/evidence/card-composition-board/README.md; accepted operator report with stated limits. If the architecture decision establishes a viable route, an opt-in prototype SHALL prove two simultaneously running application surfaces visually represented in a single card scene, continuous finger tracking, adjacent-card selection and expansion, and a dismissal request with an explicit close-refusal outcome. It SHALL preserve keyboard focus and the existing usable Pixman session on failure. A grounded negative decision SHALL state that product delivery is blocked, not call the capability delivered.
Grounding: docs/evidence/proposal-closeout/2026-10-01/card-composition.md and docs/evidence/card-composition-board/README.md; accepted operator report with stated limits. The prototype SHALL record CPU, memory, frame/presentation evidence, pixel format, buffer lifetime, and synchronization observations separately from host models. It SHALL not claim GPU acceleration, zero-copy, or full card UX acceptance unless those observations demonstrate them.
Grounding: docs/evidence/home-widgets-folders/closeout-2026-10-01/board/README.md and sibling paired QEMU reports; operator acceptance plus delegated board uinput proof, not new finger measurements. Additional committed native board evidence: docs/evidence/home-widgets-folders/closeout-2026-10-01/board/README.md and docs/evidence/home-widget-design/closeout-2026-10-01/board/README.md.
Long-pressing an installed application’s tile in the drawer SHALL lift that application’s icon to follow the finger instead of pinning it immediately, and Home SHALL be revealed underneath while the drag is live. Releasing over an empty grid cell or dock slot SHALL place the item there. Releasing over an already-pinned application SHALL create a new folder containing both. Releasing over an existing folder SHALL add the item to it. Releasing over a Cancel target, or over the area the drawer’s own chrome occupied before the drag began, SHALL abandon the drag with no change to Home. Holding the dragged item near the panel’s left or right edge for about 500ms SHALL turn Home to the neighboring page, or add a new page when held past the last one.
Grounding: docs/evidence/home-widgets-folders/closeout-2026-10-01/board/README.md and sibling paired QEMU reports; operator acceptance plus delegated board uinput proof, not new finger measurements. Additional committed native board evidence: docs/evidence/home-widgets-folders/closeout-2026-10-01/board/README.md and docs/evidence/home-widget-design/closeout-2026-10-01/board/README.md.
Long-pressing an item already on Home (an application, a folder, or a widget) SHALL enter the same drag as a drawer-originated one, resolved by the same cell/folder/dock/edge-page-switch rules, plus a Remove target that unpins the dragged item from Home without uninstalling it. A page left with nothing pinned to it after a move SHALL be removed automatically, except that Home always keeps at least one page even when it is empty.
Grounding: docs/evidence/home-widgets-folders/closeout-2026-10-01/board/README.md and sibling paired QEMU reports; operator acceptance plus delegated board uinput proof, not new finger measurements. Additional committed native board evidence: docs/evidence/home-widgets-folders/closeout-2026-10-01/board/README.md and docs/evidence/home-widget-design/closeout-2026-10-01/board/README.md.
A folder SHALL display as a single rounded tile showing up to four of its members’ icons in a 2x2 arrangement. Tapping a folder tile SHALL open an overlay showing every member application in a grid and the folder’s name. The folder’s name SHALL be editable. Removing an application from a folder that would leave exactly one member SHALL dissolve the folder, leaving that one application pinned directly in the folder’s former cell.
Grounding: nix/shell.nix’s existing k230-weather desktop entry is
the reused wttr.in source; this board’s actual power-supply hardware is
UNVERIFIED beyond “no such sysfs device exists today” (design.md Decision
6). Native board widget appearance and cached weather are recorded in
docs/evidence/home-widget-design/closeout-2026-10-01/board/README.md; their content logic (battery absent/present, weather
cache freshness/staleness/offline) is host-tested. Additional committed native board evidence: docs/evidence/home-widgets-folders/closeout-2026-10-01/board/README.md and docs/evidence/home-widget-design/closeout-2026-10-01/board/README.md.
Home SHALL support placing a Clock widget, a Battery widget, and a Weather
widget, each occupying a fixed cell span, rendered by the shell itself
rather than delegating to an external application. The Clock widget SHALL
show the current time and date in the active theme’s colors, updating at
least once per minute, aligned to the minute boundary. The Battery widget
SHALL show a clean “no battery info” state when no battery device is
present, and SHALL reflect a battery device that later appears without
requiring a restart. The Weather widget SHALL show a condition indicator
and the current temperature from the same source k230-weather already
uses, fetched no more often than every 30 minutes, cached to disk, and
SHALL continue showing its last successful reading when offline rather
than an error or a blank tile.
power_supply class device of type
BatteryGrounding: home_state.rs’s existing schema-1 round-trip tests are
the migration source this change’s schema-2 loader is tested against
directly (a_schema_1_file_migrates_to_plain_apps_on_load). Additional committed native board evidence: docs/evidence/home-widgets-folders/closeout-2026-10-01/board/README.md and docs/evidence/home-widget-design/closeout-2026-10-01/board/README.md.
The on-disk Home layout SHALL record folders (their name and member application ids) and widgets (their kind) alongside plain pinned applications, for both grid pages and the dock. A layout file written by an earlier version of the shell that predates folders and widgets SHALL load successfully, with every previously pinned application preserved in its existing cell.
Grounding: implemented and host-tested (home_screen/home_pager
unit tests, including the dwell-timing, page-creation, and fling tests
named below). The rendered edge glow/arrow and “no room” highlight are
evidenced by a host Cairo render harness
(docs/evidence/home-widget-design/), not a board or QEMU capture; real
touch feel and daylight visibility of the affordance are UNVERIFIED on
hardware. Additional committed native board evidence: docs/evidence/home-widgets-folders/closeout-2026-10-01/board/README.md and docs/evidence/home-widget-design/closeout-2026-10-01/board/README.md.
While a person holds a dragged Home item (an icon, a folder, or a widget) within about 40px of the panel’s left or right edge, Home SHALL show a visible themed highlight and a growing arrow at that edge, and SHALL turn to the neighboring page after about 350-400ms of continuous holding there. Continuing to hold at the edge past that first turn SHALL keep turning pages with a shorter repeat delay of about 260ms. Holding at the true last page’s right edge past that same dwell SHALL create a brand-new, empty page and slide onto it rather than remaining inert. Every page turn this triggers, and any triggered by a quick horizontal fling below, SHALL animate as a smooth slide, never an instant jump, and the dragged item’s own on-panel position SHALL continue following the raw finger position throughout, unaffected by the page transform. Page-count dots SHALL render enlarged while any drag is live. A quick, deliberate horizontal drag motion during a hold (independent of edge proximity) SHALL also turn one page immediately. A multi-cell widget’s drag hovering over a target it cannot fit SHALL show a visibly distinct “no room here” highlight instead of the ordinary accepting one.
Grounding: implemented and host-tested (clock style formatting,
j1 forecast selection/parsing, battery ring percent/charging state, the
procedural dot-matrix digit table). Rendered appearance is evidenced by a
host Cairo render harness (docs/evidence/home-widget-design/) composited
over real Omarchy theme wallpaper images, not a board or QEMU capture;
daylight readability and on-device color/font reproduction are UNVERIFIED
on hardware. Additional committed native board evidence: docs/evidence/home-widgets-folders/closeout-2026-10-01/board/README.md and docs/evidence/home-widget-design/closeout-2026-10-01/board/README.md.
The Clock widget SHALL offer at least four selectable visual styles,
researched from current mobile-platform and community widget design
(docs/design/clock-widget-research.md): a heavy centered stacked hour/
minute pair, a thin centered single time line, a procedurally drawn
dot-matrix readout, and a drawn analog face (ticks and hands only, no dial
fill or ring) with an accent-colored minute hand — each choosable from the
widget picker, which SHALL render a live preview of each widget kind’s
actual content inline in its own row. The Battery widget SHALL show its
charge as a themed ring with a distinct charging indicator when charging,
and its absent state SHALL pair the existing “No battery info” wording with
a muted outline battery glyph. The Weather widget SHALL show the current
temperature as a large numeral, a drawn condition icon distinct per
condition family (at minimum sun/cloud/rain/snow/fog/storm), the location
name when available, today’s high and low, and a short multi-entry forecast
strip when forecast data is available. No widget of any kind SHALL paint a
card background, surface fill, or border behind its content — every widget
sits directly on the wallpaper; legibility SHALL instead come from a halo
or glow computed from the theme’s own resolved color for that glyph (a
light halo behind a dark glyph, a dark halo behind a light glyph), never a
fixed shadow color that ignores which theme is active.
Archived change · Archived
Snapshot 5836ef1d113d · 2026-10-17 08:22 UTC
Closed recordCompleted: repeated edge turns, new-page drops, interior fling and redesigned native widgets verified.
the-home-screen-has-widgets-and-folders (still unarchived) shipped
drag-to-place, folders, and three plain widgets. The user tried it on the
board and reported two concrete gaps, in their own words: “i can’t drag
widgets/icons between screens easily and the widgets all are designed like
horseshit can they look way better we need a dope clock nice weather
widget.”
Two concrete problems this closes:
A first pass at both landed, and the coordinator deployed it to the board
for the user’s judgment. Board review round 2 (from the deployed build’s
own evidence screenshots, before the user looked) fixed a corner-leaking
tint, a boxed-in border, an oversized battery ring, a cramped clock, and a
tiny forecast strip. The user then tried that build on the board and
reported, verbatim: “the widgets don’t have to have a background like they
do and the clock looks like shit browse the web find dope clock widgets
plz.” Round 3 (this pass) responds to both halves of that: every widget’s
card background is gone entirely, replaced by a theme-derived halo/glow
computed straight from each glyph’s own color; and the Clock widget was
rebuilt from a survey of real clock-widget design across current mobile
platforms and community tools (docs/design/clock-widget-research.md),
not another guess.
home_screen::PageSwitchAnim driving home_pager::HomePager:: set_position), never an instant jump, and the lifted item keeps
following the raw finger position throughout, unaffected by the page
transform. A quick, deliberate horizontal fling mid-drag (>=900px/s,
independent of edge proximity) pages over immediately, with a short
lockout against re-triggering off one continuous swipe. Dragging a widget
or icon to the true last page’s right edge and continuing to hold now
creates a brand-new empty page and slides onto it, rather than sitting
inert at the clamp. Page dots enlarge while any drag is live. A
multi-cell widget hovering somewhere its span cannot fit now shows a
distinct dashed “no room here” highlight (the theme’s error role)
instead of the ordinary accepting one.docs/design/clock-widget-research.md surveys twelve
standout clock-widget designs — Pixel’s lock-screen bubble/thin presets
and At a Glance’s own legibility fix, Nothing OS’s Ndot dot-matrix,
iOS StandBy, Samsung One UI’s Adaptive Clock, Material You’s system clock
widget, KWGT/KLWP community packs, Braun/Dieter Rams’s single-accent
analog convention, and r/unixporn/Omarchy desktop-rice clocks — and
states, per design, what each borrows into this change.WidgetKind
gains ClockMinimal, ClockAnalog, and ClockDotMatrix alongside the
existing Clock, all additive to the schema-2 tag (clock/
clock_minimal/clock_analog/clock_dot_matrix), so an existing save
file needs no migration and the enum’s internal variant names stay
unchanged even though every style’s user-facing label changed. All four
are selectable from the widget picker, which renders a live preview of
each inline in its own row.
Clock): hour and minute each their own huge line, Inter
at its heaviest weight, the same color, centered — Pixel’s own
two-line lock clock.ClockMinimal): one line, Inter at its thinnest weight,
centered.ClockDotMatrix, new): a procedural 5x7 dot-matrix
HH:MM readout drawn with plain Cairo circles, no font file at all —
digits in the theme’s foreground, the colon in its accent.ClockAnalog): ticks and hands only, the dial fill/ring
from the first two passes removed entirely (Braun/Rams: “no dial
background, just markers and hands”), an accent minute hand.nix/shell.nix gains clockDisplayFont, one file
(Inter.ttc, 13,172,948 bytes) extracted from nixpkgs’s pkgs.inter
— the classic static collection, not the variable font: pango-sys
at this repo’s pinned version has no binding at all for
pango_font_description_set_variations (confirmed with a scratch
cargo check), so the variable weight axis is unreachable from this
client, but the static collection already carries Thin through Black
as ordinary named faces pango::Weight addresses the same way this
shell’s existing DejaVu lookup already does. Used for the Bubble/Thin
styles only; Dot matrix needs no font, and Analog’s only text (its
date caption) stays on the existing FONT_FAMILY.render.rs::paint_widget_surface
(round 2’s own card-without-a-border fix) is gone entirely — no fill,
no border, no corner radius, nothing painted behind a widget’s content
but the wallpaper itself. Legibility instead comes from a halo/glow
computed from each glyph’s own resolved color (glow_for): a dark glyph
gets a light halo, a light glyph gets a dark one, via 8 offset copies of
the same Pango layout at a small radius and low alpha behind the real
glyph (draw_layout_halo) — a cheap stand-in for a true blur, which
Cairo’s toy API has none of. Small graphic elements (the weather glyph,
the battery ring/outline) get the equivalent non-text treatment, a soft
ambient circular backdrop (draw_soft_backdrop) rather than a halo.j1
format. Current temperature (large), a Cairo-drawn condition glyph
(sun/cloud/rain/snow/fog/storm), location name, today’s high/low, and a
3-entry forecast strip, all now painted straight on the wallpaper with
the halo/backdrop treatment above instead of on a card. The 30-minute
throttle, disk cache, and offline-keeps-last-reading behavior are
unchanged.home.battery/home.weather)
changed, or once a minute for the clock (clock::ms_until_next_minute);
this pass adds more Cairo path drawing per widget paint but no new timers
and no per-frame recomputation — paint_widget_card still reads
already-cached state and draws once per repaint, exactly as before.Non-goals for this pass: widget resizing (still explicitly out of
scope, as in the sibling change); a fourth clock style beyond the three
named; changing the weather source away from wttr.in; touching any
theme_ui.rs/theme_carousel.rs/theme_thumbnails.rs/theme_catalog.rs/
appearance.rs file (per the coordinator’s explicit instruction — this
change reads theme colors through the existing appearance/render.rs
brush/palette lookups only); nix/card-shell/ (the C card renderer, owned
by other concurrent work).
Board dependency: every behavior above is host-testable. The drag
timing/page-creation/fling state machine is exercised by cargo test
(home_screen/home_pager unit tests, including new ones for the ~380ms/
~260ms dwell thresholds, the last-page new-page creation, and the “no room”
drop-target check). The widget content/parsing logic (the three clock
styles’ formatting, the j1 forecast selection, the battery ring’s percent/
charging state) is unit-tested with no hardware. The visual result is
evidenced by a host Cairo render harness
(nix/rust-shell-client/examples/render_widget_evidence.rs,
docs/evidence/home-widget-design/), not a board or QEMU capture — this
proposal does not touch the board, and physical-board real-finger
acceptance (daylight readability, real touch feel, real forecast data over
the board’s own network) remains an explicitly open evidence gate for the
coordinator.
None.
None archived to modify — openspec/specs/runtime/home-screen/ does not
exist yet (the-home-screen-has-widgets-and-folders, the change that would
create it, is itself still unarchived). This change’s own spec delta below
therefore also adds its requirements as ADDED, exactly as that sibling
change’s own proposal explains doing for the same reason. Two of this
change’s requirements revise in place, once both land, requirements the
sibling change already added:
Mostly userspace, nix/rust-shell-client/: home_state.rs (WidgetKind
gains three variants plus add_blank_page/would_fit), home_pager.rs
(set_position), home_screen.rs (edge-hold/fling/page-switch-animation
state machine, drag_edge_indicator/drop_target_fits accessors),
home_widgets.rs (the weather module’s j1 rewrite), render.rs (the
no-card/halo widget redesign, the four clock styles, the edge indicator,
the “no room” drop-target style, enlarged page dots), main.rs (two
call-site signature updates for the drawer-drag hand-off’s now
time/height-aware external_drag_motion), and a rewritten
examples/render_widget_evidence.rs host harness (now composites over a
real wallpaper image via background_decode::BackgroundCache). Plus one
Nix-level change: nix/shell.nix gains clockDisplayFont (one font file,
13,172,948 bytes, extracted from nixpkgs’s pkgs.inter) in
fonts.packages, alongside the existing pkgs.dejavu_fonts — the one
font addition this whole home-widget-design change makes, used only by
the Clock widget’s Bubble/Thin styles. No kernel, device tree, boot, radio,
or second-core change. The existing .#handheld-shell-rust/.#card-shell
outputs and the k230-coherent-shell NixOS configuration absorb it.
home_screen::HomeScreen already had a working, if slow and silent,
edge-hold page turn: a single EDGE_HOLD_MS: u32 = 550 constant and an
instant self.pager.set_page(next) jump, both computed inline in tick().
home_widgets.rs’s Clock/Battery/Weather modules already separated content
(host-testable, no touch surface) from rendering (render.rs:: paint_widget_card, plain shadowed_label text calls). Neither needed a
rewrite from scratch; both needed the mechanism widened and the paint code
replaced.
Goals: make cross-page dragging read as deliberately responsive (dwell
timing, visible affordance, fling, new-page creation, a “no room” cue);
redesign every widget’s visuals without breaking its existing content/cache
logic; keep every existing home_state/home_screen test passing and add
coverage for the new timing/creation/fling/no-room behavior; produce visual
evidence without the board.
Non-goals: widget resizing; a new font package; touching
nix/card-shell/ or any theme-picker file; changing where weather data
comes from (still wttr.in, still curl).
PageSwitchAnim, driven independently of HomePager’s own drag/momentum/settle stateThe old edge-hold code called self.pager.set_page(next) — an instant,
un-eased jump, chosen originally because nothing at the time needed it to
animate. Making it slide smoothly could have reused HomePager’s own
settle field (already an eased from/target/elapsed/duration), but that
field’s owner is a live touch drag’s release; reaching into it from
home_screen for an edge-hold/fling trigger would mean either exposing a
start_settle-equivalent publicly (blurring “who owns this pager’s motion
right now”) or risking a real touch-driven settle and an edge-hold-driven
one fighting over the same field on the same tick.
Instead, HomePager gained one small, narrow addition:
set_position(position, count) — an unconditional, un-animated setter
(clamped, clears velocity/settle) that assumes the caller supplies an
already-eased value. home_screen::PageSwitchAnim { from, target, elapsed_ms, duration_ms } owns the easing curve entirely on the
HomeScreen side and calls set_position every tick. This keeps the two
animation sources (a live touch drag, and a triggered edge-hold/fling)
structurally separate: HomePager never runs both at once because nothing
in this change ever calls both pager.down/pager.motion and
start_page_switch for the same touch.
note_drag_point/maybe_fling/advance_edge_hold factored out of both drag pathsThe internal (touch-tracked, Contact-gated) drag path and the external
(drawer-origin, no Contact) drag path used to each inline their own
edge-zone check. Both now funnel through one note_drag_point(point, time_ms, width, height) that updates edge_side, resets the dwell timer on
a zone change, and calls maybe_fling(). This was worth the refactor
because task 1 asks for the same fling/edge-hold/no-new-page-
double-triggering behavior on both paths, and two independently-tuned copies
of the same threshold logic is exactly the kind of drift this project’s own
AGENTS.md warns about.
drag_track_ms: Option<u32>, not a bare u32, for the fling velocity baselineThe very first motion sample after a drag begins has no prior point to
diff against. Rather than seed drag_track_ms with the drag’s start time
(which tick()-driven drag starts, e.g. promoting a long-press into a
rearrange, do not have — tick only receives an elapsed-ms accumulator,
never an absolute timestamp), reset_drag_tracking() sets it to None and
note_drag_point only computes a velocity when a prior Some baseline
exists. This sidesteps needing tick() to know the wall clock at all, and
guarantees a drag’s very first sample can never read a stale, wildly-large
elapsed time as if it were real motion.
WidgetKind gains one variant per clock style, not a separate style: ClockStyle field on HomeItem::WidgetAdding a style field to HomeItem::Widget { widget: WidgetKind, style: ... }
would need either an Option<ClockStyle> (meaningless for Battery/Weather)
or a default-valued new field threaded through every existing call site and
every schema-2 save file already on a board — a real migration concern for
a “just landed” feature. Modeling each clock style as its own WidgetKind
variant (Clock/ClockMinimal/ClockAnalog, and now ClockDotMatrix) is
purely additive to the existing #[serde(rename_all = "snake_case")] tag:
an old save file simply never contains "clock_minimal"/"clock_analog"/
"clock_dot_matrix", and a new one just starts using them. span()
already dispatches per-variant, so a wider analog face vs. the three
full-width line/readout styles falls out for free. The tradeoff:
WidgetKind::ALL’s length is load-bearing for the picker’s row count
(home_screen::picker_row_count) — fixed by deriving that count from
WidgetKind::ALL.len() instead of a hand-typed literal, so adding
ClockDotMatrix in round 3 needed no change to that count logic at all,
exactly the point of the original design. Only [WidgetKind::label]‘s
user-facing string changed to match round 3’s own style names (Bubble/
Thin/Dot matrix/Analog) — the Rust variant identifiers, and therefore the
serialized tag, deliberately did not get renamed to match, since a board
may already have saved a layout using the old names.
j1 JSON wholesale, cache shape includedThe old WeatherSnapshot { condition, temperature, fetched_unix_secs }
could not carry a forecast, a high/low, or a location at all — %C|%t
never had that data. Rather than adding a second, parallel fetch for the
extra fields, the whole snapshot moved to j1 (temperature_c: i32, not a
formatted string with degree/unit baked in, since the widget now needs the
raw number for its own hero-numeral formatting). This is a breaking change
to the cache file’s shape, deliberately not migrated: weather.json is a
disposable, re-fetchable cache (unlike home.json’s persisted layout,
losing which loses a person’s actual arrangement), so an old-shape cache
file simply fails to deserialize, load_cache returns None, and the next
poll re-fetches — one extra network round-trip, not a data-loss risk.
The Weather widget’s own card is 2x2 (WidgetKind::span), which at this
panel’s real grid geometry (home_grid’s ROW_HEIGHT/tile_width) works
out to roughly 253x350px. Three forecast columns at a legible size (an
11-13px label/temperature pair plus a small glyph) fill that width
comfortably; four or five would either shrink past comfortable legibility
at 330ppi or force the card wider than its 2x2 footprint. j1’s own hourly
data has enough entries for 5 if a future pass widens the card; this one
keeps the fixed 2x2 span the sibling change already committed to and picks
the count that actually reads well at it.
The first pass (see the superseded reasoning this replaces, below) declined
to add a font at all, partly because “this host environment cannot prove a
brand-new nixpkgs source fetch actually succeeds.” Round 3’s own research
task required actually trying it, which changed the calculus: nix build --impure --expr '...pkgs.inter' against this repo’s own pinned nixpkgs
input succeeded directly from cache.nixos.org (5.1 MiB compressed, 14.3
MiB unpacked) — so the risk that motivated declining a font turned out not
to hold. pkgs.inter ships two things: a variable font (InterVariable (-Italic).ttf, ~1.75 MiB combined) and a classic static collection
(Inter.ttc, 13,172,948 bytes, every weight from Thin to Black as its own
named face under one “Inter” family, confirmed with fc-scan). The
variable font was checked first and ruled out: pango-sys at this repo’s
pinned version (0.21.5) has no binding at all for
pango_font_description_set_variations, confirmed directly with a scratch
cargo check against the real crate (not assumed from a changelog), so
that axis is unreachable from this client regardless of which font ships
it. Inter.ttc’s static faces need no such binding — pango::Weight
already knows how to select a named face by weight, exactly the mechanism
this shell’s existing DejaVu Book/Bold lookup already uses — so that is
the one file nix/shell.nix’s clockDisplayFont extracts (via a small
pkgs.runCommand, so the final image closure carries only that one file,
not all of pkgs.inter; the fuller package is a build-time-only input,
discarded after extraction since the copied font file contains no store-
path references of its own). Used for the Clock widget’s Bubble/Thin
styles only, per round 3’s own “ONE small… font” instruction — Dot
matrix draws its own dots and Analog’s only text stays on FONT_FAMILY.
Superseded first-pass reasoning, kept for the record: “render.rs:: FONT_FAMILY’s own doc comment already recorded, for a prior rendering-
only fix, that this image ships exactly one family (pkgs.dejavu_fonts,
nix/shell.nix: ‘One family is enough’) and that pulling in a second is a
blob-inventory/image-size change out of scope for rendering work alone…
this pass did not attempt it partly because this host environment cannot
prove a new nixpkgs source fetch actually succeeds under the coordinator’s
own cross-build sandbox.” That specific risk is what round 3 actually
tested and found not to hold, for this exact font, in this exact
environment — the general caution was reasonable given what was known at
the time, but “cannot prove it” is not the same claim as “would fail.”
The sibling change’s own evidence README documents a QEMU/injected-touch
driver that was silently terminated at a reproducible point across three
attempts, on this same shared build machine. Rather than re-attempt that
same fragile path for a change that is 90% pure rendering, this change adds
examples/render_widget_evidence.rs: it calls the real, unmodified
render::paint_home offscreen against a cairo::ImageSurface, with two
synthetic AppearanceSnapshot themes built from that struct’s own public
fields (not a live Omarchy IPC session — this host has no compositor to
receive one). The two drag-mechanic screenshots in that evidence set are
not faked: they drive HomeScreen through its real public down/motion/
tick/external_drag_motion API, the same one a real touch event stream
calls. This proves the widget-drawing and drag-state-machine code paths
genuinely execute and look as designed; it does not substitute for
QEMU/board proof of real touch input, real compositor compositing, or
daylight/panel color reproduction, and is not claimed as such anywhere in
this change’s evidence or tasks.
The coordinator deployed the first pass’s build to the board for the user’s judgment and, from the host evidence screenshots alone (not a board photograph), flagged five concrete visual issues: the weather card’s condition tint leaking past its rounded corners; a 1px border on every widget reading as “boxed-in”; an oversized battery ring with its percentage captioned beneath instead of inside it; the “Big stacked” clock cramped against the card’s left edge with both lines at equal visual weight; and a forecast strip too small to read at arm’s length. Each is a rendering-only fix, addressed in this same change rather than a follow-up:
paint_condition_tint painted an unclipped rectangle.
The call site now wraps it in the card’s own rounded clip path (the exact
clip paint_widget_surface, below, already establishes for the card’s
fill, just re-applied since Cairo’s clip does not persist across a
save/restore pair once popped).service_card’s border stroke (drawn from the theme’s own
border/selected-border brush when the theme defines one) was never
wrong on the panels that still use it — the dock, the folder overlay,
the picker sheet all keep it, and still look consistent doing so, since
they sit inside other chrome (a card row, a scrim) that already frames
them. A widget has nothing else framing it; the same border read as a
literal box around content sitting directly on the wallpaper. Decision 9
covers the replacement in more detail.caption_line) to a new
ring_percent_label, sized and positioned to sit centered inside the
ring itself. The charging bolt moved out of the ring’s dead center (where
it would now collide with the centered percentage) to a small accent
badge circle at the ring’s own upper-right, the glyph drawn in the
card’s own background color for contrast against the accent fill —
reading as a distinct status badge rather than competing with the
number for the ring’s center.pad to pad * 1.7,
and the minute line dropped from Bold to Normal weight (the hour stays
Bold and accent-colored) so the pair reads as a clear hour-first
hierarchy rather than two equally-weighted numbers pressed against the
edge. The date caption grew from 14px to 17px.paint_widget_surface: a dedicated, borderless widget backgroundSuperseded by decision 10, round 3: the function this decision
describes no longer exists — board review round 2’s own fix (a filled
surface instead of a bordered one) was itself replaced by “no surface at
all” once the user judged the filled card itself, not just its border,
as something that “doesn’t have to” be there. Kept below for the record of
why a dedicated painter (rather than a flag on service_card) was the
right shape for the problem as understood at the time; that reasoning
carried forward into decision 10’s own halo/backdrop functions, which are
equally dedicated and equally narrow.
Rather than pass a flag into service_card to suppress its border only for
widgets (which would leave service_card itself doing two visually
different things depending on a boolean, for every one of its many other
call sites to reason about), widgets got their own small, single-purpose
painter. paint_widget_surface clips to the card’s own rounded rect,
paints a handful of offset, low-alpha filled passes underneath as a cheap
soft shadow (no true blur — Cairo’s toy API has none, and a real one would
mean an intermediate render target on every dirty repaint), then fills the
theme’s own “launcher”/“background” brush through the existing
overlay_brush helper at a fixed ~80% alpha via paint_with_alpha,
regardless of whatever alpha that brush’s own authored stops carry. It
never queries a “border” token at all. This keeps service_card completely
unchanged for every other panel in this shell, and gives widgets one
narrow, easily-audited place that owns “what a widget card’s own background
looks like” independent of whatever any other panel decides to look like.
Board review, round 2, on the first pass’s own evidence: “the widgets
don’t have to have a background like they do.” paint_widget_surface
(decision 9) is removed entirely — paint_widget_card now paints nothing
behind its own content but whatever the caller already painted (the real
wallpaper). Legibility instead comes from glow_for(rgb): a plain
luminance check (Rec. 709 coefficients) on the glyph’s own resolved color,
returning black for a light glyph and white for a dark one — literally
what the board review asked for (“dark text gets a light halo, light text
gets a dark shadow”), computed from the theme’s own resolved value rather
than a fixed shadow color that would look wrong under the other theme.
Two primitives apply it:
draw_layout_halo — for text: draws the same Pango layout again at 8
points evenly spaced around a small circle, each at a low alpha, before
the real glyph on top at full opacity. This is a standard “poor man’s
blur” (multiple offset copies standing in for a true Gaussian blur, which
Cairo’s toy API has no support for at all) — cheap, since a widget only
repaints when its underlying value changes or once a minute for the
clock, never per frame.draw_soft_backdrop — for small graphic elements (the weather condition
glyph, the battery ring, the absent-battery outline): a single soft
filled circle behind the shape, the same idea without needing a text
layout to redraw.Every caption that previously used a lower-alpha “muted” tone
(style.muted, caption_line’s old 0.82 alpha) moved to the theme’s full
text/accent colors at full opacity, the halo doing the contrast work
instead of a dimmer color — a low-alpha color plus a halo still reads as
faint against a busy photo; a full-strength color plus a halo reads
clearly regardless of what is directly underneath it.
The four clock styles, rebuilt from research rather than guessed: with
no card constraining the layout to “content inside a box,” Bubble and Thin
both moved from round 2’s left-aligned-with-padding layout to centered,
matching the actual Pixel/iOS convention docs/design/ clock-widget-research.md surveys (a hero clock floating on wallpaper,
not boxed text) — and both now use CLOCK_FONT_FAMILY (decision 6) at a
real Black/Thin weight instead of DejaVu’s Bold/Normal standing in for
“heavy” and “light.” Dot matrix is new, entirely procedural (decision
document’s own digit-bitmap table), needing no font at all — the
research survey’s own “no font dependency” point from the r/unixporn/
Rainmeter/Conky tradition. Analog dropped its dial fill and ring stroke
entirely (draw_analog_clock no longer paints either), leaving only tick
marks and hands, per the same survey’s Braun/Dieter Rams citation: “no
dial background, just markers and hands.” The two hands get the halo
treatment too (they are this widget’s own thinnest strokes, most likely to
vanish against a busy photo); the twelve tick marks stay plain, since
haloing all twelve reads as clutter rather than polish.
The drop-target highlight rect is sized to the single raw grid cell under
the finger; the floating dragged-item preview is sized to the dragged
item’s own span, centered at the same finger point. For a widget-sized
drag (2x2 or 4x2), the preview is necessarily larger than that one
highlighted cell and, centered on the same point, usually covers most or
all of it — this is true for every existing drag in this shell, not new
behavior this change introduces. Redesigning the highlight to draw outside
the lifted preview’s bounds (e.g., only its uncovered edges) was considered
and rejected: it would make the accepting-drop case look different from
every other reference launcher’s convention (a highlighted cell the item
visibly sits inside), for a cosmetic gain only visible in the one moment a
widget-sized item hovers dead-center over its own target. The stronger,
already-shipped proof that “no room” actually blocks the wrong drop is
HomeScreen::drop_target_fits, unit-tested directly
(dragging_a_widget_over_another_widgets_full_span_shows_no_room).
home_pager::HomePager::set_position — an external, un-animated
position setter (clamped, clears velocity/settle) that home_screen’s own
eased driver calls every tick, distinct from set_page’s instant integer
jump; verify with
cargo test --offline -p k230-shell-rust home_pager::tests::set_position_clamps_and_clears_velocity_and_settle.home_screen: EDGE_ZONE_PX narrowed to 40px;
EDGE_HOLD_FIRST_MS/EDGE_HOLD_REPEAT_MS (380ms/260ms) replace the old
single 550ms constant; PageSwitchAnim drives every edge-hold/fling page
turn as a smooth eased slide instead of an instant jump;
note_drag_point/maybe_fling/advance_edge_hold shared by both the
internal (touch-tracked) and external (drawer-origin) drag paths; verify
with
cargo test --offline -p k230-shell-rust home_screen::tests::edge_hold_does_not_switch_before_the_first_dwell_threshold home_screen::tests::edge_hold_repeats_with_a_shorter_delay_than_the_first_turn home_screen::tests::a_quick_horizontal_fling_mid_drag_pages_immediately_without_an_edge_dwell.HomeLayout::add_blank_page plus advance_edge_hold’s own
last-page-edge branch: holding at the true last page’s right edge creates
a brand-new empty page and slides onto it; verify with
cargo test --offline -p k230-shell-rust home_state::tests::add_blank_page_always_appends_even_when_the_last_page_has_room home_screen::tests::edge_hold_at_the_last_page_creates_a_new_page_instead_of_stalling.HomeLayout::would_fit/HomeScreen::drop_target_fits: a live
drag’s drop target now distinguishes an ordinary accepting cell from one
that cannot fit the dragged item’s span; verify with
cargo test --offline -p k230-shell-rust home_state::tests::would_fit_matches_fits_at_for_an_existing_page_and_always_allows_a_future_one home_screen::tests::dragging_a_widget_over_another_widgets_full_span_shows_no_room.render.rs: paint_edge_page_indicator (themed edge glow plus a
growing chevron, driven by HomeScreen::drag_edge_indicator’s dwell
progress), enlarged page dots while any drag is live, and
paint_drop_target’s dashed “no room” style (the theme’s error role);
verify with the host evidence harness (task 3) and
cargo build --offline -p k230-shell-rust.
QEMU/board coverage: not attempted this pass — see task 3’s note on why
(the sibling change’s own QEMU driver was silently terminated on this
same shared machine across three prior attempts); UNVERIFIED on real
touch/panel.HomeScreen::drop_dragged_item’s DragSource::Existing arm was the only
drag source with no same-page fallback when the release point resolved
to no slot at all — every other source (FromDrawer/Widget/
FromFolder) already fell back to place_first_fit. A release right in
the edge margin (inside EDGE_ZONE_PX’s 40px trigger band but outside
any tile’s own hit rect, since SIDE_MARGIN is only 22px) is exactly
where a person naturally lifts off after watching the page turn under
their finger, and move_existing’s own “target occupied, can’t merge or
swap” branch had the same silent-revert gap. Fixed with a new
HomeScreen::move_existing_to_page/place_on_page_or_restore same-page
fallback (lands on the nearest free cell of whichever page is currently
on screen, not from’s own page), plus a since-empty-and-pruned target
page recreated via HomeLayout::ensure_page before searching it (a
cross-page drag’s own remove_slot on the origin cell unconditionally
prunes a still-empty trailing page, which is exactly what a
freshly-edge-hold-created target page is until something lands on it).
Covered by four new regression tests reproducing the exact release
geometry (an existing icon onto an empty new-page cell, onto an
already-occupied new-page cell, released right in the edge margin, and a
widget released onto an incompatible occupied cell); verify with
cargo test --offline -p k230-shell-rust home_screen::tests::dragging_an_existing_icon_across_the_edge_lands_on_the_new_page home_screen::tests::dragging_an_existing_icon_across_the_edge_onto_an_occupied_cell_lands_nearby_on_the_new_page home_screen::tests::releasing_right_at_the_edge_where_the_page_just_turned_still_commits_to_the_new_page home_screen::tests::dragging_a_widget_across_the_edge_onto_an_incompatible_occupied_cell_lands_nearby_on_the_new_page.
Full-suite re-run: cargo test --offline -p k230-shell-rust (386 lib +
60 integration tests, all passing, 1 pre-existing ignored) and
cargo clippy --offline --all-targets (exit 0, only the same
pre-existing warning set this change’s task 4.1 already documents).
Evidence class: host unit test only (cargo test, native x86 host) plus
a plain cargo build/cargo clippy pass — not QEMU-injected touch
and not real glass; the dedicated fix commit’s own drag/drop logic
was not otherwise touched by rendering or Wayland-input-path changes, so
this is believed to close the reported behavior, but real-finger
confirmation remains open per task 5.1 below.home_state::WidgetKind gains ClockMinimal/ClockAnalog/
ClockDotMatrix (additive to the schema-2 tag, no migration needed),
WidgetKind::ALL and the picker’s row list/count are derived from it
rather than hand-typed literals; verify with
cargo test --offline -p k230-shell-rust home_state::tests::the_four_clock_styles_have_their_documented_spans_and_are_all_pickable.home_widgets::weather rewritten onto wttr.in’s j1 format:
WeatherSnapshot carries location, current temperature/feels-like,
today’s high/low, and up to 5 forecast entries; parse_wttr_j1 selects
forecast entries starting at the current hour and spilling into the next
day; the 30-minute throttle, disk cache, and offline-keeps-last-reading
behavior are unchanged; verify with
cargo test --offline -p k230-shell-rust home_widgets::weather.render.rs::paint_widget_card redesigned per kind, in three
passes (each documented in design.md, each superseding the last where
they conflict):
service_card surface.paint_widget_surface), rescaled the
battery ring and centered its percentage, widened clock breathing room,
enlarged the forecast strip.docs/design/clock-widget-research.md):
removed paint_widget_surface entirely — no card, fill, or border of
any kind. Legibility comes from a luminance-derived halo (glow_for/
draw_layout_halo, for text) or soft backdrop (draw_soft_backdrop,
for small graphics) instead. Rebuilt all four clock styles: Bubble/Thin
centered in CLOCK_FONT_FAMILY (“Inter”) at real Black/Thin weights,
Dot matrix added as a fully procedural 5x7 dot grid
(draw_dot_matrix_time/draw_dot_matrix_glyph, digit bitmaps in
DOT_DIGITS), Analog stripped of its dial fill/ring
(draw_analog_clock no longer paints either). nix/shell.nix gained
clockDisplayFont (one file, Inter.ttc, 13,172,948 bytes, extracted
from pkgs.inter).
Verify with cargo build --offline -p k230-shell-rust,
cargo test --offline -p k230-shell-rust home_state, and the host
evidence harness (task 3).paint_widget_picker’s preview
thumbnail), not a static icon; verify with the host evidence harness
(task 3), dark-widget-picker.png/light-widget-picker.png.nix/rust-shell-client/examples/render_widget_evidence.rs: calls
the real, unmodified render::paint_home offscreen against two synthetic
AppearanceSnapshot themes (Catppuccin Mocha-derived dark, Catppuccin
Latte-derived light) built from appearance.rs’s own public fields,
composited over a genuine Omarchy theme wallpaper image (decoded through
the production background_decode::BackgroundCache, round 3’s own
addition — passed as a command-line path, not embedded), plus two
drag-mechanic captures driven through HomeScreen’s real public
down/motion/tick/external_drag_motion API; verify with
cargo run --offline --example render_widget_evidence -- <dir> <dark-wallpaper> <light-wallpaper> and by looking at every produced
image.docs/evidence/home-widget-design/
(10 distinct captures: 4 clock styles, battery present/absent, weather,
overview, widget picker, and 2 drag-mechanic captures — the drag
mechanics captured once, in the dark theme only, since they are
theme-independent) with a README explaining the harness, the revision
history across all three passes, what each image shows, and what this
evidence class does and does not prove; blob-inventory rows updated for
all 20 (replacing the 18 from the prior pass); verify with
python3 tools/blob-scan.py exiting 0. Done: exit 0, “every binary is
accounted for”.docs/design/clock-widget-research.md: twelve surveyed clock-
widget designs (Pixel bubble/thin/At-a-Glance, Nothing OS Ndot, iOS
StandBy, Samsung One UI/Adaptive Clock, Material You, KWGT/KLWP, Braun/
Dieter Rams, r/unixporn/Omarchy desktop rices), each with sourced links
and a stated design principle taken from it (never a copied asset), plus
a synthesis table mapping each of the four shipped styles to the
principles behind it and the font-decision section design.md
decision 6 cites.docs/evidence/home-widget-design/closeout-2026-10-01/qemu/README.md; blob inventory passes.cargo test --offline (full workspace) and
cargo clippy --offline --all-targets; verify their exit codes directly,
re-run after each of the three passes described in task 2.3. Done (round
3, final): 382 lib tests + 60 integration tests pass, 1 pre-existing
ignored test unaffected; clippy exits 0 — the four new multi-argument
functions round 3 added (draw_layout_halo, draw_dot_matrix_glyph,
draw_dot_matrix_time, plus hero_glow/caption_glow carried forward
from round 2’s own allow) all carry their own
#[allow(clippy::too_many_arguments)], and the pre-existing warning set
(overlay_brush/text_weight/service_card/paint_icon_plate’s
too-many-arguments, theme_ui.rs/wifi_ui.rs’s field-reassign-with-
default, one pre-existing assertions-on-constants in home_grid.rs, one
pre-existing manual-implementation-of-ok and one useless-vec! deeper
in render.rs) is unchanged and does not originate from any line this
change touched.nix build .#handheld-shell-rust --max-jobs 1 --cores 6 --no-link --print-out-paths.
Done (round 1): /nix/store/79l3ny61f523skmf06va1alpgxzcissq-k230-shell-rust-riscv64-unknown-linux-gnu-0.1.0.
Re-verified (round 3, final):
/nix/store/yxnfzw58v1mqlc26mayn5c77y6rrrfmq-k230-shell-rust-riscv64-unknown-linux-gnu-0.1.0.clockDisplayFont/fontconfig derivations round 3 adds; verify
with nix build .#nixosConfigurations.k230-coherent-shell.config.system.build.toplevel --max-jobs 1 --cores 6 --no-link --print-out-paths.
Done (round 1): /nix/store/65w36kvr1h8i0ym6i94x0nphgcryaar4-nixos-system-nixos-26.11.20260919.20b1ddd,
which the coordinator deployed to the board for the user’s judgment.
Done (round 2): /nix/store/7k1w73rjpb4b3s91d3h2sbdb5bg35cn0-nixos-system-nixos-26.11.20260919.20b1ddd.
Done (round 3, final, foreground): the build fetched and built
inter-4.1/inter-static-ttc/font-dirs/fc-cache/fontconfig-conf/
fontconfig-etc alongside the usual derivations, confirming the new font
actually integrates into the real cross-built closure, not just cargo build on the host:
/nix/store/fv2gvvq6q3s3q180qxwabin41lc76cdg-nixos-system-nixos-26.11.20260919.20b1ddd
(a host cross-build proof only; not deployed to the board or booted this
round).openspec validate the-home-screen-pages-fluidly-and-widgets-look-designed --strict.docs/evidence/home-widget-design/closeout-2026-10-01/board/README.md. The user delegated acceptance instead of repeating the earlier manual/photo sequence. No human-finger/daylight measurement is invented; battery attachment is conditional and not applicable to the current board.While a person holds a dragged Home item (an icon, a folder, or a widget) within about 40px of the panel’s left or right edge, Home SHALL show a visible themed highlight and a growing arrow at that edge, and SHALL turn to the neighboring page after about 350-400ms of continuous holding there. Continuing to hold at the edge past that first turn SHALL keep turning pages with a shorter repeat delay of about 260ms. Holding at the true last page’s right edge past that same dwell SHALL create a brand-new, empty page and slide onto it rather than remaining inert. Every page turn this triggers, and any triggered by a quick horizontal fling below, SHALL animate as a smooth slide, never an instant jump, and the dragged item’s own on-panel position SHALL continue following the raw finger position throughout, unaffected by the page transform. Page-count dots SHALL render enlarged while any drag is live. A quick, deliberate horizontal drag motion during a hold (independent of edge proximity) SHALL also turn one page immediately. A multi-cell widget’s drag hovering over a target it cannot fit SHALL show a visibly distinct “no room here” highlight instead of the ordinary accepting one.
The Clock widget SHALL offer at least four selectable visual styles,
researched from current mobile-platform and community widget design
(docs/design/clock-widget-research.md): a heavy centered stacked hour/
minute pair, a thin centered single time line, a procedurally drawn
dot-matrix readout, and a drawn analog face (ticks and hands only, no dial
fill or ring) with an accent-colored minute hand — each choosable from the
widget picker, which SHALL render a live preview of each widget kind’s
actual content inline in its own row. The Battery widget SHALL show its
charge as a themed ring with a distinct charging indicator when charging,
and its absent state SHALL pair the existing “No battery info” wording with
a muted outline battery glyph. The Weather widget SHALL show the current
temperature as a large numeral, a drawn condition icon distinct per
condition family (at minimum sun/cloud/rain/snow/fog/storm), the location
name when available, today’s high and low, and a short multi-entry forecast
strip when forecast data is available. No widget of any kind SHALL paint a
card background, surface fill, or border behind its content — every widget
sits directly on the wallpaper; legibility SHALL instead come from a halo
or glow computed from the theme’s own resolved color for that glyph (a
light halo behind a dark glyph, a dark halo behind a light glyph), never a
fixed shadow color that ignores which theme is active.
Archived change · Archived
Snapshot 5836ef1d113d · 2026-10-17 08:22 UTC
Closed recordCompleted: folder create, join, rename, member extraction, dock placement and widget picker verified.
the-shell-presents-a-pinned-home-screen (still unarchived) gave this
handheld a pinned-icon Home with pages, a dock, and long-press pin/unpin/
rearrange — and explicitly listed “folders or categories” and “home-screen
widgets” as non-goals for that pass. The user now wants both, plus a
specific correction to the pin gesture itself, in their own words: “i
wouldn’t want ‘long press to pin to home’ i want ‘long press to start the
process of dragging it where it will live on home’ and home should support
multiple screens i can swipe between like android bruh as well as widgets -
clock battery weather are the obvious firsts. same dealio for folders and i
can have folders in the ‘dock bar’ in theory.”
Three concrete gaps this closes:
k230-weather desktop entry and a themed rendering
pipeline capable of drawing exactly that content itself./sys/class/power_supply, a clean “No
battery info” state — this board currently has none, the fuel gauge lives
on a not-yet-connected keyboard base — and a 30s poll for one appearing),
and Weather (2x2, reuses the wttr.in source k230-weather already uses,
disk-cached and fetched at most every 30 minutes, offline-safe).HomeItem: App/Folder/Widget, each with its own footprint),
migrating an existing schema 1 file in place on load.Non-goals for this pass (see design.md’s Deferred section and
tasks.md): the widget picker sheet UI (long-press empty Home space to
choose a widget) and drag-a-widget-from-it; the open folder’s rename field
actually taking system-keyboard input (the rename data — buffer, apply,
cancel — exists and is tested, the keyboard grab is not wired); dragging an
app back out of an open folder onto Home; cached-layer/dirty-rect
rendering and prebuilding the drawer’s grid cache at idle (both explicitly
“if you can” in the task, not required); widget resizing (explicitly
“skip it if it’s costly”). None of these regress what already shipped in
the-shell-presents-a-pinned-home-screen.
Board dependency: every behavior above is host-testable and covered by
cargo test --offline with no hardware — the drop resolution, folder
create/join/dissolve, schema migration, and both widgets’ content logic
(including the battery-absent and battery-present cases, and the weather
cache’s fresh/stale/offline states) are plain Rust unit tests. The drawer’s
tick-driven long-press-arm and Home’s external-drag hand-off are also
host-tested at the state-machine level. A QEMU injected-touch trial of the
new drag/folder/widget interactions, and the physical-board real-finger
acceptance, remain open evidence gates for the coordinator (see task 6 and
tasks.md’s final section) — this proposal does not touch the board.
None. This extends the existing runtime/home-screen capability
(the-shell-presents-a-pinned-home-screen’s own new capability, still
unarchived — see that proposal’s own Modified Capabilities note for why a
MODIFIED delta cannot legally target it yet per
.skills/k230-spec-change/SKILL.md). This change’s own spec delta adds new
requirements to runtime/home-screen as ADDED, for the same reason: there
is nothing in openspec/specs/runtime/home-screen/ yet to modify.
None archived to modify. The sibling proposal’s own requirements (paged
grid, dock, pin/unpin/rearrange, seeding, persistence, tap-to-launch,
gesture topology) are superseded in spirit by this change’s drag-to-place
model and widened persistence schema — see design.md’s reconciliation
note for exactly which of that proposal’s scenarios this one revises in
place once both land, and the coordinator note left for whoever archives
first.
Userspace only, nix/rust-shell-client/: home_state.rs’s on-disk model
(HomeItem, schema 2 + migration), home_screen.rs’s drag/drop/folder
gesture logic, home_grid.rs’s span/folder-overlay geometry, a new
home_widgets.rs (battery/weather/clock content), navigation.rs’s
drawer long-press arming, render.rs’s Home/folder/widget painting and the
drawer’s drag-reveal rendering, and main.rs’s touch-dispatch wiring for
the hand-off plus the widgets’ poll/fetch scheduling. No kernel, device
tree, boot, radio, or second-core change; no new Nix package. The existing
.#handheld-shell-rust/.#card-shell outputs and the
k230-coherent-shell NixOS configuration absorb it.
the-shell-presents-a-pinned-home-screen shipped a paged icon grid, a
fixed dock, and long-press pin/unpin/rearrange, all backed by
home_state::HomeLayout { pages: Vec<Vec<Option<String>>>, dock: Vec<Option<String>> } — one desktop-entry id per cell, nothing else.
home_screen::HomeScreen drives a single touch contact through
home_pager::HomePager (page physics) and home_grid (slot geometry),
exactly mirroring navigation::DrawerNavigation’s own shape. render.rs
paints Home directly from that layout on every dirty frame; there is no
cached-layer/dirty-rect system anywhere in this client, only whole-surface
SHM repaints gated by a dirty flag per surface.
The drawer (navigation.rs) is a wholly separate Layer::Overlay Wayland
surface from Home’s Layer::Bottom. A touch that begins on one
surface is delivered to that same surface for its whole lifetime — Wayland
grants touch focus at down and does not reassign it — so a drag that
visually “moves from the drawer to Home” cannot be a real cross-surface
touch handoff; it has to be the drawer’s own touch continuing to arrive at
the drawer’s own listener while the drawer stops painting its own content
and Home (already always mapped underneath) shows through.
Goals: replace instant-pin with drag-to-place; extend pinning to folders
(grid and dock) and three widgets; widen persistence to carry all of it
with migration; do all of this without touching nix/card-shell/ (another
agent owns compositor-side rendering there concurrently) or the theme
picker.
Non-goals for this pass: the widget picker sheet, drag-to-place for widgets from a picker (only rearranging an already-placed widget is covered), a live system-keyboard grab for folder rename, dragging an app out of an open folder card, widget resizing, and cached-layer rendering. Each is called out below with why it was cut rather than silently dropped.
HomeItem replaces the bare id, with schema migration, not a rewriteenum HomeItem { App { id: String }, Folder(FolderData), Widget { widget: WidgetKind } }
struct FolderData { name: String, apps: Vec<String> }
enum WidgetKind { Clock, Battery, Weather } // span(): (4,2) / (2,2) / (2,2)
HomeLayout::pages/dock become Vec<Option<HomeItem>>. A multi-cell
widget stores itself only at its own anchor cell; the cells it also covers
stay None in storage but are excluded from “free” by walking every
anchored item’s own span() (home_state::occupied) — no redundant
“reserved” markers to keep in sync. HomeLayout::anchor_at resolves any
covered cell back to the widget’s anchor, so a tap/long-press anywhere in a
Clock’s 4x2 footprint hits the clock.
home_state::load tries the current schema first; on failure, tries the
old bare-string shape and converts every Some(id) to HomeItem::App. The
file itself is not rewritten until the next save, matching this client’s
existing best-effort-state conventions (home_state.rs’s own doc already
frames the state directory as “must not be silently dropped”, so a
migration that only touches memory, not disk, until an explicit save is the
conservative choice — a crash between migrate and save just re-migrates
next boot instead of losing anything).
Rejected: two separate code paths (one for “move an existing icon”, one for
“place a new one from the drawer”). Instead HomeScreen::drop_dragged_item
takes a DragSource (Existing(HomeSlot) or FromDrawer(String)) and
both funnel into the same merge_two/span/dock-eligibility decisions —
folder-create, folder-join, and same-span-swap-or-revert behave identically
regardless of where the dragged item came from. This also means the
“cancel a drawer drag” and “the drop happened to land nowhere resolvable”
cases share HomeLayout::place_first_fit as the same fallback the original
pin already used.
The old DrawerAction::LongPress fired at up(), after the finger already
lifted — fine for an instant pin, useless for a drag the person is still
supposed to be watching happen. DrawerNavigation::take_long_press_drag
is now polled every tick (mirroring HomeScreen::tick’s own long-press
timer exactly), fires once at LONG_PRESS_MS, and consumes the
contact (self.contact = None) the instant it fires — the rest of that
gesture belongs entirely to HomeScreen’s external-drag API from that
point on, and the navigation model’s own motion/up simply see no
contact and no-op. main.rs remembers which touch id this is
(drawer_home_drag: Option<i32>) and, for that id only, skips the
drawer’s ordinary scroll/close-drag/search dispatch entirely in favor of
forwarding straight into home.external_drag_motion/release_drag.
Rejected outright: reassigning the Wayland touch to Home’s surface
mid-gesture (protocol does not support it) and tearing down/reopening the
drawer’s layer-shell surface mid-drag (main.rs::hide() destroys self.layer
synchronously; a still-live touch bound to a since-destroyed wl_surface
would very likely be cut short by the compositor, and even if it were not,
begin_animated_close()’s own settle animation is the mechanism that
later destroys the surface, so starting it mid-drag races the drag itself).
Instead: while drawer_home_drag.is_some(), the drawer’s own draw()
skips its normal draw_with_hud call and paints a small, purpose-built
frame instead (RendererCache::draw_drawer_drag): fully transparent except
a translucent Cancel band across its former top-chrome zone. Home’s own
Layer::Bottom surface (already always mapped, underneath) keeps painting
itself exactly as it does for an on-Home rearrange — including the lifted
icon and drop-target highlight — so it simply shows through. This is a
real, correct “reveal”, just implemented as “stop drawing the top layer”
rather than an actual slide/fade transition. Deferred: an animated
slide/fade for the reveal itself (currently instant) and for the drawer’s
return-to-normal on Cancel (also currently instant) — both are pure
render.rs/main.rs polish with no data-model dependency, safe to add
later without touching this change’s own logic.
The drawer’s own top-chrome band is reused as the Cancel target (task: “a Cancel target at the top, or releasing over the drawer area”) — since the drawer’s grid is hidden during the drag, that top band is the one part of its surface that still reads as “the drawer” to release back onto, so a single zone serves both phrasings rather than adding a second, separate top-of-Home pill that would sit on the wrong surface entirely (the drop point is delivered to the drawer’s touch listener, not Home’s).
merge_two(dragged, existing) always keeps the item under the finger as
the survivor: an app dropped onto a folder joins that folder; a folder
dropped onto a lone app absorbs that app into the dragged folder, not the
reverse. This is one predictable rule instead of four direction-dependent
ones, and it matches where a person’s attention already is (the thing they
are actively carrying). Folder+folder does not merge (two folders’ worth of
apps combining unprompted felt like real data loss risk for a first pass);
it swaps positions instead, the same fallback any other non-mergeable,
same-span drop gets.
A folder dissolving at one member (HomeLayout::remove_app) is a property
of removal, not of the drag/drop path — it fires identically whether the
last-but-one app left via a drag-out, a future “remove from folder” action,
or (today, since drag-out-of-an-open-folder is deferred) nothing at all yet
actually reaches it outside tests. The logic is real and tested now so
whichever removal path lands next has nothing left to implement here.
Each WidgetKind gets exactly one span from the task’s own listed options
(Clock 4x2; Battery and Weather 2x2, the smaller of each pair’s two
choices, since a 4x2 weather tile would waste a full row’s width on two
fields). Resizing is the task’s own explicitly optional item and is cut
entirely for this pass — supporting it later needs per-instance span
storage (HomeItem::Widget would need to carry its own span override, not
just WidgetKind), a bounded but real follow-on.
Battery is a plain synchronous /sys/class/power_supply scan on a 30s poll
(the task’s own explicit fallback, since this board’s current hardware has
no supply device at all to inotify-watch yet — the fuel gauge lives on the
not-yet-connected keyboard base). It runs on the main thread: reading a
handful of small sysfs files is cheap enough not to need a worker.
Weather cannot run on the main thread — it shells out to curl against a
real network endpoint, and this client’s event loop is a single manual
poll (Cargo.toml’s own comment: “the event loop here is a manual poll,
not a calloop source”), so any blocking call on it would freeze every
surface for up to the fetch’s timeout. home_widgets::weather::refresh is
therefore only ever invoked from a short-lived std::thread::spawn,
reporting back through an mpsc::channel main.rs polls non-blockingly
each tick — spawned at most once per should_fetch window (30 minutes),
never per-frame. A stale cache is preferred over “Unavailable” on a failed
fetch (task: “Handle offline gracefully”).
render.rs::paint_home grew a widget-card path (paint_widget_card, a
themed plate plus the widget’s own live text/glyph) and a folder path
(paint_item_plate, a 2x2 mini-icon plate instead of a single icon) that
both slot into the existing per-frame whole-surface repaint —
[performance task 7’s “cached layers”/“clock redraws only its own area”]
are not implemented as actual partial-region compositing; there is
nowhere in this client’s architecture to hang that today (every surface
here is one SHM buffer repainted in full on dirty, not a stack of
independently-damaged layers). What is real: the clock does not drive a
60fps or even per-frame redraw — main.rs::tick_home_widgets schedules the
next minute-aligned wake itself (home_widgets::clock:: ms_until_next_minute) and only marks Home dirty then, so between minute
boundaries nothing about the clock causes a single extra repaint. Turning
that into a genuine sub-region repaint (and prebuilding the drawer’s grid
cache at idle, the task’s other performance item) are both real, separably
schedulable follow-on work, not implemented here — see tasks.md.
HomeLayout::place, span/occupancy) is what a picker would call, and it
is done and tested; the picker itself is cut for scope.home_screen::OpenFolder’s
editing_name/name_buffer/push_folder_name_char/
backspace_folder_name/apply_folder_rename are real and tested; wiring
a live wl_keyboard grab into the overlay (matching the Wi-Fi password
field’s own keyboard-interactivity request) is a main.rs integration
this pass did not reach.None of these block what already works: drag-to-place from the drawer, rearranging (including folder create/join and widget moves) on Home, folders opening/closing/dissolving, and both implemented widgets’ live content, are all real, wired, and tested end to end at the state-machine level.
home_state::load is the only place schema 1 and schema 2 ever meet: it
attempts to deserialize the current shape first, and only on failure tries
the old bare-string shape, converting every entry to HomeItem::App. No
separate migration command, no version-gated code path elsewhere in the
client — every other module only ever sees today’s HomeItem-based
HomeLayout. home_state::seed_default (fresh install, no saved file at
all) now also seeds one Clock widget onto the first page alongside the
existing curated app defaults, so a brand-new Home is not just an empty
grid with nothing that reads as intentional.
HomeItem, schema 2, migrationHomeLayout’s bare Option<String> cells with
HomeItem (App/Folder/Widget), bump SCHEMA to 2, and migrate a schema-1
file on load without rewriting it until the next save; verify with
cargo test --offline -p k230-shell-rust home_state. Done: 20 unit
tests, including round-trip and schema-1 migration.covered_slots/occupied/fits) so a
multi-cell widget blocks every cell of its own footprint, and
HomeLayout::anchor_at resolves any covered cell back to its widget’s
anchor; verify with the same home_state test run (widget-placement and
anchor_at cases included above).cargo test --offline -p k230-shell-rust seed_default.home_screen::merge_two (two apps merge into a folder, an app
joins a folder, a folder absorbs a lone app) and the shared
move_existing/place_new drop paths for both an on-Home rearrange and
a drawer-origin drag; verify with
cargo test --offline -p k230-shell-rust home_screen. Done: covers
folder-create, folder-join, dock placement (including a dock folder),
same-span swap fallback, widget span-aware move, and empty-page pruning.push_folder_name_char/backspace_folder_name/apply_folder_rename);
verify with the same home_screen test run.home_widgets::battery — injectable-root /sys/class/ power_supply scan, absent/present states, 30s POLL_INTERVAL; verify
with cargo test --offline -p k230-shell-rust home_widgets::battery.
Done: 7 unit tests including the absent-hardware case this board
actually has today.home_widgets::weather — disk cache, 30-minute
REFRESH_INTERVAL/should_fetch, wttr.in %C|%t parsing, offline
fallback to the last cache; verify with
cargo test --offline -p k230-shell-rust home_widgets::weather. Done: 9
unit tests including an injected-binary-failure “offline” case.home_widgets::clock — libc::localtime_r-backed formatting and
minute-aligned redraw scheduling; verify with
cargo test --offline -p k230-shell-rust home_widgets::clock.navigation::DrawerNavigation::take_long_press_drag: tick-armed
(not release-detected), consumes the touch on firing; remove the old
release-time DrawerAction::LongPress/instant-pin path entirely; verify
with cargo test --offline -p k230-shell-rust navigation.main.rs: drawer_home_drag: Option<i32> bound to the
armed touch id, forwarding motion/release into HomeScreen’s external-
drag API and bypassing the drawer’s ordinary scroll/close-drag/search
dispatch for that touch; the drawer’s own draw() paints only a Cancel
band while live (RendererCache::draw_drawer_drag), letting Home’s
already-live rendering (lifted icon, drop-target highlight) show
through; verify with cargo build --offline -p k230-shell-rust and
cargo test --offline -p k230-shell-rust. Done: 353 lib/bin tests + 60
integration tests pass; cargo clippy --offline --all-targets reports no
new warnings (pre-existing, untouched warnings elsewhere unaffected).render.rs: paint_widget_card (Clock/Battery/Weather content),
paint_item_plate generalized for App/Folder (2x2 mini-icon preview),
paint_open_folder (scrim, card, member grid, name label); verify with
cargo test --offline -p k230-shell-rust render.WidgetPicker/WidgetPickerPage in home_screen.rs,
picker_row_rect/picker_row_at in home_grid.rs, paint_widget_picker
in render.rs, all covered by unit tests (menu navigation, a Widgets-row
long-press-drag placing Clock via place_first_fit). “Wallpaper & style”
navigates to the existing theme/background chooser
(OpenWallpaperAndStyle -> ThemeIntent::Open) without touching any
theme-picker file. QEMU coverage: see task 6.4 — attempted, not
obtained this pass.sync_home_keyboard/forget_home_keyboard/handle_home_key in
main.rs mirror sync_wifi_keyboard exactly against
home_surface.layer (KeyboardInteractivity::Exclusive while
open_folder.editing_name), Enter commits
(apply_folder_rename)/Escape cancels (cancel_folder_rename). QEMU
coverage: see task 6.4 — attempted every way described there, not
obtained this pass; the code path is exercised only by cargo test
today.DragSource::FromFolder { folder, app_id } unifies through the
same drop_dragged_item engine as every other drag source; releasing
back onto the folder’s own icon cancels (distinct from releasing
anywhere else on the open card). Covered by
dragging_a_member_out_of_an_open_folder_onto_home_removes_and_places_it
and neighbouring unit tests. QEMU coverage: see task 6.4 — not attempted
this pass (sequenced after the rename scenario that would not complete).RendererCache::prebuild_drawer_grid wired
after startup, after a catalog rescan, and after a theme
commit/rollback; RendererCache::draw_drawer_reveal (ease-out-cubic
slide+fade of a captured snapshot) replaces an instant vanish on
long-press hand-off, kept cheap (translate a cached image, not a
re-render). Board-measured baseline this fixes:
K230_DRAWER_FRAME ms=549.89 on first open vs 1.04 afterward
(docs/design/app-drawer-review.md’s own performance section).cargo test --offline (full workspace) and
cargo clippy --offline --all-targets; verify their exit codes directly.
Done: all tests pass, no new clippy warnings.nix build .#handheld-shell-rust --max-jobs 1 --cores 6 --no-link --print-out-paths.
Done: /nix/store/xyh2paw8j216zda8ad8fqwpz58v2l59r-k230-shell-rust-riscv64-unknown-linux-gnu-0.1.0.nix build .#nixosConfigurations.k230-coherent-shell.config.system.build.toplevel --max-jobs 1 --cores 6 --no-link --print-out-paths.
Done: /nix/store/z23fr90qkv8azcawzvi75kh143fp0ggg-nixos-system-nixos-26.11.20260919.20b1ddd
(a host cross-build proof only — not deployed to the board or booted).docs/evidence/home-widgets-folders/closeout-2026-10-01/qemu/README.md. Additional mapped-app rename regression passes in its rename-over-app/ subdirectory. The previously stalled rename was a keyboard/focus bug, now fixed; historical failed attempts remain in the earlier report.docs/evidence/home-widgets-folders/closeout-2026-10-01/board/README.md. Prior operator finger acceptance and new injected board checks are distinguished explicitly. The user delegated acceptance in place of the former repeat manual/photo sequence. Attached-battery acceptance is conditional and not applicable because no battery is present.openspec validate the-home-screen-has-widgets-and-folders --strict.Define the touch-operated Home layout: exact app and widget placement, paged rearrangement, folders in the grid and dock, system-keyboard naming, and theme-aware clock, weather and battery widgets.
Long-pressing an installed application’s tile in the drawer SHALL lift that application’s icon to follow the finger instead of pinning it immediately, and Home SHALL be revealed underneath while the drag is live. Releasing over an empty grid cell or dock slot SHALL place the item there. Releasing over an already-pinned application SHALL create a new folder containing both. Releasing over an existing folder SHALL add the item to it. Releasing over a Cancel target, or over the area the drawer’s own chrome occupied before the drag began, SHALL abandon the drag with no change to Home. Holding the dragged item near the panel’s left or right edge for about 500ms SHALL turn Home to the neighboring page, or add a new page when held past the last one.
Long-pressing an item already on Home (an application, a folder, or a widget) SHALL enter the same drag as a drawer-originated one, resolved by the same cell/folder/dock/edge-page-switch rules, plus a Remove target that unpins the dragged item from Home without uninstalling it. A page left with nothing pinned to it after a move SHALL be removed automatically, except that Home always keeps at least one page even when it is empty.
A folder SHALL display as a single rounded tile showing up to four of its members’ icons in a 2x2 arrangement. Tapping a folder tile SHALL open an overlay showing every member application in a grid and the folder’s name. The folder’s name SHALL be editable. Removing an application from a folder that would leave exactly one member SHALL dissolve the folder, leaving that one application pinned directly in the folder’s former cell.
Home SHALL support placing a Clock widget, a Battery widget, and a Weather
widget, each occupying a fixed cell span, rendered by the shell itself
rather than delegating to an external application. The Clock widget SHALL
show the current time and date in the active theme’s colors, updating at
least once per minute, aligned to the minute boundary. The Battery widget
SHALL show a clean “no battery info” state when no battery device is
present, and SHALL reflect a battery device that later appears without
requiring a restart. The Weather widget SHALL show a condition indicator
and the current temperature from the same source k230-weather already
uses, fetched no more often than every 30 minutes, cached to disk, and
SHALL continue showing its last successful reading when offline rather
than an error or a blank tile.
power_supply class device of type
BatteryThe on-disk Home layout SHALL record folders (their name and member application ids) and widgets (their kind) alongside plain pinned applications, for both grid pages and the dock. A layout file written by an earlier version of the shell that predates folders and widgets SHALL load successfully, with every previously pinned application preserved in its existing cell.
Archived change · Archived
Snapshot 5836ef1d113d · 2026-10-17 08:22 UTC
Closed recordAccepted and archived; no remaining Wi-Fi Settings work.
A person can see only a read-only network-link row in Settings today. Joining or changing Wi-Fi requires a root console procedure, so the handheld cannot set up its own connection through touch.
None.
radio/wifi: Add touch provisioning, saved-network management, and secret-safe service behavior to the existing protected runtime and persistent Wi-Fi capability.The system’s Wi-Fi service and a protected broker, Settings backend, Rust shell service worker and Settings rendering, and focused host/QEMU and physical evidence. The broker reuses /var/lib/k230/wifi/wpa_supplicant.conf and the k230-wifi.service credential boundary. The coherent-shell Settings proposal remains the parent navigation and visual contract.
Open and WPA2-Personal networks on the existing wlan0 path are in scope. Enterprise credentials, captive-portal login, hotspot mode, and hidden-network manual entry are not. Host tests and QEMU can prove parsing, state, focus, and touch behavior; only the physical board can prove scanning, association, reconnect after reboot, and real-glass keyboard usability. Those gates remain unverified until observed.
See proposal.md. nix/hardware.nix already defines k230-wifi.service: wlan0, root-private /var/lib/k230/wifi/wpa_supplicant.conf, systemd LoadCredential, and a root-only supplicant control directory. tools/device_settings.py reports only link state. The Rust shell has an asynchronous Settings worker and touch-routed Settings panel. Existing physical evidence in docs/evidence/wifi-persistent/ proves operator-installed persistence, not Settings-driven setup. Stage 1, kernel, device tree and radio driver remain unchanged.
Goals: A usable 568×1232 touch route, no terminal procedure in the user flow; strict secret and service ownership; bounded asynchronous work; safe coexistence with the already proven persistent service; inspectable host and physical gates.
Non-Goals: Enterprise/EAP, hidden-network manual entry, captive-portal login, hotspot mode, or a claim that association proves Internet access. Do not make the unprivileged shell a network administrator.
A small root-owned userspace broker owns Wi-Fi changes. A private local socket accepts bounded typed scan/status/connect/forget messages from the shell session UID, authenticates peer credentials, rate-limits scans and connection attempts, and emits bounded typed results. A fresh image has no credential and therefore no active supplicant: the broker first brings wlan0 up using fixed ip arguments, then scans with fixed iw arguments. The service never shells out with SSIDs or passwords in argv; diagnostics use fixed error codes. The wlan0 and root-only supplicant control paths remain authoritative. Rejected: direct wpa_cli from the shell (root-only socket and privilege), sudo from Settings (argv and authorization surface), or running a second supplicant (radio conflict).
Only the root broker writes persistence. It validates SSID bytes and supported security, writes a root-owned 0600 candidate file under /run, stops the existing service, and runs a private candidate supplicant for wlan0. It verifies candidate COMPLETED state before writing a root-owned 0600 temporary file in /var/lib/k230/wifi, fsyncing and atomically replacing the credential, then starts k230-wifi.service to consume its LoadCredential copy. A bounded set of eight saved network stanzas survives switching; an accepted connection replaces only its own stanza, and Forget removes only the selected stanza. Existing operator stanzas are preserved byte-for-byte when their identity and top-level format can be parsed safely; unknown global directives or ambiguous identities block mutation while retaining the previous file. Connection failure leaves prior configuration intact; start failure restores it. The shell sees network names and statuses but never stored secrets. Rejected: simultaneous supplicants, home-directory persistence or passing a credential through Nix/systemd unit environment.
The shell owns a Wi-Fi subview under Settings. Network opens a list with current/saved badges, a refresh action, and tap selection. The selected WPA2-Personal entry opens a masked editor; open networks skip password. Connect/Forget are explicit distinct actions. The editor has backspace, cancel and disabled/working states; the password buffer is cleared on exit, successful submit and route teardown. Worker requests carry monotonically increasing IDs, and the UI accepts only the active route’s matching reply. Rejected: relying on an external terminal.
Password entry originally drew its own in-app keypad rather than raising
the shell’s own system keyboard (wvkbd), because every layer surface this
shell owns requests KeyboardInteractivity::None (ensure_layer,
ensure_home, ensure_wallpaper): a deliberate, shell-wide policy so
chrome never contests keyboard focus with an application, not a security
requirement about this one field. wvkbd delivers keys as ordinary
wl_keyboard input to whichever surface currently holds keyboard focus,
so a layer surface that never requests it can never be that surface —
the keys had nowhere to go. The in-app keypad worked around that gap
instead of closing it, at the cost of a dense, easily mis-hit custom
keyboard glued mid-screen above Cancel/Connect, with duplicate Del/Delete
keys and a release/down-position hit test tight enough (an 18px combined
tolerance over ~50px-wide keys) to drop taps under ordinary fingertip
jitter.
Corrected: the overlay surface requests KeyboardInteractivity::Exclusive
only for the narrow lifetime of an unsaved WPA2-Personal password field
(WifiView::wants_keyboard), releasing it back to None the instant the
field is no longer active (Connect, Cancel, Back, or leaving Settings), so
the “never contest an app’s focus” policy still holds everywhere else.
The shell raises/lowers wvkbd itself through the same
k230-keyboard-gesture-signal helper the compositor’s own two-finger
keyboard gesture already uses (one show/hide path, not two), and reflows
Cancel/Connect to sit above the keyboard’s reserved height
(entry_buttons_rect, K230_KEYBOARD_HEIGHT) like Android’s
adjustResize. Typed text, Backspace, Enter (Connect) and Escape
(Cancel) all arrive as normal wl_keyboard key events
(wifi_ui::key_event_intent), through the exact same wifi_action
dispatcher a touch-hit intent already used.
Status is a staged state machine. A scan result is not association; association is not DHCP or Internet. The backend reports radio unavailable, scan pending/empty/failure, connecting, authentication failure, association, and saved state independently. Timeout and cancellation do not claim success. Long-running requests stay off the Wayland loop and bounded queues coalesce scans; no secret enters debug formatting or UI error strings.
A separate systemd recovery timer is armed before stopping the persistent service. The candidate remains in the broker service cgroup. If the broker crashes or exceeds the bounded attempt window, the timer stops that cgroup, restarts the previously saved service, and restores the broker. A normal completion cancels the timer only after service restart. The timer’s fixed arguments contain no network data.
sync_wifi_keyboard chokepoint, and unconditionally on seat keyboard-capability loss (forget_wifi_keyboard) rather than trusting that capability to still be there to release cleanly.Add the broker and Settings client without changing the credential-free default or existing operator file format. Install and host-test the isolated package, then cross-build the full closure. The root operator activates a recovery-capable image and tests open/WPA2 connection, Forget and reboot reconnect on the physical board. Rollback disables the new broker and restores the previous image; the existing root-owned credential remains usable by the proven service.
The physical operator found the Wi-Fi flow usable but requested an eye toggle to inspect touchscreen typos. Add explicit Show/Hide beside the field with a usable touch target. Keep masked entry as the default and reset visibility on every editor exit and new selection. Preserve the existing secret holder and focus lifecycle; public status/debug state may contain a visibility flag and length, but never the secret. A visible-field render is transient user-requested output, not permission to put its content in worker/debug messages, cache keys, logs or committed captures. Verify with a disposable sample rather than recording actual credentials. See docs/evidence/wifi-settings/operator-2026-09-30.md; broad positive feedback does not stand in for the unperformed reboot/Forget cases.
python3 -m unittest tests.test_wifi_settings_broker (host proof only).python3 -m unittest tests.test_wifi_settings_broker (host proof only).python3 -m unittest tests.test_wifi_settings_broker (host proof only).k230-wifi.service without changing the protected LoadCredential path; prove Nix unit values with tools/test-k230-wifi-persistent-service.sh and a narrow nix build .#wifi-settings-broker (build proof only). Host closeout proof (2026-09-30): docs/evidence/wifi-settings/closeout-host-2026-09-30/README.md and result.json record the successful commands and exact output paths; no board claim. 2.1 Add bounded typed asynchronous Wi-Fi scan/status/connect/forget worker responses with request IDs and secret-safe errors; prove stale replies, queue bounds and no-argv credential transport with cargo test --offline --manifest-path nix/rust-shell-client/Cargo.toml wifi_ (host proof only).
2.2 Add Settings Network list, current/saved badges, empty/loading/error/retry and selection routes; prove touch routing and scroll/reversal with cargo test --offline --manifest-path nix/rust-shell-client/Cargo.toml wifi_ (host proof only).
2.3 Add masked passphrase editor with correction/cancel and open-network skip; prove masking and secret teardown with cargo test --offline --manifest-path nix/rust-shell-client/Cargo.toml wifi_ (host proof only). Originally drawn as a dense in-app keypad glued above Cancel/Connect; see 2.6 for why and how that was corrected to the shell’s own system keyboard.
2.4 Add Connect pending/result and explicit Forget confirmation, preserving selected context and rejecting stale responses; prove fake-broker host tests and paired Sway QEMU touch capture with unshare -Ur python3 tests/rust_wifi_settings_qemu.py --sway <exact-Sway> --rust <exact-Rust-client> --theme-source nix/handheld-theme-default --output <private-output> (QEMU proof only; see docs/evidence/wifi-settings/README.md).
2.6 Replace the password field’s in-app keypad with the shell’s system keyboard (wvkbd): the overlay layer requests KeyboardInteractivity::Exclusive only while an unsaved WPA2-Personal field is active (WifiView::wants_keyboard, ShellClient::sync_wifi_keyboard), the shell raises/lowers wvkbd through the existing k230-keyboard-gesture-signal helper (K230_KEYBOARD_SIGNAL), and Cancel/Connect reflow above the keyboard’s reserved height (K230_KEYBOARD_HEIGHT, wifi_ui::entry_buttons_rect) like Android’s adjustResize. Typed text/Backspace/Enter/Escape arrive as ordinary wl_keyboard events mapped by wifi_ui::key_event_intent. Prove key mapping, the reflowed hit region and focus lifecycle with cargo test --offline --manifest-path nix/rust-shell-client/Cargo.toml wifi_ and cargo clippy --offline --manifest-path nix/rust-shell-client/Cargo.toml --lib --bins (host proof only); real keyboard-focus delivery and wvkbd show/hide on the physical board remain gated by 3.1.
2.5 Cross-build the integrated shell and system closure using nix build .#handheld-shell-rust and nix build .#nixosConfigurations.k230-coherent-shell.config.system.build.toplevel; record output identity, without claiming deployment (build proof only). Host closeout proof (2026-09-30): docs/evidence/wifi-settings/closeout-host-2026-09-30/README.md and result.json record the successful commands and exact output paths; no board claim.
2.7 Add a generously sized password eye toggle: entry is masked by default, explicit Show displays only the current unsaved input, Hide immediately remasks it, and leaving/re-entering the editor resets visibility. Preserve system-keyboard focus, cursor/edit contents and private credential transport; never expose saved secrets or copy displayed text into public/debug DTOs, logs, argv, environment or evidence. Verify visibility transitions, edit/Cancel/Connect/route teardown and secret-safe formatting with cargo test --offline --manifest-path nix/rust-shell-client/Cargo.toml wifi_, then cross-build nix build .#handheld-shell-rust. Prove the eye control and continued keyboard typing on the reserved physical board using a disposable non-secret sample before task 3.1 closes.
docs/evidence/wifi-settings/closeout-2026-10-01/README.md. New injected UI proof is distinguished from operator glass acceptance; no fresh radio/Forget sequence is claimed.The system’s shell userspace SHALL let a person open Network from Settings, refresh and scroll a bounded list of nearby networks, distinguish current and saved connections, select an open or WPA2-Personal network by touch, and return without changing connection. It SHALL show scanning, empty, unavailable, stale, and failed states without presenting a stale scan as current. It SHALL not equate association with Internet reachability.
The shell userspace SHALL offer masked password entry for a selected supported secured network using the same system keyboard every other text field in the shell uses (not a separate in-app keypad), mask entered characters by default, permit correction and cancellation, and show a bounded Connect pending state with a useful failure and retry route. The password field SHALL take real keyboard focus only for its own lifetime and release it immediately on Connect, Cancel, or leaving the page, so the system keyboard never contests focus with an application the rest of the time. Cancel/Connect SHALL remain reachable above the raised keyboard rather than hidden beneath it. The system SHALL pass a credential only through a private runtime channel to a privileged Wi-Fi service; neither side SHALL put the secret or a network identifier in command arguments, environment, Nix closure, tracked files, ordinary logs, or committed evidence. The shell SHALL NOT receive saved passwords back from the service.
The system SHALL save an accepted connection only in the existing root-controlled Wi-Fi credential location outside the image closure and use the existing runtime credential service to reconnect on later boots. Settings SHALL expose saved state and an explicit Forget action that removes the selected saved credential and stops automatic reconnect for that network. A failed, cancelled, or stale attempt SHALL NOT overwrite the last confirmed saved configuration.
Archived change · Archived
Snapshot 5836ef1d113d · 2026-10-17 08:22 UTC
Closed recordComplete: operator accepted ordinary/video card behavior; unperformed timing preserved in Planned interaction-jank followup.
Board evidence (docs/evidence/card-shell/video-card-gestures/) showed the
overview taking several seconds to enter, and touches going unacted-on,
whenever a video card was present and playing — because the video card’s
own mirror was expensive to recompose on every one of mpv’s frequent
commits. The fix that shipped for that (video-windows-become-ordinary-cards)
special-cased video specifically: a struct card.video_view flag, an
app_id check (video_app_id()), a frozen-thumbnail path that only engaged
for video under the opt-in SWAY_K230_CARD_SCALED_CACHE toggle, and a
compositor-side close hook (card_shell_video_stop() /
SWAY_K230_CARD_VIDEO_STOP) spawning k230-video-session stop so its
controller would not mistake a close for a decoder failure and relaunch a
fallback player.
The user’s stated principle: “there should not be any special-case shit for video right it should just show the window because it’s a compositor.” The actual cost driver — Pixman composite work for a small deck thumbnail whose source keeps committing new frames — is not specific to video at all: a game or a busy scrolling terminal commits just as often and would pay the identical cost once it sat in the deck. Special-casing video hid a generic performance problem behind an app_id check instead of fixing it, and left a second, needless special case (the close hook) that only exists because video’s controller cannot otherwise tell “the user closed my window” from “my decoder died.”
struct card.video_view, video_app_id(), and every app_id check in
nix/card-shell/adapter.c. Ordinary-card eligibility is decided
generically: a real transient/popup (an xdg_toplevel with a parent) stays
unmarked; a client that merely reports a fixed, non-resizable size (which
used to need the video carve-out to avoid wants_floating’s min==max-size
heuristic) is treated like any other ordinary app.card_shell_video_stop() (nix/card-shell/route.c/route.h) and
the SWAY_K230_CARD_VIDEO_STOP environment variable
(nix/shell.nix). Closing a card sends only the ordinary xdg_toplevel
close, for every app, with no compositor-side hook back to any
particular client’s launcher.nix/shell.nix’s separate video for_window rule into the single
generic ordinary-card rule (now matching any app_id, not just [tiling]
ones, so a client that maps floating due to a fixed-size hint — video’s
own reason for needing a second rule — needs no separate match either).SWAY_K230_CARD_SCALED_CACHE, previously opt-in and video-only-frozen)
to every card, and make it the shipped default:
nix/video-session.py (the video-launch controller, not part of
card-shell) replaces the removed stop hook with its own signal: it tracks
whether mpv ever printed a first-frame status line, and only falls back
to the software decoder when MVX failed before any frame was shown.
Closing the window (or any other post-first-frame exit) never relaunches
a fallback player.tests/test_card_shell_video_card.py,
tests/test_video_session.py, and tests/card_scaled_cache.c for the
above; the QEMU regression now proves mpv’s historical app_id gets no
special treatment, rather than proving a video-specific mechanism works.video-windows-become-ordinary-cards superseded where its task 2.1
(card_shell_video_stop) and task 3.1 (the video-only freeze) describe
mechanisms this change removes; that change’s own history is left intact.(none)
runtime/card-shell: card eligibility, close behavior, and the deck’s
live-preview cost model no longer vary by app identity; the downscaled,
rate-capped mirror path is the default for every card.nix/card-shell/adapter.c, nix/card-shell/route.c,
nix/card-shell/route.h, nix/card-shell/scaled-cache.c,
nix/card-shell/scaled-cache.h, nix/card-shell/render.c,
nix/card-shell/render.h, nix/shell.nix, nix/video-session.py.nix/card-composition-probe-client/card-composition-probe-client.c
(a stale comment only; the QEMU test fixture’s behavior is unchanged).tests/test_card_shell_video_card.py, tests/test_video_session.py,
tests/card_scaled_cache.c, tests/test_card_scaled_cache.py (unchanged,
exercises the same card_scale_rgb565 entry point with a new parameter).tests/test_card_shell_video_card.py,
tests/card_shell_runtime.py) and needs the physical board for the
performance claim itself (entry-animation and touch-latency targets with
a live video and a separate busy non-video app) — see design.md and
tasks.md for what is QEMU-provable versus board-only.nix/card-shell/adapter.c currently special-cases video in three places:
video_app_id() gates ordinary-card eligibility, struct card.video_view
gates a frozen-thumbnail path inside scaled_mirror (itself gated behind
the opt-in SWAY_K230_CARD_SCALED_CACHE, off by default), and closing a
video card additionally spawns $SWAY_K230_CARD_VIDEO_STOP stop
(nix/card-shell/route.c). Board evidence
(docs/evidence/card-shell/video-card-gestures/) traced the actual
overview-responsiveness problem to scaled_mirror/the raw mirror fallback
recomposing a card’s content on every client commit, which is expensive
under this compositor’s Pixman software path and has nothing to do with
the client being video specifically — any frequently-committing client
(a game, a busy terminal) pays the identical cost once it sits in the
deck.
Goals:
nix/card-shell/adapter.c,
route.c/route.h, and nix/shell.nix; card eligibility and close
behavior are decided the same way for every app.nix/video-session.py itself (first-frame-seen), since there is no
longer a compositor-side signal for it.Non-Goals:
feat/android-sized-cards (a concurrent branch); this change does not
touch card sizing or radius.runtime/video’s existing board evidence, beyond the relaunch-on-close
behavior this change fixes in the controller.cmd_card_shell’s ordinary
handler now excludes a container only when its view is an xdg_toplevel
with a parent set (con->view->wlr_xdg_toplevel->parent). This is
strictly narrower than the old wants_floating() check (which also
excluded any fixed-size, non-resizable window) and needs
#include <wlr/types/wlr_xdg_shell.h> for the full struct definition.
XWayland is disabled in this build (enableXWayland = false), so the
wlr_xdg_toplevel union member is always the live one.for_window rule. nix/shell.nix’s [tiling app_id="^(?!k230-video-...).+"]
and video’s separate [app_id="^k230-video-...$"] rule become one
[app_id=".+"] rule with no [tiling] qualifier, so a window that maps
floating for any reason (video’s own fixed-size hint, or any other
client’s) still reaches the same ordinary-maximized treatment.card_source_size() stays generic, unchanged in spirit. The
earlier fix (using a card’s real committed container box instead of
the client’s self-reported geometry for the entry-transition anchor
math) was already keyed on card_shell_ordinary_maximized, not app
identity; nothing about it needed to change for this proposal.scaled_mirror, keyed on
card_shown_large()/scene_in_motion(). Both are pre-existing
concepts (a card shown at full panel size, and the scene actively
animating) reused rather than duplicated: scene_in_motion() is
factored out of tick_impl’s own frame-scheduling gate so
scaled_mirror can share the exact same “is something moving right
now” answer.V: HH:MM:SS / ... only once a
decoded frame has actually been shown; nix/video-session.py already
parses stdout for a different diagnostic (truncated_http), so this
reuses the same PlayerOutput.feed() path rather than adding a new
IPC round-trip over mpv’s --input-ipc-server socket.wants_floating()’s combined heuristic; a genuine dialog-style app
that sets a fixed size but never sets a parent would now become an
ordinary card where it previously would not have. No such client is
known to exist in this shell today (checked: only mpv relied on the
fixed-size exclusion).first_frame_seen is a heuristic (mpv’s own terminal output format),
not a protocol guarantee; if mpv’s status-line format changes upstream,
the fallback-suppression could regress silently. Bounded risk: the
fallback is a safety net for a decode failure, not the close-detection
path anymore, so a false negative here only means an occasional missed
fallback, not a broken close.struct card.video_view, video_app_id(), and every
app_id check from nix/card-shell/adapter.c; replace the ordinary
command’s exclusion with a generic transient test
(con->view->wlr_xdg_toplevel->parent), keeping
card_shown_large()/card_source_size() unchanged (already generic).
Verify with a clean nix build .#card-shell --max-jobs 1 --cores 6.card_shell_video_stop() (nix/card-shell/route.c/
route.h) and SWAY_K230_CARD_VIDEO_STOP (nix/shell.nix); a card’s
close sends only the ordinary xdg_toplevel close, for every app.nix/shell.nix’s separate video for_window rule into one
generic [app_id=".+"] ordinary-card rule (no [tiling] qualifier).
Verify with nix eval .#nixosConfigurations.k230-coherent-shell.config.system.build.toplevel.drvPath.nix/video-session.py: track whether mpv ever printed a
first-frame status line (V: ...); only fall back to the software
decoder when MVX failed before any frame was shown. Verify with
python3 -m pytest tests/test_video_session.py -v (adds
test_mvx_exit_after_first_frame_does_not_fall_back).scaled_mirror (nix/card-shell/adapter.c): remove the
video-only frozen-thumbnail branch; every card not shown at full panel
size (card_shown_large()) is capped to about 15fps (66ms) of
recomposition instead, refreshed on every commit once due — never
frozen indefinitely. Add scene_in_motion() (factored out of
tick_impl’s own frame-scheduling gate) and use it to select a cheap
nearest filter while animating/dragging, bilinear at rest
(card_scale_rgb565’s new fast parameter,
nix/card-shell/scaled-cache.c/.h, threaded through
card_scaled_buffer_create, nix/card-shell/render.c/.h). Verify
with python3 tests/test_card_scaled_cache.py -v (adds a
nearest-vs-bilinear divergence assertion) and a clean
nix build .#card-shell --max-jobs 1 --cores 6.SWAY_K230_CARD_SCALED_CACHE=1 the shipped default
(nix/shell.nix).tests/test_card_shell_video_card.py for the single
generic for_window rule and the removed stop-hook assertion; it now
proves mpv’s historical app_id gets the same ordinary/switchable/
closable treatment as any other app, with no compositor-side
video-stop call to check for. Verify with python3 tests/test_card_shell_video_card.py -v (7/7 passes observed against
real cross-built Sway under qemu-riscv64-static).tests/card_shell_runtime.py’s focused()=='k230.card.two'
assertion (after a full horizontal drag then an immediate tap) raced
cs_up’s deliberate release-continuity coast (up to a 760ms settle,
nix/card-shell-policy/card-shell-policy.c) — a tap fired immediately
after release could land before the newly selected card reached center.
The test now waits past the documented worst-case coast before tapping,
and a second, independently found capture race in the same drag loop
(during-drag.png, grim run immediately after an IPC motion with no
wait for the next composited frame) now polls instead of asserting a
single screenshot. No compositor source changed. Verify with python3 -m unittest test_card_shell_scaled_cache_runtime -v (run from tests/;
both SWAY_K230_CARD_SCALED_CACHE=0 and =1 passed, reproduced clean on
three additional direct invocations). Root cause, fix and verification
recorded in docs/evidence/card-shell/runtime-tap-after-drag-race/ README.md.docs/evidence/proposal-closeout/2026-10-01/ordinary-cards.md, supplementing existing board-injected live-preview/switch/close evidence. Transfer the unperformed sub-400ms entry and sub-100ms touch-ack measurements to the-shell-profiles-reported-interaction-jank task 4.1, already landed before archive; neither timing target is represented as measured or passing.openspec validate the-card-shell-has-no-video-special-case --strict.Coordinator note (2026-09-28): video-windows-become-ordinary-cards archived
today (0 open tasks; openspec/changes/archive/2026-09-28-video-windows- become-ordinary-cards), creating openspec/specs/runtime/card-shell/ spec.md with a Requirement named “A video playback window is an ordinary,
closable card” that describes the app_id-keyed stop hook and video-only
thumbnail freeze this change already removes from source. This change’s own
delta spec (specs/runtime/card-shell/spec.md here) is currently authored
as ## ADDED Requirements under a different requirement name (“Card
eligibility, close, and deck-preview cost do not vary by app identity”),
which its own grounding text already says “generalizes and replaces” the
now-archived one. Whoever archives this change once task 5.1’s board
evidence lands should rewrite this delta as MODIFIED/REMOVED against
the now-existing “A video playback window is an ordinary, closable card”
requirement (per openspec/config.yaml’s archive guidance: “Check the
delta’s operation against what openspec/specs/ actually holds”), not leave
both requirements sitting side by side describing contradictory behavior.
Closeout reconciliation (2026-10-01): the contradictory archived video-only requirement is removed by this delta; generic behavior replaces it. Historical coordinator advice above is satisfied by the REMOVED/ADDED operations.
The card shell SHALL decide whether a window becomes an ordinary,
closable card, how closing it is signaled, and how its deck thumbnail is
kept live, without inspecting the window’s app_id or otherwise
special-casing any particular application. A window that reports a
fixed, non-resizable size (as mpv’s --geometry=WxH does) MUST NOT be
excluded from ordinary-card treatment on that basis alone; only a real
transient/popup (a toplevel with a parent set) is excluded. Closing any
card SHALL send only the window’s ordinary close request; the compositor
MUST NOT spawn an app-specific helper process as part of closing a card.
Grounding: nix/card-shell/adapter.c’s ordinary command handler and
cmd_card_shell’s CS_CLOSE handling (source read); this generalizes
and replaces the app_id-keyed behavior proposed in
video-windows-become-ordinary-cards (its task 2.1
card_shell_video_stop/SWAY_K230_CARD_VIDEO_STOP hook is removed by
this change). Physical-board injected close/live-preview proof: docs/evidence/card-shell/live-card-cost/README.md. Real-finger functional acceptance: docs/evidence/proposal-closeout/2026-10-01/ordinary-cards.md.
A card not currently shown at full panel size SHALL continue reflecting its source’s real, current content — never a frame frozen indefinitely — while bounding the compositing cost of doing so, for every application equally. The card shell MAY refresh such a thumbnail at a capped rate (about 15 times per second) instead of on every single client commit, and MAY use a cheaper resampling filter while the overview is actively animating or being dragged, reverting to the higher-quality filter once settled. A card currently shown at full panel size (focused full-screen, mid-entry, or expanded) MUST always reflect its most recent content with no rate cap.
Grounding: nix/card-shell/adapter.c’s scaled_mirror (source read);
this generalizes and replaces the video-only frozen-thumbnail behavior
proposed in video-windows-become-ordinary-cards (its task 3.1). Physical-board injected live-preview proof: docs/evidence/card-shell/live-card-cost/README.md; operator functional acceptance: docs/evidence/proposal-closeout/2026-10-01/ordinary-cards.md. Quantitative entry and acknowledgement targets remain UNVERIFIED and are retained in the-shell-profiles-reported-interaction-jank task 4.1.
Reason: The historical video-only stop helper and frozen-thumbnail behavior were removed; every app now follows the same ordinary close request and live deck-preview policy. Migration: Use the generic card eligibility/close and bounded live-thumbnail requirements added by this change. Existing video windows retain ordinary overview, gesture, focus and close behavior.
Archived change · Archived
Snapshot 5836ef1d113d · 2026-10-17 08:22 UTC
Closed recordCompleted: operator accepted continuous real-finger card interaction; existing probe collection and restoration evidence retained.
The existing launcher can page text metadata after release, but it cannot show a running application’s pixels, track a finger globally, shrink an app into a card, or close a thrown card. A real card deck needs a source-grounded route to application surfaces and input while preserving Sway as the single DRM owner.
runtime/card-composition-plan: specifies the evidence and interface gates for the selected visual application-card architecture.None.
Planning only. Host source audit and fixture work can proceed without the board; the two-app visual proof needs the board coordinator. A later implementation may add a pinned Sway patch only if the comparison selects it, and must not alter the default shell until the specified capability evidence exists. The sibling the-shell-manages-apps-as-cards change consumes this architecture boundary for product behavior.
The current launcher is a Wayland client and can render only its own SHM surface; it learns window metadata through Sway IPC. In contrast, the installed pinned wlroots 0.20 headers expose compositor scene surfaces, node position/input hooks, scene-output commit/frame completion, and presentation helpers (wlr_scene.h, wlr_presentation_time.h). The default shell explicitly sets WLR_RENDERER=pixman and Sway owns DRM through seatd. Existing VGLite evidence proves bounded private/imported buffers, not compositor integration.
Goals:
Non-Goals:
Compare client/protocol and compositor routes before selecting one. The audit first determines whether a viable existing protocol exposes live application surfaces plus global touch/focus ownership. A Wayland client cannot itself reparent another client’s wlr_surface or receive touch before Sway routes it, so the initial hypothesis is a narrow opt-in Sway patch. wlroots’ compositor-side scene API exposes wlr_scene_xdg_surface_create, node positioning, clipping, input acceptance, scene output commit and frame-done mechanisms. The route remains conditional on a pinned Sway source audit proving its container/seat hooks can own the required state. If neither route is safe, record a grounded negative result and mark product delivery blocked; do not substitute metadata cards.
Keep the renderer and DRM owner fixed. Sway remains the only KMS/DRM owner, WLR_RENDERER=pixman remains default, and the experiment is an explicit opt-in package/session. The existing VG-Lite CPU result justifies measuring an alternative later, not selecting it here.
Use a capability prototype before product work. It exposes only two eligible app surfaces, a card scene at the selected boundary, continuous single-finger motion, selection/expand, and a close request. It records per-surface lifecycle: mapped -> captured/scene-attached -> dragging -> selected or dismissal-requested -> restored/destroyed. A client buffer is referenced only while wlroots owns the surface; destruction, unmap, output leave and close/refusal cancel the card and restore focus safely.
Treat formats and completion as observed contracts. The probe logs Pixman buffer format, dimensions/stride, damage/commit and frame/presentation signals. It does not promise dma-buf, RGB565 texture import, or GPU cache/fence behavior. Any unsupported format, capture policy, or renderer operation ends the experiment and returns the normal session.
Separate architecture from product UX. This change neither waits on nor supplies the interaction policy in the-handheld-has-a-coherent-ux-plan. The sibling card-product change consumes this route decision plus the independently agreed UX contract; no dependency points back to it.
The architecture experiment must publish: an opt-in entry condition; eligible-surface policy; stable card IDs owned by the selected boundary; lifecycle events; touch/focus ownership during drag; exact close request/refusal/exit states; fallback/abort behavior; renderer/format and completion observations; and evidence paths. The product change may request card behavior only through those published events, never by opening DRM, copying private application data, or assuming thumbnails, GPU, or zero-copy.
Ship no default behavior. Build/run the probe only by explicit opt-in; remove its package/patch or decline to enable it to return to the existing Sway session.
tools/audit-card-composition-sources.py to resolve and report derivation/source inputs for .#shell-compositor and .#touch-launcher, then audit client protocol, Sway seat/container, and wlroots scene/frame/presentation hooks; verify nix path-info --derivation .#shell-compositor .#touch-launcher, python3 tools/audit-card-composition-sources.py --flake . --output docs/research/card-composition-source-audit.md, and python3 tests/test_card_composition_source_audit.py.python3 tests/test_card_composition_contract.py docs/research/card-composition-architecture.md checks lifecycle/fallback fields and no dependency on the-handheld-has-a-coherent-ux-plan.openspec validate the-shell-has-a-card-composition-plan --strict (passes) and by
reading tasks 2.1-4.2 below, all of which record positive-route delivery,
not a blocked/not-pursued status..#card-composition-probe package exposing bin/card-composition-probe; if it selects Sway, expose the same executable and attribute using a source-built opt-in Sway package; verify nix build .#card-composition-probe --max-jobs 1 --cores 8 and python3 tests/test_card_composition_probe.py --mode selected without adding either route to the default image.python3 tests/test_card_composition_probe.py --case two-app-drag --case stale-destroy --case disabled and source checks show no DRM node open.python3 tests/test_card_composition_probe.py --case select --case close-refused --case app-exit --case keyboard-return leaves no scene node or focus orphan.tools/card-composition-board-session.sh with --probe, --restore-shell, --collect, and --verify-restored modes. For a client route it keeps normal Sway as sole DRM owner; for a Sway route it stops normal shell, runs the opt-in session as sole DRM owner, and restores the known normal shell in cleanup. Verify with probe_path=$(nix build --no-link --print-out-paths .#card-composition-probe) followed by tools/card-composition-board-session.sh --probe "$probe_path/bin/card-composition-probe" --restore-shell, recording session ownership with no concurrent DRM owners.docs/evidence/card-composition-board/README.md, plus the operator’s explicit real-finger verification in docs/evidence/proposal-closeout/2026-10-01/card-composition.md. The operator waives a duplicate isolated run; no new capture or quantitative measurement is claimed.systemctl is-active shell seatd, a concise board capture, and tools/card-composition-board-session.sh --verify-restored pass. Do not require unchanged invocation IDs across planned stop/start.the-shell-manages-apps-as-cards; verify its scope consumes only the published contract and makes no unsupported live-card claim.openspec validate the-shell-has-a-card-composition-plan --strict, named host tests, ./tools/blob-scan.py --no-vendor, and python3 tools/work-status.py; verify media and source-built artifacts have named provenance before any default-shell proposal.Host implementation proof for 2.2–2.3 is committed in
docs/evidence/card-composition-headless/README.md: actual cross-built Sway
under headless QEMU user emulation, real Wayland clients and virtual keyboard,
with explicitly injected card input. This does not complete any task in group 3
or establish physical finger/OSK/panel behavior. Task 1.3 is conditional on a
negative route finding; this route has passed host capability checks.
Board injected capability and restored Apps/keyboard/Terminal proof are committed
in docs/evidence/card-composition-board/README.md. Group 3.2 was subsequently accepted by the operator on 2026-10-01; see
docs/evidence/proposal-closeout/2026-10-01/card-composition.md. Previously missing
continuous real-finger tracking is now operator-reported; the complete IPC-injected sequence passed on
RGB565/Pixman, including live parent/subsurface updates and presentation signals.
The negative branch in 1.3 is not applicable to the selected positive route; no
negative-result test is being claimed. Physical limits remain explicit before archive.
Defines the evidence gates and safe ownership boundaries for an opt-in visual application-card composition experiment in the handheld shell.
The system SHALL retain one Sway-owned DRM/KMS presentation path while a card experiment is active. Before a visual-card implementation is selected, the project SHALL compare existing client/protocol and narrow compositor routes using pinned source evidence for application-surface composition, touch routing, focus return, frame completion, and presentation reporting. A client-only metadata overlay SHALL NOT be represented as live application-card composition.
If the architecture decision establishes a viable route, an opt-in prototype SHALL prove two simultaneously running application surfaces visually represented in a single card scene, continuous finger tracking, adjacent-card selection and expansion, and a dismissal request with an explicit close-refusal outcome. It SHALL preserve keyboard focus and the existing usable Pixman session on failure. A grounded negative decision SHALL state that product delivery is blocked, not call the capability delivered.
The prototype SHALL record CPU, memory, frame/presentation evidence, pixel format, buffer lifetime, and synchronization observations separately from host models. It SHALL not claim GPU acceleration, zero-copy, or full card UX acceptance unless those observations demonstrate them.
Archived change · Archived
Snapshot 5836ef1d113d · 2026-10-17 08:22 UTC
Closed recordClosed on operator acceptance; see evidence for waived captures and retained limits.
Tapping an app in the drawer, on Home, or in the dock today leaves whatever was already on screen visible while the process starts. On this hardware that gap is not instant: icon/catalog work, process exec, and the new client’s own Wayland handshake all take real time, so a person sees the previous app sit there, unresponsive to their tap, before the one they asked for finally appears. Nothing tells them the tap registered.
.desktop Icon= key, via the
existing icon.rs/librsvg path), and the app name below it. The backdrop
paints fully opaque on its very first frame; only the icon/name ease in
over ~220ms, so the previously active app is never uncovered even
momentarily.window event subscription (no swayipc crate
existed in this client before), matched against the spawned process’s pid
(captured via gio::AppLaunchContext) or its bounded /proc ancestry —
covering Terminal=true entries and other one-hop indirection, which map
as their terminal’s own app_id, not the launched entry’s.Pending becomes TimedOut (“Taking
longer than usual…”, tap to dismiss or return Home) after about 10s with
no matching window, and a spawned process exiting before any window maps
shows “Couldn’t open ” and dismisses itself shortly after (or on a
tap).nix/card-shell/adapter.c needs no
change, because the overlay already composites above every ordinary
toplevel, and never unmapping it during the transition is what removes
the flash. design.md records why this was chosen over a card-shell
placeholder.Non-goals: a grow-from-the-tapped-icon-rect scale animation (considered
and rejected for this hardware’s cost budget — see design.md); a
notification/toast system; any change to the drawer/Home/dock catalog,
gesture, or window-switching behavior beyond what a launch’s own splash
needs; a compositor-side placeholder-card implementation.
runtime/shell: launching a desktop entry now shows an instant splash
with icon/name, hands off on the real window mapping, and exposes
explicit timeout/failure states, superseding the previous “leave a
visible explanation” wording for a launch failure with the concrete
splash-based one.Affects nix/rust-shell-client (splash.rs, sway_ipc.rs are new;
main.rs, render.rs, icon.rs are modified) and its own test suite. No
device tree, kernel, boot, or card-shell/adapter.c change. Host build and
cargo test/cargo clippy can (and did) complete without the board; a
QEMU harness proves the splash paints and hands off under the headless
Pixman backend, but only the physical board proves real-glass timing,
touch-dismiss feel, and that the previous app is never perceptibly
uncovered on real hardware. Both remain open until that evidence exists.
The operator accepts this delivered functional scope and waives additional
capture-only acceptance gates. docs/evidence/proposal-closeout/2026-10-01/splash.md records the exact report,
prior evidence and limits. Its task dispositions supersede older statements
that these acceptance gates remain open; they do not claim new test runs.
Focus behavior in this accepted implementation applies to identifiable running Home/dock entries. The drawer still uses its existing launch path; shared GNOME activation and New Window menus remain planned in the Home change, group 11. The closeout does not claim those future actions are installed.
nix/rust-shell-client/src/main.rs already launches installed desktop
entries: launch_app (drawer taps) called self.hide() before spawning
launch_selected, which re-parses the .desktop file with
gio::DesktopAppInfo::from_filename and calls app.launch(&[], None).
launch_home_app (Home/dock taps) calls focus_or_launch, which looks up
running_con_id over swaymsg -r -t get_tree and focuses it, or falls
through to the same launch_selected. hide() drops the shared
Layer::Overlay LayerSurface (self.layer) entirely, unmapping it, which
is what let whatever card was already focused show through, unstyled and
unresponsive, until the new app’s window happened to map. Neither path knew
when a launch actually finished; a Home-only launch_started/launching
pair drove a blind 3-second “reopen the drawer” fallback that fired whether
or not the app was about to succeed.
icon.rs’s IconCache::paint(cr, icon, size, x, y) already resolves a
desktop entry’s Icon= key (through the installed freedesktop icon theme,
including scalable SVG via librsvg) and paints it into any Cairo context at
any size, with its own bounded per-size decode cache; it needed only a
raised size cap (128px -> 192px) to admit a “large” 176px splash icon.
render.rs already has a proven pattern for a cached, geometry-keyed
bitmap repainted cheaply every frame (RendererCache::draw’s
static_pixels) and an eased-alpha convention for a full-screen dim
(tray_backdrop_alpha). Nothing in this client had ever spoken sway’s own
IPC protocol directly before this change — every existing use
(running_con_id, focus_con, swaymsg_back) shells out to the swaymsg
binary. tests/card_shell_runtime.py’s own ipc() helper proves the wire
format this change’s sway_ipc.rs reimplements in Rust: i3-ipc magic,
then a native-endian u32 length and u32 type, matching sway-ipc(7)’s
documented framing exactly; sway-ipc(7) also documents that a window
event’s container.pid is “the PID of the application that owns the
window”, and a window/new event’s container already carries it.
Goals: a full-screen splash within one frame of a tap, in every launch
entry point (drawer, Home, dock); the theme’s real background colour and
the app’s own icon/name, never a placeholder; the previously active app
never visible in between, even for one frame; a real hand-off the instant
the launched window maps, detected without relying on app_id (which a
Terminal=true entry defeats, since it maps as its terminal, not the
launched entry); explicit, recoverable timeout and process-exit states;
cheap on a single slow RISC-V core running a software (Pixman) compositor.
Non-Goals: a grow-from-the-tapped-icon-rect scale animation (see
Decision 3); a compositor-side (adapter.c) placeholder card (Decision 1);
any change to which apps exist, how the drawer/Home/dock lay them out, or
how window switching/gestures behave once an app is showing; a generic
sway-IPC client library (only window/SUBSCRIBE are implemented, and
only as much of each as the splash needs).
The splash lives in the Rust client, on its existing overlay surface
— not a compositor-side placeholder card in nix/card-shell/adapter.c.
The client already owns one Layer::Overlay LayerSurface shared by the
drawer/shade/Settings/theme-chooser (self.layer), and Layer::Overlay
already composites above every ordinary toplevel by construction. That
means the flash was never a compositor ordering problem — it was this
client tearing its own surface down (hide()) before the replacement was
ready. Keeping that same surface mapped and simply repainting it as the
splash (start_splash, replacing the old self.hide() call in
launch_app) removes the flash with no adapter.c/card-shell-policy.c
change at all: nothing about focus handoff, view mapping, or z-order
needed to move, because the overlay already sat on top of the view that
would otherwise flash. A card-shell placeholder was considered and
rejected: it would duplicate icon/name rendering in C
(nix/card-shell/render.c/icon.c have their own separate Cairo-less
drawing path), need a new IPC message from the Rust client to the
compositor naming which card is “the splash”, and still leave the Rust
client needing its own window-map detection to know when to ask the
compositor to remove that placeholder — strictly more moving parts for
the same outcome. The trade-off: a Home/dock-triggered splash must call
ensure_layer, which is not free (an xdg_surface-style configure
round trip before the very first attach), so that path’s first frame is
one Wayland round trip later than a drawer tap’s (whose overlay is
already mapped and configured). That is still well under one visible
frame on a local Wayland connection and nowhere near what it replaces
(an uncontrolled, multi-hundred-millisecond process-start gap).
Window-map detection subscribes to sway’s own window IPC event and
matches by pid//proc ancestry, not app_id. gio::AppLaunchContext
emits its launched signal synchronously inside app.launch(...) itself
(a direct g_signal_emit, not scheduled through a GMainContext) —
proven against the real glib/gio runtime in
route_tests::launch_selected_captures_the_real_spawned_pid_with_no_glib_main_loop_running,
not just reasoned about, since this client runs no glib main loop at all.
platform_data’s pid key (present since glib 2.72, for a launch GIO
itself spawned) is captured into a Cell the closure can reach, with no
Mutex/thread-safety needed since it never leaves the launch call.
sway_ipc.rs is a from-scratch, minimal client (write_message/
try_parse_frame/watch_window_events) matching the wire format
tests/card_shell_runtime.py’s Python helper already proves against a
live sway; adding the swayipc crate was rejected as unnecessary weight
for “subscribe to one event type and read change/container.pid”.
Matching walks a bounded (4-hop) /proc/<pid>/stat ppid chain
(splash::pid_or_ancestor) rather than only exact-pid equality, covering
a Terminal=true entry (which GIO/the desktop file’s own Exec spawns as
the configured terminal directly — that terminal process is the
window’s owner, so an exact pid match already covers the common case)
and any one-hop shell-wrapper indirection a quoted Exec= can add. When
GIO reports no pid at all (a launch whose platform_data never carried
one), the target degrades to SplashTarget::LaunchOrder: match the next
window/new event, full stop — sound only because launch_in_flight
already serializes this client to one launch at a time, so there is
never a second candidate to confuse it with. A process-liveness check
(sway_ipc::process_alive, a plain /proc/<pid> existence check) runs
alongside the IPC watch so a process that exits before mapping anything
is detected without waiting for SPLASH_TIMEOUT.
Motion is an opaque-backdrop-first icon/name fade-in, not a
grow-from-the-tapped-icon-rect scale. The task’s own preference was
“ideally grows from the tapped icon’s rect … at minimum fades in
quickly”. A grow animation needs the tapped icon’s exact on-screen rect
threaded out of whichever grid computed it (drawer or Home/dock, two
different layout modules), a per-frame scaled/clipped repaint of the
whole composed splash bitmap, and touches this hardware’s one slow
RISC-V core doing everything through Pixman software rasterization was
explicitly asked to keep cheap. Instead: render.rs’s
ensure_splash_bake paints the theme background colour plus every line
of text into a (name, width, height, status)-keyed bitmap exactly
once (rebuilt only when one of those four actually changes, e.g. a
Pending -> TimedOut status transition); this bake is unconditionally
opaque, so the previously active app cannot show through even during
the fade. draw_splash then composites only the icon on top each frame,
through IconCache’s own existing per-size decode cache (so re-painting
it every frame is already a cheap cached blit, not a redecode), ramped
through an ease-out cubic alpha (splash::fade_alpha, mirroring the
existing tray_backdrop_alpha convention) over 220ms — inside the
requested 200-250ms band. This is one memcpy-sized backdrop copy plus
one small cached-surface composite per frame, an explicit, bounded cost
this hardware can sustain, versus an unbounded-resolution scale/clip
operation repeated every frame of the transition.
The pre-existing blind 3-second “reopen the drawer” timeout is
removed, not layered underneath the splash. It existed only because a
failed/stuck drawer launch had no other way to recover
(launching/launch_started existed for exactly this). The splash now
owns that whole story with real signals (LaunchOutcome, SplashSignal)
instead of a blind clock: TimedOut after SPLASH_TIMEOUT (10s, chosen
to clear an ordinary cold start — icon decode, catalog re-parse, process
exec, first frame — with room to spare) with an explicit tap-to-dismiss/
Home affordance, and Failed (immediately, from the real Err this
launch’s own thread already reports, or from SplashSignal:: ProcessExited) auto-dismissing after FAILED_AUTO_DISMISS (1.6s, long
enough to read “Couldn’t open ”, short enough that “dismiss” reads
as automatic). Keeping the old 3-second clock running underneath would
have raced the new one and reopened the drawer mid-splash for a launch
that was about to succeed.
Exec= that GIO spawns through an intermediate shell puts the
window’s owner more than one hop below the captured pid] -> the bounded
4-hop /proc walk covers this for any launch this client actually ships
(a hand-authored NixOS desktop entry, not an attacker-controlled one);
splash::pid_or_ancestor’s own tests cover exact, one-hop, and
bounded-multi-hop ancestry, plus a ppid cycle terminating instead of
looping.sway_ipc watcher thread’s own socket/IO failure leaves a Pending
splash with no further signal] -> deliberately degrades to
SPLASH_TIMEOUT rather than guessing at a false “process exited”; a
live process is never misreported as failed.adapter.c change means this fix is entirely dependent on
the client’s own overlay always compositing above every toplevel] ->
already a load-bearing invariant of the existing shell (the drawer/shade/
Settings would all have the same flash risk otherwise), not a new
assumption this change introduces.No data/format migration: this only changes what the Rust client paints
during a launch and how it decides a launch finished. Existing desktop
entries, icon themes, and the Home/drawer/dock layouts are unaffected.
Land the source change, host tests, and the QEMU splash-and-handoff capture
(tests/test_launch_splash_qemu.py, docs/evidence/launch-splash/qemu/)
together, then hand off to the board for the real-glass acceptance this
design cannot itself provide: splash timing/readability, touch-dismiss on
TimedOut/Failed, a real Terminal=true launch mapping and handing off
correctly, and confirmation that the previously active app is never
perceptibly visible during a real launch.
The operator accepts this delivered functional scope and waives additional
capture-only acceptance gates. docs/evidence/proposal-closeout/2026-10-01/splash.md records the exact report,
prior evidence and limits. Its task dispositions supersede older statements
that these acceptance gates remain open; they do not claim new test runs.
Focus behavior in this accepted implementation applies to identifiable running Home/dock entries. The drawer still uses its existing launch path; shared GNOME activation and New Window menus remain planned in the Home change, group 11. The closeout does not claim those future actions are installed.
adapter.c placeholder) and how a launched window is matched
without relying on app_id; record both in design.md. Verify: the
decisions are written down with the rejected alternative and why.nix/rust-shell-client/src/splash.rs: Splash/
SplashTarget/SplashStatus, fade_alpha, should_time_out,
should_auto_dismiss_failed, pid_or_ancestor, window_event_matches.
Verify: cargo test in nix/rust-shell-client (this module’s own tests
cover launch->mapped, launch->timeout, launch->process-exit,
already-running-needs-no-target, exact/bounded-descendant/cycle-safe pid
matching, and monotonic fade easing).nix/rust-shell-client/src/sway_ipc.rs: a minimal
hand-rolled i3-ipc client (write_message, try_parse_frame,
watch_window_events, parse_window_event, parent_pid,
process_alive) matching the wire format
tests/card_shell_runtime.py’s own ipc() helper already uses against a
live sway. Verify: cargo test (frame parsing on partial/complete/
malformed input, a real local Unix-socket round trip against a fake
“sway”, and parent_pid/process_alive against this host’s own real
/proc).gio::AppLaunchContext’s
launched signal in launch_selected; change launch_selected/
focus_or_launch to return a LaunchOutcome (Focused vs.
Spawned(Option<pid>)) instead of (). Verify: cargo test —
route_tests::launch_selected_captures_the_real_spawned_pid_with_no_glib_main_loop_running
proves the pid is captured from the real spawned process with no glib
main loop running on this thread (the riskiest assumption this task
makes, proven rather than assumed).launch_app’s self.hide() with start_splash, which
keeps an already-mapped overlay mapped (drawer taps) or maps it fresh
(launch_home_app, Home/dock taps) and repaints it as the splash
immediately; remove the old blind 3-second “reopen the drawer” timeout
in favor of the splash’s own SplashStatus transitions. Verify: cargo test (route_tests::*, unchanged existing tests plus the new ones)
and cargo clippy --all-targets with no new warnings.spawn_splash_watcher background thread (started once
LaunchOutcome::Spawned’s pid is known, not at the tap itself) that
subscribes to window events and reports SplashSignal::Matched/
ProcessExited back through an attempt-tagged channel, mirroring the
existing launch_sender/launch_results staleness pattern. Verify:
cargo test (spawn_splash_watcher_ignores_events_with_no_swaysock_and_ never_signals, splash_window_event_matches_by_pid_through_the_real_ thin_wrapper).render::SplashParams/ensure_splash_bake/draw_splash/
RendererCache::draw_splash: an opaque, name/geometry/status-keyed
cached backdrop plus a per-frame icon composite through the existing
IconCache, and raise icon.rs’s decode size cap (128px -> 192px) to
admit the splash’s 176px icon. Verify: cargo test (bake-rebuilds-only-
on-key-change, backdrop-opaque-on-first-frame, mismatched-canvas-
rejected, failed-message-baked-distinctly, plus icon.rs’s own new
176px-admits/oversize-rejects test).TimedOut/
Failed (input_region/down/up special-cases), auto-dismiss
Failed after FAILED_AUTO_DISMISS, and force a fast (~16ms) poll
cadence while the icon is still fading in. Verify: cargo test passes
with the full existing suite unchanged in behavior for every route this
did not touch.cargo test in nix/rust-shell-client — verify: all 274 tests
pass (221 lib + 18 route_tests (main.rs) + 14 appearance + 8
background_decode + 8 service_data + 5 theme_catalog), including every
new test this change adds.cargo clippy --all-targets in nix/rust-shell-client — verify:
no new warnings; every warning present afterward (theme_ui.rs,
wifi_ui.rs, theme_catalog.rs, service_data.rs, and one pre-existing
main.rs:950 redundant-closure) is in a file/line this change did not
touch.nix build .#handheld-shell-rust --max-jobs 1 --cores 6 —
verify: cross-builds to
/nix/store/71v0ssqfkp89yaw8ssxs2d08ysg97rbv-k230-shell-rust-riscv64-unknown-linux-gnu-0.1.0.nix build .#nixosConfigurations.k230-coherent-shell.config.system.build.toplevel --max-jobs 1 --cores 6 --no-link --print-out-paths
— verify: builds to
/nix/store/4mrxgn1n57a2v1dq17b01y9y10swhmg3-nixos-system-nixos-26.11.20260919.20b1ddd
(reran after rebasing onto integrate/apps-video-catalog’s later
card-shell commits, which changed this path from the pre-rebase run).python3 tools/blob-scan.py — verify: exits 0 (every binary is accounted for; this change adds only source files).tests/test_launch_splash_qemu.py (following
tests/card_shell_runtime.py/tests/test_rust_drawer_interaction_runtime.py’s
pattern: the unwrapped sway from nix-store -qR of the built
card-shell package, a private single-fixture desktop-entry catalog,
card_shell test-touch synthetic input), whose fixture Exec sleeps
then execs the existing card-composition-probe-client fixture under
a fresh --app-id (exec, not a fork, preserves the pid GIO reports
through to the pid that owns the mapped window, exercising the exact-pid
match path end to end). Verify: python3 tests/test_launch_splash_qemu.py --sway <sway> --swaymsg <swaymsg> --rust <k230-shell-rust> --client <card-composition-probe-client> --output <dir> — reproduced PASS twice;
committed screenshots and command in
docs/evidence/launch-splash/qemu/README.md, with blob-inventory rows
for all four PNGs (python3 tools/blob-scan.py exits 0).6.1 Record physical operator acceptance: launch splash works (2026-10-01), also reported fine on 2026-09-27. Retain existing QEMU/source evidence. Additional frame-timing/native capture is waived; this is not a measured one-frame latency result.
6.2 Accept functional launch splash with the operator report and existing process-identity/terminal launch source tests. A new recorded Terminal=true board launch is waived, not claimed.
6.3 Accept the delivered splash behavior using the operator report plus committed host timeout/failure tests. The requested artificial slow/failing physical launches and captures are waived; no newly observed physical fault injection is claimed.
openspec validate launching-an-app-shows-a-splash --strict passes.The updated completed tasks describe actual acceptance, waivers and scope
transfer, not execution of the superseded protocols. See docs/evidence/proposal-closeout/2026-10-01/splash.md.
Historical checkpoint notes above that say physical gates remain open are
superseded by this record. Quantitative or individually unreported results
are not promoted to physical proof.
Proof: openspec validate launching-an-app-shows-a-splash --strict; committed operator report;
python3 scripts/render_work_board.py --working-tree --output <snapshot.json>.
Grounding: docs/evidence/shell-features/desktop-launcher/README.md, its
console, PNGs and camera recording establish physical-panel discovery, launch,
refresh and error recovery using injected input. The user separately confirmed finger usability on 2026-09-22; normal source-image reboot persistence is demonstrated by the separate
image-launcher video and console, without restoring home-directory state.
The system’s Apps surface SHALL list visible application desktop entries from the user’s XDG data directories and Nix profile data directories, applying user-over-system precedence and desktop visibility rules. Reopening Apps SHALL reflect entries added or removed since the previous open. The surface SHALL provide readable application names and touch-accessible pages when the list exceeds the portrait display. Launching an entry SHALL preserve desktop-entry argument expansion and working-directory semantics. Terminal applications SHALL open in the configured terminal. A launch error SHALL leave a visible explanation and a usable Back control. The application grid SHALL present at least 4 columns of icons at this panel’s width, each icon at least 56 logical pixels square, with a single-line, ellipsized application name below each icon and no surrounding card or plate. An application with no resolvable icon SHALL show a round, theme-coloured fallback bearing its initial letter, rather than leaving the tile blank.
A launch SHALL show the instant splash defined below instead of leaving the previous app visible during startup. Terminal applications SHALL hand off the splash correctly despite mapping under the terminal identity. A launch failure SHALL use the splash’s recoverable failure state and a reachable return to Apps or Home, never an unexplained dead overlay.
Grounding: operator acceptance in docs/evidence/proposal-closeout/2026-10-01/splash.md, with prior source and board/QEMU evidence retaining their original classes and limits.
Tapping an installed application in the drawer, on Home, or in the dock
SHALL show a full-screen splash within one visible frame: the active
theme’s background colour, the tapped application’s desktop-entry icon
large and centred, and its name below the icon. The previously active
application or overlay SHALL NOT be visible at any point during this
transition, including momentarily. The splash’s icon and name SHALL ease in
over roughly 200-250 milliseconds; the backdrop itself SHALL be fully
opaque from its first painted frame regardless of that easing. The splash
SHALL remain shown until the launched application’s own window maps, at
which point the shell SHALL hand off to it as an ordinary running
application with no further splash. Matching that window SHALL NOT depend
solely on the launched entry’s own identity, since a Terminal=true entry’s
window maps under its terminal’s identity instead.
When a tapped Home or dock entry has an identifiable running instance, the shell SHALL focus that instance instead of starting a new process, and SHALL show the splash for no more than one round trip confirming that focus — never a splash lasting as long as a genuine cold start.
If no window has mapped after approximately ten seconds, the splash SHALL show an explicit “taking longer than usual” state offering a way to dismiss it or return Home, and SHALL remain until the user acts. If the launched process exits before any window maps, the splash SHALL show that the named application could not be opened and SHALL dismiss itself shortly after, without requiring a tap.
Terminal=true and its window maps
as the configured terminal rather than under the launched entry’s own
application identityArchived change · Archived
Snapshot 5836ef1d113d · 2026-10-17 08:22 UTC
Closed recordClosed on operator acceptance; see evidence for waived captures and retained limits.
plugging-in-hdmi-moves-the-display gives the board a mode where an
external monitor is the active output (1080p, rotated portrait) and the
built-in AMOLED panel goes dark. In that mode the GT9895 touchscreen is
still live silicon with nothing to point at directly: a person’s finger no
longer lands on anything it’s touching, since the picture is on a monitor
across the desk, not under the glass. Direct absolute touch-to-output
mapping (map_to_output, the coordinator’s parallel work) is one answer
for someone standing at the panel; it is not useful for someone sitting at
the monitor with the board flat on a desk, which is the actual physical
arrangement HDMI mode is for. The operator wants that same glass usable
the way a laptop trackpad is: relative pointer motion, tap-to-click, and
multi-finger gestures (two-finger scroll, pinch-zoom, swipes) for the
monitor session — and wants it to happen automatically, with no manual
mode switch, whenever HDMI is actually the active output.
A new host-side prototype, nix/touch-trackpad/ (Rust, cross-built for
riscv64-linux exactly as nix/rust-shell-client/ is): grabs the
touchscreen (EVIOCGRAB) and re-emits its multitouch protocol-B contacts
through a virtual uinput device declared with touchpad properties
(INPUT_PROP_POINTER + INPUT_PROP_BUTTONPAD, BTN_TOOL_FINGER/
_DOUBLETAP/_TRIPLETAP, no INPUT_PROP_DIRECT) instead of one that
itself computes relative motion or gestures. libinput classifies the
result as a touchpad on its own (host-verified: ID_INPUT_TOUCHPAD=1,
docs/evidence/the-touchscreen-becomes-an-hdmi-trackpad/host-uinput-classification.md)
and does its own pointer acceleration, tap-to-click, and every
multi-finger gesture (two-finger scroll, pinch, swipe) itself — this
program’s only job is protocol translation, not gesture recognition.
Automatic mode switching: the daemon polls /sys/class/drm/*/status
(no dependency on Sway’s IPC socket or on Sway having started) and grabs
the touchscreen only while an HDMI* connector reads connected;
otherwise the touchscreen is left ungrabbed for the coordinator’s direct
touch mapping. A --force-mode=trackpad|direct flag is kept as a manual
override for bring-up, but is not the normal path.
nix/touch-trackpad-service.nix: an importable NixOS module
(k230.touchTrackpad.enable) defining the systemd unit. The explicit
k230-coherent-shell-hdmi-trial profile imports and enables it after
the bounded standalone board safety trial. Other profiles retain their
existing direct-touch configuration.
design.md records the rejected alternatives (a hand-synthesized
relative-pointer uinput daemon; the wlroots zwlr_virtual_pointer_v1
Wayland-client route; a compositor-side patch) and why the
touchpad-re-emission design won on latency, permissions, and getting
pinch/swipe “for free” from libinput’s already-shipped gesture engine.
The Rust shell subscribes to wl_pointer and shares its existing
touch actions with primary mouse clicks/drags, so the virtual trackpad can
activate Home/launcher icons and settings controls. Pointer hover and
secondary buttons do not accidentally activate apps.
A four-finger inward pinch on the touchscreen-derived virtual touchpad opens app overview via Sway’s normal device-scoped gesture binding.
None — this describes what the existing touch input does in a new situation (HDMI active), not a new piece of hardware.
display/touch: records that while an HDMI output is the active one,
the touchscreen SHALL be re-emitted as a virtual touchpad rather than
reporting absolute touch coordinates, and what a consumer (libinput,
Sway) observes as a result.
runtime/shell: overview entry through four-finger trackpad pinch.
nix/touch-trackpad/), cross-built and
proven with nix build .#handheld-touch-trackpad; no kernel or
device-tree change (CONFIG_INPUT_UINPUT=y is already built into this
kernel per nix/kernel.nix’s existing evemu/touch-injection rationale,
and TOUCHSCREEN_GOODIX_BERLIN_* is already on).nix/touch-trackpad-service.nix), plus a named virtual-touchpad input
stanza in nix/shell.nix enabling normal libinput tap and scroll behavior.
The coordinator owns that configuration change after the HDMI checkpoint landed.board/contact-checkpoint.json under
this change’s evidence directory. The coordinator reserves the board and
serial port for those trials.map_to_output
touch path (this is a parallel mode, not a replacement); implementing
the no-reboot HDMI hot-plug automation (plugging-in-hdmi-moves-the-display
group 4) — this change’s mode detection is written to work under either
outcome of that still-open question; retuning pointer acceleration or tap timing; a udev-rule-based non-root permission
model for the service (documented as follow-on in design.md).The operator reports awkward shell gestures and requests an actual HDMI UX pass, especially easy two-finger drawer/card navigation. Extend this existing change rather than create another unrelated in-flight proposal. Two-finger vertical swipes starting near the built-in glass’s top/bottom edges navigate the shell independently of cursor location; center scrolling/pinch and one-finger pointer/taps remain libinput-owned. Two-finger horizontal overview scroll follows movement continuously and preserves release momentum. Drawer/ shade dismissal must be reversible and must not strand a half-visible sheet. The coordinator owns relay gesture arbitration, bounded local IPC, compositor policy, shared Rust reveal/dismiss and named-device natural scroll defaults. No HDMI kernel/DT change, new graphics engine or whole-device flash is needed.
The operator confirmed upward two-finger navigation but reported that downward drawer dismissal failed. They clarified the interaction model: two fingers in HDMI trackpad mode must perform the shell gestures already available to one finger in direct touch mode, rather than accumulating independent shortcuts. Three fingers from the bottom replace the touch mode’s two-contact keyboard chord. Both modes share tracking, reversal, scrolling boundaries and release physics. Preserve ordinary one-finger pointer input and application scroll/zoom.
The operator accepts this delivered functional scope and waives additional
capture-only acceptance gates. docs/evidence/proposal-closeout/2026-10-01/trackpad.md records the exact report,
prior evidence and limits. Its task dispositions supersede older statements
that these acceptance gates remain open; they do not claim new test runs.
plugging-in-hdmi-moves-the-display establishes that HDMI is, today and
for the foreseeable near term, a reboot-based device-tree swap, not a
live no-reboot switch (its own task group 4 is explicitly speculative and
may never land, per that change’s design.md decision 4). So at any given
moment exactly one of the panel (DSI-1) or the bridge (HDMI-A-1) is the
connector Linux is actually driving, and that fact is visible in
/sys/class/drm/*/status without needing Sway, a reboot marker, or
anything this change would have to invent.
The touchscreen itself is unaffected by which DTB booted: the GT9895 is
wired independently of the DSI/HDMI mux question (its own I2C bus, its own
GPIO23/24 lines — shared with the LT9611’s reset/interrupt per
plugging-in-hdmi-moves-the-display’s display/touch delta, but that
sharing is about power/interrupt contention, not about whether the touch
driver is loaded; nothing in that change’s device-tree work removes the
GT9895 node from either DTB). The touchscreen keeps producing ordinary
ABS_MT_* events regardless of which display output is live; the only
thing that needs to change is what consumes them.
Goals: let a person use the touchscreen glass as a laptop-style trackpad for the HDMI session — relative pointer motion with acceleration, tap-to-click, two-finger scroll, pinch-zoom, and multi-finger swipes — with no manual mode switch; keep the coordinator’s direct absolute-touch path for panel mode completely unaffected; prove the design’s mechanism on the host to the extent host evidence can reach.
Non-goals: implementing or depending on no-reboot HDMI hot-plug
automation; retuning pointer acceleration or tap timing; a hardened
non-root permission model (see “Permissions” below); wiring the resulting
NixOS module into the shipped configuration (left for the coordinator once
an HDMI session exists to try it against); any change to the touchscreen’s
existing direct-mode behavior or its display/touch digitizer-range
requirement.
Three designs were evaluated for turning the touchscreen into something HDMI-session-useful:
(a) A uinput daemon that grabs the touchscreen and itself computes
relative pointer motion + buttons + scroll, i.e. the daemon is the
gesture recognizer (tracks finger count and velocity, decides tap vs.
drag vs. scroll, emits REL_X/REL_Y/BTN_LEFT/REL_WHEEL on a virtual
mouse device). This is the most common pattern for “make an unusual input
device act like a mouse” (it’s what most touchscreen-as-trackpad hacks and
several evdev/python-evdev-based tools online do). Rejected as the
primary design: it means re-implementing, by hand, a worse version of
tap-timing, palm rejection, multi-finger disambiguation, scroll-vs-pointer
arbitration, and acceleration curves that libinput already ships,
extensively tuned, in the exact code path Sway already runs. Pinch-zoom
and arbitrary multi-finger swipes specifically are libinput pointer
gesture frames (libinput_event_gesture_*, delivered to Wayland clients
via wp_pointer_gestures_v1) — a hand-rolled relative-motion daemon would
have to reimplement that protocol surface entirely to get pinch/swipe at
all, which the operator explicitly asked for (“like a real laptop
touchpad”).
(b) Existing projects (ydotool, generic python-evdev/evdev-rs
touchpad emulators, or driving input via the wlroots
zwlr_virtual_pointer_v1 Wayland protocol from a client instead of
uinput). Rejected: ydotool and the common evdev-based emulators are
all instances of design (a) — same reimplementation problem. The
zwlr_virtual_pointer_v1 route moves the synthesis from kernel-level
uinput to a Wayland client talking directly to Sway/wlroots, which
removes the uinput permission question but only exposes a relative/
absolute pointer protocol (motion + buttons + optional discrete scroll) —
it has no multitouch/gesture-frame surface at all, so it cannot deliver
pinch-zoom or swipe gestures to Wayland clients either; it would still
need this program to invent gesture recognition, and would additionally
tie the whole design to one Wayland compositor’s client library instead of
a device any compositor’s libinput already understands.
(c) A compositor-side patch (recognizing gestures from raw touch events inside Sway/wlroots itself, bypassing libinput’s touchpad path entirely). Rejected: this is strictly more invasive than either uinput option (patching and tracking a wlroots/Sway fork) for no capability this project doesn’t already get for free from libinput once it’s shown a touchpad-shaped device; also removes the “grab the raw device, everything else is unaffected” isolation the other two options have.
Chosen: (a’), a variant of (a) that does not compute motion or
gestures at all. The re-emission device declares itself as a touchpad
(INPUT_PROP_POINTER + INPUT_PROP_BUTTONPAD, no INPUT_PROP_DIRECT,
BTN_TOOL_FINGER/_DOUBLETAP/_TRIPLETAP capability) and forwards the
touchscreen’s real ABS_MT_SLOT/_TRACKING_ID/_POSITION_X/_POSITION_Y
stream through unchanged, synthesizing only the finger-count-derived
BTN_TOUCH/BTN_TOOL_* transitions a real touchpad’s own driver would
also be reporting. libinput’s own evdev_configure_device() then
classifies the device as a touchpad from those bits alone — verified on
the host (not the board; see “What this design does and does not prove”
below) via udev’s identical classifier:
docs/evidence/the-touchscreen-becomes-an-hdmi-trackpad/host-uinput-classification.md
shows ID_INPUT_TOUCHPAD=1 on the created device, no
ID_INPUT_TOUCHSCREEN. From there, pointer acceleration, tap-to-click,
two-finger scroll, and pinch/swipe gesture frames are entirely libinput’s
existing, already-shipped code paths — identical to what a real laptop
touchpad gets. nix/touch-trackpad/src/relay.rs is the whole translator;
it is deliberately not a gesture state machine, and its host tests
(cargo test, 20/20 passing) check exactly that narrow claim: given a
synthetic 1/2/3-finger contact sequence, does it emit the right
BTN_TOUCH/BTN_TOOL_* transitions at the right point in the frame,
without ever touching position data.
swaymsg -t get_outputs was considered and rejected as the primary
signal: it requires $SWAYSOCK/a running Sway session, so a daemon
started before or independent of the shell session couldn’t decide its
mode, and it adds a JSON-parsing dependency for a fact /sys/class/drm
already states directly. nix/touch-trackpad/src/mode.rs reads
/sys/class/drm/*/status (matching the operator’s own suggested
mechanism, “Detect via DRM/Sway outputs, e.g. HDMI-A-1 active”), polled
every 750ms via poll(2) on the touchscreen fd with that same value as
the timeout — so a real touch event is handled with effectively zero added
latency (the poll returns immediately when data is ready) while mode
changes are still noticed within one poll interval when the touchscreen is
otherwise idle. This works unchanged whether HDMI switching stays
reboot-only (the common case today: mode is decided once, at boot, and
never changes until the next reboot) or plugging-in-hdmi-moves-the-display
group 4’s live hot-plug switching later lands (the poll would then notice
the connector flip within 750ms of it happening) — this daemon does not
need to know or care which regime it’s running under.
EVIOCGRAB is taken only while in trackpad mode, and released
(EVIOCGRAB(0)) the instant the mode check sees the panel become active
again — there is never a window where both this daemon and Sway’s direct
touch path see the same physical touch. The virtual touchpad uinput device
is created fresh on entering trackpad mode and destroyed
(UI_DEV_DESTROY, via Drop) on leaving it, rather than kept alive idle,
so libinput never has to reconcile a touchpad whose contact slots didn’t
reset across a mode boundary.
The service (nix/touch-trackpad-service.nix) runs its ExecStart as
root. EVIOCGRAB-ing another process’s input device and creating a
uinput device both normally need CAP_SYS_ADMIN-adjacent privilege
without a udev rule; this image has no uaccess-style ACL rule for
/dev/uinput or /dev/input/event* (unlike the interactive development
host this was prototyped and host-tested on, where a seat ACL already
grants the logged-in user write access to /dev/uinput — see
docs/evidence/.../host-uinput-classification.md). DevicePolicy = "closed"
plus an explicit DeviceAllow still bounds the unit’s device access to
exactly /dev/uinput and /dev/input/event* even running as root.
Narrowing this to a dedicated non-root user plus a purpose-built udev rule
is real, identifiable follow-on work, not done here — this prototype
optimizes for “provably correct protocol translation,” not for hardening a
service the coordinator has not yet decided to ship.
Host-provable and proven in this change: the ioctl sequence is accepted by a real Linux kernel and produces a device udev’s own classifier calls a touchpad; the protocol-translation state machine emits the right transitions for synthetic 1/2/3-finger contact sequences; the mode detector resolves correctly against DRM-sysfs fixtures covering panel-only, HDMI-connected, HDMI-present-but-unplugged, and missing/unreadable sysfs; the crate cross-builds for riscv64-linux with the same toolchain the rest of the shell already cross-builds with.
Not provable without the board, and left open in tasks.md: whether the
real GT9895, grabbed this way, still reports usable contact data through
this relay; whether libinput really does classify and drive the resulting
virtual device correctly when Sway is the one running it (host udevadm
evidence is real but is not the same code path as Sway’s own libinput
context); whether tap-to-click, two-finger scroll, and pinch/swipe
actually feel right, or feel at all, under a monitor session on this
specific slow RISC-V core; and the interaction between this daemon’s
EVIOCGRAB and any GPIO23/24 contention plugging-in-hdmi-moves-the-display
documents between touch and the LT9611 bridge. tasks.md group 3 names
the exact board commands for each of these once an HDMI session exists to
try them against.
The first board run (docs/evidence/the-touchscreen-becomes-an-hdmi-trackpad/board-hang-2026-09-29.md)
hit a real bug and hung the board badly enough to need a hardware reset.
Three changes came out of it, none of them claiming to be the single
proven cause (board access was not available to isolate that) but each
closing off a real, identified failure mode:
uinput::axis_plan: the real GT9895 reports ABS_MT_PRESSURE with
minimum == maximum (0 == 0) — confirmed the direct cause of the
logged libinput error (“kernel bug: device has min == max on
ABS_MT_PRESSURE”), and this crate’s own read_ranges() fallback for a
failed pressure ioctl was equally degenerate, so the bug could not
have been avoided by “just handle the ioctl failure case.” axis_plan
now validates every axis before it reaches /dev/uinput: a degenerate
load-bearing axis (slot/tracking_id/position_x/position_y,
none of which a touchpad can function without) refuses device creation
outright; a degenerate optional one (pressure, which relay.rs
never reads — slot occupancy, not pressure, drives BTN_TOOL_*) is
silently omitted, matching how real pressure-less touchpads report
themselves. Position-axis resolution is also sanitized (a fallback
applied only when the source reports <= 0), addressing the
“sane resolution values” half of the same request even though it was
not implicated in the logged error. Host-verified end to end, including
a live /dev/uinput creation using the board’s exact degenerate-pressure
fixture, re-confirmed still ID_INPUT_TOUCHPAD=1 via udevadm:
docs/evidence/the-touchscreen-becomes-an-hdmi-trackpad/board-hang-2026-09-29.md.wait_readable
previously returned “readable” for any poll()-reported event,
including POLLERR/POLLHUP/POLLNVAL with no POLLIN — a device
that reached a state where the kernel reports one of those on every
poll() call without ever legitimately blocking again would turn this
into an unbounded tight loop (poll() returns instantly forever). It
now checks revents explicitly and treats those three as a hard error,
tearing the session down (which does sleep before retrying) instead of
looping. The event-drain loop in main.rs also gained a hard cap
(MAX_EVENTS_PER_DRAIN) so any bug that made pump_one never report
idle degrades to “drains up to 2048 events, then yields back to the
mode/shutdown check” rather than never yielding at all. SIGINT/SIGTERM
handlers (setting an atomic flag only, per async-signal-safety rules)
let an operator interrupt a run cleanly from the console instead of
needing kill -9 or a reset. Host-verified: a FIFO-based test proves
wait_readable genuinely blocks for its timeout on idle data and
returns promptly once data exists (a real /dev/input/event* node
cannot be opened unprivileged in this sandbox, unlike /dev/uinput, so
the FIFO exercises the same underlying poll(2) code path instead).--dry-run / --log-events: --dry-run runs the real grab and
read/relay logic but never opens /dev/uinput at all, so a re-test on
the board cannot repeat the libinput/Sway interaction that preceded the
hang, no matter what it turns out to have been. --log-events traces
every raw and translated event to stderr. tasks.md group 3’s revised
re-test procedure leads with --dry-run --log-events under a timeout
wrapper before ever creating a real uinput device again.What this explicitly does not claim: that the degenerate-pressure axis
was the mechanism that hung the board (as opposed to, say, a busy loop
independently triggered around the same moment) — board-hang-2026-09-29.md
records that as unestablished. The fix set is deliberately broader than
“patch the one confirmed bug” because board time to iterate is scarce and
precious (AGENTS.md’s single shared board/serial reservation), and each
addition here is independently justified and host-tested on its own
terms, not speculative padding.
ABS_MT_POSITION_X/Y
resolution (units/mm) fields are mirrored from the real device rather
than hardcoded, which is what libinput’s size-dependent heuristics key
off; if the feel is still wrong on the board, tuning is a libinput
config-file change (nix/shell.nix’s Sway input stanza), not a change
to this relay.Vec per SYN_REPORT frame (at most 3 synthesized events) and no
parsing; the real cost floor is two syscalls (a read and a write,
each already a poll-then-io round trip today for the touchscreen’s
existing consumer) per event, which this design does not add to, only
redirects. Not yet measured on the board — a follow-on task, not claimed
here.DeviceAllow/DevicePolicy bound the
blast radius even so, and the module is enabled only in the explicit coherent-shell HDMI
profile after its standalone safety trial.plugging-in-hdmi-moves-the-display’s shared GPIO23/24 net between
touch and the LT9611 could mean touch’s interrupt behaves differently or
less reliably while the HDMI DTB is the one booted] → this change cannot
observe that without the board and does not assume otherwise; it is
named explicitly as an open board-verification question in tasks.md
rather than folded into a confident requirement.The real bounded contact capture contains both one- and two-finger frames.
It revealed that the original hand bindings emitted BTN_TOOL_TRIPLETAP
for two fingers. The corrected codes now have an independent C/Linux-header
regression check; relay synthesis and advertised capabilities share those
bindings. The operator confirmed pointer movement in the live virtual-device
trial, but tapping did not click. Sway disables tapping by default, so the
image explicitly enables tapping and two-finger scrolling for
1:1:K230_Virtual_Touchpad_(HDMI_mode). Direct-touch input keeps its existing
configuration. See the committed board contact checkpoint for provenance and
limits; physical click/scroll/pinch and panel restoration are still required.
After the corrected standalone relay remained active without the original
libinput pressure error, the explicit k230-coherent-shell-hdmi-trial profile
imports this service and enables it. Other configurations do not import it.
Systemd bounds shutdown to two seconds, and normal unit-change restarts ensure
future rebuilt relay packages replace the running binary. The persistent unit
replaces the transient trial so only one process grabs the glass. Installation
and enabled-unit observations establish the deployed profile, not an actual
reboot or panel-mode acceptance; those remaining gates stay explicit.
The operator reports that pointer movement works but clicking shell icons
opens nothing. Source inspection finds that the Rust client subscribes only
to touch and keyboard capabilities: it never obtains a wl_pointer.
The relay/libinput path cannot deliver mouse actions to a client that never
requests them. Subscribe to normal SCTK pointer frames and share the existing
contact down/motion/up/cancel actions between touch and primary pointer drag.
Keep a pointer contact owned by its initial surface, ignore hover/secondary
buttons for activation, and cancel on leave or capability loss. This uses
normal Wayland client paths and does not change the compositor or touch mapping.
Physical launcher activation remains a separate evidence gate from injected
mouse delivery or host model tests.
The board’s touchscreen glass remains the input while its built-in display
is inactive and HDMI presents the image. In relay mode its contacts reach
libinput as touchpad events, so the direct-touch compositor edge-swipe path
does not apply. The operator requests a four-finger inward pinch to enter app
overview. Sway’s pinned sway/sway.5.scd documents pinch:4:inward; its
sway/input/seatop_default.c routes matching pinch gestures to bindings.
Use bindgesture --input-device=1:1:K230_Virtual_Touchpad_(HDMI_mode) pinch:4:inward card_shell enter
in the generated Sway configuration. A live IPC binding provides immediate
availability; the image configuration makes it persistent. Actual four-finger
recognition/overview appearance remains a physical evidence gate.
The original pure relay remains the app-input path. Its forwarding tests still apply. Add a bounded frame gate around it only in trackpad mode, enabled by an explicit shell socket argument in the service. This is an intentional refinement of the earlier non-goal after real operator feedback.
EVIOCGMTSLOTS and retained across tracking IDs, because Linux
filters unchanged position values. No per-frame subprocess, unbounded queue, or synchronous render
work in the input-reading loop. The compositor owns a distinct gesture ID,
validates sequence/finiteness/ranges and restores ownership on lost transport.Source, exact installed outputs, raw-input board observations, reviewed native
captures and the remaining real-glass gate are recorded in
docs/evidence/the-touchscreen-becomes-an-hdmi-trackpad/gesture-ux/README.md.
Host gates cover edge/center arbitration, staggered contacts, pinch/horizontal fall-through, timing/buffer bounds, transport failure, cancellation and dropped controller recovery. Paired real compositor tests cover live geometry, focus, normal-app input and reversible sheets. Cross-build and installed-board injected proof are separate from real glass feel and camera evidence. Keep every old physical restoration/click/pinch gate open until its own proof exists.
The initial group 5 implementation required a fresh outward gesture to start at the same physical edge; this does not reproduce native drawer gestures. Keep its committed evidence as a historical installed checkpoint. Group 6 replaces its separate close thresholds and edge/dismiss stream with translation into the existing touch interactions: two physical contacts become one logical contact at their normalized centroid, with original displacement and timestamps; three contacts qualify the existing two-contact keyboard policy from the bottom. Qualification is bounded and fail-open before ownership. A short initial contact window allows the third finger to arrive before two-contact navigation commits.
The compositor chooses the existing owner at Begin. App edge navigation and card manipulation use the shared input_down/motion/up policy. A shell overlay receives standard Wayland touch on its own surface so the Rust client’s native scroll-at-top, close-drag, reversal and settle logic remains authoritative. The relay never sends synthetic touch to an ordinary app: declined application center input falls through, with original events, to libinput scroll/pinch. One-finger pointer movement must retain prompt fall-through. Four-contact pinches remain libinput-owned. Synthetic pan release cannot activate an icon or a control after a tiny or reversed gesture. Watchdog, output change, seat loss and client destruction cancel the translated contact without stale grabs.
Reject adding a wider edge-only close zone or additional drawer-specific thresholds: the operator explicitly requests common gesture semantics. Preserve native logical touch geometry; comfortable physical edge qualification is an input adaptation, not a separate navigation state machine. No kernel/DT change.
The implemented uniform checkpoint, exact sources/outputs, timing failure,
strict injected-board result and reviewed native captures are recorded in
docs/evidence/the-touchscreen-becomes-an-hdmi-trackpad/uniform-gestures/README.md.
Physical recognition/feel remains UNVERIFIED.
The operator accepts this delivered functional scope and waives additional
capture-only acceptance gates. docs/evidence/proposal-closeout/2026-10-01/trackpad.md records the exact report,
prior evidence and limits. Its task dispositions supersede older statements
that these acceptance gates remain open; they do not claim new test runs.
ydotool, generic python-evdev/evdev-rs
emulators, the wlroots zwlr_virtual_pointer_v1 protocol), and (c)
a compositor-side patch; recommend one with tradeoffs on latency,
permissions, and mode switching. Recorded in design.md decision 1.
Superseded mid-task by an operator requirements update (multi-finger
gestures — pinch/swipe — required, “like a real laptop touchpad”):
the recommendation changed from a relative-pointer daemon to
re-emitting the touchscreen’s real multitouch contacts through
uinput as a virtual touchpad, so libinput’s own already-shipped
gesture engine does the recognition instead of this program. 2.1 nix/touch-trackpad/src/relay.rs: the touchscreen-to-touchpad
protocol translator (contact-count-derived BTN_TOUCH/BTN_TOOL_*
synthesis; ABS_MT_* passthrough). Verify:
cd nix/touch-trackpad && cargo test (28/28 passing as of task 2.7,
including 1/2/3-finger tap/drag/lift and a 2-to-1-finger transition
case).
2.2 nix/touch-trackpad/src/mode.rs: DRM-sysfs-based automatic mode
detection (HDMI* connected -> trackpad, else direct-touch),
fixture-tested for panel-only, HDMI-connected,
HDMI-present-but-unplugged, and missing/unreadable sysfs. Verify:
cargo test (same command as 2.1).
2.3 nix/touch-trackpad/src/{devsearch,touchdev,uinput}.rs: find the
touchscreen by its recorded input name
(“Goodix Berlin Capacitive TouchScreen”), read its real ABS_MT_*
ranges via EVIOCGABS to mirror onto the virtual device, and the
hand-bound uinput/EVIOCGRAB ioctl surface (every ioctl number and
the two on-wire struct sizes independently checked against the
kernel UAPI in cargo test). Verify:
cargo test (same command), plus one live host /dev/uinput device
creation (creates_and_destroys_a_real_virtual_touchpad_if_permitted)
whose udevadm classification is captured in
docs/evidence/the-touchscreen-becomes-an-hdmi-trackpad/host-uinput-classification.md.
2.4 nix/touch-trackpad/src/main.rs: the orchestration loop (poll
mode via poll(2) on the touchscreen fd with the mode-check interval
as timeout, so real touch events add no latency; start/stop a
TrackpadSession on mode transitions; --force-mode/--device/
--drm-root overrides for manual bring-up). Verify:
cargo build && cargo clippy --all-targets (0 warnings).
2.5 nix/touch-trackpad/default.nix + flake.nix’s
handheld-touch-trackpad output, packaged the same way
nix/rust-shell-client is (rustPlatform.buildRustPackage,
cargoLock.lockFile, doCheck = false since the cross build cannot
run a RISC-V test binary on the x86_64 host). Verify:
nix build .#handheld-touch-trackpad --out-link .build-out/handheld-touch-trackpad --max-jobs 2 --cores 8
— produced a riscv64 ELF binary at
.build-out/handheld-touch-trackpad/bin/k230-touch-trackpad
(store path, after task 2.7’s fixes,
/nix/store/v0n70zk76z0p3xky67613769l8pc2lrl-k230-touch-trackpad-riscv64-unknown-linux-gnu-0.1.0;
the coordinator’s board-hang report was against an earlier build at
/nix/store/sklwlg9n...-k230-touch-trackpad).
2.6 nix/touch-trackpad-service.nix: a standalone, importable NixOS
module (k230.touchTrackpad.enable) defining the systemd unit,
initially kept out of nix/shell.nix/nix/k230.nix. Task 3.1
subsequently imports it in the explicit HDMI trial profile. Verify: evaluates —
nix eval .#nixosConfigurations.k230.config.system.build.toplevel.drvPath
still succeeds for the base panel configuration. The service-enabled
HDMI system was subsequently built and installed for task 3.1:
/nix/store/0gdzw6l64c99wh0f0lydb9ghdld85cff-nixos-system-nixos-26.11.20260919.20b1ddd.
2.7 Fix in response to the coordinator’s first board run, which hung
the board and needed a hardware reset
(docs/evidence/the-touchscreen-becomes-an-hdmi-trackpad/board-hang-2026-09-29.md):
uinput::axis_plan now validates every axis (rejects a degenerate
load-bearing range outright; silently omits a degenerate optional
one — exactly the real GT9895’s min=0,max=0 ABS_MT_PRESSURE, the
confirmed direct cause of the logged libinput error) and sanitizes
position-axis resolution; touchdev::wait_readable now checks
revents instead of trusting any poll()-reported event, closing
off one concrete unbounded-tight-loop mechanism; main.rs gained a
bounded per-wakeup event-drain cap, SIGINT/SIGTERM handling, and
--dry-run/--log-events flags. None of this claims to have proven
the exact hang mechanism (board access was not available to isolate
it) — see design.md decision 5 and the evidence doc for what is
and is not established. Verify: cargo test (28/28 passing,
including a live /dev/uinput creation with the board’s exact
degenerate-pressure fixture, re-confirmed ID_INPUT_TOUCHPAD=1 via
udevadm, and a FIFO-based proof that wait_readable genuinely
blocks rather than busy-spinning) and cargo clippy --all-targets
(0 warnings); repackaged with
nix build .#handheld-touch-trackpad --out-link .build-out/handheld-touch-trackpad --max-jobs 2 --cores 8
(new store path in task 2.5).
2.8 Correct the independently observed UAPI mismatch: two-, three-
and four-finger tool bits are 0x14d, 0x14e, 0x14f. Compare
the Rust bindings against a C probe of the host Linux headers:
TMPDIR=$HOME/tmp cargo test and
TMPDIR=$HOME/tmp cargo clippy --all-targets -- -D warnings.
All 28 existing tests and the new header comparison pass (the
integration target also reruns the event-layout test). Configure
tap enabled and scroll_method two_finger for the named virtual
touchpad in nix/shell.nix. Cross-build with
nix build .#handheld-touch-trackpad .#nixosConfigurations.k230-coherent-shell-hdmi-trial.config.system.build.toplevel --no-link --max-jobs 2 --cores 8.
Corrected relay: /nix/store/j53iiav8xbz0kqrval861z6lky63kbgy-k230-touch-trackpad-riscv64-unknown-linux-gnu-0.1.0.
Configuration build: /nix/store/gcm3azrpvcm8vr24wps6wrdiqif6mmbd-nixos-system-nixos-26.11.20260919.20b1ddd.
These host results do not establish physical clicking or gestures.
2.9 Handle standard Wayland pointer events in the Rust shell. Subscribe
to pointer capability and route primary press/drag/release through the
same Home, launcher and settings actions as touch. Hover and secondary
clicks must not activate icons; loss of focus/capability must cancel a
pending press. Verify the event ownership model and actual client build:
cd nix/rust-shell-client && cargo test pointer_input && cargo check --bin k230-shell-rust;
cross-build nix build .#nixosConfigurations.k230-coherent-shell-hdmi-trial.config.system.build.toplevel --no-link.
Passed: 404 library tests, one existing ignored test, binary check/build
and RISC-V system build. board/pointer-host-checks.json identifies
the exact source hashes and /nix/store/173csl1mfjw2jf3069f1cgm310nxvrl1-nixos-system-nixos-26.11.20260919.20b1ddd.
2.10 Bind four-finger inward pinch on the virtual touchscreen-derived
touchpad to card_shell enter using normal Sway bindgesture, scoped
to that device so two-finger app scrolling/zooming remains available.
Verify the system cross-build and live Sway IPC acceptance; generated
configuration must put the binding inside Sway, not a shell script.
Corrected build and installed-board checks pass; board/overview-binding.json
records the actual profile/configuration and resolved initial build error.
Physical four-finger recognition remains task 3.6.
Coordinator checkpoint: docs/evidence/the-touchscreen-becomes-an-hdmi-trackpad/board/contact-checkpoint.json records real one- and two-finger input during the bounded dry run, with clean shutdown and release. A subsequent live trial created a Sway-classified touchpad; the operator confirmed cursor movement but no tap click. That trial exposed incorrect hand-bound multi-finger key codes and default-disabled tapping. The coordinator owns the board and serial lock for the corrected trial. The corrected relay is now installed as an enabled service in the explicit HDMI profile; board/persistent-service.json records its actual store path, active unit, single relay process and Sway configuration. Full click/scroll/pinch and panel-mode proof remain open. The prototype was already merged through 6534585eb00a, satisfying 4.2 independently.
3.0 Safe re-test first. Under the reserved board/serial lock, run
the new build (task 2.7’s store path, not the one from the
original hang report) with both safety flags and a hard wall-clock
bound for a process that remains schedulable:
flock -w 120 /tmp/k230-board.lock python3 tools/console.py /dev/ttyACM0 --wait=30 "timeout -k 2s 20s /nix/store/v0n70zk76z0p3xky67613769l8pc2lrl-k230-touch-trackpad-riscv64-unknown-linux-gnu-0.1.0/bin/k230-touch-trackpad --dry-run --log-events".
--dry-run means no /dev/uinput device is ever created, so
whatever libinput/Sway did last time cannot recur even if the fix in
2.7 is incomplete; timeout -k 2s 20s sends SIGTERM after 20 seconds
and SIGKILL two seconds later if needed. This cannot guarantee recovery
from a kernel hang or an uninterruptible task; hardware reset remains
the fallback if the console stops responding. Confirm over the console: the
process grabs the touchscreen, --log-events shows real touch
events being read and translated (touch the glass during the 20s
window), and the process exits cleanly (its own “shutting down” line
or timeout’s SIGTERM) with the touchscreen ungrabbed afterward
(evtest/direct-touch check per 3.3 below). If this step itself
shows any sign of the earlier hang (console stops responding before
the 20s timeout should have fired), stop here, do not proceed to
3.1, and record what was observed instead.
3.1 Only after 3.0 passes clean: run the same build without
--dry-run (still timeout-wrapped) and confirm the service starts
and logs mode -> Trackpad once the HDMI connector reads
connected, this time with a real virtual touchpad device created;
check dmesg/journalctl for the same libinput error the original
report showed and confirm it is gone (pressure axis omitted). Once
confirmed safe standalone, import nix/touch-trackpad-service.nix
into the booted configuration, set k230.touchTrackpad.enable = true;,
and install the rebuilt system profile for the persistent-service form:
flock -w 120 /tmp/k230-board.lock python3 tools/console.py /dev/ttyACM0 --wait=10 "journalctl -u k230-touch-trackpad -n 20 --no-pager".
3.2 Record operator acceptance: HDMI trackpad works (2026-10-01), supported by earlier cursor/click feedback and installed-device proof. Extra monitor captures and an exhaustive per-gesture rerun are waived; do not claim a newly recorded right-click/zoom test.
3.3 Accept panel/direct-touch restoration from earlier panel-return feedback and current overall HDMI-trackpad acceptance. Existing mode/service and injected-board evidence remain distinct. No new reboot or evtest session is claimed.
3.4 Reconcile display/touch grounding with actual installed-board evidence and committed operator acceptance. Preserve limits for gestures not individually documented; update the evidence contract to allow operator reports under the explicit capture waiver.
3.5 Accept working launch/click behavior from prior operator touchpad feedback and current HDMI-trackpad acceptance, alongside the actual pointer/launch matrix. No new photograph is required.
3.6 Close the requirement for another physical four-finger recording under the operator’s overall HDMI-trackpad acceptance and no-further-investigation instruction. Binding/routing proof remains committed; individual physical recognition remains explicitly UNVERIFIED, not claimed as a new observed test.
openspec validate the-touchscreen-becomes-an-hdmi-trackpad --strict
(exit code checked directly).master per
AGENTS.md, independent of whether group 3 has started — the
proposal, the host-tested prototype, and the packaged binary are the
reviewable deliverable now, not a private preface to board work that
depends on another still-open change. 5.1 Add bounded two-contact physical-edge arbitration around the unchanged app-input relay and persistent/coalescing shell IPC. Preserve center/one-finger/pinch/extra-contact fall-through and fail-open before ownership. Verify cargo test --offline --manifest-path nix/touch-trackpad/Cargo.toml, including transport and frame-gate failure fixtures. Host proof only.
5.2 Reuse compositor navigation for the distinct trackpad stream; validate sequence/geometry and watchdog recovery. Add reversible close-from-visible-state to the shared Rust reveal protocol and test cancel/EOF. Verify cargo test --offline --manifest-path nix/rust-shell-client/Cargo.toml --lib protocol and the named real-compositor gesture fixture from 5.3. Host/headless proof only.
5.3 Replace overview finger-axis card stepping with continuous drag/coast while preserving wheel steps and ordinary app input; verify python3 -m unittest discover -s tests -p test_card_shell_trackpad_gestures.py against the built compositor. Exercise held/reversed movement, lift, focus, drawer/shade open/close and malformed/lost streams. Headless injected proof only.
5.4 Cross-build nix build .#handheld-touch-trackpad .#card-shell .#handheld-shell-rust .#nixosConfigurations.k230-coherent-shell-hdmi-trial.config.system.build.toplevel --no-link --print-out-paths --max-jobs 1 --cores 8; record exact outputs/source. Build proof only.
5.5 Reserve the board, install the matching recoverable candidate, record service/store identities and bounded injected physical-board gesture/focus/recovery checks with native captures. Use python3 tools/console.py /dev/ttyACM0 --wait=5 with the concrete sanitized commands recorded under docs/evidence/the-touchscreen-becomes-an-hdmi-trackpad/gesture-ux/. This does not prove real two-finger recognition/feel.
5.6 Record operator acceptance of HDMI-trackpad behavior; retain the installed gesture-UX native/console evidence. The requested new real-touch capture is waived, not performed.
5.7 Review/merge/push proved source/evidence and inspect exact-revision CI/Pages. Retain tasks 3.2-3.6 and any unperformed physical acceptance; archive only after every named gate passes. Verify openspec validate the-touchscreen-becomes-an-hdmi-trackpad --strict and the deployed work card.
2026-09-30 gesture checkpoint: tasks 5.1–5.5 are grounded by docs/evidence/the-touchscreen-becomes-an-hdmi-trackpad/gesture-ux/README.md. The strict final board trial passes thirteen checks with eight accepted raw edges, no IPC timeout/rejection, and reviewed native screenshots. Real-glass task 5.6 and earlier physical gates remain open; this change is not archived.
6.1 Replace the relay’s edge/dismiss shortcut with bounded two/three-contact centroid translation; permit native shell content dragging and preserve declined ordinary input. Verify cargo test --offline --manifest-path nix/touch-trackpad/Cargo.toml and cargo clippy --offline --manifest-path nix/touch-trackpad/Cargo.toml --all-targets -- -D warnings. Host proof only.
6.2 Dispatch the translated stream to existing compositor touch/card/keyboard policy or the actual Rust overlay through standard Wayland touch; remove separate close thresholds and prevent synthetic pan taps. Verify python3 -m unittest discover -s tests -p test_card_shell_trackpad_gestures.py against the matching actual compositor, including center drawer close/scroll/reversal, card movement and keyboard contact counts. Headless injected proof only.
6.3 Cross-build the relay, compositor, Rust client and HDMI system with nix build .#handheld-touch-trackpad .#card-shell .#handheld-shell-rust .#nixosConfigurations.k230-coherent-shell-hdmi-trial.config.system.build.toplevel --no-link --print-out-paths --max-jobs 1 --cores 8; record matching sources/outputs. Build proof only.
6.4 Reserve board/serial, install the recoverable matching candidate and run tools/hdmi-trackpad-gesture-trial.py under its named timeout and independent restore timer. Record native captures and source/service identities with injected-board provenance.
6.5 Record operator acceptance of the uniform HDMI-trackpad behavior; retain installed uniform-gesture evidence and prior two-finger feedback. Additional exhaustive contact-count capture is waived; no new three-finger keyboard recording is claimed.
6.6 Review, merge/push and inspect exact-revision CI/Pages using openspec validate the-touchscreen-becomes-an-hdmi-trackpad --strict; keep the original incomplete physical tasks open and do not archive.
Group 5 landed at 7cd22432381e508dabd77ce1163864af8eae8004; the screenshot
inventory correction 5d2349785d72071f2bf9abcdd51823bfbc38ad49 passed build and
Pages deployment in run 36775320813. Both published work/evidence URLs were
read successfully and the work snapshot matched 5d2349785d72. See
docs/evidence/the-touchscreen-becomes-an-hdmi-trackpad/gesture-ux/publication.json.
This is the historical edge-based checkpoint, not proof of group 6 semantics.
Group 6 tasks 6.1–6.4 are grounded by docs/evidence/the-touchscreen-becomes-an-hdmi-trackpad/uniform-gestures/README.md: matching cross-build, native-client actual-compositor checks and 15 strict injected-board checks passed. Real-glass task 6.5 remains open.
Uniform implementation d29cf869009ad3c3f772b9cca6cd586597399bd7 passed build and Pages deployment in run 36783163625. The published work snapshot, rendered evidence page and exact cover bytes were read successfully. See uniform-gestures/publication.json; physical task 6.5 remains open.
The updated completed tasks describe actual acceptance, waivers and scope
transfer, not execution of the superseded protocols. See docs/evidence/proposal-closeout/2026-10-01/trackpad.md.
Historical checkpoint notes above that say physical gates remain open are
superseded by this record. Quantitative or individually unreported results
are not promoted to physical proof.
Proof: openspec validate the-touchscreen-becomes-an-hdmi-trackpad --strict; committed operator report;
python3 scripts/render_work_board.py --working-tree --output <snapshot.json>.
While an HDMI connector is the active display output (per
display/hdmi’s reboot-based device-tree swap in
plugging-in-hdmi-moves-the-display), the GT9895 touchscreen’s raw
ABS_MT_* contact stream SHALL be exclusively grabbed (EVIOCGRAB) and
re-emitted through a virtual uinput device declared with touchpad
properties (INPUT_PROP_POINTER + INPUT_PROP_BUTTONPAD, BTN_TOOL_FINGER/
_DOUBLETAP/_TRIPLETAP, no INPUT_PROP_DIRECT), so that libinput
classifies it as a touchpad and provides pointer motion, tap-to-click,
two-finger scroll, and pinch/swipe gestures for the HDMI session, in place
of the panel-mode absolute touch-to-output mapping. Qualified two-contact shell gestures and three-contact bottom keyboard gestures
may instead translate to the existing logical touch policies through the bounded
shell gesture path; ordinary application center scrolling/pinch and pointer input
remain on the touchpad path. While the panel (not
HDMI) is the active output, the touchscreen SHALL be left ungrabbed and
unmodified, continuing to report absolute coordinates as
display/touch’s existing digitizer-range requirement already states.
Grounding: host relay/mode/ioctl tests and the independent Linux-header
comparison (cargo test); the earlier host udev classification in
docs/evidence/the-touchscreen-becomes-an-hdmi-trackpad/host-uinput-classification.md;
and the real contact/operator checkpoint plus installed-board service probes
in docs/evidence/the-touchscreen-becomes-an-hdmi-trackpad/board/.
The operator confirmed cursor motion, and Sway classifies the actual virtual
device as a touchpad with tapping enabled. The operator subsequently accepts the HDMI trackpad as working;
docs/evidence/proposal-closeout/2026-10-01/trackpad.md records that acceptance and earlier panel-return feedback.
It does not manufacture individual per-gesture observations.
connected per /sys/class/drm/*/status
and a finger drags across the touchscreenplugging-in-hdmi-moves-the-display group 4’s no-reboot switching later
lands, the HDMI connector reports disconnected while running)While the board’s built-in display is inactive and its touchscreen is a virtual touchpad for HDMI, the shell SHALL open app overview after a four-finger inward pinch on that touchscreen. The Sway configuration SHALL scope this binding to the virtual touchpad and leave two-finger application scroll/zoom gestures available. Direct-touch panel-mode gestures SHALL retain their existing configuration.
Grounding: operator acceptance in docs/evidence/proposal-closeout/2026-10-01/trackpad.md, with prior source and board/QEMU evidence retaining their original classes and limits.
In HDMI trackpad mode, two-contact shell gestures SHALL use the same navigation, card manipulation, sheet scrolling/dismissal and release policies as one-contact direct touch gestures. Three-contact upward bottom gestures SHALL use the existing two-contact direct touch keyboard policy. Motion SHALL follow the contact centroid, reverse while held, and settle with the shared release physics. The shell SHALL preserve ordinary application center scroll/pinch and one-contact pointer/tap. Transport loss and cancellation SHALL restore recoverable state without a stale contact, and translated pan release SHALL NOT activate an app as a tap. Direct-touch behavior SHALL retain its existing gesture configuration.
Archived change · Archived
Snapshot 5836ef1d113d · 2026-10-17 08:22 UTC
Closed recordClosed on operator acceptance; see evidence for waived captures and retained limits.
A person can type on the handheld but cannot readily discover how to show or dismiss the keyboard. The user also wants dismissal to follow their fingers and settle smoothly, consistent with app navigation.
None.
runtime/shell: Add explicit gesture control and direct manipulation of the on-screen keyboard in the coherent shell.Userspace compositor input/scene policy, keyboard lifecycle integration, themed grip and Settings text, Nix session wiring, host/native QEMU checks and separate real-glass proof. No kernel, device-tree or stage-1 changes. Physical panel/touch proof is required for completion. Non-goals: replacing wvkbd, changing its key layout, interpreting drags on ordinary keys as dismissal, adding haptics, or replacing the Wi-Fi password editor’s explicit close/cancel controls.
The operator accepts this delivered functional scope and waives additional
capture-only acceptance gates. docs/evidence/proposal-closeout/2026-10-01/keyboard.md records the exact report,
prior evidence and limits. Its task dispositions supersede older statements
that these acceptance gates remain open; they do not claim new test runs.
Pending measurement work is preserved in the-shell-profiles-reported-interaction-jank before archive.
See proposal.md. The installed coherent shell uses wvkbd and compositor-owned bottom navigation, while the Wi-Fi Settings change adds a separate password editor. The user reported that external keyboard visibility was not discoverable. Existing nix/card-shell/adapter.c detects keyboard reservation and excludes it from card gestures. Layers: userspace compositor policy/scene plus Nix session wiring; no hardware change.
Goals: Explicit touch ownership, a visible dismissal affordance, direct held motion and continuous release, safe coexistence with app navigation and typing.
Non-Goals: New key layout/IME, typing recognition, replacing wvkbd, or binding an application-wide two-finger gesture outside the shell’s edge region.
Land the proposal first. Build host policy, then integrate compositor/keyboard grip with the current motion checkpoint in an isolated worktree. Cross-build narrowly and prove native injected input before guarded board deployment. Preserve the existing Settings toggle and previous system for recovery; capture real-finger show/hide/typing before archive.
The operator accepts this delivered functional scope and waives additional
capture-only acceptance gates. docs/evidence/proposal-closeout/2026-10-01/keyboard.md records the exact report,
prior evidence and limits. Its task dispositions supersede older statements
that these acceptance gates remain open; they do not claim new test runs.
Pending measurement work is preserved in the-shell-profiles-reported-interaction-jank before archive.
Commands naming new files below are planned interfaces, not existing proof. Preserve real-glass gates until observed and commit evidence under docs/evidence/keyboard-gestures/.
python3 tests/test_keyboard_gestures.py.python3 tests/test_keyboard_gestures.py before marking complete. 2026-09-28: re-ran python3 tests/test_keyboard_gestures.py -v, 16/16 pass, including test_contact_drain (proves kg_cancel), test_surface_loss (proves kg_surface(&p,false) keyboard/output loss) and test_overlay_isolation (proves an overlay-owned contact is left KG_NONE, not consumed) — host policy evidence only.Proof: python3 tests/test_keyboard_gestures.py is host policy evidence only.
nix build .#card-shell --max-jobs 1 --cores 4 --no-link --print-out-paths under the sole build reservation.nix build .#handheld-shell-rust --max-jobs 1 --cores 4 --no-link --print-out-paths.python3 tests/test_keyboard_gestures_runtime.py against the exact built compositor and keyboard, verifying injected two-contact show, grip hide/hold/reverse, typed text ownership and settled app geometry. Record native screenshots and source/store identities.ordinary_backdrop (nix/card-shell/adapter.c), a card-coloured wlr_scene_rect in output->layers.tiling resized to the current usable_area on every ordinary_sync_usable() call — a compositor-side reposition with no client round trip — directly behind ordinary cards. Added a --stall-resize-ms fixture to card-composition-probe-client to model a slow client, and a hard-assertion regression check python3 tests/keyboard_drag_backdrop_qemu.py; confirmed it fails against the pre-fix source and passes against the fix. Evidence: docs/evidence/keyboard-drag-usable-area-gap/.Proof: the two narrow Nix builds plus python3 tests/test_keyboard_gestures_runtime.py and python3 tests/keyboard_drag_backdrop_qemu.py. Native headless QEMU does not establish panel touch reachability or smoothness, and this harness has no wallpaper renderer, so the “before” gap reads flat black rather than the real desktop wallpaper photo.
3.1 Build nix build .#nixosConfigurations.k230-coherent-shell.config.system.build.toplevel --max-jobs 1 --cores 4 --no-link --print-out-paths; record exact output and a recovery-capable installed identity via python3 tools/console.py /dev/ttyACM0 --wait=3 'readlink -f /run/current-system' while holding the board reservation.
3.2 Record operator acceptance of keyboard gestures (2026-10-01), together with the earlier standalone Foot keyboard confirmation. The operator waives additional capture; this is physical operator feedback, not a new recorded show/hold/reverse sequence.
3.3 Transfer the unperformed installed-board visibility/gesture budget measurement intact to the-shell-profiles-reported-interaction-jank task 3.1, on the operator-authorized performance deferral. This checks scope transfer, not a measured budget pass.
4.1 Retain already-published keyboard feature media and add the committed operator report to the dashboard evidence; validate the working-tree work snapshot. Additional real-touch video is waived, not fabricated.
4.2 Reconcile accepted functional scope and the explicit measurement successor; validate and archive/sync runtime/shell through the OpenSpec CLI. Source and prior media are already landed; the closeout is pushed and its publication checked separately.
The updated completed tasks describe actual acceptance, waivers and scope
transfer, not execution of the superseded protocols. See docs/evidence/proposal-closeout/2026-10-01/keyboard.md.
Historical checkpoint notes above that say physical gates remain open are
superseded by this record. Quantitative or individually unreported results
are not promoted to physical proof.
Proof: openspec validate the-keyboard-follows-touch-gestures --strict; committed operator report;
python3 scripts/render_work_board.py --working-tree --output <snapshot.json>.
Grounding: operator acceptance in docs/evidence/proposal-closeout/2026-10-01/keyboard.md, with prior source and board/QEMU evidence retaining their original classes and limits.
The system’s coherent shell SHALL reveal the external keyboard with a deliberate two-finger upward swipe from the bottom edge and expose a visible handle above a shown keyboard for downward dismissal. Settings SHALL retain an explicit keyboard action and describe the gestures. One-finger bottom navigation MUST remain available without opening the keyboard.
Grounding: operator acceptance in docs/evidence/proposal-closeout/2026-10-01/keyboard.md, with prior source and board/QEMU evidence retaining their original classes and limits.
During an accepted keyboard drag the system SHALL move the keyboard with direct proportional contact displacement, remain stationary while contact is held still, and reverse immediately with contact. Release SHALL settle from the displayed geometry and bounded measured velocity to shown or hidden without a position jump or abrupt end. Reduced motion SHALL preserve direct manipulation while shortening release settlement. Reserved app space MUST match the final visible keyboard and remain coherent during transition.
Grounding: operator acceptance in docs/evidence/proposal-closeout/2026-10-01/keyboard.md, with prior source and board/QEMU evidence retaining their original classes and limits.
The system SHALL claim only its explicit edge chord or handle stream and SHALL preserve ordinary key taps and application touch input. Cancelled, late, additional or lost contacts MUST NOT type keys, launch apps, or strand an invisible input surface. Keyboard failure, output change and interrupted settling SHALL restore a usable app and a reachable Settings action. The Wi-Fi editor’s integrated keyboard MUST retain its own explicit cancellation and focus contract.
Archived change · Archived
Snapshot 5836ef1d113d · 2026-10-17 08:22 UTC
Closed recordReview the archived record and cited scope
The installed-application drawer’s “Files” entry launches nnn inside a
Foot terminal (nix/handheld-desktop-entries.nix’s nnn.desktop). The user’s
verbatim assessment: “the ‘files’ app is fuckin awful we need a great files
app” — with two more requirements in their own words: “it has to honor
themes” and “see what omarchyists use” (i.e. what Omarchy itself ships or
would recommend, not an invented alternative).
Reading Omarchy’s own install package lists
(install/omarchy-base.packages at the pinned revision this repo already
tracks in docs/research/omarchy-quattro-theme-compatibility.md) shows
Omarchy ships nautilus and nautilus-python, plus gvfs-mtp/nfs/smb,
sushi (Nautilus’s Quick Look), gnome-disk-utility and udiskie. There is
no yazi, thunar, pcmanfm, or portfolio package anywhere in either of
Omarchy’s package lists. Omarchy’s own theming for it
(bin/omarchy-theme-set-gnome, read at the same pin) is narrow: it only
flips org.gnome.desktop.interface color-scheme between
prefer-dark/prefer-light and switches icon-theme to the resolved
theme’s Yaru variant (or a hardcoded Yaru-blue fallback) — it does not
recolor GTK/libadwaita with the resolved accent palette. Matching that scope
is feature parity with the reference implementation, not a shortfall.
A course correction during this change’s own research reset its direction:
rather than building a new native Rust/Cairo Files app, first give existing,
maintained, touch-aware Linux file managers a genuine try on this hardware,
since at least one (Nautilus) is the literal thing “omarchyists” run.
Portfolio — nixpkgs
portfolio-filemanager — is a second candidate: GTK4/libadwaita,
purpose-built for Linux phones (Librem 5, PinePhone), much smaller than
Nautilus (no tracker/localsearch/gvfs/modemmanager stack). Both are
evaluated here on their real cross-build cost and closure weight; the board
decides the rest, per AGENTS.md’s evidence-class rule (“a host build, QEMU
run, injected event, camera recording, and real glass interaction are
distinct evidence classes”).
pkgs.nautilus (Omarchy’s own choice) and
pkgs.portfolio-filemanager (a phone-first alternative already in
nixpkgs) for riscv64 and add both to the handheld’s package set, each
reachable from the drawer as a distinct “Files (Nautilus)” / “Files
(Portfolio)” entry.k230.shell.filesAppNautilus now defaults to true,
no longer gated), and remove nnn’s old terminal “Files” entry outright —
its package (pkgs.nnn), desktop entry (former nnn.desktop), launcher
wiring, and the compositor’s "nnn" -> "Files" card-title fallback are all
deleted, not just superseded. This was previously deferred to the
coordinator (see the superseded non-goal below); board launch-time/RSS/
scroll comparison is unaffected and remains a separate, still-open
hardware task (tasks.md 5.3).GSK_RENDERER=cairo (so GTK4
never attempts the GL scene renderer this Mesa-less board cannot provide),
GDK_BACKEND=wayland, and an XDG_DATA_DIRS that includes the launched
app’s own share, adwaita-icon-theme and hicolor-icon-theme — matching
operator-reported board behavior that icons were missing without the
latter two, and keeping the fix in the Nix wrapper rather than hand-made
files under /home/shell.tools/theme_gtk.py, wired into the existing tools/app_appearance.py
“app appearance” generation alongside its Foot adapter) that renders a
GSettings keyfile-backend snippet — color-scheme and icon-theme under
org.gnome.desktop.interface — from the same resolved theme generation
Foot already reads, matching Omarchy’s own omarchy-theme-set-gnome
scope exactly (dark/light + icon variant, no accent-color recolor). Both
apps’ launcher wrapper links ~/.config/glib-2.0/settings/keyfile to the
active generation’s rendered file before every launch, so a freshly
launched instance always reflects the currently active theme; there is no
xdg-desktop-portal on this image; the keyfile is read directly. Whether
an already-open window picks up a later theme change live (the keyfile
GSettings backend does watch its file) is explicitly marked
UNVERIFIED below pending a board check.nix/handheld-theme-default/gtk-settings.keyfile, generator/checker
tools/generate_default_gtk.py, following the existing
generate_default_foot.py/generate_default_keyboard.py pattern) so a
fresh home has correct GTK appearance before any theme is ever explicitly
activated.tests/test_theme_gtk.py) and its wiring into app_appearance.py
(tests/test_handheld_app_themes.py).k230-coherent-shell toplevel, and host/QEMU screenshots of both apps
under a dark and a light theme, recorded under
docs/evidence/files-app/.tasks.md 5.3) and are not required
to justify this removal.accent-color) is a follow-up, not scoped here.tinysparql/
localsearch runtime dependents are not started by this change (no
systemd user service wiring); Nautilus falls back to plain directory
reads without them. Documented as a known limitation, not solved here.The handheld cross-compiles everything from x86_64-linux to riscv64-linux
with no binary cache for the target (openspec/specs/image/cross-build).
Every GUI package already installed renders through GTK3 Cairo/Pixman or a
plain terminal, chosen specifically because this board has no Mesa/EGL/GL
driver at all (nix/shell.nix’s comment above zathuraApp). GTK4 is new to
this image: its default GSK renderer wants a GL (or, failing that, an
ngl/Vulkan) context, none of which this board can provide.
The existing theme pipeline (tools/theme_activate.py → generation
directory with report.json/colors.toml/icons.theme →
tools/theme_transaction.py::activate_generation → an acknowledged
app-appearance/active symlink built by tools/app_appearance.py::sync)
already has exactly one installed-app adapter: Foot (terminal/monitor
configs plus opt-in OSC for the caller’s own PTY). Its coverage.json
already documents what is and is not covered per generation. That adapter
is the natural place to add a second one rather than inventing a parallel
mechanism.
Goals: get real cross-build and closure evidence for both candidate file managers; make both launch from the drawer without attempting GL, and with their icons actually resolving; give both the same dark/light + icon-theme fidelity Omarchy itself gives Nautilus; ship both installed and visible by default, per the operator’s decision, with nnn’s old unusable “Files” entry removed outright rather than left as a fallback.
Non-goals: recoloring GTK/libadwaita’s accent color from the resolved
palette (Omarchy doesn’t do this either); wiring gvfs/tracker/localsearch
services; a native Files app; narrowing to a single GTK4 candidate (both
stay installed — the board-measured launch-time/RSS/scroll comparison in
tasks.md 5.3 is still open, but it no longer gates keeping both or
removing nnn, which the operator has already decided).
The course correction was explicit: try existing touch-aware file managers before building anything new, and let the board decide between Omarchy’s own choice (Nautilus) and a phone-first alternative already packaged in nixpkgs (Portfolio). Both get a drawer entry with a distinguishing name (“Files (Nautilus)” / “Files (Portfolio)”).
Originally nnn’s plain “Files” entry was left untouched as a known-working
fallback while the other two were evaluated, with any entry removal deferred
to a follow-up once the coordinator had real launch-time/RSS/scroll numbers
from the board. The operator has since made that call directly: keep both
GTK4 candidates installed and visible by default
(k230.shell.filesAppNautilus now defaults to true), and remove nnn’s
entry outright rather than keep it as a fallback — it launched inside a
terminal and was unusable on a touch handheld, so it was never a real
long-term candidate. Removed with it: pkgs.nnn from environment.systemPackages, its
nnn.desktop override, its handheld-desktop-entries.nix wiring, and the
compositor’s hardcoded "nnn" -> "Files" card-title fallback
(nix/card-shell/adapter.c). The board-measured
launch-time/RSS/scroll comparison between Nautilus and Portfolio (tasks.md
5.3) remains open and unaffected by this decision.
GSK_RENDERER=cairo in a launcher wrapper, not a patched packageGTK4 supports selecting its scene-graph renderer via the GSK_RENDERER
environment variable; cairo is the software fallback that never touches
GL/EGL. Setting it in a thin writeShellScriptBin wrapper (mirroring the
existing k230-foot/themedFoot pattern) is a one-line, narrowly-scoped
fix — no patch to nixpkgs’ gtk4 or either app’s own package, and no
rebuild cost beyond the wrapper derivation itself.
This image runs no dconf service and no xdg-desktop-portal. The
in-process keyfile GSettingsBackend (GSETTINGS_BACKEND=keyfile,
built into GLib, no extra package) reads
$XDG_CONFIG_HOME/glib-2.0/settings/keyfile directly — no D-Bus session,
no daemon, no portal implementation to install or keep alive. A session
D-Bus bus does exist on this image (/run/shell-bus/bus, nix/shell.nix),
but wiring dconf onto it would be strictly more moving parts for the same
two keys (color-scheme, icon-theme) this change actually needs.
The schema definition itself (org.gnome.desktop.interface) still has to
be discoverable regardless of backend: pkgs.gsettings-desktop-schemas is
a buildInput of nixpkgs’ nautilus package already, but not of
portfolio-filemanager, and libadwaita itself only depends on it at
build/check time (pkgs/by-name/li/libadwaita/package.nix:
gsettings-desktop-schemas appears only in the checkPhase environment,
not propagatedBuildInputs). Both launcher wrappers add it to
XDG_DATA_DIRS/GSETTINGS_SCHEMA_DIR explicitly rather than relying on
either app’s own transitive closure.
A naive ${pkgs.gsettings-desktop-schemas}/share on XDG_DATA_DIRS is not
enough, and this change’s host-native evidence harness
(docs/evidence/files-app/README.md) caught it directly: nixpkgs’ glib
setup-hook installs each package’s compiled schema under
<pkg>/share/gsettings-schemas/<name>/glib-2.0/schemas/, not
<pkg>/share/glib-2.0/schemas/, specifically so unrelated packages’
schemas never collide. With the naive path, gsettings get org.gnome.desktop.interface color-scheme returned No schemas installed
and both apps silently ignored the keyfile’s color-scheme entirely
(rendering light regardless of the keyfile). nix/shell.nix’s
filesAppSchemaDirs uses nixpkgs’ own glib.getSchemaDataDirPath passthru
helper instead of a hand-built path, which is what libadwaita’s own
checkPhase uses for the identical purpose.
app_appearance.pytools/app_appearance.py::prepare() already turns an acknowledged theme
generation into a content-addressed, cached app-appearance/generations/ <id>/ directory (terminal-foot.ini, monitor-foot.ini, coverage.json),
published at app-appearance/active only after the shell’s own commit
acknowledgement — the same fail-closed, no-partial-publish contract this
change’s GTK output needs. Adding gtk-settings.keyfile to that same
directory (read via a new gtk_appearance() helper that independently
re-reads report.json for mode/icon_theme, since palette() only
returns ANSI colors) reuses that contract instead of building a second,
parallel activation path. The per-app launcher wrapper links
~/.config/glib-2.0/settings/keyfile to
app-appearance/active/gtk-settings.keyfile immediately before every
launch — cheap, idempotent, and correct even for a process started outside
the normal drawer flow.
GKeyfileSettingsBackend does watch its backing file for changes and can
in principle notify an already-running process. Nothing in this change’s
host/QEMU evidence can exercise “a GTK4 app stays open across a real theme
switch on this board” — that is a hardware observation
(.skills/k230-spec-change/SKILL.md’s evidence-order rule: an observation
on the board outranks anything documentation says should happen). The spec
delta marks this scenario <!-- UNVERIFIED --> rather than asserting it. A
fresh launch after any theme change is unconditionally correct by
construction (the wrapper re-links the symlink every time), so the feature
degrades to “correct on next open” in the worst case, never to a stale or
wrong theme.
Every other per-generation default (terminal-foot.ini, monitor-foot.ini,
wvkbd.args) in nix/handheld-theme-default/ is a committed static file,
regenerated and diff-checked by a small tools/generate_default_*.py --check script rather than computed inside the Nix derivation. The new
gtk-settings.keyfile follows the same pattern
(tools/generate_default_gtk.py) for the same reason: it keeps the
derivation free of a native-vs-cross Python invocation, and keeps the
committed value auditable in a diff instead of opaque inside a build log.
GDK_BACKEND=wayland and the Adwaita/hicolor icon fallback chain, in the same wrapperBoard testing (performed by the operator, not reproduced by this worktree)
found icons missing from both apps unless two more things were set
explicitly: GDK_BACKEND=wayland (rather than letting GDK auto-detect,
which is otherwise fine under Sway but was the difference observed on the
board) and XDG_DATA_DIRS including adwaita-icon-theme’s and
hicolor-icon-theme’s own share directories alongside the launched app’s
own share. Both symbolic-icon lookups (GTK4/libadwaita’s own chrome:
toolbar buttons, “list-add”, etc.) and the bundled Yaru theme’s own
inheritance chain (Inherits=...hicolor/Adwaita) resolve through this
fallback, and none of the handheld’s existing packages had previously
needed adwaita-icon-theme/hicolor-icon-theme on XDG_DATA_DIRS at all.
Fixed directly in mkFilesAppLauncher (nix/shell.nix) rather than as
hand-made files under /home/shell, per the operator’s explicit direction,
so a fresh home never depends on anything not reproduced by the Nix build.
This repository’s own board re-check of this specific fix is still
outstanding (tasks.md 5.3); it is recorded here as the operator’s report,
not as evidence this worktree gathered itself.
GtkMediaFile backend), which is why even the
smaller candidate (Portfolio) has a large riscv64 build list — this is
intrinsic to GTK4 on this nixpkgs pin, not something either app’s choice
changes. See tasks.md for the measured derivation counts and, once the
full system build finishes, the closure-size delta.tracker/localsearch
running falls back to synchronous directory reads; large directories may
be slower to populate than on a full GNOME desktop. Untested on this
board; flagged for the coordinator’s scroll/large-directory check.accent-color), once it is confirmed to have any observable effect
without a portal.tasks.md 5.3) surfaces a decisive reason to drop one. Not expected by
default now that both are the operator’s chosen shipped state.docs/research/omarchy-quattro-theme-compatibility.md
(install/omarchy-base.packages, install/omarchy-other.packages) and
its GNOME theming script (bin/omarchy-theme-set-gnome). Verify with:
curl -s https://raw.githubusercontent.com/omacom/omarchy/master/install/omarchy-base.packages
and the same path for bin/omarchy-theme-set-gnome. Done: confirms
nautilus/nautilus-python are Omarchy’s shipped file manager, no
yazi/thunar/pcmanfm/portfolio anywhere in either package list, and that
Omarchy’s own GTK theming is dark/light color-scheme + icon-theme only
(no accent-color recolor).basecamp/omarchy (the name in the user’s request) and
omacom/omarchy (the name this repo’s existing research already pinned)
are the same project. Verify with:
curl -s https://api.github.com/repos/basecamp/omarchy (redirect) then
curl -sL https://api.github.com/repositories/994093166. Done: confirmed
redirect to omacom/omarchy.portfolio-filemanager (nixpkgs pkgs.portfolio-filemanager,
upstream tchx84/Portfolio) exists at the pinned nixpkgs revision this
flake already locks, and read its package.nix build inputs. Verify with:
a store read of
pkgs/by-name/po/portfolio-filemanager/package.nix in this flake’s
locked nixpkgs input tree. Done: GTK4/libadwaita/PyGObject, no
gvfs/tracker/modemmanager/polkit stack in its own buildInputs.grep -n "nnn" nix/shell.nix nix/handheld-desktop-entries.nix. Done:
nnn in Foot, nix/handheld-desktop-entries.nix’s nnn.desktop.pkgsCross.riscv64 at this
flake’s locked nixpkgs revision. Verify with:
nix build --file nix/files-app-probe.nix portfolio --dry-run --no-link
and the same for nautilus. Done: portfolio 129 derivations to build /
417 paths fetched (838.2 MiB); nautilus 205 derivations to build / 197
paths fetched (1.1 GiB) — nautilus’s larger build list is tinysparql,
localsearch, gnome-user-share, glycin/libjxl, webrtc-audio- processing, modemmanager and friends; both pull the same GTK4/
libadwaita/GStreamer core, which portfolio’s build list shows is intrinsic
to GTK4 on this pin, not a candidate-specific cost.pkgsCross.riscv64.portfolio-filemanager. Verify with:
nix build --file nix/files-app-probe.nix portfolio --no-link --print-out-paths --max-jobs 1 --cores 4.
PASS: /nix/store/q0zq2kivvqilcz12wswvwrwp9caa6a8j-portfolio-1.0.3-riscv64-unknown-linux-gnu,
closure 1.2 GiB (nix path-info -Sh). All 129 derivations built from
source, no patches needed. On this shared, heavily contended build host
(uptime showed load average ~46-52 against 32 cores throughout), wall
clock was several hours; gtk4/libadwaita/GStreamer’s own dependency graph
(not portfolio-specific) is the bulk of it.pkgsCross.riscv64.nautilus. Verify with the same command
form against the nautilus attribute. Launched after 2.2 reached its own
gtk4/libadwaita derivations, so those were shared/reused rather than
rebuilt (confirmed: no building 'gtk4-riscv64... or
'libadwaita-riscv64... line reappears in nautilus-build.log). PASS:
/nix/store/2mrz6i0r38z0pjxxn451vc68sqr8lv7m-nautilus-riscv64-unknown-linux-gnu-50.2.2,
closure 1015.3 MiB (nix path-info -Sh) — smaller than Portfolio’s own
1.2 GiB standalone number despite Nautilus’s larger dependency list
(tracker/localsearch/gnome-user-share/modemmanager), because Portfolio’s
own closure count already carries the full gtk4-pulled GStreamer/media
stack that both share; Nautilus’s marginal cost on top of that shared
base is smaller than it looks from derivation counts alone.tools/theme_gtk.py: render [org/gnome/desktop/interface]
color-scheme/gtk-theme/icon-theme GSettings-keyfile text from a
resolved mode/icon_theme pair, matching
bin/omarchy-theme-set-gnome’s own scope and fallback
(Yaru-blue). Verify with: python3 -m pytest tests/test_theme_gtk.py -q.
Done: 9 tests (dark/light, missing-icon fallback, invalid mode, invalid/
over-length/empty icon selectors, quoting, injection-surface check).tools/app_appearance.py::prepare() alongside the
existing Foot adapter: new gtk_appearance() reader, gtk-settings.keyfile
written into the same content-addressed, cache-validated generation
directory, coverage.json updated. Verify with:
python3 -m pytest tests/test_handheld_app_themes.py -q. Done: 11 tests,
including cache-tamper rejection for the new file (mirroring the existing
Foot-config tamper check).gtk-settings.keyfile for a fresh home
(nix/handheld-theme-default/gtk-settings.keyfile,
tools/generate_default_gtk.py, installed for both the bundled and
recovery generations in nix/handheld-theme-default/default.nix).
Verify with: python3 -m pytest tests/test_handheld_theme_default.py -q
and python3 tools/generate_default_gtk.py --check.mkFilesAppLauncher in nix/shell.nix):
GSK_RENDERER=cairo, GSETTINGS_BACKEND=keyfile,
gsettings-desktop-schemas + theme icons on XDG_DATA_DIRS, and the
~/.config/glib-2.0/settings/keyfile symlink re-linked to the active (or
pinned default) generation before every launch. Verify with:
nix-instantiate --parse nix/shell.nix (syntax) now, nix build .#nixosConfigurations.k230-coherent-shell.config.system.build.toplevel
(full closure) once both candidates finish building — task 5.1. Done:
the host-native screenshot harness (task 5.2) caught a real bug in the
first draft of filesAppSchemaDirs (plain <pkg>/share on
XDG_DATA_DIRS does not expose nixpkgs’ per-package-nested
gsettings-schemas layout — gsettings get returned “No schemas
installed” and both apps ignored color-scheme entirely) before it ever
reached a cross-build; fixed with glib.getSchemaDataDirPath, re-verified
by the same harness. See docs/evidence/files-app/README.md.dev.tchx84.Portfolio.desktop / org.gnome.Nautilus.desktop in
nix/handheld-desktop-entries.nix, using the exact upstream desktop IDs
(so this repo’s override precedes each package’s own installed entry in
XDG_DATA_DIRS order, same pattern the file’s own header comment already
documents) with distinguishing Name= values (“Files (Nautilus)” /
“Files (Portfolio)”); nnn’s nnn.desktop “Files” entry unchanged at the
time. Verify with: nix-instantiate --parse nix/handheld-desktop-entries.nix.
Superseded by task 6.1: nnn’s entry is since removed outright, not
left unchanged.filesAppNautilus defaults
off; per coordinator direction, do not wait on Nautilus’s own build for a
testable system). Verify with:
nix build .#nixosConfigurations.k230-coherent-shell.config.system.build.toplevel --max-jobs 1 --cores 6 --no-link --print-out-paths.
PASS: /nix/store/jv44pdh4al448zfl7h33l87pl3n4wmbq-nixos-system-nixos-26.11.20260919.20b1ddd.
Closure delta against origin/master (292ee81624fd, builtins.getFlake "git+file://<repo>?rev=...", same k230-coherent-shell configuration,
no source changes otherwise), measured as an independent per-path
nix-store -q --size sum over nix-store -q --requisites (not nix path-info -rS, per coordinator’s request that these be cross-checked
separately):
| requisite paths | summed size | |
|---|---|---|
| master baseline | 1041 | 3.196 GiB |
| Portfolio-only system | 1114 | 3.576 GiB |
| delta | +73 net (97 new, 24 superseded same-named rebuilds) | +389.0 MiB (+0.380 GiB) |
The 24 superseded paths (dbus-1, etc, foot, this repo’s own | ||
k230-*/unit-*.service/system-path/system-units derivations) are | ||
| the same conceptual thing rebuilt with a new hash because the closure | ||
| around them changed, not new weight. The 73 genuinely new packages are | ||
| overwhelmingly GTK4’s own default GStreamer media backend closure | ||
| (libdvdnav/libdvdread/libdvdcss, libdc1394+libraw1394 FireWire camera, | ||
| gupnp/gupnp-igd UPnP, webrtc-audio-processing, openh264, tinysparql, | ||
| chromaprint, …) plus gtk4-riscv64, libadwaita-riscv64 and | ||
portfolio-1.0.3-riscv64 themselves — confirming design.md’s “closure | ||
| weight is intrinsic to GTK4 on this nixpkgs pin” note with an exact, | ||
| itemized list rather than an estimate. See | ||
docs/evidence/files-app/closure-delta.md. |
k230-coherent-shell-both-files-apps, filesAppNautilus = true).
Verify with the same command against that configuration. PASS:
/nix/store/b2f6yqk428w599jcc7w6rcjawld85bp6-nixos-system-nixos-26.11.20260919.20b1ddd.
Same per-path nix-store -q --size sum method:
| requisite paths | summed size | |
|---|---|---|
| master baseline | 1041 | 3.196 GiB |
| Portfolio-only | 1114 | 3.576 GiB |
| Both apps | 1154 | 3.704 GiB |
| Nautilus’s own marginal delta (both vs. Portfolio-only) | +40 net (54 new, 14 superseded) | +130.4 MiB (+0.127 GiB) |
| both apps vs. master | +113 net | +519.4 MiB (+0.507 GiB) |
| Nautilus’s marginal byte cost is much smaller than its own 1015.3 MiB | ||
| standalone closure, because gtk4/libadwaita/GStreamer’s bulk is already | ||
| shared with Portfolio; what Nautilus adds on top is real, itemized | ||
| dependency-surface growth rather than size: iOS/USB device sync | ||
(libimobiledevice+libusbmuxd+libplist+libtatsu), network | ||
directory sharing (gnome-user-share+apache-httpd+mod_dnssd), | ||
localsearch+tinysparql full-text indexing, polkit, LDAP | ||
(openldap+cyrus-sasl), PDF (poppler-glib/poppler-data, | ||
libgxps), image metadata (gexiv2/exempi), libnotify, | ||
libcloudproviders, libosinfo+osinfo-db, gnome-autoar, | ||
gnome-desktop, nautilus-riscv64-unknown-linux-gnu-50.2.2 and | ||
k230-nautilus (this change’s launcher) themselves. See | ||
docs/evidence/files-app/closure-delta-both-apps.md. |
portfolio-filemanager/
nautilus builds — substituted from cache.nixos.org, not the riscv64
cross build — under Xvfb with the same GSK_RENDERER=cairo/
GSETTINGS_BACKEND=keyfile the board wrapper sets, driven by a keyfile
tools/theme_gtk.py rendered. docs/evidence/files-app/README.md and
docs/evidence/files-app/host/*.png, with blob-inventory rows. QEMU
screenshots (riscv64 binary, patched Sway, qemu-riscv64-static, this
repo’s existing brightness/volume-slider QEMU harness pattern) not done in
this change — blocked on 2.2/2.3’s riscv64 builds finishing.docs/evidence/files-app/board-2026-09-30/README.md. Repeatable board command
is recorded there. These are warm-cache surface-map measurements, not
first-frame latency or quantified scrolling FPS. Keep both by the existing
operator decision; no further candidate selection remains.k230.shell.filesAppNautilus default flipped from false to true in
nix/shell.nix; k230-coherent-shell-both-files-apps in flake.nix is
now identical to k230-coherent-shell, kept only so anything naming it by
attribute still resolves), and remove nnn’s old terminal “Files” entry
outright rather than leave it as a fallback. Verify with:
grep -rn nnn nix/shell.nix nix/handheld-desktop-entries.nix finding only
historical/explanatory comments, no live wiring.pkgs.nnn
dropped from environment.systemPackages and from
handheld-desktop-entries.nix’s inputs, the nnn.desktop override
deleted from handheld-desktop-entries.nix, and the compositor’s
hardcoded "nnn" -> "Files" card-title fallback removed from
nix/card-shell/adapter.c. Add GDK_BACKEND=wayland and
adwaita-icon-theme/hicolor-icon-theme/the app’s own share to
mkFilesAppLauncher’s XDG_DATA_DIRS in nix/shell.nix (operator-
reported board fix for missing icons), in the Nix wrapper rather than
hand-made files under /home/shell. Verify with:
nix-instantiate --parse nix/shell.nix nix/handheld-desktop-entries.nix flake.nix and nix flake check --no-build.tests/test_card_shell_deck_title.py (drop the "nnn" -> "Files" card
title case), tests/handheld_desktop_entries_probe.c (drop nnn.desktop
from the probed IDs), tools/app_appearance.py and
tests/test_handheld_app_themes.py (drop "nnn" from the "inherited"
theme-coverage list). Verify with:
python3 -m pytest tests/test_handheld_app_themes.py tests/test_theme_gtk.py tests/test_handheld_theme_default.py -q
and gcc -Wall -Wextra -Werror tests/handheld_desktop_entries_probe.c -o /tmp/probe $(pkg-config --cflags --libs gio-unix-2.0).
tests/test_card_shell_deck_title.py itself fails to compile on this
host’s GCC independent of this change (desktop_identity_icon: unused-
function under -Werror, reproduced identically on the pre-edit
commit) — not fixed here, out of this change’s scope.nix build .#nixosConfigurations.k230-coherent-shell.config.system.build.toplevel --max-jobs 1 --cores 6 --no-link --print-out-paths.
PASS: /nix/store/6m8avy8didrmf6c0znlhqw40l82dq5sz-nixos-system-nixos-26.11.20260919.20b1ddd.
Only 31 derivations needed building (the wrapper/desktop-entry/adapter.c
and their dependents); the riscv64 portfolio-filemanager/nautilus
packages themselves were unaffected by this task group’s changes and did
not need rebuilding. This is a host evaluation/build proof only, not
board evidence — see 5.3.openspec validate --all --strict exits 0 after this task
group’s proposal/spec edits (owner: this change, checked directly, not
through a pipe to tail). PASS: Totals: 60 passed, 0 failed (60 items),
exit code 0.Provide two installed touchscreen file managers with reproducible software rendering, icon resolution and theme appearance from the handheld’s Nix image.
Grounding: docs/research/omarchy-quattro-theme-compatibility.md’s pinned
Omarchy revision and this change’s install/omarchy-base.packages read
confirm Nautilus is Omarchy’s own shipped file manager. Portfolio
(portfolio-filemanager) is read directly from this flake’s locked
nixpkgs package.nix. Cross-build feasibility is grounded in
nix build --file nix/files-app-probe.nix ... --dry-run output recorded
under docs/evidence/files-app/, not assumed. The decision to keep both by
default and remove nnn’s old entry outright is an operator decision
recorded in this change’s design.md/tasks.md, not a board measurement.
The system SHALL make Nautilus and Portfolio available as distinct
installed-application drawer entries, each cross-built for the board’s
riscv64 target, installed and visible by default
(k230.shell.filesAppNautilus defaults to true), and SHALL NOT ship
nnn’s previous terminal “Files” entry, its package, or any launcher/
card-title wiring for it.
coherentShell buildGrounding: this board has no Mesa/EGL/GL driver
(nix/shell.nix’s comment above zathuraApp; AGENTS.md’s hardware
description). GTK4’s default GSK renderer requires GL/Vulkan; cairo is
its documented software fallback.
Each candidate’s drawer entry SHALL launch through a wrapper that sets
GSK_RENDERER=cairo before executing the application.
GSK_RENDERER=cairo set in its environmentGrounding: docs/evidence/files-app/board-2026-09-30/README.md records
actual desktop-wrapper launches on the installed board, application process
checks for Wayland and application/adwaita/hicolor shares, original native
captures showing resolved icons, and operator acceptance of both apps’ icons
and scrolling. The configuration is in nix/shell.nix’s mkFilesAppLauncher,
not hand-made files under /home/shell.
Each candidate’s launcher wrapper SHALL set GDK_BACKEND=wayland and SHALL
include the launched application’s own share directory,
adwaita-icon-theme’s share directory, and hicolor-icon-theme’s
share directory on XDG_DATA_DIRS, entirely from the Nix configuration.
GDK_BACKEND=wayland set, and XDG_DATA_DIRS includes that
application’s own share, adwaita-icon-theme’s share, and
hicolor-icon-theme’s share, without relying on any file outside the
Nix store under the launching user’s home directoryGrounding: bin/omarchy-theme-set-gnome (pinned upstream revision) is the
reference behavior being matched — dark/light color-scheme plus an
icon-theme switch, no accent-color recolor. tests/test_theme_gtk.py and
tests/test_handheld_app_themes.py are the host-side proof; no on-panel
rendering claim is made by this requirement.
The system SHALL derive org.gnome.desktop.interface color-scheme and
icon-theme from the same resolved theme generation the existing Foot
appearance adapter reads (tools/app_appearance.py), publish them as a
GSettings keyfile-backend file inside that generation’s app-appearance
directory, and re-link each candidate’s GSettings keyfile-backend
configuration to that file (or, before any theme has been explicitly
activated, to a pinned default) immediately before every launch.
mode = "dark" and
icon_theme = "Yaru-purple"gtk-settings.keyfile contains
color-scheme='prefer-dark' and icon-theme='Yaru-purple'~/.config/glib-2.0/settings/keyfile resolves to that theme
generation’s gtk-settings.keyfile, not to any earlier generation’s file
or to the pinned default~/.config/glib-2.0/settings/keyfile resolves to the pinned
default generation’s gtk-settings.keyfile, matching the pinned bundled
theme’s mode/icon_themeGrounding: tests/test_theme_gtk.py’s injection-surface and bound tests;
tests/test_handheld_app_themes.py’s cache-tamper test.
The GTK appearance adapter SHALL reject an unrecognized mode, an
icon-theme selector containing characters outside
[A-Za-z0-9._+-], an empty selector, or a selector over 160 characters,
and SHALL fall back to Yaru-blue when no icon theme is selected at all,
matching omarchy-theme-set-gnome’s own fallback.
icon_theme contains a character outside
the allowed set (for example a newline or a [)icon_theme is absentgtk-settings.keyfile sets icon-theme='Yaru-blue'Archived change · Archived
Snapshot 5836ef1d113d · 2026-10-17 08:22 UTC
Closed recordReview the archived record and cited scope
The operator reports that the Home weather widget shows Celsius and wants Fahrenheit. The unit must be an image default, including existing cached weather.
None.
runtime/shell: Home weather presents Fahrenheit.nix/rust-shell-client/src/home_widgets.rs and src/render.rs. Cache fields and network fetches retain Celsius. The separate terminal weather app and a unit-picker UI are outside this change.
The weather source and cache store explicit Celsius fields; the renderer currently draws those integers directly with a degree sign. Converting the cache would invalidate existing values and could cause double conversion.
Format Celsius as rounded Fahrenheit at the rendering boundary using C × 9/5 + 32. Include °F on every temperature label. Fresh and stale snapshots share the renderer, so cached offline weather changes immediately too. Keep unavailable placeholders unchanged.
Deploy the same coherent HDMI trial system profile with the Chicago timezone and proven touch/compositor selection preserved. Refresh shell-ui to run the installed Rust binary.
Cross-building proves the changed binary. An installed profile and board-native screenshot establish runtime deployment and displayed units separately; they do not establish new gesture or reboot acceptance.
nix build .#nixosConfigurations.k230-coherent-shell-hdmi-trial.config.system.build.toplevel --no-link --print-out-paths.python3 tools/console.py /dev/ttyACM0 --wait=3; capture Home using board-native grim and inspect the weather temperatures. Commit only reviewed, cropped widget evidence without private location or unrelated screen content. This is rendered board capture, not finger or reboot proof.openspec validate the-weather-widget-shows-fahrenheit --strict, commit the source/evidence, merge and push master, and inspect the matching Pages deployment.Grounding: docs/evidence/fahrenheit-weather/README.md, activation.log and the cropped native capture establish physical-board deployment and Fahrenheit rendering. Finger and reboot proof are not claimed.
The Home weather widget SHALL display current, daily high/low and hourly temperatures in rounded Fahrenheit with an explicit °F label. Fresh and stale Celsius cache snapshots SHALL retain their existing schema and receive the same display conversion.
Archived change · Archived
Snapshot 5836ef1d113d · 2026-10-17 08:22 UTC
Closed recordReview the archived record and cited scope
The operator wants the handheld clock to use America/Chicago rather than UTC. The timezone must be the reproducible image default, so a new image uses it without restoring user state.
America/Chicago in the shared NixOS configuration.None.
system/nixos-config: the image provides America/Chicago as its local timezone.nix/k230.nix, the generated system closure, and physical console evidence. The shell clock already uses libc local time. This does not change UTC system time, NTP policy, RTC persistence, gesture behavior, or add timezone settings UI. Nix evaluation/build is host proof; observing the effective device setting requires the reserved board.
The shared base currently leaves the timezone at the NixOS default. The shell clock already uses libc localtime_r and /etc/localtime.
Use the requested timezone for the running board and every board profile. RTC persistence and a timezone picker are outside this change.
Set time.timeZone in nix/k230.nix, the Nix layer shared by the hardware profiles. A runtime-only timedatectl setting cannot define a fresh image default, so it is only the immediate activation step. Retain the existing UTC/NTP/RTC policies.
A running client may retain its libc timezone state. Refresh only the shell UI if necessary; preserve the compositor and apps. Deploy the coherent HDMI trial profile so the proven renderer and touch routing remain selected.
nix eval --raw .#nixosConfigurations.k230-coherent-shell-hdmi-trial.config.time.timeZone returns America/Chicago.nix build .#nixosConfigurations.k230-coherent-shell-hdmi-trial.config.system.build.toplevel --no-link --print-out-paths; record its store path and localtime target (cross-build proof).python3 tools/console.py /dev/ttyACM0 --wait=3 'timedatectl show -p Timezone -p NTPSynchronized' 'date +%Z%z' 'readlink -f /run/current-system'; confirm Chicago while retaining shell and shell-ui active. This is activation proof, not a reboot or RTC-retention test.openspec validate the-clock-uses-chicago-time --strict, commit the evidence and source, merge and push, and inspect the matching Pages result.The system SHALL use America/Chicago as its local timezone, providing Central local time to applications without restoring home-directory state. This is owned by the NixOS system; it does not change the UTC hardware-clock or synchronization policy.
Grounding: docs/evidence/chicago-clock/runtime.json records the physical board reporting Timezone=America/Chicago and a local CDT offset after the requested runtime setting. The repository configuration and installed profile are verified separately in the same evidence directory.
timedatectl reports America/Chicago and ordinary local-time output uses the zone’s current offsetArchived change · Archived
Snapshot 5836ef1d113d · 2026-10-17 08:22 UTC
Closed recordArchived after matching-system installation and operator acceptance of the rounded cards.
The operator asked directly: “have a design agent review our whole shell
setup and make it polished af also i think the cards should have a border
radius and fill a lot of the screen not be tiny idk more like android
does.” docs/design/shell-polish-review-2026-09.md (this change’s
companion review) covers the whole shell; this change implements the one
piece of that ask the operator stated as an explicit, concrete requirement
rather than a general “make it nicer”: the card overview.
Before this change, the overview’s focused card (cs_default_config,
nix/card-shell-policy/card-shell-policy.c) was 50% of the panel’s width
and 60% of its height, with an 8px corner radius on its content plate
(CARD_PLATE_RADIUS, nix/card-shell/adapter.c) — a webOS-style “fan” of
2-3 small cards, chosen and recorded in the still-open
the-shell-behaves-as-one-coherent-system change’s design.md decision 1
after an earlier round of board/real-glass feedback. That decision is not
wrong on its own terms, but it is not what the operator is asking for now:
Android’s recents carousel shows one focused, near-full-panel,
phone-aspect-ratio card with only a thin sliver of neighbours peeking at
the edges, and a visibly rounded corner radius proportional to that larger
card.
card_shown_large predicate) — the first pass
computed this interpolation but fed it to a plate that was hidden for the
whole transition, so it was never actually visible; this pass’s version
is the first one a capture can actually show.tasks.md).docs/design/shell-polish-review-2026-09.md’s
findings (shade quick-toggle tiles, Settings pressed-state feedback,
velocity-aware expand/collapse easing, the touch-target physical-size
gap). Those are recorded in that review as quick wins, medium, or
structural work for separate changes.the-shell-behaves-as-one-coherent-system’s
own open slices (B, C) or its design.md decision 1 record of the prior
webOS-fan choice; it supersedes that one number (card size), the same way
that change’s own decision 1 already superseded an earlier, smaller pass,
and says so in both files.runtime/shell (the Sway/Pixman handheld session;
see openspec/specs/runtime/shell/spec.md — no existing requirement
there specifies overview card proportions or corner radius, so this adds
one rather than modifying the stale, generation-1 “metadata-only window
overview” requirement already in that file, which describes a different,
no-longer-shipped launcher mode).nix/card-shell-policy/card-shell-policy.{c,h},
nix/card-shell/adapter.c, nix/card-shell/render.{c,h},
nix/card-shell/rounded-clip.h, nix/card-shell.nix,
nix/patches/wlroots-k230-rounded-clip.patch,
tests/card_shell_policy_driver.c.docs/evidence/card-shell/android-sized-cards/ (headless-QEMU
before/after screenshots).tasks.md); this proposal
claims host-build and headless-QEMU evidence only.Layer: userspace, the C compositor’s card policy
(nix/card-shell-policy/card-shell-policy.c) and its adapter/renderer
(nix/card-shell/adapter.c, nix/card-shell/render.c). No device tree,
kernel change. The transparent-corner correction extends pinned wlroots
through nix/card-shell.nix; other compositor packages stay unchanged.
the-shell-behaves-as-one-coherent-system’s design.md decision 1 already
records one revision of this same number (an original small pass, then a
50%/60% webOS-fan pass “after board/real-glass review”). This change is a
second, operator-directed revision of the same decision, not a new decision
axis — recorded here rather than by editing that other change’s still-open
design.md, since that document belongs to a different in-flight change and
this repo’s worktree discipline says not to edit another change’s files.
1. Card size: 80% of panel width AND 80% of panel height, not independent
fractions. The prior pass used two different fractions (50% width, 60%
height) picked to fit a specific vertical budget, which left the card’s own
aspect ratio not matching the panel’s. Using the same fraction on both
axes guarantees card_width/card_height == width/height exactly — the card
is phone-shaped by construction, not by a second, separately-tuned number.
80% sits at the low end of the operator’s own “roughly 80-85%” framing,
chosen to leave enough vertical budget for the header (icon + app name,
44px + 14px gap) and the existing 56px footer/hint band without needing to
shrink either past this repo’s own minimums (footer_height>=56); see
card-shell-policy.c’s valid_config.
2. Reduce title_height from 100 to 70, not the footer or inset. The
80%-height card needs slightly more vertical budget than the 100px title bar
left available. footer_height and inset already sit at this repo’s
declared minimums (56 and 24); title_height’s own minimum is lower (56),
and the title bar’s only content (a short “Home”/app-name string plus a
status cue) does not need 100px to read comfortably. This is also a small,
independent win in the same direction as
docs/design/shell-polish-review-2026-09.md’s dead-space findings, though
it is not itself one of that document’s numbered findings.
3. No plate, no pad, for live cards — a coordinator correction after
review. The first pass of this change kept the existing content plate
(a themed, filled, stroked rounded rect drawn behind the live mirror,
inset from the card slot by a 32px pad so its rounded corner would peek
out around the square content). Reviewing the resulting screenshots, the
coordinator identified that this reintroduced exactly what the operator
had separately, explicitly rejected: “when i swipe up to see active
windows the cards have some background behind them that’s no good they
should just be cards.” A 32px pad with a themed fill is a visible
background/border, regardless of how small the number sounds. Live
cards now have no plate at all. The mirrored content fills the entire
card slot (sync_card’s box computation drops the pad term entirely —
box_x/box_y/box_width/box_height are now exactly the content’s own
aspect-fit rect, full stop), which also directly satisfies the “use the
space” ask: content now genuinely reaches ~80% of the panel width, where
the padded version only reached ~69% (card_width - 2*32px).
Non-live placeholder cards (private/unavailable content, which has no
live pixels of its own to round) are the one remaining user of a plate
(card_background/card_plate_scene), unchanged in kind, since there is
nothing else to draw for those and no live content to protect from a
background.
4. Round the ordinary compositor draw, revealing the real wallpaper. The initial implementation painted backdrop-colored squares over each live corner. That only matched a solid canvas; it was not a rounded clip. The operator explicitly rejected this approximation. Its original host/QEMU captures remain historical evidence, not proof of wallpaper correctness.
The pinned wlroots 0.20 scene API has rectangular subsurface clips and render-pass region clips, but no rounded scene clip. A narrow local extension adds destination-local rounded bounds to a scene buffer and passes them through to Pixman. The adapter sets the same card-space shape on every mirrored descendant after its ordinary rectangular crop. Thus partially visible neighbors, alpha clients, subsurfaces, transformed source buffers, and cached RGB565 thumbnails all use the same shape. No app surface is mutated; no full-card alpha copy or snapshot is introduced.
Pixman draws the interior normally and composites the four corner squares through small antialiased A8 coverage masks. An eight-entry renderer-owned LRU caches radius/opacity masks (at most 2 MiB with the 256px guard; normal 26px masks use 2,704 bytes each), freed with the renderer. Source crop, source transform, destination position, and damage clipping keep their ordinary render-pass semantics. Scene damage handles radius changes. Opaque-region accounting retains only the interior cross so the wallpaper is rendered under corners. Rounded nodes cannot bypass clipping through direct scanout. Allocation/unsupported-radius failure rejects the render pass instead of silently drawing square corners.
This extension is implemented for the production Pixman renderer only; VG-Lite/GLES/Vulkan rounding is not claimed. The experimental GPU package is unchanged. The card-shell package explicitly uses Pixman.
Rejected: the inherited alpha-thumbnail draft. It doubled the RGB565 cache memory, only rounded fully visible opaque SHM buffers, missed clipped neighbors and alpha/subsurface cases, and mutated cached pixels without scene damage. Repairing that optimization into a second general renderer would duplicate the compositor’s existing source handling.
5. Radius interpolation only for the card(s) actually changing size, not
every card in the deck. sync_card’s entering flag is mode-wide (true
for every card, including ordinary stationary neighbours, for the whole
duration of any app-switch gesture), but only the dragged card (and its
full_clip companion during a shared full-frame entry) or the tap-expanded
card actually grow/shrink between full-screen and deck size —
card_shown_large(c), already defined in this file for exactly this
distinction, is reused to gate the interpolation. A card for which
card_shown_large is false always uses the full CARD_CORNER_RADIUS
(steady, cheap, cache hits every frame); a card for which it is true gets
CARD_CORNER_RADIUS * entry_progress (entering) or
CARD_CORNER_RADIUS * (1 - expand_progress) (expanding), 0 at full screen
rising to the full radius once settled. This corrects a latent gap in
this change’s own first pass: that pass computed an equivalent
interpolated value but fed it to a plate that was unconditionally hidden
for the entire duration of any entering/expanding transition (the
pre-existing hidden = entering || expanding gate on the old
card_background call), so the interpolation, while present in the code,
was never actually visible in any capture. Rounded clips are not hidden
during the transition — they are the only rounding a live card has, and
the whole point is to see the radius grow in as the card grows into the
deck — so this version of the interpolation is the first one that is
actually observable.
6. The direct-switch (bottom-edge) entry gesture’s own target rect
(entry_card_width/entry_card_height) is untouched. This repo already
decoupled that gesture’s anchor/travel geometry from the overview’s own
card size for exactly this reason (a design goal from the prior pass,
restated in card-shell-policy.h’s field comments); this change keeps that
decoupling and does not touch cs_entry_target_rect.
7. Test fixtures that hardcoded absolute pixel drag distances are
rewritten as fractions of the pitch (card_width + gap), not scaled by a
one-off constant. Several existing card_shell_policy_driver.c cases
(horizontal, scroll_catch_mid_coast, stream_cancel,
stream_cancel_multitouch) used a fixed 180px drag to exercise “drag well
past half a card and commit to the next one.” With the pitch now ~58%
wider, that same absolute distance no longer crosses half the new, wider
pitch — not a regression in the gesture’s formula (unchanged), but a
fixture tuned to the old geometry. Rewriting these as pitch * .6 (a
fraction already used elsewhere in the same file, e.g.
scroll_slow_release_snaps_nearest) keeps the same relative intent (“a
firm drag past half a card”) and makes the fixture correct for any future
card-size revision, not just this one. scroll_fling_multi_card and
scroll_end_clamp_soft needed their velocity samples recalibrated for
the same reason (a fixed flick speed now projects proportionally less
distance across the wider pitch); their fixed dx-clamp-based reach
(scroll_end_clamp_soft’s “land on the last card” case) was rewritten as a
two-sample flick, since a single drag’s raw position is capped at 2 * width regardless of pitch and can no longer alone reach the last card of a
4-card deck at this wider pitch — this is a real, if narrow, structural
note: a single drag (no velocity) genuinely cannot span an arbitrarily
wide deck in one gesture on this panel; a flick (drag + velocity)
always can, because the velocity term is not subject to that same
position-space cap. No production code enforces or needs a “reach the far
end via drag alone” guarantee; only this test assumed it.
card_radius field on cs_config. Rejected: radius is a
rendering-only concern, matching this codebase’s existing separation of
policy (geometry, gesture math) from rendering (colours, radii, fonts) —
card-shell-policy.h’s own header comment states this policy struct
“never stores… ” rendering concerns. Keeping CARD_CORNER_RADIUS in adapter.c preserves that boundary.No data migration. The existing geometry changes remain in the policy and its runtime recompute site. The compositor correction is selected by the card-shell package’s local wlroots override; the separate experimental GPU package is unchanged. There is no visual opt-in flag for transparent corners. Review and land the source/evidence, then activate a matching combined system under the coordinator’s board reservation before claiming physical proof.
tasks.md.title_height’s reduction from 100 to 70 needs any Rust-side
companion change (the Rust overlay client renders its own, separate
Settings/Drawer/Shade chrome and is not affected by this C-side constant,
confirmed by grep: title_height is a cs_config field, never read by
nix/rust-shell-client/src/*.rs) — not expected, not verified further
here.The initial geometry and solid-canvas implementation has host/QEMU proof. Group F corrects its wallpaper corner rendering; its proof is tracked separately. Real-finger acceptance remains open.
cs_default_config’s card_width/card_height from
.5*width/.6*height to .8*width/.8*height (nix/card-shell-policy/card-shell-policy.c),
matching the panel’s own aspect ratio. Reduce title_height from 100 to
70 to fit the taller card within the existing valid_config bounds
(inset, footer_height unchanged, both already at their declared
minimums). Recompute card_top_offset for the new numbers, keeping the
same centering formula.nix/card-shell/adapter.c’s runtime
config recompute (the real per-output path, distinct from the test-only
cs_default_config defaults), which already reads title_height from
the shared cs_default_config call so no separate edit was needed there.card-shell-policy.h’s field comment describing
card_width/card_height to record the new sizing and supersede the
prior “webOS-fan, 55-65%” comment, per this repo’s “record what was
rejected and why” convention.tests/card_shell_policy_driver.c’s overview_geometry
case: width/height fractions (75-85% band), neighbour-peek assertion
(now a thin ≤15%-of-card-width sliver, not ≥30%), third-card assertion
(now fully off-screen, not merely <15%). Recompute the entry-target
independence assertions (unchanged formula, still checked exactly).horizontal, scroll_catch_mid_coast, stream_cancel,
stream_cancel_multitouch: 180px → pitch*.6; scroll_fling_multi_card:
recalibrated two-sample velocity so a fast flick still projects past two
cards at the new pitch; scroll_end_clamp_soft: the “land on the last
card” drag rewritten as a two-sample flick, since a single drag’s raw
reach is capped at 2*width regardless of pitch and no longer alone
spans a 4-card deck at the new, wider pitch). See design.md decision 7.cc -std=c11 -Wall -Wextra -Werror -pedantic -g -fsanitize=address,undefined -fno-omit-frame-pointer -I nix/card-shell-policy tests/card_shell_policy_driver.c nix/card-shell-policy/card-shell-policy.c -lm -o /tmp/policy-test, then
every case in tests/test_card_shell_state.py’s CASES list run against
that binary, and python3 -m pytest tests/test_card_shell_state.py -q:
36 passed. Host build proof, no board.Revised after coordinator review of the first pass’s screenshots, which
kept a padded plate behind live content — exactly what the operator had
separately rejected (“the cards have some background behind them …
they should just be cards”). See design.md decisions 3-5.
sync_card’s
content box (box_x/box_y/box_width/box_height) is now exactly the
mirrored content’s own aspect-fit rect within the card slot, with no
inset margin. CARD_PLATE_PAD is removed; CARD_PLATE_RADIUS is
renamed CARD_CORNER_RADIUS (26.0, unchanged value) since it is no
longer plate-specific.card_corner_mask_scene (nix/card-shell/render.c/render.h):
one small (size×size) cached Cairo rasterization per corner
orientation, opaque in the deck’s backdrop colour outside a quarter-circle
arc curving toward the card’s centre, fully transparent inside it.card_corners_sync (nix/card-shell/adapter.c): for live
cards, builds/positions four of these patches on top of the mirrored
content (wlr_scene_node_place_above), rebuilding all four only when
this card’s own quantised (whole-pixel) radius or the canvas’s
representative colour (canvas_solid_color, factored out of
appearance_canvas_refresh so both share one definition of “the backdrop
colour”) changes. Non-live (private/unavailable) cards keep the existing
card_background/card_plate_scene plate, unchanged in kind, since they
have no live pixels to protect from a background.card_shown_large(c) (already
defined in this file) rather than the mode-wide entering flag, and stop
hiding the card’s rounding during the transition: only the card(s)
actually growing/shrinking between full screen and deck size get
CARD_CORNER_RADIUS * progress; every other card always uses the full
radius. This also fixes a latent gap in this change’s first pass, where
the interpolated radius was computed but fed to a plate unconditionally
hidden for the whole transition, so it was never actually visible.nix build .#card-shell in task C.1, not the standalone policy test
binary); no dedicated unit test targets card_corners_sync in isolation,
so this task’s proof is the successful build plus the headless-QEMU
capture in task D below, which shows rounded live-card corners with no
visible background/border, in both themes, across scroll/close/open.nix build .#card-shell --max-jobs 1 --cores 6 — succeeds,
producing /nix/store/j3idplp3kbmbp36cn7ik13z4q46yq0qy-k230-card-shell.nix build .#nixosConfigurations.k230-coherent-shell.config.system.build.toplevel --max-jobs 1 --cores 6 --no-link --print-out-paths — succeeds, producing
/nix/store/aklc0jcyiddgbg4h2b0dnnsdkns36wyv-nixos-system-nixos-26.11.20260919.20b1ddd.
Host build proof.tools/capture-webos-fan-switcher.py against this
branch’s built card-shell (unwrapped riscv64 Sway from nix-store -qR of
the task C.1 output path, a host-arch build of
nix/card-composition-probe-client, and a symlinkJoin of pkgs.foot,
pkgs.htop, nix/handheld-theme-icons for real icon resolution), both
themes, all five stages. Commit the result plus one copy of the prior
(pre-change) dark-01-overview.png for direct comparison under
docs/evidence/card-shell/android-sized-cards/, with matching
docs/blob-inventory.md MANIFEST rows. Re-run again after the slice B
revision and replace the after-* files with the plate-free capture.python3 tools/blob-scan.py — exits 0.docs/evidence/card-shell/android-sized-cards/README.md.
Headless-QEMU proof (real cross-built compositor code, real IPC, real
synthetic touch) — explicitly not board/panel/real-finger proof, per that
README’s own “what this does not show” section.docs/evidence/card-shell/android-sized-cards/ alongside this change’s
existing headless-QEMU evidence, distinguishing the evidence class per
AGENTS.md. Operator command, once a board/serial reservation is held:
flash this branch’s system closure, then python3 tools/card-shell-board-session.py (or the equivalent board capture tool
already used for docs/evidence/card-shell/webos-fan-switcher/’s own
board-facing companions) against /dev/ttyACM0.
Operator real-finger report, 2026-09-27: “the rounded cards seem fine”
(docs/evidence/operator-reports/2026-09-27-shell-acceptance.md).
Evidence class: operator report, no camera recording.Narrow command for this whole change, once E.1 lands:
openspec validate the-overview-shows-large-rounded-cards --strict.
F.1 Replace backdrop-colored overlays with rounded destination
clipping in pinned wlroots/Pixman. Preserve the RGB565 cache and apply
one card-space shape to all mirrors, including cropped neighbors and
subsurfaces. Verify premultiplied alpha, transforms, partial descendants,
changing radii, damaged regions and RGB565 output against an independent
full-mask pixel oracle: python3 tests/test_card_rounded_clip.py (288
comparisons, host only). Existing policy/cache tests remain required.
F.2 Cross-build nix build .#card-shell --max-jobs 1 --cores 4 --no-link --print-out-paths; capture the actual compositor over a
patterned wallpaper under headless QEMU, checking corner pixels against
an unobscured wallpaper baseline. Record source/artifacts/limits under
docs/evidence/card-shell/transparent-corners/. This is QEMU proof only;
final package 7pjmarasi…, source 4b33dda9, all three positive fixtures
passed and the master negative control failed at the first corner.
F.3 On the reserved board, install the matching system, capture a
native screenshot with wallpaper and live cards, and verify that the
wallpaper shows through rounded corners. Keep E.1’s real-finger motion
acceptance separate. Operator: python3 tools/console.py /dev/ttyACM0 --wait=3 'runuser -u shell -- env XDG_RUNTIME_DIR=/run/shell /run/current-system/sw/bin/grim /run/shell/rounded-cards.png' after
coordinated activation (set the session’s actual WAYLAND_DISPLAY if needed);
record exact installed paths and the capture command with the evidence.
Physical installation proof: docs/evidence/card-shell/transparent-corners/installed-system/README.md.
The normal boot resolves to 11y992kp…; all shell services are active and
the native screenshot shows wallpaper through selected and neighboring
card corners. Exact installed paths and image hash are committed. This
closes F.3 only; E.1’s real-finger motion acceptance remains open.
The card overview (CS_DECK) SHALL render its focused card at approximately
80% of the panel’s width and 80% of its height, matching the panel’s own
aspect ratio, with each neighbouring card’s own edge visible only as a thin
sliver (not a wide multi-card fan). A live card’s content SHALL fill the
entire card slot with no visible background, border, or plate behind it —
the card IS the app content, scaled — and its four corners SHALL read as
visibly rounded. The existing webOS-fan gesture behavior — a horizontal
flick that can carry the selection past more than one adjacent card via a
velocity-projected momentum coast, an upward throw past a configured
distance/speed that requests a close, and a tap that expands the selected
card to full screen — SHALL be unchanged by this sizing; only the geometry
the same gesture formulas operate on changes.
While a card is entering the deck from a full-screen app, or expanding from the deck to full screen, its corner radius SHALL interpolate continuously between 0 (full screen) and its settled deck-card radius, so the transition does not pop between square and rounded corners; cards not themselves undergoing that size change SHALL keep their full, constant radius throughout.
Grounding: nix/card-shell-policy/card-shell-policy.c’s cs_default_config
(card_width=.8*width, card_height=.8*height) and nix/card-shell/adapter.c’s
matching runtime recompute. The original corner-overlay evidence below
predates the transparent-corner correction. Current implementation uses
wlr_scene_buffer_set_rounded_clip and nix/card-shell/rounded-clip.h in
the pinned Pixman compositor; tests/card_rounded_clip.c independently
compares its pixels over a patterned backdrop.
docs/evidence/card-shell/transparent-corners/README.md records matching
headless-QEMU wallpaper checks with cached, direct and ARGB/child paths,
plus a failing pre-fix control. The correction’s board
wallpaper result remains UNVERIFIED until task F.3. Non-live
(private/unavailable) cards keep the pre-existing card_background plate,
since they have no live pixels to protect from a background.
tests/card_shell_policy_driver.c’s overview_geometry case asserts the
75-85% width/height band, a ≤15%-of-card-width neighbour peek, and a fully
off-screen third card; 36/36 cases in tests/test_card_shell_state.py pass.
docs/evidence/card-shell/android-sized-cards/README.md records a
headless-QEMU capture of the resulting overview, scroll, close, and open
sequence in both themes, compared directly against the prior 50%/60%
webOS-fan capture, confirming no visible background/border behind a live
card. Real-finger board acceptance of the gesture feel and the radius
transition’s smoothness is UNVERIFIED and tracked as this change’s open
board task.
Archived change · Archived
Snapshot 5836ef1d113d · 2026-10-17 08:22 UTC
Closed recordReview the archived record and cited scope
A person adjusting brightness today only has a discrete −/+ stepper,
reachable only from inside Settings, one navigation hop from the shade
they just pulled down. docs/design/shell-polish-review-2026-09.md
finding #8 (“Brightness is a stepper everywhere, not a slider”, Settings/
Shade, P2) recommends a drag slider instead, matching Android’s Quick
Settings shade, which puts a full-width brightness slider directly under
the tile grid on every pull (§5, “Brightness slider: none”). The same
review’s finding #1 (“Touch targets are 4.3mm physical (330.9ppi × 56px),
well under Material’s ~9mm”, Global, P1) applies directly to the stepper’s
existing −/+ glyphs, which are smaller still.
Live brightness itself already works on hardware
(docs/evidence/backlight/live-hs/README.md, source d76e126f): the
backend writes /sys/class/backlight/canaan-dsi-backlight/brightness
through tools/device_settings.py, invoked once per stepper tap by
ServiceRequest::Brightness (nix/rust-shell-client/src/service_data.rs).
That per-tap Python subprocess is fine for a stepper’s occasional discrete
steps; it is not fine for a slider’s ~20-30 writes/sec while a finger
drags, which would spawn a process per sample and pile up behind the
service worker’s single request queue.
−/+ glyphs and their
release-only tap classification in panel_intent) with a Material-3-
style slider: a full-width track, a thick active portion up to the
thumb, a round thumb, and a cheap vector sun glyph at each end. The
touch target is the whole row (110px), well past the review’s 56px
floor.nix/rust-shell-client/src/slider.rs, new) so the two never
visually drift apart. The shade’s existing drag-to-close gesture is
unaffected: the slider’s own touch band is excluded from the close-drag
candidacy zone (service_ui::shade_panel_close_zone), the same way the
scrollable notification list already is, so a horizontal drag on the
slider never starts a close drag and a drag anywhere else on the sheet
still closes it exactly as before.ServiceRequest::BrightnessLive) that writes the backlight sysfs
attribute directly from the shell process — no subprocess per write —
throttled to about 20-30 writes/sec while dragging, always followed by
one authoritative ServiceRequest::Brightness (the existing Python
path, with its real read-back and UI feedback) on release. Clamp every
value the slider itself can produce to a minimum of 3%, so the slider
can never drive the screen fully black.ServiceRequest::RefreshSettings) whenever Settings or the shade opens,
so an external change to brightness shows in either place.2026-09-26-the-panel-brightness-is-adjustable change and its
display/backlight requirements; this change only replaces the touch
model on top of the existing, already-working device.theme_ui.rs, theme_carousel.rs, theme_thumbnails.rs,
theme_catalog.rs, appearance.rs) — a separate, concurrent change
owns those files in the same crate./dev/ttyACM0.display/backlight: retires the “Settings brightness stepper drives
the real device” requirement (see its own Reason/Migration) and adds
four requirements in its place — the slider control itself, the
shade’s own slider without disturbing its close gesture, the throttled
direct-sysfs live-write path, and reflecting the real value on open.Userspace: the Rust shell client (nix/rust-shell-client) and the existing
tools/device_settings.py sysfs bridge. No kernel, device tree, or Nix
module change — the backlight device itself is unchanged from the archived
2026-09-26-the-panel-brightness-is-adjustable change.
src/slider.rs holds only pure math and drag state (value↔x mapping,
MIN_PERCENT clamping, the live-write throttle, and an armed Drag
struct) — no cairo, no service_data types. This mirrors
theme_carousel.rs’s own split: render.rs paints from the module’s
numbers (track_bounds, x_at_value), main.rs/service_ui.rs own
touch dispatch and the actual ServiceRequest calls. Both the Settings
row and the Shade header call the same paint_slider/slider::Drag, so
the two can never visually or behaviorally drift apart, and the module is
unit-testable with no display server.
Rejected: two independent slider implementations (one per surface). This is exactly the “stepper’s two separate hit-tested glyphs vs. one track” duplication the design review’s finding #8 flags as unnecessary cost, and would double the surface for the two to disagree.
The old stepper was hit-tested only at touch-up, inside panel_intent’s
release-only tap classification. A slider needs continuous value updates
during the drag itself, so the slider is instead armed at touch-down
whenever the touch lands in its band (service_ui::slider_band), exactly
like Carousel::down arms on its own carousel band. Once armed, it owns
the rest of that gesture unconditionally — horizontal or not — through
main.rs’s down/motion/up handlers, added as a new sibling branch
ahead of the existing route-specific branches (close drag, notification
swipe/scroll, wifi/theme picker dispatch) rather than edited into any of
them. slider_band also feeds shade_panel_close_zone’s existing
carve-out mechanism (the same one that already excludes the scrollable
notification list), so a touch that starts on the slider is never even a
close-drag candidate — the guarantee task 3’s “must not start a close
drag” needs. slider_band is gated on ControlState::Writable so an
unavailable brightness control never steals a gesture from whatever plain
text sits in its place instead.
Rejected: teaching panel_intent’s release-only classifier a drag state
of its own. That function is shared by every other Settings/Shade tap
(Wi-Fi, keyboard, power, dismiss-all, the close drag) and already carries
a large text describing why its zones must not overlap; adding live-drag
tracking to it would either slow down its other, still-discrete callers
or fork its logic in place, both worse than one new orthogonal component.
The stepper’s existing ServiceRequest::Brightness shells out to
k230-settings brightness <percent> (tools/device_settings.py) once per
tap — fine for occasional discrete steps, wrong for ~20-30 writes/sec: a
process spawn per sample would pile up behind the service worker’s single
blocking-subprocess queue. docs/evidence/backlight/live-hs/README.md
already established the shell user has group write via udev directly on
/sys/class/backlight/canaan-dsi-backlight/brightness, so the cheaper fix
is a new ServiceRequest::BrightnessLive(u8) that writes that file
directly from the existing service worker thread (a fs::write, no
subprocess) — mirroring tools/device_settings.py’s own backlight lookup
(exactly one device, a valid max_brightness) so the two paths compute
the same raw value. The live path never touches the Settings Control’s
read-back/UI-feedback machinery; the UI’s own optimistic local value
(ShellClient::apply_brightness_preview) is what the finger actually
sees, and release always follows with the ordinary, verified Brightness
request.
Rejected: a separate long-lived helper process (a second daemon) purely for brightness. The direct write is simpler, needs no new socket or process lifecycle, and the existing worker thread already isolates it from the Wayland/UI thread.
The Shade’s header (title, notification count, “Dismiss all”) already
occupies its first ~160px; the slider’s band (SHADE_SLIDER_TOP = 190.0,
56px tall) sits just below it, clear of the existing “Dismiss all” tap
zone (116.0..190.0). Everything below — the preview card,
NOTIFICATION_TOP and the whole notification list — shifts down by the
same 76px this makes room for; both are still defined as one shared
constant each (render.rs’s preview-card y, service_ui:: NOTIFICATION_TOP), so nothing downstream needed its own layout change.
nix/rust-shell-client/src/slider.rs: value↔x mapping
(value_at_x/x_at_value), clamp_percent (3% floor), the
~20-30/s live-write throttle (Drag::should_write), and the armed
Drag struct, with unit tests for the mapping, the clamp, and the
throttle. Proven: cargo test --lib (236 passed, 0 failed,
including slider::tests::*).paint_slider/paint_sun in render.rs for both the
Settings row and the Shade header, replacing the Settings −/+
stepper text. Proven: cargo test --lib (render’s own pixel-sampled
shade/preview tests updated and passing after the layout shift this
needed).main.rs::suppresses_action_message (suppresses only the success/
pending path of the authoritative Brightness commit specifically;
a genuine failure, e.g. a denied write, still surfaces normally;
every other request’s own message is unaffected) and a unit test
(route_tests::brightness_commit_suppresses_its_own_success_toast_ but_not_a_failure). Proven: cargo test --lib --bin k230-shell- rust (257 passed, run in the foreground) and cargo clippy --lib --bin k230-shell-rust ... report no new warning; the QEMU capture
in docs/evidence/brightness-slider/ was refreshed and no longer
shows the toast.service_ui::slider_band (gated on
ControlState::Writable) and fold it into
shade_panel_close_zone’s existing carve-out, alongside the
existing notification-list exclusion. Remove the old release-only
stepper hit-test from panel_intent. Unit tests cover both the
Settings row band and the Shade band, including the
gesture-disambiguation case (a touch that starts on the slider band
is excluded from close-drag candidacy regardless of direction; a
touch starting elsewhere still engages the close drag exactly as
before). Proven: cargo test --lib
(service_ui::tests::slider_band_owns_its_row_and_is_excluded_from_the_close_drag_candidacy
and the existing close-drag suite, all passing).main.rs’s
down/motion/up/cancel touch handlers, as a new sibling
branch ahead of the existing route-specific dispatch (never editing
the theme/wifi dispatch those already own). Gated arming to the
plain Settings capabilities page specifically (wifi_view.page == WifiPage::Closed && theme_view.page == ThemePage::Controls) after
noticing slider_band’s row-1 Y range can otherwise coincide with
a Wi-Fi or Theme sub-page’s own rows, since both still report
Route::Settings. Proven: cargo test --bin k230-shell-rust (19
passed) and cargo clippy --all-targets report no warning
attributable to these files.ServiceRequest::BrightnessLive(u8) and
service_data::write_backlight_live, writing the backlight sysfs
brightness attribute directly (mirroring
tools/device_settings.py’s own backlight lookup), and swallow its
reply in main.rs::service_reply (fire-and-forget; the release
that follows always sends the authoritative Brightness request).
Proven: cargo test --test service_data_module (11 passed,
including live_backlight_write_scales_percent_by_the_real_max_ brightness, live_backlight_write_rejects_out_of_range_percent_ and_missing_device, and
worker_rejects_an_out_of_range_live_brightness_write_without_ shelling_out).ShellClient::refresh_route
now also submits RefreshSettings when the Shade opens (previously
only RefreshNotifications), so an external brightness change
shows in either sheet. Proven: same test run as 3.1 (the existing
worker/reply fixtures cover RefreshSettings’s path unchanged).cargo test for nix/rust-shell-client (lib, the k230-shell- rust bin’s own tests, and the service_data_module/
appearance_module/background_decode_module integration tests) —
all pass. cargo clippy --all-targets reports no warning
attributable to this change’s files; a pre-existing
crate::runtime_trace unresolved-import failure in
tests/theme_catalog_module.rs (added by a prior, unrelated commit,
ad752b1d, to a file this change does not touch) blocks a single
combined cargo test/cargo clippy --all-targets invocation and is
not this change’s to fix — a separate, concurrent session owns the
theme picker files.nix build .#handheld-shell-rust --max-jobs 1 --cores 6. Run in
the foreground after the 1.3 toast-suppression fix. Proven: exit 0,
/nix/store/fqmys3pjlj2kv3hivxa1s8hg4da8mi78-k230-shell-rust-riscv64-unknown-linux-gnu-0.1.0.nix build .#nixosConfigurations.k230-coherent-shell.config.system.build.toplevel --max-jobs 1 --cores 6 --no-link --print-out-paths. Run in the
foreground after the 1.3 fix. Proven: exit 0,
/nix/store/pzp59g0fkkvbzhkpr5rr35il3jhc0hqg-nixos-system-nixos-26.11.20260919.20b1ddd.tests/rust_service_surface_qemu.py exists and already covers
this surface, so used its own cross-built handheld-shell-rust
(riscv64) and the card-shell-patched sway-unwrapped under
qemu-riscv64-static, driven the same way (Sway’s headless
card_shell test-touch fixture), to capture a finger-drag across
the Settings slider (mid-drag 54%, released 90%) and the Shade’s
own slider (opens synced at the fixture’s 45%, drags to 90%
without closing the shade). Screenshots and their blob-inventory
rows are committed under docs/evidence/brightness-slider/
(README.md there has the exact commands and store paths).
python3 tools/blob-scan.py exits 0. The existing harness’s own
--surface-flag route() helper could not reliably complete
inside the client’s hardcoded 500ms deadline on this heavily
loaded shared host (uptime showed 40+ load average across 32
cores); the capture instead wrote directly to the same Unix
socket that flag uses, reaching the identical RouteServer — see
the README for detail. tests/rust_service_surface_qemu.py itself
needed one small fix regardless of this capture: its own hardcoded
brightness expectation (a tap at a fixed x used to mean the old
stepper’s “+10% from 45”; the same x now means “jump to this
fraction of the track” under the slider) was updated from 55 to
95, the slider’s own value_at_x result at that x.6.1 Real-finger drag and tap-to-jump on the Settings slider, confirming the panel’s actual brightness follows the finger live and clamps at 3%, not 0%, at the low end. Not done in this worktree — AGENTS.md and this task’s own instructions keep board access and real-finger acceptance out of scope here.
6.2 Real-finger drag on the Shade’s slider, confirming the shade does not begin closing on a horizontal drag there, and that a drag starting elsewhere on the sheet still closes it. Not done in this worktree.
6.3 Confirm on hardware that opening Settings or the Shade after an external brightness change (e.g. the other sheet’s own drag) shows the real current value, not a stale one. Not done in this worktree.
Operator physical acceptance, 2026-09-28 (“confirming physical acceptance of
the-brightness-control-is-a-slider”), covering 6.1-6.3:
docs/evidence/operator-reports/2026-09-27-shell-acceptance.md.
Reason: Replaced by a full-width Material-3-style slider, shared by
Settings and the shade, per docs/design/shell-polish-review-2026-09.md
finding #8 (“Brightness is a stepper everywhere, not a slider”) and
finding #1 (existing touch targets too small at 56px). The stepper’s
discrete −/+ release-only tap classification is removed from
panel_intent entirely; a touch on that row is now armed and tracked
continuously as a drag instead.
Migration: See “The brightness control is a slider, not a stepper”
below, which the Settings screen now satisfies in its place. No sysfs or
device-side change: the same /sys/class/backlight/*/brightness path and
tools/device_settings.py backend still apply the committed value.
Host build proof: cargo test and cargo clippy --all-targets pass for
nix/rust-shell-client (value↔x mapping, clamping, the live-write
throttle and gesture disambiguation are covered by unit tests in
src/slider.rs and src/service_ui.rs); nix build .#handheld-shell-rust
and the full k230-coherent-shell system closure cross-build. These are
host/build proofs only — see the open real-finger task below for physical
acceptance.
The Settings screen and the pull-down shade SHALL each present the same
brightness control as a full-width Material-3-style slider (a track with
a thick active portion up to the thumb, a round thumb, and a sun glyph at
each end), replacing the previous discrete −/+ stepper. Touch-drag
anywhere on the track SHALL set the value live while dragging; releasing
anywhere on the track SHALL commit that value through
/sys/class/backlight/*/brightness via the existing
tools/device_settings.py path (ServiceRequest::Brightness), exactly as
the stepper’s taps did. The touch target SHALL be at least 56 physical
pixels tall, per docs/design/shell-polish-review-2026-09.md finding #1
(4.3mm/56px touch targets, well under Material’s ~9mm guidance).
A drag SHALL never set brightness below 3%, so the slider itself can never drive the panel fully black; a value read from sysfs (an external change) SHALL be shown as-is, not raised to this floor.
Grounding: nix/rust-shell-client/src/render.rs’s Settings row loop and
Shade paint arm both call one shared paint_slider (new
src/slider.rs); service_ui::slider_band gates both the Settings row
and the Shade’s own header band on the same
ControlState::Writable check tools/device_settings.py’s
Settings.brightness() already reports.
Host build proof: same cargo test/clippy/nix build evidence as the
sibling requirement above; service_ui.rs unit tests exercise
shade_panel_close_zone’s exclusion of the slider band directly. Real-
finger acceptance on the board is a separate, currently open task (see
tasks.md); this requirement’s behavioral claim is unverified on
hardware pending that pass.
The pull-down shade (quick settings) SHALL show the same brightness
slider component at the top of its own header, above the notification
list, matching Android’s Quick Settings placement
(docs/design/shell-polish-review-2026-09.md §5, “Android’s Quick
Settings shade puts a full-width brightness slider directly under the
clock/tile grid on every pull”). A horizontal drag that starts on the
slider’s own band SHALL NOT be promoted into the shade’s drag-to-close
gesture; a drag that starts anywhere else on the sheet (the header above
it, the backdrop below it, or the notification list once scrolled to its
end) SHALL still close the shade exactly as it did before this change.
Grounding: service_ui::shade_panel_close_zone excludes
service_ui::slider_band’s own Y range from close-drag candidacy the
same way it already excludes the scrollable notification list; both
exclusions are sampled once at touch-down
(ShellClient::panel_close_candidate) and never re-evaluated mid-gesture,
so a touch already owned by one can never be reinterpreted as the other
partway through.
Host build proof: nix/rust-shell-client/tests/service_data_module.rs
covers write_backlight_live (percent-to-raw scaling against a fixture
sysfs tree, out-of-range rejection, a missing device) and confirms
ServiceRequest::BrightnessLive never shells out to
tools/device_settings.py. src/slider.rs’s own unit tests cover the
~20-30/s throttle gate and that release always reads the true value
regardless of it.
While a brightness slider drag is in progress, the system SHALL send
backlight writes at roughly 20-30 per second, each writing the backlight
sysfs brightness attribute directly from the shell’s existing service
worker thread (no subprocess spawned per write), so the Wayland/UI thread
is never blocked waiting on one. The drag’s release SHALL always send one
additional, authoritative write through the existing
tools/device_settings.py path (ServiceRequest::Brightness) regardless
of the live-write throttle’s own timing, so the committed value is always
the real, read-back-verified one.
Grounding: nix/rust-shell-client/src/service_data.rs’s
write_backlight_live mirrors tools/device_settings.py’s
Settings.backlight() lookup (exactly one
/sys/class/backlight/* device, a valid max_brightness) but calls
fs::write directly instead of spawning k230-settings; the existing
stepper’s ServiceRequest::Brightness already proved that per-request
subprocess path works but was only ever exercised at stepper-tap
frequency, never at drag frequency.
Host build proof: same evidence as above; ShellClient::refresh_route’s
change (Shade now also submits ServiceRequest::RefreshSettings) is
covered by the existing worker/reply test fixtures.
Opening Settings or the shade SHALL read the panel’s actual current brightness from sysfs and show it, so a brightness changed from the other sheet, or by anything else writing to the backlight device, is reflected rather than stale.
Grounding: ServiceRequest::RefreshSettings already reads
/sys/class/backlight/*/actual_brightness via
tools/device_settings.py’s Settings.brightness(); the Shade route
previously issued only ServiceRequest::RefreshNotifications on open
(ShellClient::refresh_route), so it never picked this up until this
change added the second request there.
Archived change · Archived
Snapshot 5836ef1d113d · 2026-10-17 08:22 UTC
Closed recordReview the archived record and cited scope
The handheld cannot pair with a Bluetooth accessory today. Not because the
hardware is unreachable — Bluetooth here is a generic USB dongle over
already-working USB host, mainline drivers/bluetooth/btusb.c is already
present in our pinned kernel source tree — but because nobody has ever
turned on a single Kconfig symbol.
docs/research/board-capability-inventory.md ranks this rank 4 by
value/effort (“Present-but-not-enabled. Effort S … pure Kconfig + a NixOS
package addition, no DT, no patch, risk low. Genuinely one of the cheapest,
highest-value gaps in this document”).
CONFIG_BT) and the USB HCI driver
(CONFIG_BT_HCIBTUSB), plus the Realtek protocol support LILYGO’s own
BSP enables for the CSR8510-clone dongle their kit ships
(0a12:0001, CONFIG_BT_HCIBTUSB_RTL).hardware.bluetooth.enable, the standard
NixOS module for it.bluetoothctl show and btmgmt info in the combined board test
plan, plus lsusb to confirm the dongle enumerates and is powered.radio/bluetooth: the taxonomy’s radio/ group already holds wifi
and lora; Bluetooth is a third radio and gets its own capability rather
than overloading radio/wifi (a different radio, different bus — a USB
accessory, not on-board SDIO/SPI silicon — and a different kernel
subsystem entirely).None.
The kernel (nix/kernel.nix — Kconfig only, kept in its own clearly
delimited hunk since feat/speaker is concurrently editing this same file
for audio; no device-tree change at all, matching the inventory’s
“no DT, no patch” finding) and NixOS (hardware.bluetooth.enable, in
nix/k230.nix). No Rust shell changes beyond an optional cheap status row;
if that turns out not to be cheap, this change documents it as explicit
follow-up rather than silently dropping it. The dongle sits on USB host,
whose power switching this project has already validated
(docs/uboot-usb-host*, docs/evidence/usb-host-validation.md); this
change does not touch USB host configuration itself, only whether the
kernel can drive a Bluetooth device once one is plugged in and powered.
Pairing, scanning and bluetoothctl/btmgmt output against a real dongle
are hardware-only gates — QEMU’s k230 machine models no USB host
controller at all, so this whole change’s functional proof is
hardware-only, same as backlight.
See proposal.md. Grounding, read directly from the pinned tree’s own
unpacked source
(/nix/store/bjgv1xn5b66gbz2kxv2aqzr1szp7dk7c-linux-xuantie-k230-src at
the time of writing):
net/bluetooth/Kconfig’s menuconfig BT is tristate, depends only on
!S390 and RFKILL || !RFKILL (always satisfied) — nothing about this
SoC blocks it.drivers/bluetooth/Kconfig’s BT_HCIBTUSB depends on USB (already
enabled: CONFIG_USB_DWC2=y, CONFIG_USB_DWC2_DUAL_ROLE=y in our pinned
k230_defconfig) and select BT_INTEL. BT_HCIBTUSB_RTL is bool "Realtek protocol support" ... default y once BT_HCIBTUSB is on —
matching the inventory’s citation of LILYGO’s own
CONFIG_BT=m CONFIG_BT_HCIBTUSB=m CONFIG_BT_HCIBTUSB_RTL=y and their two
quirk patches (0056, 0057-bluetooth-btusb-*.patch) for the specific
CSR8510-clone dongle (0a12:0001) their kit bundles.status = "okay" in nix/dts/k230-tdisplay.dts.nix/kernel.nix’s structuredExtraConfig sets no CONFIG_BT* symbol at
all today (checked directly against the current file) — this is the one
and only kernel gap.Goals: hci0 (or equivalent) appears once a Bluetooth USB dongle is
plugged into USB host and powered; bluetoothctl show and btmgmt info
report a controller; BlueZ is present and its service starts; scanning
finds nearby devices.
Non-Goals: pairing UI in the shell beyond an optional cheap status row;
audio profiles (A2DP/HSP — out of scope, and would additionally interact
with feat/speaker’s in-flight audio routing, which this change does not
touch); BLE peripheral/central application code; the on-board nRF52840
base’s own BLE stack (a separate MCU with its own firmware, out of scope
per the inventory’s UART-only Linux-side treatment of that accessory).
CONFIG_BT, CONFIG_BT_HCIBTUSB as modules (module, matching this
kernel’s general preference for loadable Bluetooth so it is absent from
a board with no dongle attached) and CONFIG_BT_HCIBTUSB_RTL as yes
(it is a plain bool once BT_HCIBTUSB is set, and matches the
inventory’s specific citation for the bundled test dongle). Rejected:
porting LILYGO’s two btusb quirk patches (0056/0057) speculatively
— those exist to paper over one specific dongle’s HCI_QUIRK_RESET_ON_CLOSE
behavior; whether our dongle needs them is a board observation this
change’s task group makes, not an assumption to patch in before ever
testing the base upstream driver.hardware.bluetooth.enable = true, the standard NixOS module,
rather than hand-rolling a bluez package addition and systemd unit.
This is the same “add a real, boring, unadapted upstream mechanism”
choice radio/wifi and system/nixos-config already make elsewhere
(environment.systemPackages additions require a recorded reason; this
module is the recorded, standard reason for BlueZ specifically).SettingsSnapshot/Control plumbing
(nix/rust-shell-client/src/service_data.rs) is a fixed struct with
four named fields (network, brightness, keyboard, motion), each
threaded through tools/device_settings.py’s status(),
service_ui.rs’s touch-routing tests and render.rs’s row layout —
adding a fifth field touches all three call sites and their existing
test literals (grep -n "brightness:" nix/rust-shell-client/src/*.rs
shows nine occurrences across three files just for one existing
control). That is not “cheap” by any reasonable reading, and the
working agreement is explicit that scope creep here is expensive
because one change can reach from a device tree to a running app.
Rejected: adding a bare read-only row anyway — a half-integrated status
row (no pairing action, no device list) would create exactly the kind
of “the-panel-brightness-is-adjustable”-style follow-up debt this
inventory already tracks explicitly, better tracked as its own named
follow-up than folded silently into a Kconfig change.bluetoothctl show, bluetoothctl scan on,
btmgmt info and lsusb, run from the console, not a shell UI
interaction. This matches the “no DT, no patch” scope: the claim being
proved is “the kernel and BlueZ can drive a real dongle,” not “the shell
has Bluetooth UI.”lsusb but never reaches RUNNING in
btmgmt info is the failure signature); porting 0056/0057 becomes a
follow-up change if and only if that is observed, not assumed here.lsusb showing the device at all is the fast, cheap way to separate
“no power” from “power but no Bluetooth stack,” and this project’s
existing USB host validation (docs/uboot-usb-host*,
docs/evidence/usb-host-validation.md) already establishes host mode and
UMS work on this exact port.Enable the Kconfig symbols and hardware.bluetooth.enable; cross-build the
kernel and the full system closure. Install the built kernel to /boot
and reboot (a kernel config change, not just activation). Physical
acceptance is: plug in the dongle, confirm lsusb, run
bluetoothctl show/scan on/btmgmt info from the console. Rollback is
reverting this commit; no device-tree or userspace behavior outside
Bluetooth is touched.
BT = module;, BT_HCIBTUSB = module;,
BT_HCIBTUSB_RTL = yes; to nix/kernel.nix’s
structuredExtraConfig, in a clearly delimited, separately commented
block (no shared lines with feat/speaker’s audio Kconfig edits, so
the two merge cleanly). Proven:
nix build .#kernel --max-jobs 1 --cores 6 --no-link --print-out-paths
exited 0, producing
/nix/store/78cdif47ayqwv67m7crjpawfzy2mx3af-linux-riscv64-unknown-linux-gnu-6.6.36-xuantie
(build proof only) — one kernel derivation shared with
the-panel-brightness-is-adjustable’s driver change.hardware.bluetooth.enable = true; in nix/hardware.nix
(the real-hardware-only base; nix/k230.nix is the shared
hardware+QEMU base). Proven:
nix build .#nixosConfigurations.k230-coherent-shell.config.system.build.toplevel --max-jobs 1 --cores 6 --no-link --print-out-paths
exited 0, producing
/nix/store/152qrxpkagai2fahgyhkxq7sp8sk98n4-nixos-system-nixos-26.11.20260919.20b1ddd,
which schedules unit-bluetooth.service, unit-obex.service and a
dbus-broker unit (build proof only).bluetoothctl show, bluetoothctl scan on (10 s),
btmgmt info and lsusb to the combined board test plan
(docs/evidence/backlight-bluetooth-rtc-board-test-plan.md), with
expected output and failure signatures for: no dongle detected, no
Bluetooth controller node, and a dongle visible in lsusb but never
reaching RUNNING/powered state in btmgmt info (the LILYGO-quirk
failure mode named in design.md). 4.1 MOVED, NOT PERFORMED HERE: install the built kernel to /boot and reboot. Under the
reserved board lock, plug in the USB Bluetooth dongle, confirm
lsusb shows it, then run bluetoothctl show, bluetoothctl scan on for 10 s, and btmgmt info. Commit sanitized console output
(no MAC addresses/SSIDs of nearby devices) under
docs/evidence/bluetooth/ (hardware proof only).
Scope split authorized by the operator on 2026-09-28: this board has
no onboard Bluetooth (docs/research/bluetooth-onboard.md), and no USB
dongle is available. The dongle test is preserved verbatim in the
successor change the-handheld-pairs-over-a-usb-bluetooth-dongle
(tasks 1.1-1.3 and 2.1). No Bluetooth pairing has been verified.
2026-09-28 system/hw closeout audit: this project does not currently
own a USB Bluetooth dongle (`docs/research/bluetooth-onboard.md`
confirms the board has no on-board Bluetooth radio of any kind, so a
dongle is the only path). Everything else in this change is build-
proven and complete. A successor change,
`openspec/changes/the-handheld-pairs-over-a-usb-bluetooth-dongle/`,
has been drafted and validates `--strict`, carrying this exact task
and the `radio/bluetooth` requirement it grounds, so this change can
archive its finished kernel/BlueZ scope once a coordinator authorizes
the split. Not yet authorized; this task and this change stay open
until then.
The system SHALL build the Bluetooth core (CONFIG_BT) and the USB HCI
driver (CONFIG_BT_HCIBTUSB) into the kernel, with Realtek protocol
support (CONFIG_BT_HCIBTUSB_RTL) for the CSR8510-clone dongle
(0a12:0001) this project’s accessory kit bundles, and SHALL run BlueZ via
hardware.bluetooth.enable. No device-tree change is required.
Grounding: net/bluetooth/Kconfig and drivers/bluetooth/Kconfig in the
pinned Xuantie kernel tree already carry BT, BT_HCIBTUSB and
BT_HCIBTUSB_RTL with no K230-specific blocker; nix/kernel.nix’s
structuredExtraConfig sets no CONFIG_BT* symbol today. Both DWC2 USB
controllers are already status = "okay" in nix/dts/k230-tdisplay.dts;
USB Bluetooth binds on the USB bus, not a device-tree node.
lsusb shows the device and bluetoothctl show reports a
controllerbluetoothctl scan on with a controller presentbtmgmt info is checkedbtmgmt info with the dongle attachedBluetooth SHALL work from the console (bluetoothctl, btmgmt) in this
change. A Settings status row is explicit, named follow-up work, not a
silent gap — this requirement exists so that gap is tracked rather than
assumed away.
Grounding: design.md decision 3 — adding a fifth SettingsSnapshot field
touches tools/device_settings.py, service_ui.rs’s touch-routing tests
and render.rs’s row layout at nine existing call sites for one control
alone; not “cheap” by this change’s own bar.
Archived change · Archived
Snapshot 5836ef1d113d · 2026-10-17 08:22 UTC
Closed recordReview the archived record and cited scope
Superseded in part by
the-card-shell-has-no-video-special-case: per the user’s own principle (“there should not be any special-case shit for video … it should just show the window because it’s a compositor”), task 2.1’scard_shell_video_stop/SWAY_K230_CARD_VIDEO_STOPclose hook and task 3.1’s video-only frozen-thumbnail path are both removed and replaced by generic mechanisms that apply to every card. This history is left as-is; see the newer change for what actually ships now.
A person cannot close network video today. k230-video-software and
k230-video-mvx (mpv, launched by nix/video-session.py) were deliberately
excluded from card_shell ordinary alongside real transient/popup views
(nix/card-shell/adapter.c’s now-removed “video and transient views stay
unmarked” check), so a playing video stayed a small 480x270/568x320 floating
window: no card, not in the overview, not reachable by the bottom-edge
switch gesture, and with no other close control in this touch-only shell. A
user who ends up on the video entry (deliberately, or by an accidental tap
while navigating the drawer) has no way back except restarting the session.
Board evidence: a real session in which nobody deliberately tapped Video
still ended up with Big Buck Bunny playing and unclosable.
k230-video-software and k230-video-mvx the same ordinary-maximized
card treatment as every other coherent-shell application: full-panel,
present in the overview, reachable by the bottom-edge switch gesture, and
closable by the same swipe-up-to-close every other card uses. The
480x270/568x320 floating geometry is kept only for the plain (non-card-shell)
touch launcher, which has no deck to close a card from.video-session.py controller itself to stop (card_shell_video_stop,
SWAY_K230_CARD_VIDEO_STOP), not only the xdg_toplevel close request the
compositor already sends every other card. Without this, the controller
cannot distinguish “the user closed the card” from “the decoder died”, and
the MVX fallback path relaunches a fresh software player right after the
card is closed — the observed “unclosable video” is xdg_toplevel close
alone not being enough, not a missing gesture.struct card.video_view, card_shown_large),
matching every other card’s static-while-small treatment instead of paying
continuous decode-to-thumbnail rescale cost for motion nobody can see in
the deck. The thumbnail still updates live whenever the card is actually
shown large (focused full-screen, mid-entry, or expanded).None. runtime/card-shell is being defined by the sibling, still-open
the-shell-manages-apps-as-cards change, so it does not exist under
openspec/specs/ yet; this change ADDs one further requirement to the same
capability rather than MODIFYing text that is not archived. Whichever change
archives first creates openspec/specs/runtime/card-shell/spec.md; the
other’s later archive adds to it. Neither change depends on the other’s
archive order for its own requirement to stand.
None.
nix/card-shell/adapter.c, nix/card-shell/route.c/route.h: card
eligibility, the video-close helper call, and the frozen-thumbnail
optimization.nix/shell.nix: for_window rules (video is card_shell ordinary under
coherentShell; the old floating rule is kept only when card-shell is
off) and the new SWAY_K230_CARD_VIDEO_STOP environment variable.nix/video-session.py is unchanged: its existing stop subcommand and
k230-video-session stop process-group teardown already do what the new
helper call needs.runtime/video’s existing board evidence.Video windows (k230-video-software, k230-video-mvx) were excluded from
card_shell ordinary and stayed small floating windows. The touch-only shell
had no control that could close them, and the MVX fallback path relaunched a
software player after an xdg_toplevel close.
Goals:
Non-Goals:
nix/video-session.py, the kernel, or the device tree.card_shell ordinary under coherentShell in
nix/shell.nix. Keep the old floating rule only when card-shell is off.stop
(SWAY_K230_CARD_VIDEO_STOP). The controller then cannot mistake a user
close for a decoder failure.k230-video-software/k230-video-mvx from card_shell
adapter.c’s ordinary command exclusion (video_app_id), keeping the
wants_floating exclusion for genuine transient/popup views; verify with
python3 tests/test_card_shell_state.py (unaffected: policy-layer only)
and a clean nix build .#card-shell --max-jobs 1 --cores 6.card_shell ordinary, floating enable, resize set 100 ppt 100 ppt, move position 0 0 for_window
treatment as every other coherent-shell app (nix/shell.nix), keeping the
old 480x270/568x320 floating rule only for the plain (non-coherent-shell)
touch launcher, which has no deck to close a card from; verify with
nix eval .#nixosConfigurations.k230.config.system.build.toplevel.drvPath.card_shell_video_stop() (nix/card-shell/route.c/route.h),
spawning $SWAY_K230_CARD_VIDEO_STOP stop (k230-video-session stop)
alongside the existing view_close() whenever a closed card’s
video_view is set; wire SWAY_K230_CARD_VIDEO_STOP in nix/shell.nix.
Verify with nix build .#card-shell --max-jobs 1 --cores 6 and the QEMU
regression in 4.1.struct card.video_view and card_shown_large()
(nix/card-shell/adapter.c); freeze scaled_mirror’s cached copy on its
most recently captured frame once a video card has one and is not shown
at full panel size, unconditionally re-checking size so a resize/entry
transition still snaps to correct geometry. Verify with nix build .#card-shell --max-jobs 1 --cores 6;
non-video cards take an unchanged code path (c->video_view false), so
every existing card-shell QEMU suite continues covering them.tests/test_card_shell_video_card.py proves, against real
cross-built Sway under qemu-riscv64-static with injected touch: a video
app_id reaches full ordinary-maximized card geometry; a real touch-first
vertical entry swipe from a focused video card is accepted into the
overview; the video card is a genuine, switchable deck member reachable
by previous/next (the persistent-button route a lateral release
resolves to); requesting its close sends the ordinary xdg_toplevel close
and invokes the video-stop helper exactly once; the other ordinary card
and the deck are unaffected. Verify with python3 -m unittest test_card_shell_video_card (run from tests/, 7/7 consecutive passes
observed). docs/evidence/card-shell/video-card/README.md records the
command and log excerpt. openspec validate video-windows-become-ordinary-cards --strict.Network video windows (k230-video-software, k230-video-mvx) SHALL receive
the same ordinary-maximized card treatment as any other coherent-shell
application: full panel size, present in the overview, reachable by the
bottom-edge switch gesture, and closable by the same swipe-up-to-close every
other card uses. A video window MUST NOT be a small floating window with no
card and no close affordance while the coherent card shell is active.
Closing a video card SHALL also stop the underlying player session (not only send the window’s own close request), so the session controller cannot mistake a requested close for a decode failure and relaunch a fallback player. Closing a video card MUST NOT leave an orphaned player process.
A video card’s deck-sized thumbnail MAY stop tracking every newly decoded frame while the card is not shown at full panel size, provided it still reflects a real captured frame of that session (not a placeholder) and resumes live updates whenever the card is shown at full panel size again (focused full-screen, mid-entry, or expanded).
Grounding: nix/card-shell/adapter.c’s prior “video and transient views
stay unmarked” exclusion and nix/shell.nix’s prior unconditional floating
for_window rules for both video app IDs (source read, not board evidence
of the fix). The unclosable-video board observation itself is recorded in
the coordinator’s session notes for this change; QEMU regressions proving
card membership, switch/close reachability and no orphaned process are
recorded under docs/evidence/card-shell/video-card/. Decoded-frame
presentation and physical touch remain runtime/video’s existing board
evidence and are not re-proven here.
Archived change · Archived
Snapshot 5836ef1d113d · 2026-10-17 08:22 UTC
Closed recordReview the archived record and cited scope
The archived editor capability blocks site publication because its evidence comments are not recognized as grounding citations.
None.
runtime/editor: correct the proof declaration for both existing requirements.Documentation only; no board access or image change. New behavior and new physical acceptance are non-goals.
The editor board proof was committed, but the spec used an unrecognized HTML comment. See proposal.md.
Make the existing grounding visible to the site. No changes to userspace, Nix or the installed system.
Use the established *Grounding: ...* format and cite the committed board result and normal-reboot record. Preserve every requirement and scenario. Do not widen the classifier to accept arbitrary verification comments.
Injected input is not real-finger acceptance; retain that explicit limit. The dashboard requires this design artifact even for a documentation correction.
openspec validate the-editor-cites-its-board-proof --strict and the site renderer classifier; host documentation proof only.The design document records this citation-only correction for the work dashboard; userspace and system behavior are unchanged. Existing board evidence remains the physical proof. Rejected alternative: weakening the site classifier would accept unsupported declarations.
Grounding: docs/evidence/omawrite/README.md, docs/evidence/omawrite/board/result.json and docs/evidence/omawrite/board/boot-result.json record the source build, physical-board injected input/native captures, and normal reboot. This is not new real-finger acceptance.
The system SHALL include source-built Omawrite and make the existing Editor entry open it with its application icon. Existing Editor Home pins SHALL remain valid. Plain-text and Markdown graphical file associations SHALL use that entry.
Grounding: docs/evidence/omawrite/README.md, docs/evidence/omawrite/board/result.json and docs/evidence/omawrite/board/boot-result.json record the source build, physical-board injected input/native captures, and normal reboot. This is not new real-finger acceptance.
Omawrite SHALL display its writing area and reachable Open/Save controls at the handheld’s portrait size, render without a GPU, accept keyboard input, and save and reopen local text without loss. It SHALL remain an ordinary window that can return through Overview and Home. Its palette SHALL follow the active Omarchy theme where the upstream application supports those palette fields.
Archived change · Archived
Snapshot 5836ef1d113d · 2026-10-17 08:22 UTC
Closed recordReview the archived record and cited scope
The handheld’s Editor currently opens Nano in a terminal. The user wants Omawrite as the writing/editing app accessible from Home and All apps.
Non-goals: replacing the Rust shell with Qt/Quickshell, claiming general Qt performance acceptance, GPU enablement, print setup, or removing the CLI recovery editor. No kernel, device-tree or bootloader change is intended.
runtime/editor: the image’s graphical editor opens Omawrite and supports
local text/Markdown editing on the handheld.None.
Nix package and shell desktop/MIME configuration, bounded portrait/dialog adaptations to pinned upstream source, focused launch/edit validation, and committed evidence. A reserved board is required for device acceptance; source/package preparation can proceed without it. The separate general Qt Quick/Quickshell evaluation proposal remains open.
Editor is k230-editor.desktop, currently a Nano launcher in nix/shell.nix.
Home pins store desktop-entry IDs. Upstream Omawrite is a Qt Quick/C++ app
with its own Open/Save buttons, Qt file dialogs and Omarchy palette reader.
The board currently uses a software Wayland compositor at 568x1232.
Make Omawrite a usable ordinary app in the existing shell and default graphical text/Markdown handler. Keep the CLI recovery editor available. This is not approval of Qt as the shell toolkit or completion of the general Qt proposal.
omacom/omawrite revision and source hash;
compile for RISC-V and retain MIT/OFL notices. No prebuilt x86 package.k230-editor.desktop for existing pins, label it Omawrite and use
the upstream icon. Set StartupWMClass to the app’s Wayland ID so Home can
focus it. Avoid a duplicate visible editor entry.Land the plan promptly, build/test the package, wire image defaults, then use the reserved board for a bounded application trial. Preserve user files; use a dedicated scratch document for edit/save/reopen proof. Select the new system persistently only after that proof, retaining the prior image for rollback.
nix build .#omawrite --cores 6 --no-link --print-out-paths and record the
exact output, architecture and closure size.python3 tests/omawrite_runtime.py --sway <sway> --omawrite <app> --output <dir>.
This is host/headless proof, not device or finger acceptance.
PASS: host evidence.nix build .#nixosConfigurations.k230-coherent-shell.config.system.build.toplevel --cores 6 --no-link --print-out-paths.
Inspect its installed desktop/MIME entries and retain Nano for CLI recovery.python3 tools/console.py /dev/ttyACM0 --wait=3 '<recorded trial command>'.
Commit the expanded command, native captures, backend identity, scratch-file
edit/save/reopen result, Open/Save dialog observations, keyboard show/hide,
and Overview/Home return. Distinguish injected input from real fingers.openspec validate the-editor-opens-omawrite --strict, and verify the matching
CI/Pages deployment and published evidence. Archive only if every named
requirement has its proof; preserve any unperformed evidence gate explicitly.Provides the handheld’s default graphical editor for local text and Markdown, accessible through existing Home pins and the installed-application drawer.
The system SHALL include source-built Omawrite and make the existing Editor entry open it with its application icon. Existing Editor Home pins SHALL remain valid. Plain-text and Markdown graphical file associations SHALL use that entry.
Omawrite SHALL display its writing area and reachable Open/Save controls at the handheld’s portrait size, render without a GPU, accept keyboard input, and save and reopen local text without loss. It SHALL remain an ordinary window that can return through Overview and Home. Its palette SHALL follow the active Omarchy theme where the upstream application supports those palette fields.
Archived change · Archived
Snapshot 5836ef1d113d · 2026-10-17 08:22 UTC
Closed recordReview the archived record and cited scope
The panel lights at one fixed brightness baked into panel-init-sequence
(15 05 02 51 fe — SET_DISPLAY_BRIGHTNESS 0xFE, in
nix/dts/k230-tdisplay.dts). There is no /sys/class/backlight device, so
nothing on the system — not tools/device_settings.py, not the Settings
brightness stepper already built into the Rust shell — can change it. A
person holding the handheld in a dark room or full sun has exactly one
brightness, forever.
docs/research/board-capability-inventory.md names this the single
cheapest, lowest-risk gap on the board (rank 2: “Adjustable screen
brightness … Low — DSI command writes only”) and cites LILYGO’s own fix,
already shipped in their BSP:
Xinyuan-LilyGO/T-Display-K230:k230_bsp patch
0049-drm-panel-canaan-universal-add-rm69a10-dsi-backlight.patch, which adds
canaan,dsi-command-backlight, default-brightness and max-brightness
device-tree properties plus a Linux backlight_device driven by
MIPI_DCS_SET_DISPLAY_BRIGHTNESS (0x51). The inventory also flags the
prerequisite this change must close: canaan_panel_prepare() in our pinned
panel-canaan-universal.c has every reset pulse commented out
(docs/dts-evidence.md), so a brightness value applied once would not
survive a later modeset or DPMS cycle without one.
panel-canaan-universal.c: register a
real /sys/class/backlight/<dev> device whose brightness attribute
writes MIPI_DCS_SET_DISPLAY_BRIGHTNESS (0x51), gated by
MIPI_DCS_WRITE_CONTROL_DISPLAY (0x53) to enable the brightness control
block. max_brightness reflects the DCS command’s 8-bit range; the
default brightness matches today’s fixed value (0xFE) so a fresh boot
looks identical to today until someone touches the control.lcd
panel node (canaan,dsi-command-backlight, default-brightness,
max-brightness) rather than a new node, so a board without the property
keeps today’s fixed-brightness behavior unchanged.ServiceRequest::Brightness, a stepper per the
design review, not a slider — out of scope to redesign here) already
calls k230-settings brightness <percent>, and tools/device_settings.py
already reads/writes /sys/class/backlight/*/brightness generically. The
only missing piece is write permission for the unprivileged shell user;
add a udev rule granting the shell group write access to the backlight
device’s brightness attribute.display/backlight: the taxonomy in .skills/k230-spec-change/SKILL.md
already names this capability; no spec file exists for it yet. This
change adds the first one.None. display/panel’s existing requirements (panel is device-tree-driven,
panel displays what the system draws) are unchanged; this change only adds
brightness control alongside them and fixes a defect
(canaan_panel_prepare()’s missing reset) already flagged against that
capability’s evidence, not a requirement rewrite.
The kernel (panel-canaan-universal.c, via nix/kernel.nix postPatch —
kept in its own clearly delimited hunk since feat/speaker is concurrently
editing this same file for audio Kconfig), the device tree
(nix/dts/display-rm69a10-568x1232.dtsi, not touched by feat/speaker),
NixOS (nix/k230.nix, a new udev rule), and the Rust shell (already wired;
one boundary test added). No new userspace package. Camera-observable
brightness change at 10/50/100% and persistence across a DPMS/modeset cycle
are hardware-only gates; a cross-build and the panel’s existing QEMU-proof
boundary (QEMU’s k230 machine models no display) do not touch the panel
at all, so this whole change’s functional proof is hardware-only.
See proposal.md. Grounding for this design, per .skills/k230-spec-change/SKILL.md’s
ordering:
/nix/store/bjgv1xn5b66gbz2kxv2aqzr1szp7dk7c-linux-xuantie-k230-src at
the time of writing — the same tree nix/kernel-src.nix pins):
drivers/gpu/drm/panel/panel-canaan-universal.c registers no backlight
device today; ctx->power_on (DT property backlight_gpio) is only an
enable gate (GPIO25, driven high once at probe and low at unprepare),
not a brightness control. MIPI_DCS_SET_DISPLAY_BRIGHTNESS = 0x51 and
MIPI_DCS_WRITE_CONTROL_DISPLAY = 0x53 are both already defined in the
pinned tree’s include/video/mipi_display.h. DRM_PANEL_CANAAN_UNIVERSAL
already depends on BACKLIGHT_CLASS_DEVICE, and
CONFIG_BACKLIGHT_CLASS_DEVICE=y is already set in
arch/riscv/configs/k230_defconfig — so no new Kconfig symbol is needed,
only the driver code and DT properties.drivers/gpu/drm/panel/panel-samsung-s6d7aa0.c
(s6d7aa0_bl_update_status/s6d7aa0_create_backlight,
lines 184–226) is the exact shape being adapted — a DSI-command backlight
registered with devm_backlight_device_register, driven by
mipi_dsi_dcs_set_display_brightness(). drivers/gpu/drm/drm_panel.c
(drm_panel_enable/drm_panel_disable) calls backlight_enable()/
backlight_disable() automatically whenever panel->backlight is set —
which is how this design gets DPMS-cycle persistence for free by
assigning ctx->panel.backlight instead of inventing a second code path.0049-drm-panel-canaan-universal-add-rm69a10-dsi-backlight.patch
(cited, not fetched — see the inventory’s provenance discussion of why a
LILYGO k230_bsp citation counts as tier-2 grounding here), independently
confirms the same three DT property names
(canaan,dsi-command-backlight, default-brightness, max-brightness)
and the same DCS command. This design’s C differs in structure (adapted
to this driver’s current shape, using the mainline
devm_backlight_device_register idiom above) but the DT contract and the
wire command match.Goals: a real /sys/class/backlight/<dev> with a correct
max_brightness; writing brightness changes what the panel shows;
brightness set once survives a later modeset or DPMS cycle; the existing
Settings stepper drives it end to end; the default at boot matches today’s
fixed value so a plain image looks unchanged.
Non-Goals: redesigning the stepper into a slider (explicitly deferred by the design review already on file); PWM or GPIO-based backlight dimming (this panel’s backlight gate is a hard on/off enable line, not a PWM — brightness is purely a DSI command to the panel controller itself); ambient-light auto-brightness; ramping/animation on brightness changes.
backlight_gpio) stays exactly what it is today — an enable gate driven
high at probe and prepare, low at unprepare. Brightness itself is a DCS write to the RM69A10
controller, which is what the fixed 0xFE in panel-init-sequence
already proves works. Rejected: adding a pwm-backlight node — nothing
on this board’s schematic wires the backlight gate to a PWM channel
(docs/dts-evidence.md; only GPIO25, plain on/off), and the inventory
found no PWM consumer for this panel at all.canaan,dsi-command-backlight is
present in the device tree, defaulting to disabled. This keeps a board
.dts that does not opt in — including, hypothetically, some other
canaan,universal panel this driver might later serve — on exactly
today’s fixed-brightness behavior. Our own display-rm69a10-568x1232.dtsi
sets the property, since this is the one and only panel this repository
drives.default-brightness defaults to 0xFE (254) and max-brightness to
255, matching the fixed value already baked into
panel-init-sequence and the DCS command’s 8-bit range. A fresh image
therefore reports ~100% and looks identical to before this change; the
first person to move the stepper is the first brightness change that
has ever happened on this board.ctx->panel.backlight, not a second manual reapply
path. Setting the panel’s backlight field makes drm_panel_enable()/
drm_panel_disable() — already called by canaan_dsi.c’s encoder
enable/disable path on every modeset — call backlight_enable()/
backlight_disable() automatically, which calls back into this driver’s
update_status with the last brightness core state (.brightness field
held on the backlight_device, independent of DRM). Because enable()
runs after prepare() (which re-runs the full DCS init sequence,
including the hardcoded 0xFE), the automatic post-enable
update_status call is what overwrites that fixed value back to
whatever was actually requested — this is the mechanism that closes the
inventory’s “must survive a modeset” gap, not a bespoke one. Rejected: a
hand-rolled reapply inside canaan_panel_prepare() itself, which would
duplicate logic drm_panel.c already provides and run before the panel
is confirmed enabled.update_status no-ops while the panel is not prepared. A
bool prepared field, set at the tail of prepare() and cleared at the
head of unprepare(), guards every DSI write from the backlight path.
Without it, a brightness write arriving while the panel is mid-reset (or
before the first modeset) would attempt a DSI transaction against a
controller not currently listening — exactly the class of hang this
kernel’s postPatch history (bounded PHY waits, bounded thermal loop) has
already had to fix elsewhere. Rejected: writing unconditionally and
trusting DSI transaction timeouts — this driver’s own DSI writes already
log -110 (ETIMEDOUT) in the unpowered-domain case recorded in
nix/kernel.nix; a guard is cheaper than another timeout.get_brightness is left unset (the backlight core then returns
bl->props.brightness directly) rather than issuing
mipi_dsi_dcs_get_display_brightness() (0x52). This DCS-read path is
new and unproven on this panel — only RDDID (0x04) and RDDPM (0x0A) have
been read back successfully so far (docs/evidence/panel-dark.md) — and
a shadow value the driver itself wrote is already authoritative for this
single-writer device. Rejected: trusting a fresh 0x52 read, which would
add an unverified DSI transaction to every cat brightness.tools/device_settings.py already runs as the unprivileged
shell user (spawned directly by the Rust shell client, no sudo) and
already implements the full sysfs read/write path generically
(Settings.backlight()/Settings.change_brightness() in
tools/device_settings.py, unchanged by this proposal) — the only gap is
that /sys/class/backlight/*/brightness is root-only by default. A
udev rule (SUBSYSTEM=="backlight", chgrp/chmod to the existing shell
group already defined in nix/shell.nix) is the narrowest fix. Rejected:
a new broker daemon (vglite-access/broker.py’s pattern) — that
machinery exists because a private GPU descriptor must go to exactly one
compositor MainPID under a security policy; a world-readable brightness
percentage on a single-user handheld has no comparable secret or
contention to broker.dev_err) rather than silently dropped, and the
cached class-device value is reapplied at the next real enable()
regardless — no user-visible action is lost, only deferred.0x24 WRITE_CONTROL_DISPLAY value (BCTRL|DD|BL) is a mainline
convention borrowed from other MIPI panels, not confirmed against this
exact controller’s application note] → this is exactly the class of
“measured, not assumed” risk docs/dts-evidence.md’s history warns about;
the physical board test at 10/50/100% is the actual gate, and if the
panel does not respond as expected the fallback is the existing fixed
0xFE behavior (this change is purely additive to the init sequence, not
a replacement of it).canaan_panel_prepare()
function already carrying several UNVERIFIED bring-up hypotheses in
nix/kernel.nix] → the reset block already exists in prepare() (see
nix/kernel.nix’s already-landed reset-pulse postPatch, applied for the
DSI-hang bring-up work); this change does not need to add it again, only
confirm it is present before adding backlight code after it, so the
panel is not mid-reset when the init sequence (and the brightness
override that follows it) runs.Add the backlight class device, DT properties and udev rule; no existing
behavior changes for a boot that does not touch the stepper. Cross-build
the kernel and the full system closure in the foreground. A board install
(/boot update, not just activation — this is a kernel and DT change) and
reboot are required before any board proof. Rollback is reverting this
commit; the fixed 0xFE brightness is the starting point either way.
The board’s negative brightness result remains authoritative. GPIO25 must
be raised in every non-handoff prepare(), symmetrically with the existing
unprepare() low drive. This follows LILYGO’s patch
0027-panel-canaan-universal-enable-reset-in-prepare.patch at upstream
revision bb831ab358b66f5bd9a87ecd7c580fee4537492e; our existing reset
sequence is retained. A successful DSI transfer returns a byte count, so
the backlight callback normalizes nonnegative results to zero.
Review also found the host dispatch routes DCS short-write-with-parameter through a helper that emits long-write type 0x39. The earlier single-byte panel change therefore did not correct the wire packet type. Follow the kernel’s standard packet constructor and bounded FIFO completion semantics. Review and test the runtime LP command configuration separately from the power gate. The inherited draft’s unconditional command/video mode toggling is rejected for now: it lacked FIFO drain, missed stage-1 handoff, and could race disable. A source hypothesis is not brightness proof.
Prove recovery on a reserved board with the known boot bundle retained: first boot the candidate once, then capture display off/on recovery and three brightness levels under fixed camera exposure. Check the shell’s unprivileged brightness path and restoration of a nondefault value after DPMS. Keep failure logs and distinguish native screenshots (geometry) from camera evidence (panel luminance). Only install the candidate persistently after its boot and recovery checks pass.
The earlier malformed-packet and active-video LP findings remain recorded
in docs/evidence/backlight/board-findings.md and runtime-recovery/README.md.
GPIO25 restoration and packet/FIFO fixes alone did not make live LP writes
visibly apply. The final narrow policy copies a validated message under the
host transfer mutex and clears USE_LPM only for a two-byte DCS 0x51 short
write while video is active. It retains initialization LP policy, ACK flags,
caller immutability and unrelated packet behavior, without cycling video,
PHY or panel power. Thirty-one host fixtures and the physical camera result
in docs/evidence/backlight/live-hs/README.md support this resolution.
struct backlight_device *bl, bool prepared,
u32 default_brightness, u32 max_brightness, bool dsi_command_backlight to struct canaan_panel; parse
canaan,dsi-command-backlight (bool), default-brightness and
max-brightness (u32, defaulting 254/255) in
canaan_panel_parse_dt(). Proven:
nix build .#kernel --max-jobs 1 --cores 6 --no-link --print-out-paths
exited 0, producing
/nix/store/78cdif47ayqwv67m7crjpawfzy2mx3af-linux-riscv64-unknown-linux-gnu-6.6.36-xuantie
(build proof only — DT parsing itself is exercised only once loaded
on hardware).canaan_panel_bl_update_status()/register the backlight
with devm_backlight_device_register() when
dsi_command_backlight is set, using MIPI_DCS_WRITE_CONTROL_DISPLAY
(0x53, value 0x24) then mipi_dsi_dcs_set_display_brightness()
(0x51); assign ctx->panel.backlight so drm_panel_enable/
drm_panel_disable drive it automatically across a modeset or DPMS
cycle. Guard every write on p->prepared. Same build proof as 1.1
(one kernel derivation).canaan_panel_prepare()
(already landed in nix/kernel.nix’s postPatch history) runs before
the init sequence on every prepare, so brightness code added in 1.2
never races an unreset panel. No new patch — a citation check against
the current nix/kernel.nix, recorded in design.md. This one is a
source-reading check, not a build, so it is genuinely done.canaan,dsi-command-backlight;, default-brightness = <254>;, max-brightness = <255>; to the lcd: panel@0 node in
nix/dts/display-rm69a10-568x1232.dtsi (not touched by
feat/speaker, so no merge risk with the concurrent audio DT work).
Proven: nix build .#deviceTree --max-jobs 1 --cores 6 --no-link --print-out-paths
exited 0, producing /nix/store/247k32c241fwhpzwx77ps3ldlrpcvds9-k230-tdisplay.dtb
(build proof only).services.udev.extraRules entry in nix/hardware.nix
(the real-hardware-only base; nix/k230.nix is the shared
hardware+QEMU base) granting the shell group write access to
/sys/class/backlight/*/brightness (chgrp/chmod on device add).
Proven: nix build .#nixosConfigurations.k230-coherent-shell.config.system.build.toplevel --max-jobs 1 --cores 6 --no-link --print-out-paths
exited 0, producing
/nix/store/152qrxpkagai2fahgyhkxq7sp8sk98n4-nixos-system-nixos-26.11.20260919.20b1ddd
(build proof only — no board to exercise the rule yet).nix/rust-shell-client/src/service_ui.rs
covering the brightness stepper’s 0% and 100% clamps (previously
untested because no real backend existed for the clamp to matter
against). Proven: cargo test --offline --manifest-path nix/rust-shell-client/Cargo.toml passes (196 tests, including the
new one). cargo clippy --offline --manifest-path nix/rust-shell-client/Cargo.toml --all-targets reports no warning
attributable to this change’s files; a pre-existing, unrelated
field_reassign_with_default lint in wifi_ui.rs (not touched by
this change) already fails a repo-wide -D warnings run and is not
this task’s to fix./boot and reboot (a kernel and
DT change, not just activation) — done, via the coordinator’s
export/import + bootfetch/bootswap procedure, confirmed by a real
cold reboot. ls /sys/class/backlight does show exactly one
device (canaan-dsi-backlight, max 255), and writes at 10/50/100%
read back as set with no dmesg errors — but camera evidence
(locked exposure) shows no visible or measurable panel change
across the full 0..255 range (mean luminance 200.99/201.14/201.33).
A real transport bug was found and fixed
(nix/kernel.nix’s board-finding hunk;
docs/evidence/backlight/board-findings.md), but the underlying
requirement — a person can see the panel change brightness — is
not yet met. Ticked because the task (install, reboot, confirm
the device, write and observe) was performed and is fully
evidenced, not because the result was a pass; the negative result
is the finding.926c7a61 now proves power recovery and distinct 26/128/255
levels after re-enable; see
docs/evidence/backlight/runtime-recovery/README.md. Live writes
still have no visible effect, so the core brightness requirement
and tasks 6.3/6.4 remain open. 6.1 Restore GPIO25 in panel prepare and normalize the backlight
callback’s success result. Proof: nix build .#kernel --max-jobs 1 --cores 4 --no-link --print-out-paths (cross-build only).
6.2 Correct DSI packet framing/completion and review runtime command delivery against the pinned driver and mainline DesignWare path. Run the focused transport fixtures and the same kernel build; preserve the stage-1 handoff and bounded failure paths.
6.3 Boot the candidate once, verify display off/on recovery by camera,
and demonstrate three distinct brightness levels with fixed camera
exposure. Record exact kernel/system identities and commands under
docs/evidence/backlight/. Sysfs readback alone does not pass.
Physical proof: docs/evidence/backlight/live-hs/README.md, source
d76e126f, live raw 26/128/255 and DPMS recovery at 128 with fixed
exposure; shell-user Settings commands also visibly apply.
6.4 Verify shell-user brightness controls and retention of a chosen nondefault brightness across DPMS. Install persistently only after the candidate checks, then repeat boot/service identity checks.
Candidate controls, camera levels and retention pass on source
`433a4226`; see `docs/evidence/backlight/combined-candidate/README.md`.
Corrected durable installation and a normal reboot now pass. Exact
boot hashes, profile, kernel and all three shell service identities
are committed alongside the camera proof. The failed shadow-copy
attempt and recovery remain documented; no full-card readback or
real-finger acceptance is claimed.
Tasks 6.1/6.2 host proof: docs/evidence/backlight/transport/build.json
(source 926c7a61, combined cross-build exit 0) and 25 transport fixtures
under ASan/UBSan. These checks do not complete 6.3/6.4.
Let a person adjust the physical panel brightness from Settings or the console, and retain the selected level across display power cycles.
The system SHALL register exactly one /sys/class/backlight/<dev> device
for the RM69A10 panel, with max_brightness reflecting the
MIPI_DCS_SET_DISPLAY_BRIGHTNESS command’s 8-bit range and
brightness writable by a process with permission on the device node.
Writing brightness SHALL send a single-byte MIPI_DCS_SET_DISPLAY_BRIGHTNESS
(0x51) command to the panel controller, matching the exact command shape
(MIPI_DSI_DCS_SHORT_WRITE_PARAM, cmd + one data byte) already proven
working in panel-init-sequence.
Grounding: drivers/gpu/drm/panel/panel-canaan-universal.c in the pinned
Xuantie kernel tree registers no backlight device by default —
ctx->power_on (DT property backlight_gpio, GPIO25) is an on/off enable
gate driven once at probe, not a brightness control. Confirmed on the
board: ls /sys/class/backlight shows exactly one device
(canaan-dsi-backlight, max_brightness=255), and writes at 10/50/100%
read back as set with no dmesg errors — see
docs/evidence/backlight/board-findings.md.
Physical follow-up: docs/evidence/backlight/live-hs/README.md records
source d76e126f sending brightness in HS during active video. Fixed-exposure
camera means for raw 26/128/255 are 26.69/91.56/172.36 without DPMS between
writes. The earlier negative findings are preserved as historical evidence.
ls /sys/class/backlight on the boardmax_brightness and
brightness filesmax_brightness to that
device’s brightness filePhysical proof: docs/evidence/backlight/live-hs/README.md demonstrates
power off/on recovery at requested raw 128: mean grayscale 92.12 before,
24.15 off, 91.50 on. GPIO25 is restored in prepare, before panel init.
A brightness value a person has set SHALL still apply after the panel is re-enabled by a later modeset or a DPMS-style off/on cycle. The system SHALL NOT silently revert to the fixed default brightness baked into the panel’s init sequence.
Grounding: the inventory’s flagged prerequisite —
canaan_panel_prepare()’s reset pulses were commented out by the vendor
(now fixed in nix/kernel.nix’s postPatch history), so prepare() fully
re-runs panel-init-sequence, including its fixed brightness DCS write, on
every real modeset. drivers/gpu/drm/drm_panel.c’s drm_panel_enable()/
drm_panel_disable() already call backlight_enable()/
backlight_disable() whenever struct drm_panel.backlight is set, and
canaan_dsi.c’s encoder enable/disable path already calls
drm_panel_enable()/drm_panel_disable() on every modeset — see design.md
decision 4.
The default brightness SHALL match the value already baked into
panel-init-sequence today, so a system with this change but with nobody
having used the Settings brightness control looks identical to a system
without it.
Grounding: panel-init-sequence’s existing fixed DCS write is
15 05 02 51 fe — 0xFE — in nix/dts/k230-tdisplay.dts.
Physical proof: docs/evidence/backlight/combined-candidate/README.md
records actual Settings stepper taps through a verified virtual touchscreen
on the board, changing raw brightness 255 → 230 → 255, plus camera-proven
Settings backend levels. This is injected board input, not real-finger
acceptance. The matching combined candidate is installed and normal-boot
identities are verified there.
The existing Settings brightness stepper (ServiceRequest::Brightness,
already implemented in the Rust shell as a stepper rather than a slider,
per the design review) SHALL change the panel’s actual brightness through
/sys/class/backlight/*/brightness, through the existing
tools/device_settings.py sysfs path, once the unprivileged shell user
holds write permission on that device.
Grounding: tools/device_settings.py’s Settings.backlight() and
Settings.change_brightness() already read/write
/sys/class/backlight/*/brightness generically and already report
writable/read-only/unavailable based on os.access() — this was
previously always unavailable because no backlight device existed at
all. nix/rust-shell-client/src/service_ui.rs’s stepper logic
(value.saturating_sub(10) / .saturating_add(10).min(100)) is already
implemented and tested.
/sys/class/backlight/*/brightness and the
panel’s brightness changes accordinglyArchived change · Archived
Snapshot 5836ef1d113d · 2026-10-17 08:22 UTC
Closed recordReview the archived record and cited scope
The work board hides screenshot evidence behind text links, so readers cannot see what a proposal has produced while scanning cards. Screenshots should accompany their change and provide a useful card cover without implying that a mockup or QEMU capture proves hardware behavior.
Non-goals: generating new shell evidence, recropping committed evidence, changing proposal acceptance, or adding a new photo-upload service. No physical board is needed.
None.
docs/spec-site: show proposal-related visual evidence on the work board and its inline detail view.Static work-board data extraction, Astro card/dialog rendering, reviewed status metadata and narrow site tests. No image, kernel, shell runtime or board change.
Clicking media in a card opens a viewport-sized gallery modal, preserving aspect ratio and card reading position, with swipe/keyboard navigation and video controls. Raw evidence links remain available separately.
Evidence files likewise open in an in-place document modal, preserving rendered Markdown, readable text, and a separate original-file download link.
Videos start when opened or selected in the gallery. Space plays/pauses the current video without closing the viewer; card previews stay paused.
Layer: static documentation site. The board already renders committed proposal documents inside a dialog and retains separate source/device states. Evidence is currently a flat set of links. Images and videos are committed under docs/, with binary inventory and evidence records.
Land this plan, implement extraction/rendering, verify committed fixtures and browser behavior, publish and inspect the exact deployed revision. A source revert restores text-only cards. No board or image deployment is involved.
python3 tests/test_work_board.py.2.1 Add image/video card covers, header evidence links and inline detail galleries while retaining one whole-card action, keyboard access and no autoplay.
2.2 Verify generated markup and site budgets with python3 scripts/build_site.py; inspect desktop/mobile card and dialog behavior in a browser, including direct evidence links and a video player. Record exact commands/results in docs/evidence/work-card-media/README.md.
2.3 Add a viewport-sized media modal/gallery with contain sizing, swipe/keyboard navigation, video controls, Escape/close and restoration of the underlying card position/focus. Verify with python3 tests/work_card_media_browser.py and python3 scripts/build_site.py; extend the committed evidence record.
2.4 Open evidence files in document modals with rendered Markdown or bounded text, original-file access, Escape/close and position/focus restoration. Verify header and inline file links on desktop/mobile with python3 tests/work_card_media_browser.py and python3 scripts/build_site.py.
2.5 Start videos when opened or selected in the viewer and make Space toggle play/pause without activating Close; verify desktop/mobile with python3 tests/work_card_media_browser.py.
openspec validate the-work-board-shows-visual-evidence --strict, land/push and inspect CI plus the exact revision published at the work board URL.Host website evidence: browser and published work-board checks.
The work board SHALL discover committed images and videos associated with a change’s cited evidence, show a representative visual cover when available, and present the discovered media inside that card’s detail view. Videos SHALL provide playback controls, start playback when opened or selected in the media viewer, and support Space to toggle play/pause without closing it. Card previews SHALL remain paused. Captions and evidence-class labels SHALL not imply physical validation from mockups or automated captures. Changes without visual evidence SHALL remain readable text cards.
Each work card with related evidence SHALL expose directly usable evidence links from its header area, including reports, logs, screenshots and videos. Those links SHALL identify their artifacts, refer to the published revision, and remain separately usable from the primary whole-card action. Discovery SHALL exclude uncommitted, missing, unsafe and unrelated paths.
Archived change · Archived
Snapshot 5836ef1d113d · 2026-10-17 08:22 UTC
Closed recordReview the archived record and cited scope
A person can boot into the handheld shell and reach working controls, but the experience is currently described as a collection of bring-up features rather than one dependable product journey. Existing evidence covers pieces such as the 568x1232 portrait shell, launcher/catalog, keyboard, splash handoff, window controls, and video playback; it does not yet give a single evidence ledger for first use, discovery, readability, touch reachability, state recovery, and accessibility. Without that plan, new card and gesture work can polish one surface while leaving inconsistent labels, focus, loading, and recovery behavior elsewhere.
This change creates an evidence-driven UX plan and an ordered backlog. It can be authored and checked on the host now; final readability, reachability, motion, and first-boot acceptance still require explicitly labelled board observations.
docs/handheld-ux-plan: An evidence-labelled, reviewable UX plan with user flows, heuristic findings, shared visual/interaction principles, measurable acceptance, and successor proposal boundaries.None. This change documents and plans cross-surface behavior; implementation changes will land through successor proposals.
The planning deliverable defines a concrete follow-up audit at docs/research/handheld-ux/ (flow matrix, issue ledger, evidence index, and visual comparison sheets) without adding those research assets in this proposal-only change. It references the Sway/Pixman shell, Foot, touch launcher and catalog, persistent bar, wvkbd, desktop entries, video session, splash evidence, and existing card proposals. Host analysis and deterministic fixture checks can proceed without the board. Board work is required for final first-use timing, real-finger gesture/reachability, optical readability, and any orientation claim. Palm webOS is used as an interaction benchmark for continuity, cards, and recovery, not as a claim that the current shell matches it.
The shell is a portrait Sway/Pixman session on a 568x1232 panel with Foot, a persistent touch bar, wvkbd, desktop-entry discovery, and native launcher/window controls. Repository evidence shows a visible shell handoff around recording timestamp 72.6–72.7 seconds in one camera audit (not a measured power-on duration), a 568x1232 Sway tree, injected Apps/overview matrices, keyboard show/hide and Home recovery, and installed video playback with injected Back/Stop/Home/EOF checks. Those artifacts also state their limits: injected input is not real-finger proof, native images are not optical readability proof, and orientation/latency/continuity claims require narrower evidence.
The existing touch-launcher-gestures-overview proposal owns gesture classification and metadata-card behavior. The active the-shell-has-a-card-composition-plan and the-shell-manages-apps-as-cards work own card architecture and app lifecycle respectively. This plan supplies the cross-surface contract and routes work to those owners rather than duplicating their implementation.
Goals:
Non-Goals:
Use one outside-in journey map. Start with boot feedback and the first successful app launch, then cover repeat navigation, keyboard-visible work, video/system states, and recovery. This exposes cross-surface inconsistencies that component specs miss. Evidence links point to docs/evidence/splash-initial-scene-ready/video-audit.md, docs/evidence/network-video/installed-app/README.md, docs/evidence/network-video/installed-controls/README.md, and the launcher/keyboard evidence reports.
Use an evidence ladder. Host source/tests establish structure and deterministic state behavior; native screenshots establish intended composition; injected board runs establish routing and cleanup; camera captures establish visible physical results; focused real-finger captures establish touch and reachability. A lower rung cannot substitute for a higher one. Missing rungs remain UNVERIFIED.
Define tokens before polishing cards. The successor visual-system work should record a small spacing scale, text roles, minimum contrast checks, focus/pressed/error treatments, and target geometry in panel pixels. It must test with the keyboard visible and hidden. This is a shared contract for the card-composition and app-card owners, not a second card renderer.
Preserve explicit navigation fallbacks. Every gesture route has a button/Back/Home path. The card owners decide gesture thresholds and overview state; the UX plan checks that Apps, Windows, Keyboard, System, Back, Home, and video Stop remain discoverable and composable. A card or overview surface must close or yield before focusing an application.
Treat transient states as first-class screens. Loading, empty, stale, launch failure, network failure, EOF, cancellation, and cleanup each need a visible status and a bounded recovery path. The network-video proposal owns player lifecycle; this plan owns whether the resulting state is understandable and returns to the shell.
Budget motion for Pixman. Existing feasibility evidence reports restrained scene-build/KMS timings and recommends solid cards, limited buffers, and short transitions. The card proposal owns implementation and performance measurements; this plan defines distinct budgets for release animations and continuous finger tracking, reduced-motion behavior, and a board camera check before calling motion usable; immediate settling cannot replace required direct manipulation.
Use Palm webOS as a comparison lens. Evaluate continuity of cards, reversible navigation, and visible state transitions against the benchmark, while retaining this shell’s Sway, layer-shell, keyboard, and persistent-bar constraints. Do not import webOS-specific assumptions about gestures, thumbnails, or compositor ownership.
UNVERIFIED markers and require board evidence for boot timing, optical readability, orientation, and real-finger behavior.The follow-up audit should include two low-cost, implementation-neutral sheets under docs/research/handheld-ux/: (1) a current-versus-recommended portrait shell frame showing the persistent bar, title/action hierarchy, card bounds, keyboard occlusion, and empty/error treatment; and (2) a navigation storyboard showing Apps → card/overview → selected app → Back/Home/Stop recovery. These are annotated wireframes or native-frame overlays, not claims that new pixels have shipped. Compare each recommendation against the current native capture and the 568x1232 geometry, then record contrast, target size, focus, and state-label changes. Keep thumbnails, blur, and GPU effects out of the baseline comparison unless a later owner proves their cost.
The audit may complete with evidence-labelled unknowns and proposed acceptance tests. It does not need to prove every future usability improvement before producing its plan. Existing physical keyboard and Home acceptance remains valid; inspect those reports before requesting another operator trial. Use new physical observation only for an unresolved finding that cannot be answered from existing artifacts. A missing observation remains unknown rather than becoming either a fabricated defect or a pass.
The resulting issue ledger must derive severity from observed user impact. Do not preassign onboarding, boot, or visual inconsistency as P0, or create duplicate successors for work already owned by an active change. A validator checks fields and links, not whether a design judgment is sound: a named coordinator review of the findings and visual comparisons is still required.
rg -n "UNVERIFIED|injected|physical|camera|native" docs/evidence to locate candidate sources, then inspect the cited artifacts and record the review in docs/research/handheld-ux/evidence-review.md; search matches alone are not proof.specs/docs/handheld-ux-plan/spec.md (host document review).docs/research/handheld-ux/flow-matrix.md, issue-ledger.md, and evidence-index.md with required fields for task, visible result, severity, owner, dependency, evidence class, citation path, and open gate; reconcile ownership with the-shell-has-a-card-composition-plan, the-shell-manages-apps-as-cards, touch-launcher-gestures-overview, and the-shell-plays-network-video. After implementing task 1.4, verify every citation path exists or is explicitly named UNVERIFIED with python3 tools/verify-ux-plan.py docs/research/handheld-ux/flow-matrix.md docs/research/handheld-ux/issue-ledger.md docs/research/handheld-ux/evidence-index.md (host proof).tools/verify-ux-plan.py verifier for required table fields and citation existence; it must accept explicit UNVERIFIED rows and reject missing owner, evidence class, or acceptance fields. Verify with python3 tools/verify-ux-plan.py --self-test (host proof).docs/research/handheld-ux/interaction-contract.md: distinguish release-animation budgets from continuous finger tracking, preserve required card interactions under reduced motion, and cover readable status/focus. Create annotated current-versus-recommended wireframes and a navigation storyboard in that directory; review against existing native captures without claiming new pixels shipped. Verify required fields and references with python3 tools/verify-ux-plan.py docs/research/handheld-ux/interaction-contract.md and record coordinator visual review in docs/research/handheld-ux/design-review.md. Extend the verifier schema for the contract as needed; it does not assess design quality.openspec validate --all --strict, merge/push them to master, and record their commits and dependencies in the issue ledger. If no uncovered P0/P1 finding exists, record that conclusion rather than inventing work.openspec status --change the-shell-has-a-card-composition-plan --json and the app-card proposal status are reviewed before landing any successor (host OpenSpec review).UNVERIFIED markers rather than creating an unsupported implementation task (host document review).python3 tests/test_launcher_navigation.py && python3 tests/test_touch_menu.py && python3 tests/test_window_catalog.py && python3 tests/test_desktop_catalog.py (host proof only).flock /tmp/k230-board.lock python3 tools/capture-boot.py --dev /dev/ttyACM0 --out /tmp/k230-ux-boot.txt --seconds 120; for a needed physical interaction capture run python3 tools/capture-feature.py ux-review --provenance real-touch --duration 30 --description 'Observed handheld flow for UX review' --output-dir /tmp/k230-ux-capture. Arrange real interaction before labelling footage real-touch, sanitize and review before committing selected artifacts. If observation is unavailable or unnecessary, record the reason and explicit unknowns; that is an audit outcome, not hardware acceptance. Do not repeat already accepted keyboard/Home trials without a new concern.openspec validate the-handheld-has-a-coherent-ux-plan --strict, git diff --check -- openspec/changes/the-handheld-has-a-coherent-ux-plan, and python3 tools/work-status.py (host proof).This capability gives the handheld a single, reviewable UX contract across boot, discovery, touch navigation, application states, and recovery, while preserving evidence boundaries between host checks, injected input, native captures, and real-finger observations.
Grounding: docs/research/handheld-ux/evidence-index.md and evidence-review.md link the reviewed source, native, injected and physical observations; unsupported observations remain explicit.
The plan SHALL describe the person-facing journey from boot to a recoverable application state and SHALL identify the owning layer or successor proposal for each issue. Every observation SHALL name its source artifact and SHALL distinguish host/native/injected evidence from physical-finger or optical evidence; unsupported current behavior SHALL be marked UNVERIFIED.
UNVERIFIEDGrounding: docs/research/handheld-ux/flow-matrix.md records boot, discovery, keyboard, media and recovery journeys with their owners, evidence and open gates.
The plan SHALL define an observable first-use path: boot feedback into the portrait shell, a clear initial action, Apps discovery through desktop entries, Help or equivalent orientation, and a recoverable empty/error state. It SHALL preserve existing working bar controls while proposing consistent labels and focus behavior.
Grounding: docs/research/handheld-ux/interaction-contract.md, three annotated SVG sheets and design-review.md establish measurable planning criteria; physical readability and reachability remain UNVERIFIED.
The plan SHALL provide measurable guidance for hierarchy, type, spacing, color contrast, touch target geometry, reachability, keyboard-visible layout, and focus indication at the 568x1232 portrait panel. It SHALL treat rotation as unsupported until a source or board observation proves it, and SHALL not infer readability or reachability from injected input alone.
Grounding: docs/research/handheld-ux/interaction-contract.md and flow-matrix.md define visible routes and state ownership; runtime completion remains gated by the respective changes.
The plan SHALL define how Apps, Windows/overview, cards, Back, Home, Keyboard, System, and video controls compose; how focus changes; and how loading, empty, network failure, EOF, cancellation, and cleanup are exposed. Existing card proposals own card state and gesture mechanics; this capability owns cross-surface consistency and acceptance.
Grounding: docs/research/handheld-ux/issue-ledger.md maps P0/P1 findings to the two published successors and existing card/video owners; audit and proposals were pushed through master 7e4cc02.
The plan SHALL maintain a severity-ranked issue ledger, user-flow/task matrix, P0/P1 successor proposals, dependencies, and parallel ownership. Each successor SHALL have host and board gates where applicable, and all resulting proposals SHALL be validated, merged and pushed to master before implementation is treated as integrated.
Archived change · Archived
Snapshot 5836ef1d113d · 2026-10-17 08:22 UTC
Closed recordReview the archived record and cited scope
The handheld’s native Apps launcher is reliable for taps and buttons, but a finger drag currently cancels the card instead of providing a useful page or window transition. A bounded client-side gesture and overview surface can give the shell a webOS-like cards experience while preserving the working Sway session, persistent bar, keyboard, and button fallbacks.
None.
runtime/shell: add touch launcher paging and a metadata-only window overview while retaining existing controls and recovery behavior.The change affects nix/touch-launcher, its launcher packaging and tests, the shell’s launcher/menu integration, and shell evidence. It uses existing Wayland layer-shell, wl_touch, Sway IPC, and terminal/window focus paths. It does not require kernel, device-tree, compositor, or GPU changes. Physical-board validation is required for real-finger gesture behavior and panel readability; injected input and host tests can validate state-machine correctness and fallback behavior first.
The current native launcher is a Wayland layer-shell client using SHM/Pango/Cairo
and direct wl_touch events. It activates a card only when release remains over the
same card; motion outside the card cancels activation. The persistent shell bar and
its touch-menu.sh already provide button-based Apps, Windows/Home, Keyboard,
System, Terminal, and Monitor paths. Sway owns DRM, input routing, workspaces, and
focus through IPC.
The panel is 568x1232 at about 52.19 Hz, RGB565, and Pixman-rendered with no DRM render node. Existing scene-build/KMS submission measurements are 14.0 ms median, 15.6 ms p95, and 22.7 ms p99 under terminal scrolling and keyboard load. They do not prove presentation timing for a new animation.
Goals:
Non-Goals:
Keep one launcher client. Extend the existing layer-shell surface and state machine so the gesture and overview share current launch/error/Back behavior. A separate overview client would duplicate input and lifecycle handling before live thumbnails are even available.
Use fixed geometry thresholds. Start with a 48 logical-pixel threshold as an explicit tuning assumption, to be accepted or adjusted from new gesture evidence on the panel. It is not yet a measured finger-jitter boundary. Require a 1.25 horizontal/vertical dominance ratio. Once the threshold is crossed, cancel tap activation permanently for that touch. Reject multi-touch and compositor cancellation.
Map directions to simple modes. Horizontal left/right pages the existing Apps catalog. Up enters metadata overview; down exits it. A mode transition is committed only on release after classification, avoiding partial app launches during motion. The existing Previous/Next/Back buttons remain equivalent non-gesture routes.
Use Sway metadata, not thumbnails. Read the current tree through the existing IPC boundary or a small shell-owned helper and retain stable container identifiers only for the open view. Draw title/app ID/state cards. Re-query before focus and treat missing IDs as stale; never assume a window still exists. No screencopy or privacy surface is introduced in this phase.
Keep keyboard focus out of the overlay. The launcher and overview remain layer-shell keyboard-non-interactive. Selecting a card closes/yields the surface before focusing the target. The on-screen keyboard is still controlled by the persistent bar and retains its current focus semantics.
Bound transitions for Pixman. Pre-render the source and destination card pages, use a short fixed translation/settle sequence capped at 200 ms, and fall back to an immediate final frame if frame work misses the deadline. Do not add blur, shadows, alpha-heavy thumbnails, or continuous physics until measured evidence justifies them.
Build the launcher with the gesture state machine behind the existing Apps entry. Run host state-machine tests and injected input checks first. Flash only after the launcher package and shell image validate. If gestures regress, disable gesture recognition while retaining the existing tap/button launcher; the persistent bar and Apps catalog remain the recovery path. If the overview is unstable, remove only its mode and leave horizontal paging and all prior controls intact.
None. Live thumbnails and compositor-level gestures are deferred decisions, not requirements for this bounded first phase.
python3 tests/test_launcher_navigation.py or a focused gesture test.python3 tests/test_touch_menu.py and existing launcher/catalog tests pass.docs/evidence/.nix build .#touch-launcher show only the intended userspace closure.openspec validate touch-launcher-gestures-overview --strict and verify every new requirement has evidence or an explicit UNVERIFIED marker../scripts/build_site.py and ./tools/blob-scan.py --no-vendor; verify any evidence images/video have provenance, hashes, and DATA inventory rows.Task 1.3: docs/evidence/launcher-gestures/integrated-injected/README.md records the flashed-image matrix: 20 exact left/right pairs, no new application window, and all 41 settled transitions within 163 ms. This is injected input; final-glass acceptance remains open.
Task 4.1: the integrated-injected evidence includes 40 keyboard-hidden Apps transitions, a two-window overview, and ten keyboard-visible transitions, with elapsed/process CPU median/p95, buffer/snapshot counters and before/after RSS/PSS. These are CPU-side measurements, not optical timing.
Task 3.2: docs/evidence/launcher-gestures/metadata-budget/README.md records the production-client host ordering fixture plus an injected Monitor-to-Terminal selection on the board: launcher closed, Terminal focused, existing Foot/htop process sets unchanged. The same report records 20 keyboard-visible two-card overview refreshes using the separated metadata deadline; final-image and physical-finger acceptance remain distinct.
Final installed-image proof: docs/evidence/final-shell-image/README.md, result JSON, executed checker and native captures. Injected board interaction and the accepted real-finger workflow are separate evidence classes; the existing camera view does not prove uniform sharpness or optical timing.
Final evidence validation: python3 scripts/build_site.py passed (123 pages, 4,029,541 bytes); python3 tools/blob-scan.py --no-vendor accounted for all 295 committed binaries; strict validation passed all 25 active specs/changes.
The Apps launcher SHALL treat a single touch as a tap until its movement reaches 48 logical panel pixels. After that threshold, a horizontal gesture SHALL require horizontal displacement at least 1.25 times its vertical displacement. A left swipe SHALL advance one application page and a right swipe SHALL return one page; the same touch SHALL NOT activate a card. A gesture that does not meet the threshold or directional ratio SHALL leave the page unchanged and SHALL NOT launch an application.
Grounding: docs/evidence/launcher-gestures/integrated-injected/README.md
records numeric threshold and transition checks on the installed image;
docs/evidence/launcher-gestures/real-finger/README.md records the accepted
physical paging workflow. The camera view does not resolve exact finger
coordinates or uniformly sharp small text.
The launcher SHALL provide an overview mode reachable by an upward single-touch gesture from the Apps card region using the same 48-pixel threshold and 1.25 directional ratio. It SHALL render one touch-sized card per current Sway window using metadata such as title and application identity, focus the selected window on tap, and return to Apps or the prior shell surface through Back or a downward gesture. Stale or empty window state SHALL be represented visibly and SHALL not make the launcher exit.
The first overview SHALL use text, solid surfaces, and small icons only. It SHALL not require live window thumbnails, a compositor fork, a GPU renderer, or a screencopy protocol. Existing persistent Windows/Home, Keyboard, Apps, Help, Previous, Next, and Back controls SHALL remain available according to their current contracts.
Grounding: docs/evidence/launcher-gestures/real-finger/README.md records
overview entry, return, and window selection by a real finger. The installed
image’s injected/native observations are in
docs/evidence/launcher-gestures/integrated-injected/README.md and
docs/evidence/final-shell-image/README.md. Exact touch paths and optical
sharpness remain outside this recording’s proof.
A gesture transition SHALL complete or cancel within 200 milliseconds of its release, SHALL not leave a half-open overlay after a rendering or input error, and SHALL preserve the existing button paths for Previous, Next, Back, Apps, Windows/Home, Keyboard, Help, Terminal, Monitor, and system controls. The client SHALL remain keyboard-non-interactive while it is an app chooser or overview so that the existing terminal keyboard path is not displaced.
Grounding: docs/evidence/launcher-gestures/integrated-injected/README.md
records installed-client transition timing, resource counts, and fallback
checks. docs/evidence/launcher-gestures/real-finger/README.md establishes the
accepted workflow, but optical timing of its transitions remains UNVERIFIED.
Archived change · Archived
Snapshot 5836ef1d113d · 2026-10-17 08:22 UTC
Closed recordReview the archived record and cited scope
Live cards still miss their measured CPU/frame budgets, and the normal system cannot expose the CPU-vector path that might reduce software rendering cost. Existing kernel and Pixman build investigations identify disabled vector support; a recoverable physical trial is needed to learn whether it is safe and useful. This kernel experiment needs an explicit scope separate from the userspace-only card proposal.
Non-goals: enabling the second core or GPU, replacing stage 1, upgrading the kernel family, making vector support a dependency of card acceptance, changing interaction budgets, or promoting a trial into the default image. Any default promotion needs a separate reviewed proposal and compatibility evidence.
None.
system/kernel: a recoverable optional CPU-vector trial with capability, context-safety and measured-rendering gates.The kernel owns vector enablement and context handling; userspace owns capability gating, pixel tests and measurements; Nix owns matching kernel/modules/initrd packaging. Likely paths are the existing RVV derivations and patches, dedicated board-trial tools, optional renderer packaging and committed evidence. Existing host builds and full Linux QEMU context tests can be reused with exact provenance. Physical trial boot, recovery and rendering comparisons require the single board and serial reservation. The normal Pixman shell remains the baseline.
See proposal.md for the performance gap and separate scope. Existing source work already fixes the pinned Xuantie compiler probe (rv64iv needs M with GCC 15) and Pixman’s missing sys_riscv_hwprobe wrapper. Normal hardware still reports no usable standard V. The context diagnostic passes full Linux QEMU cases and safely skips on the normal board. These are reusable checkpoints, not trial-kernel or speedup acceptance.
Goals: make the existing experiment reproducible, recoverable and measurable; close each diagnostic/build/board stage with its own evidence; feed a concrete result to the card cost decision.
Non-goals: see the proposal. In particular, do not change the normal kernel/renderer, relax card budgets, claim a second core, or require RVV to finish the independent Pixman card path.
saveenv. Reflashing for every experiment is rejected because it needlessly replaces the known return path. A physical reset remains a possible recovery action after a kernel hang; do not relabel that limitation as automatic recovery.Publish this scope, then reconcile the existing source/build/guest checkpoints. Finish the physical load-and-return path and record normal recovery. Boot the matching system once, capture capability/configuration/context results and normal shell/network observations, then return and reverify normal boot. Only after a physical context PASS should pixel and paired card trials proceed. Keep every unmet gate open. A default promotion, if justified, is proposed separately with its remaining image and real-glass checks.
Existing successful commands may be reused only after reviewing their committed source/artifact provenance. These tasks claim host or full-system guest proof, never physical vector execution.
nix build .#kernel-rvv-trial --no-link --print-out-paths and cite the inspected configuration in docs/evidence/card-shell/kernel-rvv/.PIXMAN_SOURCE_TAR=/nix/store/s2cifkjf074cwcim1p9lij646fi3p3zy-pixman-0.46.4.tar.gz python3 tests/test_pixman_rvv_probe.py and nix build .#pixman-rvv --no-link --print-out-paths, retaining the normal-board no-vector result.nix build .#nixosConfigurations.k230-rvv-trial.config.system.build.toplevel --no-link --print-out-paths; record the immutable system path.nix build .#sdImage-rvv-trial --no-link --print-out-paths; record actual image/kernel hashes, wrapped-initrd payload/CRCs and matching bootargs selection.python3 tools/rvv-context-qemu.py --package PROBE --corrupt-package CORRUPT_PROBE --kernel GUEST_KERNEL --output NEW_OUTPUT invocation and artifacts recorded in docs/evidence/card-shell/kernel-rvv/context-probe/README.md and result.json.Reserve the board and keep raw console output private until selecting secret-free evidence. Each capture uses a new output path. HOST_TRIAL_MANIFEST binds the inspected trial artifacts to the committed normal-system baseline. A failed gate remains open; do not force vector instructions.
python3 tests/test_rvv_board_boot.py, then load all five physical artifacts with matching lengths/CRCs and return to normal using python3 tools/rvv-board-boot.py --manifest HOST_TRIAL_MANIFEST --private-log PRIVATE_LOG --output NEW_LOAD_JSON. Commit the load observation and separate normal shell/Wi-Fi recovery capture.python3 tools/rvv-board-boot.py --manifest HOST_TRIAL_MANIFEST --private-log PRIVATE_LOG --output NEW_BOOT_JSON --boot; commit the observed boot and running-system/configuration identity. A login by itself does not complete the identity check.flock /tmp/k230-board.lock python3 tools/console.py --wait=20 'timeout --kill-after=3s 15s /nix/store/4gn2z5fi5szrnflhzjsr1kq3f1b39wqx-k230-rvv-context-probe-riscv64-unknown-linux-gnu-0.1/bin/k230-rvv-context-probe'; commit JSON, exit status and provenance. SKIP, timeout or FAIL does not satisfy this gate.python3 tools/check-root-growth.py --board --phase repeat --helper /nix/store/6sca423wcjlq1v9ynjpbv4ai48jf53l9-k230-root-growth --target-system /nix/store/gnr36q39hmy4pq7ipwac1r1rpfbyqxd4-nixos-system-nixos-26.11.20260919.20b1ddd --before docs/evidence/storage-capacity/board-after.json --output NEW_RECOVERY_JSON. Record whether recovery needed physical intervention and retain failures.Requires 2.3 PASS. Proposed commands in this section must be implemented before invocation; their names are intended interfaces, not claims that tools already exist.
python3 tools/pixman-rvv-compare.py --board --package /nix/store/1sc1733sagi7ifx4bxw4dz0yg3hw3amj-k230-pixman-rvv-pixel-probe-riscv64-unknown-linux-gnu-0.1 --output NEW_PIXEL_OUTPUT. Commit cases, exact library identities, actual dispatch evidence and results.nix build .#card-shell-rvv --no-link --print-out-paths and record its dependency/dispatch identity; this build is host proof only.Requires physical context and pixel correctness. The comparison must use the same trial kernel, scene, panel format, input sequence and measurement producer. Keep native capture, injected input and real-glass observations distinct.
python3 tools/card-shell-rvv-benchmark.py --board --repeats 3 --revision BENCHMARK_SOURCE_REV --output /var/lib/k230/rvv-benchmark-NEW_NAME on the reserved board with its sibling scripts staged, measuring identical live-card interactions with vector dispatch on/off. Commit each run’s frame/update timing, input latency, CPU and memory costs, producer/artifact identity and comparison against unchanged card budgets.docs/evidence/card-shell/kernel-rvv/; restore and reverify the normal system using the recovery command in 2.4 after the final rendering trial. A successful experiment does not promote the default image; any promotion requires a separate reviewed proposal.openspec validate the-system-trials-cpu-vector-acceleration --strict and python3 scripts/build_site.py, then verify the pushed revision’s CI and published site. Archive only after every task and physical evidence gate is complete.Physical tasks 2.2–2.4: docs/evidence/card-shell/kernel-rvv/board-trial/README.md
links the actual one-time boot, verified running-system/configuration identity,
scalar capability report, two-process context PASS and separate normal-recovery
capture. The committed capture script invokes the bounded command in 2.3; this
is physical-board evidence, not the earlier generic Linux guest result.
Tasks 3.1–3.2: docs/evidence/card-shell/pixman-rvv/pixel-trial/README.md
records 192 physical byte comparisons, executed RVV callback counts, the
one-byte corruption control, normal recovery and the built optional card
package. The package uses recursive dependency-reference replacement with the
ABI-identical library; a default promotion requires a fully rebuilt graph.
No card performance result is claimed by these tasks.
Task 4.1: docs/evidence/card-shell/kernel-rvv/card-cost/README.md records six
matched physical runs and exact host reconstruction of their budgets. Every
workload still fails frame CPU and tracking cadence; four runs miss the upward
throw. Complete measurement does not mean accepted card performance.
Task 4.2: the same card-cost record retains the negative promotion decision;
normal-reboot.json and normal-recovery.json prove serial return without
physical intervention, the ordinary system, preserved boot/root data and
shell/Wi-Fi HTTPS recovery after the final rendering trial.
Task 4.3: source/evidence revision a27a08941fddf9ed8a0d7560654f329a990a482e
passed strict change validation and the 141-page site build (4,231,164 bytes,
17.32 seconds), then CI/deployment run 35931039551. The actual handheld and
paired-evidence URLs returned HTTP 200 with the new result/failure text;
docs/evidence/card-shell/kernel-rvv/card-cost/publication.json records the
observation. Archive publication is verified separately after its final push.
Physical grounding: docs/evidence/card-shell/kernel-rvv/board-trial/boot1.json, vector-state1.json and trial-normal-recovery.json record one-time trial boot, matching running identity and normal shell/Wi-Fi return with protected hashes unchanged. Earlier failed load reports and recovery are retained in the same directory.
Grounding for the approach: the matching kernel/system/image builds and actual boot-artifact inspection are recorded in docs/evidence/card-shell/kernel-rvv/; storage first/repeat boot evidence is in docs/evidence/storage-capacity/. Host builds do not prove a trial kernel boots.
The system SHALL provide an explicitly selected CPU-vector trial with matching kernel, external modules, initrd and userspace. Trial preparation and one-time boot SHALL retain the known normal persistent boot selection and protected credential procedure. The operator SHALL verify artifact identity before loading the trial and verify the normal system, shell and Wi-Fi after returning. A failed load SHALL stop trial execution and attempt normal recovery while the bootloader remains available. Recovery requiring an operator reset SHALL be reported rather than claimed as automatic success.
Physical grounding: docs/evidence/card-shell/kernel-rvv/board-trial/vector-state1.json records hwprobe value 63 and a two-process PASS with 2,000 checks per process across signals and scheduling. This is representative state proof, not exhaustive ISA coverage.
Grounding: docs/evidence/card-shell/pixman-rvv/kernel-probe.json records successful hwprobe with value 59 and no standard V bit; docs/evidence/card-shell/kernel-rvv/context-probe/board-skip.json records safe SKIP/77. Full-system guest context and deliberate-corruption cases are separate diagnostic proof.
The optional vector path SHALL require the kernel’s runtime capability report and physical vector computation with preserved state across asynchronous signals and process scheduling. A processor name, ISA string, successful cross-build or guest result SHALL NOT substitute for that physical evidence. If capability is absent or the state check fails, rendering SHALL retain scalar fallback and the failed or skipped result SHALL remain visible. The trial SHALL NOT force vector instructions merely to bypass a failed runtime gate.
Grounding: physical-board comparison in docs/evidence/card-shell/kernel-rvv/card-cost/README.md, run1/result.json and comparison.json record six matched physical runs with unchanged budgets. CPU-cost changes are small and mixed; every workload fails overall acceptance, four upward-throw checks fail, and the decision retains the ordinary image. This is injected-input measurement, not real-finger or optical proof.
Partial physical grounding: docs/evidence/card-shell/pixman-rvv/pixel-trial/board/result.json records 192 exact byte comparisons, real RVV callback counts and a detected one-byte corruption control. This proves only its declared pixel cases, not card costs.
The optional userspace renderer trial SHALL compare its declared pixel cases against the scalar reference and measure the same live-card workload with vector dispatch enabled and disabled on the same trial kernel. It SHALL retain frame/update, input-latency, CPU and memory measurements and all existing card interaction budgets. A compiled vector path, isolated instruction test or faster synthetic operation SHALL NOT be presented as a card-shell speedup. The recorded decision SHALL preserve negative results and distinguish an optional experiment from a default image change.
Archived change · Archived
Snapshot 5836ef1d113d · 2026-10-17 08:22 UTC
Closed recordReview the archived record and cited scope
The handheld cannot stage the next complete system trial because its root filesystem has only 77 MB free, even though the physical card is about 128 GB. The flashed image leaves the root partition at about 2.2 GB; the same limit also restricts ordinary app installation and Nix updates. Board measurements are committed in docs/evidence/storage-capacity/preflight.json.
Non-goals: moving partitions, shrinking filesystems, general disk management, automatic deletion of Nix generations or app data, changes to flashing target authorization, GPU/RVV default selection, or restoring mutable home-directory state.
None.
image/sd-layout: distinguish compact flashed root size from safely expanded running size while preserving fixed boot locations.The system owns growth through NixOS configuration and a bounded layout guard. Likely paths are nix/hardware.nix, a narrow growth helper/module if the pinned NixOS options need extra guards, and dedicated disposable-image tests. Stage 1 and flashing remain unchanged. Host/QEMU tests can proceed independently; acceptance requires the physical board, a recovery artifact and serial ownership. This unblocks staging larger trial closures but does not itself prove RVV, card performance or GPU correctness.
See proposal.md for the capacity failure and docs/evidence/storage-capacity/preflight.json for the physical measurements. The root starts at 128 MiB after the fixed boot/firmware areas. nix/hardware.nix declares ext4 by label without growth. The observed card has ample unused tail space; reclaiming old diagnostic packages would only postpone this limit on fresh images.
Goals: let a fresh, compact image use its actual card capacity; make repeat boots and interrupted two-phase growth safe; provide proof for both filesystem behavior and fixed boot boundaries.
Non-Goals: see the proposal. In particular, do not turn this into a generic host-disk tool or delete store paths/home data to make a test fit.
mmcblk number. Any failed check precedes either mutation. A layout with later partitions is refused even if a gap could be consumed safely; partition rearrangement is outside this scope.nixos/modules/system/boot/grow-partition.nix exposes boot.growPartition using cloud-utils growpart; it tolerates exit 1 for already-full partitions and orders before filesystem growth. It does not supply this project’s complete layout guard and has an infinite timeout. Use those pinned utilities behind a single guarded, finitely bounded oneshot; reuse stock options only if both mutation phases can be gated together. Do not independently enable filesystem auto-growth on a refused layout. A failed growth job must not make the existing root/shell unavailable.Land this proposal first. Implement/evaluate the narrow guarded service and run disposable-image tests. Build a matching system/image only after those checks pass. Preserve the normal recovery image, reserve the board, and record pre-growth identities/boundaries and boot-file hashes. Prove first boot, increased available capacity, root sentinel retention, normal shell/Wi-Fi recovery without publishing credentials, and a second reboot with unchanged boundaries. A source build or temporary manual resize does not satisfy the default-image boot requirement. Keep every physical task open until that evidence is committed.
python3 tests/test_root_growth.py and nix build .#root-growth --no-link --print-out-paths. Host policy/build proof only.python3 tools/check-root-growth-config.py. Keep QEMU’s unrelated netboot root outside board growth selection.Narrow host proof: python3 tests/test_root_growth.py, nix build .#root-growth --no-link --print-out-paths, and python3 tools/check-root-growth-config.py. These do not prove real filesystem mutation.
python3 tools/test-root-growth.py --qemu --output docs/evidence/storage-capacity/qemu. Assert protected firmware/boot hashes, root start/identity, root-file sentinels, increased capacity and no writes on refusal. Record exact guest/tool artifacts and keep failed runs.nix build .#nixosConfigurations.k230.config.system.build.toplevel --no-link --print-out-paths followed by nix build .#sdImage --no-link --print-out-paths, recording image/system identities and unchanged initial boot/root offsets. This proves build/layout, not physical expansion.Proof: python3 tools/test-root-growth.py --qemu --output docs/evidence/storage-capacity/qemu, then the two narrow system/image builds above. QEMU is not K230 boot proof.
python3 tools/check-root-growth.py --board --phase before --output docs/evidence/storage-capacity/board-before.json. Reserve board/serial and retain the existing protected credential procedure. No routine whole-image flash readback is required.python3 tools/check-root-growth.py --board --phase after --before docs/evidence/storage-capacity/board-before.json --output docs/evidence/storage-capacity/board-after.json and commit the actual serial growth/boot observations. A manual resize alone does not satisfy this task.--phase repeat --before docs/evidence/storage-capacity/board-after.json --output docs/evidence/storage-capacity/board-repeat.json. Keep this open until the physical second boot exists.Physical proof: the named tools/check-root-growth.py --board captures plus serial boot logs; host/QEMU output cannot close group 3.
openspec validate the-system-uses-the-card-space --strict, python3 scripts/build_site.py, and python3 tools/blob-scan.py --no-vendor, then merge/push and inspect the deployed spec URL. Archive only after every preceding task and physical proof is complete.Proof: the three commands above and the published URL for the landed revision. Proposal publication alone is not a shipped expansion capability.
Host policy, narrow package and evaluated service proof: docs/evidence/storage-capacity/implementation.md. The actual disposable RISC-V guest passes all seven filesystem/preservation cases in docs/evidence/storage-capacity/qemu/result.json. These complete tasks 1.1, 1.2 and 2.1. docs/evidence/storage-capacity/image-build.json records the matching system/image build and actual compact boot-partition inspection for 2.2. Physical first/repeat boots now pass in board-before.json, board-after.json and board-repeat.json beside that evidence. The image system closure and exact boot files were installed on the existing compact root, without a full reflash or manual resize. Publication of the completed physical evidence and handheld update passed build/deploy run 35921034930 for master a20c0492; publication.json records the actual published-page response. All eight tasks are complete.
Grounding: docs/evidence/storage-capacity/board-before.json, board-after.json and board-repeat.json record two physical boots of the integrated image system and matching boot files on the existing compact root. The boot service grew ext4 from 2,173,693,952 to 127,800,422,400 bytes; the second boot reported no change. Shell and Wi-Fi recovered. image-build.json separately proves the downloadable image remains compact. No full-image reflash or manual resize was used for this trial.
On a card with the repository’s supported layout and unallocated trailing space, the system SHALL grow its final root partition and ext4 filesystem during boot so that the trailing capacity becomes usable without a manual resize. The downloadable image SHALL remain compact. The system SHALL retain root contents, filesystem identity, and the fixed root start offset. Stage 1 SHALL not own this growth.
Grounding: physical first/repeat boot captures in docs/evidence/storage-capacity/ preserve root/boot identities, the MBR boot code, firmware-gap hash, all eight selected boot-file hashes and a root-file sentinel. The actual disposable-system QEMU cases in qemu/result.json separately prove unsupported-layout refusal, tool-failure preservation and partition-only retry. Those negative cases are guest proof, not destructive tests on the physical card.
The system SHALL preserve raw stage-1 payloads, the boot partition’s start, size and contents, and the root partition’s start and identity. It SHALL grow only the positively identified mounted ext4 root in the supported final-partition layout. If the root device, labels, partition table or filesystem is unexpected, or any later partition exists, it SHALL refuse growth before writing and retain a bootable system with a recorded reason. A growth error SHALL not erase data or require root reformatting. A subsequent boot SHALL safely handle a partition already enlarged before filesystem growth completed.
Archived change · Archived
Snapshot 5836ef1d113d · 2026-10-17 08:22 UTC
Closed recordReview the archived record and cited scope
The handheld can now prove a bounded remote Big Buck Bunny stream through a temporary mpv probe, but video playback is not part of the Nix image or Apps surface. Current evidence shows unscaled software H.264 at 480x270 with zero reported drops and MVX-decoded 640x360 with point scaling at 0–2 output drops per 30 seconds, using a silent known-CFR timing workaround; the project needs a reproducible player configuration and honest hardware acceptance before presenting network video as a shell capability.
runtime/video: reproducible network video playback, decoder selection, controls, and evidence requirements for software and MVX paths.runtime/shell: Apps exposes the video player and the user can launch, stop, return Home/Back, and recover from a failed playback or network attempt without an external keyboard.The change affects the Nix shell image, mpv/FFmpeg package configuration, the native launcher catalog or terminal bridge, and touch/menu controls. It adds no kernel or device-tree requirement for the software baseline; the optional MVX path depends on the existing V4L2 device and requires physical-board evidence. The existing root-controlled persistent Wi-Fi service remains the network boundary; media credentials and private URLs are runtime inputs. The current Big Buck Bunny and docs/evidence/mvx-v4l2-audit.md records provide initial grounding; new-player and successful hardware-presentation requirements begin unverified.
The existing shell is Sway/Pixman at 568x1232 with Foot, a native Apps launcher,
an on-screen keyboard, and root-controlled persistent Wi-Fi credentials delivered at runtime. The initial BBB trial
recorded substantial output drops. The follow-up in
docs/evidence/video-acceleration/README.md establishes unscaled 480x270
software playback at zero reported drops and 640x360 MVX playback with CPU
point scaling at 0–2 output drops per 30 seconds. MVX still needs a known-CFR
workaround and showed a teardown stall; neither general timestamps nor
presentation cadence nor integrated recovery is accepted yet.
Goals:
Non-Goals:
Use the existing terminal/launcher path. Add one controlled desktop entry through the current catalog and Foot bridge. This keeps input, Back/Home, process lifecycle, and error recovery in already-tested shell paths. A separate full-screen Wayland player would duplicate focus and return behavior.
Ship a software baseline first. Pin the mpv/FFmpeg derivations and explicit
wlshm, software-H.264, and audio settings. The 480x270 BBB representation is the
initial reproducible baseline with native media timestamps. The improved 640x360
MVX profile remains explicit and limited to the known silent 30-fps demo until
its timestamp and recovery behavior is established.
Keep MVX opt-in and evidence-gated. Add a separate command/profile that selects the audited V4L2 decoder only after device discovery, format negotiation, and frame delivery are observable. On failure, return to software playback and label the result as fallback. Do not make the default image depend on a successful MVX path.
Use runtime-only source configuration. A public URL may be supplied by the
operator or a documented test wrapper. Private network material stays in the existing
root-controlled systemd credential or one-off /run procedure and never enters desktop files, Nix expressions, argv,
or the store. The player entry must not become a general network installer.
Separate three evidence layers. Host/Nix evidence proves derivations and closure. Console evidence proves decoder/output counters and CPU/cache behavior. Native screenshots and camera frames prove visible content, but only synchronized presentation timing over at least 30 seconds can support a sustained-presentation claim. Audio gets its own measured result or remains explicitly unverified.
Prefer bounded controls over playback sophistication. The first controls are launch, stop/quit, Back/Home return, and recovery after EOF/network/decoder failure. Do not add seek UI, thumbnails, playlist state, or background playback until the basic lifecycle is stable on the narrow portrait panel.
Build the player and launcher entry behind the existing shell image option. Validate host closure and desktop discovery before flashing. On the board, run the software baseline first, then the optional MVX profile, leaving the ordinary shell configuration unchanged on failure. Roll back by removing the video package and entry; existing Apps, Help, Terminal, Monitor, keyboard, and Home behavior remain the recovery path.
None that change the bounded first implementation. The exact MVX format/output negotiation and audio method can be selected during the evidence task after the software baseline is reproducible.
wlshm/software-H.264 profile to the Nix shell image; verify the narrow package evaluations and derivation paths succeed without private URLs or credentials.nix build .#sdImage plus the named package derivations succeed on the host.k230-desktop-catalog list discovers it and launch ID returns a successful process launch with the expected terminal environment.wlshm, audio state, decoder drops, video-output drops, cache, and player exit reason in docs/evidence/.CLK_TCK and page size, and calculate only clearly labeled interval estimates; verify raw /proc transcripts and the calculation method are committed with no secret or unrelated terminal data./dev/video0 presence alone.openspec validate the-shell-plays-network-video --strict; verify every requirement has grounded evidence or an explicit UNVERIFIED marker../scripts/build_site.py and ./tools/blob-scan.py --no-vendor; verify all committed screenshots, clips, logs, and any media test assets have provenance, attribution, hashes, and DATA inventory rows.Initial completed tasks are grounded in docs/evidence/big-buck-bunny/README.md
and its committed 270p/360p logs and CPU sample. These are temporary-probe
results; package/image integration and presentation acceptance remain open.
Task 4.1: docs/evidence/video-acceleration/v4l2-capabilities.txt records the
live MVX H.264 capability; mvx-decode-300.txt proves real decoded frames.
MVX timing, automatic fallback and integrated controls remain unaccepted.
Task 5.1: docs/evidence/network-video/README.md and the software/MVX
presentation logs record >30-second hardware-signalled compositor feedback,
unique submitted/presented frame IDs, clock/sequence validation and limitations.
Final-image lifecycle regression remains separate.
Host integration proof: docs/evidence/network-video/integration-host.md and its
JSON record cover package/image builds, closure deltas, runtime source boundary
and lifecycle tests. They do not close the final-image board acceptance tasks.
Tasks 2.1 and 3.4: docs/evidence/network-video/installed-app/README.md records catalog discovery, an injected Apps launch through Foot on the flashed image, 100 seconds of IPC/process observation with advancing playback, native/physical captures, and Back cleanup. Stop/Home/EOF/error/MVX/final regression remain separately open.
Final installed-image proof: docs/evidence/final-shell-image/README.md, result JSON, executed checker and native captures. Injected board interaction is distinct from the still-open focused real-finger gesture capture.
Final evidence validation: python3 scripts/build_site.py passed (123 pages, 4,029,541 bytes); python3 tools/blob-scan.py --no-vendor accounted for all 295 committed binaries; strict validation passed all 25 active specs/changes.
The shell SHALL expose a visible terminal video entry through Apps. A user SHALL be able to launch the documented player, stop or leave it with Back/Home, and return to the existing shell controls without an external keyboard. A failed launch, closed stream, or network error SHALL leave a usable recovery path.
Grounding: docs/evidence/final-shell-image/README.md records Apps launch, advancing playback, Stop/Back/Home and final control regression on the installed image. docs/evidence/network-video/installed-controls/README.md covers EOF; recovery-fixed/README.md and midstream-error/README.md in that evidence tree cover decoder fallback, startup errors and an actual interrupted stream. Final control checks use injected touch on the physical board; they do not establish a new real-finger or audio claim.
Provides a reproducible network-video path for the handheld shell and distinguishes software playback, optional MVX hardware decoding, audio, and physical presentation.
Grounding: docs/evidence/network-video/integration-host.md records the pinned player and source boundary. docs/evidence/final-shell-image/README.md records the flashed default image, installed player wrapper and successful Apps playback/cleanup; docs/evidence/network-video/midstream-error/README.md records interrupted-stream recovery.
The Nix image SHALL provide a version-pinned player and FFmpeg path that can open a runtime-supplied HTTP(S) or DASH media URL with software H.264 decoding and the existing CPU Wayland output. A protected network credential, URL, or derived secret MUST NOT be stored in Nix configuration, source control, process arguments, or the Nix store.
The system SHALL keep the MVX V4L2 decoder experiment separate from the software baseline. Hardware decoding MUST be enabled only when the device, format, and output path are verified on the board; a failed or unsupported MVX attempt SHALL fall back to the known software path without claiming hardware acceleration.
Grounding: docs/evidence/network-video/recovery-fixed/README.md records a forced MVX initialization failure followed by a distinct software child with advancing media time. docs/evidence/network-video/strict-comparison/README.md records strict MVX selection and over 30 seconds of steady playback/presentation. The experiment remains limited to the documented known-30-fps source; general MVX timestamps and seek smoothness remain UNVERIFIED, and software remains the default.
Playback evidence SHALL identify source frame rate and selected representation, report decoder and output-drop counters, and include at least 30 seconds of timing samples that distinguish decoded frames from actual presentation or scanout. A native compositor screenshot alone MUST NOT be treated as proof of sustained presentation.
Grounding: docs/evidence/network-video/README.md records >30-second per-frame presentation feedback, declared clock, event flags and kernel IRQ path, separately from decoder/output counters and physical photographs.
Grounding: docs/evidence/big-buck-bunny/README.md records explicit --audio=no video trials and makes no audio-output claim.
The player SHALL expose whether audio is disabled, decoded, or presented. Video acceptance MUST NOT imply audio acceptance when audio is disabled or lacks measured physical output evidence.
Archived change · Archived
Snapshot 5836ef1d113d · 2026-10-17 08:22 UTC
Closed recordReview the archived record and cited scope
The shell still composes through Pixman because the proven GPU result covers only opaque RGBX private buffers. A compositor integration would be unsafe to assume until RGB565, alpha/color behavior, and a DRM dma-buf import have been measured without taking over the live display.
runtime/gpu-validation: A bounded, privileged GPU validation path that
proves individual prerequisites before any compositor integration.None.
Adds nix/vglite-probe*, an optional flake package, GPU-specific research and
evidence documentation, and this change’s planning artifacts. It requires the
physical board only for the runtime checks; narrow cross-build and static
validation run on the build host.
See proposal.md. The pinned kernel exposes a root-only
/dev/vg_lite single-context API, while the shell owns DRM master and scans
out RGB565 dumb buffers. Existing board evidence proves only an opaque RGBX
private allocation; strict partially-alpha RGBA color preservation failed.
Goals:
vg_lite_finish timing window alongside
a Pixman CPU window for the same 2x RGB565 blit geometry.Non-Goals:
The executable runs rgb565, alpha, dmabuf, and benchmark subtests (or
all in sequence), printing begin/end markers and sampled pixels. This keeps
the one-context vendor API serialized and gives the board owner a compact
transcript. Separate binaries were rejected because an accidental overlap of
their VG-Lite contexts is explicitly unsupported by the kernel driver.
The dma-buf subtest opens the explicitly supplied DRM node with
O_RDWR|O_CLOEXEC; on this board it is /dev/dri/card0, with the running shell
already holding DRM master. It calls only dumb-create, PRIME export, dumb-map,
and dumb-destroy ioctls. The code contains no drmSetMaster, modeset,
add-framebuffer, plane, or atomic APIs. It maps the private dumb buffer on the
CPU, supplies that mapping and exported fd to vg_lite_map, waits with
vg_lite_finish, and checks every CPU-visible pixel. It must run with the
shell active; it does not select or adopt a scanout buffer.
The RGB565 test uses nonuniform red/green/blue/black quadrants and exact
multi-row boundary samples. Vendor VG_LITE_BGR565 is the memory layout that
matches DRM/Pixman RGB565 on this board. The alpha test prints original and
blended pixels and compares one sample against explicit straight and
premultiplied source-over models; an unmatched result fails. Passing this
sample does not resolve the previously observed general RGBA quantization.
Both paths perform identical nearest 2x scaling at 128x128-to-256x256 and 284x616-to-568x1232. After output validation and warmups, three rounds measure monotonic elapsed and process-CPU time. GPU per-operation completion uses 20 iterations; batched GPU work ending in one finish and Pixman use 200 each. This is not a compositor benchmark: cache state, memory placement, synchronization, interrupt work, and future buffer-import costs differ.
vg_lite_finish is required
before every read and outputs samples even on an assertion failure.Build the optional package, run it only under the board coordinator, commit the captured transcript, and update the integration recommendation. There is no deployment, service, image, or boot-state migration. Remove the package export to roll back host-side availability.
nix build .#k230-vglite-validation --max-jobs 1 --cores 8.nix eval .#packages.x86_64-linux.k230-vglite-validation.name.openspec validate validate-vglite-gpu-path --strict and git diff --check.docs/evidence/, and verify there was no modeset or service interruption. Hardware proof only; do not tick from a host build.Tasks 2.2–2.3: docs/evidence/gpu-validation/README.md and
cpu-timing-pass.txt record all four passed physical probes, unchanged service
invocations, three timing rounds, and the evidence-bounded renderer decision.
Provide an opt-in validation path for GPU prerequisites while preserving the working shell and the live display owner’s control of the panel.
Grounding: docs/evidence/gpu-validation/README.md records the source-built package and optional deployment; docs/evidence/gpu-validation/initial-format-failure.txt records nonzero pixel assertion failures.
The system SHALL expose a source-built, optional GPU validation package outside the default system closure. Its board invocation MUST report each probe’s completion and sampled color results, and MUST return nonzero if a required GPU operation or its explicit pixel assertion fails.
Grounding: docs/evidence/gpu-validation/cpu-timing-pass.txt records private dumb-buffer import, full CPU pixel checks, and unchanged service invocation IDs; docs/evidence/gpu-validation/README.md records the bounded DRM API review.
The GPU validation path SHALL create and export a private RGB565 DRM dumb buffer, import that dma-buf into VG-Lite, and verify the resulting buffer through its CPU mapping. It MUST NOT acquire DRM master, set a CRTC, create a framebuffer, or select a plane.
Grounding: docs/evidence/gpu-validation/README.md distinguishes the four measured results, process-CPU and wall-time costs, and remaining compositor/scanout gates while retaining Pixman.
The project SHALL record RGB565, alpha/color, dma-buf, and timing outcomes separately. A passing private-buffer or dma-buf probe MUST NOT be described as an accelerated compositor, display scanout, or video pipeline.
Archived change · Archived
Snapshot 5836ef1d113d · 2026-10-17 08:22 UTC
Closed recordReview the archived record and cited scope
Every time we change the image, a person has to power the board down, pull the TF card out of it, carry it to a reader, wait for 2.21 GB to be written, carry it back and power the board up. We did that several times in one evening. The loop cannot run unattended, it cannot run while nobody is at the desk, and it makes a one-line kernel change cost the same as a full rebuild.
Stage 1 could hand the card to the host itself. U-Boot’s ums command
presents a block device over USB, so the host writes the card while it stays
in the slot. The board already has the hardware for it — the data USB-C at
J3 goes straight to the SoC’s usbotg0 — and Canaan already ships a working
USB-gadget configuration for this SoC in the same U-Boot tree we build. See
docs/uboot-ums.md.
ums 0 mmc 1
presents the TF card to a host connected to J3 as a mass-storage device.tools/flash-latest.sh gains a target that writes to that device instead
of to a card reader. The reader path stays; it is the recovery path.ums command on, and usbotg0 enabled in the board device tree.snps,dwc2 nodes. The completed A2 follow-up now keeps host support
and uses the K230-specific binding/driver refusal so U-Boot host and UMS
coexist; current evidence covers that repaired variant. Linux is unaffected.Non-goals, named because each is a tempting adjacent thing:
k230_flash). That is
preserved in successor change characterise-bootrom-usb-recovery; this
change is complete on the U-Boot UMS path and makes no BootROM claim.flash-latest.sh copy 60 MB into a
mounted boot partition instead of dd-ing 2.21 GB is the larger speedup and
it depends on this change, but it is not this change.This change needs the physical board. QEMU’s k230 machine models no
block device and no USB controller, so nothing here can be proven under
emulation beyond “U-Boot still compiles”.
New Capabilities
Modified Capabilities
image/boot-chain — gains two requirements, about what stage 1 offers a
host over USB and about how a stage 1 that does not boot is recovered. The
capability is in openspec/specs/ (introduced by
the-board-boots-what-we-built, revised by
every-blob-is-built-from-source-or-named, both archived by 2026-09-22).
The delta is ADDED requirements only; no existing requirement is modified
or renamed — see design.md, “Why this is an ADDED delta and not a MODIFIED
one”. The requirement this change would once have had to overturn —
“Stage 1 … SHALL NOT be built from source by this project” — is gone: it
now reads “Stage 1 is built from source this project can read”, and this
change is the first to use that.nix/uboot-k230.nix. Written when
tools/gen-stage1.sh packaged a tree built elsewhere; since
every-blob-is-built-from-source-or-named landed, the flake compiles
U-Boot from pinned sources, so the configuration change is a Kconfig
fragment (nix/uboot-k230-ums.config) and a patch file
(nix/patches/uboot-k230/) that derivation applies, and nix build .#stage1 is the whole rebuild.tools/flash.sh / tools/flash-latest.sh. flash.sh refuses anything
that is not a /dev/disk/by-id path, for good reasons recorded in its
header. A ums target is a different by-id path, not an exception to that
rule.docs/blob-inventory.md. Nothing enters or leaves the blob inventory
— the sources are the same pinned sources, only the configuration
changes — and tools/blob-scan.py says so. There is no committed binary
whose hash needs refreshing any more; the built hashes live in
nix build .#stage1’s SHA256SUMS and in the evidence.See proposal.md — Why. The technical findings this design rests on are in
docs/uboot-ums.md; this document records the choices, not the evidence.
Three constraints shape everything below.
nix/uboot-k230.nix. When this was written,
tools/gen-stage1.sh packaged a tree built elsewhere and a configuration
change had nowhere to land; every-blob-is-built-from-source-or-named
moved the compile into the flake, so the change is a Kconfig fragment and
a patch file that derivation applies.Goals
ums.Non-Goals
ums. A bootcmd that stops and waits for a host is
a boot-time hazard on a board whose only recovery is a card reader. Typing
ums 0 mmc 1 at a prompt we already interrupt is enough.ums, not dfu, not rockusb, not fastbootums gives the host a block device, so dd, sfdisk, mount and
rsync all work unchanged and tools/flash.sh keeps its
/dev/disk/by-id guardrails.
Rejected: dfu. Canaan’s path, and cheaper in one way — CONFIG_CMD_DFU=y
alone also flips usbotg0 to okay, because k230.dtsi guards its
status = "disabled" with #ifndef CONFIG_CMD_DFU. But DFU writes named raw
regions from dfu_alt_info; it cannot mount a filesystem, so the
partial-write follow-up that is the real prize is not available. It also
drags in select DFU and, per arch/riscv/cpu/k230/cpu.c, removes the PMP
entries locking the 0x91213000/0x91214000 window.
Rejected: rockusb, fastboot. f_rockusb.c is in the tree but is
Rockchip protocol; fastboot needs a host tool and gives less than a block
device. Neither is used by anything on this board.
usbotg0 with an explicit device-tree override&usbotg0 {
status = "okay";
dr_mode = "peripheral";
};
in arch/riscv/dts/k230_canmv_v3.dts, rather than getting the same effect
for free by setting CONFIG_CMD_DFU=y. The override says what it means, does
not change the PMP configuration, and matches what
k230_canmv_mrt.dts, k230_canmv_lckfb.dts and k230_canmv_gt6700.dts
already do in the vendor tree.
In U-Boot 2022.10, U_BOOT_DRIVER(usb_dwc2) (UCLASS_USB) and
U_BOOT_DRIVER(dwc2_udc_otg) (UCLASS_USB_GADGET_GENERIC) both match
snps,dwc2. lists_bind_fdt() binds the first matching driver in the linker
list and stops; it only continues on -ENODEV from a driver’s .bind, and
neither driver has one. The gadget’s dr_mode refusal lives in
dwc2_udc_otg_of_to_plat(), which runs at probe — too late. Linker-list
entries sort by name, and dwc2_udc_otg sorts before usb_dwc2.
So with both enabled and only the generic compatible, the gadget claims every
snps,dwc2 node, including usbotg1, and U-Boot’s USB host goes dark.
This was confirmed by the first coexistence candidate; .bind alone was
insufficient because lists_bind_fdt() advances to the next compatible
string, not another driver for the same string.
The first A1 variant therefore set # CONFIG_USB_DWC2 is not set. That
configuration is historical: it produced the working UMS enumeration and
measured flash documented in docs/evidence/uboot-ums-write.txt.
The preferred A2 variant keeps CONFIG_USB_DWC2. Its gadget driver has a
bind-time refusal for non-peripheral/non-OTG nodes, and usbotg1 has
canaan,k230-usbotg-host before the generic snps,dwc2 compatible. The
K230-specific entry is needed so the host driver can claim usbotg1 while
the gadget claims usbotg0. The repaired build and current hardware evidence
are recorded separately; board proof confirms both paths work in the repaired
candidate. It does not claim USB packet traffic.
CONFIG_DM_USB_GADGET=y takes the DM half of dwc2_udc_otg.c, which fills
struct dwc2_plat_otg_data from the device tree. The legacy path, where a
board calls dwc2_udc_probe() by hand as Rockchip and Meson do, is the
#if !CONFIG_IS_ENABLED(DM_USB_GADGET) branch and we do not take it. The USB
PHY is already set up unconditionally in harts_early_init()
(arch/riscv/cpu/k230/cpu.c writes USB_IDPULLUP0, USB0_CTL0,
USB0_CTL1), so there is nothing left for a board file to do.
every-blob-is-built-from-source-or-namedThis change cannot land first. It needs a U-Boot that this repository configures and compiles, and under the requirement that change is replacing — “Stage 1 … SHALL NOT be built from source by this project” — it is not merely awkward but forbidden.
The obvious move was a MODIFIED delta against “Stage 1 is a pinned vendored artifact”. Two reasons not to, both now history but still the reason the delta has the shape it has:
openspec/specs/;
image/boot-chain existed only as an ADDED delta in
the-board-boots-what-we-built. Both that change and
every-blob-is-built-from-source-or-named have since archived, and the
capability is in openspec/specs/image/boot-chain/spec.md.every-blob-is-built-from-source-or-named
renamed it to “Stage 1 is built from source this project can read”. A
second MODIFIED delta against the same requirement, from a change that
depends on the first, would have been two changes editing the same
sentence in opposite directions.So the delta ADDs two requirements to the existing capability and touches
none of the five already there. openspec archive accepts ADDED against an
existing capability; it is MODIFIED and RENAMED that need their target to
exist under the exact name, and this delta carries neither.
The BootROM requirement originally drafted here is preserved in
characterise-bootrom-usb-recovery; it is not part of this archive.
So this change adds requirements about what stage 1 offers, and states its dependency instead of re-litigating how stage 1 is produced.
image/sd-layout, learned while reading the card backThe SDK’s genimage.cfg writes the environment twice, at 3 MiB and at
3.2 MiB, and nix/sd-image.nix reproduces that. Only the first copy is
live: k230_canmv_v3_defconfig sets CONFIG_ENV_OFFSET=0x300000 and has no
CONFIG_ENV_OFFSET_REDUND, so this U-Boot never reads or writes the copy at
3.2 MiB — observed 2026-09-22 (docs/evidence/uboot-ums-enumerate.txt,
session 8): after boots, the 3 MiB copy holds the saved live environment and
the 3.2 MiB copy is still byte-identical to the image. Not a requirement of
this change; recorded so nobody relies on the second copy as a backup.
dwc2_udc_otg_of_to_plat() in this tree reads
u-boot,force-b-session-valid and u-boot,force-vbus-detection; adding
either is a device-tree line. J3 has real USB0_ID and USB0_VBUS wiring
and cpu.c already sets IDPULLUP0, so there is a decent chance neither is
needed. Budget one extra iteration.dm tree at the U-Boot prompt settles it in one command, before and after.
Both variants are safe under either answer; only the explanation changes.ums is not obviously faster. The image is 2.21 GB and U-Boot’s dwc2
gadget realistically moves 5–20 MB/s. → The win claimed here is removing
the human, not raw throughput. If the follow-up partial write never
happens, this change buys unattended flashing and little else, and that
should be said out loud rather than discovered later.flash.sh’s existing
unmount step and by-id discipline already cover this; the ums device is
just another by-id path.ums overwrites the raw region at 1 MiB / 1.5 MiB /
2 MiB that the running U-Boot came from. → Harmless, because the running
copy is already in DRAM and the next boot reads the new one; and if the new
one is bad, §6 of docs/uboot-ums.md applies.every-blob-is-built-from-source-or-named lands; stage 1 is compiled from
this repository. (Done, 2026-09-22.)nix/uboot-k230.nix.
nix build .#stage1. The old stage 1 still exists in git history and in
the store.ums on hardware, capture the console into
docs/evidence/uboot-ums-hardware.txt.ums target to tools/flash-latest.sh, keeping the reader path.Rollback is writing the previous image in a reader. There is no state on the board that survives it.
ums 0 mmc 1. Answered by dm tree on the first boot of the new
stage 1; it does not change the specs, the approach or the tasks.k230_flash procedure are preserved in
successor change characterise-bootrom-usb-recovery.Task groups 1 and 5 need only the board as it stands today. Group 2 needs no board at all. Groups 3, 4 and 6 need the board and a cable to J3, the data USB-C — not the charging one that carries the console.
Group 2 onwards depends on every-blob-is-built-from-source-or-named having
landed, because until then nothing in this repository compiles U-Boot. It
landed on 2026-09-22: U-Boot is compiled by nix/uboot-k230.nix, so “the
configuration this repository builds” below means a Kconfig fragment and a
patch file that derivation applies, and “build stage 1” means nix build .#stage1. Wherever a task below still says firmware/stage1/*.bin or
PROVENANCE.txt, read the built SHA256SUMS instead; there is no committed
binary any more.
ums is absent and k230_dfu is present, which also
confirms that the source under .build/ is what is on the card.
Hardware proof.
./tools/console.py /dev/ttyACM0 --wait=3 "help ums" && ./tools/console.py /dev/ttyACM0 --wait=3 "help k230_dfu"
Done when the first says the command is unknown and the second prints
“k230 burntool enter dfu”.snps,dwc2 node today, as the
before half of the D3 question. Hardware proof.
./tools/console.py /dev/ttyACM0 --wait=3 "dm tree"
Done when the output is appended to
docs/evidence/uboot-ums-hardware.txt and shows usb-otg@91540000
bound and usb-otg@91500000 absent../tools/console.py /dev/ttyACM0 --wait=3 "usb start; usb tree"
Done when the result is in docs/evidence/uboot-ums-hardware.txt,
either way.ums arguments are not a
guess. Hardware proof.
./tools/console.py /dev/ttyACM0 --wait=3 "mmc list; mmc dev 1; mmc info"
Done when the device number and capacity are in the evidence file.CONFIG_USB_GADGET, CONFIG_DM_USB_GADGET,
CONFIG_USB_GADGET_DWC2_OTG, CONFIG_USB_GADGET_DOWNLOAD,
CONFIG_CMD_USB_MASS_STORAGE, and a vendor/product pair. Done when
CONFIG_CMD_USB_MASS_STORAGE=y appears in the generated .config.# CONFIG_USB_DWC2 is not set) and
write the reason — design.md D3 — next to it, so the next reader does
not “fix” it. Done when the comment names the binding conflict, not
just the symbol.&usbotg0 in arch/riscv/dts/k230_canmv_v3.dts to
status = "okay"; dr_mode = "peripheral";. Done when the built
device tree has usb-otg@91500000 enabled.ums is linked in. No board needed.
nix build .#stage1 && strings result/fn_ug_u-boot.bin | grep -c ums
— or, if the compressed image defeats strings, grep the U-Boot map
or .config in the build output instead. Done when the ums command
is demonstrably in the binary.nix/sd-image.nix
enforces — fn_ug_u-boot.bin has a 1 MiB slot and the gadget code
grows it. No board needed.
nix build .#sdImage
Done when the build succeeds rather than failing the slot check../tools/flash-latest.sh
Done when the board still boots Linux exactly as before — the gadget
must not have broken the normal path../tools/console.py /dev/ttyACM0 --wait=3 "dm tree"
Done when the gadget driver is bound to usb-otg@91500000 and the
evidence file says whether it also took usb-otg@91540000, settling
design.md D3.ums and confirm the host
sees a block device of the right size. Hardware proof.
board: ./tools/console.py /dev/ttyACM0 --wait=3 "ums 0 mmc 1";
host: lsblk -o NAME,SIZE,MODEL,TRAN and ls -l /dev/disk/by-id/
Done when a by-id path exists whose size matches 1.4, and both the
console and the host output are in
docs/evidence/uboot-ums-hardware.txt.
- Ticked 2026-09-22 on session 5 of docs/evidence/uboot-ums-enumerate.txt: 29f1:0230 on usb 3-4 at 480 Mb/s, /dev/disk/by-id/usb-Linux_UMS_disk_0-0:0, 249 872 384 sectors = the card. Sessions 1-4 failed because the cable’s far end was not this host; the registers said so before the phone test proved it.ums and compare it against the image that
was written in 3.1. Hardware proof.
Reworded 2026-09-22: the original check — cmp of the whole image
against the device, silent — cannot pass on a card that has booted
even once. U-Boot’s k230_set_dtb_env() calls env_save() on every
boot (board/canaan/common/k230_board_common.c:511), rewriting the
environment slot at 3 MiB, and Linux mounts both ext4 partitions
read-write. The check that replaces it, all read-only over ums:
the BootROM region [0, 3 MiB) byte-identical to the image; the five
partition-1 files (Image, fw_jump_add_uboot_head.bin, the DTB,
bootargs.txt, initrd.uimg) byte-identical via debugfs with no
mount; and every remaining byte read to the end with all differing
4 KiB blocks confined to mounted ext4 metadata and data, zero in the
gaps.
tools/ums-session.py --cmp <image>
Done when region A is identical, the five files are identical, and the
block statistics show gap=0 — docs/evidence/uboot-ums-enumerate.txt,
session 8: A identical, 5/5 identical, 5 506 differing blocks all in
p1(boot)/p2(root), gap=0, read at 12.0 MB/s.sudo dd if="$IMG" of=/dev/disk/by-id/<ums path> bs=4M status=progress oflag=direct
Done when the observed MB/s is recorded in docs/uboot-ums.md §3.tools/flash-latest.sh a ums target, keeping the card
reader as the fallback and keeping flash.sh’s by-id refusal intact.
Done when the reader path still works unchanged../tools/flash-latest.sh /dev/disk/by-id/<ums path> then reset the
board and capture the boot.
Done when docs/evidence/uboot-ums-hardware.txt holds a boot log of an
image that was written over USB.
- Ticked 2026-09-22: written by tools/ums-session.py --flash through tools/flash.sh on the by-id path, 175 s, then reset; the boot log — SPL banner and PMU training included, for the first time — is in docs/evidence/uboot-ums-write.txt, summarised at the end of uboot-ums-hardware.txt. Board hashed its own slots to the image’s bytes afterwards.BootROM recovery was not tested and is not part of this completed UMS change.
The four unperformed tests are preserved verbatim in the separate,
implementation-ready OpenSpec change characterise-bootrom-usb-recovery:
no-card fall-through, SW3/BOOT0 entry, conditional k230_flash recovery, and
spec/evidence reconciliation. Nothing here claims that path works.
Optional, and only after group 3 has settled whether it is needed.
.bind to drivers/usb/gadget/dwc2_udc_otg.c returning
-ENODEV unless dr_mode is peripheral or otg, set
dr_mode = "host" on &usbotg1, and re-enable CONFIG_USB_DWC2.
Done when the patch is a file in this repository, not a hand edit in
.build/../tools/console.py /dev/ttyACM0 --wait=3 "dm tree; usb start; usb tree"
then ums 0 mmc 1 and check the host.
Done: docs/evidence/uboot-usb-host-coexist-v2.txt and
docs/evidence/usb-host-second-candidate-linux.txt record
RTL8152 in the U-Boot host tree, UMS enumeration/readback, and return
to Linux with the shell active. This does not claim packet traffic.docs/blob-inventory.md that the configuration changed rather than the
sources — nothing enters or leaves the inventory. (Rewritten 2026-09-22:
there is no committed binary or PROVENANCE hash to refresh any more.)
nix build .#stage1 && cat result/SHA256SUMS && ./tools/blob-scan.py
Done when the hashes are in docs/evidence/ and the scan exits 0.docs/uboot-ums.md, so it reads as a record rather than a forecast.
./scripts/build_site.py
Done when the site build is green and every docs/ path cited by a
requirement is committed.
- Completed 2026-09-22: measured A1 transfer rates and repaired A2
binding/enumeration are documented, both raw hardware transcripts are
committed, and the full site build passes (55 pages, 1,100,344 bytes,
12.63 seconds). See docs/evidence/usb-host-validation.md.Stage 1 SHALL be able to present the TF card to a host computer as a USB mass storage device, over the data USB-C connector, without the card leaving the board. Writing an image SHALL NOT require a person to move the card to a reader.
Which connector and which controller this uses is a property of the board and
SHALL be recorded rather than rediscovered: the data USB-C is J3, it is
wired to the SoC’s usbotg0, and the charging USB-C J2 carries only the
CH342 console bridge and cannot be used for this.
Grounding: docs/uboot-ums.md §2. repo/schematic/T-Display K230_V1.0_NEW.pdf routes USB0_P/USB0_N to J3 pins A6/A7/B6/B7 with
USB0_ID and USB0_VBUS, and USB_P/USB_N on J2 to the CH342.
docs/evidence/hardware-boot.txt agrees: Linux registers dwc2 91500000.usb as bus 1 with nothing attached and dwc2 91540000.usb as bus 2
carrying an onboard Realtek USB 10/100 LAN. So does U-Boot itself:
docs/evidence/uboot-ums-hardware.txt, at the board’s own K230# prompt
on 2026-09-22, shows dm tree with exactly one snps,dwc2 node bound —
usb-otg@91540000, to the host driver — and usb start; usb tree finding
the RTL8152 behind it, while usb-otg@91500000 is absent because the
vendor device tree disables it. The gadget configuration is not speculative
— Canaan ships one for this SoC in the same U-Boot tree, as
k230_canmv_burntool_defconfig — and this project’s build of it
(nix/uboot-k230-ums.config, docs/evidence/uboot-ums-build.txt) puts
ums in the binary and enables usb-otg@91500000 as a peripheral.
Grounding, on hardware: docs/evidence/uboot-ums-enumerate.txt, session 5,
2026-09-22. With the card in the slot and the ums stage 1 on it, ums 0 mmc 1 at the K230# prompt made this host log usb 3-4: new high-speed USB device ... idVendor=29f1, idProduct=0230 ... Product: USB download gadget, Manufacturer: U-Boot and attach /dev/disk/by-id/usb-Linux_UMS_disk_0-0:0
as a 249 872 384-sector removable disk — the size mmc info reports for the
card and the count ums printed — with the image’s K230_BOOT and
NIXOS_SD partitions visible to lsblk. 350 046 bytes read back from its
2 MiB offset hash to bd562f2b…, the fn_ug_u-boot.bin of that build.
Four earlier sessions had failed with the core’s registers showing VBUS
valid and a bus reset received: the cable’s far end was not this machine,
which a phone on the same cable then proved. Nothing was written.
The project SHALL record which boot media this board can start from, and SHALL keep the recovery procedure for an unbootable stage 1 written down and true. A change to stage 1 SHALL NOT be able to put the board beyond recovery by rewriting its card.
Grounding: docs/uboot-ums.md §6. The schematic’s strap table reads BOOT0=0, BOOT1=0 SPI Nor / BOOT0=0, BOOT1=1 eMMC / BOOT0=1, BOOT1=0 SPI Nand /
BOOT0=1, BOOT1=1 SD Card, and the board sits at 1,1. No SPI NOR or NAND
part appears anywhere in the schematic — the OSPI_* pins carry IO16_MOSI
and IO19_BUSY, the LoRa radio. docs/findings.md records MMC0 as the
RTL8189FTV SDIO radio and MMC1 as the TF card, so there is no eMMC. LilyGO’s
own product table lists this board’s FLASH as “SD Card”. A third-party wiki
claiming onboard SPI NOR also claims the Wi-Fi is an ESP32-S3 co-processor,
which docs/findings.md already records as contradicted by the schematic.
Archived change · Archived
Snapshot 5836ef1d113d · 2026-10-17 08:22 UTC
Closed recordReview the archived record and cited scope
The board has no usable network path. The current system exposes the SDIO radio to the kernel but no wireless interface, and its image lacks the tools needed to inspect or join a network. Evidence can be recovered through U-Boot UMS, but that card-transfer workflow and the host tether do not provide a usable network path for the board itself.
This is timely because the committed, sanitized
docs/evidence/wifi-preflight.txt records an SDIO function without a wireless
driver binding. That evidence establishes a missing bring-up path, not that
the radio works; the first hardware task records the driver decision before
changing the system.
radio/wifi capability for a system that can enumerate its wireless
interface, join a WPA network from a runtime-only secret, obtain a lease,
and demonstrate routing and DNS.Non-goals. This does not add Ethernet, cellular, an access point, a network UI, saved credentials in Nix, or a claim that the shipped RT-Smart radio stack works. It does not change stage 1, panel, touch, AtomVM, or Dozer.
Needs the physical board. Package and kernel-module configuration can be audited and cross-built on the host, but QEMU models neither this SDIO radio nor its power gate. Only a board can prove enumeration, association, DHCP, DNS, or packet delivery.
radio/wifi: credential-safe wireless diagnosis, runtime connection, and
evidence of usable network connectivity on the physical board.None.
iw, WPA supplicant, and regulatory data; the
existing DHCP client remains part of the connection path.docs/evidence/ after a real attempt.The board routes its RTL8189FTV radio through SDIO. The current Xuantie 6.6.36
kernel configuration has generic wireless and MMC support, but its source and
module set do not include an RTL8189 SDIO driver. A private physical-board
preflight observed an SDIO function with no bound driver, no ieee80211
object, no wireless interface, no iw or WPA command-line tools, and no
regulatory database. The existing DHCP client is present and runs. The sanitized evidence added with this proposal records
that gap. It is not proof of association or connectivity.
The device tree enables the SDIO controller but declares no separate radio power regulator. Because the SDIO function enumerates, the initial work must distinguish a missing driver from a power or board-routing fault before changing power control. Vendor material names an RTL8189ES Linux driver tree, but its exact compatibility, license, source revision, and module name still require an audit.
The NixOS image is cross-built for riscv64. Host evaluation and a cross-build can show that a closure includes selected packages or a module; only the board can establish driver binding, association, DHCP, DNS, or packet delivery.
Goals:
Non-Goals:
First audit the exact SDIO modalias against the current kernel source, configuration, and the vendor RTL8189ES source. Select a source only if it has a reviewable license and can be pinned by immutable revision and Nix hash. Build it against the exact board kernel and record its module name and firmware requirements. The private preflight makes a missing driver the leading cause, but an audit must still rule out a wrong compatible-ID table or an independent power requirement.
Once the driver decision is made, add only the diagnostic and connection
programs needed on the console: iw, wpa_supplicant/wpa_cli, regulatory
data, and one DHCP client selected during the NixOS package audit. These tools
are absent from the current board image. A module load and iw dev check come
before any association attempt.
The board operator creates the protected network configuration by a private
runtime procedure and makes its file readable only by root. Tracked commands
refer only to RUNTIME_SECRET_FILE and YOUR_SSID; they never show a real
network identifier or secret-file contents. The procedure must avoid putting secret contents in shell history, command
arguments, system configuration, the Nix store, or a captured terminal log.
A harmless pathname can name RUNTIME_SECRET_FILE; wpa_supplicant receives
the protected file from /run after its permissions are checked.
The initial connection is deliberately imperative so that driver and network failures are visible separately. A later persistent option is chosen only after it works: a systemd credential delivery mechanism or an equivalently root-controlled runtime file. Declarative wireless network definitions are rejected because embedding a protected-network secret would copy it into the Nix store.
For the physical-board operator, the minimal non-secret command shape is:
install -m 0600 "$RUNTIME_SECRET_FILE" /run/wpa-supplicant-board.conf
wpa_supplicant -B -i "$WIFI_IFACE" -c /run/wpa-supplicant-board.conf
dhcpcd -4 -w "$WIFI_IFACE"
ip route show default dev "$WIFI_IFACE"
RESOLVER_IP="$(awk '/^nameserver/{print $2; exit}' /etc/resolv.conf)"
ip route get "$RESOLVER_IP" | grep -F "dev $WIFI_IFACE"
getent ahostsv4 "$TEST_DNS_NAME"
ping -4 -c 3 -I "$WIFI_IFACE" "$TEST_IP"
RUNTIME_SECRET_FILE is prepared privately by the operator and is never
printed, recorded, or supplied as an argument. WIFI_IFACE, TEST_DNS_NAME,
and TEST_IP are discovered or selected at runtime. Cleanup terminates the
supplicant and removes the copied /run file.
The operator validates an associated interface in this order: interface and association state, IPv4 address, default route bound to that interface, a route lookup for the selected resolver that resolves through that interface, a DNS lookup of an operator-supplied test name, and a reachability probe bound to the interface and aimed at an operator-supplied test IP. This prevents a second interface from masking Wi-Fi DNS failure and separates radio failure from DHCP, routing, DNS, and upstream failure.
Raw scans, WPA logs, status output carrying network names or BSSIDs, secret files, and DHCP output with local addressing are not evidence artifacts. Before committing, the operator reduces outputs to the relevant pass/fail state, driver/interface information, and redacted identifiers. A failed stage is evidence of that failure only; it never becomes a connectivity claim.
/run
file. Restore the known-good image through the established recovery
procedure for the custom hard-coded-DTB boot path; do not assume NixOS
generation rollback is available. No persistent network configuration is
introduced before a successful live validation.docs/evidence/wifi-preflight.txt with the exact 6.6.36 kernel source, configuration, loaded-module set, and the vendor RTL8189ES source; record the selected driver, compatible-ID support, license, immutable source revision, kernel API compatibility, and firmware requirement. Verify the audit cites each source and does not claim a bound board driver.k230-wifi-driver derivation for the audited driver and verify it with the narrow nix build .#k230-wifi-driver; coordinate any later system-image build separately, because a successful module build is not radio proof.iw, wpa_supplicant, wpa_cli, and regulatory data while retaining the existing DHCP client to the system closure; verify their paths with a narrow Nix evaluation and inspect the closure for no protected-network material.RUNTIME_SECRET_FILE, WIFI_IFACE, and YOUR_SSID placeholders only; verify the procedure passes the configuration file from /run with mode 0600 and never places a secret in argv, source control, or Nix configuration.iw dev, and regulatory state before any scan or connection attempt; commit only sanitized evidence and verify it omits MAC addresses, access-point identifiers, local addresses, and terminal control sequences.wpa_supplicant for the discovered WIFI_IFACE from RUNTIME_SECRET_FILE; verify association with a sanitized state result and remove the runtime secret on failure or cleanup. Do not record the invocation with a real network identifier or secret.WIFI_IFACE using the selected DHCP client; verify a sanitized board record distinguishes successful address assignment from DHCP failure without exposing the assigned address.ip route get result uses WIFI_IFACE, then run getent ahostsv4 "$TEST_DNS_NAME" and ping -4 -c 3 -I "$WIFI_IFACE" "$TEST_IP"; commit sanitized evidence that records each stage’s result, not raw network identifiers or addresses./run; record a sanitized result in docs/evidence/.2026-09-22: docs/evidence/offline-wifi-image/README.md records the first
physical driver bind, runtime regulatory setup, protected one-off association,
DHCP, Wi-Fi resolver routing, DNS, interface-bound outbound delivery, shell
regression and secret cleanup. Persistent credential delivery and reboot
reconnection remain open; no network material enters declarative configuration.
2026-09-22: docs/evidence/wifi-persistent/README.md completes task 4.2.
The source-built image and service booted on the board; after private
provisioning, a second boot automatically passed all six network stages.
The systemd credential source remains root-owned 0600 outside the Nix store.
Defines credential-safe wireless diagnosis and connection behavior that the physical board must demonstrate before it is treated as network-capable.
Grounding: docs/evidence/offline-wifi-image/final-readiness.txt records bound RTL8189 SDIO radio, wlan0/wlan1 and regulatory state on the physical board.
The system SHALL provide the radio driver, regulatory data, and diagnostic
commands needed for an operator at the console to determine whether the board
has a wireless interface, its driver, and its regulatory state without
scanning for or naming access points. The physical board owns proof of this
requirement; a host build only proves that the closure contains the selected
components.
Grounding: docs/evidence/offline-wifi-image/final-wifi-network.txt records association COMPLETED; docs/evidence/offline-wifi-image/README.md records the root-only runtime handoff and wifi-cleanup.txt records cleanup.
The system SHALL allow the board operator to supply a protected-network
configuration at runtime from a root-readable secret file and use it to
associate. The system MUST NOT place a network name, passphrase, derived PSK,
or secret-file contents in the Nix store, tracked configuration, command-line
arguments, or committed evidence.
Grounding: docs/evidence/offline-wifi-image/final-wifi-network.txt separately records DHCP, Wi-Fi default/resolver routes, DNS and interface-bound outbound ping on the physical board.
After association, the system SHALL let an operator verify address assignment,
default routing through the wireless interface, confirmation that the selected
resolver routes through that interface, DNS resolution, and an
interface-bound outbound reachability check as distinct stages. Physical-board
evidence MUST redact access-point identifiers and locally assigned addresses
before it is committed.
Grounding: docs/evidence/wifi-persistent/after-reboot-identity.txt records a new boot and root-owned mode-0600 credential; docs/evidence/wifi-persistent/after-reboot.txt records automatic association, DHCP, Wi-Fi routing, DNS and bound ping without re-provisioning.
If the operator elects to persist wireless configuration after a successful
live connection, the system SHALL consume the credential through a
root-controlled runtime credential mechanism rather than embedding it in Nix
source, generated world-readable configuration, or the system closure.
Archived change · Archived
Snapshot 5836ef1d113d · 2026-10-17 08:22 UTC
Closed recordReview the archived record and cited scope
The launcher now proves the shell can discover and start installed desktop entries, but a fresh image still offers too little useful offline software and no in-device explanation of the controls. The next increment should give a person a small, predictable set of portrait-friendly tools and a Help page without turning the shell into a general desktop or adding a network-dependent installer.
runtime/shell: Adds a bounded offline app set and keyboard-free Help surface to the portrait shell.The change affects the shell Nix package set, desktop-entry exposure, launcher cards, and evidence tasks. Candidate packages must work with the pinned riscv64 cross build, 568x1232 portrait layout, Pixman rendering, 1 GiB RAM, and existing Foot terminal profile. The board is needed for physical touch and reboot evidence; package closure and isolated desktop-entry fixtures can run on the host; startup and injected panel workflow checks require the physical board.
The existing shell owns a GLib desktop catalog and a native Wayland launcher. The new capability adds userspace packages and launcher content in the Nix layer; it does not change stage 1, the kernel, the device tree, or the compositor. The display is 568x1232 portrait with Pixman rendering and a 1 GiB target, so every candidate needs measured cross-build and runtime evidence.
Goals:
nano as the first editor candidate and compare lf (Go) with the lighter C-based nnn as a file
browser candidate, with an already-present terminal utility as fallback when
either candidate fails the riscv64 or closure checks.Non-Goals:
Keep selection bounded and evidence driven. Start with nano as the editor
candidate; measure the Go closure of lf against the lighter C-based nnn
before selecting either file browser;
confirm their actual pinned riscv64 derivations and closure costs before choosing
them. If either fails, retain the existing shell and select only a package that
already satisfies the measured budget. This avoids committing to a Python or GUI
file manager solely because its desktop entry is attractive.
Represent terminal tools as normal desktop entries. The Nix layer owns
package inclusion and a minimal .desktop entry with Terminal=true; the
existing GLib launcher owns discovery, visibility rules, Exec expansion, and
terminal selection. Do not add raw command parsing or a second hardcoded app
catalog.
Make Help launcher-owned. Help is a built-in page/card, not a package or a desktop entry. It uses the same SHM/Pango rendering and touch release handling as the launcher, with Back and paging targets. This keeps Help available offline even if application discovery is empty.
Use a compact content contract. Help text names each persistent control and the launcher actions in short lines sized for portrait cards. It must explain that Previous/Next paginate apps and that Back returns to the prior surface. Avoid implementation terms, network instructions, and claims about unverified hardware behavior.
Validate at four boundaries. Host checks cover evaluation, cross-build, desktop file validation, and closure delta. Image checks cover startup and catalog appearance. Injected board checks cover Help paging and candidate launch/return. Physical finger, reboot, and panel legibility remain separate evidence owned by the hardware integration work.
Add the selected packages and Help card behind the existing shell image option. Build and inspect the closure before flashing. If a candidate fails, remove its package and desktop entry without changing the existing launcher contract. If the Help card fails, revert only its built-in page and retain Apps, Terminal, Monitor, and Back.
None that change the bounded approach; candidate acceptance is determined by the recorded checks in the task list.
nano, lf, and nnn against the pinned riscv64 package set, record desktop IDs, package derivations, and whether each builds without adding an unsupported toolchain; verify with the narrow Nix evaluation command and saved JSON evidence.Terminal=true and the existing Foot bridge; verify k230-desktop-catalog list discovers each ID and k230-desktop-catalog launch ID preserves the configured terminal environment.python3 tests/test_touch_menu.py, python3 tests/test_desktop_catalog.py, and openspec validate the-shell-offers-offline-apps-and-help --strict.For task 1.1, run for each candidate (substitute lf or nnn for nano):
nix eval --raw --impure --expr '(builtins.getFlake (toString ./.)).nixosConfigurations.k230.pkgs.nano.drvPath'.
For task 3.1 use nix build --impure --expr '(builtins.getFlake (toString ./.)).nixosConfigurations.k230.pkgs.nano' --option max-jobs 1 --option cores 8 --option substituters https://cache.nixos.org;
coordinate the builder slot first. Measure nix path-info -S and the closure
set difference against the recorded current system. These are host claims.
Task 3.2 uses nix build .#sdImage with the same coordinated limits.
Task 3.3 and startup/memory observations in 1.2 require the physical board;
a host process or QEMU cannot prove this panel workflow.
2026-09-22 progress: host candidate outputs/desktop IDs and closure differences
are in docs/evidence/offline-app-candidates/; the injected physical-board Help,
error recovery, nano and nnn trials are in docs/evidence/offline-help-injected/.
The final lf board trial records startup and 8,576 KiB RSS, completing task 1.2;
it remains rejected in favor of nnn on closure size and observed memory. Fresh-image integration, boot, catalog discovery and injected launches are
recorded in docs/evidence/offline-wifi-image/README.md. Navigation tests include python3 tests/test_launcher_navigation.py.
The shell SHALL expose Help and the existing Terminal action through the portrait Apps flow. It SHALL add only a small, explicitly reviewed set of portrait-usable desktop entries selected from packages that build for the pinned riscv64 image and fit the measured closure and startup budgets. An editor and a file browser are preferred candidates when an existing dependency satisfies those constraints; the image SHALL not gain a network installer, package manager UI, AtomVM, Dozer, or a general desktop suite for this capability.
Grounding: Package builds, measured closure differences, fresh-image discovery
and injected launches are recorded in docs/evidence/offline-wifi-image/README.md
and docs/evidence/offline-app-candidates/selection.md.
The shell SHALL provide an offline Help surface reachable from Apps and SHALL describe the purpose and action of Apps, Keyboard, Windows/Home, System, Back, paging, and the terminal and monitor actions. Help SHALL be readable at 568x1232 in portrait mode, support touch navigation back to Apps, and avoid requiring a network, physical keyboard, or text entry.
Injected paging, readable native portrait layout, Back and launch-error recovery
are recorded in docs/evidence/offline-wifi-image/README.md and
docs/evidence/offline-help-injected/README.md.
Before an app is added to the image, the project SHALL record its desktop ID, package source, riscv64 build result, closure delta, startup result, and injected portrait touch result. Physical finger accuracy, reboot persistence, and final glass readability SHALL remain separately labelled evidence rather than inferred from host or injected checks.
Grounding: The package comparison and hardware trials are recorded in
docs/evidence/offline-app-candidates/selection.md and
docs/evidence/offline-wifi-image/README.md.
Archived change · Archived
Snapshot 5836ef1d113d · 2026-10-17 08:22 UTC
Closed recordReview the archived record and cited scope
a-riscv-nixos-closure-cross-builds gets an image to a prompt under emulation.
That proves the closure builds; it proves nothing about the board, because
QEMU’s k230 machine loads a kernel directly and the real hardware does not.
On the board a vendored chain runs first — BootROM, U-Boot SPL with its DDR
training blob, U-Boot, then OpenSBI — and only then is anything of ours
loaded.
Until our own image boots on the actual device, every plan after this one is speculative. This is the change where the project stops being a build exercise.
A bootable SD image, laying our kernel, initrd and rootfs alongside the vendored stage 1 so the board’s existing chain finds and loads them.
The vendored stage-1 firmware is pinned as an artifact, with its origin and how it was obtained recorded. The seam declared in the previous change gets filled with something specific.
The board reaches a console prompt over /dev/ttyACM0, and the
transcript is committed. That transcript is the evidence for every hardware
claim this repository makes afterwards.
A flashing procedure that names the target device unambiguously. The
development machine has four 8 TB RAID members on /dev/sd[a-d]; a dd to
the wrong node is unrecoverable. The procedure uses /dev/disk/by-id.
The difference between the QEMU boot and the hardware boot is written down, because that gap is where the next failure will live.
A kernel that can boot this SoC. Added after proposing, because the
plan assumed one already existed. It does not: mainline Linux ships no
K230 device tree and no SOC_CANAAN_K230, so the kernel from the previous
change has nothing to boot with on this board. We build the Xuantie tree
Canaan’s own Linux SDK pins, from source — not as a vendored binary.
Non-goals. The panel, touch, or backlight — the board can boot headless and
the screen is the-screen-comes-up-under-linux. Either radio. Building stage 1
from source; it stays vendored. Booting from anything but an SD card.
image/boot-chain: what runs before our kernel, what is vendored, and how
our kernel is handed control.image/sd-layout: what is written to the card, where, and how the card is
produced without endangering the host.system/console: how a person talks to this board, on hardware.system/nixos-config: the system’s boot requirement currently speaks only of
emulation. It gains a hardware obligation, and its stage-1 requirement is
grounded against a real vendored artifact rather than a boot log from the
shipped firmware.Adds an SD image derivation and a vendored stage-1 input to the flake. Adds a
flashing script under tools/.
Destroys the contents of the target SD card. The card currently in use was previously an EverDrive 64 cartridge card; the procedure this change establishes must make the target impossible to mistake.
Requires physical access to the board and a known-good USB-C data cable —
docs/findings.md records that a charge-only cable produces total silence and
a marginal one produces error -71, and that both look like a dead board.
See proposal.md — Why. What constrains the approach:
U-Boot SPL 2022.10 → U-Boot 2022.10 → OpenSBI v0.9,
with a DDR PHY training blob inside SPL and a Canaan-specific compressed image
header. All observed in docs/rtsmart-boot-log.txt.Model: kendryte k230 canmv v3.0, and k230_linux_sdk carries
a matching k230_canmv_v3_defconfig with BR2_TARGET_UBOOT_BOARDNAME="k230_canmv_v3".
The board is a CanMV v3 derivative, which is why an official Linux path exists
at all.Goals:
Non-Goals:
Take stage 1 from k230_linux_sdk’s k230_canmv_v3 build, not from the
LilyGO RT-Smart image. Both would probably boot a kernel, but the RT-Smart
image’s U-Boot is configured to load an RT-Smart payload from a raw offset,
while the Linux SDK’s is configured to load a kernel from a filesystem. Taking
the one already aimed at our case avoids reverse-engineering boot arguments.
The cost is one buildroot run in Docker on Ubuntu, once.
Pin stage 1 by content hash as a fixed-output derivation. The alternative, committing the binary into the repository, was rejected: it is several megabytes of opaque vendor output, and a hash plus a recorded provenance says more about where it came from than a checked-in blob does.
Flash by /dev/disk/by-id, and refuse bare device nodes. The host has four
8 TB RAID members at /dev/sd[a-d] and device letters move when the card
reader is replugged. Accepting /dev/sdX at all — even with a confirmation
prompt — leaves a one-character typo between a working session and a destroyed
array. Refusing the form outright is worth the small inconvenience.
Show the card’s contents before writing. Rejected doing this only on a
--force flag. The card in hand was an EverDrive 64 cartridge card holding
306 ROMs, and “the blank one” is exactly the assumption that loses data.
Reuse the existing console tooling rather than writing new. tools/console.py
and tools/probe.py already speak to this board; the boot capture pattern in
tools/bootcap.py produced docs/rtsmart-boot-log.txt. They need retargeting
at a Linux console, not replacing.
Whether U-Boot needs a Resolved 20 September 2026: fixed filenames, and it is none of
the three options as posed. The SDK’s boot.scr, an extlinux config, or a fixed
filename.default.env runs a hardcoded
blinux command that ext4loads exactly /fw_jump_add_uboot_head.bin,
/Image and /force.dtb from the first partition of mmc 1, then bootms
the OpenSBI payload. It never calls sysboot, so extlinux is not read at
all. Full text in docs/evidence/uboot-env.txt.
This invalidated nix/hardware.nix as written in the previous change, which
had enabled generic-extlinux-compatible. Rewritten to configure no
bootloader: the image derivation places the three files stage 1 expects.
The cost, recorded rather than hidden: one kernel on the card, so NixOS
generations cannot be chosen at boot. Recoverable later by rewriting the
U-Boot environment — which is plain data at 3M and 3.5M, separate from the
SPL and U-Boot binaries — to run sysboot. Deferred until something boots,
because a bringup failure and a bootloader misconfiguration are
indistinguishable from a dark screen.
Task groups here make hardware claims unless they say otherwise. A QEMU run
proves nothing in this change — QEMU’s k230 machine models neither the
vendored boot chain nor the SD card.
Group 2 was added after the change was proposed. The plan assumed the
kernel from a-riscv-nixos-closure-cross-builds could boot this board. It
cannot: mainline ships no K230 device tree and no SOC_CANAAN_K230, so a
stock nixpkgs kernel has nothing to boot with. The Xuantie kernel was going
to be the-screen-comes-up-under-linux’s work; it is pulled forward here
because nothing in groups 4 and 5 is reachable without it. The panel and
touch remain that change’s job.
k230_linux_sdk with k230_canmv_v3_defconfig in Docker on Ubuntu 22.04, and keep the firmware stage. Verify by recording the SDK commit, the defconfig, and the sha256 of the artifact in docs/evidence/stage1-provenance.txtnix build .#stage1.verified and confirm the hashes match what was recordeddocs/evidence/uboot-env.txtruyisdk/linux-xuantie-kernel at the revision k230_canmv_v3_defconfig pins, built from source with k230_defconfig plus the options NixOS requires. Verify with nix build .#packages.x86_64-linux.kernel and confirm Image is producedls $(nix build --no-link --print-out-paths .#packages.x86_64-linux.kernel)/dtbs/canaan/ showing k230-canmv-v3.dtbdocs/evidence/why-xuantie-kernel.txtgenimage.cfg, and a boot ext4 carrying the three filenames task 1.3 found U-Boot loads. Verify with nix build .#sdImage and fdisk -l on the result showing the documented layouttools/flash.sh taking only a /dev/disk/by-id path, refusing bare device nodes, and printing the card’s current contents before writing. Verify by running it against a bare /dev/sdX and confirming it refuses, and against a by-id path with the write declineddocs/evidence/hardware-boot.txt and confirming stage 1 hands off to our kernelcat /proc/cpuinfo showing a thead,c908 hart
- Clause corrected during implementation. It originally read “showing
two C908 harts”, written from the datasheet before anything had
booted. The SoC does have two C908s, but no K230 device tree declares
a cpu@1 — every cpu@1 under dts/canaan belongs to the K210 —
so Linux sees one hart and the second core is Canaan’s AMP core for
RT-Smart. No spec delta in this change asserted a hart count, so this
corrects a verification instruction, not a requirement.
Evidence: docs/evidence/hardware-userspace.md — uarch: thead,c908,
mvendorid: 0x5b7, run at a root prompt on the board.docs/evidence/boot-path-differences.md, citing both transcriptsUNVERIFIED markers in image/boot-chain and image/sd-layout against the committed hardware transcript, or restate what remains unproven. Verify with openspec validate the-board-boots-what-we-builtsystem/nixos-config boot requirement is met on hardware and cite the transcript path from it. Verify with openspec validate --allDefines what executes before our kernel on this board, which parts are vendored, and how control reaches the system we built.
The boot chain before our kernel SHALL be a vendored binary, pinned by content hash, with its origin recorded — which SDK, which board configuration, and how it was produced. It SHALL NOT be built from source by this project.
Grounding: docs/rtsmart-boot-log.txt records the chain on this board:
U-Boot SPL 2022.10, the DDR PMU training messages, U-Boot 2022.10, and
OpenSBI v0.9. Canaan wraps these in a custom header with compression
(image: uboot load to 20000000 compress =1).
Grounded on hardware. The vendored chain loaded our kernel, our device tree
and our initrd from the card and reached userspace: uname -a on the board
reports Linux nixos 6.6.36 #1-NixOS ... riscv64
(docs/evidence/hardware-userspace.md). Stage 1 itself was not modified; the
two things it required of us were recorded rather than rediscovered — the
literal filenames its blinux variable ext4loads, and the fact that the
kernel command line comes from the U-Boot environment and not from
/chosen/bootargs (docs/evidence/stage1-emergency-mode.md).
The vendored chain SHALL load the kernel, device tree and initrd this project builds, from the SD card, without modification to stage 1 itself. Where stage 1 requires a particular filename, location or image format, that requirement SHALL be recorded as a property of the vendored artifact rather than discovered again each time.
Grounding: docs/evidence/boot-path-differences.md records the comparison,
started during a-riscv-nixos-closure-cross-builds. Two differences are
already observed rather than anticipated: QEMU’s k230 machine models no
block device, and it generates no FDT at all (dumpdtb answers “This machine
doesn’t have an FDT”).
Under QEMU the kernel is loaded directly; on hardware it is loaded by vendored U-Boot. The project SHALL record what differs between the two paths, so that a failure on hardware after a success under emulation is diagnosed against a written expectation rather than from memory.
Defines what is written to the SD card and how a card is produced without endangering the machine producing it.
Grounded on hardware. Our layout has now been written to a card and booted:
stage 1 raw at 1M and 1.5M, U-Boot at 2M, environment at 3M and 3.5M, the boot
ext4 at 4M and the root ext4 at 128M. The board boots from it and mounts /
from /dev/mmcblk1p2 (docs/evidence/hardware-userspace.md). One size in the
list is empirical rather than chosen: the boot partition is 112 MiB because
83 MiB of content did not fit the original 80.
The card SHALL carry the vendored stage 1 and the system this project builds in documented regions, and the layout SHALL be recorded as offsets and sizes rather than implied by a tool’s defaults.
Grounding for the shipped layout, read from the vendor image: raw boot
firmware occupies sectors 0 through 102399; partition 1 begins at sector 102400
and is 30 MB of FAT32 labelled BIN; partition 2 begins at sector 163840 and
is 500 MB of FAT32 labelled SDCARD.
Grounding: observed on this host. The card reader presents two slots as
/dev/disk/by-id/usb-Generic-_USB3.0_CRW_-SD_201506301013-0:0 and -0:1,
while /dev/sda through /dev/sdd are the four 8 TB members of the RAID10
array. Device letters were seen to move across a replug of the reader during
this session.
The flashing procedure SHALL identify the target by a /dev/disk/by-id path,
not by a kernel device node.
This is not stylistic. The development host carries four 8 TB RAID members on
/dev/sda through /dev/sdd, device letters are reassigned when a reader is
replugged, and a dd to the wrong node destroys the array. A by-id path can
only ever resolve to the one reader slot.
The procedure SHALL also show what is on the card and require confirmation before writing, because a card that looks blank may not be.
/dev/sdX instead of a by-id pathDefines how a person reaches a prompt on the physical board.
The board SHALL present its console on the CH342 USB-UART bridge, on the charging USB-C port, at 115200 8N1 with no flow control.
Grounding: observed on this board. The bridge enumerates as 1a86:55d2
“USB Dual_Serial” and is handled by the in-kernel cdc-acm driver with no
vendor driver installed, giving /dev/ttyACM0 (CH342 channel 0, K230 UART0)
and /dev/ttyACM1 (channel 1, UART3). docs/rtsmart-boot-log.txt was captured
this way.
No vendor driver SHALL be required on the host. The CH342 is CDC-ACM
compliant, and installing WCH’s ch343ser driver would displace cdc-acm
rather than help.
The project SHALL record how a cable fault presents, because on this hardware it is indistinguishable from failure by eye — the charge LED lights either way.
Grounding: observed. A charge-only cable produces no kernel USB events
whatsoever. A marginal cable produces device descriptor read/64, error -71
followed by unable to enumerate USB device. A working cable enumerates
1a86:55d2 cleanly.
Grounded on both halves. QEMU: docs/evidence/qemu-boot.txt. Hardware: a
root prompt was reached on the board over the CH342 serial console at 115200
8N1, with no display, no keyboard and no network, and commands were run at it
(docs/evidence/hardware-userspace.md). The transcript format is shared, as
the requirement intends.
The system SHALL boot to an interactive console prompt on the serial console without a display, a keyboard, or a network.
The console SHALL be the serial console at 115200 8N1, matching the board’s CH342 bridge, so that one transcript format serves both QEMU and hardware.
This SHALL hold on the physical board, not only under emulation. A boot
under QEMU’s k230 machine is not evidence for this requirement, because that
machine models neither the vendored boot chain nor the SD card the board loads
from.
k230 machine/dev/ttyACM0, and that transcript is committed as evidenceArchived change · Archived
Snapshot 5836ef1d113d · 2026-10-17 08:22 UTC
Closed recordPower the board with a known-good data cable and capture the console. Verify by committing docs/evidence/stage1-from-source.txt containing the PMU Major Msg: training sequence and U-Boot 2022.10 from a…
Nobody can say what this board runs. The chain that executes before our kernel is 570 KB of committed binary, and the honest answer to “what is in it?” is currently “U-Boot, probably, plus something that trains the memory”. A person who wants to change how the board boots — to get NixOS generations back at the boot menu, to raise a memory timing, to put a splash on the panel before Linux starts — cannot, because the thing that would have to change is not a file they can edit. A person who wants to know what unauditable code runs on their device cannot be told, because nobody has counted.
Worse, the build that produced those binaries executed a stripped vendor executable to do it. We ran an unreadable 110 KB program from Canaan and shipped what came out.
Both are fixable, and most of the way more cheaply than anyone assumed. What is not fixable has to be named, once, in a place a future reader can check, because a blob nobody remembers is indistinguishable from a blob nobody chose.
kendryte/k230_linux_sdk, both open. BREAKING against
image/boot-chain, which today requires the opposite.k230_priv_gzip executable leaves the build. It is GNU gzip
1.6 with the version string filed off, and nixpkgs gzip produces
byte-identical output; this was measured, not assumed.docs/blob-inventory.md lands as a standing artifact: every opaque
binary this project ships, executes, or is one defconfig line from pulling
in, with its sha256, what would make it go away, and whether it is a property
of this chip, this vendor, this board, or of the industry.fw_jump pair was committed for the same good reason as the others.0x1fc74, and
building U-Boot from source does not remove it — it only means we compile it
ourselves. The current spec language implies stage 1 is opaque because it is
vendored. It is the other way round: almost all of it is open, and one small
part of it will never be.Non-goals. Removing the DDR PMU firmware, which is a person-years research project nobody has completed for any Synopsys PHY. Building the Linux kernel, the NPU stack, or any radio firmware — those blobs get inventoried, not excised. Changing the SD layout or the boot command; stage 1 is rebuilt to do exactly what the committed one does. Reviving RT-Smart. Packaging the Xuantie toolchain for Nix — the point is to stop needing it.
Hardware. Most of this needs no board. Building stage 1 in Nix, proving gzip equivalence, reproducing the packaging, and the inventory check are all laptop work, and the first three are already done or nearly so. Exactly one task needs the board: booting a stage 1 that we compiled, which cannot be proven any other way because the DDR training runs before there is a console.
image/vendor-blobs: what opaque binaries an image carries or its build
executes, which of them are unavoidable and why, and how a new one is
prevented from arriving unnoticed.image/boot-chain: its first requirement currently reads “Stage 1 is a
pinned vendored artifact” and states that stage 1 SHALL NOT be built from
source by this project. That reverses. The capability also gains the
obligation to name what stays opaque inside the stage 1 we build.Adds a U-Boot derivation and an OpenSBI derivation to the flake and removes
all five committed binaries under firmware/stage1/ — the SPL, the compressed
U-Boot, the environment, and the fw_jump pair that landed on 2026-09-20
while this was being drafted.
Rewrites nix/stage1.nix, whose vendored = true / builtFromSource = false
contract is exactly what this change inverts, and retires tools/gen-stage1.sh
and its Docker dependency. Adds tools/blob-scan.py and wires it into
./scripts/build_site.py.
This lands on top of the-board-boots-what-we-built, which is in flight and
owns image/boot-chain. That capability is not yet in openspec/specs/;
the delta here is written against the requirement text in
openspec/changes/the-board-boots-what-we-built/specs/image/boot-chain/spec.md
and assumes that change archives first. If it does not, the two must be merged
by hand rather than both applied.
One correction to something already committed. tools/gen-stage1.sh
reproduces the SDK’s gen_uboot_bin() but omits the sed -i -e "1s/\x08/\x09/" that post-image.sh applies immediately after compression.
That byte is how the SPL is told to use the SoC’s hardware decompressor, and
the committed fn_ug_u-boot.bin does not carry it, so the board will take the
software path instead. It should still boot. It is not what the vendor ships,
and it was an accident rather than a decision.
See proposal.md — Why. What constrains the approach:
firmware/stage1/fw_jump.bin and
fw_jump_add_uboot_head.bin were committed on 2026-09-20 while this change
was being drafted, taking the committed count from three to five. Each
addition is individually well reasoned; that is how the count grows..build/k230_linux_sdk is a checkout
of kendryte/k230_linux_sdk at 1104236, BSD-2-Clause. Canaan’s U-Boot
changes are not a patch series but a directory rsynced over vanilla
u-boot-2022.10 (UBOOT_OVERLAY_DIRS, buildroot-overlay/boot/uboot/uboot.mk:581).
Nothing has to be reverse-engineered.docs/blob-inventory.md §D.
Only compilation remains vendor-bound.readelf -A on the built SPL reports
rv64i2p1_m2p0_a2p1_c2p0_zicsr2p0_zifencei2p0_zmmul1p0. The T-Head cache
operations in arch/riscv/cpu/k230/cache.c are hand-encoded
(asm volatile(".long 0x0295000b") /* dcache.cpa a0 */) and the vendor
CSRs are written by number. Nothing needs the Xuantie assembler.0x1fc74. It arrives as C, so building
from source compiles it rather than removing it.image/boot-chain is owned by an in-flight change. It is not yet in
openspec/specs/; the-board-boots-what-we-built holds it. The delta here
is written against that change’s text and assumes it archives first. This is
a sequencing constraint, not an unknown.Goals:
nix build, from sources pinned by hash, with no Docker
and no vendor toolchain.Non-Goals:
Build stage 1 as an ordinary derivation, not a fixed-output one.
the-board-boots-what-we-built’s design chose a fixed-output derivation;
firmware/stage1/PROVENANCE.txt then chose committed binaries on the grounds
that a fixed-output derivation needs a URL and these were built locally. Both
are answers to the wrong question. A hash over an opaque artifact records that
it has not changed, not what is in it. An ordinary derivation over pinned
sources records both. Layer: Nix.
Vendor the packaging script, not the packaging binary.
firmware_gen_no_securiy.py — the thing that applies the K230 header — is
about 100 lines of readable Python inside the U-Boot tree, and it is already a
source input. Use it as-is. Rejected: reimplementing the header format in Nix.
It is simple enough to reimplement and that is exactly the trap: a subtly
different SHA-256 field produces a BootROM that refuses the image with no
console output to say why, and the bug would look like a DDR failure.
Layer: Nix, over vendor source.
Restore the sed -i -e "1s/\x08/\x09/". The vendor’s pipeline flips the
gzip header’s CM byte to 0x09 so the SPL decompresses U-Boot with the SoC’s
ugzip DMA engine rather than in software. tools/gen-stage1.sh omits this and
the committed fn_ug_u-boot.bin carries 0x08. Both paths are linked into
the SPL (nm shows zunzip and k230_priv_unzip) so the software path
should work, but it is not the path the vendor ships or tests, and “should
work” is how the next hour gets spent. Match the vendor. Rejected: adopting
the software path deliberately — defensible, and cheaper to reason about, but
it would be the first place to look after any SPL hang and it buys nothing.
Layer: stage 1 packaging.
Replace k230_priv_gzip with pkgs.gzip, and keep the proof. It is GNU
gzip 1.6 with the name changed; output is identical on the real u-boot.bin
at every level the SDK tries. Record the comparison as evidence rather than a
claim, because the whole argument for the substitution is empirical. Rejected:
keeping the vendor binary and pinning its hash. Pinning the hash of an
unreadable program only guarantees that we keep running the same unreadable
program. Layer: Nix.
Compile with pkgsCross.riscv64, and be willing to pin an older GCC.
U-Boot 2022.10 against nixpkgs GCC 15.3.0 is a three-year gap and old U-Boot
trees routinely need warning suppressions for new compilers. If the build
fights, pin pkgsCross.riscv64.buildPackages.gcc13 rather than patching the
vendor tree — a compiler pin is a one-line, legible, reversible constraint and
a patch series against Canaan’s overlay is not. Rejected: packaging the
Xuantie toolchain. 1.9 GB, MD5-only provenance, and the ISA evidence says it
is unnecessary. Layer: Nix.
Build Canaan’s OpenSBI 1.4 in the flake, not nixpkgs’ 1.8.1 — and this is
the one place a newer upstream is the wrong answer. OpenSBI was not a blob
when this change was drafted; fw_jump.bin and fw_jump_add_uboot_head.bin
were committed to firmware/stage1/ on 2026-09-20, mid-draft, for the same
build-convenience reason as U-Boot, and PROVENANCE.txt says as much. They
are E1: the whole Canaan delta is nine readable C files over
riscv-software-src/opensbi 1.4.
The tempting shortcut is pkgs.opensbi. It is wrong here, and not for the
usual version-skew reason. Upstream v1.8 does match
canaan,kendryte-k230 in platform/generic/thead/thead-generic.c — but with
thead_pmu_quirks only. Canaan’s overlay matches the same compatible with
THEAD_QUIRK_DISABLE_MAEE and calls thead_disable_maee() to clear
MXSTATUS.MAEE, and upstream’s c9xx_errata.h has no such bit. MAEE left on
is a page-attribute fault: the kind that boots fine and corrupts memory later.
So: fetch opensbi 1.4, apply the overlay, generic platform,
FW_TEXT_START=0, header it with mkimage exactly as post-image.sh does.
Rejected: pkgs.opensbi with a patch, and pkgs.opensbi unchanged — the
first is the same work with a worse diff, the second is a bet on a quirk we
can see is absent. Revisit if upstream gains a K230 MAEE quirk. The v0.9 in
docs/rtsmart-boot-log.txt is LilyGO’s shipped RT-Smart firmware and is in
neither chain. Layer: Nix.
Keep the committed binaries until a compiled stage 1 has booted, then delete them in the same commit as the evidence. A bringup failure with no fallback on a board whose console appears only after DDR training is a bad afternoon. Rejected: deleting them at the start to force the issue. Layer: repository.
Enforce “accounted for”, not “absent”. The scanner requires every binary
to have an inventory entry; an entry saying “permanent, here is why” passes.
Rejected: banning binary files, which would fail the moment a photograph of
the screen is committed as evidence — and photographs are grounding in this
project. Rejected: a git pre-commit hook, which is bypassable and does not see
the vendor checkouts where most of these blobs live. The check belongs in
./scripts/build_site.py, which already refuses to publish a spec whose
evidence is missing. Layer: tooling.
Publish the inventory by citing it, not by adding a renderer.
scripts/render_specs.py already copies any docs/ path cited from a
*Grounding:* line into the site. A requirement in image/vendor-blobs
citing docs/blob-inventory.md publishes it at /evidence/… and makes its
deletion a build failure. No new code. Layer: docs.
CONFIG_CANMV_V3_LPDDR4_2667) are taken unchanged, so the training data is
identical; and the recovery is writing a different card.CONFIG_SPL_SIZE_LIMIT=0x80000. → Low: the vendor’s
SPL is 206 064 bytes against a 524 288-byte limit. Check the size in the
derivation so a regression fails the build rather than the board.the-board-boots-what-we-built archives after this, or never. → The
image/boot-chain delta then has nothing to modify. Merge by hand; the
proposal says so rather than leaving it to be discovered at archive time.The removal of firmware/stage1/*.bin and env.env is the only destructive
step and it is last, gated on a committed console transcript. Rollback at any
earlier point is git checkout of those three files plus the existing
nix/stage1.nix. The flake attribute stage1.verified, which today checks
the committed hashes, is replaced by the derivation itself: a build that does
not produce the expected artifact fails, which is a stronger check than a
hash comparison against bytes we chose.
Whether the hardware ugzip path is meaningfully faster than the software
one at 345 KB. It does not change the specs, the approach, or the tasks — the
decision above is to match the vendor either way — but if the difference is
milliseconds, a future change could drop the sed and the one-byte
non-standard header with it.
Groups 1 through 4 make no hardware claim and can run while the board is in
pieces. Group 5 is the only one that needs the board, and it needs it because
DDR training happens before there is a console: nothing else can prove a stage 1
we compiled. QEMU proves nothing anywhere in this change — its k230 machine
loads a kernel directly and models neither the SPL nor the SD card.
1.1 Inventory every opaque binary this project ships, executes, or is one defconfig line from acquiring, with sha256, class, scope and the event that would remove it. Verify by committing docs/blob-inventory.md and confirming every sha256 in it reproduces: sha256sum -c over the MANIFEST’s file-backed rows
1.2 Write tools/blob-scan.py: walk the committed tree, plus any vendor checkout passed as an argument, classify each file as text or binary, and exit non-zero on a binary with no MANIFEST entry or a mismatched hash. It must also check the stage-1 release hash pinned in nix/stage1.nix, because a blob fetched by URL is not a blob the filesystem walk will find. Verify with ./tools/blob-scan.py exiting 0 on the current tree and ./tools/blob-scan.py --self-test exiting non-zero against a planted unlisted binary and against a mutated release hash
1.3 Call it from ./scripts/build_site.py alongside the existing evidence check. The citation that publishes the inventory is already in the image/vendor-blobs delta, so it takes effect when the capability reaches openspec/specs/; this task confirms it does. Verify with ./scripts/build_site.py exiting 0 and site/dist/evidence/docs-blob-inventory-md/index.html existing
Ticked after archive, which is the only point it could be: the page exists once image/vendor-blobs is in openspec/specs/. Archived at f6977ec; spec-site run on that sha completed success; https://knewter.github.io/tdisplay-k230/evidence/docs-blob-inventory-md/ returned HTTP 200 and the landing page reported 0 of 29 requirements are unverified, generated 2026-09-22 12:14 UTC. (coordinator)
1.4 Capture the scan’s passing and failing output to docs/evidence/blob-scan.txt, and resolve the UNVERIFIED marker on “A binary that is not in the inventory fails the build” against it. Verify with openspec validate --all
k230_priv_gzip -n8 against nixpkgs gzip -n -8 over the SDK’s u-boot.bin at levels 4 through 9, with both sha256 sets. Verify by committing docs/evidence/gzip-equivalence.txt and confirming it shows identical hashes at every levelk230_priv_gzip in the stage-1 pipeline with pkgs.gzip, and add the sed -i -e "1s/\x08/\x09/" the vendor applies and tools/gen-stage1.sh omits. Verify with nix build .#stage1-packaging reproducing fn_ug_u-boot.bin from the existing u-boot.bin and the result differing from the committed file in exactly the CM byte and the two checksums that cover ituboot-k230 derivation: fetch u-boot-2022.10 (sha256 50b4482a…) and kendryte/k230_linux_sdk at 1104236, rsync the overlay, apply k230_canmv_v3_defconfig, build with pkgsCross.riscv64. Pin gcc13 if GCC 15 fights. Verify with nix build .#uboot-k230 producing u-boot.bin and spl/u-boot-spl.binu-boot-spl.bin exceeds CONFIG_SPL_SIZE_LIMIT (0x80000). Verify with nix build .#uboot-k230 and the build log printing the measured size against the limitmkimage with SOURCE_DATE_EPOCH, the CM byte, firmware_gen_no_securiy.py — to produce fn_u-boot-spl.bin and fn_ug_u-boot.bin. Verify with nix build .#stage1 and file/xxd on the result showing the K230 magic and a CM byte of 0x09default.env rather than carrying env.env. Verify with nix build .#stage1 and sha256sum on the produced env.env matching f522ba13aa8a2e643e61e4fde9f2babb604e86b2f38a487be37c7bdc0b14c957 — this one step stays bit-identical, so it is checkable without the boardopensbi-k230 derivation: fetch riscv-software-src/opensbi 1.4, apply the SDK’s nine-file opensbi-1.4-overlay, generic platform, FW_TEXT_START=0. Do not substitute nixpkgs OpenSBI 1.8.1 — upstream matches canaan,kendryte-k230 but without THEAD_QUIRK_DISABLE_MAEE, and that quirk clears MXSTATUS.MAEE so standard page-attribute bits behave. Verify with nix build .#opensbi-k230 producing fw_jump.bin and strings on it finding canaan,kendryte-k230docs/evidence/uboot-env.txt says stage 1 expects: mkimage -A riscv -O linux -T kernel -C none -a 0 -e 0 -n linux. Verify with nix build .#fwJump and mkimage -l on the result showing a RISC-V Linux kernel image at load 0 and entry 0FW_JUMP_FDT_ADDR undefined, so fw_jump passes the device tree through where bootm put it instead of copying it to FW_TEXT_START + 0x2200000 — which docs/evidence/opensbi-fdt-lands-in-kernel-image.md proves is inside the kernel’s .BTF section. Verify by disassembling fw_next_arg1 in the built fw_jump.elf (nix shell nixpkgs#pkgsCross.riscv64.buildPackages.binutils -c riscv64-unknown-linux-gnu-objdump -d <fw_jump.elf> | grep -A4 '<fw_next_arg1>:') and showing a pass-through (add a0,a1,zero / mv a0,a1), not li a0,0x2200000; capture before and after into docs/evidence/opensbi-fdt-passthrough.txtfirmware/stage1/fw_jump.bin and fw_jump_add_uboot_head.bin once 4.2 produces a working equivalent, and confirm nothing in the flake copies a binary out of .build/. Verify with ./tools/blob-scan.py exiting 0 and grep -rn '\.build/' flake.nix nix/ returning nothing./tools/flash.sh against a /dev/disk/by-id path and fdisk -l on the result showing the documented offsetsdocs/evidence/stage1-from-source.txt containing the PMU Major Msg: training sequence and U-Boot 2022.10 from a binary this project built, and confirming it reaches the same prompt the vendored chain reaches
docs/evidence/stage1-from-source.txt and docs/evidence/boot-from-source-cold.txt record the board booting the from-source image to the login prompt, hashing its own card’s stage-1 slots to this flake’s bytes, and OpenSBI’s banner from the new build — but neither holds PMU Major Msg: or the U-Boot 2022.10 banner. The CH342 bridge loses power with the board and re-enumerates ~3.4 s later, after stage 1 has printed; across a cold boot those lines are unrecoverable with this bridge. Ticking on inference is what this task forbids.firmware/stage1/fn_u-boot-spl.bin, fn_ug_u-boot.bin and env.env, and rewrite nix/stage1.nix and firmware/stage1/PROVENANCE.txt around the derivations. Verify with nix build .#stage1 succeeding and git ls-files firmware/ listing no binary at all — the OpenSBI pair went in task 4.3, so this is the commit where firmware/ becomes textUNVERIFIED marker on “Stage 1 is built from source this project can read” against the transcript from task 5.2, and confirm the DDR PMU requirement still names the firmware’s offset in the new SPL rather than the old one. Verify with openspec validate every-blob-is-built-from-source-or-nameddocs/blob-inventory.md describes the tree as it then is, and record in it that A1–A3 are now derivations. Verify with ./scripts/build_site.py exiting 0 and openspec validate --all### Requirement: Stage 1 is a pinned vendored artifact### Requirement: Stage 1 is built from source this project can readThe boot chain before our kernel — U-Boot SPL, U-Boot 2022.10 and its environment — SHALL be produced by this project from source, pinned by the hash of that source rather than of the binary, and SHALL NOT be carried in the repository as a committed binary. The packaging steps that turn the compiled output into what the BootROM will load SHALL be expressed in the flake rather than in a shell script run by hand.
This reverses the previous requirement, which held that stage 1 SHALL NOT be built from source. The reason it held was a belief that the source was unavailable or the build unreasonable. Both are false: the source is open and on disk, and every packaging step has been reproduced with stock tools.
Grounding: docs/blob-inventory.md §A1–A2 and §D. The sources are U-Boot
2022.10 upstream, sha256
50b4482a505bc281ba8470c399a3c26e145e29b23500bc35c50debd7fa46bdf8, plus
Canaan’s rsync overlay applied by UBOOT_OVERLAY_DIRS in the SDK’s
buildroot-overlay/boot/uboot/uboot.mk, both open. Measured 2026-09-20:
nixpkgs ubootTools reproduces the committed env.env byte for byte, and
nixpkgs gzip plus mkimage plus the U-Boot tree’s own
firmware_gen_no_securiy.py reproduce both committed firmware images byte for
byte from the compiled U-Boot. readelf -A reports the compiled SPL as
rv64i2p1_m2p0_a2p1_c2p0_zicsr2p0_zifencei2p0_zmmul1p0 — no vendor ISA — and
the T-Head cache operations are hand-encoded as .long words, so the vendor
toolchain is not required to assemble them. Built 2026-09-22 and recorded in
docs/evidence/stage1-from-nix.txt: nix build .#uboot-k230 compiles
U-Boot and its SPL with nixpkgs GCC 15.3.0 (SPL 222 816 bytes against the
524 288-byte CONFIG_SPL_SIZE_LIMIT; readelf -A reports
rv64i2p1_m2p0_a2p1_c2p0_zicsr2p0_zifencei2p0_zmmul1p0_zaamo1p0_zalrsc1p0_zca1p0,
no vendor extension; zero th. mnemonics), nix build .#opensbi-k230
compiles OpenSBI 1.4 with the overlay under a GCC 13 pin, and nix build .#stage1 wraps both into the five files the card carries, with the K230
magic, a CM byte of 0x09, and the environment’s mkenvimage step
reproducing the SDK default byte for byte
(f522ba13aa8a2e643e61e4fde9f2babb604e86b2f38a487be37c7bdc0b14c957).
One deliberate departure from the vendor’s build: the vendor’s OpenSBI is
compiled with FW_JUMP_FDT_ADDR = FW_TEXT_START + 0x2200000, so fw_jump
copies the device tree to 0x2200000 — inside the kernel image loaded at
0x200000, in its .BTF section, as
docs/evidence/opensbi-fdt-lands-in-kernel-image.md reads back from
/sys/kernel/btf/vmlinux on the board. The OpenSBI this project builds
leaves FW_JUMP_FDT_ADDR undefined and passes the device tree through where
bootm placed it; docs/evidence/opensbi-fdt-passthrough.txt is the
fw_next_arg1 disassembly before and after.
Grounding, on hardware: docs/evidence/stage1-from-source.txt. On
2026-09-22 the board booted the pure nix build .#sdImage to the NixOS
login prompt with no panic and no emergency shell, and hashed its own
card’s raw slots from Linux: SPL at 1 MiB fe3d537f…, U-Boot at 2 MiB
805bd543…, /boot/fw_jump_add_uboot_head.bin 9627edbe… — the bytes
result-stage1/SHA256SUMS lists for this flake’s output. The BootROM ran
this SPL, it trained the DRAM and ran this U-Boot, and U-Boot ran this
OpenSBI; nothing vendor-compiled was on that card.
docs/evidence/boot-from-source-cold.txt is a second capture from power-on:
bootm’s Loading Device Tree to 000000000a0eb000 followed by this flake’s
OpenSBI banner reporting Platform Name : LILYGO T-Display-K230 and
Domain0 Next Arg1 : 0x000000000a0eb000 — the device tree handed on where
bootm put it, not at 0x2200000. What neither transcript holds: the SPL’s
PMU Major Msg: lines and the U-Boot 2022.10 banner. The CH342 console
bridge loses power with the board and takes about 3.4 s to re-enumerate,
and stage 1 prints inside that window; the cold capture’s --- port lost
/ --- port opened markers at 10.7 s and 14.1 s bracket it. The boot is
observed; the banners are inferred from it.
Building stage 1 from source SHALL NOT be treated as making it transparent. The parts of it that remain unreadable SHALL be listed by name, size and sha256, with their location inside the produced binary, so that compiling them ourselves does not remove them from view.
Grounding: docs/rtsmart-boot-log.txt records this board’s SPL printing
PMU Major Msg: End of CA training through Firmware run has completed —
the Synopsys DDR PHY training firmware running before anything else. It has no
source: it reaches us transliterated into 16 384 reg_write() calls in
Canaan’s lpddr4_init_32_swap_2667.c, which the SDK’s ddr.sh turns back
into an array at build time. Measured 2026-09-20 and recorded in
docs/blob-inventory.md §A5–A6: that image is 32 768 bytes of instruction
memory, sha256
517aa534255e88c941882be40f5e5735349cd1e3b144b536155e51bdc6309c8b, plus 1 660
bytes of data memory, and it sits verbatim at offset 0x1fc74 of the
vendor-compiled SPL — 15.9 % of it. In the SPL this flake compiles the same
bytes, same hashes, sit at 0x23f80 of u-boot-spl.bin and 0x24184 of
fn_u-boot-spl.bin — 14.7 % of a 222 816-byte SPL — measured 2026-09-22 and
recorded in docs/evidence/stage1-from-nix.txt. Compiling it moved it; it
did not shrink it.
Producing anything that goes on the card SHALL NOT require executing a binary this project cannot read. Where the vendor’s own build does so, the project SHALL substitute a readable equivalent and record the evidence that the substitution changes nothing.
Grounding: docs/blob-inventory.md §A4. The SDK’s
buildroot-overlay/board/canaan/k230-soc/post-image.sh runs
tools/k230_priv_gzip, a stripped x86-64 ELF, to compress U-Boot. Its strings
identify it as GNU gzip 1.6 — the FSF copyright, Written by Jean-loup Gailly., bug-gzip@gnu.org, and gzip’s unmodified option table
ab:cdfhH?klLmMnNqrS:tvVZ123456789, in which -n8 is the ordinary -n -8.
Measured 2026-09-20 on the SDK’s own 693 576-byte u-boot.bin: nixpkgs gzip
1.14 produces output identical to the vendor binary at every level the SDK
falls back through — docs/evidence/gzip-equivalence.txt is that
measurement, re-run 2026-09-22 with both sha256 sets at levels 4 through 9.
What is actually vendor-specific is a one-byte sed on the following line,
flipping the gzip header’s CM field to 0x09 so that the SPL’s
k230_priv_unzip() uses the SoC’s hardware decompressor; nix/stage1.nix
carries that sed, and docs/evidence/stage1-from-nix.txt records the
packaging over the vendor-compiled U-Boot reproducing the on-card
fn_ug_u-boot.bin and fn_u-boot-spl.bin byte for byte with nixpkgs tools
alone, and exactly which 40 bytes the sed changes.
Names every opaque binary this project ships, executes during a build, or is one configuration line away from pulling in — with what it is, what would remove it, and what it says about the next board — so that a blob we keep is one we chose rather than one nobody noticed.
The project SHALL maintain a single inventory naming every binary it ships, executes during a build, or would acquire by enabling a vendor package that its chosen board configuration already sets. Each entry SHALL carry the binary’s sha256, its size, and where it came from. The inventory SHALL cover binaries that are not on the current path as well as those that are, marked as such, because the cost of a blob is paid when someone enables it rather than when it is written down.
Grounding: docs/blob-inventory.md is that inventory. Its MANIFEST holds
68 rows: the five stage-1 files and the two byte ranges embedded in one of
them, the nine images this repository commits as evidence, the three source
fetches the stage-1 nix files pin, the BootROM, the toolchain and two
downloads, and the rest covering the Kendryte Linux SDK and the LilyGO
RT-Smart clone by hash or by counted group. docs/evidence/blob-scan.txt
records tools/blob-scan.py walking the committed tree and both vendor
checkouts on 2026-09-22 — 45 422 files, 3 597 of them binary — and matching
every binary to a row, with 54 rows verified against the bytes on disk. The
first run of that scanner is also in the file: it found 3 080 vendor binaries
and four group counts the hand-compiled inventory had wrong, which is why
the inventory is a scanned artifact and not a remembered one.
The build SHALL refuse to complete when a binary file exists in the tree, or in a vendor checkout the scan is pointed at, that the inventory does not account for. The check SHALL be “every binary is accounted for”, not “there are no binaries” — an entry may record that a blob is permanent and that is a passing state.
Grounding: tools/blob-scan.py, called from scripts/build_site.py beside
the evidence check, so a site that publishes the inventory cannot publish a
stale one. docs/evidence/blob-scan.txt records, on 2026-09-22: the scan
passing on the committed tree with both vendor checkouts walked; the scan
passing on the committed tree alone, which is what CI sees; and the
scanner’s self-test planting, in a scratch copy of the tree, a binary with
no row, a release hash in nix/stage1.nix with no row, and a listed blob
whose bytes had changed — each refused with a non-zero exit that names the
fault. The check also reaches what a filesystem walk cannot: every hash the
stage-1 nix files pin must be classified by the inventory as source or as a
fetched binary, so a blob arriving by URL is refused the same way.
Every inventory entry SHALL name the concrete event that would make the binary unnecessary — an upstream publishing source, a driver reaching mainline, a different boot mode, or “none, this is work rather than waiting” — so that a future reader can check whether it has happened without re-deriving the analysis. Every entry SHALL also say whether the binary is a property of the silicon, of this vendor’s process, of this board’s parts, or near-universal across modern systems-on-chip.
Grounding: docs/blob-inventory.md carries both for each entry, and section
F distils them into the questions worth asking before buying hardware. The
distinction it draws is load-bearing: the DDR PMU training firmware is marked
industry-wide and permanent, while being made to execute a renamed GNU gzip to
produce a bootable image is marked as this vendor’s choice and removable
today.
The inventory SHALL be reachable from the specification site rather than only from the repository, because the people most affected by what a device runs are the least likely to clone it.
Grounding: scripts/render_specs.py copies any docs/ path cited from a
*Grounding:* line into the site and serves it at /evidence/<slug>/, and
scripts/build_site.py fails when a cited evidence file is missing. Citing
docs/blob-inventory.md from a requirement therefore publishes it and keeps
it published, with no new rendering code.
./scripts/build_site.py fails rather than publishing a site that silently drops itArchived change · Archived
Snapshot 5836ef1d113d · 2026-10-17 08:22 UTC
Closed recordReview the archived record and cited scope
Nothing this project wants to run — AtomVM, the Dozer core, anything with a
screen — can be built until something can build riscv64 at all. riscv64-linux
is community-tier in nixpkgs with no binary cache, so a NixOS closure for it
is compiled rather than downloaded, and whether that succeeds on the machine we
have is unknown.
It is worth answering that first and separately, because it needs no hardware.
QEMU 11.1 ships a k230 machine, so an image can be built and booted in a loop
on a laptop while the board sits in a drawer. If a riscv64 closure turns out not
to cross-build cleanly, every later plan changes, and we would rather learn that
now than after a soldering iron is involved.
binfmt with
qemu-riscv64 is registered on the build host and stays as the fallback for
derivations that refuse to cross.qemu-system-riscv64 -machine k230 to a console
prompt, with the boot recorded as committed evidence.the-board-boots-what-we-built fills it.Non-goals. The physical board. The panel, touch, or either radio — QEMU’s
k230 models none of them, so claiming any would be unfounded. AtomVM, the
Dozer core, or any choice of shell. A pleasant or minimal closure size; this
one only has to boot.
image/cross-build: producing riscv64 artifacts on an x86_64 host, and what
is done when something will not cross.system/nixos-config: what the NixOS system for this board contains and what
it guarantees on boot.None. This is the first change in the repository.
Adds flake.nix and a nix/ tree at the repository root. Adds a QEMU runner
under tools/. No existing code is touched; tools/ currently holds only
serial and USB helpers, which this does not disturb.
Build host requirements: an x86_64-linux Nix with flakes, and binfmt
qemu-riscv64 registered for the emulation fallback. Both are present on the
development machine.
See proposal.md — Why. The constraints that shape the approach:
x86_64-linux with 32 cores and 125 GiB of RAM, Nix 2.35
with flakes, and binfmt qemu-riscv64 already registered.riscv64-linux has no upstream binary cache, so wall-clock cost is dominated
by compilation, and anything that lands in the closure is paid for repeatedly.-machine k230, described as “RISC-V Board compatible
with Kendryte K230 SDK”. It models the SoC well enough to boot; it does not
model this board’s panel, touch controller, SDIO radio, or SD layout.Goals:
Non-Goals:
Cross-compile by default; emulate only named exceptions.
nixpkgs.buildPlatform = "x86_64-linux" with
nixpkgs.hostPlatform = "riscv64-linux". The alternative — run the whole build
under binfmt emulation — was rejected because a full NixOS closure emulated
through QEMU user-mode on this host would take long enough to stop the
feedback loop this change exists to create. Emulation stays registered as a
per-derivation escape hatch, and each use gets written down.
Vendor stage 1 as an opaque input rather than packaging it. Canaan’s SPL carries a DDR PHY training blob and a custom image header with compression. Reimplementing that packaging in Nix was considered and rejected for now: it is a project in itself, it is not on the path to answering this change’s question, and it can be revisited once anything boots at all. The seam is declared now so the later work has somewhere to land.
Boot proof on virt, not k230. See Open Questions — mainline has no
bootable K230 platform, so this is forced rather than chosen. The consequence
worth carrying forward: nothing in this change exercises K230-specific kernel
support, so the-screen-comes-up-under-linux is where that first gets tested.
QEMU is a boot check, not a hardware simulator.
The runner is a script under tools/, not a Nix app, so it stays obviously a
development convenience rather than something later changes might mistake for
a test of the board. Its output is committed under docs/evidence/.
The console is serial at 115200 8N1 in both worlds. The board’s CH342 gives two CDC-ACM ports at that rate. Matching it under QEMU means one transcript format, and means the first hardware boot differs from a known-good QEMU boot in the fewest possible ways.
k230 diverges from the real SoC. → Accepted and bounded by
scope: this change claims only that the closure builds and boots under
emulation. Nothing here is evidence about the board, and the spec says so.k230 machine. It cannot: mainline
6.18.52 ships no K230 device tree (arch/riscv/boot/dts/canaan/ is K210-only)
and no SOC_CANAAN_K230, so there is no bootable K230 platform upstream at
all.The resolution keeps this change’s scope rather than pulling kernel packaging
forward. What this change asks — does the closure build and start — is
machine-independent, so it is answered on -machine virt with the stock
kernel. A k230-machine boot needs the Xuantie kernel with
CONFIG_ERRATA_THEAD_PBMT=n (that errata being the T-Head MAEE page-table
extension QEMU does not implement), and that belongs to
the-screen-comes-up-under-linux, which needs that kernel anyway.
Recorded in full in docs/evidence/boot-path-differences.md.
Every proving command below is a QEMU or build-host claim. None of them say
anything about the board — QEMU’s k230 machine models no panel, no touch, no
radio and no SD layout.
flake.nix and cross-build one trivial package to prove the toolchain resolves. Verify with nix build --no-link .#checks.x86_64-linux.cross-hello and record the store pathdocs/evidence/cross-build.txtnixosConfigurations.k230 with buildPlatform = x86_64-linux and hostPlatform = riscv64-linux, a serial console at 115200 8N1, and no graphical stack. Verify with nix eval .#nixosConfigurations.k230.config.system.build.toplevel.drvPathnix build .#nixosConfigurations.k230.config.system.build.topleveldocs/evidence/cross-build.txt; if the list is empty, say so explicitlytools/qemu-k230.sh that boots the built system under qemu-system-riscv64 with the console on stdio, defaulting to -machine virt and explaining why k230 is not yet reachable. Verify by running it and reaching a promptCAPTURE=120 ./tools/qemu-k230.sh | tee docs/evidence/qemu-boot.txt and confirm the transcript ends at an interactive promptnix eval showing the vendored attribute exists, and grep -riE 'u-?boot|opensbi' nix/ flake.nix showing no derivation compiles eithersystem/nixos-config’s stage-1 requirement against the committed QEMU transcript and the flake, and resolve or restate the UNVERIFIED markers in both delta specs. Verify with openspec validate a-riscv-nixos-closure-cross-buildsDefines how riscv64 artifacts for this board are produced on an x86_64 host, and what is recorded when a package will not cross-compile.
Grounding: docs/evidence/cross-build.txt. The full system closure was
cross-compiled on an x86_64 host with no riscv64 hardware — 353 derivations
built locally, ~970 substituted, producing 1.2 GiB across 474 store paths in
4413s. The resulting kernel booted under QEMU to a shell prompt
(docs/evidence/qemu-boot.txt).
Building the system SHALL NOT require a riscv64 machine. The build SHALL
declare an x86_64-linux build platform and a riscv64-linux host platform,
so that derivations cross-compile by default.
Emulation SHALL remain available as a fallback for derivations that cannot cross-compile, and any derivation built under emulation SHALL be named in the repository rather than silently emulated. The distinction matters because emulated builds are slow enough to change what is worth attempting.
Two things are easily conflated, and the difference decides whether a build takes minutes or hours:
riscv64-linux is community-tier in nixpkgs and is not built by
the upstream cache.pkgsCross.riscv64 derivations are built on x86_64, so
upstream does build many of them and they are substitutable.Because this project cross-compiles, it benefits from that second case. The project SHALL NOT assume full cache coverage, and documentation of the build SHALL state the measured split between substituted and locally built paths, so that a long compile is recognised as normal rather than as a fault.
Grounding: measured on this host building the k230 closure — 636 paths
substituted from cache.nixos.org, of which 174 were riscv64 outputs, against
164 built locally. Recorded in docs/evidence/cross-build.txt.
Defines what the NixOS system for this board contains, what it guarantees when it boots, and where the boundary sits between what we build and what is vendored from Canaan.
Grounding: docs/evidence/qemu-boot.txt. Booted under
qemu-system-riscv64 -machine virt on 2026-09-20, reaching
<<< Welcome to NixOS kexec-26.11.20260919.20b1ddd (riscv64) - ttyS0 >>>
and an interactive shell on ttyS0 at 115200 8N1, with no display, no
keyboard and no network configured. OpenSBI v1.8.1 handed off to S-mode and
systemd reached Login Prompts.
The system SHALL boot to an interactive console prompt on the serial console without a display, a keyboard, or a network. Everything this project does next is done through that prompt, so it is the first thing that must hold.
The console SHALL be the serial console at 115200 8N1, matching the board’s CH342 bridge, so that one transcript format serves both QEMU and hardware.
What this proves is machine-independent: that the closure is coherent and that userspace starts. It SHALL NOT be read as evidence about the board.
The emulated machine is virt, not k230, and that is a finding rather
than a shortcut. Mainline Linux has no bootable K230 platform: 6.18.52
carries pinctrl-k230.c and reset-k230.c but ships no K230 device tree
(arch/riscv/boot/dts/canaan/ is K210-only) and has no SOC_CANAAN_K230 —
only SOC_CANAAN_K210, which is depends on !MMU. A k230-machine boot
additionally needs the Xuantie kernel built with CONFIG_ERRATA_THEAD_PBMT=n,
that errata being the T-Head MAEE page-table extension QEMU does not
implement. That kernel is the panel bring-up’s to package.
BootROM, the U-Boot SPL and its DDR PMU training firmware, U-Boot, and OpenSBI SHALL be treated as a vendored binary input. The build SHALL NOT attempt to compile them from source.
Grounding: docs/rtsmart-boot-log.txt records the chain on this board —
U-Boot SPL 2022.10, the PMU training messages, U-Boot 2022.10, then
OpenSBI v0.9. Canaan packages these with a custom header and compression
(image: uboot load to 20000000 compress =1), which is why reproducing them is
out of scope.
This boundary SHALL be explicit in the build rather than implied by what happens not to be built, so that a later change cannot acquire a dependency on building stage 1 without saying so.
Grounding: measured against the built closure rather than asserted —
/nix/store/lzg30bab6kqkgsa54jaql1ixfxgizxv3-nixos-system-nixos-... is
1.2 GiB over 474 store paths and contains zero NetworkManager, ModemManager,
xserver or mesa paths. Recorded in docs/evidence/cross-build.txt. The QEMU
variant is deliberately heavier — netboot-minimal imports
installation-device — but that is the test harness and never reaches the
board.
The system SHALL contain what is needed to reach a prompt and inspect the machine, and SHALL NOT carry a desktop, a display manager, or a graphical stack. Absent a binary cache every added package is compiled, so the closure’s contents are a cost paid on every clean build.