# Upgrade Guide — vNEXT

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

## What Changed

First build slice of the Commitments Coherence spec (P1.5 of multi-machine
coherence): every machine can now SEE every machine's promises. Dark
everywhere except explicitly replication-enabled pairs.

- Every commitment is stamped with its home machine at creation; the
  cross-machine identity is (machine, id) together — because the plain ids
  are per-machine counters that collide by construction (the review
  round's headline catch: an id-keyed merge would have silently hidden
  real obligations).
- Each machine's store replicates to peers as small seq-windowed delta
  pages on the existing 30s presence cadence — one field change ships one
  record, not the whole store; a restored-from-backup store re-mints its
  incarnation so peers re-pull wholesale instead of stranding.
- Free-text fields are credential-shape-scanned at serve time; a flagged
  field ships redacted while the record itself still replicates.
- `GET /commitments?scope=mesh` merges own + replica rows with honest
  labels (replica + how stale) and flags possible cross-machine duplicate
  promises. The default scope is byte-identical to before.

NOT yet (P1.5b): closing a promise from the non-home machine (owner-routed
mutation + the durable offline queue).

The first LIVE run of the P2 working-set proof caught two real bugs; both
are fixed with regression tests.

1. On release days the server restarts in quick succession — the
   coherence journal's writer lock could be left held by a dead process,
   and the new writer sat silently read-only until the NEXT restart (75
   live minutes of missing placement/run history). The writer now retries
   on a bounded timer and recovers in place; live holders heartbeat the
   lock so even a recycled process id can't impersonate one.
2. A conversation deliberately moved to a machine — but quiet since the
   move — had no recorded owner, so the "go fetch this topic's workspace"
   reflex refused to run in exactly the situation it was built for. The
   deliberate placement (the pin) now counts as ownership until real
   traffic takes over.

## What to Tell Your User

On machine pairs with sync enabled: ask ANY machine "what are your open
commitments?" and you get the complete picture — promises made on the
other machine show up, honestly labeled with where they live and how
fresh the copy is. Closing one from the "wrong" machine arrives in the
next slice.

Nothing to do. Your machines' shared history can no longer silently stop
recording after updates, and fetching a moved conversation's files works
even before you've sent it a new message.

## Summary of New Capabilities

- `commitments-sync` MeshCommand — paged, incarnation-fenced delta
  replication of commitment records between same-operator machines.
- `src/core/CommitmentsSync.ts` — serve/receive/merge engine
  (CommitmentReplicaStore, mergeCommitmentViews, resolveBareId).
- `GET /commitments?scope=mesh` — the merged cross-machine view.
- CommitmentTracker: originMachineId stamping + replicationSeq /
  storeIncarnation / lastMutatedSeq bookkeeping (additive, legacy-safe).

- CoherenceJournal: lock retry timer + mtime heartbeat + pid-reuse-proof
  stale reclaim (issue #925).
- Working-set ownerOf seam: placement-pin fallback for unowned topics
  (issue #926; WORKING-SET-HANDOFF-SPEC §3.3 delta).
- Autonomous scanner: runs are not marked seen while the writer is
  locked out (dropped emits re-emit after recovery).

## Evidence

- 15 unit (CommitmentsSync) + 2 integration (real signed transport
  round-trip w/ delta-only convergence; mixed-version 501) + 77
  CommitmentTracker tests unchanged; typecheck/lint/docs-coverage clean.

3 new lock tests (38 total in CoherenceJournal.test.ts); live remediation
on the echo pair confirmed the analysis end-to-end.
