@panphora/clayjs 1.1.0 → 1.3.0

package/src/sync/live-sync.js

@@ -40,12 +40,17 @@ import Mutation from "../lib/mutation.js";
 import { isSnapshotRemoved } from "../lib/region-policy.js";
 import { isEditMode } from "../core/is-edit-mode.js";
 import { mergeTagRecognizers } from "./merge-tags.js";
-import { serializeForSync, captureForComparisonAndDirty, captureSnapshot } from '../core/snapshot.js';
+import { serializeForSync, captureForComparisonAndDirty, captureSnapshot, originalSnapshotNode } from '../core/snapshot.js';
 import { isTabLocalRootAttr } from '../lib/root-attrs.js';
 import { protectPeerDoc, protectDiskDoc, activateIncomingDoc } from './splice-merge.js';
+import { presence } from './presence.js';
+// Side-effect import: the section-changed notice wires itself to
+// `clay:sync-applied`, which this file is the only dispatcher of.
+import './section-notice.js';
 import { hostMeta } from '../core/host-meta.js';
-import { recordEtag, seedEtag } from '../core/etag.js';
+import { recordEtag, seedEtag, lastSeenEtag } from '../core/etag.js';
 import { pageMaybeDirty, pauseGate, resumeGate } from '../lib/dirty-gate.js';
+import { SyncStream } from './stream.js';
 
 // The page just took a frame verified clean against its baseline, so it now IS
 // the file on disk. Both saved baselines move together from one capture: leaving
@@ -75,6 +80,12 @@ import { savePageThrottled, setLastSavedBaselines, setUnsavedChanges } from '../
  * One profile is chosen once and used for BOTH directions for the life of the page.
  * Letting send and receive decide independently is exactly the bug this replaces: a
  * client that posted to the spec address while streaming from the legacy one.
+ *
+ * Both stream addresses carry `client-id`, in the same kebab spelling as the rest of
+ * the query. It is the tab's own sender id — the one every outbound frame already
+ * carries — so a host that reads it at admission knows this connection by the value
+ * its frames arrive under, and can tell two tabs of one cookie-less guest apart. A
+ * host that does not read it ignores an unknown parameter.
  */
 const WIRE_PROFILES = {
   spec: {
@@ -82,8 +93,8 @@ const WIRE_PROFILES = {
     relayPath: '/_/sync',
     documentHeader: 'Document-URL',
     snapshotKey: 'snapshot',
-    streamPath: (href, lane, resumeId) =>
-      `/_/sync?document-url=${encodeURIComponent(href)}&lane=${lane}&resume-id=${resumeId}`,
+    streamPath: (href, lane, resumeId, clientId) =>
+      `/_/sync?document-url=${encodeURIComponent(href)}&lane=${lane}&resume-id=${resumeId}&client-id=${encodeURIComponent(clientId)}`,
   },
   // What every published clayjs speaks, and what hyperclayjs and the inline script in
   // every Collection dashboard hardcode. Hosts keep these addresses permanently.
@@ -92,8 +103,8 @@ const WIRE_PROFILES = {
     relayPath: '/_/live-sync/save',
     documentHeader: 'Page-URL',
     snapshotKey: 'html',
-    streamPath: (href, lane, resumeId) =>
-      `/_/live-sync/stream?page-url=${encodeURIComponent(href)}&lane=${lane}&resume-id=${resumeId}`,
+    streamPath: (href, lane, resumeId, clientId) =>
+      `/_/live-sync/stream?page-url=${encodeURIComponent(href)}&lane=${lane}&resume-id=${resumeId}&client-id=${encodeURIComponent(clientId)}`,
   },
 };
 
@@ -114,6 +125,15 @@ class LiveSync {
 
     this.debounceMs = 150;
     this.debounceTimer = null;
+
+    // The sync serialization of the clone the CURRENT save was captured from,
+    // held so the commit relay can pair the host's stamp with the content that
+    // stamp actually describes. Set at snapshot-ready, which fires before the
+    // save POST goes out, and consumed by _relayCommit when the response lands.
+    // Never reconstructed from lastHtml: that is the last relay that COMPLETED,
+    // which lags the save whenever the response beats the 150ms debounce, and
+    // pairing a fresh stamp with older bytes is the one thing spec §10 forbids.
+    this._savedSnapshot = null;
     this._sendInFlight = false;
     this._queuedSend = null;
 
@@ -155,13 +175,22 @@ class LiveSync {
     this._pendingHtml = null;
     this._pendingSeq = null;
     this._pendingIdentityMap = null;
+    // The stamp a pending frame carries, adopted only if that frame applies
+    // cleanly. It rides in the slot beside the bytes it describes so the two can
+    // never be separated, which is the whole rule (§6, and §22 of the plan).
+    this._pendingEtag = null;
+    // Who the server says sent the pending frame, `{ id, name }`. Rides in the
+    // slot for the same reason the stamp does: it describes these bytes and
+    // nothing else, so a newer frame replacing them takes its author with it.
+    // Reported on `clay:sync-applied` once the frame has actually applied.
+    this._pendingBy = null;
     this._morphInFlight = false;
     this._rafHandle = null;
 
     // Disk-sourced external changes (htmlclay watcher content) get their own
     // one-deep slot so a peer frame arriving in the same window can't
     // displace them. Drained in seq order alongside the peer slot.
-    this._pendingExternal = null;   // { html, seq, saveEpoch }
+    this._pendingExternal = null;   // { html, seq, saveEpoch, etag }
 
     // Newest external-change seq accepted for apply. Replayed or reordered
     // disk frames (and their fetch fallbacks) are dropped against this.
@@ -274,6 +303,7 @@ class LiveSync {
     // so mint a fresh resume id — this stream must not resume the previous one.
     this.lastHtml = null;
     this._lastIdentityMap = null;
+    this._savedSnapshot = null;
     this._applyGen++;
     this.lastSeenSeq = 0;
     this._lastExternalSeq = 0;
@@ -295,7 +325,10 @@ class LiveSync {
     // snapshot listener would never fire — skip registering it.
     if (this.lane === 'live') {
       this.listenForSnapshots();
-      this._saveSavedHandler = () => { this._saveEpoch++; };
+      this._saveSavedHandler = () => {
+        this._saveEpoch++;
+        this._relayCommit();
+      };
       document.addEventListener('clay:save-saved', this._saveSavedHandler);
     }
   }
@@ -310,6 +343,10 @@ class LiveSync {
       this.sse = null;
     }
 
+    // Nothing feeds the roster once the stream is gone, so leaving the stack up
+    // would show a list of people who may all have left.
+    presence.clear();
+
     if (this._snapshotHandler) {
       document.removeEventListener('clay:snapshot-ready', this._snapshotHandler);
       this._snapshotHandler = null;
@@ -333,6 +370,7 @@ class LiveSync {
     this._pendingHtml = null;
     this._pendingSeq = null;
     this._pendingIdentityMap = null;
+    this._pendingBy = null;
     this._pendingExternal = null;
     clearTimeout(this._holdRetryPeer);
     clearTimeout(this._holdRetryExt);
@@ -365,33 +403,25 @@ class LiveSync {
     const map = {};
     if (!liveRoot || !cloneRoot) return map;
 
-    const visit = (live, clone, path) => {
-      let id = this.liveWeakMap.get(live);
-      if (!id) {
-        id = this._mintId();
-        this.liveWeakMap.set(live, id);
+    const visit = (clone, path) => {
+      const live = originalSnapshotNode(clone);
+      if (live) {
+        let id = this.liveWeakMap.get(live);
+        if (!id) {
+          id = this._mintId();
+          this.liveWeakMap.set(live, id);
+        }
+        map[path] = id;
       }
-      map[path] = id;
 
-      const liveKids = [];
-      for (const c of live.children) {
-        if (!isSnapshotRemoved(c)) liveKids.push(c);
-      }
       const cloneKids = clone.children;
 
-      if (liveKids.length !== cloneKids.length) {
-        this._log(
-          `identity map: subtree skipped at "${path}" (live=${liveKids.length}, clone=${cloneKids.length})`
-        );
-        return;
-      }
-
-      for (let i = 0; i < liveKids.length; i++) {
-        visit(liveKids[i], cloneKids[i], path === '' ? String(i) : `${path}.${i}`);
+      for (let i = 0; i < cloneKids.length; i++) {
+        visit(cloneKids[i], path === '' ? String(i) : `${path}.${i}`);
       }
     };
 
-    visit(liveRoot, cloneRoot, '');
+    visit(cloneRoot, '');
     return map;
   }
 
@@ -494,7 +524,11 @@ class LiveSync {
   _resolveProfile() {
     if (!this._profilePromise) {
       this._profilePromise = hostMeta()
-        .then((meta) => (meta?.extensions?.includes('sync') ? WIRE_PROFILES.spec : WIRE_PROFILES.legacy))
+        .then((meta) => {
+          const extensions = meta?.extensions || [];
+          this._sharedSync = extensions.includes('sync') && extensions.includes('sync-worker') && !extensions.includes('presence');
+          return extensions.includes('sync') ? WIRE_PROFILES.spec : WIRE_PROFILES.legacy;
+        })
         .catch(() => WIRE_PROFILES.legacy)
         .then((profile) => {
           this._profile = profile;
@@ -534,31 +568,32 @@ class LiveSync {
   }
 
   /**
-   * Take a stamp that arrived with no document (spec §6).
+   * Drop a stamp that arrived with no document (spec §6).
    *
-   * The host sends one whenever the file on disk changes, because an editing tab
-   * never receives the saved document itself: that lane is for viewers, and
-   * pushing a saved document onto an editor would replace work in progress.
+   * ⚠️ This used to TAKE it, and taking it was wrong. A stamp says "disk is at this
+   * version"; adopting it says "and I hold those bytes". Only the second claim
+   * makes the next save safe, and a frame with no content is no evidence for it.
    *
-   * Taking it is what makes live sync and the conflict check agree. An editor
-   * whose peer frames are merging is already looking at the other tab's content,
-   * so refusing its next save would be a conflict about nothing.
+   * The race is real and it loses work. A peer's save and that peer's snapshot
+   * relay are two concurrent requests, so a stamp travelling on its own can arrive
+   * first. This tab would record it while its DOM still held the older content,
+   * and its next save would then pass If-Match and overwrite the save it had never
+   * received. The hold flags cannot cover that: a lane holds when an incoming
+   * change could NOT be merged, not when one has yet to arrive.
    *
-   * But only while this tab is in step. A held lane means live sync saw an
-   * incoming change, could not merge it into an unsaved local edit, and kept this
-   * tab's version instead, so the DOM here is knowingly missing what disk holds.
-   * Taking the new stamp there would let this tab's next save replace that change
-   * with nobody seeing it. That is the one loss live sync cannot prevent on its
-   * own: a held tab "converges through its own next save", and that convergence
-   * IS the overwrite. Refusing the stamp turns it into a conflict somebody is
-   * told about.
+   * So a stamp now rides on the snapshot the saving tab relays after its save
+   * returns, and `_doApplyUpdate` records it only once that content has merged.
+   * Nothing sends a bare stamp any more — hyperclay's was deleted, and it had
+   * never reached anyone, because the relay library refuses a payload with no
+   * document in it. This stays as the rule rather than as compatibility: if some
+   * host does send one, dropping it is correct.
    *
    * @param {Object} data - The decoded frame
-   * @returns {boolean} True when this was a stamp frame and nothing should morph
+   * @returns {boolean} True when this was a stamp-only frame and nothing should morph
    */
   _applyEtagFrame(data) {
     if (typeof data.etag !== 'string' || typeof data.html === 'string') return false;
-    if (!this._heldLive && !this._heldExt) recordEtag(data.etag);
+    this._log('Dropping a stamp that arrived with no document: nothing proves this tab holds those bytes');
     return true;
   }
 
@@ -572,10 +607,14 @@ class LiveSync {
     // Whichever wire discovery selected. start() does not call connect() until the
     // profile is known, so this is never null on the normal path.
     const profile = this._profile || WIRE_PROFILES.legacy;
-    const path = profile.streamPath(window.location.href, this.lane, this.resumeId);
+    const path = profile.streamPath(window.location.href, this.lane, this.resumeId, this.clientId);
     // Resolved against the real origin: a <base href> in the authored document
     // would otherwise point the sync stream at an origin the document chose.
-    this.sse = new EventSource(new URL(path, window.location.origin).href);
+    this.sse = new SyncStream(new URL(path, window.location.origin).href, {
+      shared: this._sharedSync,
+      documentURL: window.location.href,
+      lane: this.lane,
+    });
 
     this.sse.onopen = () => {
       console.log('[LiveSync] Connected');
@@ -610,6 +649,21 @@ class LiveSync {
       });
     });
 
+    // The roster is a NAMED event for the same reason the cursor frame is: a tab
+    // with no listener for it never sees a bare data line, so every published
+    // client is counted in the roster without being sent one. The frame is
+    // handed on untouched — who is named is the host's decision, taken per
+    // recipient from that recipient's own access, and nothing here can widen it.
+    this.sse.addEventListener('presence', (event) => {
+      let data;
+      try {
+        data = JSON.parse(event.data);
+      } catch {
+        return;
+      }
+      presence.update(data);
+    });
+
     this.sse.onmessage = (event) => {
       const data = JSON.parse(event.data);
 
@@ -665,9 +719,21 @@ class LiveSync {
         return;
       }
 
+      const etag = typeof data.etag === 'string' && data.etag ? data.etag : null;
+
+      // The common case, and it costs nothing: a peer saved bytes this tab has
+      // already applied, so the frame's only news is the stamp. Taking it without
+      // a morph is exactly as safe as taking it after one, because the baseline
+      // being equal IS the proof that this tab holds those bytes.
+      if (etag && html === this.lastHtml) {
+        this._log(`Taking the stamp from a peer save of content already applied (seq=${seq})`);
+        recordEtag(etag);
+        return;
+      }
+
       this._log(`Received update from: ${sender} (my clientId: ${this.clientId}, seq=${seq})`);
-      this.applyUpdate(html, seq, identityMap);
-      if (this.onUpdate) this.onUpdate({ html, sender, seq, identityMap });
+      this.applyUpdate(html, seq, identityMap, etag, data.by);
+      if (this.onUpdate) this.onUpdate({ html, sender, seq, identityMap, etag });
     };
 
     // Native EventSource auto-reconnects on transient errors
@@ -704,6 +770,12 @@ class LiveSync {
       this._log('snapshot-ready received, preparing to send');
       const html = serializeForSync(clone);
       const identityMap = this._buildIdentityMap(document.documentElement, clone);
+
+      // The save that follows this capture stores these bytes, so this is the
+      // content its stamp will describe. Held for _relayCommit, and overwritten
+      // by the next capture, so it always names the save currently in flight.
+      this._savedSnapshot = { html, identityMap };
+
       this.sendUpdate(html, identityMap);
     };
 
@@ -750,6 +822,77 @@ class LiveSync {
     this._postUpdate(queued.html, queued.identityMap);
   }
 
+  /**
+   * Tell the other editors what this tab's save stored, and under which stamp.
+   *
+   * Runs on clay:save-saved, by which point the save response has already been
+   * recorded, so `lastSeenEtag()` is the stamp for the bytes that just landed.
+   *
+   * The content is `lastHtml`, the snapshot this tab most recently relayed, which
+   * is the state the save was taken from: the save pipeline dispatches
+   * clay:snapshot-ready on its way to capturing what to send, so that relay has
+   * already gone out. Re-sending those same bytes is not redundant, because the
+   * stamp is the new information and a stamp may never travel without the content
+   * it describes. A receiver whose baseline already matches takes the stamp and
+   * skips the morph.
+   */
+  _relayCommit() {
+    // Holding a stamp is the whole condition. It is set only from a save response
+    // that carried one, and a host that does not do conditional saves returns
+    // none, so this is the same test as "the host stamps what it stores" without
+    // a second flag that would have to be reached through discovery to exercise.
+    const etag = lastSeenEtag();
+    if (!etag) return;
+    if (this.isDestroyed || this.isPaused) return;
+
+    // The content this save stored, captured with it. Consumed rather than left
+    // behind, so a save-saved with no capture of its own can never reuse an
+    // older save's bytes under a newer stamp.
+    const pending = this._savedSnapshot;
+    this._savedSnapshot = null;
+
+    // No captured snapshot means nothing here knows which bytes this stamp
+    // describes, and §10 is explicit that a stamp must never travel on its own.
+    // Staying silent costs the other editors one refusal they recover from;
+    // guessing costs somebody their work.
+    if (!pending || typeof pending.html !== 'string') return;
+
+    this._postCommit(pending.html, etag, pending.identityMap);
+  }
+
+  /**
+   * Post a snapshot whose point is the stamp attached to it.
+   *
+   * Deliberately not `_postUpdate`: that one returns early when the html matches
+   * `lastHtml`, and the whole point here is that the stamp is the new information
+   * even when the bytes are not. It also does not touch `lastHtml` or the
+   * single-flight queue, because it must not displace a real snapshot waiting to
+   * go out. It carries the identityMap captured with these bytes, so a receiver
+   * that morphs on this frame pairs elements the same way it would on the
+   * ordinary relay of the same content.
+   */
+  _postCommit(html, etag, identityMap) {
+    const profile = this._profile;
+    if (!profile) return;
+    fetch(new URL(profile.relayPath, window.location.origin).href, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        [profile.documentHeader]: window.location.href,
+      },
+      body: JSON.stringify({
+        [profile.snapshotKey]: html,
+        sender: this.clientId,
+        identityMap,
+        etag
+      })
+    }).catch(err => {
+      // Losing this costs the other editors one spurious refusal on their next
+      // save, which they recover from. It is not worth surfacing as an error.
+      this._log('Commit relay failed: ' + (err && err.message));
+    });
+  }
+
   _postUpdate(html, identityMap) {
     // Skip if unchanged
     if (html === this.lastHtml) {
@@ -817,7 +960,7 @@ class LiveSync {
     const info = data.data;
     if (info && info.kind === 'external-change') {
       if (typeof info.html === 'string') {
-        this._enqueueExternal(info.html, data.seq);
+        this._enqueueExternal(info.html, data.seq, info.etag, info.by);
       } else {
         this._fetchExternalChange(data.seq);
       }
@@ -830,7 +973,7 @@ class LiveSync {
     return false;
   }
 
-  _enqueueExternal(html, seq) {
+  _enqueueExternal(html, seq, etag, by) {
     if (typeof seq === 'number') {
       if (seq <= this._lastExternalSeq) {
         this._log(`Dropping replayed external change: seq=${seq}`);
@@ -838,7 +981,17 @@ class LiveSync {
       }
       this._lastExternalSeq = seq;
     }
-    this._pendingExternal = { html, seq, saveEpoch: this._saveEpoch };
+    this._pendingExternal = {
+      html,
+      seq,
+      saveEpoch: this._saveEpoch,
+      etag: typeof etag === 'string' && etag ? etag : null,
+      // Carried for the same reason the stamp is, and null on every disk frame
+      // today: hyperclay stamps an author on the two live relays and nowhere
+      // else, so a change that arrived from the filesystem has no author to
+      // name. The slot carries it so a host that does stamp one is believed.
+      by: by ?? null,
+    };
     this._scheduleNextFrame();
   }
 
@@ -865,6 +1018,7 @@ class LiveSync {
    */
   _fetchServedDocument(seq, { attempt = 0, repair = false } = {}) {
     const epoch = this._saveEpoch;
+    if (repair && typeof seq !== 'number') seq = this._lastExternalSeq;
     fetch(new URL(window.location.href), { cache: 'no-store' })
       .then((response) => (response.ok ? response.text() : null))
       .then((html) => {
@@ -875,7 +1029,7 @@ class LiveSync {
           // said replay cannot fix this page, so if the newer fetch fails there is
           // nothing else coming. Refetch rather than drop the only repair.
           if (repair && attempt < 3) {
-            this._fetchServedDocument(seq, { attempt: attempt + 1, repair });
+            this._fetchServedDocument(this._lastExternalSeq, { attempt: attempt + 1, repair });
           }
           return;
         }
@@ -889,7 +1043,11 @@ class LiveSync {
           }
           return;
         }
-        this._pendingExternal = { html, seq, saveEpoch: epoch };
+        // No stamp: this body came from a GET of the served page, which nobody
+        // stamped, so the apply leaves the held stamp alone and etag.js asks the
+        // host for a replacement. No author either, for the same reason — a GET
+        // answers what disk holds, not who put it there.
+        this._pendingExternal = { html, seq, saveEpoch: epoch, etag: null, by: null };
         this._scheduleNextFrame();
       })
       .catch((err) => {
@@ -916,12 +1074,19 @@ class LiveSync {
    * @param {string} html - Full document HTML
    * @param {number} [seq] - Optional monotonic seq from the server
    * @param {Object} [identityMap] - Optional element-identity map from sender
+   * @param {string} [etag] - Optional version stamp for these bytes
+   * @param {Object} [by] - Optional `{ id, name }` author stamp for these bytes
    */
-  applyUpdate(html, seq, identityMap) {
+  applyUpdate(html, seq, identityMap, etag, by) {
     if (this.isDestroyed) return;
     this._pendingHtml = html;
     this._pendingSeq = seq;
     this._pendingIdentityMap = identityMap;
+    // A newer frame replacing this one takes its stamp with it, and that is
+    // correct: the stamp belongs to bytes that are no longer what will apply.
+    // Losing it costs one honest 412 later, which is the safe direction.
+    this._pendingEtag = etag ?? null;
+    this._pendingBy = by ?? null;
     this._scheduleNextFrame();
   }
 
@@ -979,7 +1144,7 @@ class LiveSync {
       } else {
         this._morphInFlight = true;
         try {
-          await this._doApplyExternal(ext.html, ext.seq);
+          await this._doApplyExternal(ext.html, ext.seq, ext.etag, ext.by);
         } catch (err) {
           console.error('[LiveSync] applyExternal failed:', err);
         } finally {
@@ -990,14 +1155,18 @@ class LiveSync {
       const html = this._pendingHtml;
       const seq = this._pendingSeq;
       const identityMap = this._pendingIdentityMap;
+      const etag = this._pendingEtag;
+      const by = this._pendingBy;
       this._pendingHtml = null;
       this._pendingSeq = null;
       this._pendingIdentityMap = null;
+      this._pendingEtag = null;
+      this._pendingBy = null;
       if (html == null) return;
 
       this._morphInFlight = true;
       try {
-        await this._doApplyUpdate(html, seq, identityMap);
+        await this._doApplyUpdate(html, seq, identityMap, etag, by);
       } catch (err) {
         console.error('[LiveSync] applyUpdate failed:', err);
       } finally {
@@ -1036,9 +1205,11 @@ class LiveSync {
    * @param {string} html
    * @param {number} [seq]
    * @param {Object} [identityMap]
+   * @param {string} [etag]
+   * @param {Object} [by]
    * @returns {Promise<void>}
    */
-  async _doApplyUpdate(html, seq, identityMap) {
+  async _doApplyUpdate(html, seq, identityMap, etag, by = null) {
     this._log('applyUpdate - pausing mutations and morphing');
     this.isPaused = true;
 
@@ -1126,6 +1297,7 @@ class LiveSync {
             this._pendingHtml = html;
             this._pendingSeq = seq;
             this._pendingIdentityMap = identityMap;
+            this._pendingBy = by;
             this._scheduleNextFrame();
           }, 3000);
           return;
@@ -1135,6 +1307,18 @@ class LiveSync {
 
       this._setHeld('live', false);
 
+      // The frame merged, so this tab may take its stamp — but not yet. Adopting
+      // the stamp and applying the bytes have to be the same event, and they only
+      // are once the apply has actually happened. The morph below is awaited and
+      // can reject, and a stamp recorded before it would sit on the old DOM with
+      // nothing to undo it, so the next save would pass If-Match and replace a
+      // version this tab never received. It is recorded after the await, beside
+      // `lastHtml`, on the one path where the bytes definitely landed.
+      //
+      // The hold path above returns before that point, deliberately. A held tab is
+      // knowingly missing what disk holds, and a stamp there would let its next
+      // save replace that change with nobody told.
+
       // Morph entire document. We MUST await — HyperMorph.morph returns a
       // Promise when `scripts: { handle: true }` needs to wait for external
       // scripts to load. If we don't await, Mutation.resume() fires before
@@ -1190,6 +1374,13 @@ class LiveSync {
           : null;
       this._applyGen++;
 
+      // The stamp of section 6, taken now that the bytes it describes are the
+      // bytes this tab is holding. Same line of reasoning as lastHtml directly
+      // above, and deliberately the same moment: the two claims a page makes
+      // when it adopts a stamp are "the host stores this version" and "I hold
+      // it", and only the second one is this tab's to make.
+      if (typeof etag === 'string' && etag) recordEtag(etag);
+
       // Cross-lane baseline: the DOM now holds this frame's content, but the
       // DISK baseline (lastSavedContents) still describes pre-frame state. A
       // later dirty disk apply diffing against that stale baseline would
@@ -1214,8 +1405,13 @@ class LiveSync {
       // `source` is what lets a listener tell the two apply paths apart. clay.wire
       // waits for a DISK frame to call an agent's write landed, and another tab's
       // edit arriving first would otherwise report the wrong bytes as delivered.
+      //
+      // `by` is the server's answer about who sent these bytes, and it is on the
+      // event rather than on the frame's arrival for one reason: a frame that held
+      // returns above without reaching here, so nothing can name an author for a
+      // change this tab never took. Null on every frame the host did not stamp.
       document.dispatchEvent(new CustomEvent('clay:sync-applied', {
-        detail: { seq, source: 'peer' }
+        detail: { seq, source: 'peer', by: by || null }
       }));
     } finally {
       this._log('applyUpdate - morph complete, resuming mutations');
@@ -1252,7 +1448,7 @@ class LiveSync {
    * holds or a later dirty peer apply misclassifies this frame's content as
    * local edits.
    */
-  async _doApplyExternal(html, seq) {
+  async _doApplyExternal(html, seq, etag = null, by = null) {
     this._log(`applyExternal - external disk change (seq=${seq})`);
     this.isPaused = true;
 
@@ -1292,7 +1488,7 @@ class LiveSync {
           this._holdRetryExt = setTimeout(() => {
             this._holdRetryExt = null;
             if (this.isDestroyed || this._pendingExternal != null) return;
-            this._pendingExternal = { html, seq, saveEpoch: epochAtHold };
+            this._pendingExternal = { html, seq, saveEpoch: epochAtHold, etag, by };
             this._scheduleNextFrame();
           }, 3000);
           return;
@@ -1329,6 +1525,17 @@ class LiveSync {
 
       window.scrollTo(scrollX, scrollY);
 
+      // The stamp of section 6, adopted here and nowhere else: this is the moment
+      // the bytes it describes reached this tab. It is taken on the retained-roots
+      // path too, because a merge still incorporates the disk bytes, and the
+      // convergence save at the bottom needs a stamp the host will accept or the
+      // merge is refused and lost.
+      //
+      // A frame with no stamp (an older host, or the content-less fetch fallback,
+      // which serves bytes nobody stamped) leaves this alone, and the listener in
+      // etag.js falls back to asking the host.
+      if (typeof etag === 'string' && etag) recordEtag(etag);
+
       if (this.lane === 'live' && retainedRoots === 0 && !pageMaybeDirty()) {
         // Clean apply: the DOM now IS the disk state, so a local comparison
         // capture of it is the truthful baseline. The next no-op save skips,
@@ -1350,7 +1557,12 @@ class LiveSync {
       }
 
       document.dispatchEvent(new CustomEvent('clay:sync-applied', {
-        detail: { seq, source: 'disk' }
+        detail: {
+          seq,
+          source: 'disk',
+          etag: typeof etag === 'string' && etag ? etag : null,
+          by: by || null,
+        }
       }));
     } finally {
       this._log('applyExternal - morph complete, resuming mutations');