fix: hold cascading child pages, preserve rollup attribution, document file storage

[fclairamb]

Three fixes from the 2026-08-31 batch, all rooted in the RabbitMQ nonprod outage of 2026-08-30 and a silent upload-loss confirmed on the k8xp dev cluster.

1. A child no longer pages while a hard parent is still validating

The forward rollup was damage control: it suppressed the remaining pages after a late-confirming parent opened, but could not recall those already sent. During the 2026-08-30 outage that residue was 5 Slack reports instead of 1 — the dependents' health endpoints flipped to 503 within milliseconds, while the parent probe only observed its first failure period + timeout later (26 s observed). Both sides then waited the same 120 s confirmation, so the gap was preserved rather than closed.

The static fix — requiring parent.period <= child.period — is disproven by the outage itself: both inequalities already held and 5 pages still escaped. So the hold is dynamic runtime state instead:

A check whose confirmation period has elapsed does not open an incident while a hard ancestor is itself validating — it stays validating one more tick. When the ancestor confirms first, the child's eventual open is suppressed by the existing backward walk before anything is sent.

• Zero cost when healthy — a check failing alone confirms at exactly its configured period. No permanent latency tax, which a config margin cannot avoid.
• No new machinery — no timers, no recall, no schema change, no config knob.
• Each ancestor gates only until a hold cap (FirstFailureAt + confirmation + period + timeoutOrDefault), so a paused or wedged parent frozen in validating can hold a child for at most one cap window.
• Down and Up ancestors never gate; soft edges are never consulted.
• The gate sits before createOrReopenIncident, so reopen-after-cooldown relapses are held too, and holdConfirmation is threaded into the status derivation so a held check displays validating rather than down-with-no-incident.

Also adds a soft, never-blocking warning on GET /checks/$check/dependencies (and an amber alert in dash0) for hard edges whose margin is too short to detect the same outage.

2. Rollup detach no longer erases the cascade's audit trail

markRollupDetached cleared both paging_suppressed and caused_by_incident_uid, and emitted nothing. After the outage, 10 of 11 dependent incidents read as though rollup had never run — the investigation had to be reconstructed from the events feed.

• Detach now clears only paging_suppressed; the attribution survives as the post-mortem record. Safe because nothing downstream reads a non-nil caused_by as "currently suppressed" (ListSuppressedChildIncidents filters on paging_suppressed), and the reopen path resets attribution from scratch.
• Adds the incident.rollup_detached event the wiki already documented but which never existed, routed to "never pages".
• The preserved property — a detached child relapsing before its incident resolves still pages — is covered by a dedicated test.

3. File storage is documented, and the install guides no longer lose every upload

grep -ril filestorage web/docs/ returned nothing, while SP_FILESTORAGE_LOCAL_ROOT defaults to ./data/files relative to the container's working directory. Every install guide mounted a volume for Postgres and none for uploads, so org logos, status-page assets and incident screenshots landed on the ephemeral writable layer — silently. Nothing fails at write time; the loss surfaces later as 500 read file: file not found in storage.

• SP_FILESTORAGE_LOCAL_ROOT was also not read at all: koanf collapses it to filestorage.local.root, missing the local_root tag, so a container told to store blobs on a mounted volume kept writing inside the image. Fixed in applyFileStorageEnv.
• New /configuration/file-storage page: both backends, credential resolution, MinIO / OVHcloud / AWS worked examples, and the backend-switching guarantee — verified against GetStorageForURI, which resolves reads by the scheme recorded at write time — with the "old backend must stay reachable" caveat stated.
• Volumes and SP_FILESTORAGE_LOCAL_ROOT added to the Kubernetes, Docker, Docker Compose and homepage quick-start guides, including the ReadWriteOnce single-replica caveat and the S3 block for multi-replica.

Testing

• 9 table-driven cases for the confirmation hold and 4 for the detach contract, each on both dialects (SQLite + Postgres). Both suites include positive controls, and both were mutation-tested — reverting the fix makes them fail.
• make build-backend lint-back test green; make build-dash0, bun run lint (no new errors), bun run test:unit green; make build-docs green.

Every spec passed an independent completeness audit before being archived.

---

4. Every ingest path now uses the configured check timeout

incidents.Service.defaultCheckTimeout is the last term of the confirmation-hold cap added in §1. The constructor seeds it to a 15 s fallback and expects callers to overwrite it with sp.check_timeout_ms — but the heartbeat, inbound-mail and MCP ingest paths never did. At shipped defaults the values coincide, so nothing was observable; the moment an operator raises or lowers the ceiling, the same check gets a different hold cap depending on which path processed the result.

The structural cause was the ms→Duration conversion being copy-pasted per call site, so a site that forgot to copy it inherited the fallback with no signal. SchedulingConfig.CheckTimeout() is now the single conversion, and heartbeat.NewService / emailcheck.NewHandler take the timeout as a required parameter — mirroring the existing publicationHook rationale — so a new call site has to make a deliberate choice rather than silently inherit the bug.

Each of the three wiring tests carries a positive control (NotEqual(fallback, configured), so it cannot pass vacuously) and a companion case pinning the other half of the contract: non-positive input keeps the fallback rather than collapsing to a zero-length hold that would release every child immediately.

5. The empty-org onboarding hero no longer outlives the first check

On production the dashboard kept showing "create your first check" for well over a minute after a check existed. The hero is gated on stats.total === 0 from GET /orgs/:org/checks/stats, and three caches stacked up: a 60 s server-side snapshot with deliberately no invalidation, no client mutation invalidating ["check-stats", org], and a poll timer stretched to 5 minutes while the live socket is connected. Worst case the hero sat over a non-empty org for several minutes, and a page reload only bypassed two of the three layers.

All three are fixed, the server-side bust being load-bearing:

• Server — membership-changing writes call checkStatsCache.invalidate. The two chokepoints insertCheckResolvingSlugRace and Service.DeleteCheck cover create, upsert-create, import, apply (including its prune loop) and clone; s.db.CreateCheck has exactly one call site, so nothing in that set escapes. Worker status transitions deliberately keep riding the TTL — only total crossing zero flips the page mode.
• Client — useCreateCheck / useDeleteCheck now invalidate ["check-stats", org].
• Live map — check-stats added under the checks kind, and deliberately not under results: that firehose is what spec 2026-08-09-07 keeps away from org-wide refetches.

Both control tests that keep the fix honest are present: a server test proving a plain result write does not bust the cache (preserving the TTL trade-off), and a frontend test asserting a results-kind live hint does not invalidate the stats query.

The E2E onboarding assertion is authored but was not run locally — the shared dev server isn't in SP_RUNMODE=test. CI runs it.