Home the roxyd self-update contract in this crate (#91)

CHANGELOG.md

@@ -8,6 +8,21 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ### Added
 
+- `roxyd_selfupdate_contract`, the frozen on-disk contract the roxyd self-update
+  rollback supervisor coordinates through: the record directory, the file names,
+  the canonical roxyd binary path, the decision subcommand and its three
+  activation reasons, the self-test freshness window and nonce rules, a resolver
+  for every path composed from them, and the versioned JSON record types —
+  `ArmRecord`, `ConfirmMarker`, `StatusRecord`, `SupervisorVersionMarker`,
+  `ReportRequest` and `SelfTestRecord` — with the `FORMAT` revision each carries.
+  It is the one definition both writers of these files can name: the shape is a
+  versioned agreement between the installer and the on-host agent, and a second
+  copy of it diverges after deployment with both repositories' tests green. It
+  is a sibling of `roxyd_selfupdate` rather than part of it and neither module
+  depends on the other — the unit text is byte-identical data with one consumer
+  and deliberately no parameters, where this is a shape two writers have to
+  agree on. Every value is the one already on disk on every host, held there by
+  a test that names each rather than rebuilding it from the constant beside it.
 - `executor::Executor::hard_link_over`, which preserves a root-owned regular
   file under another name by hard-linking it to a temporary sibling, renaming
   that over the destination, and flushing the directory the new entry appeared

README.md

@@ -49,9 +49,20 @@ Product-neutral deploy primitives shared by an installer and an on-host root age
 - **registration** — service registration against the on-host PKI.
 - **roxyd_selfupdate** — the roxyd self-update rollback supervisor units as
   data: the three activation services and the deadline timer, with no renderer
-  and nothing to substitute. This crate is their single owner — the installer
-  and roxyd's own `join` both embed these bytes from their pinned dependency,
-  so the hosts each onboards cannot roll back under different rules.
+  and nothing to substitute. This crate is their single owner and the installer
+  is its only consumer, embedding these bytes from its pinned dependency onto
+  both host populations — the ones it provisions and the ones roxyd onboards
+  through its join flow — so neither can roll back under different rules.
+- **roxyd_selfupdate_contract** — the frozen on-disk contract those units
+  coordinate through, and a sibling of **roxyd_selfupdate** rather than part of
+  it: the record directory, the file names, the canonical roxyd binary path,
+  the decision subcommand and its three activation reasons, the self-test
+  freshness window and nonce rules, a resolver for every path composed from
+  them, and the versioned JSON record types with the `FORMAT` revision each
+  carries. Unlike the unit text it has two writers, the installer and the
+  on-host agent, which is why one definition lives here rather than a copy in
+  each — a second copy diverges after deployment with both repositories' tests
+  green. Neither module depends on the other.
 - **roxyd_trust** — trust-material activation for the on-host agent: the X.509
   validator for roxyd's staged cert/key/CA triple, over the crate-internal
   tree-neutral generation engine (stage, validate the copy, swap `active`,

src/lib.rs

@@ -13,12 +13,13 @@
 //! that turns its active generation back into the verifier's injected trust set,
 //! the install/update diff engine, the apply primitives, the canonical
 //! self-update rollback supervisor unit text both installers embed rather than
-//! each carrying a copy, the
-//! bootroot command wrapper, service registration, and the on-host trust-material
-//! activation. It carries **no** product concept — no component catalog, no
-//! per-component renderers — so both the installer and the per-machine root daemon
-//! depend on it and share a single implementation rather than shelling out to a
-//! CLI.
+//! each carrying a copy, the frozen on-disk self-update contract those units
+//! coordinate through — the record names, paths and versioned JSON shapes the
+//! installer and the on-host agent both write — the bootroot command wrapper,
+//! service registration, and the on-host trust-material activation. It carries
+//! **no** product concept — no component catalog, no per-component renderers —
+//! so both the installer and the per-machine root daemon depend on it and share
+//! a single implementation rather than shelling out to a CLI.
 //!
 //! The product-specific install/update orchestration, the component catalog, and
 //! the per-component rendering stay in the installer crate, which depends on this
@@ -45,6 +46,12 @@ pub mod registration;
 pub mod release_trust;
 pub mod render;
 pub mod roxyd_selfupdate;
+// The frozen on-disk self-update contract. A sibling of `roxyd_selfupdate` and
+// deliberately not part of it: the unit text has one consumer and no
+// parameters, while this shape has two writers — the installer and the on-host
+// agent — and a `FORMAT` they both have to agree on. Neither module depends on
+// the other.
+pub mod roxyd_selfupdate_contract;
 pub mod roxyd_trust;
 pub mod systemd;
 pub mod transport;