instar 1.3.368 → 1.3.370

package/upgrades/side-effects/journal-lock-retry-pin-fallback.md

@@ -0,0 +1,64 @@
+# Side-Effects Review — journal lock retry + heartbeat (#925) and quiet-topic pin fallback (#926)
+
+**Version / slug:** `journal-lock-retry-pin-fallback`
+**Date:** `2026-06-06`
+**Author:** `echo`
+**Second-pass reviewer:** `not required (two live-found fixes against converged specs; both bounded; both with regression tests)`
+
+## Summary of the change
+
+Two bugs found by the P2 LIVE two-machine proof (echo pair, v1.3.367):
+
+1. **#925 — writer lock wedge.** The restart cascade (3 boots/hour on a
+   release day) left the journal writer silently read-only for ~75 min:
+   boot-time stale-lock reclaim correctly refused while the old process
+   lingered, and the locked-out state had NO retry. Fix: (a) a bounded
+   retry timer (max(40×flushInterval, 10s)) re-attempts activation and
+   recovers IN PLACE with one log line; (b) the live holder heartbeats the
+   lock file mtime every ~40 flushes; (c) reclaim treats an mtime-stale
+   (5 min) lock as dead even when its recorded pid "exists" — the
+   pid-reuse defense; (d) the autonomous scanner does NOT mark runs seen
+   while the writer is locked out, so dropped `started` emits re-emit
+   after recovery (op-key dedupe makes re-emits safe).
+2. **#926 — quiet-topic reflex refusal.** Ownership only CASes when
+   traffic flows, so a topic just moved (pinned, owner:null) — the exact
+   state the fetch reflex exists for — answered not-owner. Fix: the
+   ownerOf seam falls back to the placement pin (`pinned &&
+   preferredMachine === self` ⇒ self at epoch 0); a real claim bumps past
+   epoch 0 and aborts an in-flight pull as superseded (the existing
+   recheck, by design). Spec §3.3 delta + eli16 amendment ride along.
+
+## Decision-point inventory
+
+- Retry cadence bounded (P19): one timer, unref'd, cleared on recovery +
+  close; no retry while active.
+- mtime-stale threshold (5 min) vs heartbeat cadence (~10s): 30× margin —
+  a paused-but-alive holder (debugger, SIGSTOP) longer than 5 min loses
+  the lock deliberately (it wasn't flushing anyway; the new holder's
+  'wx' open + the old holder's dead fd keep streams append-consistent).
+- The pin fallback only ever returns SELF (never another machine) and
+  only when pinned — an unpinned unowned topic still refuses honestly.
+
+## 1-2. Over/Under-block
+
+Over: a >5-min-frozen live holder is reclaimed (stated trade). Under:
+two processes could still interleave between mtime check and rm in a
+pathological race — the 'wx' open after rm serializes the winner; the
+loser retries on its timer.
+
+## 3. Fit / 4. Blast radius
+
+Lock logic stays inside CoherenceJournal (the single owner of the lock
+discipline); the scanner guard is one line at the existing seenRuns
+seam; the pin fallback lives in the server's ownerOf wiring (the seam
+the spec names). Blast radius: journal writer recovery behavior +
+reflex eligibility on pinned-unowned topics; both covered by tests.
+
+## Evidence
+
+- tests/unit/CoherenceJournal.test.ts — 38 passing (3 new: locked-out
+  honored for a fresh live-pid lock; mtime-stale reclaim despite an
+  "alive" pid; freed lock acquirable). Full typecheck clean.
+- Live remediation already validated the failure analysis: stale-lock
+  removal + restart restored emissions (the 77901 proof artifact
+  journaled + replicated to the Mini within one cadence).

package/upgrades/side-effects/threadline-conversation-kind-p3.md

@@ -0,0 +1,83 @@
+# Side-Effects Review — Threadline Conversation Coherence build (P3.1 + P3.2 surfaces)
+
+**Version / slug:** `threadline-conversation-kind-p3`
+**Date:** `2026-06-06`
+**Author:** `echo`
+**Second-pass reviewer:** `not required (implements the 2-round-converged P3 spec; a 4th journal kind riding P1's proven transport; content-free by typed schema; read-only view)`
+
+## Summary of the change
+
+THREADLINE-CONVERSATION-COHERENCE-SPEC (converged 2026-06-06, merged in
+#924) — every machine can answer "which machine holds each A2A
+conversation, and is it bound to a topic?" from local disk:
+
+1. The 4th journal kind `threadline-conversation` — the spec's honest
+   "compiler-guided multi-site edit" performed in full: JournalKind union,
+   JOURNAL_KINDS, 6 Record literals (nextSeq/highWaterSeq/opKeys/retention
+   merge/rateBuckets/persistMeta), the typed validate() branch
+   (action/conversationId/peerFingerprint/topicId? — free text
+   structurally excluded, 256-char id bounds), the opKeyOf branch
+   ((conversationId, action, topicId?) — conversationId lives in data,
+   the round-1 finding), the emitThreadlineConversation emitter, AND the
+   JournalSyncApplier.validateData mirror branch (without which the
+   receive side suspect-flags the sender). DEFAULT_RETENTION +
+   ConfigDefaults literal (8MiB × keep 8; applyDefaults backfills).
+2. ConversationStore: the lifecycle emission as a prev/next TRANSITION
+   DIFF inside commit() — the store's single write funnel — on `state` +
+   `boundTopicId` ONLY (message appends/lastActivity bumps emit NOTHING);
+   terminal set = resolved/failed/archived (the real enum);
+   setCoherenceJournalSeam + one wiring line at the store's construction
+   (journal in scope; emit drops harmlessly when absent/locked-out).
+3. NEW route GET /threadline/conversations (?scope=mesh) + the
+   ConversationMeshView fold: OWN rows from the LIVE store (the
+   authority — own-stream journal entries ignored), replica rows folded
+   per-stream last-writer on the composite (holderMachineId,
+   conversationId) key under the P1 reader's bounds, with staleness +
+   streamStatus + partial-result honesty. 200 with own rows when
+   replication is dark; 503 only when the store itself is absent.
+4. Agent Awareness on ALL THREE surfaces (template + migrateClaudeMd +
+   shadow markers + featureSections tracking): the holder-view trigger
+   including the relay's REAL offline bound (in-memory ~24h queue) in the
+   honest-answer wording.
+
+## Decision-point inventory
+
+- Transition derivation: first-commit → started (+bound when born
+  bound); boundTopicId change → unbound(old)+bound(new); non-terminal →
+  terminal → closed. No fingerprint → no emission (nothing coherent to
+  record).
+- The fold's `unbound` clears the binding; `closed` keeps the row with
+  status closed (existence stays answerable).
+- Emission failure NEVER reaches the conversation write (observability
+  invariant; try/catch at the seam).
+
+## 1-2. Over/Under-block
+
+Over: conversations without peer fingerprints never journal (deliberate).
+Under: the P1.2 reader reports streamStatus 'current' always — the
+gapped qualifier gains teeth with the P1.3 reader states (the spec's
+named dependency); until then partial-result is the honesty signal.
+
+## 3. Fit / 4. Blast radius
+
+The kind rides P1's transport/trust wholesale (proven by the integration
+test reusing the journal-sync applier verbatim); the store seam is one
+injected callback; the view is read-only. Emission is always-on with the
+journal (like every kind); REPLICATION of it rides the existing explicit
+gate. A bug can only mis-report holder visibility — nothing actuates off
+this view (Signal vs Authority).
+
+## Evidence
+
+- tests/unit/ThreadlineConversationKind.test.ts — 7 passing: schema
+  bounds + op-key dedupe; the commit() diff matrix (started/bound,
+  rebind unbound+bound naming the OLD topic, closed, non-lifecycle
+  emits NOTHING, no-fingerprint emits nothing); the fold (own-live +
+  replica last-writer + unbound clears + closed status + local scope).
+- tests/integration/threadline-conversation-replication.test.ts — 1
+  passing: store lifecycle on A → journal → buildServeBatch → apply on
+  B under A's authenticated identity → B's mesh view names A as holder
+  with the binding → close converges on the next delta.
+- CoherenceJournal (39 incl. the advert test updated for 4 kinds),
+  CoherenceJournalReader, JournalSyncApplier suites green;
+  feature-delivery-completeness (81) green. Typecheck clean.