Document the live-staleness pattern (and record the surface-derive deferral)

[briananderson1222]

Document the live-staleness pattern (and record the surface-derive deferral)

Surface's staleness is a pure function of now at report-build time; reactivity is diff-based (checkpointFromReport + buildTrustReport({since}) + diffFreshness + recomputeChangeRecords). src/recompute.ts records the packaging decision: a stateful watcher is exactly what would justify an optional @kontourai/surface-derive package, deferred "until a concrete consume-side need appears."

That concrete need has now appeared: Station's provenance cards must flinch when their sources stale (kontourai/station#1391), and Ephemeris (the suite's deadline-reading scheduler) will drive re-derivation. But the pattern for wiring an external scheduler to checkpoints and freshness diffs is undocumented — the next consumer would have to reverse-engineer it from src/report.ts and src/recompute.ts.

Scope

• Docs page (or reference section): "Re-derivation and live staleness" — the canonical loop: persist checkpoint → external trigger (scheduler, file watch, event) → buildTrustReport({now, since: checkpoint}) → diffFreshness/recomputeChangeRecords → notify/render. Include cost-bounding guidance (checkpoint cadence, since semantics)
• Record the standing decision: core stays on-demand; surface-derive remains deferred until a consumer needs in-process watching or arithmetic method execution — with the trigger conditions for revisiting
• Note Ephemeris as the suite's reference external scheduler (reads claim deadlines from TrustBundles, fires idempotent triggers)

Non-goal

Building the watcher. This issue is docs + decision record only; if the doc reveals the loop is awkward in practice, that is the evidence to revisit surface-derive.

[briananderson1222]

Implemented on branch glm/staleness-docs (commit 3312244): docs/reference/re-derivation-and-live-staleness.md — canonical checkpoint→trigger→bounded re-derivation→freshness-diff loop with source-verified signatures, cost-bounding guidance, and the surface-derive deferral decision with revisit triggers. Repo-only page (not promoted to Pages site — deliberate).