From a1f217709fae56d884ecfbf15de8e4ce8fe87658 Mon Sep 17 00:00:00 2001 From: Andres Cera Date: Fri, 24 Jul 2026 14:13:42 -0500 Subject: [PATCH] docs: record the runtime-package version contract (#20) AGENTS.md named no package version and did not mention the package-contract gate's version/Provides/SONAME locks. Record 1.5.6+ceralive.1, the versioned Provides that lets it replace both Debian TLS flavours, and the apt/R2 percent-encoding consequence of the '+' in the version. --- AGENTS.md | 30 +++++++++++++++++++++++++++++- 1 file changed, 29 insertions(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 4c29a0fb3..7eca06ba5 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -8,7 +8,9 @@ Parent: [`../AGENTS.md`](../AGENTS.md) - **SONAME:** `libsrt.so.1.5` - **Runtime package:** `libsrt1.5-ceralive` for arm64 and amd64, built by - `packaging/build-deb.sh` with the GnuTLS backend. + `packaging/build-deb.sh` with the GnuTLS backend. Current version + **`1.5.6+ceralive.1`** (`master` carries upstream v1.5.6, incl. the KMREQ CVE + fixes). The `+`-bearing version is deliberate — see the packaging contract below. - **Device use:** image-building-pipeline stages it from apt.ceralive.tv and installs it before `cerastream`. It replaces the Debian GnuTLS/OpenSSL flavors and provides their virtual package names; GStreamer and cerastream resolve one @@ -34,6 +36,32 @@ re-checks the installed binary's `ldd`. `package-contract.sh` locks `ENABLE_APPS=ON` + `ENABLE_STATIC=OFF` so the tools can never silently drop out or gain a static/second-flavor libsrt. +### Runtime-package version contract (#20) + +`packaging/package-contract.sh` is a STATIC gate — it reads the packaging sources +and workflows, so it runs without building. It locks, in addition to the +`ENABLE_APPS`/`ENABLE_STATIC` flags above: + +| Locked | Current value | +|--------|---------------| +| `.deb` version | `1.5.6+ceralive.1` (`CERALIVE_SRT_VERSION` default in `build-deb.sh`) | +| `Provides` | `libsrt1.5-gnutls (= 1.5.6)`, `libsrt1.5-openssl (= 1.5.6)` | +| `Conflicts` / `Replaces` | `libsrt1.5-gnutls`, `libsrt1.5-openssl` | +| SONAME | `libsrt.so.1.5` | +| No stale pin | neither `publish-release.yml` nor `runtime-package.yml` may retain a `1.5.5` reference | + +The versioned `Provides` is what lets this package *replace* both Debian TLS +flavours rather than co-install beside them — the single-fork invariant depends on +the `(= 1.5.6)` upstream version matching what Debian's flavours would satisfy, so +the package version and the `Provides` version move together but are NOT the same +string (`1.5.6+ceralive.1` vs `1.5.6`). + +**The `+` is load-bearing downstream.** apt's https method percent-encodes `+` as +`%2B` in the fetch URL while R2 stores the literal `+`, which 404'd every +`+`-versioned `.deb` on-device until `apt-worker` #23 keyed lookups on the decoded +path. Keep that in mind before assuming a `+` version is "just cosmetic": see +`apt-worker/AGENTS.md` → "R2 keys are matched on the percent-DECODED path". + **Why bundled, not a separate `srt-tools-ceralive` package.** The apt publish path (`apt-worker/scripts/reindex.sh`) downloads *every* `.deb` in a release tag and hard-fails (`validate_deb`, G-B) if any package name ≠ the dispatched `COMPONENT`,