@cotal-ai/web 0.18.0 → 0.20.0

package/dist/web/event-order.js

@@ -0,0 +1,283 @@
+// The bootstrap ordering this surface needs because it taps live BEFORE it reads history.
+//
+// THE RACE IS THIS PAGE'S, NOT A HYPOTHETICAL. `app.js` opens the SSE feed and only then calls
+// `refresh()`, so `onMessage` is already appending live traffic while the backfill fetch is still in
+// flight. For ordinary chat that is harmless: entries carry `ts`, the feed is a window, and a
+// duplicate is caught by message id. For an event frame it is not harmless, because a frame's
+// position in its stream is `seq`, and `seq` is the only thing that can tell a reader that a frame
+// is MISSING. Message-id dedupe cannot: two ids are equal or they are not, which says nothing about
+// what belongs between them.
+//
+// SO THE CONSUMER HAS TO IMPOSE ITS OWN PHASE BOUNDARY. The transport arms the watermark, goes live,
+// and only then surfaces retained history, so a live frame at `seq` 1003 can legitimately be the
+// FIRST frame this page ever sees, ahead of the retained 1000-1002. Two rules follow, and both are
+// the opposite of what a first-arrival reading would do:
+//
+//   · The baseline is the MINIMUM of the settled history batch, not the first frame observed.
+//     Baselining on arrival makes the entire backfill look like it ran backwards.
+//   · Gap checking is not armed until the boundary passes. Armed earlier, the same backfill reads as
+//     a hole between 1003 and 1000.
+//
+// WHAT A BASELINE ABOVE THE FIRST SEQUENCE MEANS, AND WHAT IT DOES NOT. The chat stream caps per
+// subject, so a reader that arrives late finds the earliest retained frame at some `seq` N > 1. That
+// is ordinary retention and NOT a fault: the chain is marked prefix-incomplete and applied forward.
+// A discontinuity AFTER the baseline is the fault, and the two must never be reported as one thing,
+// because the first is what always happens and the second is what must never be ignored.
+//
+// DETECTION IS NOT RECOVERY, AND A DETECTED GAP STILL DRAWS THE FRAME. A gap note is surfaced and
+// the frame is emitted anyway. Holding it back until the missing predecessor turns up would hold it
+// forever when the predecessor is genuinely gone, which converts a visible gap into a silent loss:
+// the exact trade this lane exists to refuse. `next` also advances past the hole, so one lost frame
+// reports once instead of reporting on every frame that follows it.
+//
+// FIRST SEQUENCE. The emitter publishes its first frame at `seq` 1 (`firstSeq` is the WAL frontier
+// plus one, from a zero frontier), while the frame validator admits any non-negative safe integer.
+// "Complete from origin" therefore keys on `<= 1` and not on `=== 1`, so a `seq` 0 frame, which is
+// structurally valid and which no emitter produces, cannot be reported as an evicted prefix.
+//
+// NOT ORDERED, DELIBERATELY: anything that is not a frame carrying a usable `seq`. Chat, presence,
+// DMs and a malformed frame all pass straight through in arrival order. A machine that held a frame
+// it could not sequence would either hold it forever or invent a gap around it, and delaying chat
+// behind a frame's backfill would make this file a latency bug for the traffic it does not own.
+(() => {
+  const KIND = "ag-ui.frame";
+  /** The first `seq` any emitter publishes. A baseline at or below this is complete from origin. */
+  const FIRST_SEQ = 1;
+
+  const isSeq = (v) => Number.isSafeInteger(v) && v >= 0;
+
+  /** The frame part an entry carries, or `undefined`. A ROUTING question, so it never throws.
+   *
+   *  Accepts a feed entry (`{mode, channel, msg}`, the all-activity shape) or a bare message (the
+   *  selected-channel shape), because both merge sites run this race and a machine that only
+   *  understood one of them would leave the other unordered. */
+  const frameOf = (entry) => {
+    try {
+      const msg = entry && typeof entry === "object" ? entry.msg || entry : undefined;
+      const parts = msg && msg.parts;
+      if (!Array.isArray(parts)) return undefined;
+      for (const p of parts)
+        if (p && typeof p === "object" && p.kind === KIND && isSeq(p.seq)) return p;
+      return undefined;
+    } catch {
+      return undefined;
+    }
+  };
+
+  /** The chain a frame belongs to: `(from.id, epoch, threadId)`.
+   *
+   *  EPOCH IS IN THE KEY BECAUSE `runId` CANNOT DISCRIMINATE. Two writers pick run ids and sequences
+   *  independently, so their `(runId, seq)` pairs collide by construction; `epoch` is what makes one
+   *  writer's stream its own. A JSON array is the delimiter rather than a joining character, because
+   *  a thread id is a producer-supplied string and any separator chosen here could appear inside it,
+   *  which would fuse two chains into one and hide a gap in the merge. */
+  const chainKey = (entry, frame) => {
+    const msg = entry && typeof entry === "object" ? entry.msg || entry : undefined;
+    const from = msg && msg.from;
+    return JSON.stringify([
+      (from && typeof from.id === "string" ? from.id : null),
+      typeof frame.epoch === "string" ? frame.epoch : null,
+      typeof frame.threadId === "string" ? frame.threadId : null,
+    ]);
+  };
+
+  /** A two-phase shape-B bootstrap. One instance per bootstrap: a reconnect re-runs both phases. */
+  const create = () => {
+    /** key -> {baseline, next, prefixIncomplete, faulted, seen:Set<seq>} */
+    const chains = new Map();
+    /** Live frames arriving before the boundary, in arrival order. */
+    const pending = [];
+    let settled = false;
+
+    const chainOf = (key) => {
+      let c = chains.get(key);
+      if (!c) {
+        c = { baseline: undefined, next: undefined, prefixIncomplete: false, faulted: false, released: false, seen: new Set() };
+        chains.set(key, c);
+      }
+      return c;
+    };
+
+    /** Admit one frame against an armed chain. Returns the notes it produced.
+     *
+     *  `straddle` marks the ONE frame per chain whose predecessor lies on the other side of the
+     *  bootstrap seam, and it changes what a hole MEANS rather than merely how it is worded. See
+     *  {@link STRADDLE} below. */
+    const admit = (c, key, seq, straddle) => {
+      const notes = [];
+      if (c.seen.has(seq)) return { emit: false, notes };
+      c.seen.add(seq);
+      if (seq > c.next) {
+        // Both ends are named either way, so a reader sees WHAT is missing rather than only that
+        // something is.
+        const hole = { key, expected: c.next, got: seq, missing: seq - c.next };
+        if (straddle) {
+          // STRADDLE: THE ONE HOLE THIS PAGE CANNOT ATTRIBUTE, and calling it a fault was a measured
+          // false positive on healthy traffic.
+          //
+          // The two halves of the bootstrap are two independent reads with no shared cut: a live
+          // subscription, and a history request. Nothing makes the point the read was served equal
+          // the point the tap began delivering, and on this page the fetch is issued before the tap
+          // is even open. So a frame published inside that window is in NEITHER half, and the first
+          // buffered frame of a chain can therefore sit above the retained range's top by more than
+          // one with nothing lost by the broker at all. Reported as a fault, it latched `faulted`
+          // forever on a stream that was fine, and the frame that filled the hole a moment later did
+          // not clear it.
+          //
+          // A fault that fires on healthy traffic is worse than no fault at all, because it teaches
+          // the reader to ignore the one signal that matters. So this is reported as its own kind,
+          // named as unconfirmed on the surface, and it does NOT set `faulted`. What it is not is
+          // silence: the page says it could not establish the join, rather than saying nothing was
+          // missing.
+          //
+          // ONLY THE FIRST RELEASED FRAME OF A CHAIN GETS THIS TREATMENT. Every later buffered frame
+          // arrived through the SAME tap as the one before it, and a subscription delivers a subject
+          // in order, so a number missing BETWEEN two buffered frames was never delivered while the
+          // page was listening. That is a real loss and takes the hard path below, exactly like a
+          // post-boundary hole.
+          notes.push({ type: "boundary-hole", ...hole });
+        } else {
+          notes.push({ type: "gap", ...hole });
+          c.faulted = true;
+        }
+      }
+      if (seq >= c.next) c.next = seq + 1;
+      return { emit: true, notes };
+    };
+
+    return {
+      /** A live arrival. Before the boundary a frame is HELD; everything else always passes. */
+      live(entry) {
+        const f = frameOf(entry);
+        if (!f) return { emit: [entry], held: false, notes: [] };
+        if (!settled) {
+          pending.push(entry);
+          return { emit: [], held: true, notes: [] };
+        }
+        const key = chainKey(entry, f);
+        const c = chainOf(key);
+        if (c.next === undefined) {
+          // First frame for a chain that the settled history did not mention: this arrival is the
+          // baseline, which is sound now only because the boundary has passed.
+          c.baseline = f.seq;
+          c.next = f.seq;
+          c.prefixIncomplete = f.seq > FIRST_SEQ;
+        }
+        const r = admit(c, key, f.seq);
+        return { emit: r.emit ? [entry] : [], held: false, notes: r.notes };
+      },
+
+      /** THE PHASE BOUNDARY: the history batch has settled.
+       *
+       *  Returns the merged feed to render, oldest-first: the batch in the order the server sorted
+       *  it, then every held live frame that the batch did not already carry, released in `seq`
+       *  order per chain. The batch is the baseline source, so a live frame that ran ahead of it
+       *  lands after its own retained predecessors instead of before them. */
+      backfill(batch) {
+        const notes = [];
+        const rows = Array.isArray(batch) ? batch.slice() : [];
+
+        // Phase one: the batch establishes each chain's baseline. Taken as a MINIMUM over the batch
+        // rather than from its first row, because the server sorts the union by `ts` across channels
+        // and a frame's `ts` is not its `seq`.
+        for (const row of rows) {
+          const f = frameOf(row);
+          if (!f) continue;
+          const c = chainOf(chainKey(row, f));
+          if (c.baseline === undefined || f.seq < c.baseline) c.baseline = f.seq;
+          c.seen.add(f.seq);
+        }
+        for (const [key, c] of chains) {
+          if (c.baseline === undefined) continue;
+          let highest = c.baseline;
+          for (const s of c.seen) if (s > highest) highest = s;
+          c.next = highest + 1;
+          c.prefixIncomplete = c.baseline > FIRST_SEQ;
+          if (c.prefixIncomplete) notes.push({ type: "prefix-incomplete", key, baseline: c.baseline });
+          // THE RETAINED RANGE IS AUDITED, NOT JUST ITS ENDS. Recording the minimum, the maximum and
+          // the set is enough to place the baseline and to dedupe, and it is NOT enough to notice that
+          // the middle is missing: a batch of 1, 2, 5 has a baseline of 1 and a frontier of 6, and
+          // every later frame follows contiguously, so the chain reads healthy forever while two
+          // frames are gone. A discontinuity that exists only inside retained history is still a
+          // discontinuity after the baseline, and it is the one kind no live arrival will ever
+          // reveal, because nothing after it is out of order.
+          //
+          // Reported as runs rather than per missing number, so losing a thousand frames is one note
+          // naming both ends instead of a thousand notes burying it. The walk stops at `highest`,
+          // which is in the set by construction, so a run always terminates on a present frame.
+          let run = 0;
+          for (let s = c.baseline + 1; s <= highest; s++) {
+            if (!c.seen.has(s)) {
+              run++;
+              continue;
+            }
+            if (run > 0) {
+              notes.push({ type: "gap", key, expected: s - run, got: s, missing: run });
+              c.faulted = true;
+              run = 0;
+            }
+          }
+        }
+
+        // Phase two: release what the tap delivered while the fetch was in flight. Sorted by `seq`
+        // within a chain and stable across chains, so a chain's frames are contiguous with the
+        // retained range they follow.
+        const heldFrames = pending
+          .map((entry, i) => ({ entry, frame: frameOf(entry), i }))
+          .filter((h) => h.frame !== undefined);
+        heldFrames.sort((a, b) => (a.frame.seq - b.frame.seq) || (a.i - b.i));
+
+        for (const h of heldFrames) {
+          const key = chainKey(h.entry, h.frame);
+          const c = chainOf(key);
+          if (c.next === undefined) {
+            // No retained frame for this chain, so the earliest BUFFERED frame is the baseline. This
+            // is the empty-history arm, and it is why the buffer is sorted before it is walked.
+            c.baseline = h.frame.seq;
+            c.next = h.frame.seq;
+            c.prefixIncomplete = h.frame.seq > FIRST_SEQ;
+            if (c.prefixIncomplete)
+              notes.push({ type: "prefix-incomplete", key, baseline: c.baseline });
+          }
+          // The seam is crossed once per chain: this frame's predecessor is retained history (or
+          // nothing), every later one's predecessor came through the same tap it did.
+          const straddle = !c.released;
+          c.released = true;
+          const r = admit(c, key, h.frame.seq, straddle);
+          for (const n of r.notes) notes.push(n);
+          if (r.emit) rows.push(h.entry);
+        }
+
+        pending.length = 0;
+        settled = true;
+        return { emit: rows, notes };
+      },
+
+      /** Whether the boundary has passed. Gap checking is armed only after it has. */
+      get settled() {
+        return settled;
+      },
+      /** Held-but-unreleased count. Zero after the boundary, by construction. */
+      get pendingCount() {
+        return pending.length;
+      },
+      /** A chain's observed state, for a surface that wants to mark it and for the suite. */
+      state(key) {
+        const c = chains.get(key);
+        return c === undefined
+          ? undefined
+          : {
+              baseline: c.baseline,
+              next: c.next,
+              prefixIncomplete: c.prefixIncomplete,
+              faulted: c.faulted,
+            };
+      },
+      get chainKeys() {
+        return [...chains.keys()];
+      },
+    };
+  };
+
+  window.COTAL_EVENT_ORDER = { KIND, FIRST_SEQ, frameOf, chainKey, create };
+})();

package/dist/web/graph.html

@@ -214,6 +214,8 @@
     <div class="hint" id="hint">click a node for detail · scroll to zoom · drag to pan</div>
 
     <script src="/harness.js"></script>
+    <script src="/parts.js"></script>
+    <script src="/agui-frame.js"></script>
     <script src="/graph.js"></script>
   </body>
 </html>

package/dist/web/graph.js

@@ -62,13 +62,18 @@
   const particles = [];
   const blooms = [];
   const recent = [];
-  const feed = { asOf: undefined, available: false }; // membership-feed freshness
+  // `available` is "there is a feed and it said something"; `unreadable` is "the last attempt to read
+  // it failed". They are independent, and `unreadable` is declared here rather than sprung into
+  // existence on first failure so the shape of the state is readable in one place.
+  const feed = { asOf: undefined, available: false, unreadable: false }; // membership-feed freshness
   const cam = { x: 0, y: 0, scale: 1, ready: false, user: false };
   const filter = { chat: true, unicast: true, anycast: true, window: 30, paused: false, hideOffline: true, hideEmpty: true };
   let W = 0, H = 0, DPR = 1, hover = null, sel = null, lastT = 0, alpha = 1;
 
   // ── utils ──
-  const partsText = (m) => (m.parts || []).map((p) => (p.kind === "text" ? p.text : JSON.stringify(p.data))).join(" ");
+  // Shared with app.js via parts.js (loaded before this file). It names a part kind it cannot
+  // draw instead of rendering it as the empty string, which read as "nothing arrived".
+  const partsText = (m) => window.COTAL_PARTS.partsToText(m.parts);
   const ease = (t) => (t < 0.5 ? 2 * t * t : 1 - (-2 * t + 2) ** 2 / 2);
   const esc = (s) => String(s ?? "").replace(/[&<>"]/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" }[c]));
   const shortId = (x) => (/^[A-Z2-7]{32,}$/.test(x) ? x.slice(0, 6) + "…" : x);
@@ -195,8 +200,12 @@
   function heatFanOut(channel, from) {
     for (const e of edges.values()) if (e.chan === channel && e.a !== from) e.heat = 1;
   }
-  function onMessage({ mode, senderId, msg }) {
+  function onMessage({ mode, senderId, channel, msg }) {
     if (!msg) return;
+    // Trust decided once (see app.js): the subject-derived channel replaces the payload claim,
+    // UNCONDITIONALLY. A guarded overwrite fails open on `inst`/`svc`, where there is no
+    // authoritative channel and the publisher's forged one would survive.
+    msg.channel = channel;
     const from = ensureAgent(senderId ? { id: senderId, name: msg.from?.name, role: msg.from?.role } : msg.from);
     if (from) { from.ts = now(); from.present = true; } // a live sender is a live presence (roster event may lag)
     // Visual gate: pause chip, mode filter, AND tab visibility. State (heat/recent/roster) always applies.
@@ -256,8 +265,13 @@
   }
 
   // ── membership (authoritative spokes) ──
+  // The server said it could not read membership. Kept separate from `available` rather than folded
+  // into it: they are different facts and the pill has to say which one.
+  function membershipUnreadable() { feed.unreadable = true; setFeed(); }
+
   function applyMembership(snap) {
     if (!snap) return;
+    feed.unreadable = false; // a snapshot arrived, whatever it contains
     feed.asOf = snap.asOf;
     feed.available = snap.asOf !== undefined || (Array.isArray(snap.members) && snap.members.length > 0);
     setFeed();
@@ -328,13 +342,24 @@
   // default) collapses a HUB with no VISIBLE member under the current filters — it reads the cached `h.empty`
   // (kept current by recomputeHubEmpty). So when `hide offline` is ON this
   // means "no ONLINE member"; when it's OFF a channel that still shows offline members keeps its hub — the two
-  // toggles don't fight (review-critic R2). Gated on `feed.available`: without the authoritative feed there
-  // are no membership edges, so every hub would read empty — we can't tell a quiet channel from an unknown
-  // one, so we don't hide. Reading the cached flag keeps isHidden(hub) O(1), not an all-edges scan per call.
+  // toggles don't fight (review-critic R2). Gated on the feed being AUTHORITATIVE: without the
+  // authoritative feed there are no membership edges, so every hub would read empty — we can't tell a
+  // quiet channel from an unknown one, so we don't hide. Reading the cached flag keeps isHidden(hub)
+  // O(1), not an all-edges scan per call.
   // Hiding suppresses node/spoke rendering, hit-testing, camera framing, and physics participation; the node
   // stays in the model, so toggling reveals it instantly.
+  //
+  // `feedAuthoritative()` rather than `feed.available` alone. Those came apart the moment the feed
+  // could report that it could not be READ: the last snapshot is still the last thing we KNEW, but it
+  // is no longer what IS, and `hide empty` asserts a hub has no member NOW. That is the gate's own
+  // stated reason applied to the case where we hold stale edges rather than none — otherwise the pill
+  // says "unreadable" while the page keeps acting on the reading it just disowned.
+  //
+  // The snapshot itself is deliberately NOT discarded: `asOf` and the spokes remain the honest record
+  // of the last successful read, which is true and worth showing. What stops is treating it as current.
+  const feedAuthoritative = () => feed.available && !feed.unreadable;
   const isHidden = (n) => n.kind === "hub"
-    ? filter.hideEmpty && feed.available && n.empty
+    ? filter.hideEmpty && feedAuthoritative() && n.empty
     : filter.hideOffline && isOffline(n);
   // Per-CHANNEL visibility of a membership spoke: hidden when `hide offline` is on AND this edge is offline
   // for its channel (durable-only, or the agent is offline) — so "hide offline" holds per channel, not just
@@ -522,7 +547,12 @@
     const el = $("feed"); if (!el) return;
     el.hidden = false;
     let cls, text;
-    if (!feed.available) { cls = "off"; text = "membership: traffic-only"; }
+    // UNREADABLE IS ITS OWN STATE, and it must be checked before `available`. "traffic-only" is a
+    // CLAIM ABOUT THE MESH — that no membership feed is being published — and it was being shown for
+    // a failed read, which is a claim about US. The operator's own viewer reported traffic-only
+    // against a mesh that had a feed, and nothing on the page could have revealed the difference.
+    if (feed.unreadable) { cls = "off"; text = "membership: unreadable"; }
+    else if (!feed.available) { cls = "off"; text = "membership: traffic-only"; }
     else { const age = feed.asOf ? now() - feed.asOf : Infinity; if (age < FEED_STALE_MS) { cls = ""; text = "membership: live"; } else { cls = "stale"; text = "membership: stale"; } }
     el.className = "pill" + (cls ? " " + cls : "");
     el.querySelector(".t").textContent = text;
@@ -657,14 +687,24 @@
   async function load() {
     const [meta, roster, chans, membership, activity, dmHist] = await Promise.all([
       fetch("/api/meta").then((r) => r.json()), fetch("/api/roster").then((r) => r.json()), fetch("/api/channels").then((r) => r.json()),
-      fetch("/api/membership").then((r) => r.json()).catch(() => ({ members: [] })),
+      // `.catch(() => ({members: []}))` here turned a failed fetch into an empty snapshot, which the
+      // pill then reported as "traffic-only" — the client half of the same defect the server had.
+      // A non-200 is not a snapshot either: `r.json()` on the refusal body would parse fine and
+      // arrive as data, so the status is checked before the body is trusted.
+      fetch("/api/membership")
+        .then((r) => (r.ok ? r.json() : { unreadable: true }))
+        .catch(() => ({ unreadable: true })),
       fetch("/api/activity?limit=400").then((r) => r.json()).catch(() => []), fetch("/api/dms?limit=400").then((r) => r.json()).catch(() => []),
     ]);
     $("space").textContent = "· " + meta.space;
     for (const c of chans) { const h = ensureHub(c.channel); h.msgs = c.messages || 0; h.desc = c.description || ""; h.deliveryClass = c.deliveryClass; h.replay = c.replay; h.replayWindow = c.replayWindow; }
     updateRoster(roster);
-    applyMembership(membership); // authoritative spokes BEFORE traffic seeding (no skeleton flicker)
-    for (const e of activity) { const m = e.msg; const a = m?.from?.id && agents.get(m.from.id); if (e.mode === "chat" && m?.channel && a) chatHit(a, m.channel, m.ts || now()); }
+    // authoritative spokes BEFORE traffic seeding (no skeleton flicker) — unless the read refused,
+    // in which case there are no spokes to draw and the pill has to say so rather than imply a mesh
+    // with no feed.
+    if (membership && membership.unreadable) membershipUnreadable();
+    else applyMembership(membership);
+    for (const e of activity) { const m = e.msg; if (m) m.channel = e.channel; const a = m?.from?.id && agents.get(m.from.id); if (e.mode === "chat" && m?.channel && a) chatHit(a, m.channel, m.ts || now()); }
     for (const m of dmHist) { const a = m.from?.id && agents.get(m.from.id), b = typeof m.to === "string" && agents.get(m.to); if (a && b && a !== b) dmHit(a, b, m.ts || now()); }
     // Seed the `recent` buffer from the activity backfill so the channel detail's "recently active" tags +
     // the "recent" section aren't empty until the first live SSE message arrives (norman).
@@ -678,7 +718,7 @@
     alpha = 1; for (let i = 0; i < 200; i++) physics(); // pre-warm to a settled layout
     const f = fitTarget(); cam.x = f.x; cam.y = f.y; cam.scale = f.scale;
   }
-  function connect() { const es = new EventSource("/feed"); es.onopen = () => setConn(true); es.onerror = () => setConn(false); es.addEventListener("roster", (e) => updateRoster(JSON.parse(e.data))); es.addEventListener("membership", (e) => applyMembership(JSON.parse(e.data))); es.addEventListener("message", (e) => onMessage(JSON.parse(e.data))); }
+  function connect() { const es = new EventSource("/feed"); es.onopen = () => setConn(true); es.onerror = () => setConn(false); es.addEventListener("roster", (e) => updateRoster(JSON.parse(e.data))); es.addEventListener("membership", (e) => applyMembership(JSON.parse(e.data))); es.addEventListener("membership-read-failed", () => membershipUnreadable()); es.addEventListener("message", (e) => onMessage(JSON.parse(e.data))); }
 
   resize();
   setInterval(setFeed, 5000); // age "live" → "stale" even without new events

package/dist/web/index.html

@@ -229,6 +229,14 @@
       .chip.danger { color: var(--red); }
       .chip.danger:hover { background: #2a1717; border-color: var(--red); }
 
+      /* Ordering notice: what the bootstrap found out about the event stream it merged. Shape and
+         text carry the meaning; `.fault` only adds emphasis, so colour is never the whole signal. */
+      .order-notice {
+        flex: none; padding: 8px 20px; font-size: 12px; color: var(--fg);
+        background: var(--tile); border-bottom: 1px solid var(--line);
+      }
+      .order-notice.fault { border-left: 3px solid var(--amber); }
+
       .feed { overflow-y: auto; min-height: 0; flex: 1; display: flex; flex-direction: column;
         gap: 2px; padding: 8px; }
       .sys { text-align: center; padding: 5px 12px; font-size: 11px; color: var(--faint); }
@@ -495,6 +503,9 @@
     <script src="/vendor/marked.umd.js"></script>
     <script src="/vendor/purify.min.js"></script>
     <script src="/harness.js"></script>
+    <script src="/parts.js"></script>
+    <script src="/agui-frame.js"></script>
+    <script src="/event-order.js"></script>
     <script src="/md.js"></script>
     <script src="/app.js"></script>
   </body>

package/dist/web/parts.js

@@ -0,0 +1,144 @@
+// Rendering message parts as the flat text the dashboard displays.
+//
+// WHY THIS FILE EXISTS. `app.js` and `graph.js` each carried their own copy of
+//   (msg.parts || []).map((p) => (p.kind === "text" ? p.text : JSON.stringify(p.data))).join(" ")
+// and that expression DELETES any part it cannot draw. `JSON.stringify(undefined)` returns the
+// VALUE `undefined` — not the string "undefined" — and `Array.prototype.join` coerces that to the
+// empty string. So a part with no `data` field — `ag-ui.frame` among them, but NOT every extension
+// kind, since a data-bearing one rendered its JSON perfectly well — vanished: a stray separator
+// between its neighbours, or an empty string when it was the only part. In every case the KIND went
+// unnamed, so a reader could not tell which renderer was missing. Those two are what this file
+// fixes, and they are the claims to hold it to.
+//
+// THE CONSEQUENCE DIFFERS BY SURFACE, AND AN EARLIER VERSION OF THIS COMMENT GOT IT WRONG. It said
+// both surfaces told the operator that nothing arrived. That is true of ONE of them:
+//   - `app.js` renders the body through `bodyBlock`, i.e. `MD.render(text || "")`, so an empty
+//     rendering really does produce a blank body — absence reported as calm.
+//   - `graph.js`'s detail row renders `esc(m.text).slice(0, 160) || "—"`, so an empty rendering
+//     became a VISIBLE DASH inside a row still carrying mode, sender and channel/target. The graph
+//     showed a message with an unreadable body. It never claimed nothing arrived.
+// Overstating a defect is the same class of error as understating one: it describes a property
+// nothing recomputes, and it makes the fix look like it closes more than it does.
+//
+// A literal "undefined" in a message body would have been reported the day it shipped; a blank one
+// is not, which is part of why this survived. But note the graph placeholder cuts the other way —
+// it was the more visible of the two and still went unfixed, so visibility alone was not enough.
+//
+// ONE renderer for both pages, not two copies, for the reason core's own `partsToText` gives: the
+// duplicated form broke identically everywhere when a new part kind appeared, because each copy had
+// to be found and fixed separately.
+//
+// AND ON THIS SURFACE NOTHING ELSE WOULD HAVE CAUGHT IT. `implementations/web/tsconfig.json` sets
+// `"exclude": ["src/web"]`, so every file in this directory is plain JS that `tsc` never reads. The
+// two copies of the broken expression were the same mistake, in the same words, in two files, and
+// **no compiler in this repo could see either one**. That is not an argument about style; it is why
+// the checks on this directory have to be executable cells that run the shipped file, because they
+// are the only enforcement this surface has. `index.html` and `graph.html` both load this file BEFORE their
+// page script, and `web.ts` serves it from the PAGE allow-list — a file missing from that map is a
+// 404 no matter what the HTML says.
+//
+// IT WAS AHEAD OF CORE, AND CORE HAS SINCE CAUGHT UP. This mirrors the contract of core's
+// `partsToText`. When this file was written, core's copy still had the vanishing
+// `JSON.stringify(p.data)` fallback and printed no marker, so the browser ran ahead on purpose;
+// core now carries the marker and a per-kind renderer seam of its own. The two remain SEPARATE
+// implementations because this surface cannot import core at all, and they are held together by
+// `bin/smoke/agui-render-parity.smoke.ts` rather than by anyone's intention. One difference is
+// deliberate and survives: an extension kind carrying `data` renders its JSON here (see below) and
+// goes straight to the marker in core.
+//
+// SCOPE: this makes an undrawable part SAY SO, preserves everything that was already visible, and
+// CONSULTS a per-kind renderer registry so a surface can be taught to draw a kind without this file
+// learning what the kind is. It does not itself know how to render an AG-UI frame; `agui-frame.js`
+// does, and it registers. An earlier version of this line read "and nothing wider", which was FALSE
+// while the extension branch discarded data: the scope sentence was wider than the code in one
+// direction and narrower in the other. It then read "does not teach either page to RENDER an AG-UI
+// frame", which went false in the other direction the moment the lookup landed, because the page
+// can now draw one via a file this one has never heard of. A scope sentence is only worth having if
+// it is re-read every time the code under it moves.
+//
+// Neither page republishes this text — `graph.js` only issues GETs and `app.js`'s single POST is
+// `/api/channel/delete`, which carries a channel name — so the marker is safe to place in the body
+// itself. If either page ever gains a republish path, the marker must move beside the text rather
+// than inside it, or it will be replayed to the mesh as though an agent had typed it.
+window.COTAL_PARTS = (() => {
+  function partText(p) {
+    if (p.kind === "text") return p.text;
+    // The digest is verbose and not optional: it is the only handle a reader can act on to fetch
+    // the bytes. Name and size come from the publisher, so they are shown as its claims.
+    if (p.kind === "artifact") return `[artifact ${p.name} (${p.mediaType}, ${p.size} bytes) ${p.digest}]`;
+    if (p.kind === "data") {
+      const encoded = JSON.stringify(p.data);
+      // A `data` part carrying no data hits the same vanishing act as an unknown kind, so it needs
+      // its own marker. Named separately from the kind marker below because "a data part with
+      // nothing in it" and "a kind this build cannot draw" are different facts, and a reader who
+      // sees one must not conclude the other.
+      return encoded === undefined ? "[empty data part]" : encoded;
+    }
+    // An extension kind. A surface may have been TAUGHT to draw one, by registering a function
+    // under its kind in `window.COTAL_PART_RENDERERS` (see `agui-frame.js`). Consulted here, first,
+    // because a renderer that exists is strictly more specific than either fallback below.
+    //
+    // READ AT CALL TIME, not when this closure was built, so registration may happen in any script
+    // order. That is the whole reason this is a lookup and not an import: this file stays ignorant
+    // of every kind anyone teaches it, which is what keeps the dispatcher a dispatcher.
+    //
+    // A THROWING RENDERER MUST NOT TAKE THE PAGE DOWN, and must not silently become a blank body
+    // either, which is precisely the failure this file exists to remove; re-introducing it through
+    // the extension seam would be the same bug with a new door. It degrades to a NAMED marker
+    // carrying the error, and the data fallback below is not reached: a renderer that registered
+    // and then failed is a different fact from no renderer at all, and a reader who saw raw JSON
+    // would conclude the second.
+    // OWN PROPERTIES ONLY. `p.kind` comes off the wire, and a plain object inherits `toString`,
+    // `valueOf` and `constructor` from `Object.prototype` — every one of them a function. A bare
+    // `renderers[p.kind]` therefore RESOLVES for a part whose kind is `"toString"`, passes the
+    // `typeof === "function"` test, and gets called unbound: the body renders `[object Window]`,
+    // which names no kind and reports no failure. Core's dispatcher is keyed by a `Map` and never
+    // had this door; a plain object on `window` does, so it is closed explicitly here.
+    const renderers = window.COTAL_PART_RENDERERS;
+    const render =
+      renderers && Object.prototype.hasOwnProperty.call(renderers, p.kind) ? renderers[p.kind] : undefined;
+    if (typeof render === "function") {
+      let out;
+      try {
+        out = render(p);
+      } catch (err) {
+        return `[renderer for part kind ${JSON.stringify(p.kind)} failed: ${err && err.message ? err.message : String(err)}]`;
+      }
+      // A renderer returning a non-string would put `undefined` or `[object Object]` into the body
+      // through the same coercion described at the top of this file. Its contract is a string.
+      if (typeof out === "string") return out;
+      return `[renderer for part kind ${JSON.stringify(p.kind)} returned ${typeof out}, expected a string]`;
+    }
+
+    // No renderer for this kind. Not drawable here, and not silently droppable either.
+    //
+    // BUT DATA-BEARING EXTENSIONS MUST KEEP THEIR DATA. The first version of this file sent every
+    // non-core kind straight to the marker, which THREW AWAY content the old expression had been
+    // showing: `{kind:"com.acme.snapshot", data:{x:1}}` rendered `{"x":1}` before and the marker
+    // after. That is a regression wearing a fix's clothes — it removes information while claiming
+    // to add it, and it made this file's own "scope is nothing wider" claim false.
+    //
+    // THIS IS THE DELIBERATE DIFFERENCE FROM CORE ANNOUNCED AT THE TOP OF THIS FILE, NOT AGREEMENT
+    // WITH IT. Core's `partsToText` renders a data-bearing extension kind as the marker alone and
+    // keeps nothing (driven, not read: a part `{kind:"com.acme.snapshot", data:{x:1}}` through core
+    // returns only the unrenderable marker). The difference is justified by the SURFACE, not by
+    // core: this file replaces an expression that was already showing that JSON, and core's
+    // equivalent never did, so keeping it is a regression here and would be an addition there.
+    //
+    // So: name the kind AND keep the data. That is strictly more than either did alone — the old
+    // expression showed the data but never said what it was, and the marker alone said what it was
+    // while discarding it.
+    const encoded = JSON.stringify(p.data);
+    if (encoded !== undefined) return `[${p.kind}] ${encoded}`;
+    // No data to keep. This is the case the file exists for: name the kind, so a reader knows which
+    // renderer is missing instead of seeing a message that looks like it was sent blank.
+    return `[unrenderable part kind ${JSON.stringify(p.kind)} — no renderer for it on this surface]`;
+  }
+
+  /** A message's parts as one flat string, space-joined. */
+  function partsToText(parts) {
+    return (parts || []).map(partText).join(" ");
+  }
+
+  return { partsToText };
+})();