instar 1.3.1213 → 1.3.1215

package/upgrades/1.3.1215.md

@@ -0,0 +1,39 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+The Tailscale key-expiry tier of `RopeHealthMonitor` now scans only tailnet nodes that back
+a mesh rope (plus self), rather than every node on the tailnet. `parseTailscaleStatus`
+takes an optional mesh-address set and flags each entry `backsMeshRope`; `soonestKeyExpiry`
+takes `meshScopedOnly`; `server.ts` supplies the addresses from the registry's `tailscale`
+endpoints. An unreadable or empty address source falls back to the previous tailnet-wide
+scan, so a failure is never quieter.
+
+## What to Tell Your User
+
+Your machines warn you when a Tailscale key is about to expire — but they were checking
+every device on your account, including phones and old laptops that aren't part of the
+mesh. One dead device with a lapsed key made that warning permanent, so it stopped meaning
+anything, and on 2026-08-29 it was read as a live risk and reported as one.
+
+The warning now covers only the devices your machines actually reach each other on. Same
+horizon, same wording — it just stops crying wolf about hardware that can't affect
+anything.
+
+## Summary of New Capabilities
+
+- Key-expiry warnings are scoped to devices that genuinely carry mesh traffic.
+- This machine's own key always counts, since its expiry would drop every route it has.
+- Every failure path (unreadable registry, empty list) falls back to the old tailnet-wide
+  scan — the change can make the check noisier, never quieter.
+- No device names, addresses, or account details leave the parser; addresses go in, a
+  boolean comes out.
+
+## Evidence
+
+- Unit: `tests/unit/tailscaleStatusParser.test.ts` (+6), `tests/unit/RopeHealthMonitor.test.ts` (+2),
+  verified red-then-green against pre-fix behaviour.
+- Side-effects review: `upgrades/side-effects/rope-key-expiry-mesh-scope.md`.

package/upgrades/side-effects/rope-key-expiry-mesh-scope.md

@@ -0,0 +1,85 @@
+# Side-effects review — rope key-expiry mesh scoping
+
+**Change:** the Tailscale key-expiry tier of `RopeHealthMonitor` now considers only tailnet
+nodes that back a mesh rope (plus self), instead of every node on the tailnet.
+`parseTailscaleStatus` gained an optional mesh-address set and a per-entry
+`backsMeshRope` flag; `soonestKeyExpiry` gained `opts.meshScopedOnly`; `server.ts` supplies
+the addresses from the registry's `tailscale` endpoints.
+
+**Origin (live, 2026-08-29, topic 62395):** a tailnet node offline since 2026-08-13 with a
+lapsed key was the tailnet-wide soonest expiry, so `GET /mesh/rope-health` reported
+`warn: true, inDays: -16.6` continuously. Every real mesh machine's key was valid into
+Dec 2026 / Feb 2027. The permanent warning was not merely noise — it was read as a live
+finding and relayed to the operator as a real risk requiring their login.
+
+## 1. Over-block — what legitimate input does this now reject?
+
+A genuine expiry on a tailnet node that backs a mesh rope but whose address is NOT in the
+registry's endpoint list — e.g. a peer reachable over tailscale that has only ever
+advertised `lan`/`cloudflare`. That node's expiry would no longer warn.
+
+Bounded by two fallbacks that both fail LOUD: an unreadable address source and an empty
+address set BOTH degrade to the tailnet-wide scan. So the narrowed scope applies only when
+a non-empty mesh address list is genuinely available. Self is unconditionally included.
+
+## 2. Under-block — what does this still miss?
+
+It does not detect a rope dropping for any reason other than key expiry (unchanged), and
+it cannot warn about a mesh machine whose tailscale address this machine has never
+recorded. It also does not change the two-week horizon, so a key that lapses inside one
+check interval is still reported late — pre-existing, untouched.
+
+## 3. Level-of-abstraction fit
+
+Correct. The parser owns the scrubbed shape and is the only place that may see addresses,
+so the matching belongs there; the monitor owns the policy (`meshScopedOnly`); the wiring
+site owns knowledge of the registry. Putting the filter in the monitor would have required
+addresses to escape the parser, breaking that file's stated content-scrub boundary.
+
+## 4. Signal vs authority compliance
+
+Compliant. This is a digest/status signal with no blocking authority — it gates nothing,
+changes no routing, and cannot suppress a rope. It makes an existing signal more accurate.
+
+## 5. Interactions
+
+- The `key-expiry-warning` metric fires strictly less often (that is the fix).
+- `composeDigest()` drops the permanent expiry sentence when scoped — the other digest
+  sentences (per-peer conditions) are untouched.
+- `TailscaleKeyExpiryEntry` gained a field; one existing unit assertion deep-equalled the
+  old shape and was updated. No serialized/persisted format includes this type.
+- No interaction with the U4.3 recovery prober or the resolver — the expiry tier has its
+  own cadence and data source.
+
+## 6. External surfaces
+
+`GET /mesh/rope-health → keyExpiry.soonest` may now name a later expiry (a mesh node)
+where it previously named an earlier one (an unrelated node). No shape change. The
+content-scrub boundary is preserved: addresses flow INTO the parser and only a boolean
+flows out — no identity, address, or account data is added to any output.
+
+## 7. Multi-machine posture (Cross-Machine Coherence)
+
+**Machine-local BY DESIGN.** Each machine runs its own `tailscale status` and reads its own
+registry, so each scopes to the peers it knows. This is correct rather than a limitation: a
+tailnet node backing a rope is a per-observer fact, and the digest is composed per machine.
+No replication path added. A single-machine agent supplies an empty address list and
+therefore keeps exactly today's tailnet-wide behaviour.
+
+## 8. Rollback cost
+
+Trivial. Remove the `meshTailscaleAddresses` dep from the `server.ts` construction and the
+monitor reverts to the tailnet-wide scan by an explicitly-tested path. No persisted data,
+no migration, no state repair.
+
+## Tests
+
+- Unit `tests/unit/tailscaleStatusParser.test.ts` (+6): flagging, mesh-scoped soonest,
+  un-scoped soonest (pre-fix behaviour retained), no-set and empty-set back-compat, self
+  always counts, node with no address array is not mesh-backing.
+- Unit `tests/unit/RopeHealthMonitor.test.ts` (+2): the dead-node regression through the
+  monitor (scoped vs un-scoped on identical input), and the throwing/empty source falling
+  back to tailnet-wide rather than to a silent empty scope. Verified RED against pre-fix
+  behaviour and green after.
+- E2E: not applicable — no new route or feature-liveness surface; this narrows an existing
+  status field already covered by the monitor's own suite.

package/upgrades/side-effects/w29-ledger-selfaction-model.md

@@ -0,0 +1,39 @@
+# Side-Effects Review — window-lifecycle self-action convergence model
+
+**Slug:** w29-ledger-selfaction-model · **Date:** 2026-08-29 · **Author:** Codey (W29 Lane C2), commit ritual by Echo/Observer 1 · **Tier:** 1 (test infrastructure, 40 LOC)
+
+## Summary
+Registers the WindowLifecycleObligationLedger's owned 60s notify tick in `src/testing/selfActionRegistry.ts` (a faithful convergence model of its save-before-send dedupe brake) plus the `@self-action-controller` annotation at the real emit site in `src/server/routes.ts`. Closes the ACT-320 closure:gap declared at the W28 merge.
+
+## 1. Over-block
+None — the change blocks nothing; it is a registry entry + comment. The ratchet could over-fail future edits to the real brake; that is its purpose.
+
+## 2. Under-block
+The model covers the dedupe-brake class only (one issue → one emit, restart-surviving). It does not model the tick's other behaviors (evaluation cost, remediation flows) — those are not self-action emits.
+
+## 3. Level-of-abstraction fit
+Matches the established registry pattern (30th entry, same shape as the other 29): modeled trigger→brake→emit under the pinned PressureFixture. No new mechanism.
+
+## 4. Signal vs authority compliance
+No decision authority anywhere — pure test infrastructure. The ratchet is CI signal.
+
+## 5. Interactions
+The forcing lint (`lint-no-unregistered-self-action`) stops flagging this emit (verified); no other check consumes the registry entry. No double-fire risk — the annotation is a comment.
+
+## 6. External surfaces
+None. No runtime behavior, routes, or messaging changes.
+
+## 7. Multi-machine posture
+Not applicable — test-only code; the modeled controller itself is Echo-local by the W28 spec's non-leakage rule.
+
+## 8. Rollback cost
+Revert the commit; the lint returns to report-only flagging of the emit. No data or state involved.
+
+## Fidelity verification (the load-bearing check)
+The model records the issue into durable state BEFORE emitting, mirroring `routes.ts` where `ledger.surfacedIssues.push(...)` + `windowStore.save(...)` precede the async `sendToTopic` (verified at the shipped lines during this review). Ratchet: 141/141 including the new entry's bounded-emission and restart cases.
+
+## Review record
+Lane C2 (codex): 1 review cycle, clean, stop conditions declared before cycle 1, last-material-defect cycle 0 (none found). Observer independently verified fidelity + gates at commit time.
+
+## Conclusion
+Clear to ship.

package/upgrades/w29-ledger-selfaction-model.eli16.md

@@ -0,0 +1,7 @@
+# ELI16 — proving the rulebook engine's messenger can't spam
+
+The window-rulebook engine that shipped this week has a background loop that checks, every minute, whether any window duty is being violated — and when it finds a new problem, it sends one notice to the observers' channel. A loop that sends messages on its own is exactly the kind of thing that has caused message floods before, so this repo keeps a registry of every such self-acting loop, each paired with a small simulated model of its braking logic. A test then squeezes every model under sustained worst-case pressure — the problem never goes away, the process restarts mid-stream — and proves the loop settles at a bounded number of actions instead of firing forever.
+
+The engine's loop was shipped with its brake in the code (it durably records each issue BEFORE sending, so the same issue can never send twice — even across a restart) but WITHOUT its entry in that registry, which was tracked as a follow-up with a deadline. This change pays that debt: it adds the faithful model of the engine's brake to the registry (the model was checked line-against-line with the real code: record-first, then send), plus the one-line annotation at the real send site that links code and registry. The pressure test now covers it — 141 checks pass, including the new ones proving one problem yields exactly one notice, forever, restart included.
+
+Nothing about the engine's behavior changes. This is test infrastructure: the safety net under the engine's messenger, not the messenger itself. If someone later edits the engine's brake and breaks it, the registry test is now the tripwire that catches it before it ships.