# Upgrade Guide — vNEXT

<!-- assembled-by: assemble-next-md -->
<!-- bump: minor -->

## What Changed

**Coherence Journal P1.1** (COHERENCE-JOURNAL-SPEC, converged + approved):
every machine now writes per-kind append-only event streams under
`state/coherence-journal/` — `topic-placement` (emitted at all 8
ownership-CAS sites with caller-known reasons, paired by a new CI lint),
`session-lifecycle` (derived at the saveSession funnel; `reaped` emitted
beside the reap-log), `autonomous-run` (60s observer + stop-funnel seam —
no phantom-live runs). Writer is non-blocking (memory enqueue + 250ms
flusher; zero sync I/O in caller stacks), crash-safe (repair-counted
truncation, incarnation-fenced restore detection), single-process-locked,
schema-typed with artifactPath jail. Plus: the State-Coherence Registry is
now machine-readable (`src/data/state-coherence-registry.json`, 66
categories) with `lint-state-registry` failing CI on undeclared durable
stores. Dark-ship: `multiMachine.coherenceJournal.enabled ?? developmentAgent`.

**Coherence Journal P1.2** — the read API. `GET /coherence/journal` serves
the merged placement / session-lifecycle / autonomous-run history from
local disk: skew-proof `(epoch,ts)` ordering for placement, replica entries
labeled with `source:"replica"` + `stalenessMs`, `(topic,epoch)` dedupe,
bounded reverse-tail reads (byte ceiling + archive caps; placement stays
answer-complete), opaque keyset cursors, corrupt lines skipped + counted.
New `lint-journal-actuation-ban` build-enforces §3.9 (actuators may not
import the reader). CLAUDE.md template teaches every agent the capability.
TelegramAdapter emergency-stop now reports its journal line instantly.

**Coherence Journal P1.3 (apply/serve engine)** — `JournalSyncApplier`,
the pure mesh-independent receive+serve engine for journal replication
(COHERENCE-JOURNAL-SPEC §3.4): first-hop sender binding, schema-validated
apply with suspect-self-clear, incarnation-fenced restore detection with
bounded quarantine, truncation gap signals, ack-after-fdatasync on receive,
and durably-flushed-only own-stream serve. The `journal-sync` mesh verb +
session-status advert + the live two-machine proof are the closing wiring
step (the engine ships ahead of the network exposure, fully tested).

Adds a **learning-velocity metric** — Salim Ismail's EXO 3.0 KPI inversion (from
*Your KPI System Is Training You to Miss the Future*). Backward-looking
operational KPIs (throughput, utilization, efficiency) reward the existing model
and suppress the weak signals where the future shows up. The EXO 3.0 answer is to
measure how fast you're **learning** — adaptability, experimentation, capability
creation.

Instar already emits the raw learning events (registered learnings, captured
corrections, evolution actions); this turns them into a signal:

- `GET /metrics/learning-velocity?windowDays=30` → `{ totalEvents, eventsPerDay,
  byType, typeDiversity, trend, adaptabilityScore, reason }`.
- `trend` is `accelerating` | `steady` | `declining` | `insufficient-data`
  (first-half vs second-half of the window).
- `adaptabilityScore` (0–100) blends velocity (saturating) with category
  diversity.

Read-only + advisory — it never gates anything. A flat or declining trend is the
EXO 3.0 warning sign that the org is optimizing the old model instead of learning.

## What to Tell Your User

Nothing user-visible yet — this is the foundation layer. Your agent's
machines have started keeping reliable local "diaries" of where
conversations live, when sessions open/close, and where autonomous runs
put their files. The pieces that let you ASK about that history from any
machine arrive in the next two updates (the query API, then
machine-to-machine sync).

If your agent runs on more than one machine, you can now ask it "which
machine was this conversation on last night, and why did it move?" or
"where did the overnight run put its files?" — and it answers from a
durable history instead of guessing. (Multi-machine sync of those
histories lands in the next update; today each machine answers from what
it holds.)

Nothing user-visible changes yet — this is the engine that will let your
agent's machines safely exchange their diaries. Once the final wiring lands,
asking ANY machine "where did this conversation live / where are the
overnight files?" will answer from a synced history. Today the engine is in
place and proven; the cross-machine exchange turns on with the next step.

Your agent can now answer "are we actually learning, or just running?" with real numbers. Ask it for its learning velocity and you get a trend — accelerating, steady, or declining — built from its genuine learning events (lessons it recorded, corrections it absorbed, capabilities it grew) instead of backward-looking activity stats. The EXO 3.0 idea behind it: traditional KPIs measure how well the OLD model runs; learning velocity measures whether you're building the next one. A flat or declining trend is your early warning that things are coasting.

## Summary of New Capabilities

- None user-invocable yet (P1.2 ships `GET /coherence/journal` + the
  agent-facing docs). Internal: `CoherenceJournal` writer,
  `StateManager.guardJournalWrite`, machine-readable state registry, two
  new CI lints.

- `GET /coherence/journal?topic=N&kind=...&machine=...&limit=...&cursor=...`
  — merged journal view; read-only; 503 when the journal is not enabled.
- Agents proactively reach for it on "where did topic N live / where are
  the artifacts?" questions (CLAUDE.md template entry ships in this
  release).

- None user-invocable yet (the engine is internal; the `journal-sync`
  transport that drives it is the closing wiring step). Internal:
  `JournalSyncApplier` (receive+serve engine for §3.4 replication).

- `GET /metrics/learning-velocity?windowDays=30` — `{ totalEvents, eventsPerDay, byType, typeDiversity, trend, adaptabilityScore (0-100), reason }`, computed from registered learnings, corrections, and evolution actions. Read-only + advisory — never gates.
- PROACTIVE trigger: "are we learning/adapting?" → read this metric and contrast it with operational throughput.

## Evidence

- 56 new tests (writer 33 incl. fault-injected non-blocking emit +
  kill-9-window re-mint precision; wiring 9 with independent oracles;
  guard 7; registry lint 7); 357 tests green across the affected surface;
  both lints clean on the real tree; tsc clean.
- The cas-pairing lint caught a real unpaired site (POST /pool/transfer
  release) during development — the structural guard works.

- 22 new reader/route tests + Tier-3 e2e lifecycle (feature-alive, 503
  when dark); actuation-ban lint clean over 8 actuator modules; tsc + full
  lint chain clean.

- 26 new tests covering every §3.4 rule (seq-gating, forged-entry reject,
  suspect→self-clear, incarnation quarantine bounds + reset-flapping,
  truncation fast-forward, ack-after-fsync ordering via injected spy,
  guardWrite refusal). tsc + full lint chain clean.

Three-tier coverage, all green, `tsc --noEmit` clean:

- Unit — `LearningVelocityScorer.test.ts` (6): empty, window exclusion,
  accelerating, declining, insufficient-data, and byType/diversity/adaptability.
- Integration — `learning-velocity-routes.test.ts` (3): the route reads a real
  `learning-registry.json` + corrections over HTTP and computes.
- E2E — `learning-velocity-lifecycle.test.ts` (1): a real server on a real port,
  feature alive end-to-end (200, not 404/503).

CLAUDE.md scaffold template documents the endpoint.
