diff --git a/briefs/PACKAGING-PLAN-HEARTBEAT-CANON-MS-LEAD.md b/briefs/PACKAGING-PLAN-HEARTBEAT-CANON-MS-LEAD.md index 6493640a..b5710e04 100644 --- a/briefs/PACKAGING-PLAN-HEARTBEAT-CANON-MS-LEAD.md +++ b/briefs/PACKAGING-PLAN-HEARTBEAT-CANON-MS-LEAD.md @@ -6,9 +6,12 @@ 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. -**Rev 2 (2026-07-25):** addresses W-jarvis independent review at `cd11bbb` — 4 gaps resolved -(1 component manifest/version, 2 schema ordering ≤ W4, 3 blank-reset target/lifecycle, 4 framework/operator -boundaries + fail-closed) + the #889 minor. Still PROPOSED / PENDING-AUTHORITY. +**Rev 2 (2026-07-25):** addresses W-jarvis review at `cd11bbb` — 4 gaps resolved (component manifest/version, +schema ordering ≤ W4, blank-reset target/lifecycle, framework/operator boundaries) + #889 minor. +**Rev 3 (2026-07-25):** W-jarvis Rev-2 re-review = CONDITIONAL APPROVE; adds two acceptance gates — **Gate A** +(wake manifest is VERSION metadata only; path-ownership stays the single `framework-manifest.txt` SSOT + +Bash/TS parity tests — no second ownership truth) and **Gate B** (component manifest declares a supported +schema RANGE; detector fails loud outside it; upgrade/downgrade boundary tests). Still PROPOSED / PENDING-AUTHORITY. --- @@ -49,10 +52,10 @@ beacon (A8), A9, A11 are near-independent; installer (A10) lands last (needs all | **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 **+** watch-list SCHEMA contract (framework `.schema.json` + `schema_version`) | core three-cursor transaction **+ the public schema W4/W5 validate against** (W-jarvis gap 2 — schema lands ≤ its first consumer, not W7); red-first heavy. | | **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 (incl. schema)/W3; **validates watch-list `schema_version` → FAIL-LOUD**; repo-section/anchor-scoped hashing; flock; in mos-comms loop. | +| **W4** | A1 detector daemon | depends on W2 (incl. schema)/W3; **checks watch-list `schema_version` ∈ component supported-range → FAIL-LOUD (Gate B)** + boundary tests; 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 + **pluggable alarm-sink adapter** | semi-independent; independent liveness leg (G1). Framework = emitter+adapter iface; operator = target (§5 boundaries). | -| **W7** | A10 idempotent install.sh (**component-manifest install** + snapshot-guard + blank-reset on **legacy timer** drop-ins during retire) + `mosaic-wake.service` | LAST; **absorbs batch (d)**; #869 publish-gate. Operator schema VALUES deploy here; schema CONTRACT is W2. | +| **W7** | A10 idempotent install.sh (**component-manifest install, metadata-only; path-ownership stays framework-manifest SSOT + parity tests — Gate A** + snapshot-guard + blank-reset on **legacy timer** drop-ins during retire) + `mosaic-wake.service` | LAST; **absorbs batch (d)**; #869 publish-gate. Operator schema VALUES deploy here; schema CONTRACT is W2. | ~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. @@ -61,16 +64,20 @@ Red-first mandatory on all code PRs; `test:framework-shell` chain extended per P ## 3. Versioning + #869 compatibility - **Two independent version axes** (resolves the inherit-vs-adopt-independently contradiction — W-jarvis gap 1): - 1. **Component artifact version** — the wake component ships its OWN manifest+semver - (`framework/tools/wake/manifest.txt`, mirroring the existing `framework/framework-manifest.txt` - pattern), **independently addressable**. A10's installer can install/update **just the wake - component subtree** keyed to that version (`install.sh --component wake` / component-scoped copy), - decoupled from a full framework-manifest bump — this is the concrete enabler that lets a host adopt - the component alone (design §5.4). The component manifest is the artifact-selection/update unit; - the framework version is NOT. - 2. **Watch-list `schema_version`** — config-compat only, orthogonal to axis 1. The detector validates - the installed **component version against the watch-list `schema_version`** and **FAILS LOUD on - incompatible** (no silent degrade — #869 discipline, Patch-2b posture). + 1. **Component artifact version — metadata only (Gate A).** The wake component ships its own + manifest+semver (`framework/tools/wake/manifest.txt`) as **VERSION metadata ONLY**. **Path-ownership + stays the single SSOT `framework/framework-manifest.txt`** (consumed by BOTH the Bash and TS + installers with parity tests) — the wake manifest does NOT independently authorize file writes/prunes + (no second ownership truth). A component-scoped install/update (`install.sh --component wake`) selects + the component's file set **intersected-and-validated against framework-manifest ownership**, and + **extends the Bash/TS parity tests**. Net: independent *addressability/versioning* of the component + WITHOUT a second path-ownership authority (design §5.4 enabler). **Acceptance: parity tests green + + no wake-manifest-authorized write outside framework-manifest ownership.** + 2. **Watch-list `schema_version` — orthogonal; compat via explicit RANGE (Gate B).** Component semver + and `schema_version` are different axes and are **NOT compared directly**. The **component manifest + declares a supported schema range** (`schema_min`/`schema_max`, or a supported list); the detector + checks the watch-list `schema_version` **∈ range → else FAIL LOUD** (#869 discipline, Patch-2b + posture). **Acceptance: upgrade/downgrade boundary tests** (in-range pass, out-of-range fail-loud). - 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`.