stack/briefs/PACKAGING-PLAN-HEARTBEAT-CANON-MS-LEAD.md

Wake/Heartbeat Canon — FRAMEWORK PACKAGING PLAN (MS-LEAD)

Author: MS-LEAD (framework packaging role, named in CONVERGED-DESIGN footer) · Date: 2026-07-25 Input: jarvis-brain@31f1f6fd5 docs/scratchpads/heartbeat-planning/CONVERGED-DESIGN.md (GO-WITH-GATES, RATIFIED) + ENHANCE-CADENCE-WRITER-FIX.md + ENHANCE-BASELINE.md. Scope: §6 category-A framework-component items (A1–A11) + WAKE-DOCTRINE guide. NOT pilot (B*, mos-dt-0) or operator-config values (C*). Proposal only — no framework PR cut until Mos acks this plan (per Mos). Repo facts verified against mosaicstack/stack origin/main (read-only ls-tree) — not assumed.

---

1. Repo layout (grounded in verified paths)

Framework source lives in packages/mosaic/framework/ and installs to ~/.config/mosaic/. Verified: tools/<subdir>/ (git, tmux, fleet, orchestrator, lease-broker, context, …); guides/*.md; install.sh; systemd/; tools/tmux/agent-send.sh (+ agent-send.test.sh).

Item	Source path (new unless noted)	Installs to
A1 detector daemon	framework/tools/wake/detector.sh	~/.config/mosaic/tools/wake/
A2 store+drain lib	framework/tools/wake/store.sh (three-cursor, atomic write-tmp+rename)	XDG state ~/.local/state/mosaic/wake/
A3 digest renderer	framework/tools/wake/digest.sh	"
A4 ack-wrapper	framework/tools/wake/ack.sh (RECEIVED/CONSUMED, local-write+async)	ledger under XDG state
A5 HMAC signer	framework/tools/wake/sign.sh (non-circular tuple, load_credentials by-name)	"
A6 FN-oracle · A7 reconciler	framework/tools/wake/{fn-oracle,reconcile}.sh	"
A8 off-host beacon	framework/tools/wake/beacon.sh + alarm integration	off-host monitor
A9 digest class validator	MODIFY framework/tools/tmux/agent-send.sh (+ .test.sh)	—
A10 idempotent installer	MODIFY framework/install.sh + framework/systemd/user/mosaic-wake.service	~/.config/systemd/user/
A11 WAKE-DOCTRINE	framework/guides/WAKE-DOCTRINE.md (lift §"WAKE-DOCTRINE" verbatim)	~/.config/mosaic/guides/
C1 watch-list SCHEMA (framework)	framework/defaults/wake-watch-list.schema.json	operator supplies values

Note: gitea-pr-watch / mos-comms (the pollers the detector generalizes) are NOT under framework/tools/ on main — they are host/operator artifacts today. A1 becomes the canonical framework generalization; it does not depend on those existing in-repo. The detector runs as a long-lived service (not a timer) — the whole point is retiring unconditional timers; fallback cadence is a per-class SLO bound inside the daemon, not a systemd interval.

2. PR slicing (dependency-ordered, ≤2 concurrent builders, each builder→indep-review→Mos id-11)

Dependency spine: store/ack (A2/A4) → digest/sign (A3/A5) → detector (A1) → oracle/reconciler (A6/A7); beacon (A8), A9, A11 are near-independent; installer (A10) lands last (needs all files present).

PR	Contents	Notes
W0	A11 WAKE-DOCTRINE.md	docs-only, independent; lands first as normative reference. Resolves #889 (see §5).
W1	A9 agent-send.sh digest-class validator + test	tiny, independent, red-first (like Patch 2b). Good opener.
W2	A2 store+drain lib + A4 ack-wrapper	core three-cursor transaction; red-first heavy. The heart.
W3	A3 digest renderer + A5 HMAC signer	depends on W2 store; hard-locator + scrub + non-circular MAC tests.
W4	A1 detector daemon	depends on W2/W3; repo-section/anchor-scoped hashing; flock; in mos-comms loop.
W5	A6 FN-oracle + A7 reconciler	depends on W4; the non-optional G3/§4 cost, built explicitly.
W6	A8 off-host beacon + alarm	semi-independent; the independent liveness leg (G1).
W7	A10 idempotent install.sh (blank-reset idiom + snapshot-guard) + mosaic-wake.service + C1 schema	LAST; absorbs batch (d); #869 publish-gate (enforcement path).

~8 PRs pipelined; at ≤2 lanes this is several convergence cycles. Each: fresh-clone builder (mosaic-coder), author≠reviewer independent review at exact head, RoR packet, Mos id-11 stamp+merge. Red-first mandatory on all code PRs; test:framework-shell chain extended per PR.

3. Versioning + #869 compatibility

• Component ships inside the framework (packages/mosaic/framework/) → inherits framework version.
• §5.4 decoupling requirement: a host must adopt "just the component + its watch-list without a full framework bump." Enabler: the watch-list carries an explicit schema_version; the detector validates schema-version and FAILS LOUD on incompatible (no silent degrade — #869 discipline, same fail-loud posture as Patch 2b). WAKE-DOCTRINE is version-agnostic doctrine.
• A10 installer is an enforcement path → #869 publish-gate: fail-closed, idempotent, snapshot-guard blocks a reap/clean-checkout without a snapshot; post-apply verify = exactly one OnUnitActiveUSec.
• web1 rides #869 Point-2 (currently HELD/non-autonomous). dragon-lin pilots NOW (separate host, outside the #869 freeze) — so canon PRs can land + be piloted without touching the web1 release hold.

4. Rollout sequence (§5, retire-net-LAST)

1. Snapshot-first (B5, mos-dt-0/pilot): dragon-lin jarvis-heartbeat.{service,timer} — snapshot already present at heartbeat-planning/pilot/snapshot-dragon-lin/. Canon is version-controlled from day one (the failure class — deployed-from-uncommitted — cannot recur).
2. Land W0→W7 to main (reviewed framework PRs).
3. dragon-lin: enable canon alongside ad-hoc (B1) → dual-ledger compare (B2) → run §4 vector (B3) → delete ad-hoc units after pass (B4). Every step leaves old-or-new live (sol F7).
4. web1: adopt component + watch-list on #869 resolution.

• Do NOT land the ad-hoc infra/fleet/* subsystem to main first (§5.1, Mos ruling) — it is exactly what canon retires.

5. Disposition of adjacent items

• Batch (d) — ABSORBED into A10. The blank-reset bug is in infra/fleet/install.sh (deployed-from-uncommitted, NOT on main — confirms my "could not verify on main"). Host drop-ins already corrected + live-verified 2026-07-25 (planner-opus/planner-sol now fire 30min not 15min). Nothing standalone to land; the proven idiom (byte-identical to installer-7) becomes an A10 requirement + a post-apply test. Batch item (d) is therefore closed-as-absorbed, not a separate PR.
• PR #889 (my layering note) — recommend CLOSE-SUPERSEDED. Its constraints (one liveness substrate, framework-vs-product split, state location, blank-reset invariant) are now canonized in CONVERGED-DESIGN §0/§1.1/§1.4/§5.2 (W-jarvis confirmed the constraint was accepted for relay). The canonical heartbeat docs live in jarvis-brain heartbeat-planning/; keeping a superseded duplicate in mosaicstack/stack docs/scratchpads/ is cross-repo drift. Lean: close #889 without merge (design input delivered + absorbed). Defer to Mos: close-superseded (my rec) vs merge-as-historical-record.

6. Open questions for Mos (before I cut W0)

1. Repo home — framework/tools/wake/ for A1–A8 + framework/defaults/ for C1 schema: confirm names.
2. #889 — close-superseded (my rec) vs merge-as-record?
3. PR granularity — ~8 pipelined PRs OK, or coarser (fewer, larger) / finer?
4. Pilot boundary — design assigns pilot (B1–B5) to mos-dt-0; I own framework packaging (A*). I do NOT build pilot items unless you reassign. Confirm.
5. Sequencing vs tooling batch — #890 (a) in flight for id-11; (b) held on scopes; (c) HALTED. Does W0 start now (dragon-lin outside #869), or after the tooling batch clears? My lean: W0/W1 can start now (doc + tiny validator, no #869 dependency), heavier W2+ after (b)/(c) resolve to keep ≤2 lanes.
6. Tracking issue/EPIC — create a mosaicstack/stack EPIC for the canon component (parent for W0–W7), analogous to Matrix EPIC #887 / tooling umbrella #891? I'll open it on your nod.