modem-stack: Phase-B adoption docs sweep + POLICY amendment + v1.0.0 version bump - #10
Merged
Conversation
PR #6 (actions/setup-qemu v3->v4) squash-merged and rebased in. PR #9's npm group (Biome 2.5.4->2.5.5 + TypeScript 5.9.3->7.0.2) closed: the TS major bump is forbidden by policy, so only the Biome patch bump is taken here; Dependabot re-raises TypeScript standalone if it clears the existing major-version ignore rule in .github/dependabot.yml (already present, verified unchanged).
…ounded, disabled-by-default recovery)
…-gated catalog ingestion
…th, transfer impossibility, validation checklist)
Document the uhubctl PowerHook (recovery-ladder rung 4), the hil-cycle HIL harness, the full RB-9..RB-17 bench-runbook ladder, and the eSIM investigate-only decision doc in AGENTS.md/README.md. Amend POLICY.md §4 so the Phase-A scope boundary reads as adoption-versioned: integration into CeraUI/device-image/apt is authorized starting at the v1.0.0 tag rather than blanket-forbidden, while preserving the accurate historical record that every release through v0.2.0 was Phase-A-only. Mirror the same amendment in README.md and packaging/README.md so no stale 'Phase A: no integration' claim survives outside POLICY.md's historical section.
… gate) Bumps @ceralive/modem-control (control/package.json) and modem-control-cli (cli/package.json) from 0.2.0 to 1.0.0, the version POLICY.md §4 and docs/VERSIONING.md reserve for Phase-B adoption. This is the version bump only — no tag is cut here (release is a separate, later step: workflow_dispatch on release.yml with tag v1.0.0). Pre-checked that no CI lane couples control/package.json's version to an existing tag/npm state on a non-tag build: ci-bun.yml only lints/typechecks/tests; ci-packaging.yml's contract.sh never reads control/package.json (it only handles the four packaging/ debian/changelog files via read-pin.sh); release.yml's version-vs-tag assertion lives in publish-npm, which only runs on workflow_dispatch with an explicit tag input and is not reachable from a PR or a push to this branch. bun install produced zero bun.lock drift (workspace members are referenced by name, not by version, in the lockfile's resolution table) — bun install --frozen-lockfile and git diff --exit-code -- bun.lock both exit 0.
…ive sampler apply)
…h-A HARD STOP An RB-16 re-run on bench ceralive2 found a physically connected Fibocom FM350-GL enumerating over USB as 0e8d:7127, bound by rndis_host + option (not the cdc_mbim the Branch-A template predicted, and not the documented PCIe mtk_t7xx path — the PCI bus still shows nothing). ModemManager 1.24.2 claims it via the generic fallback plugin as Modem/4, state failed / sim-missing. This is the decision record's own branch-1 contrary-evidence HARD STOP, so this change records evidence and nothing else: Branch-A steps 1-3 only. No classifier entry, branch, type, or fixture is added; the three-gate ledger table is left verbatim; the support matrix is untouched. 0e8d matches none of the previously considered identities (PCI 14c3, fibocom-USB 2cb7/1782/ 1508) — hwdb resolves it to MediaTek's USB vendor id. Also noted: RB-16's literal candidate list (0e8d:7126|14c3:4d75) reports "not connected" against this board. Widening it is deferred to the same human decision that governs the classifier question.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Closes out modem-stack's Wave 0+1 (todos 1-10, already merged onto this branch) with the integration housekeeping: doc sweep, the POLICY.md Phase-A→Phase-B scope amendment, and the
1.0.0version bump for both workspace packages. No source/behavior changes — this PR is docs + one version-bump commit.AGENTS.md/README.md: document theuhubctlPowerHook (recovery-ladder rung 4,control/src/backend/uhubctl-power-hook.ts), thehil-cycleHIL harness (bench runbook RB-10), the full RB-9..RB-17 bench-runbook ladder, and add thedocs/ESIM-DECISION.mdpointer (eSIM is investigate-only, implementation deferred).POLICY.md§4: amended from a blanket "Phase A only, no CeraUI/image/apt integration" statement to an adoption-versioned one — integration is authorized starting at thev1.0.0tag, not before, while §1-3 (no-fork gate, upstream-first) remain permanently binding. The historical fact that every release throughv0.2.0was Phase-A-only is preserved, not scrubbed.README.mdandpackaging/README.mdcarry the same amendment so no stale "Phase A: no integration" claim survives outside POLICY.md's own record of it.control/package.json(@ceralive/modem-control) andcli/package.json(modem-control-cli):0.2.0→1.0.0, the versionPOLICY.md§4 anddocs/VERSIONING.mdreserve for Phase-B adoption.No tag is cut in this PR.
v1.0.0is released later (a separateworkflow_dispatchonrelease.yml), once CeraUI's and image-building-pipeline's own Phase-B waves are also ready to consume it.Why
This is the last modem-stack todo in the current effort. The repo's
docs/VERSIONING.mdalready reserved1.0.0for "Phase-B adoption"; this PR is what actually enacts that reservation in the version files and in the policy text that currently forbids any downstream integration outright. Bumping now (rather than at tag time) means the tag, when cut, releases exactly what this PR's gates already proved green — no second PR, no last-minute version-file diff at release time.How to verify
.github/workflows/{ci-bun.yml,ci-packaging.yml,release.yml}andpackaging/ci/*.sh. Confirmed no lane assertscontrol/package.json's version against an existing tag/npm/deb state on a non-tag (PR/push) build —ci-bun.ymlonly lints/typechecks/tests;ci-packaging.yml'scontract.shnever readscontrol/package.json(only the four packagingdebian/changelogfiles); the one version-vs-tag assertion (release.yml'spublish-npmjob) only runs on manualworkflow_dispatchwith an explicit tag input, unreachable from this PR.bun install --frozen-lockfile→ exit 0.git diff --exit-code -- bun.lock→ exit 0 (zero drift; workspace members are referenced by name, not version, in the lockfile's resolution table).bunx tsc --noEmit→ exit 0.bunx biome check .→ exit 0 (171 files).dbus-run-session -- bun test→ 396 pass / 0 fail across 50 files.bash packaging/ci/contract.sh→ PASS (scaffold, tag-guard contract, dpkg tilde-ordering proofs all green;dchabsent in this sandbox, which the script itself detects and documents rather than failing).0.2.0self-reference incli/. The0.2.0mentions remaining indocs/BENCH.md/docs/VERSIONING.mdare accurate as-is —v0.2.0really is the latest released tag untilv1.0.0is actually cut (a later step), so those are correctly-retained current-state text, not stale claims.Risks
packaging/ci/{build-bookworm.sh,test-package-contract.sh,daemon-smoke.sh}— these build real.debs in adebian:bookwormcontainer and need a working Docker daemon; this sandbox's Docker context is Docker Desktop, which this stack's own tooling refuses as a runner daemon (same known limitation recorded forimage-building-pipeline). This is not a gap in this PR's own gate: those three scripts arerelease.yml-only (tag-triggered), not part ofci-packaging.yml's PR lane, so nothing in this diff exercises them.bun.lockhas no diff to commit — bumping a workspace member's own version doesn't touch its resolution-table entry (verified, not assumed).v1.0.0tag existing.Update — three further commits on this branch
The branch advanced past the version bump before merge. The PR now carries real source
changes in addition to the docs/policy/version work described above, so the "docs +
one version-bump commit" framing at the top applies only to the original three commits.
9b9184bfeat(usage):setUsagePolicywrite surface — the WRITE half of thedata-usage surface (
control/src/backend/usage/policy-write.ts+policy-store.ts).It persists a slot's cycle day and advisory threshold to a local 0600 policy file
and, when a live
UsageSampleris supplied, applies them in the same call. It writes alocal file and never the modem, because ModemManager exposes no data-usage API at all:
verified against a live MM 1.24.2 that the only
Setup/threshold surface on the objectis
Modem.Signal.Setup(rssi-threshold/error-rate-threshold— radio quality, notbytes), and the only byte counters are the per-bearer read-only
Stats, which reset onevery connection and so cannot carry a monthly cycle. Typed results rather than throws
(called from an RPC boundary), tri-state fields (
undefinedleaves alone,nullclears), order is load → validate → persist → apply, and an applied policy outranks a
later observation carrying the old one for the process lifetime.
4d53b09,eb71039docs(fm350) — record the real FM350-GL observed on USB(Citation 6) and close the adapter-mediated decision stop in
docs/FM350-DECISION.md.Documentation only; the modem stays documented-deferred, not supported.
Verification on the merged head (
eb71039)bun install --frozen-lockfile→ exit 0,bun run lint(Biome, 175 files) → exit 0,bun run typecheck(tsc --noEmit, strict +exactOptionalPropertyTypes) → exit 0.bun test→ 448 pass / 0 fail, 9274expect()calls across 52 files.Packaging contract (bookworm).
npm pack ./control --dry-run→@ceralive/modem-control@1.0.0, 121 files — theexact tarball CeraUI's consumer-side skew test was proven against before publish.
The
.deb-building lanes remainrelease.yml-only (tag-triggered) and are unchanged bythese commits; they run for real when
v1.0.0is dispatched.