docs: differential release + upstream-watch contracts

Author: andrescera

AGENTS.md

@@ -77,9 +77,32 @@ do not reach up the tree.
 
 SemVer, **not** CalVer — this repo is the documented exception (alongside `srtla-send-rs`).
 ONE unified tag `vX.Y.Z` releases **both** artifacts: `@ceralive/modem-control@X.Y.Z` on
-npm and the `.deb` set. `.deb` versions encode the tag as `<upstream>-<rev>~ceralive<X.Y.Z>`
-(upstream-ordered, apt-safe; injected with `dch --force-bad-version`). Non-tag CI builds use
-`~ceralive0.0.0~dev`. Full contract: `docs/VERSIONING.md`.
+npm and the `.deb` set. Non-tag CI builds use `~ceralive0.0.0~dev`. Full contract:
+`docs/VERSIONING.md`.
+
+**`.deb` versions no longer encode the tag.** Releases are DIFFERENTIAL, so each upstream
+source carries its own rebuild counter: `<upstream>-<rev>~ceralive.N` (upstream-ordered,
+apt-safe; injected with `dch --force-bad-version`). A REBUILT source takes its previous
+counter + 1, derived from the previous release manifest's rows for that source; an
+UNTOUCHED source is carried forward byte-identically and keeps the counter it already had,
+never re-stamped with the new tag. Two sources at different counters in one release is the
+normal shape, not drift — coherence is a PER-SOURCE property, and a source disagreeing with
+ITSELF fails closed naming that source. Derivation reads every row of a source (both arches,
+runtime and aux) and refuses on a counter disagreement, a counter/legacy mixture, or a
+malformed suffix; entirely-legacy rows and an absent previous manifest bootstrap at `.1`.
+
+The pre-`v1.0.0` releases WERE built with one uniform `~ceralive<X.Y.Z>` suffix shared by all
+four sources; those published artifacts are unchanged. No release mixes the two schemes — the
+first differential release force-rebuilds every source at `.1`, because this effort's own
+`packaging/ci/**` changes are a shared build input and force-all on their own. The
+migration-continuity chain `~ceralive0.2.0 < ~ceralive1.0.0 < ~ceralive1.1.0 < ~ceralive.1 <
+~ceralive.2 < ~ceralive.10 < <upstream>-<rev>` is proven with real `dpkg --compare-versions`
+by the ONE sourced library `packaging/ci/suffix-contract.sh`, from both
+`test-suffix-coherence-manifest.sh` (host) and `test-package-contract.sh` CHECK 5/6
+(container). The release manifest states `suffix_scheme: per-source-counter` and carries **no
+`deb_version_suffix:`** — under per-source counters no single suffix value is truthful. The
+companion `ceralive-modem-support` stays outside this entirely: bare SemVer tag version, no
+`~ceralive` suffix, and always rebuilt.
 
 ## FROZEN V1.1 DOMAIN CONTRACTS
 
@@ -249,6 +272,17 @@ arch-dependent stanzas + enumerated `-dbgsym`) for exact per-source set **equali
 `packaging/ci/check-package-sets.sh` (add/remove/rename fails closed). Full detail:
 `packaging/README.md`.
 
+**The pins are watched, never auto-bumped.** `.github/workflows/upstream-watch.yml` runs
+weekly (plus `workflow_dispatch`) and calls `packaging/ci/check-upstream-freshness.sh`, which
+enumerates each source's upstream release tags and salsa `debian/*` packaging tags via
+`git ls-remote --tags`, filters the development series out, and compares the survivors to the
+four pins above. On `behind` it opens **or updates** ONE issue labelled `upstream-freshness`,
+and closes it when everything is current again. It is **issue-only**: it never edits
+`upstream-pins.yaml` and never dispatches a build, which is why it is the only workflow here
+holding `issues: write` and no dispatch token. A newer upstream release with no matching
+Debian packaging tag reports the distinct `upstream-ahead-no-packaging` — there is no
+`<upstream>-<rev>` pair to pin, so there is no bump to recommend.
+
 ## MUTATION ADMISSION + EXCLUSIVE OWNERSHIP
 
 `control/src/ports/mutation-admission.ts` defines `MutationAdmissionPort`. It is an injected
@@ -1350,13 +1384,44 @@ major action versions, per-manager caches, weekly grouped Dependabot, test-befor
      before any other job). Exports `version` + `sha`.
   2. **test** (needs tag-guard) — full bun lane + packaging contract lane
      (test-before-publish).
-  3. **build-deb** (needs [tag-guard, test]) — injects `<upstream>-<rev>~ceralive<X.Y.Z>`
-     (non-tag runs `~ceralive0.0.0~dev`) via `packaging/ci/inject-deb-version.sh`, builds both
-     arches, runs the package contract suite + daemon smoke, builds the `Architecture: all`
-     companion ONCE (`packaging/ci/build-companion.sh`) and runs its clean-chroot contract
-     (`packaging/ci/test-companion-chroot.sh`), generates the manifest-complete
-     release manifest (`packaging/ci/generate-release-manifest.sh`), and uploads the `.deb`
-     artifacts + manifest.
+  3. **build-deb** (needs [tag-guard, test]) — the **DIFFERENTIAL** `.deb` job. Steps, in file
+     order: **Checkout the resolved commit** (`fetch-depth: 0` — load-bearing here and nowhere
+     else, since the detector diffs `<prev-tag>..HEAD`; a shallow checkout would silently
+     force-all forever) → **Assert checkout is pinned to the resolved SHA** → **Set up QEMU
+     (arm64 emulation)** → **Resolve previous release + fetch its manifest (once)**
+     (`id: prev-release`; `gh release list`, never `git describe` — the previous release is the
+     latest PUBLISHED one; no release or no manifest asset leaves both outputs empty, which is
+     the bootstrap case, not an error) → **Detect changed sources (per-source verdicts)**
+     (`packaging/ci/detect-changed-sources.sh --out verdicts.txt`) → **Stage carry-forward debs
+     (unchanged sources, sha256-verified)** (`packaging/ci/stage-carryforward-debs.sh`) →
+     **Build the MM 1.24 stack (.deb) — amd64 + arm64** (`build-bookworm.sh amd64` /`arm64`,
+     with `VERDICTS_FILE` + the already-resolved `PREV_MANIFEST_FILE`) → **Package contract
+     suite** (amd64 full, arm64 metadata) → **Daemon smoke (amd64)** → **Build the first-party
+     companion .deb (Architecture: all)** (UNCONDITIONAL — the companion is never detected and
+     never carried) → **Companion package contract (clean Debian chroot)** → **Generate release
+     manifest** (`packaging/ci/generate-release-manifest.sh`) → **Upload .deb artifacts +
+     release manifest**.
+
+     Three things about that order are load-bearing. The previous release is resolved and its
+     manifest downloaded **exactly once**, and that one path feeds all three consumers
+     (detection, carry-forward staging, per-source counter derivation). Carry-forward staging
+     runs **strictly before any `build-bookworm.sh` call**, because carried debs are a build
+     INPUT — `build-bookworm.sh` seeds its Pin-Priority-1001 local apt repo from
+     `packaging/build/<arch>/`, so a changed source resolves its build-deps and gir typelibs
+     against the carried `-dev`/`gir1.2-*` packages rather than stock bookworm; staging late
+     still goes green and silently reintroduces stock dependencies, which is why
+     `packaging/ci/test-release-workflow-wiring.sh` pins the ordering statically. And a
+     zero-build run starts no container at all yet still asserts the merged runtime closure
+     over the carried set.
+
+     Detection is **fail-SAFE toward rebuilding**: an absent previous release, a manifest with
+     no `closure_version:` header (an absent header IS closure version 1), a shared-input
+     change under `packaging/ci/**` or `packaging/BOOKWORM-ADAPTATIONS.md`, or the operator's
+     escape hatch all yield `mode=force-all`. That escape hatch is the `force_rebuild`
+     `workflow_dispatch` boolean input (default `false`), mapped to the script's
+     `FORCE_REBUILD=all` env via
+     `${{ github.event.inputs.force_rebuild == 'true' && 'all' || '' }}` — defense in depth, since
+     a shared-input change force-alls on its own.
   4. **publish-npm** (needs [tag-guard, build-deb]) — OIDC trusted publishing
      (`id-token: write`), verifies `control/package.json` version === tag, then an
      **integrity-idempotent** publish: `npm pack` → classify registry state (404 → publish;
@@ -1379,6 +1444,22 @@ major action versions, per-manager caches, weekly grouped Dependabot, test-befor
   the release exists. An operator's own `gh api` call would test the operator's CLI token and
   prove nothing about the repository secret — which is exactly why this lives here.
   `cancel-in-progress: false` (never cancel a release/publish mid-run).
+- **`.github/workflows/upstream-watch.yml`** — the weekly **upstream freshness watch**
+  (schedule + `workflow_dispatch`, `cancel-in-progress: false`). Runs
+  `packaging/ci/check-upstream-freshness.sh`, which enumerates each source's upstream release
+  tags and salsa `debian/*` packaging tags via `git ls-remote --tags`, filters out the
+  development series, and compares the survivors to the pins. On `behind` it opens **or
+  updates** ONE issue labelled `upstream-freshness`; when everything is current again it closes
+  it. **Issue-only** — it never edits `packaging/upstream-pins.yaml` and never dispatches a
+  build, which is why it is the ONLY workflow here that escalates `issues: write` and why it
+  holds no dispatch token. The stable filter is the substance: all four projects publish their
+  unstable train on the same tag namespace (ModemManager `1.25.95` → Debian *experimental*), so
+  `-rc`/`-dev`, non-`X.Y.Z`, **odd-minor** and `.9x`-micro tags are rejected, as are `~`-bearing
+  Debian revisions. A newer upstream release with no Debian packaging tag reports the distinct
+  `upstream-ahead-no-packaging` — NOT `behind`, because with no `<upstream>-<rev>` pair there is
+  no bump to recommend. `packaging/ci/test-check-upstream-freshness.sh` pins all of it offline
+  through a fixture seam. NOTE: GitHub disables scheduled workflows after 60 days of repository
+  inactivity — a silent watch reads exactly like an up-to-date one.
 
 Action pins track the latest stable **major** (resolved via the `gh api` releases/latest
 endpoint); Dependabot keeps them current. JS/TS CI runs on **Node 26** — the CeraLive CI

docs/VERSIONING.md

@@ -31,53 +31,131 @@ Do **not** apply the CalVer scheme here. The rationale, and the parallel excepti
 convention. Everything in this repo — the git tag, the npm version, and the `~ceralive`
 suffix below — is SemVer.
 
-## `.deb` version encoding
+## `.deb` version encoding — per-source rebuild counters
 
 The `.deb` internal `Version:` field must stay **upstream-ordered** so `apt` compares
-releases correctly, while still encoding which repo tag produced the rebuild. The
-encoding is:
+releases correctly, while still recording that this is a CeraLive rebuild and how many
+times that particular source has been rebuilt. The encoding is:
 
 ```
-<upstream>-<rev>~ceralive<X.Y.Z>
+<upstream>-<rev>~ceralive.N
 ```
 
-For the current pins at repo tag `v0.2.0` (the latest release — the ModemManager revision
-is `-2`, the other three `-1`):
-
-| Source | Upstream | Encoded `.deb` version |
+`N` is that **source's own rebuild counter**, not the release tag. Releases are
+differential: only the sources whose inputs actually moved are rebuilt, and only a rebuilt
+source's counter advances. Release provenance lives in the release manifest; the package
+version records the rebuild count.
+
+- A **rebuilt** source takes its previous counter **+ 1**. The previous counter is derived
+  from the previous release manifest's rows for that source, by
+  `packaging/ci/inject-deb-version.sh`.
+- An **untouched (carried-forward)** source keeps whatever counter it already had. Its
+  `.deb`s are the byte-identical artifacts from the release that last built them; they are
+  **not** re-stamped with the new release's tag. Builds are not reproducible, so reusing
+  recorded bytes is the only honest way to keep a release self-contained.
+- Different sources therefore legitimately carry **different** counters within one release.
+  That is the normal shape of a differential release, not drift.
+
+Counter derivation is **coherence-checked and fail-closed**. Every previous-manifest row
+for the source is read — both arches, `role=runtime` and `role=aux` alike — and the counter
+is accepted only if all of them agree. Three conditions refuse the release outright, each
+naming the offending source:
+
+| Condition | Why it refuses |
+|-----------|----------------|
+| rows disagree on the counter (`.2` vs `.3`) | picking either risks publishing a downgrade |
+| rows mix counter and legacy `~ceraliveX.Y.Z` suffixes | the source's history is ambiguous |
+| a row's suffix is neither `~ceralive.[1-9][0-9]*` nor `~ceraliveX.Y.Z` | malformed input |
+
+Two cases **bootstrap at `.1`** instead: a source whose previous-manifest rows are entirely
+legacy, and a rebuild with no previous manifest at all (the force-all bootstrap).
+
+The current pins are ModemManager 1.24.2 (revision `-2`), libmbim 1.34.0, libqmi 1.38.0 and
+libqrtr-glib 1.4.0 (all `-1`), so a release that rebuilt only libqmi while the other three
+carried forward from `.1` would produce:
+
+| Source | Rebuilt? | Encoded `.deb` version |
 |--------|----------|------------------------|
-| ModemManager  | 1.24.2 | `1.24.2-2~ceralive0.2.0` |
-| libmbim       | 1.34.0 | `1.34.0-1~ceralive0.2.0` |
-| libqmi        | 1.38.0 | `1.38.0-1~ceralive0.2.0` |
-| libqrtr-glib  | 1.4.0  | `1.4.0-1~ceralive0.2.0`  |
+| ModemManager  | carried  | `1.24.2-2~ceralive.1` |
+| libmbim       | carried  | `1.34.0-1~ceralive.1` |
+| libqmi        | rebuilt  | `1.38.0-1~ceralive.2` |
+| libqrtr-glib  | carried  | `1.4.0-1~ceralive.1`  |
+
+> The authoritative pin manifest is `packaging/upstream-pins.yaml`; the release workflow
+> derives `<upstream>-<rev>` from each source's `debian/changelog`, never from a value
+> hardcoded in the version script.
+
+### The legacy suffix, and the migration into counters
+
+Every release through `v0.2.0` used a different scheme: one `~ceralive<X.Y.Z>` suffix,
+identical across all four sources, taken from the release tag. Those artifacts are
+published and unchanged — `1.24.2-2~ceralive0.2.0` is still exactly what a fleet device has
+installed. What changed is what the pipeline produces from here on.
 
-> The upstream versions above are the current provenance-verified pins. The authoritative
-> manifest is `packaging/upstream-pins.yaml`; the release workflow derives `<upstream>-<rev>`
-> from each source's `debian/changelog`, never from a value hardcoded in the version script.
+There is no release that mixes the two schemes. The first release built from the
+differential pipeline **force-rebuilds every source at `.1`**, because this effort's own
+changes under `packaging/ci/**` are a shared build input, and a shared-input change in the
+diff against the last published release force-alls on its own. So the transition happens in
+one release, for all four sources at once, and no manifest ever carries a legacy suffix
+beside a counter suffix.
 
-### Why the tilde (`~`)
+### Why the tilde (`~`), and why the chain still orders
 
-`dpkg` orders a `~` suffix **lower** than the un-suffixed version:
+`dpkg` orders a `~` suffix **lower** than the un-suffixed version, and orders the counter
+suffix above every legacy one. The full **migration-continuity chain**, exactly as
+`packaging/ci/suffix-contract.sh` proves it:
 
 ```
-1.24.2-2~ceralive0.1.0  <  1.24.2-2~ceralive0.2.0  <  1.24.2-2
+<base>~ceralive0.2.0 < <base>~ceralive1.0.0 < <base>~ceralive1.1.0
+  < <base>~ceralive.1 < <base>~ceralive.2 < <base>~ceralive.10 < <base>
 ```
 
-So every CeraLive rebuild sorts **below** a hypothetical stock Debian `1.24.2-2`, and a
-newer repo tag (`0.2.0`) sorts **above** an older one (`0.1.0`) — exactly the ordering
-`apt` needs. This is why the release workflow injects the version with
-`dch --force-bad-version`: the tilde-encoded version is numerically **lower** than the
-pinned `<upstream>-<rev>` changelog top, and plain `dch --newversion` refuses a
-lower-than-current version (per `dch(1)`). `--force-bad-version` is **required**, not
-optional.
+(`<base>` is the source's `<upstream>-<rev>`, e.g. `1.24.2-2`.) Its legacy members are every
+version that exists as a published artifact today, so the chain is the proof that a fleet
+device upgrades cleanly from any shipped release into the counter scheme, and that every
+CeraLive rebuild still sorts **below** a hypothetical stock Debian `1.24.2-2`.
 
-The exact injection command, run once per source, is:
+Nothing here is asserted on paper. `prove_chain_ordered` runs the whole chain through real
+`dpkg --compare-versions`, and it is exercised from both lanes: the host-runnable
+`packaging/ci/test-suffix-coherence-manifest.sh` (which also carries a non-vacuity control
+showing a lexical compare inverts `.2` against `.10`) and the container suite
+`packaging/ci/test-package-contract.sh` CHECK 6. CHECK 5 is the coherence half — sources at
+differing counters pass, a source disagreeing with **itself** fails closed naming that
+source.
+
+Tilde ordering is also why the workflow injects with `dch --force-bad-version`: the
+tilde-encoded version is numerically **lower** than the pinned `<upstream>-<rev>` changelog
+top, and plain `dch --newversion` refuses a lower-than-current version (per `dch(1)`).
+`--force-bad-version` is **required**, not optional.
+
+The exact injection command, run once per **rebuilt** source, is:
 
 ```sh
-dch --force-bad-version --newversion "<upstream>-<rev>~ceralive<X.Y.Z>" "CeraLive rebuild"
+dch --force-bad-version --newversion "<upstream>-<rev>~ceralive.N" "CeraLive rebuild"
 ```
 
-All four sources take the **same** `~ceralive<X.Y.Z>` suffix for a given release.
+### The manifest header states the scheme, not a value
+
+Under per-source counters no single suffix value is truthful for a release, so the release
+manifest carries:
+
+```
+suffix_scheme: per-source-counter
+```
+
+and **no `deb_version_suffix:` header** — that field no longer exists in any manifest this
+repo produces. Every row keeps carrying its own version, which it always did (rows are
+parsed from real filenames), so a carried-forward deb at an old counter and a freshly built
+one at a new counter both emit correctly. `version:` is unrelated and stays: it is the
+release's own SemVer, not a per-deb suffix.
+
+### The companion is outside this scheme entirely
+
+`ceralive-modem-support` is a first-party native package with no upstream version to order
+against. It takes the repo's SemVer tag **verbatim** (`v1.1.0` → `1.1.0`) with no
+`~ceralive` suffix at all, and it is **always rebuilt** — it is never detected, never
+verdicted, and never carried forward. That is unrelated to the counter scheme, and neither
+rule affects the other.
 
 ## Tag guard (fail-closed)
 
@@ -92,7 +170,7 @@ Anything that does not match **fails closed before any other job runs**. In part
 | Input | Result | Why |
 |-------|--------|-----|
 | `v1.0.0` | ✅ accepted | canonical `vX.Y.Z` |
-| `v1.0.0-rc.1` | ❌ rejected | a pre-release tag inverts dpkg ordering — the rc's tilde-encoded version would outrank the final release (`~ceralive1.0.0-rc.1` vs `~ceralive1.0.0`), which is wrong |
+| `v1.0.0-rc.1` | ❌ rejected | a pre-release tag inverts dpkg ordering — the companion takes the tag verbatim, and `dpkg` reads the `-rc.1` as a Debian revision, so the rc would sort **above** the final `1.0.0`, which is wrong |
 | `v1.0.0+build5` | ❌ rejected | build metadata has no meaning in a `.deb` version and is not part of the contract |
 | `1.0.0` | ❌ rejected | missing the `v` prefix |