amalgm 0.1.152 → 0.1.153

package/runtime/scripts/amalgm-mcp/tests/state-docs-versioning.test.js

@@ -0,0 +1,394 @@
+'use strict';
+
+// Versioned-write contract + unversioned-overwrite preservation.
+//
+// The silent-loss bug this file exists for: reconcileFromDisk's merge gate
+// (`ours !== base`) only protects live edits still inside the write-back
+// debounce window. Once a human edit FLUSHES (live == lastDiskText == B), an
+// external writer holding a stale read A can write C and the gate sees no
+// divergence — C applies wholesale and B's edits vanish with no merge, no
+// sidecar, no event. The tests here pin the fix: flushed live-channel edits
+// are either preserved in the resulting text or recoverably preserved in a
+// conflict sidecar and surfaced on the doc event.
+//
+// It also pins the versioned write path (writeDocText / POST
+// /state/docs/write): a writer that declares the base it read (baseHash /
+// baseSeq) gets a true three-way merge against the retained disk-sync
+// history; an unknown base degrades conservatively (preserve both, surface a
+// conflict), never to a silent winner.
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const crypto = require('crypto');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'amalgm-docs-versioning-test-'));
+process.env.AMALGM_DIR = path.join(tempRoot, '.amalgm');
+
+const Y = require('yjs');
+const { closeLocalDb } = require('../state/db');
+const docs = require('../state/docs');
+const { listEventsAfter, currentSeq } = require('../state/events');
+
+const docDir = path.join(tempRoot, 'workspace');
+fs.mkdirSync(docDir, { recursive: true });
+
+function writeDoc(name, text) {
+  const target = path.join(docDir, name);
+  fs.writeFileSync(target, text, 'utf8');
+  return target;
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function sha256(text) {
+  return crypto.createHash('sha256').update(text, 'utf8').digest('hex');
+}
+
+function clientFromState(stateBase64) {
+  const doc = new Y.Doc();
+  Y.applyUpdate(doc, new Uint8Array(Buffer.from(stateBase64, 'base64')));
+  return doc;
+}
+
+function encodeLocalEdit(doc, mutate) {
+  let captured = null;
+  const listener = (update) => { captured = update; };
+  doc.on('update', listener);
+  mutate(doc.getText('content'));
+  doc.off('update', listener);
+  assert.ok(captured, 'edit should produce an update');
+  return Buffer.from(captured).toString('base64');
+}
+
+function sidecarsFor(target) {
+  const ext = path.extname(target);
+  const stem = path.basename(target, ext);
+  const pattern = new RegExp(
+    `^${stem}\\.conflicted-\\d{8}-\\d{6}(?:-\\d+)?${ext.replace('.', '\\.')}$`,
+  );
+  return fs.readdirSync(path.dirname(target))
+    .filter((name) => pattern.test(name))
+    .map((name) => path.join(path.dirname(target), name));
+}
+
+function conflictEventsFor(resource, afterSeq) {
+  return listEventsAfter(afterSeq).filter((e) => e.resource === resource && e.patch?.conflict);
+}
+
+test.after(() => {
+  docs.closeAllDocs();
+  closeLocalDb();
+  fs.rmSync(tempRoot, { recursive: true, force: true });
+});
+
+// ---------------------------------------------------------------------------
+// The confirmed silent-loss sequence (step 1: this test MUST fail against the
+// pre-fix code).
+// ---------------------------------------------------------------------------
+
+test('flushed human edits survive a stale external rewrite (preserved or sidecar + event)', async () => {
+  const versionA = 'l1\nl2\nl3\n';
+  const target = writeDoc('stale-rewrite.md', versionA);
+  const opened = docs.openDoc(target);
+  const client = clientFromState(opened.state);
+
+  // Human edits l2 through the live channel…
+  docs.applyDocUpdates(target, [
+    encodeLocalEdit(client, (ytext) => ytext.insert('l1\nl2'.length, ' human')),
+  ]);
+  // …and the edit FLUSHES: disk == live == lastDiskText == B. This is the
+  // window the old merge gate does not protect.
+  await sleep(500);
+  const versionB = 'l1\nl2 human\nl3\n';
+  assert.equal(fs.readFileSync(target, 'utf8'), versionB, 'precondition: human edit flushed to disk');
+
+  const before = currentSeq();
+  // An agent that read version A (stale) writes C — derived from A, without
+  // the human's l2 edit — directly to disk.
+  const versionC = 'l1\nl2\nl3 agent\n';
+  fs.writeFileSync(target, versionC, 'utf8');
+  await sleep(700);
+
+  const text = docs.getDocText(target);
+  const humanEditInText = text.includes('l2 human');
+  const sidecars = sidecarsFor(target);
+  const humanEditInSidecar = sidecars.some((p) => fs.readFileSync(p, 'utf8').includes('l2 human'));
+  const conflicts = conflictEventsFor(opened.resource, before);
+
+  assert.ok(
+    humanEditInText || (humanEditInSidecar && conflicts.length >= 1),
+    'the human\'s flushed edit must be preserved in the text, or recoverably preserved '
+    + `in a sidecar AND surfaced as a conflict event (text=${JSON.stringify(text)}, `
+    + `sidecars=${sidecars.length}, conflictEvents=${conflicts.length})`,
+  );
+});
+
+test('unversioned overwrite of flushed live edits: incoming applies, replaced text sidecar\'d, event flagged', async () => {
+  const versionA = 'a1\na2\na3\n';
+  const target = writeDoc('overwrite-flagged.md', versionA);
+  const opened = docs.openDoc(target);
+  const client = clientFromState(opened.state);
+
+  docs.applyDocUpdates(target, [
+    encodeLocalEdit(client, (ytext) => ytext.insert('a1\na2'.length, ' human')),
+  ]);
+  await sleep(500);
+  const versionB = 'a1\na2 human\na3\n';
+  assert.equal(fs.readFileSync(target, 'utf8'), versionB);
+
+  const before = currentSeq();
+  const versionC = 'rewritten\nwholesale\n';
+  fs.writeFileSync(target, versionC, 'utf8');
+  await sleep(700);
+
+  // Raw fs writers keep the freedom to rewrite files: the incoming text wins…
+  assert.equal(docs.getDocText(target), versionC);
+  // …but the replaced live-channel text is preserved…
+  const sidecars = sidecarsFor(target);
+  assert.equal(sidecars.length, 1, 'exactly one sidecar for the replaced text');
+  assert.equal(fs.readFileSync(sidecars[0], 'utf8'), versionB, 'sidecar holds the replaced flushed text');
+  // …and the overwrite is surfaced, not silent.
+  const conflicts = conflictEventsFor(opened.resource, before);
+  assert.equal(conflicts.length, 1);
+  assert.equal(conflicts[0].patch.conflict.reason, 'unversioned-overwrite');
+  assert.equal(conflicts[0].patch.conflict.sidecarPath, sidecars[0]);
+});
+
+test('agent rewrites with no live edits since last sync stay silent: no sidecar, no conflict', async () => {
+  const target = writeDoc('agent-rewrites.md', 'r1\n');
+  const opened = docs.openDoc(target);
+  const before = currentSeq();
+
+  // Two successive raw rewrites with nothing arriving through the live
+  // channel in between — the overwhelmingly common agent case.
+  fs.writeFileSync(target, 'r1\nr2\n', 'utf8');
+  await sleep(700);
+  fs.writeFileSync(target, 'r1\nr2\nr3\n', 'utf8');
+  await sleep(700);
+
+  assert.equal(docs.getDocText(target), 'r1\nr2\nr3\n');
+  assert.equal(sidecarsFor(target).length, 0, 'no sidecar spam for plain agent rewrites');
+  assert.equal(conflictEventsFor(opened.resource, before).length, 0, 'no conflict events either');
+});
+
+test('unflushed live edits still merge exactly as before (step-5 regression guard)', async () => {
+  const base = 'k1\nk2\nk3\nk4\nk5\n';
+  const target = writeDoc('unflushed-window.md', base);
+  const opened = docs.openDoc(target);
+  const client = clientFromState(opened.state);
+
+  // Live edit NOT yet flushed (inside the 300ms debounce)…
+  docs.applyDocUpdates(target, [
+    encodeLocalEdit(client, (ytext) => ytext.insert('k1'.length, ' human')),
+  ]);
+  // …and a disjoint external write lands immediately.
+  fs.writeFileSync(target, 'k1\nk2\nk3\nk4\nk5 agent\n', 'utf8');
+  await sleep(900);
+
+  assert.equal(docs.getDocText(target), 'k1 human\nk2\nk3\nk4\nk5 agent\n');
+  assert.equal(sidecarsFor(target).length, 0);
+});
+
+// ---------------------------------------------------------------------------
+// Versioned writes: the SDK contract (writeDocText / POST /state/docs/write).
+// ---------------------------------------------------------------------------
+
+test('open returns the sha256 a versioned writer sends back as baseHash', () => {
+  const target = writeDoc('hash-handshake.md', 'h1\n');
+  const opened = docs.openDoc(target);
+  assert.equal(opened.sha256, sha256('h1\n'));
+});
+
+test('versioned write whose base matches the live text applies as-is (fast path)', () => {
+  const target = writeDoc('fastpath.md', 'f1\nf2\n');
+  docs.openDoc(target);
+  const result = docs.writeDocText(target, 'f1\nf2\nf3\n', { baseHash: sha256('f1\nf2\n') });
+  assert.equal(result.merge, 'clean');
+  assert.equal(result.conflict, null);
+  assert.equal(result.sha256, sha256('f1\nf2\nf3\n'));
+  assert.equal(docs.getDocText(target), 'f1\nf2\nf3\n');
+  assert.equal(sidecarsFor(target).length, 0);
+});
+
+test('versioned write from a stale base three-way merges: non-overlapping edits both land', async () => {
+  const versionA = 'v1\nv2\nv3\nv4\nv5\n';
+  const target = writeDoc('versioned-merge.md', versionA);
+  const opened = docs.openDoc(target);
+  const client = clientFromState(opened.state);
+  const baseHash = opened.sha256;
+
+  // Human edits line 1 and the edit flushes — the exact window the raw-disk
+  // path could not protect.
+  docs.applyDocUpdates(target, [
+    encodeLocalEdit(client, (ytext) => ytext.insert('v1'.length, ' human')),
+  ]);
+  await sleep(500);
+
+  const before = currentSeq();
+  // The writer read version A; its rewrite touches only line 5.
+  const result = docs.writeDocText(target, 'v1\nv2\nv3\nv4\nv5 agent\n', { baseHash });
+
+  assert.equal(result.merge, 'merged');
+  assert.equal(result.conflict, null);
+  assert.equal(docs.getDocText(target), 'v1 human\nv2\nv3\nv4\nv5 agent\n');
+  assert.equal(result.sha256, sha256('v1 human\nv2\nv3\nv4\nv5 agent\n'));
+  assert.equal(sidecarsFor(target).length, 0, 'clean merge writes no sidecar');
+  assert.equal(conflictEventsFor(opened.resource, before).length, 0);
+
+  await sleep(500);
+  assert.equal(fs.readFileSync(target, 'utf8'), 'v1 human\nv2\nv3\nv4\nv5 agent\n');
+});
+
+test('versioned write with overlapping edits conflicts: OURS kept, THEIRS sidecar\'d, event published', async () => {
+  const versionA = 'c1\nc2\nc3\n';
+  const target = writeDoc('versioned-conflict.md', versionA);
+  const opened = docs.openDoc(target);
+  const client = clientFromState(opened.state);
+  const baseHash = opened.sha256;
+
+  docs.applyDocUpdates(target, [
+    encodeLocalEdit(client, (ytext) => ytext.insert('c1\nc2'.length, ' human')),
+  ]);
+  await sleep(500);
+
+  const before = currentSeq();
+  const theirs = 'c1\nc2 agent\nc3\n';
+  const result = docs.writeDocText(target, theirs, { baseHash });
+
+  assert.equal(result.merge, 'conflict');
+  assert.equal(result.conflict.reason, 'overlapping-hunks');
+  assert.equal(result.conflict.hunks, 1);
+  // Both versions present: OURS in the live text, THEIRS in the sidecar.
+  assert.equal(docs.getDocText(target), 'c1\nc2 human\nc3\n');
+  const sidecars = sidecarsFor(target);
+  assert.equal(sidecars.length, 1);
+  assert.equal(fs.readFileSync(sidecars[0], 'utf8'), theirs);
+  assert.equal(result.conflict.sidecarPath, sidecars[0]);
+
+  const conflicts = conflictEventsFor(opened.resource, before);
+  assert.equal(conflicts.length, 1);
+  assert.equal(conflicts[0].patch.conflict.reason, 'overlapping-hunks');
+});
+
+test('versioned write with an unknown base is conservative: live text sidecar\'d, write applies, base-unknown surfaced', async () => {
+  const target = writeDoc('base-unknown.md', 'u1\nu2\n');
+  const opened = docs.openDoc(target);
+  const client = clientFromState(opened.state);
+
+  docs.applyDocUpdates(target, [
+    encodeLocalEdit(client, (ytext) => ytext.insert('u1'.length, ' human')),
+  ]);
+  await sleep(500);
+  const live = 'u1 human\nu2\n';
+
+  const before = currentSeq();
+  const result = docs.writeDocText(target, 'incoming rewrite\n', {
+    baseHash: sha256('some text this doc never contained\n'),
+  });
+
+  assert.equal(result.merge, 'base-unknown');
+  assert.equal(result.conflict.reason, 'base-unknown');
+  // Writer keeps the freedom to rewrite; the live text is recoverable.
+  assert.equal(docs.getDocText(target), 'incoming rewrite\n');
+  const sidecars = sidecarsFor(target);
+  assert.equal(sidecars.length, 1);
+  assert.equal(fs.readFileSync(sidecars[0], 'utf8'), live, 'sidecar preserves the replaced live text');
+  const conflicts = conflictEventsFor(opened.resource, before);
+  assert.equal(conflicts.length, 1);
+  assert.equal(conflicts[0].patch.conflict.reason, 'base-unknown');
+});
+
+test('versioned write via baseSeq resolves against the retained history', async () => {
+  const versionA = 's1\ns2\ns3\n';
+  const target = writeDoc('base-seq.md', versionA);
+  const opened = docs.openDoc(target);
+  const client = clientFromState(opened.state);
+  const entry = docs._private.openDocs.get(opened.path);
+  const baseSeq = entry.diskHistory[entry.diskHistory.length - 1].seq;
+
+  docs.applyDocUpdates(target, [
+    encodeLocalEdit(client, (ytext) => ytext.insert('s1'.length, ' human')),
+  ]);
+  await sleep(500);
+
+  const result = docs.writeDocText(target, 's1\ns2\ns3 agent\n', { baseSeq });
+  assert.equal(result.merge, 'merged');
+  assert.equal(docs.getDocText(target), 's1 human\ns2\ns3 agent\n');
+});
+
+test('unversioned API write over live edits preserves them; over synced text applies silently', async () => {
+  const target = writeDoc('no-base.md', 'n1\n');
+  const opened = docs.openDoc(target);
+  const client = clientFromState(opened.state);
+
+  // No live edits since last sync: applies silently, like an agent rewrite.
+  const beforeQuiet = currentSeq();
+  const quiet = docs.writeDocText(target, 'n1\nn2\n', {});
+  assert.equal(quiet.merge, 'overwrite');
+  assert.equal(quiet.conflict, null);
+  assert.equal(sidecarsFor(target).length, 0);
+  assert.equal(conflictEventsFor(opened.resource, beforeQuiet).length, 0);
+
+  // Live edit flushed, then a no-base write replaces it: preserve + surface.
+  docs.applyDocUpdates(target, [
+    encodeLocalEdit(client, (ytext) => ytext.insert('n1'.length, ' human')),
+  ]);
+  await sleep(500);
+  const live = 'n1 human\nn2\n';
+  const before = currentSeq();
+  const result = docs.writeDocText(target, 'replaced\n', {});
+  assert.equal(result.merge, 'overwrite');
+  assert.equal(result.conflict.reason, 'unversioned-overwrite');
+  assert.equal(docs.getDocText(target), 'replaced\n');
+  const sidecars = sidecarsFor(target);
+  assert.equal(sidecars.length, 1);
+  assert.equal(fs.readFileSync(sidecars[0], 'utf8'), live);
+  assert.equal(conflictEventsFor(opened.resource, before).length, 1);
+});
+
+test('write validation is shape-explicit with example payloads', () => {
+  const target = writeDoc('validation.md', 'x\n');
+  docs.openDoc(target);
+  assert.throws(() => docs.writeDocText(target, 42, {}), /"text" must be[\s\S]*e\.g\./);
+  assert.throws(
+    () => docs.writeDocText(target, 'ok\n', { baseHash: 'not-a-hash' }),
+    /"baseHash" must be[\s\S]*sha256[\s\S]*e\.g\./,
+  );
+  assert.throws(
+    () => docs.writeDocText(target, 'ok\n', { baseSeq: -3 }),
+    /"baseSeq" must be[\s\S]*e\.g\./,
+  );
+  assert.throws(
+    () => docs.writeDocText(target, 'ok\n', { baseSeq: 1.5 }),
+    /"baseSeq" must be/,
+  );
+});
+
+test('writing identical text is a no-op: no sidecar, no event, no disk churn', async () => {
+  const target = writeDoc('idempotent.md', 'same\n');
+  const opened = docs.openDoc(target);
+  const before = currentSeq();
+  const result = docs.writeDocText(target, 'same\n', { baseHash: sha256('same\n') });
+  assert.equal(result.merge, 'noop');
+  await sleep(700);
+  assert.equal(listEventsAfter(before).filter((e) => e.resource === opened.resource).length, 0);
+  assert.equal(sidecarsFor(target).length, 0);
+});
+
+test('disk-sync history is bounded', async () => {
+  const target = writeDoc('bounded.md', 'gen 0\n');
+  const opened = docs.openDoc(target);
+  const entry = docs._private.openDocs.get(opened.path);
+  for (let i = 1; i <= 12; i += 1) {
+    docs.writeDocText(target, `gen ${i}\n`, { baseHash: sha256(`gen ${i - 1}\n`) });
+    await sleep(400); // let each write flush so history records each state
+  }
+  assert.ok(entry.diskHistory.length <= 8, `history stays bounded (got ${entry.diskHistory.length})`);
+  const head = entry.diskHistory[entry.diskHistory.length - 1];
+  assert.equal(head.text, 'gen 12\n', 'head is always the current disk-sync state');
+});

package/runtime/scripts/amalgm-mcp/tests/state-stream-bootstrap.test.js

@@ -0,0 +1,223 @@
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { EventEmitter } = require('events');
+
+const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'amalgm-stream-bootstrap-test-'));
+process.env.AMALGM_DIR = path.join(tempRoot, '.amalgm');
+
+const { closeLocalDb } = require('../state/db');
+const { appendStateEvent, currentSeq } = require('../state/events');
+const registry = require('../state/registry');
+const rest = require('../state/rest');
+
+test.after(() => {
+  closeLocalDb();
+  fs.rmSync(tempRoot, { recursive: true, force: true });
+});
+
+// Test resources. `midBuildEmits` makes reads append state events while the
+// snapshot is being built — the "write lands mid-read" scenario the snapshot
+// retry loop exists for, and the only way anything can interleave with the
+// synchronous build.
+let midBuildEmits = 0;
+registry.registerResource('boot:a', { read: () => [{ id: 'a' }] });
+registry.registerResource('boot:b', { read: () => [{ id: 'b' }] });
+registry.registerResource('boot:mid', {
+  read: () => {
+    if (midBuildEmits > 0) {
+      midBuildEmits -= 1;
+      appendStateEvent({ resource: 'boot:other', op: 'replace', value: [], source: 'mid-build' });
+    }
+    return [{ id: 'mid' }];
+  },
+});
+registry.registerResource('boot:throw', {
+  read: () => {
+    throw new Error('kaboom');
+  },
+});
+
+function fakeRequest() {
+  return new EventEmitter();
+}
+
+function fakeResponse() {
+  const res = new EventEmitter();
+  res.writes = [];
+  res.destroyed = false;
+  res.writableEnded = false;
+  res.writeHead = () => res;
+  res.write = (chunk) => {
+    res.writes.push(String(chunk));
+    return true;
+  };
+  res.end = () => {
+    res.writableEnded = true;
+  };
+  return res;
+}
+
+// SSE frames are delimited by a blank line; a frame may span writes (control
+// frames are two writes), so parse the concatenated output.
+function framesOf(res) {
+  return res.writes
+    .join('')
+    .split('\n\n')
+    .filter(Boolean)
+    .map((raw) => {
+      const frame = { raw };
+      for (const line of raw.split('\n')) {
+        if (line.startsWith(':')) frame.comment = line.slice(1).trim();
+        else if (line.startsWith('event: ')) frame.event = line.slice('event: '.length);
+        else if (line.startsWith('id: ')) frame.id = Number(line.slice('id: '.length));
+        else if (line.startsWith('data: ')) frame.data = JSON.parse(line.slice('data: '.length));
+      }
+      return frame;
+    });
+}
+
+function dataFramesOf(res) {
+  return framesOf(res).filter((frame) => frame.data !== undefined);
+}
+
+function stateFramesOf(res) {
+  return framesOf(res).filter((frame) => frame.event === 'state');
+}
+
+test('bootstrap=1: snapshot is the first data frame, correct seq, requested resources only', () => {
+  // Backlog exists; legacy would replay it. Bootstrap must not.
+  appendStateEvent({ resource: 'boot:other', op: 'replace', value: [], source: 'test' });
+  appendStateEvent({ resource: 'boot:other', op: 'replace', value: [], source: 'test' });
+
+  const req = fakeRequest();
+  const res = fakeResponse();
+  rest.handleStream(req, res, { bootstrap: '1', resources: 'boot:a' });
+
+  const frames = framesOf(res);
+  assert.equal(frames[0].comment, 'local-live-store connected', 'hello comment first');
+  assert.equal(frames[0].data, undefined);
+
+  const data = dataFramesOf(res);
+  assert.equal(data[0].event, 'snapshot', 'snapshot is the first data frame');
+  assert.equal(data[0].data.seq, currentSeq(), 'snapshot seq is the current seq');
+  assert.deepEqual(data[0].data.resources, { 'boot:a': [{ id: 'a' }] }, 'only the requested resource');
+  assert.equal(stateFramesOf(res).length, 0, 'no backlog replay in bootstrap mode');
+
+  const live = appendStateEvent({ resource: 'boot:other', op: 'replace', value: [], source: 'test' });
+  const states = stateFramesOf(res);
+  assert.equal(states.length, 1, 'live events flow after the snapshot');
+  assert.equal(states[0].id, live.seq);
+
+  req.emit('close');
+});
+
+test('an event arriving mid-build is buffered and flushed after the snapshot frame, exactly once, in seq order', () => {
+  const before = currentSeq();
+  // Every snapshot attempt sees a write land mid-read: three attempts append
+  // seq before+1..before+3 and the build serves best-effort at before+2
+  // (attempt 3's start). before+3 is newer than the snapshot and must be
+  // flushed after it; before+1/+2 are inside it and must not.
+  midBuildEmits = 3;
+
+  const req = fakeRequest();
+  const res = fakeResponse();
+  rest.handleStream(req, res, { bootstrap: '1', resources: 'boot:mid' });
+
+  assert.equal(midBuildEmits, 0, 'the build consumed all three mid-read writes');
+  const data = dataFramesOf(res);
+  assert.equal(data[0].event, 'snapshot', 'snapshot frame still first');
+  assert.equal(data[0].data.seq, before + 2);
+
+  const states = stateFramesOf(res);
+  assert.deepEqual(states.map((frame) => frame.id), [before + 3], 'exactly the one post-snapshot event, exactly once');
+
+  const live = appendStateEvent({ resource: 'boot:other', op: 'replace', value: [], source: 'test' });
+  assert.deepEqual(
+    stateFramesOf(res).map((frame) => frame.id),
+    [before + 3, live.seq],
+    'live events continue in seq order after the flush',
+  );
+
+  req.emit('close');
+});
+
+test('events at or below snapshot.seq are not re-sent', () => {
+  const before = currentSeq();
+  // One mid-read write: attempt 1 is unstable, attempt 2 stabilizes at
+  // before+1 — the buffered event is inside the snapshot, so nothing flushes.
+  midBuildEmits = 1;
+
+  const req = fakeRequest();
+  const res = fakeResponse();
+  rest.handleStream(req, res, { bootstrap: '1', resources: 'boot:mid' });
+
+  const data = dataFramesOf(res);
+  assert.equal(data[0].event, 'snapshot');
+  assert.equal(data[0].data.seq, before + 1);
+  assert.equal(data[0].data.stable, true);
+  assert.equal(stateFramesOf(res).length, 0, 'the mid-build event is already inside the snapshot');
+
+  req.emit('close');
+});
+
+test('legacy mode is byte-identical: no snapshot frame, after= replay unchanged', () => {
+  appendStateEvent({ resource: 'boot:other', op: 'replace', value: [], source: 'test' });
+  const e1 = appendStateEvent({ resource: 'boot:other', op: 'replace', value: [{ id: 'e1' }], source: 'test' });
+  const e2 = appendStateEvent({ resource: 'boot:other', op: 'replace', value: [{ id: 'e2' }], source: 'test' });
+
+  const req = fakeRequest();
+  const res = fakeResponse();
+  rest.handleStream(req, res, { after: String(e1.seq - 1) });
+
+  assert.deepEqual(res.writes, [
+    ': local-live-store connected\n\n',
+    `id: ${e1.seq}\nevent: state\ndata: ${JSON.stringify(e1)}\n\n`,
+    `id: ${e2.seq}\nevent: state\ndata: ${JSON.stringify(e2)}\n\n`,
+  ]);
+
+  const e3 = appendStateEvent({ resource: 'boot:other', op: 'replace', value: [{ id: 'e3' }], source: 'test' });
+  assert.equal(res.writes.length, 4, 'live event is one write');
+  assert.equal(res.writes[3], `id: ${e3.seq}\nevent: state\ndata: ${JSON.stringify(e3)}\n\n`);
+  assert.ok(!res.writes.join('').includes('event: snapshot'), 'legacy stream never sends a snapshot frame');
+
+  req.emit('close');
+});
+
+test('a throwing resource read produces a clean stream error and terminates', () => {
+  const req = fakeRequest();
+  const res = fakeResponse();
+  rest.handleStream(req, res, { bootstrap: '1', resources: 'boot:throw' });
+
+  const data = dataFramesOf(res);
+  assert.equal(data.length, 1, 'exactly one data frame');
+  assert.equal(data[0].event, 'error');
+  assert.deepEqual(data[0].data, { status: 500, error: 'kaboom' });
+  assert.equal(res.writableEnded, true, 'the stream is ended, not left hanging');
+  assert.ok(!res.writes.join('').includes('event: snapshot'), 'no snapshot frame on failure');
+
+  // The subscriber must be released: later events write nothing.
+  const writesAfterDeath = res.writes.length;
+  appendStateEvent({ resource: 'boot:other', op: 'replace', value: [], source: 'test' });
+  assert.equal(res.writes.length, writesAfterDeath, 'torn-down stream receives no events');
+});
+
+test('unknown resource names: snapshot contains what it can, no crash', () => {
+  const req = fakeRequest();
+  const res = fakeResponse();
+  rest.handleStream(req, res, { bootstrap: '1', resources: 'boot:nope,boot:a' });
+
+  const data = dataFramesOf(res);
+  assert.equal(data[0].event, 'snapshot');
+  assert.deepEqual(data[0].data.resources, { 'boot:a': [{ id: 'a' }] }, 'unknown names are simply absent');
+  assert.equal(data[0].data.seq, currentSeq());
+
+  const live = appendStateEvent({ resource: 'boot:other', op: 'replace', value: [], source: 'test' });
+  assert.equal(stateFramesOf(res).at(-1).id, live.seq, 'stream stays live');
+
+  req.emit('close');
+});