CADENCE — Decisions & Assumptions

One audited trust gate. The fail-closed verifier (signature-before-parse, per-file SHA-256, path-traversal/size/count ceilings) stays the single source of truth; the fetch step is defense-in-depth (it verifies the manifest signature only, to decide which files to download).

The cache dir IS the air-gap mirror (§2). What the client writes is a complete, signed, independently-re-verifiable copy — exactly what a customer syncs to an internal mirror. A proven test (downloaded_corruption_is_caught_by_reverification) shows a transport that swaps a file is still rejected on re-verify.

The transport is a seam, untrusted by design. FeedFetcher (sync, runtime-free, mirrors the adapter HttpGetter/CommandRunner seams) keeps domain framework-free; the fetch logic is fully offline-tested with MockFetcher. The real HTTP impl lives in the client.

Why the notification set, not just the version? A CADENCE advisory most often speaks about a version you already run ("hold 26.2.3"). A feed refresh can introduce a new BLOCKED/CVE verdict for an unchanged installed version — version-only change detection (the seen_versions table) would miss exactly the case that is the product’s core value. The notification subject already encodes {verdict}:{asset}({product} {version}), so set-difference catches both a version change and a feed-driven judgment change, and a changed body (e.g. a newly-attached CVE) re-alerts.

Edge-triggered semantics. We persist the currently-active set each cycle (not an append-only ledger), so a resolved alert ages out and a recurrence re-fires — the standard Alertmanager model. Stored as a notified table (sha256(payload) → JSON), bounded by the number of active alerts.

Reminders are intentionally out of the change-gated path. Delivery filters at Important, and reminders are emitted at Recommended, so they were never in the delivered set; their volatile "Nd overdue" subject would otherwise defeat the dedup key. A daily reminder digest is a separate (deferred) concern.

seen_versions is now live, not dead code. Each refresh records per-asset versions and logs detected old → new changes (operator-facing insight; the table’s documented "groundwork for change detection"). It is informational here — the notification diff, not this table, drives alerting — which is why feed-only changes still alert correctly.

Resilience. A failed cycle (feed pull / adapter error) is logged and skipped; the last good dashboard keeps serving. With CADENCE_REFRESH_INTERVAL unset the client stays a one-shot (backward compatible). Overturn: to fire reminders periodically, add a separate digest schedule; to re-fire on a cadence regardless of change, switch replace_notified to a TTL’d ledger.

Threat model. This is tamper-evidence against post-hoc edits of the customer-local SQLite file (an operator quietly softening a recorded verdict), not a defense against a malicious feed author — the feed is the trusted, ed25519-signed input. It catches "someone changed the record after the fact."

Truncation. Lopping off the tail can’t be detected from the chain alone (the remaining prefix is internally consistent). audit_chain_tip() exposes the head hash so an auditor records it out-of-band and notices if entries later vanish. Documented, not hidden.

Canonical is JSON, not a |-join. A delimiter inside a field (e.g. a summary containing |) must not let an attacker forge a different decision with the same canonical bytes; JSON-encoding a fixed field array removes that collision. The format is frozen (changing it invalidates chains).

Append-distinct. INSERT OR IGNORE on (asset,product,version,verdict) keeps the chain from growing on unchanged daily cycles; a changed verdict is a new dated link. recorded_on is the first-seen date.

Export. GET /decisions.json (auth-gated) serves the whole trail + chain verdict + tip for an auditor/SIEM — auditors ingest exports, not dashboards. Overturn: for cross-host integrity (not just local tamper-evidence), periodically ed25519-sign the chain tip with the feed/Nitrokey key and publish it; for true immutability, ship entries to an append-only external log.

The linter requires citations. lint_feed warns on an advisory with no references and on any reference that isn’t a well-formed http(s)://<dotted-host> URL (placeholder text and localhost rejected). Both are warnings — consistent with the existing malformed-CVE check (the Warning channel = "probable authoring mistake worth a human’s eyes"); a curator can knowingly ship without one, but the default nudges toward a sourced verdict. A feed-builder regression test asserts the committed flagship feed has zero such warnings — the reference feed must practice what the pitch sells.

Why warning, not error. An Error blocks the release. Citations are a strong norm, not a hard schema invariant (a curator might, rarely, have a defensible uncited call). Keeping it a warning avoids over-blocking while the regression test still holds our feed to 100%.

The sample content is now sourced, not illustrative. Every advisory’s facts (versions, EOL dates, CVEs, upgrade gotchas) are drawn from the cited upstream references and were current as of 2026-06-22. It is still a sample (not a paid subscription), and specific app-compatibility pairings illustrate the conditional-gate mechanism against a real cited issue — but the feed is now checkable, not hand-wavy. (Supersedes A2.) Overturn: to hard-require citations, promote the missing-reference finding to Error; to verify a URL actually resolves (not just parses), add an optional, online check in the Feed Builder — kept out of lint_feed, which must stay pure/offline.

Retain the previous feed locally, diff each pull. The appliance persists the previously-pulled feed’s advisory set in a feed_baseline singleton row (persistence), and each cycle diffs the freshly-pulled feed against it via the existing pure domain::diff_advisories, then advances the baseline. The baseline lives in CADENCE_STATE_DB, so the comparison point survives a restart (the next pull diffs against the last feed seen before the restart, not a blank slate). This matches the run-4 morning-report spec ("retain the previous feed to diff against each refresh").

Per-pull semantics (not a persisted change-history). The panel shows the delta of this pull vs the immediately-previous one — the visual analog of notify-on-change (D012). After an unchanged pull it correctly reads "no changes since the last pull (vN)". Historical change-tracking is already covered by the feed-builder diff (vendor side) and the decision audit trail (client side), so the client panel deliberately stays a live per-pull view rather than storing a serialized diff history (KISS — no new serialized FeedDiff state).

Surface safety regressions prominently. Any caution_reduced() change (a hold/block/EOL softened toward install) gets a ⚠ banner + an inline row flag — the operator’s "did the feed just quietly downgrade a warning?" check before trusting the pull. A tightening is not flagged.

Demo seeds a plausible previous baseline (demo::seed_feed_baseline) so the changelog is non-empty and sellable on first load (a softened verdict, a newly-published CVE advisory, a severity tightening, a withdrawn advisory). The seed is used only for the diff, never analyzed, so live verdicts still come from the real current feed. Overturn: to make the changelog persist across no-op refreshes (show "the last feed change" until the next one), store the computed FeedDiff + its date and only recompute on change — at the cost of serializing the diff and a slightly subtler "what does this panel mean" story.

Monotonic high-water mark. The client persists the highest feed_version it has ever trusted (feed_trust singleton, persistence) and refuses any pull whose version is strictly older (domain::check_no_rollback). Equal is accepted — re-pulling the current feed every interval is the steady state, and a vendor may legitimately re-publish the same version. The mark only ratchets up (domain::advanced_high_water), never on a rejected feed, so a repeated replay stays blocked.

Numeric comparison. Versions compare via domain::version::compare (dotted-numeric), so 2026.06.9 is correctly older than 2026.06.10 — a naïve lexical compare gets that backwards. Operational constraint: the feed_version scheme must stay monotonic dotted-numeric (the 2026.06.DD convention + the feed-builder --feed-version input already are). Switching to a scheme that parses numerically lower (e.g. a v-prefix → leading component parses to 0) would look like a massive rollback and brick clients; treat feed_version as a frozen monotonic counter.

Separate table from the changelog baseline. feed_trust is a security record (only ratchets, must never silently read as "any feed is fresh"); feed_baseline (D015) is a convenience cache (regressable, self-heals a corrupt row to "absent"). Opposite trust semantics → two singletons, never shared. Persistence holds no version-ordering logic — the client ratchets via the domain helper.

Fail-closed by skipping the cycle. On a detected rollback run_once returns Err, so the daemon logs a loud error! and keeps serving the last-good dashboard — exactly its existing behavior for a failed pull. The stale feed never advances the changelog baseline, never re-analyzes, never softens a verdict. Trade-off: a rollback at the very first cycle after a restart propagates and refuses startup (cycle 0 in main uses ?). That is a deliberate, defensible fail-closed posture — halting loudly under an active downgrade beats silently serving stale advice — though it does let an attacker who can pin a stale mirror also block a restart (a visible DoS, not a silent compromise). Scope / deferred (the natural follow-ups):

Anti-freeze (valid_until) — rollback protection stops going backwards but not a freeze (pinning the client forever on the current feed). (Updated run #11 — domain core shipped, see D017.) domain::check_not_expired now refuses a feed whose signed valid_until has passed (S44a); the manifest schema field + builder (S44b) and the client enforcement + banner (S44c) are the remaining wiring.

Operator-visible alerting. (Updated run #8 — S45a shipped.) A detected rollback is no longer log-only: enforce_feed_freshness now pushes an Important rollback_notification (domain) through the configured channels via client::page_rollback, riding the notify-on-change baseline so a replayed stale feed pages once and a failed page retries next cycle. Paging is best-effort and runs before the gate returns Err, so the fail-closed semantics are untouched (the cycle still skips, last-good dashboard stands). The complementary dashboard security banner's state channel (S45b) shipped run #9: a persisted rejected_rollback singleton (persistence) the gate sets on a refused downgrade (best-effort, before the fail-closed Err) and clears on the next accepted pull — deliberately transient (opposite of the ratcheting feed_trust mark), so it tracks an active attack window. The data path is wired + tested through the gate; only the UI render (S45c) — reading load_rejected_rollback() in the index handler + a banner in ui.rs — remains. Overturn: to make a startup rollback non-fatal, soften cycle 0 in main to log + serve a clearly "feed rejected (possible downgrade) — no trustworthy feed yet" placeholder dashboard instead of ?.

Domain core first (S44a, this run). domain::freshness::check_not_expired(valid_until, now) is the pure security judgment: now > valid_until ⇒ FreshnessError::Expired. now is injected, not read from the clock, so the judgment is offline-testable IP (matches check_no_rollback). Wiring the field into the manifest schema + builder (S44b) and enforcing it in enforce_feed_freshness + paging/banner (S44c) follow — same S41→S42→S43 decomposition as the rollback gate.

Orthogonal to rollback. Expired is a distinct variant from Rollback; a feed must pass both gates (a newest-ever-version feed can still be expired). They compose, they do not subsume.

None ⇒ accept (opt-in, backward compatible). A feed that declares no valid_until is accepted, so feeds signed before the field existed still parse and run, and the field rides the existing signature (the manifest signs its raw YAML bytes — adding a serde-optional field needs no canonicalization change). The vendor enables freeze-detection simply by signing a bound. Trade-off: freeze-detection is therefore opt-in — a feed that never carries the field can be frozen indefinitely. Right for v1 (apt’s Valid-Until is likewise optional; avoids bricking pre-field feeds), but a future hardening could make a bound mandatory once every published feed carries one.

Inclusive last valid day. valid_until is the last day the feed is good for (now == deadline accepts; now > deadline rejects), so re-pulling on the deadline day never bricks a still-valid client. Overturn: to make the bound mandatory, reject valid_until: None in check_not_expired (or in the client wiring) once the flagship feed and all live feeds always carry one.

build --valid-until <YYYY-MM-DD> (explicit date), not --valid-for Nd (relative). The mission sketch suggested --valid-for Nd, but a relative bound computed from today makes the manifest non-reproducible — re-building the same content on a different day yields different bytes, hence a different signature, breaking the builder’s byte-stable-output guarantee and any manifest diffing. An explicit date is deterministic and re-signable. build_manifest itself stays clockless (leaves the field None); only the CLI, which may read the clock, sets it. Overturn: add --valid-for later as sugar that resolves to an explicit date at invocation, if operators want it — but keep the stored value a concrete date.

A sibling expired_feed banner + expiry_notification, not a generalized "freshness rejection". This is the second freshness-rejection surface (rollback was first). Per the project’s own DRY rule (extract on the third repetition), two is not three: duplicating the transient-singleton banner pattern (parallel to rejected_rollback) is safer than refactoring the shipped, tested S45b/c security path. The one thing genuinely reused twice — the notify-on-change paging mechanic — was extracted into page_freshness_alert, which both page_rollback and page_expiry delegate to ("reuse the S45 alert seam"). Overturn: if a third freshness banner ever appears, unify the three into one parameterized banner record + renderer.

The expiry push alert is date-free (fires once); the banner carries the detection date. A freeze persists day after day; a date in the alert subject/body would re-fire it every stale day. Keeping the alert stable per (feed_version, valid_until) pages the operator once (via notify-on-change), while the transient dashboard banner shows the exact detected_on — same split as the rollback alert/banner.