# Upgrade Guide — vNEXT

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

## What Changed

The send half of multi-machine memory replication is now wired. The WS2 substrate
shipped the replicated-kind registry, the receive/apply machinery, and the
capability advert, but the journal-backed emitter that the per-store managers' write
hooks call was never constructed — so memory records were never written to the
coherence-journal own-streams, and a peer had nothing to pull (root-caused live on a
Laptop↔Mac-Mini pair).

This change adds the generic, store-agnostic `ReplicatedRecordEmitter` (HLC tick +
last-writer-witness + the store's record builder + journal append, behind the
per-store dark gate), closes the three matching gaps so a record crosses end-to-end —
the journal can now append/validate a `*-record` kind, the applier accepts a peer's
`*-record` instead of suspect-flagging the stream, and the union read materializes
own + peer journal streams (so a received record is readable) — and replaces the
snapshot-serve `loadOwnEntries` stub with a real own-stream loader. The first kind,
`learnings`, is wired end-to-end; the remaining memory stores follow on the same
machinery (tracked in the send-wiring manifest). A wiring-integrity ratchet now fails
CI if a future replicated kind is added receive-only with no send path.

Everything is gated behind the per-store multi-machine memory-sync switch (off by
default; the development-agent gate flips it live on a dev agent only). Records ride
the existing journal-sync tail and pull — no new HTTP route or mesh verb.

## What to Tell Your User

- **Cross-machine memory (lessons) now actually crosses**: "If you run me on more than
  one machine, a lesson I learn on one is now known on the others — one shared learning
  registry instead of one per machine. A copy from another machine is always treated as
  a hint, never as the boss: it never silently overwrites what this machine already
  believes, and if two machines disagree I surface both and flag it for you. It stays
  off until you ask me to turn on multi-machine memory sync."

## Summary of New Capabilities

| Capability | How to Use |
|-----------|-----------|
| Cross-machine replication of learned lessons (learnings) | Automatic once multi-machine memory sync is enabled for the store (off by default) |
| A received peer memory is readable through the no-clobber union read | Automatic (read path) |
| Snapshot serve returns real own-stream entries | Automatic (bootstrap path) |
| Wiring-integrity ratchet — no new kind can ship receive-only | CI test (automatic) |

## Evidence

The live gap: after the receive-advert fix (#1167) deployed to both machines, a
learning written on the Laptop never appeared on the Mac-Mini after 5+ minutes; the
Laptop's coherence-journal meta listed only the 5 lifecycle kinds — none of the 7 WS2
record kinds — proving no record was ever emitted to an own-stream.

Verified by a two-instance in-process E2E
(tests/e2e/ws2-learnings-cross-instance.test.ts): a learning written on instance A,
shipped over the real journal serve/apply path, is read back on instance B through the
bypass-proof union reader as a foreign-origin record; a markApplied edit replicates and
the latest wins; the same lesson learned on both machines collapses to one record key
across origins. Before this change B's union read returned null (the reproduced bug);
after, it returns A's record. Plus integration (serve→apply→read, forged-batch
rejection, snapshot serve returns entries) and unit coverage (emitter dark-gate /
witness-order / throw-isolation, journal record append + op-key dedup + 80 KB cap, peer
stream materialization). 32 new tests, all green.
