87d9cd4b1a
All checks were successful
ci/woodpecker/pr/ci Pipeline was successful
CI pipeline 2006 failed the format step: prettier --check flagged
packages/mosaic/framework/guides/WAKE-DOCTRINE.md for using *asterisk*
italic delimiters instead of the project's _underscore_ style. Ran
prettier --write on the single file; the only change is the emphasis
delimiter around "before" (*before* -> _before_) — no wording changed.
The CI test-step failure on the same pipeline is unrelated: a
docs-only .md cannot affect Python daemon socket tests. Verified
against origin/main pipeline 2005 (parent commit 3c7890f), where
recovery_b1_adversarial_unittest.py passed cleanly; on this branch's
pipeline 2006 the same file errored with ConnectionRefusedError
connecting to the lease-broker unix socket in setUp — a pre-existing/
flaky test-harness race, not introduced by this change.
32 lines
1.8 KiB
Markdown
32 lines
1.8 KiB
Markdown
# Wake Doctrine
|
|
|
|
This is the canonical fleet wake/heartbeat doctrine, extracted verbatim from the ratified
|
|
converged wake/heartbeat design (`docs/scratchpads/heartbeat-planning/CONVERGED-DESIGN.md`). It
|
|
governs when agents wake and how a wake is delivered, consumed, and retired.
|
|
|
|
**Wake only on a real, un-consumed, lane-relevant obligation.** Fixed-interval heartbeats are
|
|
forbidden as the primary wake mechanism; they survive only as a **per-class fallback cadence**
|
|
bounded by urgency SLO, never as the steady state.
|
|
|
|
**A digest is cumulative state since the last CONSUMED ack**, not an event delta. It is
|
|
self-orienting (who / lane / board-head) and decides the no-op case with **zero tool calls**.
|
|
Actionable facts are **claims-to-verify** carrying a **hard locator** (repo/issue#/SHA/file);
|
|
self-sufficiency never exempts a consequential action from its live gate.
|
|
|
|
**Consumption is a consumer act, not a delivery act.** Split RECEIVED (delivery; `wake_id`-deduped)
|
|
from CONSUMED (durable capture of a contiguous prefix). Never ack-then-crash-before-capture. Acks
|
|
are local-write-only and cumulative; a turn never blocks on the network to ack.
|
|
|
|
**Durability is unconditional; coalescing is optional.** Every delivered class is durably stored
|
|
and acked; only machine `digest` wakes coalesce. A parked or absent pane must never lose a human
|
|
or peer message.
|
|
|
|
**Park is two-phase:** flush-and-checkpoint (recording the CONSUMED cursor) _before_ `/clear`.
|
|
|
|
**Liveness is independent of work-triggering:** an off-host dead-man beacon, alarming on absence —
|
|
never a same-host sibling, never a pane scrape.
|
|
|
|
**Retire the old net LAST:** run new alongside old, compare ledgers, and cut over only when the
|
|
per-host safety vector (no-op-rate ↓ AND canary-FN=0 AND source-parity-inventory-complete AND
|
|
reconcile=0 AND p95 event→CONSUMED≤SLO AND p95 event→qualified-action≤SLO) passes.
|