From 0f5806e774e1ef05848054d59a95be9d1d54de5d Mon Sep 17 00:00:00 2001 From: orchestration-renewed Date: Wed, 18 Nov 2026 15:45:52 +0100 Subject: [PATCH] docs(base-graph): the repository graph measured; the device layer comes from docs Research base-graph-measured, base-graph-world and base-graph-how-it-stands with their material and the failing test graph-drift.sh (36 FAIL today). Decision 2026-11-18-device-layer-from-docs supersedes 2026-11-18-device-template-follows-by-release: idealkb -> docs -> every device base, the template one of them; own needs an item; a base's edit of a followed file goes up as a PR; one drift check daily; git-rhizoid built after, by conformance. Backlog base-graph and its steps, the template and lab items reshaped, idealkb's side and rhizoid's scope as upstream items. Co-Authored-By: Claude Opus 5.5 --- data/backlog.json | 23 +- data/decisions.json | 1 + data/research.json | 3 + data/session_log.json | 1 + data/sources.json | 15 ++ data/summaries.json | 3 +- data/upstream_items.json | 5 + docs/backlog.md | 237 +++++++++++++++-- docs/decisions.md | 45 ++++ docs/index.md | 14 +- docs/research.md | 93 +++++++ docs/session_log.md | 24 ++ docs/sources.md | 240 ++++++++++++++++++ docs/summaries.md | 27 +- docs/upstream_items.md | 125 +++++++++ research/base-graph/2026-11-18/graph-drift.sh | 111 ++++++++ research/base-graph/2026-11-18/measured.md | 85 +++++++ 17 files changed, 1013 insertions(+), 39 deletions(-) create mode 100755 research/base-graph/2026-11-18/graph-drift.sh create mode 100644 research/base-graph/2026-11-18/measured.md diff --git a/data/backlog.json b/data/backlog.json index b373ace..4908294 100644 --- a/data/backlog.json +++ b/data/backlog.json @@ -117,7 +117,7 @@ {"project":"linux-phone-oco/docs","id":"about-across-bases","title":"How a device row names a docs component or feature: the about rule works within one base","status":"open","note":"Open: proposal is docs:ID in text and a local components list in the device base seeded from docs; decide with the first device base. Owner: idealkb (ikb) with docs.","opened":"2026-11-17","waits":null,"blocked_by":null,"hardware":null,"needs":null,"device":null,"proof":null,"rank":null,"about":"commons-only"} {"project":"linux-phone-oco/docs","id":"device-template-base","title":"device-template gets a tad base: tables.toml following idealkb, the parts contract (status, evidence, date), next and phone-queue queries, ikb","status":"done","note":"Landed 2026-11-17 (linux-phone-oco/device-template #4, read back from main): data/ (12 empty tables), tables.toml (own: backlog + needs/proof/rank, devices, parts, test_runs, test_results), idealkb 0.9.1 pin with machine = test-run, devicebase.toml (template date, parts = 1: the contract docs validates), records backlog/backlog-status/backlog-needs/part/device/test-run, queries phone-queue/phone-next/parts (no --device: the base is the device), CI tad.yml (check + canon/render fresh), Makefile, README/AGENTS. device.toml untouched. surya-lab and google-walleye-lab are not changed: their keepers take it with move-device-rows. Next: feed-device-bases reads data/parts.json of each base against parts = 1.","opened":"2026-11-17","waits":null,"blocked_by":null,"hardware":null,"needs":null,"device":null,"proof":null,"rank":null,"about":"commons-only"} {"project":"linux-phone-oco/lab-tools","id":"gather-into-device-base","title":"devlab gather files a device's runs and results into its own base","status":"done","note":"devlab gather files into the lab's own base when it has a devicebase.toml (same test-run record; filed() and derivations from the lab; land lands the lab alone); --docs keeps the old path; the output says where it filed. lab-tools #82, devlab rebuilt into ~/.local/bin. Dry check on a scratch walleye base: run filed, test_runs/test_results rows present.","opened":"2026-11-17","waits":"move-device-rows","blocked_by":null,"hardware":null,"needs":null,"device":null,"proof":null,"rank":null,"about":"commons-only"} -{"project":"linux-phone-oco/docs","id":"device-template-follow","title":"How a device repository takes later changes of device-template beyond idealkb's generic files","status":"in-progress","note":"Decided 2026-11-17 (idealkb decision 2026-11-17-chain-follow-by-slice): the same pin-and-follow slice as idealkb, not a fork, subtree or Copier. Done: device-template lists what it gives (generic) and ships idealkb and itself as upstreams in its base. Next: device-template releases (release-please) and idealkb's follow-source-from-pin (update-pins reading its source from the pin file); then surya-lab and google-walleye-lab follow it with move-device-rows. Improvements go back as upstream items (PRs). rhizoid's missing slice mode is on git-rhizoid's backlog (slice-consumption).","opened":"2026-11-17","waits":null,"blocked_by":null,"hardware":null,"needs":null,"device":null,"proof":null,"rank":null,"about":"commons-only"} +{"project":"linux-phone-oco/docs","id":"device-template-follow","title":"How a device repository takes later changes of device-template beyond idealkb's generic files","status":"in-progress","note":"Route changed by decision 2026-11-18-device-layer-from-docs: device bases follow the device layer from docs (device-layer-in-docs), the template is a follower (template-follows-docs), the labs follow docs (surya-follows-template, walleye-follows-template). Proof: graph-drift.sh layer lines ok.","opened":"2026-11-17","waits":null,"blocked_by":null,"hardware":null,"needs":null,"device":null,"proof":null,"rank":null,"about":"commons-only"} {"project":"linux-phone-oco/lab-tools","id":"fastboot-found-by-serial-or-port","title":"fastboot: a phone out of fastboot found by its serial or USB port, else gone from USB","status":"done","note":"Done 2026-11-17 (lab-tools PR 81, f904196), asked by walleye-coordinator: after a boot try devlab took surya's postmarketOS gadget (18d1:d001) and a shared address for walleye's Linux while walleye had left USB. Now only a USB device carrying the phone's serial, or one on the USB port it sat on in fastboot (remembered at STATE/CODENAME/usb-port), answers for it; ping and vendor:product alone are gone; nothing found after three minutes is said as gone from USB, needing hands. Installed. Sign: walleye's manifest shares surya's USB address 172.16.42.1 - when Linux runs on both, devlab phone must tell them apart (by interface/port), not by address.","opened":"2026-11-17","waits":null,"blocked_by":null,"hardware":null,"needs":null,"device":null,"proof":null,"rank":null,"about":"dl-safe"} {"project":"linux-phone-oco/lab-tools","id":"bringup","title":"bringup: the host tool that makes a device's first boot images (boot image pack, unpack, swap, check; initramfs)","status":"open","note":"Decided 2026-11-17 (decision 2026-11-17-bringup-in-lab-tools): lpoco-bringup, a workspace member of lab-tools run as 'lpoco bringup' under one roof - the lpoco dispatcher (lpoco-dispatcher), one pin, one release - Rust with argenv, wrapping mkbootimg/avbtool and crates for cpio, compression and dtb. Replaces walleye's eight build/check scripts; device facts in device.toml [boot]. Steps: lpoco-dispatcher, bringup-image-v0, -swap, -initramfs, -pin-and-hooks, -release, lpoco-rename-lab-tone, lpoco-mcp-one-door. Next: lpoco-dispatcher with bringup-image-v0.","opened":"2026-11-17","waits":null,"blocked_by":null,"hardware":null,"needs":null,"device":null,"proof":null,"rank":null,"about":"bringup"} {"project":"linux-phone-oco/lab-tools","id":"bringup-image-v0","title":"bringup image info|unpack|pack|check for header v0, packed byte for byte as mkbootimg","status":"done","note":"Landed in lab-tools PR 85 (https://github.com/linux-phone-oco/lab-tools/pull/85): crate lpoco-bringup (lib+bin, argenv, family version 0.1.7, release-plz version_group), image info|unpack|pack|check for header v0, [boot] from device.toml; proof bringup-pack-matches-mkbootimg green (pack equals mkbootimg byte for byte, check fails a wrong ramdisk offset and passes the right one). Decision 2026-11-17-bringup-image-header-layer. Next, own items: swap, initramfs, pin-and-hooks, release; the device template's [boot] table with CHANGE values.","opened":"2026-11-17","waits":null,"blocked_by":null,"hardware":null,"needs":"build","device":"google-walleye","proof":"bringup-pack-matches-mkbootimg","rank":null,"about":"bringup"} @@ -174,12 +174,12 @@ {"project":"linux-phone-oco/lab-tools","id":"sxmo-utils-lab-apk-deliver","title":"Build, sign and publish the sxmo-utils lab apk as the sxmo-utils@lab repository","status":"done","note":"Delivered 2026-11-18. Conveyor v1.2.1 (v1 moved; PRs conveyor 19, 20): alpine.yml copies the APKBUILD's whole folder, keeps the live repository's other packages in the one signed APKINDEX, derives the front page and verify from it, installs the APKBUILD's makedepends in the signing container before the key, and refuses a deploy that would lose a live package; its own test (tests/alpine/run.sh, CI job alpine) runs the steps on two fixture packages. lab-tools PRs 168 (packaging/sxmo-utils/conveyor.toml, second packages job, tag sxmo-utils-v1.18.1_p20261118 pushed by hand), 169 (APKBUILD build()), 172 (restored 168/169 after #170 put the files back). Proof: lab-tools Packages run 44322521483: 19 packages verified against the committed key, https://linux-phone-oco.github.io/lab-tools/ offers lpoco-health 0.15.1 and sxmo-utils 1.18.1_p20261118-r0 (every subpackage listed), both installed in a clean Alpine 3.24 aarch64 from the page's own lines. Next: the phone takes it (apk add sxmo-utils from that repository tagged @lab) - the phone proof suspend-retry-backs-off.","opened":"2026-11-18","waits":null,"blocked_by":null,"hardware":null,"needs":"build","device":"xiaomi-surya","proof":"suspend-retry-backs-off","rank":4,"about":"sxmo-utils-lab-apk"} {"project":"linux-phone-oco/lab-tools","id":"phone-pieces-drift-in-lab","title":"lpoco lab names a stale phone-side piece at every change's end, from the report it reads back","status":"done","note":"2026-11-18, lab-tools-builder: done (lab-tools #170, main 27bd466). lpoco-lab test and health name a stale phone piece after the run, from the report just read back, judged by lpoco_host::stale_lines (shared with lpoco host check). Proof: host/tests/phone_pieces.rs the_lab_names_a_piece_off_main_from_the_report_it_reads_back (seen failing first) and the_lines_name_a_package_off_its_pin. Not tested end to end against a phone: devlab's wiring (health.rs name_stale_pieces) has no test of its own. Note: the commit named is now the oldest holding the stale blob (changes host check output). Report-name ordering checked: names are YYYYMMDD-HHMMSS, so the greatest sorts newest.","opened":"2026-11-18","waits":null,"blocked_by":null,"hardware":null,"needs":"build","device":"xiaomi-surya","proof":"a test in lab-tools lpoco/tests (to write, failing first): after a change the lab output names a piece off main","rank":6,"about":"phone-pieces-drift-named"} {"project":"linux-phone-oco/lab-tools","id":"host-plan-unreadable-not-new","title":"lpoco host records each root file it installs, so plan reads an unreadable one as up to date","status":"done","note":"2026-11-18, lab-tools-builder: done (lab-tools #173, main a4d4a3e). prepare records the git blob id of each root file it installs in ~/.local/state/lpoco-host/installed (lines 'HASH DST'), after every root command succeeded; plan reads a file under a folder the lab user may not enter (PermissionDenied) by that record: up to date when it matches, else planned as an install and worded 'unreadable, not known yet', never '(new)'. Proof: host/tests/plan.rs a_root_file_the_lab_user_cannot_read_is_judged_by_the_hash_recorded_at_its_last_install (seen failing first). Not done, now host-record-from-check: the lab has no record until the next prepare, so the first plan on it still names 50-lpoco.rules 'not known yet' and the first prepare reinstalls it (one sudo); a passing lpoco host check does not write the record; plan does not tie 'up to date' to the share check passing. The test assumes the suite does not run as root (mode 000 does not stop root).","opened":"2026-11-18","waits":null,"blocked_by":null,"hardware":null,"needs":"build","device":"xiaomi-surya","proof":"host plan tests from fixtures: (1) a root file under an unreadable directory, whose staged content hashes to the hash recorded at its last install, is planned up to date with 0 root commands; (2) changed staged content is planned as a root install; (3) with no record, it is named as unreadable and not known, never '(new)'; (4) prepare now records the hash after each root install it runs","rank":5,"about":"lpoco-host-rest"} -{"project":"linux-phone-oco/device-template","id":"template-classifies-its-files","title":"device-template names every file it has: generic (followed) or made-once (laid at creation); the skeleton followed, the hardware files left to idealkb","status":"open","note":"Decision 2026-11-18-device-template-follows-by-release, step 1. Add a made-once list (device.toml, oco.toml, README.md, devicebase.toml, idealkb.toml, provision/packages.txt, .oco/uncommitted, data/); move Makefile, bin/install-tad.sh, tad.yml, gather.yml, .gitignore, tests/health/README.md and the .gitkeep files into generic; split the script check into a workflow a lab does not extend; a template:begin/end part in AGENTS.md for the general conventions; drop records/hardware.sql, records/hardware-status.sql, queries/hardware.sql from generic (idealkb 0.15.0 gives them). Owner: orchestration (device-template).","opened":"2026-11-18","waits":null,"blocked_by":null,"hardware":null,"needs":null,"device":null,"proof":"docs research/device-template/2026-11-18/template-drift.sh device-template ideal-knowledge-base: its classified and one-source lines say ok (today 18 unclassified files, 3 with two sources)","rank":null,"about":"device-template"} -{"project":"linux-phone-oco/device-template","id":"template-releases","title":"device-template releases by release-please from v0.1.0, and a lab's devicebase.toml names the release it follows","status":"open","note":"Step 2. release-please as in idealkb; devicebase.toml template = \"X.Y.Z\" with own = [...] for template files a lab keeps; the template's own devicebase.toml comment says how a new lab sets it. The date pin (2026-11-17) is retired.","opened":"2026-11-18","waits":null,"blocked_by":"template-classifies-its-files","hardware":null,"needs":null,"device":null,"proof":"gh release list -R linux-phone-oco/device-template shows v0.1.0, and template-drift's pin line reads it for a lab pinned to it","rank":null,"about":"device-template"} -{"project":"linux-phone-oco/device-template","id":"template-drift-in-ci","title":"template-drift runs in CI: the template's (classified, one-source) and each lab's (pin, equal, no-copy), from a generic bin/template-drift.sh","status":"open","note":"Step 4. The failing test in docs research/device-template/2026-11-18/ becomes a generic file of the template; a lab's workflow clones the template at its pinned tag and idealkb at its pin, read-only. Like cruft check plus cruft diff --exit-code.","opened":"2026-11-18","waits":null,"blocked_by":"template-releases","hardware":null,"needs":null,"device":null,"proof":"a test PR to a lab that edits a template-generic file fails CI with a line naming the file; main of the template and both labs pass","rank":null,"about":"device-template"} -{"project":"linux-phone-oco/device-template","id":"template-followed-by-update-pins","title":"The hourly update-pins moves a lab's template pin as it moves idealkb's: the template lists its consumers, each bump lands through the lab's CI","status":"open","note":"Step 3. A change to the device layer then lands in the template only; no more parallel hand PRs. idealkb first, then the template, in one run.","opened":"2026-11-18","waits":"grenudi/ideal-knowledge-base item follow-source-from-pin (follow.sh and update-pins read their source from the pin file)","blocked_by":"template-releases","hardware":null,"needs":null,"device":null,"proof":"the first template release after v0.1.0 reaches surya-lab and google-walleye-lab as one bot PR each, landed by their CI, with template-drift exit 0 after","rank":null,"about":"device-template"} -{"project":"linux-phone-oco/surya-lab","id":"surya-follows-template","title":"surya-lab follows device-template's release: its copy of the list gone, check.yml and tests/health/README.md taken, the pin a release","status":"open","note":"Migration for decision 2026-11-18-device-template-follows-by-release; no phone. Measured drift today: generic copy 5 entries behind, check.yml without xargs -r, tests/health/README.md missing, devicebase.toml template = 2026-11-17. AGENTS.md outside the idealkb part stays its own until the template:begin part exists, then the general conventions come from the template.","opened":"2026-11-18","waits":null,"blocked_by":"template-releases","hardware":null,"needs":"build","device":"xiaomi-surya","proof":"docs research/device-template/2026-11-18/template-drift.sh device-template ideal-knowledge-base surya-lab: every surya-lab line says ok","rank":null,"about":"device-template"} -{"project":"linux-phone-oco/google-walleye-lab","id":"walleye-follows-template","title":"google-walleye-lab follows device-template's release: its copy of the list gone, its rust job in its own workflow, the pin a release, stale PR 208 closed","status":"open","note":"Migration for decision 2026-11-18-device-template-follows-by-release; no phone. Measured drift today: generic copy 5 entries behind, ffs-acm-rs job inside the template's check.yml, devicebase.toml template = 2026-11-17, PR #208 (the template's #15 by hand) open though main has it.","opened":"2026-11-18","waits":null,"blocked_by":"template-releases","hardware":null,"needs":"build","device":"google-walleye","proof":"docs research/device-template/2026-11-18/template-drift.sh device-template ideal-knowledge-base google-walleye-lab: every google-walleye-lab line says ok","rank":null,"about":"device-template"} +{"project":"linux-phone-oco/device-template","id":"template-classifies-its-files","title":"device-template names every file it has: generic (followed) or made-once (laid at creation); the skeleton followed, the hardware files left to idealkb","status":"open","note":"Reshaped by decision 2026-11-18-device-layer-from-docs: the template names every file it has - what docs' device layer gives (the statements, the device tables' part, the skeleton: Makefile, bin/install-tad.sh, tad.yml, gather.yml, .gitignore, check.yml, tests/health/README.md - these move to docs' device-layer/ by device-layer-in-docs) and a made-once list (device.toml, oco.toml, README.md, devicebase.toml, idealkb.toml, provision/packages.txt, .oco/uncommitted, data/). Its own generic list goes (template-follows-docs).","opened":"2026-11-18","waits":null,"blocked_by":null,"hardware":null,"needs":null,"device":null,"proof":"docs research/device-template/2026-11-18/template-drift.sh device-template ideal-knowledge-base: its classified and one-source lines say ok (today 18 unclassified files, 3 with two sources)","rank":null,"about":"device-template"} +{"project":"linux-phone-oco/device-template","id":"template-releases","title":"device-template releases by release-please from v0.1.0, and a lab's devicebase.toml names the release it follows","status":"done","note":"Closed, not done: decision 2026-11-18-device-layer-from-docs supersedes the route - the template releases nothing and is followed by nothing; docs' release carries the device layer and update-pins follows docs (device-layer-in-docs, template-follows-docs).","opened":"2026-11-18","waits":null,"blocked_by":"template-classifies-its-files","hardware":null,"needs":null,"device":null,"proof":"gh release list -R linux-phone-oco/device-template shows v0.1.0, and template-drift's pin line reads it for a lab pinned to it","rank":null,"about":"device-template"} +{"project":"linux-phone-oco/device-template","id":"template-drift-in-ci","title":"template-drift's classified check runs in the template's CI; the labs' checks are graph-drift's (docs, daily)","status":"open","note":"Reshaped by decision 2026-11-18-device-layer-from-docs: pin, equal and no-copy move to graph-drift.sh (graph-drift-daily); the template keeps classified.","opened":"2026-11-18","waits":null,"blocked_by":"template-classifies-its-files","hardware":null,"needs":null,"device":null,"proof":"a test PR to the template adding an unclassified file fails its CI with a line naming it","rank":null,"about":"device-template"} +{"project":"linux-phone-oco/device-template","id":"template-followed-by-update-pins","title":"The hourly update-pins moves a lab's template pin as it moves idealkb's: the template lists its consumers, each bump lands through the lab's CI","status":"done","note":"Closed, not done: decision 2026-11-18-device-layer-from-docs supersedes the route - the template releases nothing and is followed by nothing; docs' release carries the device layer and update-pins follows docs (device-layer-in-docs, template-follows-docs).","opened":"2026-11-18","waits":"grenudi/ideal-knowledge-base item follow-source-from-pin (follow.sh and update-pins read their source from the pin file)","blocked_by":"template-releases","hardware":null,"needs":null,"device":null,"proof":"the first template release after v0.1.0 reaches surya-lab and google-walleye-lab as one bot PR each, landed by their CI, with template-drift exit 0 after","rank":null,"about":"device-template"} +{"project":"linux-phone-oco/surya-lab","id":"surya-follows-template","title":"surya-lab follows docs' device layer and device-template's skeleton files: devicebase.toml names source = linux-phone-oco/docs and a version, its list copy gone, check.yml and tests/health/README.md taken","status":"open","note":"Reshaped by decision 2026-11-18-device-layer-from-docs (it supersedes 2026-11-18-device-template-follows-by-release): the layer's source is docs, not a template release. About an hour, no phone; surya-lab's owner lands it in its base.","opened":"2026-11-18","waits":null,"blocked_by":"device-layer-in-docs","hardware":null,"needs":"build","device":"xiaomi-surya","proof":"research/base-graph/2026-11-18/graph-drift.sh: layer-pin, layer-owner, layer-follow ok for surya-lab","rank":null,"about":"device-template"} +{"project":"linux-phone-oco/google-walleye-lab","id":"walleye-follows-template","title":"google-walleye-lab follows docs' device layer: devicebase.toml names source = linux-phone-oco/docs and a version, its list copy gone, its rust job in its own workflow, stale PR 208 closed","status":"open","note":"Reshaped by decision 2026-11-18-device-layer-from-docs: the layer's source is docs, not a template release. About an hour, no phone; walleye's owner lands it in its base.","opened":"2026-11-18","waits":null,"blocked_by":"device-layer-in-docs","hardware":null,"needs":"build","device":"google-walleye","proof":"research/base-graph/2026-11-18/graph-drift.sh: layer-pin, layer-owner, layer-follow ok for google-walleye-lab","rank":null,"about":"device-template"} {"project":"linux-phone-oco/docs","id":"bringup-steps","title":"Bring-up steps as data: every step that makes Linux run on a machine, generic in docs, each device's status claimed in its own base, a guidebook and helpers made from it","status":"open","note":"Decided 2026-11-18-bringup-steps-generic-in-docs-status-in-each-base (research bringup-steps-landscape). The pieces are the items about bringup-steps, unranked for the author.","opened":"2026-11-18","waits":null,"blocked_by":"bringup-steps-schema,bringup-steps-seed,feed-device-steps,walleye-steps-claimed","hardware":null,"needs":null,"device":null,"proof":"research/bringup-steps/2026-11-18/bringup-chain-walleye.sh passes in docs: tad q bringup-chain --device google-walleye lists walleye's steps in order, each proven one with its proof and run, none unknown (fails today: no query bringup-chain)","rank":null,"about":"commons-only"} {"project":"linux-phone-oco/docs","id":"bringup-steps-schema","title":"The bring-up step tables in docs: bringup_steps, bringup_step_edges, step_status, the records bringup-step and bringup-edge, and the query bringup-chain","status":"done","note":"Landed: tables bringup_stages (the stage list as rows, so it changes with ikb bringup-stage and no schema change), bringup_steps, bringup_step_edges, step_status (declared only; a feed fills it); records bringup-step, bringup-edge (refuses a cycle, a self-edge, a group mixing hard and soft), bringup-stage; query bringup-chain [--device] with a computed ready/waits. Reviewed by the programmer subagent (group-name collision, UNION for the depth walk, stage tie, device guard fixed). tad check: 37 tables; make verify twice clean. Test research/bringup-steps/2026-11-18/bringup-chain-walleye.sh: was 'no query bringup-chain'; with the schema and seed it gets 26 steps in order and fails only for lack of claims (walleye kernel-reaches-init is unknown, not done): walleye-steps-claimed and feed-device-steps make it pass.","opened":"2026-11-18","waits":null,"blocked_by":null,"hardware":null,"needs":null,"device":null,"proof":"tad check passes with the three tables; tad r bringup-edge refuses an edge that closes a cycle; tad q bringup-chain answers with no device (every status unknown)","rank":null,"about":"bringup-steps"} {"project":"linux-phone-oco/docs","id":"bringup-steps-seed","title":"Seed the generic steps: 26 steps and 37 edges from walleye's real chain, surya's road checked against it","status":"done","note":"Landed: 8 stages, 26 steps and 37 edges recorded through ikb bringup-stage, bringup-step and bringup-edge (research/bringup-steps/2026-11-18/seed.sh, rerunnable). tad q bringup-chain lists 26 steps in order: stock-measured, stock-facts-read, slot-state-known and initramfs-gadget-emulated at depth 0, bootloader-unlocked at 1 (a soft need on stock-measured: an unlock may wipe the stock system), health-suite-runs last at 12; every status unknown until a base claims. Stages are rows of bringup_stages (prepare, boot, console, kernel, power, storage, userspace, lab), the draft awaiting the author's word: change them with ikb bringup-stage, no schema change. tad check passes; make verify twice clean.","opened":"2026-11-18","waits":null,"blocked_by":"bringup-steps-schema","hardware":null,"needs":null,"device":null,"proof":"tad q bringup-chain lists 26 steps, bootloader and stock steps at depth 0, health-suite-runs last; tad check passes","rank":null,"about":"bringup-steps"} @@ -193,3 +193,12 @@ {"project":"linux-phone-oco/docs","id":"milestones-step-terms","title":"Milestones name steps: step:ID@device in criteria, read from step_status by milestone-readiness","status":"open","note":null,"opened":"2026-11-18","waits":null,"blocked_by":"feed-device-steps","hardware":null,"needs":null,"device":null,"proof":"milestone-readiness counts a step term done only when step_status says done for that device; a walleye milestone 'reaches a shell' over step:shell-on-console@google-walleye reads ready","rank":null,"about":"bringup-steps"} {"project":"linux-phone-oco/lab-tools","id":"host-record-from-check","title":"lpoco host check writes the install record for a root file it proves in place, so the first plan after 0.15 asks no sudo","status":"done","note":"2026-11-18, lab-tools-builder: done (lab-tools #175, main 9458bfa). A passing share check (every measured device passed, at least one measured) records the staged hash of the polkit rule, share unit and helper that plan could not read and has no record for; check and prepare both do it. A file recorded with other content stays a root install; a failing check records nothing. Proof: host/tests/plan.rs a_passing_share_check_records_the_rule_it_proved_and_a_failing_one_records_nothing (seen failing first) and a_passing_share_check_does_not_vouch_for_a_rule_recorded_with_other_content. share::probe takes the fake root so /run state is testable. Not done: plan wording 'up to date' tied to the file's check passing. Limit: check now writes the install record.","opened":"2026-11-18","waits":null,"blocked_by":null,"hardware":null,"needs":"build","device":"xiaomi-surya","proof":"host plan test from fixtures: with no record and an unreadable rules folder, a passing share check records the staged hash and the next plan lists 0 root commands for it; a failing check records nothing","rank":5,"about":"lpoco-host-rest"} {"project":"linux-phone-oco/lab-tools","id":"restore-share-per-device","title":"Restore the per-device phone share (#164) and the 0.14.2 changelogs that #165 reverted","status":"open","note":"Found by orchestration, 2026-11-18, planning the lab at 0.17.0: the plan would replace the installed helper (from 0.14.2, with #164) with the older shape. lab-tools #165 (7b4a36a, Landed-by lab-tools-builder.5af81a), squashed from a branch based before #164 and release 0.14.2, removed #164's 133 lines from host/src/share.rs and the [0.14.2] sections of every CHANGELOG. #175 has since touched share.rs, so re-apply e764ffd's change on top of main by hand; do not revert #165, whose stale-piece check stays. The lab's 0.17.0 prepare is held until this is released. Same class as PR 170, which put back files PR 168 had added.","opened":"2026-11-18","waits":null,"blocked_by":null,"hardware":null,"needs":"build","device":"google-walleye","proof":"host/src/share.rs on main carries #164's per-share nft table and shared forwarding state again, with #175's recorded-rule change kept; a share test (two shares, stopping one leaves the other's table and forwarding) passes, and fails on today's main; lpoco host plan with the next release shows /usr/local/libexec/lpoco-share unchanged against the installed helper","rank":1,"about":"lpoco-host-rest"} +{"project":"linux-phone-oco/docs","id":"base-graph","title":"Every edge of the repository graph moved by a tool and checked, both ways: files down from one owner, changes up as items, rows up by feeds","status":"in-progress","note":"Decided 2026-11-18-device-layer-from-docs (research base-graph-measured, base-graph-world). graph-drift.sh: 36 FAIL today. Steps: device-layer-in-docs, docs-own-statements-up, docs-tables-idealkb-part, graph-drift-daily, tad-pins-every-base, lpoco-pin-follows (lab-tools), fork-tracking-job, template-follows-docs and template-classifies-its-files (device-template), surya-follows-template, walleye-follows-template; idealkb's side as upstream items idealkb-slice-from-prefix, idealkb-skip-unchanged-slice, idealkb-own-needs-item, idealkb-exit3-sends-up; git-rhizoid's scope as rhizoid-scope-every-edge.","opened":"2026-11-18","waits":null,"blocked_by":null,"hardware":null,"needs":null,"device":null,"proof":"research/base-graph/2026-11-18/graph-drift.sh exits 0","rank":null,"about":null} +{"project":"linux-phone-oco/docs","id":"device-layer-in-docs","title":"docs gives the device layer: device-layer/ holds the 10 statements and the marked device part of tables.toml (devices, parts, test_runs, test_results; steps when it lands), a generic list (#! pin = devicebase.toml, #! marker = device, #! from = device-layer/), and takes device-template's place in idealkb's ./sources","status":"open","note":"Decision 2026-11-18-device-layer-from-docs (1). docs' owner (orchestration) lands it. Waits on idealkb's from-prefix (upstream item idealkb-slice-from-prefix). The files move as device-template has them at d6eae9e; the template's list goes in the same week (template-follows-docs).","opened":"2026-11-18","waits":"idealkb: upstream item idealkb-slice-from-prefix","blocked_by":null,"hardware":null,"needs":null,"device":null,"proof":"research/base-graph/2026-11-18/graph-drift.sh: layer-owner and layer-follow ok for every device base","rank":null,"about":"base-graph"} +{"project":"linux-phone-oco/docs","id":"docs-own-statements-up","title":"docs' six own statements (about, decision, research, backlog, session-log, source) each go up to idealkb as an item or are dropped for idealkb's","status":"open","note":"Decision 2026-11-18-device-layer-from-docs (4). decision.sql lacks --supersedes/--amends/--scope/--tracked-by since idealkb 0.14.0 (this decision set them with ikb set). What docs adds (--project, a place per row) is the likely item: a base holding several places' records.","opened":"2026-11-18","waits":null,"blocked_by":null,"hardware":null,"needs":null,"device":null,"proof":"research/base-graph/2026-11-18/graph-drift.sh: own-behind ok for docs; ikb decision --supersedes accepted in docs","rank":null,"about":"base-graph"} +{"project":"linux-phone-oco/docs","id":"docs-tables-idealkb-part","title":"docs' tables.toml carries idealkb's marked part, so new generic fields and rules reach it at the follow","status":"open","note":"Decision 2026-11-18-device-layer-from-docs (4); idealkb's gap tables-own-drift. docs' tables.toml has no idealkb:begin today.","opened":"2026-11-18","waits":null,"blocked_by":null,"hardware":null,"needs":null,"device":null,"proof":"research/base-graph/2026-11-18/graph-drift.sh: own-part ok for docs","rank":null,"about":"base-graph"} +{"project":"linux-phone-oco/docs","id":"graph-drift-daily","title":"graph-drift.sh runs daily in docs' CI and each FAIL line becomes an item for the edge's owner","status":"open","note":"Decision 2026-11-18-device-layer-from-docs (5). Read-only, needs gh and the clones it reads (or fetches).","opened":"2026-11-18","waits":null,"blocked_by":null,"hardware":null,"needs":null,"device":null,"proof":"a scheduled run of the workflow, red today with the 36 FAIL lines, green when every edge holds","rank":null,"about":"base-graph"} +{"project":"linux-phone-oco/docs","id":"tad-pins-every-base","title":"Every base that installs tad is on tad-engine's consumers list and at its latest release (docs' CI is on 0.6.0)","status":"open","note":"tad-engine's owner adds device-template, surya-lab, google-walleye-lab to consumers; the weekly job then moves docs too.","opened":"2026-11-18","waits":null,"blocked_by":null,"hardware":null,"needs":null,"device":null,"proof":"research/base-graph/2026-11-18/graph-drift.sh: tad-pin ok for every base","rank":null,"about":"base-graph"} +{"project":"linux-phone-oco/lab-tools","id":"lpoco-pin-follows","title":"lab.toml's lpoco pin is moved by a job when lpoco releases, or says why it holds","status":"open","note":"Decision 2026-11-18-device-layer-from-docs (5). lab.toml (grenudi/lab-machine) pins 0.15.0, lpoco-v0.17.0 tagged the same day. The pin is the lab machine's; the job is the later rhizoid tool-pin edge.","opened":"2026-11-18","waits":null,"blocked_by":null,"hardware":null,"needs":null,"device":null,"proof":"research/base-graph/2026-11-18/graph-drift.sh: tool-pin ok","rank":null,"about":"base-graph"} +{"project":"linux-phone-oco/docs","id":"fork-tracking-job","title":"A daily lab job fetches each fork's upstream into its tracking branch, test-merges every topic onto it and retires topics upstream carries (git cherry)","status":"open","note":"Decision 2026-11-18-device-layer-from-docs (6); the upstreams lane's. grenudi/sxmo-utils master is 4 behind sr.ht today.","opened":"2026-11-18","waits":null,"blocked_by":null,"hardware":null,"needs":null,"device":null,"proof":"research/base-graph/2026-11-18/graph-drift.sh: fork-track ok for grenudi/sxmo-utils and grenudi/linux","rank":null,"about":"upstream-forks"} +{"project":"linux-phone-oco/device-template","id":"template-follows-docs","title":"device-template becomes a device base like the others: it pins idealkb and docs (devicebase.toml source/version), drops its generic list, keeps its made-once files","status":"open","note":"Decision 2026-11-18-device-layer-from-docs (2). The template builder's work, reshaped: the classification and made-once list stand; no template release.","opened":"2026-11-18","waits":null,"blocked_by":"device-layer-in-docs,template-classifies-its-files","hardware":null,"needs":null,"device":null,"proof":"research/base-graph/2026-11-18/graph-drift.sh: layer-pin, layer-owner ok for device-template; template-drift.sh classified ok","rank":null,"about":"device-template"} diff --git a/data/decisions.json b/data/decisions.json index af2d98d..98e881c 100644 --- a/data/decisions.json +++ b/data/decisions.json @@ -70,3 +70,4 @@ {"id":"2026-11-18-upstream-forks","brief":"Our forks live under grenudi (the org copies transferred there); topic per upstream item, never-rebased lab branch, phones via a tagged lab apk and the labs kernel routes; one upstreams lane","project":"linux-phone-oco/docs","date":"2026-11-18","decision":"Forks: grenudi/sxmo-utils (upstream fork-sxmo-utils, a mirror of sr.ht) and grenudi/linux (fork-linux, a fork of sm7150-mainline/linux) - the organisation's two repositories transferred to the author's account, so one home holds the history; old linux-phone-oco/ URLs redirect, and new references name grenudi. Branches in each: the tracking branch (sxmo master; the kernel's upstream tags and v7.x) mirrors upstream and is never edited; one topic branch per upstream item, named topic/ITEM-ID (sxmo) or topic/ITEM-ID, fix/, dt/ (kernel), off the base its upstream takes, a series of its own, rebased only before a send (it is unsent, so ours); an integration branch per consumer that merges the topics and is never rebased - sxmo lab, kernel test/DEVICE-WHAT - tagged lab-YYYYMMDD.N where a build pins it; a topic is retired when upstream carries it (upstream-state landed, carried-in none, the branch deleted). Each patch carried is an upstream item with --carried-in FORK/BRANCH, so tad q carried says what to keep at the next rebase. How it reaches the phones: sxmo-utils as an APKBUILD in lab-tools packaging forked from Alpine's (all subpackages, source the fork's lab tag, pkgver 1.18.1_pDATE), built and signed by the package conveyor, installed as sxmo-utils@lab from the tagged lab repository so an apk upgrade keeps it; kernels by each lab's own route from a test/ branch (surya-lab test kernels from branches, walleye v7.3 + own dts). rhizoid is not used yet: plain git with this rule; what rhizoid needs to carry it is sent to git-rhizoid as a finding (rhizoid-carries-mail-forks).\nWho coordinates: one upstreams lane - a lane coordinator for all forks and every outgoing series, started by orchestration when its queue holds work (now: two series); it keeps the branch rule, prepares each series and its upstream item, and queues the proofs: needs=phone rows go to the device keepers (surya, walleye), needs=build to the builders. Split into a lane per upstream project when one project holds more than about five open items or its own review traffic.\nThe fixes, each on its topic and proven before any mail: (1) sxmo autosuspend backs off 1..64 s after failed suspends; (2) the device profile names services stopped around suspend (SXMO_SUSPEND_STOP_SERVICES), stopped before a second read of the wakeup count, started after - the Pixel 3a case moves into its profile; (3) surya's profiles name its sensors daemon - one sxmo series of three. (4) The way back from a suspend that never returns is the PMIC watchdog (pm8916_wdt on gen2 PON: pm6150, pm8998) kept running through suspend only when its bark may wake the system and a pretimeout is set - an RFC series of four to linux-watchdog; the qcom-wdt module parameter stays lab-only until (4) is proven, and its upstream question is superseded. Mail only on the author's word, from his clone, signed off by him (kernel: Assisted-by: LLM).","why":"The author's direction: forks of each project, the best fixes worked there per project, then mailed upstream as concrete working patches (research upstream-forks-landscape). The forks he asks for already exist under his organisation, and the organisation is where the project's repositories and records already live; a second fork elsewhere would split history and records, and sourcehut cannot be forked on GitHub anyway. A topic per upstream item is what a mailing list takes (a series per question, rebased on master), and a never-rebased integration branch is what a consumer can pin - rhizoid's tracking/patch split, with the patch branch cut per item. The tagged apk repository is the only route an apk upgrade does not undo, and the package conveyor already signs and publishes. One lane is enough for two series; a lane per project would hold two idle coordinators. Fix 2's form answers the reason the same idea was refused in 2024 (research sxmo-suspend-fixes); fix 4 follows the only shape upstream has taken (a wake IRQ watchdog) on the one watchdog that keeps counting while the SoC sleeps, and the APSS watchdog is known to freeze there - why try 4 had no bite (research pmic-wdt-way-back). Amended the same day on the author's word ('yes, and lets keeps them under my account for simplisity'): the forks live under grenudi. The org's two repositories were transferred to grenudi (GitHub transfer: one history, branches, issues and the fork link to sm7150-mainline kept; old linux-phone-oco/ URLs redirect), so there is one home and no duplicate.","rejected":"Keeping the forks in the organisation (the first form of this decision): the author chose his account for simplicity. New grenudi forks beside the org copies, or archiving the org copies: two histories, and the open issues and PRs of linux-phone-oco/linux (7) and the lane branches would stay behind - a transfer moves them whole. A fork of pmaports or of Alpine aports for sxmo: our own APKBUILD in lab-tools packaging carries it without a third fork. make install or pmbootstrap build --src onto the phone: undone by the next apk upgrade, no identity. rhizoid as the tool now: its CLI is stubbed and parked, and it lacks non-GitHub tracking, topic series, mail send-back, retirement and apk pins. A lane coordinator per upstream project (sxmo, kernel): two long-lived sessions for two series, each needing the keepers anyway; one patch branch per fork merged from tracking (rhizoid's literal form): a mailing list needs a series per item, and one branch mixes them. For fix 2: a list stopped inside sxmo_suspend.sh (refused 2024: the wakeup count race); suspending through logind/systemd so distro sleep hooks run (asynchronous against sxmo's time accounting, the same race, and the lab's systemctl suspend path is the one surya did not return from). For fix 3: the qcom-wdt keep_armed_in_suspend parameter upstream (refused as policy for imx2 in 2025-26, and the APSS counter freezes in the deepest sleep); qcom-wdt with its bark as a wake IRQ (the freeze makes it useless); a DT property that keeps a watchdog running (OS policy, not DT).","about":"upstream-forks","research":"upstream-forks-landscape","supersedes":null,"amends":null,"scope":null,"tracked_by":null} {"id":"2026-11-18-device-template-follows-by-release","brief":"device-template is followed like idealkb: it names every file followed or made once, releases, labs pin it and update-pins lays it; template-drift fails CI on drift; no more hand fan-out","project":"linux-phone-oco/device-template","date":"2026-11-18","decision":"device-template becomes a second source in the pin-and-follow slice that idealkb already runs (carrying out idealkb decision 2026-11-17-chain-follow-by-slice for the template, and docs item device-template-follow):\n1. It names every file it has: `generic` (followed - laid at the pinned release, never edited in a lab unless the lab names it in own) and a new `made-once` list (laid at creation, then the lab's own: device.toml, oco.toml, README.md, devicebase.toml, idealkb.toml, provision/packages.txt, .oco/uncommitted, data/). The skeleton moves into generic: Makefile, bin/install-tad.sh, tad.yml, gather.yml, .gitignore, tests/health/README.md and the template's script check, in a workflow file a lab does not extend (a lab's own jobs go in its own file). AGENTS.md's general conventions get a template:begin/end part laid like idealkb's. The three hardware files leave the template's list: idealkb gives them; a file has one source.\n2. It releases (release-please, from v0.1.0); devicebase.toml names the release (template = \"0.1.0\") and own = [...] for template files a lab keeps as its own; a lab carries no copy of the list.\n3. idealkb's follow.sh and update-pins take their source from the pin (idealkb item follow-source-from-pin), and the template lists its consumers: one hourly job moves both pins, each through the lab's CI, idealkb first.\n4. template-drift (research material, failing today) runs in the template's CI (classified, one-source) and in each lab's (pin, equal, no-copy), so a hand edit or a stale lab fails at the PR, not at the next bump.\n5. A change to the device layer lands in the template only; labs get it by the release bump. What proves general for every base goes on to idealkb, as hardware did, and leaves the template's list in the same release.\nLogic never enters the template (decision 2026-11-17-the-phone-is-data): it reaches labs as lpoco by pin. device.toml's shape is the schema's (decision 2026-11-18-device-manifest-schema-from-rust, template-manifest-schema), not this list's. When git-rhizoid's slice-consumption works, the job moves there; follow.sh is its prototype.\nMigration: surya-lab - drop the list copy, take check.yml and tests/health/README.md, pin the release (about an hour, through its first bump); google-walleye-lab - drop the copy, move its rust job to its own workflow, close stale #208, pin (about an hour). Template: classify and release (2-3 h), the check in CI (2 h); idealkb's follow-source-from-pin (about 3 h, idealkb's owner). About one agent-day in all, no phone.","why":"The author asked how drift is prevented (2026-11-18). Measured (research device-template-drift-measured): it is not - 13 statements were carried to each lab by hand in parallel PRs (9 PRs, one still open and stale), each lab carries a stale copy of the list, three files have two sources and every idealkb release since 0.14.0 opened a false-alarm PR in all three bases, closed by hand; devicebase.toml's pin is a date true of no lab. The mechanism to fix it exists and was already chosen for the template (chain-follow-by-slice); what is missing is small and named: the template's release, its classification, a check that fails, and follow.sh reading its source from the pin. Others agree (research device-template-follow-world): cruft and copier carry a template by a pin and a failing check; projen and copier name which files are kept in step and which are made once.","rejected":"Keep carrying changes by hand into each lab: it does not scale past two labs; it already left a stale PR, stale list copies and a date for a pin; nothing names drift. Copier or cruft: Python (refused here), a second state file beside the pin, a template engine and three-way merge for repositories that are data. GitHub template plus actions-template-sync: -X theirs overwrites a lab's data and surya-lab has no template history. git subtree or submodule: tad reads queries/, records/ and tables.toml at the root; a prefix breaks it. git-rhizoid now: its slice-consumption is open and its CLI stubbed - the later home, not today's (its items stay on its backlog). The device layer moved wholesale into idealkb: idealkb is domain-free; only what proves general moves, one file at a time. The device layer shipped by lpoco as a 'base follow' command: a third follow mechanism beside follow.sh. Generating every lab file from device.toml (no template files at all): tad needs its statements in the tree, and the schema decision already removes the one file worth generating.","about":"device-template","research":"device-template-drift-measured","supersedes":null,"amends":null,"scope":null,"tracked_by":"device-template-follow"} {"id":"2026-11-18-bringup-steps-generic-in-docs-status-in-each-base","brief":"Bring-up steps: generic steps and their hard/soft edges in docs; each device base claims its status per step with proof and run; docs pulls it, unclaimed = not known yet","project":"linux-phone-oco/docs","date":"2026-11-18","decision":"Bring-up steps become data, in two halves joined the way parts already are (decision 2026-11-17-commons-and-device-bases).\n1. docs, the commons, keeps the generic steps: bringup_steps (id, title, stage of prepare/boot/console/kernel/power/storage/userspace/lab, ord, applies: any or a class such as boot:android, usb:gadget, power:battery, done_when, proof: a stable check name, proof_kind of host-check/phone-suite/build-check/witness/research, helper: the lpoco command or none, component: the catalogue part whose first light it is, guide: how it is done and the traps met with the records that met them, sources, checked_on) and bringup_step_edges (step, requires, kind hard or soft, group: edges sharing one are alternatives, why). Recorded by tad r bringup-step and bringup-edge; the edge record refuses a cycle. A step first met on one device goes in the catalogue scoped by applies, so there is one graph.\n2. Each device base claims its own status per step: a steps table (step, status of done/partial/failing/open/not-needed/unknown, proof: the check it ran, run: the record or test run, proven_on: the image or kernel hash, notes, updated), contract steps = 1 in devicebase.toml, recorded by tad r step. It ships in device-template only and reaches the labs by the template's release (decision 2026-11-18-device-template-follows-by-release); never copied by hand.\n3. docs pulls the claims into step_status (device x step) by records/feed-device-steps.sql, as feed-device-parts does. A step a base never claimed is unknown, \"not known yet\"; a base unreadable or without steps = 1 gives every step unknown and why. A new device made from the template starts with data/steps.json empty, so every step is not known yet until its base claims it - measured-not-claimed. A claim does not expire by age (a passed step stays passed for what it was proven on); proven_on lets a later kernel be told from it, and the runner re-proves.\n4. tad q bringup-chain [--device D] reads them: each step in order (depth over all edges, then stage, then ord), its status, proof, run, needs, and ready (every hard need done or not-needed, one per group) or waits - readiness computed, never stored.\n5. The guidebook is rendered from the same rows by make render into docs/guidebook.md: a chapter per stage, each step's done-when, needs, proof, helper or the gap, guide, and a column per device; verify keeps it fresh.\n6. The helpers map by the helper field: today lpoco bringup image pack/check/swap/bisect, initramfs build, lpoco lab fastboot, flash, provision, suite; a step with none is a helper to write. Later one runner walks ready steps: runs the helper, then the proof, and claims the result in the device's base; a step that changes the phone goes to its keeper's queue (half automated).\n7. Milestones may name step:ID@device as they name component: and feature:, so \"boots\" becomes a set of steps.\nSchema, records, query, seed (26 steps, 37 edges) and the failing test: research/bringup-steps/2026-11-18/. The tables, records and queries are docs' owner's to land (AGENTS.md); they are queued, not landed here.","why":"The author: the precise work of a bring-up is folded under \"boots\"; he wants every step, how it relates to the ones before and after, a guidebook made from the data, small helpers per step and later a runner; and the general table used by each device base for where it stands (2026-11-18). Measured (research bringup-steps-landscape): walleye's 26 steps are real and each done one has a check and a record; surya's road shows why steps need applies and not-needed; nobody outside keeps steps with edges and proofs, but each piece exists (Nura's per-device Cargo table, LAVA ids and expected lists, BitBake typed edges and stale stamps, Taskwarrior's computed READY, openQA hard/soft). The parts join already works between docs and two bases, so the step status needs no new mechanism. The draft ran in a scratch clone: checks pass, the chain orders, walleye's ready steps are its keeper's real queue.","rejected":"Steps as more components or more feature_support rows (a step is not a part: it has order and edges, and parts would mix \"the kernel reaches init\" with \"the speaker plays\"); steps per device only, in each lab (no shared graph, no guidebook, the next device starts from nothing); status typed in docs (decided against for parts on 2026-11-17: copies drift); edges as a comma list in the step row (no kind, no alternatives, no cycle check); the backlog as the step graph (backlog is one device's work and its tries; a step is generic and outlives the items that did it - items stay linked by run); an issue tracker DAG (beads, GitHub blocked-by: edges without proofs, outside the base); per-driver probe assertions as steps (bootrr's lesson: unstable names, per-board lists; a probe check can be a step's proof, derived from the devicetree as Collabora's kselftest does); a 30-day expiry as for parts (a step proven on an image stays proven for it; proven_on and the runner's re-proof answer regressions); a generated guidebook from prose pages (Nura's guide is hand-written and being rewritten).","about":"bringup-steps","research":"bringup-steps-landscape","supersedes":null,"amends":null,"scope":null,"tracked_by":"bringup-steps"} +{"id":"2026-11-18-device-layer-from-docs","brief":"The device layer comes from docs: idealkb, then docs, then every device base, the template one of them; own needs an item, edits go up as PRs, one drift check; rhizoid later, by conformance","project":"linux-phone-oco/docs","date":"2026-11-18","decision":"Supersedes 2026-11-18-device-template-follows-by-release (its classification, made-once list, failing check and hourly job stay; the source of the device layer moves). The author's picture, taken with one correction: the template is a device base, but it is also the seed new bases are copied from, so it keeps its made-once files.\n1. Three layers of files, each file one owner at the layer that owns its meaning: idealkb (domain-free) -> docs (the commons) -> every device base. docs gives the device layer: the statements a device base runs (phone-queue, phone-next, parts, part, device, backlog-status, backlog-needs, test-run, lane-next, phone-stands) and a marked part (marker device) of tables.toml declaring devices, parts, test_runs, test_results and, when it lands, steps - kept in docs under device-layer/, beside the catalogues and the feeds that read the claims, so a contract change (parts, steps) is one change in one repository. docs' generic list says #! pin = devicebase.toml, #! marker = device, #! from = device-layer/ (read from that folder in docs, laid at the base's root: idealkb's follow.sh, item idealkb-slice-from-prefix). docs takes device-template's place in idealkb's ./sources; docs already releases; the job moves a base's device-layer pin only when a file of the list changed (idealkb-skip-unchanged-slice), so a docs release that does not touch the layer opens nothing. Each base pins each source it takes files from, by name (Gentoo's masters): idealkb.toml and devicebase.toml (source = \"linux-phone-oco/docs\", version, own).\n2. device-template is a device base like the others: it pins idealkb and docs, its CI runs the checks a lab runs, and docs' release gate asks it first (followers-answer). It gives nothing by a list; it keeps the made-once files (device.toml example, README, devicebase.toml, idealkb.toml, oco.toml, provision/packages.txt, data/ empty) that Use this template copies, so a new base is born pinned. Its generic list goes; template-drift.sh keeps its classified check.\n3. Files come down, rows go up, changes go up as change requests. Claims (parts, steps) stay pulled by docs' feeds at main. A change to a followed file is made at its owner, upstream first (the kernel's rule): a base that needs one opens it in docs or idealkb and the pin brings it back within the hour. When a base edits a followed file anyway, the job, besides its PR in the base, opens the same change as a PR on the source at the pinned release and records an upstream item in the base (copybara's change request; idealkb-exit3-sends-up).\n4. own is a named override with a status (Yocto's Upstream-Status, DEP-3): a file a base keeps as its own may differ from its source only while an upstream item of the base names it (on its way up) or the pin file says why it stays (own_why); a base whose tables.toml is its own keeps the source's marked part as the pin gives it. Otherwise the follow fails (idealkb-own-needs-item). docs' six own statements go first: each goes up to idealkb as an item or is dropped for idealkb's (docs-own-statements-up).\n5. One drift check over every edge, run on a schedule, each FAIL an item for the edge's owner (linux-next's way): graph-drift.sh (research material) in docs' CI daily - slices, own, the device layer, tad pins and their consumers, the lpoco pin in lab.toml, fork tracking.\n6. Forks: a daily lab job fetches each fork's upstream into its tracking branch (sxmo master from sr.ht) and test-merges each topic onto it, a conflict reported as an item; a topic upstream carries is found by git cherry (patch-id) and retired. Decision 2026-11-18-upstream-forks otherwise unchanged.\n7. git-rhizoid exists, scoped as the follow tool for every edge a repository has - a slice, a tool pin, a cutting - with one status over them all and both directions; never a template engine, a merge of data or rows (feeds stay docs'). Built after 1-6 work, in order, each replacing shell only once it passes the shell's tests: status (read-only; passes graph-drift.sh), follow (passes idealkb's bin/test-follow.sh fixtures byte for byte and keeps the three things idealkb names: the pin names its source, one owner per file, the followers' gate before a release - then update-pins calls it), send-back (the change request and the item), cuttings (tracking from any git URL, topic and integration branches, retire by patch-id, a distro package pin). Until then the shell is the tool.\nMigration, about two agent-days, no phone: idealkb from-prefix and skip-unchanged (~2 h), own-needs-item (~2 h), exit3-sends-up (~3 h) - idealkb's owner; docs device-layer/ with its list and the sources switch (~3 h), its own statements up (~2 h), its tables' idealkb part (~1 h), graph-drift daily (~1 h) - docs' owner; the template turned into a follower (~1 h); each lab: devicebase.toml names docs, drops its list copy, takes the device part at the first follow (~1 h each); tad consumers +3 and docs' tad (minutes, tad-engine's owner); lpoco pin moved by a job or says why it holds (~1 h); the fork tracking job (~2 h). rhizoid after: status ~1.5 days, follow by conformance ~2, send-back ~1, cuttings ~2-3.","why":"The author (2026-11-18): develop git-rhizoid without reimplementing a wheel; the device-template's graph got mixed up - docs' shared parts should be inherited by every device base, the template being one more device, with changes pulled and pushed upstream with the least resistance and drift. Measured (research base-graph-measured): 12 edges, 3 moved by a job, 6 by hand, 5 behind today (graph-drift.sh: 36 FAIL); nothing carries a change up - own is a one-way exit (docs' six own statements differ from idealkb's and no item names them; docs cannot record --supersedes through its record, missing since idealkb 0.14.0), an edited followed file stops at a person; the parts contract is declared by the template and read by docs, and bring-up steps would repeat that split. The world (research base-graph-world): every mature layered project gives a file one owner at the layer that owns its meaning, names its overrides with an upstream status that fails when missing (Yocto, DEP-3), pins each ancestor by name (Gentoo), works upstream first (the kernel) and reports drift on a schedule to each owner (linux-next); no Rust or shell tool carries root-level files down and changes up but copybara (JVM), and idealkb's follow.sh already lays slices in ~250 tested lines. So the gaps are rules and one owner, not a new mechanism: moving the device layer to docs puts each contract in one repository and removes a release train and a third owner of 14 files at about one agent-day more than the superseded route; rhizoid is worth building because the gap is real, but only behind the shell's own tests.","rejected":"The superseded route as it was (the template a middle source with its own releases): the parts and steps contracts stay split between the template (declared) and docs (read), a third release train and owner for 14 files, and docs' catalogue ids still reach no base; about one agent-day, but it keeps the mix-up the author named. The device layer at docs' root: docs would carry phone queries over tables it does not have. Device bases following all of docs: docs' statements are the commons', not a device's. The layer into idealkb: idealkb is domain-free; what proves general moves there one file at a time, as hardware did. A chain of four (idealkb, docs, template, labs): every contract change two hops. The template only a GitHub template with no pin: the next base is born unpinned. git subtree, subrepo, submodules: a prefix, and tad reads its statements at the root. josh: one monorepo as the truth, a base cannot keep its own variant, a proxy to run, push back between separate repositories unknown. copybara: a JVM 21 and Starlark for 7 followers in 2 directions; its change request is taken, not its runtime. Android repo, copier, cruft, gbp-pq, b4: Python, refused; copier/cruft also have no way up. Nix inputs: the store, not files, and no patching in place. stgit: fine on a topic branch by hand, not needed by the graph; topgit: dormant. Labels that only warn (DEP-3: 9.4% forwarded): own without an item fails. git-rhizoid now, replacing follow.sh: the shell works and is tested; a port without conformance risks every base, and the gaps are rules, not tooling. git-rhizoid never: the author asks for it, and both directions for root-level slices and the cutting case have no tool in the house's languages.","about":"device-template","research":"base-graph-measured","supersedes":"2026-11-18-device-template-follows-by-release","amends":null,"scope":"docs (owner orchestration), idealkb (its owner), device-template, surya-lab, google-walleye-lab, lab-machine, tad-engine, the upstreams lane, git-rhizoid; the template builder","tracked_by":"base-graph"} diff --git a/data/research.json b/data/research.json index 2395371..4bc02f9 100644 --- a/data/research.json +++ b/data/research.json @@ -57,3 +57,6 @@ {"id":"device-template-how-it-stands","brief":"device-template's children follow it by hand and drift unseen; decided: followed by release like idealkb, template-drift failing in CI; 6 items queued, first the classification","project":"linux-phone-oco/device-template","date":"2026-11-18","question":"Where does device-template's inheritance stand, and what is next?","found":"How it stands, 2026-11-18. device-template (a GitHub template, made 2026-11-17 from what surya proved) has two children: surya-lab (re-based by hand) and google-walleye-lab (Use this template). idealkb's slice reaches all three by update-pins; the template's own slice reaches the labs only by hand - its 13 statements are equal today because each change was landed three times, and 8 drifts are named that nothing catches (research device-template-drift-measured: stale list copies, three files with two sources and false-alarm bump PRs each idealkb release, surya's check.yml and tests/health/README.md, a date for a pin, walleye's stale PR 208, the manifest's shape).\nDecided (2026-11-18-device-template-follows-by-release, research device-template-follow-world): the template is followed like idealkb - every file named generic or made-once, a release pinned in devicebase.toml, laid by the same hourly update-pins once idealkb's follow-source-from-pin lands, and template-drift failing CI on drift. Queue, unranked: device-template template-classifies-its-files, template-releases, template-drift-in-ci, template-followed-by-update-pins; surya-lab surya-follows-template; google-walleye-lab walleye-follows-template. The failing test: research/device-template/2026-11-18/template-drift.sh (exit 1 today). device.toml's shape is template-manifest-schema's. The umbrella is docs item device-template-follow (orchestration's), which this carries out.","sources":"rhizoid-repo,idealkb-chain-follow","about":"device-template","material":null,"supersedes":null} {"id":"bringup-steps-landscape","brief":"No one keeps bring-up steps as data with edges and proofs; walleye's real chain is 26 steps (17 done with proofs), surya's another road; docs' parts join carries step status as is","project":"linux-phone-oco/docs","date":"2026-11-18","question":"How should linux-phone keep every small step of bringing Linux up on a machine - what it needs, what it enables, its proof - generic for any machine, with each device base recording where it stands, so a guidebook, helpers and later a step runner can be made from it; and how do others do it?","found":"What is: the step-level truth of a bring-up lives only in each lab's backlog, session logs and research, folded on the face into \"boots\" or \"kernel\". Walleye's chain, rebuilt from google-walleye-lab: 26 steps from the bootloader read to the health suite, 17 done (each with a host check and a record: y1 alive by gpio-reserved-ranges and no earlycon, y2's gadget, banner2, z6's shell, z7's dmesg-clean and PMIC), 2 partial (stock measure, crash window: pstore yes, UART no), 1 failing (charger: c2 defers on tps61099), 6 open (UART, watchdog, UFS, USB network, rootfs, suite). Surya's chain (27 steps from surya-lab and docs) took another road: a distribution that already booted through U-Boot, systemd-boot and EFI, so its image, dtbo and stock-kernel steps are not-needed and PMIC and charger are not known. lab-tools has helpers for the image (lpoco bringup image pack/check/swap/bisect, initramfs build), fastboot, flash, provision, suite and suspend; none for UART, devicetree, banner, shell, PMIC, charger. The health suite's checks prove only the steps after a rootfs. docs already has the join this needs: components in docs, parts claimed in each device base (contract parts = 1), pulled by feed-device-parts into support_status, unclaimed = not known yet (decision 2026-11-17-commons-and-device-bases).\nOthers: nobody keeps bring-up steps as data with edges and a proof per step. Order is prose (Nura's porting and mainlining guides, UBports, Sailfish HADK, Qualcomm cover letters: boot to shell first); per-device status is a person's tick (Nura's Infobox Cargo table, Asahi's feature pages); proofs are flat lists (bootrr, dropped for unstable names and per-board lists; Collabora's DT probe kselftest; LAVA boot stages and test-case ids); dependencies are data only where machines run them (BitBake typed edges and input-keyed stamps, KernelCI, openQA fatal/ignore_failure, beads and Taskwarrior's computed READY). Nura's categories are levels as sets of checks.\nTried: the three tables, two records and the chain query in a scratch clone of docs: tad check passes, the edge record refuses a cycle, the generic chain orders 26 steps in 13 depths, walleye's claims give the queue walleye's keeper already has as ready (charger, watchdog, UFS, USB network), and the failing test passes with them and fails when one is removed.","sources":"nura-porting-guide,nura-infobox-device,nura-device-categorization,nura-hardware-ci,nura-mainlining-guide,asahi-feature-support,bootrr,collabora-dt-probe-kselftest,yocto-bsp-guide,yocto-compatible,bitbake-task-deps,lava-boot-action,lava-test-definition,kernelci-pipeline-config,openqa-docs,beads-issue-graph,github-issue-dependencies,taskwarrior-virtual-tags,ubports-porting,sailfish-hadk-subsystems","about":"bringup-steps","material":"research/bringup-steps/2026-11-18/","supersedes":null} {"id":"bringup-steps-how-it-stands","brief":"Bring-up steps: decided (generic in docs, claimed per device base, pulled like parts), not built; 10 items unranked, first the schema the owner lands; the failing test is in the material","project":"linux-phone-oco/docs","date":"2026-11-18","question":"Where do bring-up steps as data stand, and what comes first?","found":"How it stands, 2026-11-18. Decided, not built: decision 2026-11-18-bringup-steps-generic-in-docs-status-in-each-base (research bringup-steps-landscape). Drafted and tried in a scratch clone, in research/bringup-steps/2026-11-18/: the three tables (schema.toml), the records bringup-step and bringup-edge, the query bringup-chain, a seed of 26 steps and 37 edges, walleye's 26 claims (17 done, 2 partial, 1 failing, 6 open), and the failing test bringup-chain-walleye.sh (fails on main: no query). Queue, unranked, for the author: docs bringup-steps-schema (the owner's to land), bringup-steps-seed, feed-device-steps, bringup-guidebook, milestones-step-terms; device-template steps-contract (after template-releases); google-walleye-lab walleye-steps-claimed and surya-lab surya-steps-claimed (after their template follow); lab-tools bringup-steps-helpers, then the research bringup-step-runner. Umbrella: bringup-steps. Open for the author: the stage list and the size of a step (26 for walleye's road so far); whether milestones should be rewritten as step sets; whether a claim should ever lapse by age (decided no: proven_on instead).","sources":"bitbake-task-deps,lava-test-definition,nura-infobox-device","about":"bringup-steps","material":null,"supersedes":null} +{"id":"base-graph-measured","brief":"The graph measured: 12 edges, 3 moved by a job, 6 by hand, 5 behind today; own files are a one-way exit and nothing carries a change up; the parts contract has two homes","project":"linux-phone-oco/docs","date":"2026-11-18","question":"What is the real dependency graph of idealkb, docs, device-template, the device bases, lab-tools and the forks: who pulls what, which way, by which tool, and how does drift show (the author, 2026-11-18)?","found":"Measured at origin/main of each (idealkb v0.16.0, docs 608b61f, device-template d6eae9e, surya-lab 42da677, google-walleye-lab f0e0fc2, lab-machine fb75285), read only.\nFiles go down: idealkb's slice reaches docs, ideal-agent, device-template and both labs by follow.sh/update-pins (hourly, every pin 0.16.0, current; since 0.16.0 a source names its pin and marker, ./sources lists device-template, skipped until it releases; check-one-owner stops two owners). device-template's 10 statements and the 4 device tables (devices, parts, test_runs, test_results - outside any marker) reach the labs by hand; the pin is a date. tad reaches every base by a weekly job whose consumers list lacks the three device bases; docs' CI runs tad 0.6.0, the rest 0.7.1. lab.toml pins lpoco 0.15.0 by hand; 0.17.0 was tagged the same day. sxmo-utils master on grenudi is 4 commits behind sr.ht, nothing fetches it; grenudi/linux is a GitHub fork, current.\nRows go up: docs pulls each lab's parts.json at main by DuckDB (contract parts = 1); component ids agree today by hand (none unknown) and nothing carries docs' catalogue or step ids down.\nChanges go up: nowhere by a tool. A followed file edited below ends follow.sh with 3 and a PR in the follower for a person; nothing reaches the source. own is a one-way exit: docs keeps 7 own files, 6 statements differ from idealkb's (decision.sql lacks --supersedes/--amends/--scope/--tracked-by since 0.14.0, so docs cannot record a superseding decision through its record; 0 decisions carry either), docs' tables.toml has no idealkb part, each device base's own tables.toml lacks 101 lines of idealkb 0.16.0's part; no upstream item names any of it (docs: 0 items to idealkb or the template; labs: 0).\nThe parts contract has two homes: declared by device-template, read by docs; bring-up steps will repeat it (catalogue in docs, claim table in the template). Every contract change is two PRs in two repositories and two release trains.\nIn all: 12 edges, 3 moved by a job (idealkb slice, tad, docs feeds), 6 by hand, 5 behind today. Failing test graph-drift.sh in the material: exit 1, 36 FAIL, 9 ok.","sources":"idealkb-chain-follow,rhizoid-repo,rhizoid-design-log","about":"base-graph","material":"research/base-graph/2026-11-18/","supersedes":null} +{"id":"base-graph-world","brief":"Only copybara (JVM) carries root-level files down and changes up; layered projects share four rules: one owner per file, named overrides with a status, fatal pins, a scheduled integrator report","project":"linux-phone-oco/docs","date":"2026-11-18","question":"What exists in the world for a chain of repositories that share files and must let changes travel both ways - subtree, submodules, josh, copybara, gbp-pq/quilt, stgit, topgit, Nix inputs, Yocto layers, Android repo, Gentoo/Arch overlays, copier/cruft, the kernel's maintainer trees - and what does each cost here (Python refused, Rust with argenv the house way)?","found":"Down and up, root-level files: subtree and subrepo carry a whole directory both ways (split/push) but need a prefix, and tad reads its statements at the root; submodules pin a repository at a path, no files at the root. Android repo copies files outside any project's history (Python). Nix inputs live in the store and cannot be patched in place (nix#3920); update-flake-lock bumps only. copier/cruft: pin + \"behind\" and \"edited\" checks, down only, Python. Renovate, multi-gitter, turbolift, microplane: a pin bump or a script per repo with a PR, down only. copybara alone does both: a follower's PR becomes a change request on the source, GitOrigin-RevId records the import, check_last_rev_state fails when the destination changed, merge_import keeps a destination's own lines - at the cost of a JVM 21 and Starlark per workflow. josh (Rust) selects single files at the root (::f, ::dest=src) and pushes back through a view, but its truth is one monorepo and a follower cannot keep its own variant; push back from separate repositories is unknown. No Rust or shell tool does root-level slices both ways: idealkb's follow.sh is the house's answer and the gap is real.\nLayering: Yocto (oe-core, distro, BSP): one owner per recipe, overrides as named .bbappend files, a dangling append an error, LAYERSERIES_COMPAT fatal, Upstream-Status required on every patch and an error by default, yocto-check-layer forbids a BSP changing others' signatures - the middle layer owns the contract the lowest is checked against. Gentoo: masters non-transitive (each overlay names every ancestor, as each base here pins each source), MasterPackageClobbered an error (check-one-owner). DEP-3: Forwarded/Applied-Upstream on each patch, yet 9.4% forwarded in trixie - a status that only warns moves nothing. Kernel: upstream first, a copy says \"commit X upstream\", linux-next merges every tree on a schedule and mails each conflict to its owners; ACK tags every carried commit UPSTREAM/BACKPORT/FROMGIT/FROMLIST/ANDROID. stgit (Rust 2.7.0) rebases a topic and empties what upstream took; topgit merges along .topdeps, dormant; git cherry finds a landed patch by patch-id with nothing installed. b4, gbp, copier, repo are Python.\nTake: a file has one owner, at the layer that owns its meaning (the contract's reader); an override is named and carries an upstream status, and a missing one fails; upstream first - a change is made at the owner and comes down by the pin; a follower's edit becomes a change request on the source (copybara); a scheduled integrator report names each drift to its owner (linux-next); landed patches retire by patch-id. Set aside every tool as a runtime: the house mechanism already lays slices, the gaps are the rules.","sources":"git-subtree-doc,gitsubmodules,josh-filters,josh-repo,copybara-reference,android-repo-manifest,nix-flake-patch-issue,cruft,copier-updating,dep3,yocto-layers,yocto-patch-status,gentoo-layout-conf,kernel-process,ack-readme,stgit-releases,git-cherry","about":"base-graph","material":"research/base-graph/2026-11-18/","supersedes":null} +{"id":"base-graph-how-it-stands","brief":"How the repository graph stands: decided 2026-11-18-device-layer-from-docs, nothing of it built; graph-drift.sh 36 FAIL; first step idealkb's from-prefix, then the layer moves into docs","project":"linux-phone-oco/docs","date":"2026-11-18","question":"Hand-over: where does the repository graph stand, what is decided, what is the next step and what proves it?","found":"Decided (2026-11-18-device-layer-from-docs, superseding 2026-11-18-device-template-follows-by-release): idealkb -> docs -> every device base; docs gives the device layer from device-layer/ (statements, the device tables' marked part, the skeleton), the template is a follower that keeps its made-once seed files; own needs an upstream item or a reason; a base's edit of a followed file goes up as a PR on the source; graph-drift.sh daily reports every edge; forks tracked by a daily fetch-and-test-merge job; git-rhizoid built after, by conformance (status, follow, send-back, cuttings).\nStands: nothing built. graph-drift.sh (research/base-graph/2026-11-18/) exits 1 with 36 FAIL: docs own-behind x6 and own-part, each device base's own-part and own backlog.sql, layer-pin/owner/follow in the template and both labs, lpoco pin, tad pins and consumers, sxmo tracking.\nNext, in order: idealkb's from-prefix and skip-unchanged (upstream items, idealkb's owner) -> device-layer-in-docs (docs' owner) -> template-follows-docs, surya-follows-template, walleye-follows-template; in parallel docs-own-statements-up, docs-tables-idealkb-part, graph-drift-daily, tad-pins-every-base, lpoco-pin-follows, fork-tracking-job. Done when graph-drift.sh exits 0 (backlog base-graph). Waits on the author: the device layer moving into docs, and git-rhizoid unparked with this scope.","sources":"idealkb-chain-follow,rhizoid-repo","about":"base-graph","material":"research/base-graph/2026-11-18/","supersedes":null} diff --git a/data/session_log.json b/data/session_log.json index a784f44..1e25f82 100644 --- a/data/session_log.json +++ b/data/session_log.json @@ -119,3 +119,4 @@ {"project":"linux-phone-oco/docs","id":"2026-11-18-research-bringup-steps","entry_date":"2026-11-18","title":"Research: bring-up steps as data","done":"bringup-steps-research.r1 (research lead, from orchestration). Mined google-walleye-lab (161 backlog items, 120 session logs, the bring-up order plan), surya-lab and docs' surya records, lab-tools' lpoco-bringup and lpoco-health tests (a researcher subagent), and docs' tables (components, features, feature_support, support_status, milestones, tests, the parts feed). Looked around at 22 outside sources (a researcher subagent). Drafted the tables, records, query, seed and failing test and ran them in a scratch clone of docs. Recorded 18 sources, the research, the decision, 11 backlog items unranked, the hand-over row; landed data and the material only.","considered":"Landing the schema myself; steps as components; status typed in docs; edges as a list field; an issue tracker; per-driver probe steps; a 30-day expiry","rejected":"Landing tables.toml, records and queries here: AGENTS.md sends them to the owner, orchestration. The rest: see the decision's rejected.","date":null,"about":"bringup-steps"} {"project":"linux-phone-oco/lab-tools","id":"2026-11-18-host-records-the-root-files-it-installs","entry_date":"2026-11-18","title":"host records the root files it installs","done":"Built host-plan-unreadable-not-new (lab-tools #173): Seen {Absent, Text, Unreadable} in FileChange, install record, plan wording. Programmer review: two findings fixed (only PermissionDenied counts as unreadable; no diff printed for an unreadable file).","considered":"Recording at check time (kept as host-record-from-check); a record keyed per file vs one file (one file, lines HASH DST).","rejected":"Treating every read error as unreadable: a non-UTF-8 readable file would be called up to date unread.","date":null,"about":"host-plan-unreadable-not-new"} {"project":"linux-phone-oco/lab-tools","id":"2026-11-18-host-record-from-check","entry_date":"2026-11-18","title":"host: record from the share check","done":"Built host-record-from-check (lab-tools #175): a passing share check records the hash of the unreadable polkit rule, unit and helper, so the next plan asks no sudo for them.","considered":"Recording for any unreadable file with a record; gating on ok>0 only.","rejected":"Recording over a recorded hash of other content: the probe shows some rule works, not that it is this one (reviewer finding, fixed). Recording when one of several devices failed.","date":null,"about":"host-record-from-check"} +{"project":"linux-phone-oco/docs","id":"2026-11-18-rhizoid-graph-research","entry_date":"2026-11-18","title":"Research: the repository graph, how changes travel both ways, and git-rhizoid's scope","done":"Measured every edge (12; 3 by a job, 6 by hand, 5 behind); two read-only researchers surveyed subtree, submodules, josh, copybara, Android repo, Nix inputs, copier/cruft, multi-repo bots, gbp-pq/quilt/DEP-3, stgit, topgit, Yocto, Gentoo, Arch, the kernel's trees, ACK; wrote graph-drift.sh (failing, 36 FAIL); decided 2026-11-18-device-layer-from-docs superseding the template follow decision (supersedes, scope and tracked-by set with ikb set: docs' decision record lacks them - itself an instance of the own drift); reshaped the template and lab items; filed idealkb's side and rhizoid's scope as upstream items.","considered":"Keeping the template as the layer's source; josh monorepo; copybara; porting follow.sh to rhizoid now.","rejected":"See the decision's rejected.","date":null,"about":"base-graph"} diff --git a/data/sources.json b/data/sources.json index 2ae72cf..59e11a8 100644 --- a/data/sources.json +++ b/data/sources.json @@ -257,3 +257,18 @@ {"project":"linux-phone-oco/docs","id":"taskwarrior-virtual-tags","title":"Taskwarrior tags and virtual tags","url":"https://taskwarrior.org/docs/tags/","author":null,"year":null,"by":"Taskwarrior","takes":"READY and BLOCKED computed at query time, never stored"} {"project":"linux-phone-oco/docs","id":"ubports-porting","title":"Ubuntu Touch porting introduction","url":"https://docs.ubports.com/en/latest/porting/introduction/index.html","author":null,"year":null,"by":"UBports","takes":"porting stages without a proof per stage"} {"project":"linux-phone-oco/docs","id":"sailfish-hadk-subsystems","title":"Sailfish HADK: subsystems","url":"https://hadk.sailfishos.org/subsystems/","author":null,"year":null,"by":"Jolla","takes":"concrete proof commands for phone subsystems (test_gps, list-modems)"} +{"project":"linux-phone-oco/docs","id":"git-subtree-doc","title":"git-subtree(1), git contrib","url":"https://github.com/git/git/blob/master/contrib/subtree/git-subtree.adoc","author":null,"year":null,"by":"orchestration-renewed","takes":"Every command needs --prefix; split/push carries a subtree's history up. One directory, never files at the root among a base's own."} +{"project":"linux-phone-oco/docs","id":"gitsubmodules","title":"gitsubmodules(7)","url":"https://github.com/git/git/blob/master/Documentation/gitsubmodules.adoc","author":null,"year":null,"by":"orchestration-renewed","takes":"A gitlink pins a whole repository at a path; files at the root are not possible."} +{"project":"linux-phone-oco/docs","id":"josh-filters","title":"josh filter reference","url":"https://josh-project.dev/docs/reference/filters.html","author":null,"year":null,"by":"orchestration-renewed","takes":"::file and ::dest=src select single files at the root; filters reverse, so a push through a view lands at the source - in one monorepo."} +{"project":"linux-phone-oco/docs","id":"josh-repo","title":"josh-project/josh","url":"https://github.com/josh-project/josh","author":null,"year":null,"by":"orchestration-renewed","takes":"Rust, date-tagged releases (r26.08.28); josh-proxy; changes publish opens a PR per commit; experimental parts unstated as stable."} +{"project":"linux-phone-oco/docs","id":"copybara-reference","title":"copybara reference","url":"https://github.com/google/copybara/blob/master/docs/reference.md","author":null,"year":null,"by":"orchestration-renewed","takes":"CHANGE_REQUEST workflows carry a follower's PR to the source; GitOrigin-RevId, check_last_rev_state, merge_import. JVM 21, Starlark."} +{"project":"linux-phone-oco/docs","id":"android-repo-manifest","title":"repo manifest format","url":"https://gerrit.googlesource.com/git-repo/+/HEAD/docs/manifest-format.md","author":null,"year":null,"by":"orchestration-renewed","takes":"copyfile/linkfile lay files outside any project's history; up via repo upload to Gerrit; Python."} +{"project":"linux-phone-oco/docs","id":"nix-flake-patch-issue","title":"NixOS/nix #3920: flake references to patches","url":"https://github.com/NixOS/nix/issues/3920","author":null,"year":null,"by":"orchestration-renewed","takes":"An input cannot be patched in place (open since 2020); inputs live in the store, not the follower's tree."} +{"project":"linux-phone-oco/docs","id":"dep3","title":"DEP-3: patch tagging guidelines","url":"https://dep-team.pages.debian.net/deps/dep3/","author":null,"year":null,"by":"orchestration-renewed","takes":"Forwarded and Applied-Upstream on every carried patch; UDD counts them: 9.4% of trixie's forwarded - a warning alone moves nothing."} +{"project":"linux-phone-oco/docs","id":"yocto-layers","title":"Yocto dev manual: layers","url":"https://docs.yoctoproject.org/dev-manual/layers.html","author":null,"year":null,"by":"orchestration-renewed","takes":"One owner per recipe, named .bbappend overrides, a dangling append an error, yocto-check-layer forbids a BSP changing others' signatures."} +{"project":"linux-phone-oco/docs","id":"yocto-patch-status","title":"Yocto recipe style guide: Upstream-Status","url":"https://docs.yoctoproject.org/contributor-guide/recipe-style-guide.html","author":null,"year":null,"by":"orchestration-renewed","takes":"Every patch says Pending, Submitted, Backport, Denied, Inactive-Upstream or Inappropriate [reason]; patch-status is an error in ERROR_QA."} +{"project":"linux-phone-oco/docs","id":"gentoo-layout-conf","title":"Gentoo layout.conf masters","url":"https://wiki.gentoo.org/wiki/Repository_format/metadata/layout.conf","author":null,"year":null,"by":"orchestration-renewed","takes":"masters are not inherited: each overlay names every ancestor; pkgcheck MasterPackageClobbered is an error."} +{"project":"linux-phone-oco/docs","id":"kernel-process","title":"The Linux kernel development process","url":"https://www.kernel.org/doc/html/latest/process/2.Process.html","author":null,"year":null,"by":"orchestration-renewed","takes":"Subsystem trees, a chain of trust two or three links long; linux-next merges every tree and mails each conflict to both owners."} +{"project":"linux-phone-oco/docs","id":"ack-readme","title":"Android Common Kernel README","url":"https://android.googlesource.com/kernel/common/+/refs/heads/android-mainline/README.md","author":null,"year":null,"by":"orchestration-renewed","takes":"Every carried commit is UPSTREAM, BACKPORT, FROMGIT, FROMLIST or ANDROID; a rejected patch is ANDROID, never FROMLIST."} +{"project":"linux-phone-oco/docs","id":"stgit-releases","title":"stacked-git/stgit releases","url":"https://github.com/stacked-git/stgit/releases","author":null,"year":null,"by":"orchestration-renewed","takes":"Rust since 2.0 (2.7.0, 2026-10); rebase --merged leaves a patch upstream took empty."} +{"project":"linux-phone-oco/docs","id":"git-cherry","title":"git-cherry(1)","url":"https://git-scm.com/docs/git-cherry","author":null,"year":null,"by":"orchestration-renewed","takes":"Finds by patch-id which commits of a topic upstream already has: retiring a carried patch needs no tool."} diff --git a/data/summaries.json b/data/summaries.json index b817a23..abd0a67 100644 --- a/data/summaries.json +++ b/data/summaries.json @@ -5,5 +5,6 @@ {"about":"bringup","date":"2026-11-17","says":"One roof: the command is lpoco, a git-style dispatcher (argenv) that runs the family's programs lpoco-bringup, lpoco-health, lpoco-lab (today's devlab, kept as another name), lpoco-tone; one pin (device.toml [tools] lpoco), one release, one MCP door (lpoco mcp). lpoco-bringup makes a device's first boot images: it wraps mkbootimg and avbtool and crates for cpio, compression and dtb, and owns the checks, the swap of one part against a control image and the reproducible initramfs. Devices follow by pin and extend beside it (data in [boot], hooks, a rust-script on the pinned library): no rebase; changes go back as pull requests recorded as upstream items; updates by pin bump. The phone keeps its small static lpoco-health. Rhizoid's missing parts are on its own backlog (git-rhizoid.github.io PR 28). Decision 2026-11-17-bringup-in-lab-tools; research bringup-tools-landscape, bringup-home-follow-and-rhizoid, bringup-family-names, bringup-one-roof. Not built: lpoco-dispatcher with bringup-image-v0 first (failing tests lpoco-runs-subcommand-by-path, pack_v0), then rename of lab and tone, pin-and-hooks, release, mcp door.","condenses":"2026-11-17-bringup-in-lab-tools, 2026-11-17-research-bringup-follow, 2026-11-17-research-bringup-tools, bringup-family-names, bringup-home-follow-and-rhizoid, bringup-one-roof, bringup-tools-landscape"} {"about":"phone-side-pieces","date":"2026-11-18","says":"Phone-side pieces (what lpoco puts on a phone) are decided, not built. Every lab phone's pieces ride the lab-tools package - the keep-awake first, as lpoco-health awake (lpoco-awake) - and walleye's gadget init and ACM console go under lpoco bringup (bringup-generic-init); a device names roof pieces by token and keeps only its own files (decision 2026-11-18-phone-side-pieces-under-the-roof). Drift is named, not trusted: the phone reports each package version and each declared file's git blob id every boot (health-reports-pieces), and lpoco host check names a stale one from the last gathered report (phone-pieces-drift-named, its failing test written first; text in research/phone-side-pieces/2026-11-18/). device.toml stays data, declared once in Rust with a schema projected per release (decision 2026-11-18-device-manifest-schema-from-rust, manifest-one-schema and one row per device repository). Upstream: three questions (sxmo autosuspend backoff, sxmo suspend stops by profile, qcom_wdt armed in suspend) wait on the author's word. Hand-over: phone-side-pieces-how-it-stands.","condenses":"2026-11-18-device-manifest-schema-from-rust, 2026-11-18-phone-side-pieces-under-the-roof, 2026-11-18-research-phone-side-pieces, device-declaration-typed-landscape, phone-side-pieces-how-it-stands, phone-side-pieces-landscape"} {"about":"upstream-forks","date":"2026-11-18","says":"Our forks live under the author's account - grenudi/sxmo-utils (fork-sxmo-utils, a mirror of sr.ht) and grenudi/linux (fork-linux), transferred from the organisation so one history stays (decision 2026-11-18-upstream-forks, research upstream-forks-landscape). Each upstream item is a topic branch off the untouched tracking branch; a never-rebased lab/test branch is what phones run - sxmo-utils as a tagged lab apk (sxmo-utils-lab-apk), kernels by each lab's route. One upstreams lane coordinates (upstreams-lane, waiting on orchestration). Written, unsent, each waiting on its phone proof then the author's word: the sxmo series of three (sxmo-autosuspend-backoff, sxmo-suspend-stop-by-profile, sxmo-surya-sensors-suspend; research sxmo-suspend-fixes; spec in the series) and the RFC kernel series pmic-wdt-wake-in-suspend, which supersedes qcom-wdt-armed-in-suspend (research pmic-wdt-way-back; proofs surya-pmic-wdt-proof, walleye-pmic-wdt-proof in the device bases). rhizoid is not used yet; what it needs went to it as rhizoid-carries-mail-forks.","condenses":"2026-11-18-upstream-forks, sxmo-suspend-fixes, upstream-forks-landscape"} -{"about":"device-template","date":"2026-11-18","says":"device-template (asked for 2026-11-10, made 2026-11-17 as a GitHub template from what surya proved; a lab holds data, tools are lpoco's) has two children: surya-lab, re-based by hand, and google-walleye-lab, made by Use this template. idealkb's generic files reach all three by update-pins; the template's own 13 statements reach the labs only by hand, landed three times per change, and 8 drifts nothing catches are named in research device-template-drift-measured (stale list copies, three files with two sources and false-alarm bump PRs each idealkb release, surya's check.yml and tests/health/README.md, a date as pin, walleye's stale PR 208, the manifest's shape). Decision 2026-11-18-device-template-follows-by-release (research device-template-follow-world: cruft, copier, projen, Nix): the template is followed like idealkb - each file generic or made-once, a release pinned in devicebase.toml, laid by update-pins, template-drift failing CI. Queue, unranked: template-classifies-its-files first, then template-releases, template-drift-in-ci, template-followed-by-update-pins (waits on idealkb follow-source-from-pin), surya-follows-template, walleye-follows-template. The failing test: research/device-template/2026-11-18/template-drift.sh. Hand-over: device-template-how-it-stands; umbrella device-template-follow; device.toml's shape is template-manifest-schema's.","condenses":"2026-11-18-device-template-follows-by-release, device-template-drift-measured, device-template-follow-world, device-template-how-it-stands"} {"about":"bringup-steps","date":"2026-11-18","says":"Bring-up steps as data are in docs (decision 2026-11-18-bringup-steps-generic-in-docs-status-in-each-base, research bringup-steps-landscape): tables bringup_stages (the stage list as rows, changed with ikb bringup-stage, no schema change), bringup_steps, bringup_step_edges (hard/soft, with alternatives groups) and step_status (declared, empty), the records bringup-stage, bringup-step and bringup-edge (refuses a cycle), seeded with 8 stages, 26 steps and 37 edges. tad q bringup-chain [--device] orders them by depth and says ready or waits; with no device every status is unknown. Each device base will claim its own status per step - proof, run, proven_on - by a steps contract device-template ships; docs pulls the claims into step_status as it pulls parts (feed-device-steps), and a step no base claimed is not known yet. Walleye's real road is 26 steps: 17 done with checks and records, the charger failing on its tps61099 supplier; its test (research/bringup-steps/2026-11-18/bringup-chain-walleye.sh) fails only for lack of claims. Waiting: the steps contract, the lanes' claims, the feed, the guidebook, the helper map, milestone step terms; the stage list and step size wait the author's word.","condenses":"2026-11-18-bringup-steps-generic-in-docs-status-in-each-base, 2026-11-18-research-bringup-steps, bringup-steps-how-it-stands, bringup-steps-landscape"} +{"about":"base-graph","date":"2026-11-18","says":"The repository graph (idealkb, docs, device-template, the device bases, lab-tools' pins, the forks) was measured on 2026-11-18 (research base-graph-measured): 12 edges, 3 moved by a job, 6 by hand, 5 behind; nothing carries a change up - own is a one-way exit, an edited followed file stops at a person - and the parts contract is declared by the template and read by docs. The world (base-graph-world) offers no Rust or shell tool for root-level files both ways (copybara only, JVM) and four rules: one owner per file, named overrides with a status, pins per ancestor, a scheduled integrator report. Decided 2026-11-18-device-layer-from-docs: idealkb -> docs -> every device base, docs giving the device layer from device-layer/, the template a follower keeping its seed files; own needs an item; edits go up as PRs; graph-drift.sh daily; forks tracked daily; git-rhizoid after, by conformance. Nothing built yet: graph-drift.sh 36 FAIL; next idealkb's from-prefix (upstream item), then device-layer-in-docs (backlog base-graph). How it stands: base-graph-how-it-stands.","condenses":"2026-11-18-rhizoid-graph-research, base-graph-how-it-stands, base-graph-measured, base-graph-world"} +{"about":"device-template","date":"2026-11-18","says":"device-template (made 2026-11-17 as a GitHub template from what surya proved; a lab holds data, tools are lpoco's) has two children, surya-lab (re-based by hand) and google-walleye-lab (Use this template). Its 10 statements and 4 device tables reach them only by hand; the pin is a date (research device-template-drift-measured, template-drift.sh). Decision 2026-11-18-device-template-follows-by-release (the template releases and is followed) is superseded by 2026-11-18-device-layer-from-docs: the device layer comes from docs (device-layer-in-docs), so a contract such as parts or steps has one home beside the feed that reads it; the template becomes a device base like the others, pinning idealkb and docs and keeping its made-once seed files (template-classifies-its-files, template-follows-docs); the labs follow docs (surya-follows-template, walleye-follows-template); template-releases and template-followed-by-update-pins are closed, not done. The manifest's shape is the schema's (template-manifest-schema). The whole graph: summary base-graph.","condenses":"2026-11-18-device-layer-from-docs, 2026-11-18-device-template-follows-by-release, 2026-11-18-template-research, device-template-drift-measured, device-template-follow-world, device-template-how-it-stands"} diff --git a/data/upstream_items.json b/data/upstream_items.json index f26e5c6..9d53ca4 100644 --- a/data/upstream_items.json +++ b/data/upstream_items.json @@ -13,3 +13,8 @@ {"id":"sxmo-suspend-stop-by-profile","upstream":"sxmo-devel","title":"[PATCH sxmo-utils 2/3] suspend: stop the services a device profile names around suspend (SXMO_SUSPEND_STOP_SERVICES)","form":"patch","state":"draft","from_work":"2026-11-18-upstream-forks","domain":null,"tags":null,"about":"upstream-forks","local_ref":"linux-phone-oco/sxmo-utils topic/sxmo-suspend-stop-by-profile 1156bb6 (on the backoff patch)","file":"research/upstream-forks/2026-11-18/patches/sxmo-utils/","sent_on":null,"forwarded":null,"bug":null,"version":null,"supersedes":null,"applied_upstream":null,"carried_in":"fork-sxmo-utils/topic/sxmo-suspend-stop-by-profile","reviewed_by":null,"waits":"the phone proof surya-sxmo-suspend-series, then the author's word: sent in his name","note":"Was a question; now a patch. Answers why proycon's 2024 list was refused (sxmo-devel 55649: the wakeup count goes stale while services stop): the count is read again after the stop. Moves google,b4s4-sdm670 into its profile (it is now started again after suspend - say so in the cover letter).","last_update":"2026-11-18"} {"id":"sxmo-surya-sensors-suspend","upstream":"sxmo-devel","title":"[PATCH sxmo-utils 3/3] deviceprofiles: xiaomi,surya: stop the sensors daemon around suspend","form":"patch","state":"draft","from_work":"2026-11-18-upstream-forks","domain":null,"tags":null,"about":"upstream-forks","local_ref":"linux-phone-oco/sxmo-utils topic/sxmo-surya-sensors-suspend 6432ef9","file":"research/upstream-forks/2026-11-18/patches/sxmo-utils/","sent_on":null,"forwarded":null,"bug":null,"version":null,"supersedes":null,"applied_upstream":null,"carried_in":"fork-sxmo-utils/topic/sxmo-surya-sensors-suspend","reviewed_by":null,"waits":"the phone proof surya-sxmo-suspend-series, then the author's word","note":"Third of the sxmo series; proven by test sensors-after-suspend on surya.","last_update":"2026-11-18"} {"id":"rhizoid-carries-mail-forks","upstream":"git-rhizoid","title":"What rhizoid needs to carry a mailing-list fork: non-GitHub tracking, a topic series per item, mail send-back, retire on landed, a distro package pin","form":"finding","state":"draft","from_work":"upstream-forks-landscape","domain":null,"tags":null,"about":"upstream-forks","local_ref":null,"file":null,"sent_on":null,"forwarded":null,"bug":null,"version":null,"supersedes":null,"applied_upstream":null,"carried_in":null,"reviewed_by":null,"waits":"its owner's look-around (a backlog item in git-rhizoid.github.io, beside send-back-writes-the-upstream-item and cutting-as-cargo-dependency)","note":"From linux-phone-oco: sxmo-utils (sr.ht, mailed) and the kernel (b4, mailed). (1) a cutting of a non-GitHub upstream: tracking by git fetch + push, created by gh repo create + push; (2) one topic branch per upstream item off tracking, rebased only before a send, and an integration branch merging the topics, never rebased, that consumers pin - the patch branch cut per item; (3) send-back by mail: format-patch/b4 prep of tracking..topic with cover letter and recipients, never sending, returned for the follower's upstream item; (4) retire a topic when upstream carries it (patch-id against tracking) and say so (landed, carried-in none); (5) a pin where a distro package reads it (APKBUILD source tag + sha512sums), the cargo item generalised. Meanwhile: plain git by decision 2026-11-18-upstream-forks and tad q carried.","last_update":"2026-11-18"} +{"id":"idealkb-slice-from-prefix","upstream":"idealkb","title":"A source's generic list may say #! from = DIR/: its files are read from DIR in the source and laid at the base's root; check-one-owner compares the laid paths","form":"patch","state":"draft","from_work":"2026-11-18-device-layer-from-docs","domain":null,"tags":null,"about":"base-graph","local_ref":null,"file":null,"sent_on":null,"forwarded":null,"bug":null,"version":null,"supersedes":null,"applied_upstream":null,"carried_in":null,"reviewed_by":null,"waits":null,"note":"So docs can give the device layer from device-layer/ without carrying phone queries at its own root (device-layer-in-docs waits on it). josh's ::dest=src, one prefix rather than a map. A test in bin/test-follow.sh: a source with from = layer/ lays layer/q.sql as q.sql.","last_update":"2026-11-18"} +{"id":"idealkb-skip-unchanged-slice","upstream":"idealkb","title":"update-pins moves a base's pin only when a file of the source's list changed between the pin and the latest release","form":"patch","state":"draft","from_work":"2026-11-18-device-layer-from-docs","domain":null,"tags":null,"about":"base-graph","local_ref":null,"file":null,"sent_on":null,"forwarded":null,"bug":null,"version":null,"supersedes":null,"applied_upstream":null,"carried_in":null,"reviewed_by":null,"waits":null,"note":"docs releases several times a day; most releases do not touch the device layer and should open nothing in four bases. git diff --quiet vOLD vNEW -- the listed files (and the marked parts).","last_update":"2026-11-18"} +{"id":"idealkb-own-needs-item","upstream":"idealkb","title":"own is a named override with a status: an own file that differs from the source at the pin passes only while an upstream item of the base names it or the pin says own_why; an own tables.toml keeps the marked part","form":"patch","state":"draft","from_work":"2026-11-18-device-layer-from-docs","domain":null,"tags":null,"about":"base-graph","local_ref":null,"file":null,"sent_on":null,"forwarded":null,"bug":null,"version":null,"supersedes":null,"applied_upstream":null,"carried_in":null,"reviewed_by":null,"waits":null,"note":"Measured: docs' 6 own statements differ, decision.sql lacks --supersedes/--amends/--scope/--tracked-by since 0.14.0, no item names them; each device base's own tables.toml lacks 101 lines of 0.16.0's part (the known gap tables-own-drift). Yocto Upstream-Status and DEP-3 Forwarded, failing rather than warning (9.4% forwarded where it only warns). graph-drift.sh own-behind and own-part are the test.","last_update":"2026-11-18"} +{"id":"idealkb-exit3-sends-up","upstream":"idealkb","title":"When a base changed a followed file, update-pins also opens that change as a PR on the source at the pinned release and records an upstream item in the base","form":"patch","state":"draft","from_work":"2026-11-18-device-layer-from-docs","domain":null,"tags":null,"about":"base-graph","local_ref":null,"file":null,"sent_on":null,"forwarded":null,"bug":null,"version":null,"supersedes":null,"applied_upstream":null,"carried_in":null,"reviewed_by":null,"waits":null,"note":"Today exit 3 leaves a PR in the base for a person and nothing reaches the source; copybara's CHANGE_REQUEST is the model. The base's PR still lands the source's version; the change travels up as its own PR.","last_update":"2026-11-18"} +{"id":"rhizoid-scope-every-edge","upstream":"git-rhizoid","title":"rhizoid's scope: the follow tool for every edge a repository has (slice, tool pin, cutting), one status over all, both ways; status first, then follow by conformance with idealkb's follow.sh, send-back, cuttings","form":"finding","state":"draft","from_work":"2026-11-18-device-layer-from-docs","domain":null,"tags":null,"about":"base-graph","local_ref":null,"file":null,"sent_on":null,"forwarded":null,"bug":null,"version":null,"supersedes":null,"applied_upstream":null,"carried_in":null,"reviewed_by":null,"waits":null,"note":"From research base-graph-measured and base-graph-world: no Rust or shell tool carries root-level files down and changes up (only copybara, JVM); the cutting case has no tool here. Build order, each replacing shell only once it passes the shell's tests: status (passes graph-drift.sh), follow (passes idealkb bin/test-follow.sh fixtures byte for byte; keeps the pin naming its source, one owner per file, the followers' gate), send-back (idealkb-exit3-sends-up's shape), cuttings (rhizoid-carries-mail-forks). Never a template engine, a merge of data or rows. Its base's items slice-consumption, followers-one-pin-bump, send-back-writes-the-upstream-item and implement-cli are reshaped to it.","last_update":"2026-11-18"} diff --git a/docs/backlog.md b/docs/backlog.md index 1ff1fc9..860dd8c 100644 --- a/docs/backlog.md +++ b/docs/backlog.md @@ -2758,7 +2758,7 @@ Status : in-progress Note -: Decided 2026-11-17 (idealkb decision 2026-11-17-chain-follow-by-slice): the same pin-and-follow slice as idealkb, not a fork, subtree or Copier. Done: device-template lists what it gives (generic) and ships idealkb and itself as upstreams in its base. Next: device-template releases (release-please) and idealkb's follow-source-from-pin (update-pins reading its source from the pin file); then surya-lab and google-walleye-lab follow it with move-device-rows. Improvements go back as upstream items (PRs). rhizoid's missing slice mode is on git-rhizoid's backlog (slice-consumption). +: Route changed by decision 2026-11-18-device-layer-from-docs: device bases follow the device layer from docs (device-layer-in-docs), the template is a follower (template-follows-docs), the labs follow docs (surya-follows-template, walleye-follows-template). Proof: graph-drift.sh layer lines ok. Opened : 2026-11-17 @@ -4372,7 +4372,7 @@ Status : open Note -: Decision 2026-11-18-device-template-follows-by-release, step 1. Add a made-once list (device.toml, oco.toml, README.md, devicebase.toml, idealkb.toml, provision/packages.txt, .oco/uncommitted, data/); move Makefile, bin/install-tad.sh, tad.yml, gather.yml, .gitignore, tests/health/README.md and the .gitkeep files into generic; split the script check into a workflow a lab does not extend; a template:begin/end part in AGENTS.md for the general conventions; drop records/hardware.sql, records/hardware-status.sql, queries/hardware.sql from generic (idealkb 0.15.0 gives them). Owner: orchestration (device-template). +: Reshaped by decision 2026-11-18-device-layer-from-docs: the template names every file it has - what docs' device layer gives (the statements, the device tables' part, the skeleton: Makefile, bin/install-tad.sh, tad.yml, gather.yml, .gitignore, check.yml, tests/health/README.md - these move to docs' device-layer/ by device-layer-in-docs) and a made-once list (device.toml, oco.toml, README.md, devicebase.toml, idealkb.toml, provision/packages.txt, .oco/uncommitted, data/). Its own generic list goes (template-follows-docs). Opened : 2026-11-18 @@ -4391,10 +4391,10 @@ Project : linux-phone-oco/device-template Status -: open +: done Note -: Step 2. release-please as in idealkb; devicebase.toml template = "X.Y.Z" with own = [...] for template files a lab keeps; the template's own devicebase.toml comment says how a new lab sets it. The date pin (2026-11-17) is retired. +: Closed, not done: decision 2026-11-18-device-layer-from-docs supersedes the route - the template releases nothing and is followed by nothing; docs' release carries the device layer and update-pins follows docs (device-layer-in-docs, template-follows-docs). Opened : 2026-11-18 @@ -4410,7 +4410,7 @@ About -### template-drift runs in CI: the template's (classified, one-source) and each lab's (pin, equal, no-copy), from a generic bin/template-drift.sh +### template-drift's classified check runs in the template's CI; the labs' checks are graph-drift's (docs, daily) Project : linux-phone-oco/device-template @@ -4419,16 +4419,16 @@ Status : open Note -: Step 4. The failing test in docs research/device-template/2026-11-18/ becomes a generic file of the template; a lab's workflow clones the template at its pinned tag and idealkb at its pin, read-only. Like cruft check plus cruft diff --exit-code. +: Reshaped by decision 2026-11-18-device-layer-from-docs: pin, equal and no-copy move to graph-drift.sh (graph-drift-daily); the template keeps classified. Opened : 2026-11-18 Blocked by -: template-releases +: template-classifies-its-files Proof -: a test PR to a lab that edits a template-generic file fails CI with a line naming the file; main of the template and both labs pass +: a test PR to the template adding an unclassified file fails its CI with a line naming it About : device-template @@ -4441,10 +4441,10 @@ Project : linux-phone-oco/device-template Status -: open +: done Note -: Step 3. A change to the device layer then lands in the template only; no more parallel hand PRs. idealkb first, then the template, in one run. +: Closed, not done: decision 2026-11-18-device-layer-from-docs supersedes the route - the template releases nothing and is followed by nothing; docs' release carries the device layer and update-pins follows docs (device-layer-in-docs, template-follows-docs). Opened : 2026-11-18 @@ -4463,7 +4463,7 @@ About -### surya-lab follows device-template's release: its copy of the list gone, check.yml and tests/health/README.md taken, the pin a release +### surya-lab follows docs' device layer and device-template's skeleton files: devicebase.toml names source = linux-phone-oco/docs and a version, its list copy gone, check.yml and tests/health/README.md taken Project : linux-phone-oco/surya-lab @@ -4472,13 +4472,13 @@ Status : open Note -: Migration for decision 2026-11-18-device-template-follows-by-release; no phone. Measured drift today: generic copy 5 entries behind, check.yml without xargs -r, tests/health/README.md missing, devicebase.toml template = 2026-11-17. AGENTS.md outside the idealkb part stays its own until the template:begin part exists, then the general conventions come from the template. +: Reshaped by decision 2026-11-18-device-layer-from-docs (it supersedes 2026-11-18-device-template-follows-by-release): the layer's source is docs, not a template release. About an hour, no phone; surya-lab's owner lands it in its base. Opened : 2026-11-18 Blocked by -: template-releases +: device-layer-in-docs Needs : build @@ -4487,14 +4487,14 @@ Device : xiaomi-surya Proof -: docs research/device-template/2026-11-18/template-drift.sh device-template ideal-knowledge-base surya-lab: every surya-lab line says ok +: research/base-graph/2026-11-18/graph-drift.sh: layer-pin, layer-owner, layer-follow ok for surya-lab About : device-template -### google-walleye-lab follows device-template's release: its copy of the list gone, its rust job in its own workflow, the pin a release, stale PR 208 closed +### google-walleye-lab follows docs' device layer: devicebase.toml names source = linux-phone-oco/docs and a version, its list copy gone, its rust job in its own workflow, stale PR 208 closed Project : linux-phone-oco/google-walleye-lab @@ -4503,13 +4503,13 @@ Status : open Note -: Migration for decision 2026-11-18-device-template-follows-by-release; no phone. Measured drift today: generic copy 5 entries behind, ffs-acm-rs job inside the template's check.yml, devicebase.toml template = 2026-11-17, PR #208 (the template's #15 by hand) open though main has it. +: Reshaped by decision 2026-11-18-device-layer-from-docs: the layer's source is docs, not a template release. About an hour, no phone; walleye's owner lands it in its base. Opened : 2026-11-18 Blocked by -: template-releases +: device-layer-in-docs Needs : build @@ -4518,7 +4518,7 @@ Device : google-walleye Proof -: docs research/device-template/2026-11-18/template-drift.sh device-template ideal-knowledge-base google-walleye-lab: every google-walleye-lab line says ok +: research/base-graph/2026-11-18/graph-drift.sh: layer-pin, layer-owner, layer-follow ok for google-walleye-lab About : device-template @@ -4859,3 +4859,204 @@ Rank About : lpoco-host-rest + + + +### Every edge of the repository graph moved by a tool and checked, both ways: files down from one owner, changes up as items, rows up by feeds + +Project +: linux-phone-oco/docs + +Status +: in-progress + +Note +: Decided 2026-11-18-device-layer-from-docs (research base-graph-measured, base-graph-world). graph-drift.sh: 36 FAIL today. Steps: device-layer-in-docs, docs-own-statements-up, docs-tables-idealkb-part, graph-drift-daily, tad-pins-every-base, lpoco-pin-follows (lab-tools), fork-tracking-job, template-follows-docs and template-classifies-its-files (device-template), surya-follows-template, walleye-follows-template; idealkb's side as upstream items idealkb-slice-from-prefix, idealkb-skip-unchanged-slice, idealkb-own-needs-item, idealkb-exit3-sends-up; git-rhizoid's scope as rhizoid-scope-every-edge. + +Opened +: 2026-11-18 + +Proof +: research/base-graph/2026-11-18/graph-drift.sh exits 0 + + + +### docs gives the device layer: device-layer/ holds the 10 statements and the marked device part of tables.toml (devices, parts, test_runs, test_results; steps when it lands), a generic list (#! pin = devicebase.toml, #! marker = device, #! from = device-layer/), and takes device-template's place in idealkb's ./sources + +Project +: linux-phone-oco/docs + +Status +: open + +Note +: Decision 2026-11-18-device-layer-from-docs (1). docs' owner (orchestration) lands it. Waits on idealkb's from-prefix (upstream item idealkb-slice-from-prefix). The files move as device-template has them at d6eae9e; the template's list goes in the same week (template-follows-docs). + +Opened +: 2026-11-18 + +Waits +: idealkb: upstream item idealkb-slice-from-prefix + +Proof +: research/base-graph/2026-11-18/graph-drift.sh: layer-owner and layer-follow ok for every device base + +About +: base-graph + + + +### docs' six own statements (about, decision, research, backlog, session-log, source) each go up to idealkb as an item or are dropped for idealkb's + +Project +: linux-phone-oco/docs + +Status +: open + +Note +: Decision 2026-11-18-device-layer-from-docs (4). decision.sql lacks --supersedes/--amends/--scope/--tracked-by since idealkb 0.14.0 (this decision set them with ikb set). What docs adds (--project, a place per row) is the likely item: a base holding several places' records. + +Opened +: 2026-11-18 + +Proof +: research/base-graph/2026-11-18/graph-drift.sh: own-behind ok for docs; ikb decision --supersedes accepted in docs + +About +: base-graph + + + +### docs' tables.toml carries idealkb's marked part, so new generic fields and rules reach it at the follow + +Project +: linux-phone-oco/docs + +Status +: open + +Note +: Decision 2026-11-18-device-layer-from-docs (4); idealkb's gap tables-own-drift. docs' tables.toml has no idealkb:begin today. + +Opened +: 2026-11-18 + +Proof +: research/base-graph/2026-11-18/graph-drift.sh: own-part ok for docs + +About +: base-graph + + + +### graph-drift.sh runs daily in docs' CI and each FAIL line becomes an item for the edge's owner + +Project +: linux-phone-oco/docs + +Status +: open + +Note +: Decision 2026-11-18-device-layer-from-docs (5). Read-only, needs gh and the clones it reads (or fetches). + +Opened +: 2026-11-18 + +Proof +: a scheduled run of the workflow, red today with the 36 FAIL lines, green when every edge holds + +About +: base-graph + + + +### Every base that installs tad is on tad-engine's consumers list and at its latest release (docs' CI is on 0.6.0) + +Project +: linux-phone-oco/docs + +Status +: open + +Note +: tad-engine's owner adds device-template, surya-lab, google-walleye-lab to consumers; the weekly job then moves docs too. + +Opened +: 2026-11-18 + +Proof +: research/base-graph/2026-11-18/graph-drift.sh: tad-pin ok for every base + +About +: base-graph + + + +### lab.toml's lpoco pin is moved by a job when lpoco releases, or says why it holds + +Project +: linux-phone-oco/lab-tools + +Status +: open + +Note +: Decision 2026-11-18-device-layer-from-docs (5). lab.toml (grenudi/lab-machine) pins 0.15.0, lpoco-v0.17.0 tagged the same day. The pin is the lab machine's; the job is the later rhizoid tool-pin edge. + +Opened +: 2026-11-18 + +Proof +: research/base-graph/2026-11-18/graph-drift.sh: tool-pin ok + +About +: base-graph + + + +### A daily lab job fetches each fork's upstream into its tracking branch, test-merges every topic onto it and retires topics upstream carries (git cherry) + +Project +: linux-phone-oco/docs + +Status +: open + +Note +: Decision 2026-11-18-device-layer-from-docs (6); the upstreams lane's. grenudi/sxmo-utils master is 4 behind sr.ht today. + +Opened +: 2026-11-18 + +Proof +: research/base-graph/2026-11-18/graph-drift.sh: fork-track ok for grenudi/sxmo-utils and grenudi/linux + +About +: upstream-forks + + + +### device-template becomes a device base like the others: it pins idealkb and docs (devicebase.toml source/version), drops its generic list, keeps its made-once files + +Project +: linux-phone-oco/device-template + +Status +: open + +Note +: Decision 2026-11-18-device-layer-from-docs (2). The template builder's work, reshaped: the classification and made-once list stand; no template release. + +Opened +: 2026-11-18 + +Blocked by +: device-layer-in-docs,template-classifies-its-files + +Proof +: research/base-graph/2026-11-18/graph-drift.sh: layer-pin, layer-owner ok for device-template; template-drift.sh classified ok + +About +: device-template diff --git a/docs/decisions.md b/docs/decisions.md index 3d6db8a..b7c69c1 100644 --- a/docs/decisions.md +++ b/docs/decisions.md @@ -1791,3 +1791,48 @@ Research Tracked by : bringup-steps + + + +### 2026-11-18-device-layer-from-docs + +Brief +: The device layer comes from docs: idealkb, then docs, then every device base, the template one of them; own needs an item, edits go up as PRs, one drift check; rhizoid later, by conformance + +Project +: linux-phone-oco/docs + +Date +: 2026-11-18 + +Decision +: Supersedes 2026-11-18-device-template-follows-by-release (its classification, made-once list, failing check and hourly job stay; the source of the device layer moves). The author's picture, taken with one correction: the template is a device base, but it is also the seed new bases are copied from, so it keeps its made-once files. +1. Three layers of files, each file one owner at the layer that owns its meaning: idealkb (domain-free) -> docs (the commons) -> every device base. docs gives the device layer: the statements a device base runs (phone-queue, phone-next, parts, part, device, backlog-status, backlog-needs, test-run, lane-next, phone-stands) and a marked part (marker device) of tables.toml declaring devices, parts, test_runs, test_results and, when it lands, steps - kept in docs under device-layer/, beside the catalogues and the feeds that read the claims, so a contract change (parts, steps) is one change in one repository. docs' generic list says #! pin = devicebase.toml, #! marker = device, #! from = device-layer/ (read from that folder in docs, laid at the base's root: idealkb's follow.sh, item idealkb-slice-from-prefix). docs takes device-template's place in idealkb's ./sources; docs already releases; the job moves a base's device-layer pin only when a file of the list changed (idealkb-skip-unchanged-slice), so a docs release that does not touch the layer opens nothing. Each base pins each source it takes files from, by name (Gentoo's masters): idealkb.toml and devicebase.toml (source = "linux-phone-oco/docs", version, own). +2. device-template is a device base like the others: it pins idealkb and docs, its CI runs the checks a lab runs, and docs' release gate asks it first (followers-answer). It gives nothing by a list; it keeps the made-once files (device.toml example, README, devicebase.toml, idealkb.toml, oco.toml, provision/packages.txt, data/ empty) that Use this template copies, so a new base is born pinned. Its generic list goes; template-drift.sh keeps its classified check. +3. Files come down, rows go up, changes go up as change requests. Claims (parts, steps) stay pulled by docs' feeds at main. A change to a followed file is made at its owner, upstream first (the kernel's rule): a base that needs one opens it in docs or idealkb and the pin brings it back within the hour. When a base edits a followed file anyway, the job, besides its PR in the base, opens the same change as a PR on the source at the pinned release and records an upstream item in the base (copybara's change request; idealkb-exit3-sends-up). +4. own is a named override with a status (Yocto's Upstream-Status, DEP-3): a file a base keeps as its own may differ from its source only while an upstream item of the base names it (on its way up) or the pin file says why it stays (own_why); a base whose tables.toml is its own keeps the source's marked part as the pin gives it. Otherwise the follow fails (idealkb-own-needs-item). docs' six own statements go first: each goes up to idealkb as an item or is dropped for idealkb's (docs-own-statements-up). +5. One drift check over every edge, run on a schedule, each FAIL an item for the edge's owner (linux-next's way): graph-drift.sh (research material) in docs' CI daily - slices, own, the device layer, tad pins and their consumers, the lpoco pin in lab.toml, fork tracking. +6. Forks: a daily lab job fetches each fork's upstream into its tracking branch (sxmo master from sr.ht) and test-merges each topic onto it, a conflict reported as an item; a topic upstream carries is found by git cherry (patch-id) and retired. Decision 2026-11-18-upstream-forks otherwise unchanged. +7. git-rhizoid exists, scoped as the follow tool for every edge a repository has - a slice, a tool pin, a cutting - with one status over them all and both directions; never a template engine, a merge of data or rows (feeds stay docs'). Built after 1-6 work, in order, each replacing shell only once it passes the shell's tests: status (read-only; passes graph-drift.sh), follow (passes idealkb's bin/test-follow.sh fixtures byte for byte and keeps the three things idealkb names: the pin names its source, one owner per file, the followers' gate before a release - then update-pins calls it), send-back (the change request and the item), cuttings (tracking from any git URL, topic and integration branches, retire by patch-id, a distro package pin). Until then the shell is the tool. +Migration, about two agent-days, no phone: idealkb from-prefix and skip-unchanged (~2 h), own-needs-item (~2 h), exit3-sends-up (~3 h) - idealkb's owner; docs device-layer/ with its list and the sources switch (~3 h), its own statements up (~2 h), its tables' idealkb part (~1 h), graph-drift daily (~1 h) - docs' owner; the template turned into a follower (~1 h); each lab: devicebase.toml names docs, drops its list copy, takes the device part at the first follow (~1 h each); tad consumers +3 and docs' tad (minutes, tad-engine's owner); lpoco pin moved by a job or says why it holds (~1 h); the fork tracking job (~2 h). rhizoid after: status ~1.5 days, follow by conformance ~2, send-back ~1, cuttings ~2-3. + +Why +: The author (2026-11-18): develop git-rhizoid without reimplementing a wheel; the device-template's graph got mixed up - docs' shared parts should be inherited by every device base, the template being one more device, with changes pulled and pushed upstream with the least resistance and drift. Measured (research base-graph-measured): 12 edges, 3 moved by a job, 6 by hand, 5 behind today (graph-drift.sh: 36 FAIL); nothing carries a change up - own is a one-way exit (docs' six own statements differ from idealkb's and no item names them; docs cannot record --supersedes through its record, missing since idealkb 0.14.0), an edited followed file stops at a person; the parts contract is declared by the template and read by docs, and bring-up steps would repeat that split. The world (research base-graph-world): every mature layered project gives a file one owner at the layer that owns its meaning, names its overrides with an upstream status that fails when missing (Yocto, DEP-3), pins each ancestor by name (Gentoo), works upstream first (the kernel) and reports drift on a schedule to each owner (linux-next); no Rust or shell tool carries root-level files down and changes up but copybara (JVM), and idealkb's follow.sh already lays slices in ~250 tested lines. So the gaps are rules and one owner, not a new mechanism: moving the device layer to docs puts each contract in one repository and removes a release train and a third owner of 14 files at about one agent-day more than the superseded route; rhizoid is worth building because the gap is real, but only behind the shell's own tests. + +Rejected +: The superseded route as it was (the template a middle source with its own releases): the parts and steps contracts stay split between the template (declared) and docs (read), a third release train and owner for 14 files, and docs' catalogue ids still reach no base; about one agent-day, but it keeps the mix-up the author named. The device layer at docs' root: docs would carry phone queries over tables it does not have. Device bases following all of docs: docs' statements are the commons', not a device's. The layer into idealkb: idealkb is domain-free; what proves general moves there one file at a time, as hardware did. A chain of four (idealkb, docs, template, labs): every contract change two hops. The template only a GitHub template with no pin: the next base is born unpinned. git subtree, subrepo, submodules: a prefix, and tad reads its statements at the root. josh: one monorepo as the truth, a base cannot keep its own variant, a proxy to run, push back between separate repositories unknown. copybara: a JVM 21 and Starlark for 7 followers in 2 directions; its change request is taken, not its runtime. Android repo, copier, cruft, gbp-pq, b4: Python, refused; copier/cruft also have no way up. Nix inputs: the store, not files, and no patching in place. stgit: fine on a topic branch by hand, not needed by the graph; topgit: dormant. Labels that only warn (DEP-3: 9.4% forwarded): own without an item fails. git-rhizoid now, replacing follow.sh: the shell works and is tested; a port without conformance risks every base, and the gaps are rules, not tooling. git-rhizoid never: the author asks for it, and both directions for root-level slices and the cutting case have no tool in the house's languages. + +About +: device-template + +Research +: base-graph-measured + +Supersedes +: 2026-11-18-device-template-follows-by-release + +Scope +: docs (owner orchestration), idealkb (its owner), device-template, surya-lab, google-walleye-lab, lab-machine, tad-engine, the upstreams lane, git-rhizoid; the template builder + +Tracked by +: base-graph diff --git a/docs/index.md b/docs/index.md index d83f87e..6cfe400 100644 --- a/docs/index.md +++ b/docs/index.md @@ -4,13 +4,13 @@ The memory of linux-phone-oco, whose goal is Linux phones as good as Android for everyday use, and better: which phone supports which hardware, how we know, why decisions were made, and what is next. Plain versioned data; see AGENTS.md. The plan, and where Linux phones stand against Android and iOS: [the grand picture](picture.md), and the main screen, [features against Android and iOS](feature_support.md). -- [Backlog](backlog.md): 195 +- [Backlog](backlog.md): 204 - [Bringup Stages](bringup_stages.md): 8 - [Bringup Step Edges](bringup_step_edges.md): 37 - [Bringup Steps](bringup_steps.md): 26 - [Components](components.md): 21 - [Concepts](concepts.md): 10 -- [Decisions](decisions.md): 72 +- [Decisions](decisions.md): 73 - [Devices](devices.md): 3 - [Feature Support](feature_support.md): 101 - [Features](features.md): 46 @@ -24,18 +24,18 @@ The memory of linux-phone-oco, whose goal is Linux phones as good as Android for - [Milestones](milestones.md): 23 - [Platforms](platforms.md): 7 - [Problems](problems.md): 17 -- [Research](research.md): 59 -- [Session Log](session_log.md): 121 +- [Research](research.md): 62 +- [Session Log](session_log.md): 122 - [Shell Releases](shell_releases.md): 2 -- [Sources](sources.md): 259 +- [Sources](sources.md): 274 - [Step Status](step_status.md): 0 -- [Summaries](summaries.md): 9 +- [Summaries](summaries.md): 10 - [Support Status](support_status.md): 63 - [Test Results](test_results.md): 0 - [Test Runs](test_runs.md): 0 - [Tests](tests.md): 54 - [Translations](translations.md): 204 -- [Upstream Items](upstream_items.md): 15 +- [Upstream Items](upstream_items.md): 20 - [Upstreams](upstreams.md): 13 - [Wiki Claims](wiki_claims.md): 18 - [Workings](workings.md): 17 diff --git a/docs/research.md b/docs/research.md index 7046236..f7ae12a 100644 --- a/docs/research.md +++ b/docs/research.md @@ -1540,3 +1540,96 @@ Sources About : bringup-steps + + + +### base-graph-measured + +Brief +: The graph measured: 12 edges, 3 moved by a job, 6 by hand, 5 behind today; own files are a one-way exit and nothing carries a change up; the parts contract has two homes + +Project +: linux-phone-oco/docs + +Date +: 2026-11-18 + +Question +: What is the real dependency graph of idealkb, docs, device-template, the device bases, lab-tools and the forks: who pulls what, which way, by which tool, and how does drift show (the author, 2026-11-18)? + +Found +: Measured at origin/main of each (idealkb v0.16.0, docs 608b61f, device-template d6eae9e, surya-lab 42da677, google-walleye-lab f0e0fc2, lab-machine fb75285), read only. +Files go down: idealkb's slice reaches docs, ideal-agent, device-template and both labs by follow.sh/update-pins (hourly, every pin 0.16.0, current; since 0.16.0 a source names its pin and marker, ./sources lists device-template, skipped until it releases; check-one-owner stops two owners). device-template's 10 statements and the 4 device tables (devices, parts, test_runs, test_results - outside any marker) reach the labs by hand; the pin is a date. tad reaches every base by a weekly job whose consumers list lacks the three device bases; docs' CI runs tad 0.6.0, the rest 0.7.1. lab.toml pins lpoco 0.15.0 by hand; 0.17.0 was tagged the same day. sxmo-utils master on grenudi is 4 commits behind sr.ht, nothing fetches it; grenudi/linux is a GitHub fork, current. +Rows go up: docs pulls each lab's parts.json at main by DuckDB (contract parts = 1); component ids agree today by hand (none unknown) and nothing carries docs' catalogue or step ids down. +Changes go up: nowhere by a tool. A followed file edited below ends follow.sh with 3 and a PR in the follower for a person; nothing reaches the source. own is a one-way exit: docs keeps 7 own files, 6 statements differ from idealkb's (decision.sql lacks --supersedes/--amends/--scope/--tracked-by since 0.14.0, so docs cannot record a superseding decision through its record; 0 decisions carry either), docs' tables.toml has no idealkb part, each device base's own tables.toml lacks 101 lines of idealkb 0.16.0's part; no upstream item names any of it (docs: 0 items to idealkb or the template; labs: 0). +The parts contract has two homes: declared by device-template, read by docs; bring-up steps will repeat it (catalogue in docs, claim table in the template). Every contract change is two PRs in two repositories and two release trains. +In all: 12 edges, 3 moved by a job (idealkb slice, tad, docs feeds), 6 by hand, 5 behind today. Failing test graph-drift.sh in the material: exit 1, 36 FAIL, 9 ok. + +Sources +: idealkb-chain-follow,rhizoid-repo,rhizoid-design-log + +About +: base-graph + +Material +: research/base-graph/2026-11-18/ + + + +### base-graph-world + +Brief +: Only copybara (JVM) carries root-level files down and changes up; layered projects share four rules: one owner per file, named overrides with a status, fatal pins, a scheduled integrator report + +Project +: linux-phone-oco/docs + +Date +: 2026-11-18 + +Question +: What exists in the world for a chain of repositories that share files and must let changes travel both ways - subtree, submodules, josh, copybara, gbp-pq/quilt, stgit, topgit, Nix inputs, Yocto layers, Android repo, Gentoo/Arch overlays, copier/cruft, the kernel's maintainer trees - and what does each cost here (Python refused, Rust with argenv the house way)? + +Found +: Down and up, root-level files: subtree and subrepo carry a whole directory both ways (split/push) but need a prefix, and tad reads its statements at the root; submodules pin a repository at a path, no files at the root. Android repo copies files outside any project's history (Python). Nix inputs live in the store and cannot be patched in place (nix#3920); update-flake-lock bumps only. copier/cruft: pin + "behind" and "edited" checks, down only, Python. Renovate, multi-gitter, turbolift, microplane: a pin bump or a script per repo with a PR, down only. copybara alone does both: a follower's PR becomes a change request on the source, GitOrigin-RevId records the import, check_last_rev_state fails when the destination changed, merge_import keeps a destination's own lines - at the cost of a JVM 21 and Starlark per workflow. josh (Rust) selects single files at the root (::f, ::dest=src) and pushes back through a view, but its truth is one monorepo and a follower cannot keep its own variant; push back from separate repositories is unknown. No Rust or shell tool does root-level slices both ways: idealkb's follow.sh is the house's answer and the gap is real. +Layering: Yocto (oe-core, distro, BSP): one owner per recipe, overrides as named .bbappend files, a dangling append an error, LAYERSERIES_COMPAT fatal, Upstream-Status required on every patch and an error by default, yocto-check-layer forbids a BSP changing others' signatures - the middle layer owns the contract the lowest is checked against. Gentoo: masters non-transitive (each overlay names every ancestor, as each base here pins each source), MasterPackageClobbered an error (check-one-owner). DEP-3: Forwarded/Applied-Upstream on each patch, yet 9.4% forwarded in trixie - a status that only warns moves nothing. Kernel: upstream first, a copy says "commit X upstream", linux-next merges every tree on a schedule and mails each conflict to its owners; ACK tags every carried commit UPSTREAM/BACKPORT/FROMGIT/FROMLIST/ANDROID. stgit (Rust 2.7.0) rebases a topic and empties what upstream took; topgit merges along .topdeps, dormant; git cherry finds a landed patch by patch-id with nothing installed. b4, gbp, copier, repo are Python. +Take: a file has one owner, at the layer that owns its meaning (the contract's reader); an override is named and carries an upstream status, and a missing one fails; upstream first - a change is made at the owner and comes down by the pin; a follower's edit becomes a change request on the source (copybara); a scheduled integrator report names each drift to its owner (linux-next); landed patches retire by patch-id. Set aside every tool as a runtime: the house mechanism already lays slices, the gaps are the rules. + +Sources +: git-subtree-doc,gitsubmodules,josh-filters,josh-repo,copybara-reference,android-repo-manifest,nix-flake-patch-issue,cruft,copier-updating,dep3,yocto-layers,yocto-patch-status,gentoo-layout-conf,kernel-process,ack-readme,stgit-releases,git-cherry + +About +: base-graph + +Material +: research/base-graph/2026-11-18/ + + + +### base-graph-how-it-stands + +Brief +: How the repository graph stands: decided 2026-11-18-device-layer-from-docs, nothing of it built; graph-drift.sh 36 FAIL; first step idealkb's from-prefix, then the layer moves into docs + +Project +: linux-phone-oco/docs + +Date +: 2026-11-18 + +Question +: Hand-over: where does the repository graph stand, what is decided, what is the next step and what proves it? + +Found +: Decided (2026-11-18-device-layer-from-docs, superseding 2026-11-18-device-template-follows-by-release): idealkb -> docs -> every device base; docs gives the device layer from device-layer/ (statements, the device tables' marked part, the skeleton), the template is a follower that keeps its made-once seed files; own needs an upstream item or a reason; a base's edit of a followed file goes up as a PR on the source; graph-drift.sh daily reports every edge; forks tracked by a daily fetch-and-test-merge job; git-rhizoid built after, by conformance (status, follow, send-back, cuttings). +Stands: nothing built. graph-drift.sh (research/base-graph/2026-11-18/) exits 1 with 36 FAIL: docs own-behind x6 and own-part, each device base's own-part and own backlog.sql, layer-pin/owner/follow in the template and both labs, lpoco pin, tad pins and consumers, sxmo tracking. +Next, in order: idealkb's from-prefix and skip-unchanged (upstream items, idealkb's owner) -> device-layer-in-docs (docs' owner) -> template-follows-docs, surya-follows-template, walleye-follows-template; in parallel docs-own-statements-up, docs-tables-idealkb-part, graph-drift-daily, tad-pins-every-base, lpoco-pin-follows, fork-tracking-job. Done when graph-drift.sh exits 0 (backlog base-graph). Waits on the author: the device layer moving into docs, and git-rhizoid unparked with this scope. + +Sources +: idealkb-chain-follow,rhizoid-repo + +About +: base-graph + +Material +: research/base-graph/2026-11-18/ diff --git a/docs/session_log.md b/docs/session_log.md index 112e5bd..e29f82d 100644 --- a/docs/session_log.md +++ b/docs/session_log.md @@ -2696,3 +2696,27 @@ Rejected About : host-record-from-check + +--- + + + +### Research: the repository graph, how changes travel both ways, and git-rhizoid's scope + +Project +: linux-phone-oco/docs + +Entry date +: 2026-11-18 + +Done +: Measured every edge (12; 3 by a job, 6 by hand, 5 behind); two read-only researchers surveyed subtree, submodules, josh, copybara, Android repo, Nix inputs, copier/cruft, multi-repo bots, gbp-pq/quilt/DEP-3, stgit, topgit, Yocto, Gentoo, Arch, the kernel's trees, ACK; wrote graph-drift.sh (failing, 36 FAIL); decided 2026-11-18-device-layer-from-docs superseding the template follow decision (supersedes, scope and tracked-by set with ikb set: docs' decision record lacks them - itself an instance of the own drift); reshaped the template and lab items; filed idealkb's side and rhizoid's scope as upstream items. + +Considered +: Keeping the template as the layer's source; josh monorepo; copybara; porting follow.sh to rhizoid now. + +Rejected +: See the decision's rejected. + +About +: base-graph diff --git a/docs/sources.md b/docs/sources.md index 3404a68..c893e27 100644 --- a/docs/sources.md +++ b/docs/sources.md @@ -4363,3 +4363,243 @@ By Takes : concrete proof commands for phone subsystems (test_gps, list-modems) + + + +### git-subtree(1), git contrib + +Project +: linux-phone-oco/docs + +Url +: https://github.com/git/git/blob/master/contrib/subtree/git-subtree.adoc + +By +: orchestration-renewed + +Takes +: Every command needs --prefix; split/push carries a subtree's history up. One directory, never files at the root among a base's own. + + + +### gitsubmodules(7) + +Project +: linux-phone-oco/docs + +Url +: https://github.com/git/git/blob/master/Documentation/gitsubmodules.adoc + +By +: orchestration-renewed + +Takes +: A gitlink pins a whole repository at a path; files at the root are not possible. + + + +### josh filter reference + +Project +: linux-phone-oco/docs + +Url +: https://josh-project.dev/docs/reference/filters.html + +By +: orchestration-renewed + +Takes +: ::file and ::dest=src select single files at the root; filters reverse, so a push through a view lands at the source - in one monorepo. + + + +### josh-project/josh + +Project +: linux-phone-oco/docs + +Url +: https://github.com/josh-project/josh + +By +: orchestration-renewed + +Takes +: Rust, date-tagged releases (r26.08.28); josh-proxy; changes publish opens a PR per commit; experimental parts unstated as stable. + + + +### copybara reference + +Project +: linux-phone-oco/docs + +Url +: https://github.com/google/copybara/blob/master/docs/reference.md + +By +: orchestration-renewed + +Takes +: CHANGE_REQUEST workflows carry a follower's PR to the source; GitOrigin-RevId, check_last_rev_state, merge_import. JVM 21, Starlark. + + + +### repo manifest format + +Project +: linux-phone-oco/docs + +Url +: https://gerrit.googlesource.com/git-repo/+/HEAD/docs/manifest-format.md + +By +: orchestration-renewed + +Takes +: copyfile/linkfile lay files outside any project's history; up via repo upload to Gerrit; Python. + + + +### NixOS/nix #3920: flake references to patches + +Project +: linux-phone-oco/docs + +Url +: https://github.com/NixOS/nix/issues/3920 + +By +: orchestration-renewed + +Takes +: An input cannot be patched in place (open since 2020); inputs live in the store, not the follower's tree. + + + +### DEP-3: patch tagging guidelines + +Project +: linux-phone-oco/docs + +Url +: https://dep-team.pages.debian.net/deps/dep3/ + +By +: orchestration-renewed + +Takes +: Forwarded and Applied-Upstream on every carried patch; UDD counts them: 9.4% of trixie's forwarded - a warning alone moves nothing. + + + +### Yocto dev manual: layers + +Project +: linux-phone-oco/docs + +Url +: https://docs.yoctoproject.org/dev-manual/layers.html + +By +: orchestration-renewed + +Takes +: One owner per recipe, named .bbappend overrides, a dangling append an error, yocto-check-layer forbids a BSP changing others' signatures. + + + +### Yocto recipe style guide: Upstream-Status + +Project +: linux-phone-oco/docs + +Url +: https://docs.yoctoproject.org/contributor-guide/recipe-style-guide.html + +By +: orchestration-renewed + +Takes +: Every patch says Pending, Submitted, Backport, Denied, Inactive-Upstream or Inappropriate [reason]; patch-status is an error in ERROR_QA. + + + +### Gentoo layout.conf masters + +Project +: linux-phone-oco/docs + +Url +: https://wiki.gentoo.org/wiki/Repository_format/metadata/layout.conf + +By +: orchestration-renewed + +Takes +: masters are not inherited: each overlay names every ancestor; pkgcheck MasterPackageClobbered is an error. + + + +### The Linux kernel development process + +Project +: linux-phone-oco/docs + +Url +: https://www.kernel.org/doc/html/latest/process/2.Process.html + +By +: orchestration-renewed + +Takes +: Subsystem trees, a chain of trust two or three links long; linux-next merges every tree and mails each conflict to both owners. + + + +### Android Common Kernel README + +Project +: linux-phone-oco/docs + +Url +: https://android.googlesource.com/kernel/common/+/refs/heads/android-mainline/README.md + +By +: orchestration-renewed + +Takes +: Every carried commit is UPSTREAM, BACKPORT, FROMGIT, FROMLIST or ANDROID; a rejected patch is ANDROID, never FROMLIST. + + + +### stacked-git/stgit releases + +Project +: linux-phone-oco/docs + +Url +: https://github.com/stacked-git/stgit/releases + +By +: orchestration-renewed + +Takes +: Rust since 2.0 (2.7.0, 2026-10); rebase --merged leaves a patch upstream took empty. + + + +### git-cherry(1) + +Project +: linux-phone-oco/docs + +Url +: https://git-scm.com/docs/git-cherry + +By +: orchestration-renewed + +Takes +: Finds by patch-id which commits of a topic upstream already has: retiring a carried patch needs no tool. diff --git a/docs/summaries.md b/docs/summaries.md index 04f2b3e..66a9b83 100644 --- a/docs/summaries.md +++ b/docs/summaries.md @@ -110,28 +110,43 @@ Condenses ### Row 8 About -: device-template +: bringup-steps Date : 2026-11-18 Says -: device-template (asked for 2026-11-10, made 2026-11-17 as a GitHub template from what surya proved; a lab holds data, tools are lpoco's) has two children: surya-lab, re-based by hand, and google-walleye-lab, made by Use this template. idealkb's generic files reach all three by update-pins; the template's own 13 statements reach the labs only by hand, landed three times per change, and 8 drifts nothing catches are named in research device-template-drift-measured (stale list copies, three files with two sources and false-alarm bump PRs each idealkb release, surya's check.yml and tests/health/README.md, a date as pin, walleye's stale PR 208, the manifest's shape). Decision 2026-11-18-device-template-follows-by-release (research device-template-follow-world: cruft, copier, projen, Nix): the template is followed like idealkb - each file generic or made-once, a release pinned in devicebase.toml, laid by update-pins, template-drift failing CI. Queue, unranked: template-classifies-its-files first, then template-releases, template-drift-in-ci, template-followed-by-update-pins (waits on idealkb follow-source-from-pin), surya-follows-template, walleye-follows-template. The failing test: research/device-template/2026-11-18/template-drift.sh. Hand-over: device-template-how-it-stands; umbrella device-template-follow; device.toml's shape is template-manifest-schema's. +: Bring-up steps as data are in docs (decision 2026-11-18-bringup-steps-generic-in-docs-status-in-each-base, research bringup-steps-landscape): tables bringup_stages (the stage list as rows, changed with ikb bringup-stage, no schema change), bringup_steps, bringup_step_edges (hard/soft, with alternatives groups) and step_status (declared, empty), the records bringup-stage, bringup-step and bringup-edge (refuses a cycle), seeded with 8 stages, 26 steps and 37 edges. tad q bringup-chain [--device] orders them by depth and says ready or waits; with no device every status is unknown. Each device base will claim its own status per step - proof, run, proven_on - by a steps contract device-template ships; docs pulls the claims into step_status as it pulls parts (feed-device-steps), and a step no base claimed is not known yet. Walleye's real road is 26 steps: 17 done with checks and records, the charger failing on its tps61099 supplier; its test (research/bringup-steps/2026-11-18/bringup-chain-walleye.sh) fails only for lack of claims. Waiting: the steps contract, the lanes' claims, the feed, the guidebook, the helper map, milestone step terms; the stage list and step size wait the author's word. Condenses -: 2026-11-18-device-template-follows-by-release, device-template-drift-measured, device-template-follow-world, device-template-how-it-stands +: 2026-11-18-bringup-steps-generic-in-docs-status-in-each-base, 2026-11-18-research-bringup-steps, bringup-steps-how-it-stands, bringup-steps-landscape ### Row 9 About -: bringup-steps +: base-graph Date : 2026-11-18 Says -: Bring-up steps as data are in docs (decision 2026-11-18-bringup-steps-generic-in-docs-status-in-each-base, research bringup-steps-landscape): tables bringup_stages (the stage list as rows, changed with ikb bringup-stage, no schema change), bringup_steps, bringup_step_edges (hard/soft, with alternatives groups) and step_status (declared, empty), the records bringup-stage, bringup-step and bringup-edge (refuses a cycle), seeded with 8 stages, 26 steps and 37 edges. tad q bringup-chain [--device] orders them by depth and says ready or waits; with no device every status is unknown. Each device base will claim its own status per step - proof, run, proven_on - by a steps contract device-template ships; docs pulls the claims into step_status as it pulls parts (feed-device-steps), and a step no base claimed is not known yet. Walleye's real road is 26 steps: 17 done with checks and records, the charger failing on its tps61099 supplier; its test (research/bringup-steps/2026-11-18/bringup-chain-walleye.sh) fails only for lack of claims. Waiting: the steps contract, the lanes' claims, the feed, the guidebook, the helper map, milestone step terms; the stage list and step size wait the author's word. +: The repository graph (idealkb, docs, device-template, the device bases, lab-tools' pins, the forks) was measured on 2026-11-18 (research base-graph-measured): 12 edges, 3 moved by a job, 6 by hand, 5 behind; nothing carries a change up - own is a one-way exit, an edited followed file stops at a person - and the parts contract is declared by the template and read by docs. The world (base-graph-world) offers no Rust or shell tool for root-level files both ways (copybara only, JVM) and four rules: one owner per file, named overrides with a status, pins per ancestor, a scheduled integrator report. Decided 2026-11-18-device-layer-from-docs: idealkb -> docs -> every device base, docs giving the device layer from device-layer/, the template a follower keeping its seed files; own needs an item; edits go up as PRs; graph-drift.sh daily; forks tracked daily; git-rhizoid after, by conformance. Nothing built yet: graph-drift.sh 36 FAIL; next idealkb's from-prefix (upstream item), then device-layer-in-docs (backlog base-graph). How it stands: base-graph-how-it-stands. Condenses -: 2026-11-18-bringup-steps-generic-in-docs-status-in-each-base, 2026-11-18-research-bringup-steps, bringup-steps-how-it-stands, bringup-steps-landscape +: 2026-11-18-rhizoid-graph-research, base-graph-how-it-stands, base-graph-measured, base-graph-world + + +### Row 10 + +About +: device-template + +Date +: 2026-11-18 + +Says +: device-template (made 2026-11-17 as a GitHub template from what surya proved; a lab holds data, tools are lpoco's) has two children, surya-lab (re-based by hand) and google-walleye-lab (Use this template). Its 10 statements and 4 device tables reach them only by hand; the pin is a date (research device-template-drift-measured, template-drift.sh). Decision 2026-11-18-device-template-follows-by-release (the template releases and is followed) is superseded by 2026-11-18-device-layer-from-docs: the device layer comes from docs (device-layer-in-docs), so a contract such as parts or steps has one home beside the feed that reads it; the template becomes a device base like the others, pinning idealkb and docs and keeping its made-once seed files (template-classifies-its-files, template-follows-docs); the labs follow docs (surya-follows-template, walleye-follows-template); template-releases and template-followed-by-update-pins are closed, not done. The manifest's shape is the schema's (template-manifest-schema). The whole graph: summary base-graph. + +Condenses +: 2026-11-18-device-layer-from-docs, 2026-11-18-device-template-follows-by-release, 2026-11-18-template-research, device-template-drift-measured, device-template-follow-world, device-template-how-it-stands diff --git a/docs/upstream_items.md b/docs/upstream_items.md index f092dd8..51a1447 100644 --- a/docs/upstream_items.md +++ b/docs/upstream_items.md @@ -546,3 +546,128 @@ Note Last update : 2026-11-18 + + + +### A source's generic list may say #! from = DIR/: its files are read from DIR in the source and laid at the base's root; check-one-owner compares the laid paths + +Upstream +: idealkb + +Form +: patch + +State +: draft + +From work +: 2026-11-18-device-layer-from-docs + +About +: base-graph + +Note +: So docs can give the device layer from device-layer/ without carrying phone queries at its own root (device-layer-in-docs waits on it). josh's ::dest=src, one prefix rather than a map. A test in bin/test-follow.sh: a source with from = layer/ lays layer/q.sql as q.sql. + +Last update +: 2026-11-18 + + + +### update-pins moves a base's pin only when a file of the source's list changed between the pin and the latest release + +Upstream +: idealkb + +Form +: patch + +State +: draft + +From work +: 2026-11-18-device-layer-from-docs + +About +: base-graph + +Note +: docs releases several times a day; most releases do not touch the device layer and should open nothing in four bases. git diff --quiet vOLD vNEW -- the listed files (and the marked parts). + +Last update +: 2026-11-18 + + + +### own is a named override with a status: an own file that differs from the source at the pin passes only while an upstream item of the base names it or the pin says own_why; an own tables.toml keeps the marked part + +Upstream +: idealkb + +Form +: patch + +State +: draft + +From work +: 2026-11-18-device-layer-from-docs + +About +: base-graph + +Note +: Measured: docs' 6 own statements differ, decision.sql lacks --supersedes/--amends/--scope/--tracked-by since 0.14.0, no item names them; each device base's own tables.toml lacks 101 lines of 0.16.0's part (the known gap tables-own-drift). Yocto Upstream-Status and DEP-3 Forwarded, failing rather than warning (9.4% forwarded where it only warns). graph-drift.sh own-behind and own-part are the test. + +Last update +: 2026-11-18 + + + +### When a base changed a followed file, update-pins also opens that change as a PR on the source at the pinned release and records an upstream item in the base + +Upstream +: idealkb + +Form +: patch + +State +: draft + +From work +: 2026-11-18-device-layer-from-docs + +About +: base-graph + +Note +: Today exit 3 leaves a PR in the base for a person and nothing reaches the source; copybara's CHANGE_REQUEST is the model. The base's PR still lands the source's version; the change travels up as its own PR. + +Last update +: 2026-11-18 + + + +### rhizoid's scope: the follow tool for every edge a repository has (slice, tool pin, cutting), one status over all, both ways; status first, then follow by conformance with idealkb's follow.sh, send-back, cuttings + +Upstream +: git-rhizoid + +Form +: finding + +State +: draft + +From work +: 2026-11-18-device-layer-from-docs + +About +: base-graph + +Note +: From research base-graph-measured and base-graph-world: no Rust or shell tool carries root-level files down and changes up (only copybara, JVM); the cutting case has no tool here. Build order, each replacing shell only once it passes the shell's tests: status (passes graph-drift.sh), follow (passes idealkb bin/test-follow.sh fixtures byte for byte; keeps the pin naming its source, one owner per file, the followers' gate), send-back (idealkb-exit3-sends-up's shape), cuttings (rhizoid-carries-mail-forks). Never a template engine, a merge of data or rows. Its base's items slice-consumption, followers-one-pin-bump, send-back-writes-the-upstream-item and implement-cli are reshaped to it. + +Last update +: 2026-11-18 diff --git a/research/base-graph/2026-11-18/graph-drift.sh b/research/base-graph/2026-11-18/graph-drift.sh new file mode 100755 index 0000000..176277a --- /dev/null +++ b/research/base-graph/2026-11-18/graph-drift.sh @@ -0,0 +1,111 @@ +#!/bin/sh +# graph-drift: does every edge of linux-phone-oco's repository graph carry what its source gives, in both directions, +# with something that moves it and something that says when it has not? Written failing, 2026-11-18 (research +# base-graph-measured, decision 2026-11-18-device-layer-from-docs). Reads git refs of the clones under PROJECTS +# (default ~/Projects, each fetched by the caller or with FETCH=1) and, for the forks and releases, gh and +# git ls-remote. Changes nothing. +# graph-drift.sh [PROJECTS] +# Prints one line per edge check, FAIL or ok; ends 1 when any FAIL, 2 when a clone is missing. +# +# Checks, each named in its line: +# slice-pin a base pins idealkb's latest release (the hourly job moves it) +# own-behind a file a base keeps as its own (own = [...]) is the source's at the pin, or an upstream item of the +# base names it: a change made below is on its way up, a change made above is not silently missed +# own-part a base whose tables.toml is its own still carries the source's marked part as the pin gives it +# layer-pin a device base pins its device layer by a release, not a date +# layer-owner the tables a docs feed reads from the device bases (parts) are given to them by docs itself, so a +# change of the contract is one change in one repository +# layer-follow every table a device base declares is its own or in a marked part a source gives +# tool-pin lab.toml pins the lpoco family at its latest release, or names why it holds +# tad-pin a base that installs tad pins its latest release, and tad's pin job lists the base +# fork-track a fork's tracking branch is its upstream's head +set -eu +P=${1:-$HOME/Projects} +LP=$P/linux-phone-oco +KB=$P/grenudi/ideal-knowledge-base +fail=0 +tmp=$(mktemp); trap 'rm -f "$tmp"' EXIT +say() { echo "$*"; case $1 in FAIL) fail=1 ;; esac; } +need() { [ -d "$1" ] || { echo "graph-drift: no clone at $1" >&2; exit 2; }; } +show() { git -C "$1" show "${3:-origin/main}:$2" 2>/dev/null; } +for d in "$KB" "$LP/docs" "$LP/device-template" "$LP/surya-lab" "$LP/google-walleye-lab" "$LP/lab-tools" "$P/lab-machine" \ + "$P/creation-guidelines/tad-engine"; do + need "$d"; [ "${FETCH:-0}" = 1 ] && git -C "$d" fetch -q --tags origin +done +latest_kb=$(git -C "$KB" tag -l 'v*' --sort=-v:refname | head -1 | sed 's/^v//') +part() { awk -v m="$1" '$0 ~ (m ":begin") { on = 1 } on && !/^[[:space:]]*#/ { print } $0 ~ (m ":end") { on = 0 }'; } +items() { show "$1" data/upstream_items.json | jq -r '[.id, .title, (.note // ""), (.local_ref // ""), (.file // "")] | join(" ")' 2>/dev/null; } + +# idealkb -> each base: the slice, and what each base keeps as its own +for b in docs device-template surya-lab google-walleye-lab; do + r=$LP/$b + pin=$(show "$r" idealkb.toml | sed -n 's/^version = "\(.*\)"$/\1/p') + if [ "$pin" = "$latest_kb" ]; then say ok "$b slice-pin: idealkb $pin"; else say FAIL "$b slice-pin: idealkb $pin, latest $latest_kb"; fi + own=$(show "$r" idealkb.toml | sed -n 's/^own = \[\(.*\)\]$/\1/p' | tr -d '" ' | tr ',' ' ') + carried=$(items "$r") + for f in $own; do + if [ "$f" = tables.toml ]; then + want=$(show "$KB" tables.toml "v$pin" | part idealkb); have=$(show "$r" tables.toml | part idealkb) + if [ -z "$have" ]; then say FAIL "$b own-part: tables.toml carries no idealkb part; nothing new of idealkb's tables reaches it" + elif [ "$want" != "$have" ]; then + printf '%s\n' "$have" > "$tmp" + n=$(printf '%s\n' "$want" | diff - "$tmp" | grep -c '^<' || true) + say FAIL "$b own-part: tables.toml's idealkb part lacks or differs in $n lines of idealkb $pin's" + else say ok "$b own-part: tables.toml's idealkb part is idealkb $pin's"; fi + continue + fi + if [ "$(show "$KB" "$f" "v$pin")" = "$(show "$r" "$f")" ]; then say ok "$b own-behind: $f is idealkb $pin's" + elif printf '%s\n' "$carried" | grep -qF "$f"; then say ok "$b own-behind: $f differs, and an upstream item carries it" + else say FAIL "$b own-behind: $f differs from idealkb $pin's and no upstream item names it - neither goes up nor comes down"; fi + done +done + +# the device layer: who gives it, by what pin, and whether its contract has one home +docs_tables=$(show "$LP/docs" tables.toml | grep -oE '^\[tables\.[a-z_]+\]' | tr -d '[]' | sed 's/^tables\.//') +tpl_part=$(show "$LP/device-template" tables.toml | part template | grep -oE '^\[tables\.[a-z_]+\]' | tr -d '[]' | sed 's/^tables\.//' || true) +kb_tables=$(show "$KB" tables.toml "v$latest_kb" | part idealkb | grep -oE '^\[tables\.[a-z_]+\]' | tr -d '[]' | sed 's/^tables\.//') +for b in surya-lab google-walleye-lab device-template; do + r=$LP/$b + src=$(show "$r" devicebase.toml | sed -n 's/^source = "\(.*\)"$/\1/p'); src=${src:-linux-phone-oco/device-template} + ver=$(show "$r" devicebase.toml | sed -n 's/^\(version\|template\) = "\([^"]*\)".*$/\2/p' | head -1) + if printf '%s' "$ver" | grep -qE '^[0-9]+\.[0-9]+\.[0-9]+$'; then say ok "$b layer-pin: $src $ver" + else say FAIL "$b layer-pin: the device layer is pinned as \"$ver\" - a date, no release of $src; nothing follows it"; fi + if [ "$src" = linux-phone-oco/docs ]; then say ok "$b layer-owner: the parts contract comes from docs, which reads it" + else say FAIL "$b layer-owner: parts is declared by $src and read by docs (records/feed-device-parts.sql): one contract, two repositories"; fi + for t in $(show "$r" tables.toml | grep -oE '^\[tables\.[a-z_]+\]' | tr -d '[]' | sed 's/^tables\.//'); do + printf '%s\n%s\n' "$kb_tables" "$tpl_part" | grep -qxF "$t" && continue + case $t in devices | parts | test_runs | test_results | steps) + say FAIL "$b layer-follow: table $t is the device layer's, in no marked part any source gives - carried by hand" ;; + esac + done +done +: "$docs_tables" + +# lab-tools -> the lab machine: the tool pin +lp=$(show "$P/lab-machine" lab.toml | sed -n 's/^lpoco = "\(.*\)"$/\1/p') +ll=$(git -C "$LP/lab-tools" tag -l 'lpoco-v*' --sort=-v:refname | head -1 | sed 's/^lpoco-v//') +if [ "$lp" = "$ll" ]; then say ok "lab-machine tool-pin: lpoco $lp" +else say FAIL "lab-machine tool-pin: lab.toml pins lpoco $lp, latest $ll; no job moves this pin and no line says why it holds"; fi + +# tad -> every base that installs it +tl=$(gh release list -R creation-guidelines/tad-engine --limit 10 --exclude-drafts --json tagName -q '[.[].tagName | select(startswith("tad-v"))] | first' | sed 's/^tad-v//') +cons=$(show "$P/creation-guidelines/tad-engine" consumers | grep -vE '^[[:space:]]*(#|$)') +for b in docs device-template surya-lab google-walleye-lab; do + tv=$(show "$LP/$b" bin/install-tad.sh | sed -n 's/^version="${TAD_VERSION:-\(.*\)}"$/\1/p') + if [ "$tv" = "$tl" ]; then say ok "$b tad-pin: tad $tv"; else say FAIL "$b tad-pin: CI installs tad $tv, latest $tl"; fi + printf '%s\n' "$cons" | grep -qxF "linux-phone-oco/$b" || say FAIL "$b tad-pin: tad's pin job does not list it (tad-engine consumers) - its pin is moved by hand" +done + +# upstream -> our forks: the tracking branch +s_up=$(git ls-remote https://git.sr.ht/~mil/sxmo-utils refs/heads/master | cut -f1) +s_us=$(gh api repos/grenudi/sxmo-utils/branches/master --jq .commit.sha) +if [ "$s_up" = "$s_us" ]; then say ok "grenudi/sxmo-utils fork-track: master is sr.ht's" +else + n=$(gh api "repos/grenudi/sxmo-utils/compare/$s_us...$s_up" --jq .ahead_by 2>/dev/null || echo "?") + say FAIL "grenudi/sxmo-utils fork-track: master is $n commits behind sr.ht's master; no job fetches it" +fi +k_up=$(gh api repos/sm7150-mainline/linux --jq .default_branch) +st=$(gh api "repos/grenudi/linux/compare/$(gh api repos/grenudi/linux --jq .default_branch)...sm7150-mainline:linux:$k_up" --jq .status 2>/dev/null || echo unknown) +case $st in identical) say ok "grenudi/linux fork-track: default branch is sm7150-mainline's $k_up" ;; +*) say FAIL "grenudi/linux fork-track: default branch is $st against sm7150-mainline's $k_up" ;; esac +exit $fail diff --git a/research/base-graph/2026-11-18/measured.md b/research/base-graph/2026-11-18/measured.md new file mode 100644 index 0000000..be8f7be --- /dev/null +++ b/research/base-graph/2026-11-18/measured.md @@ -0,0 +1,85 @@ +# linux-phone-oco's repository graph, measured 2026-11-18 + +What this folder holds: the measurement behind research rows base-graph-measured, base-graph-world and +base-graph-how-it-stands, and the failing test `graph-drift.sh` (decision 2026-11-18-device-layer-from-docs). +Read only git refs at origin/main (idealkb v0.16.0 8be549e, docs 608b61f, device-template d6eae9e, surya-lab +42da677, google-walleye-lab f0e0fc2, lab-machine fb75285), gh and git ls-remote. No phone, no repository changed. + +## The graph today + +``` + files, down (follow.sh, hourly) rows, up (DuckDB feeds, at main) + tad-engine ──tad pin (weekly job; lists docs, not the 3 device bases)──▶ every base + idealkb ──slice v0.16.0──▶ docs (7 own) · ideal-agent · device-template · surya-lab · google-walleye-lab (2 own each) + device-template ──10 statements + 4 tables, BY HAND (no release, pin a date)──▶ surya-lab · google-walleye-lab + surya-lab, google-walleye-lab ──parts.json (contract parts = 1, at main)──▶ docs (feed-device-parts) + docs ──component and step ids──▶ device bases: nothing carries them; ids agree today (20/21 claimed, 0 unknown) + lab-tools ──lpoco tag──▶ lab-machine lab.toml (by hand, 0.15.0; latest 0.17.0, same day) ──▶ every device.toml + sr.ht ~mil/sxmo-utils ──master, BY HAND──▶ grenudi/sxmo-utils (4 behind) ─3 topics─▶ lab ─tag lab-20261118.1─▶ lab-tools APKBUILD + sm7150-mainline/linux ──GitHub fork──▶ grenudi/linux (v7.2 identical) ─topic/fix/dt/test branches (10)─▶ each lab's kernel route + up, files: an edited followed file ends follow.sh with 3 and leaves a PR in the follower for a person; nothing + reaches the source. Upstream items: docs 0 to idealkb, 0 to device-template; each lab 0. +``` + +Edges with a job that moves them: 3 (idealkb slice, tad pin, docs feeds). By hand: 6 (template slice, device +tables, catalogue ids, lpoco pin, sxmo tracking, every upward change). Behind today: 5 (template slice in every +lab, docs' own statements, tad in docs' CI, lpoco in lab.toml, sxmo master). + +## Measured, edge by edge + +1. idealkb -> 5 bases. Every pin 0.16.0, current (journal of idealkb-update-pins: hourly, "current" at 15:04). + Since v0.16.0 a source names its pin file and marker (`#! pin`, `#! marker`), update-pins walks ./sources + (device-template listed, skipped: no release) and check-one-owner stops the job when two lists name a file. +2. own, the one-way exit. A file in `own` is never laid again; follow.sh only prints "idealkb changed it" into a + commit message. docs keeps 7 own files; 6 statements differ from idealkb 0.16.0's (about.sql 43 diff lines, + decision.sql 39, backlog.sql 38, source.sql 21, research.sql 11, session-log.sql 9). docs' records/decision.sql + has 0 of --supersedes, --amends, --scope, --tracked-by (idealkb 0.14.0, decision-links): docs cannot record + a superseding decision through its record, although its AGENTS.md and tables ask for it; 0 decisions in docs + carry supersedes or amends. docs' tables.toml has no idealkb part at all. Each device base's tables.toml + (own) carries an idealkb part that lacks 101 non-comment lines of 0.16.0's (the supersedes/amends/tracked_by + reference rules; hardware moved). Their own backlog.sql differs by 4 lines. No upstream item names any of it. +3. device-template -> 2 labs. template-drift.sh today: 18 FAIL classified on the template, pin and no-copy FAIL + per lab; the 10 statements equal (by hand). The device tables (devices, parts, test_runs, test_results) sit + in each lab's tables.toml outside any marker: equal by hand, followed by nothing. +4. The contract has two homes. parts is declared by device-template (tables.toml, devicebase.toml parts = 1) + and read by docs (records/feed-device-parts.sql); bring-up steps: catalogue and edges in docs, the claim + table to ship in the template (decision 2026-11-18-bringup-steps-generic-in-docs-status-in-each-base). Every + contract change is two PRs in two repositories and two release trains. +5. tad: docs' CI installs 0.6.0, the labs 0.7.1 (latest tad-v0.7.1); tad-engine's consumers lists docs and not + device-template, surya-lab, google-walleye-lab - their pins move by hand. +6. lab.toml pins lpoco 0.15.0 (landed 2026-11-18); lpoco-v0.17.0 tagged 15:30 the same day; nothing moves it. +7. grenudi/sxmo-utils master 303c755 is 4 commits behind sr.ht master 1fd7822; no job fetches sr.ht. + grenudi/linux default v7.2 is identical to sm7150-mainline's (GitHub keeps the fork). + +## The failing test + +`graph-drift.sh [PROJECTS]` - today exit 1: 36 FAIL, 9 ok. It passes when: every own file is the source's or +on its way up (an item names it); every own tables.toml keeps the source's part; each device base pins its +device layer by a release of docs; the device tables are in docs' marked part; lab.toml's lpoco is current; +every base's tad is current and listed; sxmo's master tracks sr.ht. + +## Outside (two researcher reports, read at source 2026-11-18) + +Down and up for root-level files: no Rust or shell tool does both (subtree/subrepo/submodules need a prefix; +Android repo copies outside git, Python; Nix inputs live in the store and cannot be patched, nix#3920; copier +and cruft are down-only, Python; Renovate, multi-gitter, turbolift are down-only). copybara does both +(CHANGE_REQUEST from a follower's PR to the source, GitOrigin-RevId, check_last_rev_state, merge_import) at the +cost of a JVM 21 and Starlark per workflow. josh (Rust, r26.08.28) maps single files at the root (`::f`, +`::dest=src`) and pushes back through a view, but its source of truth is one monorepo, and a follower cannot +keep its own variant; push back from a multi-repo follower is not known. + +Layering: Yocto (oe-core -> distro -> BSP) - one owner per recipe, overrides as named .bbappend, a dangling +append an error, LAYERSERIES_COMPAT fatal, Upstream-Status required on every patch and an error by default, +yocto-check-layer forbids a BSP changing others' signatures. Gentoo - masters non-transitive (each overlay names +every ancestor), MasterPackageClobbered an error. Debian DEP-3 - Forwarded/Applied-Upstream; only 9.4% of +trixie's patches forwarded: labels that only warn do not move work. Kernel - upstream first, stable's +"commit X upstream", linux-next merges every tree regularly and mails each conflict to both owners; ACK tags +every carried commit UPSTREAM/BACKPORT/FROMGIT/FROMLIST/ANDROID. stgit is Rust (2.7.0) and finds landed patches +(rebase --merged); topgit merges along .topdeps (dormant since 2025-01); `git cherry` finds a landed patch by +patch-id with no tool at all. b4, gbp, quilt-tools, copier, repo: Python, refused here. + +Taken: one owner per file (have it: check-one-owner); an override is named and carries a status, and a missing +status fails (Yocto, DEP-3); upstream first, the copy carries where it came from (kernel stable); the integrator +reports each drift to its owner on a schedule (linux-next); a follower's edit becomes a change request on the +source (copybara); landed patches found by patch-id (git cherry); the middle layer owns the contract the +lowest is checked against (Yocto check-layer, ACK KMI). Set aside: every tool above as a runtime.