Add interactive trace-grounded CID mechanism replay

.gitignore

@@ -0,0 +1,4 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/

README.md

@@ -24,6 +24,8 @@ Interactive Hugging Face Space for the 398.8M-parameter `fwerkor/CID-v1-0.4B` ch
 
 The demo exposes CID's revisable Display and runtime trace with example prompts for the released 0.4B checkpoint. `calculator`, `symbolic_math`, and the task-local workspace are enabled explicitly from the UI. The workspace editor is disabled until its tool switch is enabled; document-backed examples enable it automatically. Workspace mode exposes read-only `workspace_search` and `workspace_read` information needs while reasoning.
 
+The **CID in motion** replay sits between the result and detailed inspection tabs. Play or scrub through the current run, jump to tool returns and evidence projections, inspect observed TCT cell states, and compare successive Display snapshots. The shared clock uses measured trace timestamps; playback speed is adjustable. The visualization uses the full runtime events, including asynchronous completion callbacks, without additional model calls. Cell semantics and unrecorded tool contents are not inferred.
+
 The model is mechanism-focused, with general-purpose chat outside the primary evaluation target. The Space uses the published unified checkpoint and pins the CID runtime implementation to commit `49c02313044278c93e929834261bebebf3f66bf5`.
 
 **Paper:** [Continuous Interaction Diffusion](https://arxiv.org/abs/2608.10438)
@@ -38,3 +40,8 @@ The model is mechanism-focused, with general-purpose chat outside the primary ev
 - `cid_demo/workspace.py` — task-local document parsing.
 - `cid_demo/examples.py` — public examples and workspace fixtures.
 - `cid_demo/presentation.py` and `cid_demo/assets/styles.css` — display formatting, HTML, and styling.
+- `cid_demo/mechanism.py` and `cid_demo/assets/mechanism.*` — isolated interactive trace replay, event reducer, and responsive mechanism view.
+
+## Frontend checks
+
+Run `python -m pytest tests` and `node --test tests/mechanism-state.test.cjs`. These cover trace preservation, text isolation, asynchronous ordering, lifecycle reconstruction, failure/cancellation, and non-converged runs. The `/run_cid` API retains its first four outputs and appends the replay HTML as its fifth output.

cid_demo/assets/mechanism.css

@@ -0,0 +1,625 @@
+:root {
+  color-scheme: light dark;
+  --bg: #fff;
+  --soft: #f7f8fc;
+  --ink: #20263b;
+  --muted: #6c7387;
+  --line: #e5e8f1;
+  --indigo: #6256db;
+  --teal: #078b83;
+  --amber: #ba7515;
+  --purple: #8960c8;
+  --active: #7563df;
+  --waiting: #e4a443;
+  --stable: #37a797;
+  --retired: #a8afbf;
+}
+* {
+  box-sizing: border-box;
+}
+body {
+  margin: 0;
+  background: transparent;
+  color: var(--ink);
+  font:
+    14px/1.5 system-ui,
+    -apple-system,
+    BlinkMacSystemFont,
+    "Segoe UI",
+    sans-serif;
+}
+.replay {
+  padding: 25px 26px 18px;
+  border: 1px solid var(--line);
+  border-radius: 20px;
+  background: var(--bg);
+  overflow: hidden;
+}
+.heading {
+  display: flex;
+  align-items: flex-start;
+  justify-content: space-between;
+  gap: 16px;
+}
+.eyebrow {
+  font-size: 10px;
+  letter-spacing: 0.16em;
+  font-weight: 750;
+  color: var(--indigo);
+}
+h2 {
+  font-size: 27px;
+  letter-spacing: -0.035em;
+  margin: 3px 0 4px;
+  line-height: 1.2;
+}
+p {
+  margin: 0;
+  color: var(--muted);
+}
+.heading p {
+  font-size: 13px;
+}
+.badge {
+  font-size: 11px;
+  white-space: nowrap;
+  border: 1px solid var(--line);
+  padding: 5px 10px;
+  border-radius: 30px;
+  color: var(--muted);
+}
+.question {
+  font-size: 13px;
+  line-height: 1.5;
+  margin: 16px 0;
+  color: var(--muted);
+  white-space: pre-wrap;
+  max-height: 65px;
+  overflow: auto;
+  overflow-wrap: anywhere;
+  padding-left: 11px;
+  border-left: 2px solid var(--line);
+}
+.transport {
+  display: flex;
+  gap: 7px;
+  align-items: center;
+}
+button,
+select {
+  font: inherit;
+  color: var(--ink);
+  background: var(--bg);
+  border: 1px solid var(--line);
+  border-radius: 8px;
+  min-height: 32px;
+  padding: 5px 11px;
+  cursor: pointer;
+}
+button:hover:enabled,
+select:hover {
+  border-color: var(--indigo);
+}
+button:disabled {
+  opacity: 0.4;
+  cursor: default;
+}
+button.primary {
+  background: var(--indigo);
+  color: white;
+  border-color: var(--indigo);
+  min-width: 90px;
+}
+button:focus-visible,
+select:focus-visible,
+input:focus-visible,
+summary:focus-visible {
+  outline: 2px solid var(--indigo);
+  outline-offset: 3px;
+}
+.speed {
+  font-size: 11px;
+  color: var(--muted);
+  display: flex;
+  gap: 6px;
+  align-items: center;
+  margin-left: 6px;
+}
+.speed select {
+  font-size: 12px;
+  padding: 3px 5px;
+}
+.position {
+  margin-left: auto;
+  display: flex;
+  gap: 12px;
+  align-items: baseline;
+  font-variant-numeric: tabular-nums;
+}
+.position strong {
+  font-size: 13px;
+}
+.position span {
+  font-size: 11px;
+  color: var(--muted);
+}
+#scrubber {
+  width: 100%;
+  accent-color: var(--indigo);
+  margin: 12px 0 3px;
+  cursor: pointer;
+}
+.scene {
+  position: relative;
+  display: grid;
+  grid-template-columns: 26% 34% 28%;
+  justify-content: space-between;
+  padding: 20px 0 14px;
+  min-height: 330px;
+}
+.connections {
+  position: absolute;
+  inset: 72px 0 0;
+  width: 100%;
+  height: 230px;
+  pointer-events: none;
+  z-index: 0;
+  overflow: visible;
+}
+.connections text {
+  font-size: 9px;
+  fill: var(--muted);
+}
+.path {
+  fill: none;
+  stroke: var(--line);
+  stroke-width: 1.5;
+  stroke-dasharray: 4 4;
+}
+.path.lit {
+  stroke-width: 2.5;
+  stroke-dasharray: 7 5;
+}
+.playing .path.lit {
+  animation: flow 1s linear infinite;
+}
+.need.lit {
+  stroke: var(--amber);
+}
+.evidence.lit {
+  stroke: var(--teal);
+}
+.display.lit {
+  stroke: var(--purple);
+}
+@keyframes flow {
+  to {
+    stroke-dashoffset: -24;
+  }
+}
+.scene section {
+  position: relative;
+  z-index: 1;
+  min-width: 0;
+}
+.channel-label {
+  font-size: 10px;
+  font-weight: 750;
+  letter-spacing: 0.1em;
+  display: flex;
+  align-items: center;
+  gap: 7px;
+}
+.dot {
+  width: 7px;
+  height: 7px;
+  display: inline-block;
+  border-radius: 50%;
+  flex-shrink: 0;
+}
+.tool {
+  background: var(--teal);
+}
+.thought,
+.active {
+  background: var(--active);
+}
+.display {
+  background: var(--purple);
+}
+.waiting {
+  background: var(--waiting);
+}
+.stable {
+  background: var(--stable);
+}
+.retired {
+  background: var(--retired);
+}
+h3 {
+  font-size: 13px;
+  font-weight: 600;
+  margin: 6px 0 12px;
+}
+.tools {
+  display: flex;
+  flex-direction: column;
+  gap: 7px;
+  max-height: 204px;
+  overflow: auto;
+}
+.tool-row {
+  background: var(--soft);
+  border: 1px solid var(--line);
+  border-radius: 10px;
+  padding: 9px 10px;
+}
+.tool-row strong {
+  display: block;
+  font-size: 12px;
+  overflow-wrap: anywhere;
+}
+.tool-row span {
+  font-size: 11px;
+  color: var(--muted);
+}
+.tool-row.busy {
+  border-color: var(--amber);
+}
+.tool-row.ready,
+.tool-row.projected {
+  border-color: var(--teal);
+}
+.tool-row small {
+  display: block;
+  font-size: 10px;
+  color: var(--muted);
+  margin-top: 3px;
+}
+.empty {
+  color: var(--muted);
+  font-size: 12px;
+  padding: 18px 8px;
+  border: 1px dashed var(--line);
+  border-radius: 10px;
+}
+.field-wrap {
+  position: relative;
+}
+.field-wrap svg {
+  width: 100%;
+  max-height: 217px;
+  display: block;
+}
+.field-shell {
+  fill: var(--soft);
+  stroke: var(--line);
+  stroke-width: 1;
+}
+.field-inner {
+  fill: none;
+  stroke: var(--line);
+  stroke-dasharray: 3 6;
+}
+.field-wrap text {
+  fill: var(--muted);
+  font-size: 11px;
+}
+.cell {
+  stroke: var(--bg);
+  stroke-width: 2;
+  transition:
+    fill 0.15s,
+    opacity 0.15s;
+  cursor: pointer;
+}
+.cell.changed {
+  stroke: var(--ink);
+  stroke-width: 2.3;
+}
+.cell-label {
+  font-size: 7px !important;
+  fill: var(--bg) !important;
+  pointer-events: none;
+  font-weight: 600;
+}
+.model-state {
+  position: absolute;
+  bottom: 1px;
+  left: 50%;
+  transform: translateX(-50%);
+  font-size: 10px;
+  border: 1px solid var(--line);
+  border-radius: 20px;
+  padding: 2px 9px;
+  background: var(--bg);
+  white-space: nowrap;
+}
+.legend {
+  display: flex;
+  justify-content: center;
+  gap: 8px;
+  flex-wrap: wrap;
+  margin: 10px 0 4px;
+  font-size: 10px;
+  color: var(--muted);
+}
+.legend span {
+  display: flex;
+  align-items: center;
+  gap: 4px;
+}
+.micro {
+  font-size: 10px;
+  color: var(--muted);
+  margin-top: 7px;
+  line-height: 1.5;
+}
+.thought-area .micro {
+  text-align: center;
+}
+.answer {
+  border-top: 2px solid var(--purple);
+  padding: 13px 0 8px;
+  min-height: 98px;
+  max-height: 170px;
+  overflow: auto;
+  white-space: pre-wrap;
+  overflow-wrap: anywhere;
+  font-size: 23px;
+  line-height: 1.4;
+  font-weight: 620;
+  letter-spacing: -0.02em;
+}
+.answer mark {
+  background: #ebe4ff;
+  color: inherit;
+  border-radius: 3px;
+}
+.tokens {
+  display: flex;
+  gap: 3px;
+  flex-wrap: wrap;
+  max-height: 40px;
+  overflow: auto;
+  margin-top: 10px;
+}
+.token {
+  width: 6px;
+  height: 12px;
+  border-radius: 2px;
+  background: var(--line);
+}
+.token.changed {
+  background: var(--purple);
+}
+.event-story {
+  display: flex;
+  align-items: center;
+  gap: 13px;
+  background: var(--soft);
+  padding: 13px 16px;
+  border-radius: 11px;
+  min-height: 82px;
+  border-left: 3px solid var(--indigo);
+}
+.event-icon {
+  font-size: 24px;
+  color: var(--indigo);
+  min-width: 28px;
+  text-align: center;
+}
+.event-story strong {
+  font-size: 13px;
+}
+.event-story p {
+  font-size: 12px;
+  margin-top: 3px;
+  overflow-wrap: anywhere;
+}
+.timeline-area {
+  margin-top: 20px;
+}
+.timeline-heading {
+  display: flex;
+  justify-content: space-between;
+  gap: 10px;
+  font-size: 11px;
+}
+.timeline-heading span {
+  color: var(--muted);
+  font-size: 10px;
+}
+#timeline {
+  display: block;
+  width: 100%;
+  height: 116px;
+  margin-top: 8px;
+  overflow: visible;
+}
+#timeline text {
+  fill: var(--muted);
+  font-size: 10px;
+}
+#timeline .tick {
+  cursor: pointer;
+}
+#timeline .cursor {
+  stroke: var(--ink);
+  stroke-width: 1.4;
+}
+.timeline-footer {
+  display: flex;
+  justify-content: space-between;
+  color: var(--muted);
+  font-size: 10px;
+  gap: 12px;
+}
+.jumps {
+  display: flex;
+  gap: 6px;
+  flex-wrap: wrap;
+  margin-top: 14px;
+}
+.jumps button {
+  font-size: 11px;
+  min-height: 27px;
+  padding: 3px 9px;
+}
+details {
+  margin-top: 13px;
+  font-size: 11px;
+  color: var(--muted);
+}
+summary {
+  cursor: pointer;
+  width: fit-content;
+}
+pre {
+  font-size: 11px;
+  max-height: 190px;
+  overflow: auto;
+  background: var(--soft);
+  padding: 12px;
+  border-radius: 8px;
+  white-space: pre-wrap;
+  overflow-wrap: anywhere;
+}
+.footnote {
+  font-size: 10px;
+  line-height: 1.5;
+  margin-top: 11px;
+}
+@media (prefers-color-scheme: dark) {
+  :root {
+    --bg: #111727;
+    --soft: #192134;
+    --ink: #e5e9f5;
+    --muted: #9aa5bd;
+    --line: #2b354b;
+    --indigo: #978bfa;
+    --teal: #43c3b8;
+    --amber: #e8b15a;
+    --purple: #b498ee;
+  }
+  .answer mark {
+    background: #433761;
+  }
+  button.primary {
+    color: #111727;
+  }
+}
+@media (max-width: 650px) {
+  .replay {
+    padding: 18px 14px 14px;
+    border-radius: 14px;
+  }
+  .heading {
+    gap: 7px;
+  }
+  h2 {
+    font-size: 24px;
+  }
+  .heading p {
+    font-size: 12px;
+  }
+  .badge {
+    font-size: 9px;
+    padding: 4px 7px;
+  }
+  .position {
+    display: block;
+    text-align: right;
+  }
+  .position span {
+    display: block;
+    font-size: 9px;
+  }
+  .speed {
+    margin-left: 0;
+  }
+  .transport {
+    gap: 4px;
+  }
+  button {
+    padding: 5px 8px;
+  }
+  .primary {
+    min-width: 70px !important;
+  }
+  .scene {
+    grid-template-columns: 43% 53%;
+    padding-top: 16px;
+    gap: 10px;
+    min-height: 0;
+  }
+  .thought-area {
+    grid-column: 2;
+  }
+  .tool-area {
+    grid-column: 1;
+  }
+  .display-area {
+    grid-column: 1/-1;
+    border-top: 1px solid var(--line);
+    padding-top: 14px;
+  }
+  .connections {
+    display: none;
+  }
+  .field-wrap svg {
+    max-height: 176px;
+  }
+  .legend {
+    gap: 5px;
+    font-size: 9px;
+  }
+  .answer {
+    min-height: 60px;
+    max-height: 130px;
+    font-size: 23px;
+  }
+  .display-area h3 {
+    margin-bottom: 7px;
+  }
+  .timeline-heading {
+    display: block;
+  }
+  .timeline-heading span {
+    display: block;
+    margin-top: 3px;
+  }
+  .timeline-footer {
+    font-size: 9px;
+  }
+  .event-story {
+    margin-top: 12px;
+    padding: 12px;
+  }
+  .event-story p {
+    font-size: 11px;
+  }
+  .tools {
+    max-height: 175px;
+  }
+  .tool-row {
+    padding: 8px;
+  }
+  .channel-label {
+    font-size: 9px;
+  }
+  .scene h3 {
+    font-size: 12px;
+  }
+  .footnote {
+    font-size: 9px;
+  }
+}
+@media (prefers-reduced-motion: reduce) {
+  *,
+  *::before,
+  *::after {
+    animation: none !important;
+    transition: none !important;
+  }
+}

cid_demo/assets/mechanism.html

@@ -0,0 +1,62 @@
+<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+<style>/* REPLAY_CSS */</style></head>
+<body>
+<main class="replay" aria-label="CID mechanism replay">
+  <header class="heading"><div><div class="eyebrow">INSIDE THE RUN</div><h2>CID in motion</h2>
+    <p>Follow the cognitive cells, tool activity and revisable answer through this run.</p></div>
+    <span class="badge" id="run-badge">Awaiting a run</span></header>
+  <div class="question" id="question">Run a prompt above to explore its actual trajectory.</div>
+  <div class="transport">
+    <button id="play" class="primary" disabled aria-label="Play replay">▶ Play</button>
+    <button id="prev" aria-label="Previous event" disabled>←</button>
+    <button id="next" aria-label="Next event" disabled>→</button>
+    <label class="speed">Pace <select id="speed" aria-label="Playback pace"><option value="900">Slow</option><option value="380" selected>Normal</option><option value="120">Fast</option></select></label>
+    <div class="position"><strong id="step-label">Step —</strong><span id="time-label">0.000 s · event —</span></div>
+  </div>
+  <input id="scrubber" aria-label="Runtime event" type="range" min="0" max="0" value="0" disabled>
+  <div class="scene">
+    <svg class="connections" viewBox="0 0 1000 290" preserveAspectRatio="none" aria-hidden="true">
+      <defs><marker id="arrow" viewBox="0 0 10 10" refX="8" refY="5" markerWidth="5" markerHeight="5" orient="auto-start-reverse"><path d="M 0 0 L 10 5 L 0 10 z" fill="context-stroke"/></marker></defs>
+      <path id="request-path" class="path need" d="M 420 86 C 340 50 306 58 246 86" marker-end="url(#arrow)"/>
+      <path id="return-path" class="path evidence" d="M 246 191 C 319 221 355 221 420 191" marker-end="url(#arrow)"/>
+      <path id="display-path" class="path display" d="M 586 140 C 646 140 665 140 724 140" marker-end="url(#arrow)"/>
+      <text x="326" y="51" text-anchor="middle">information need</text>
+      <text x="326" y="242" text-anchor="middle">evidence → projection</text>
+      <text x="656" y="123" text-anchor="middle">materialize</text>
+    </svg>
+    <section class="tool-area"><div class="channel-label"><i class="dot tool"></i>EXTERNAL TOOLS</div>
+      <h3>Reach for information</h3>
+      <div id="tools" class="tools"><div class="empty">Tool activity will appear here.</div></div>
+      <div id="tool-count" class="micro">Requests and returns from the trace</div>
+    </section>
+    <section class="thought-area"><div class="channel-label"><i class="dot thought"></i>T · THOUGHT</div>
+      <h3>A field of cognitive cells</h3>
+      <div class="field-wrap"><svg id="field" viewBox="0 0 300 235" role="img" aria-label="Observed TCT cell lifecycle states">
+        <ellipse class="field-shell" cx="150" cy="119" rx="140" ry="108"/>
+        <ellipse class="field-inner" cx="150" cy="119" rx="118" ry="89"/>
+        <g id="cells"></g><text id="field-empty" x="150" y="122" text-anchor="middle">No cells recorded yet</text>
+      </svg><span id="model-state" class="model-state">Waiting to begin</span></div>
+      <div class="legend"><span><i class="dot active"></i>Active</span><span><i class="dot waiting"></i>Waiting</span><span><i class="dot stable"></i>Stable</span><span><i class="dot retired"></i>Retired</span></div>
+      <div class="micro" id="cell-count">Cell colors follow recorded lifecycle events.</div>
+    </section>
+    <section class="display-area"><div class="channel-label"><i class="dot display"></i>D · DISPLAY</div>
+      <h3>An answer that can change</h3>
+      <div id="answer" class="answer">No Display materialized yet.</div>
+      <div class="micro" id="display-meta">Newly changed text is highlighted.</div>
+      <div id="tokens" class="tokens" aria-label="Recorded Display token positions"></div>
+      <div class="micro" id="token-caption"></div>
+    </section>
+  </div>
+  <div class="event-story" aria-live="polite" aria-atomic="true"><span class="event-icon" id="event-icon">○</span><div><strong id="event-title">Your run, made visible</strong><p id="event-copy">Play, pause or scrub through the events after a run finishes.</p></div></div>
+  <section class="timeline-area"><div class="timeline-heading"><strong>One shared clock</strong><span>Model work & tools can overlap · click a mark to inspect</span></div>
+    <svg id="timeline" viewBox="0 0 1000 116" role="img" aria-label="Model, tool, TCT and Display events on the recorded wall clock"></svg>
+    <div class="timeline-footer"><span id="duration-label">Recorded wall time</span><span>Playback pace is illustrative; timestamps are measured.</span></div>
+  </section>
+  <div class="jumps" id="jumps"></div>
+  <details id="event-details"><summary>Inspect this event</summary><pre id="raw-event">No runtime event selected.</pre></details>
+  <p class="footnote">Cells show observed lifecycle states, not decoded thoughts. Connections highlight recorded event types; the trace does not expose cell-to-cell semantic links.</p>
+</main>
+<script id="replay-data" type="application/json">/* REPLAY_DATA */</script>
+<script>/* REPLAY_JS */</script>
+</body></html>

cid_demo/assets/mechanism.js

@@ -0,0 +1,782 @@
+/* Pure event reducer is also exercised by the Node regression tests. */
+function buildReplay(events) {
+  let state = {
+    cells: {},
+    bindings: {},
+    jobs: {},
+    display: null,
+    previousDisplay: null,
+    model: "Waiting to begin",
+    needs: 0,
+    returns: 0,
+    projections: 0,
+    done: false,
+  };
+  const frames = [];
+  for (let i = 0; i < events.length; i++) {
+    const e = events[i],
+      p = e.payload || {},
+      k = e.kind;
+    state = {
+      ...state,
+      cells: { ...state.cells },
+      bindings: { ...state.bindings },
+      jobs: { ...state.jobs },
+    };
+    const binding = (id, patch) => {
+      if (id)
+        state.bindings[id] = {
+          ...(state.bindings[id] || { source: "Unknown source" }),
+          ...Object.fromEntries(
+            Object.entries(patch).filter(([, v]) => v !== undefined),
+          ),
+        };
+    };
+    const forWork = (key, patch) => {
+      if (key)
+        for (const [id, b] of Object.entries(state.bindings))
+          if (b.work_key === key) binding(id, patch);
+    };
+    if (k === "cell_allocated")
+      state.cells[p.cell_id] = { lifecycle: p.lifecycle, event: i };
+    if (k === "lifecycle_transition")
+      state.cells[p.cell_id] = { lifecycle: p.current, event: i };
+    if (k === "cell_reclaimed") delete state.cells[p.cell_id];
+    if (k === "model_step_started") state.model = "Refining";
+    if (k === "model_step_finished") {
+      state.model = p.converged
+        ? "Convergence proposed"
+        : p.equilibrium
+          ? "At equilibrium"
+          : "Step complete";
+      if (Object.hasOwn(p, "display_materialized_text")) {
+        state.previousDisplay = state.display;
+        state.display = {
+          text: p.display_materialized_text,
+          ids: p.display_token_ids || null,
+          step: e.step,
+          unresolved: p.display_unresolved,
+        };
+      }
+    }
+    if (k === "information_need") state.needs++;
+    if (k === "binding_active")
+      binding(p.binding_id, {
+        source: p.source,
+        need_id: p.need_id,
+        ...(!state.bindings[p.binding_id] ? { status: "Bound" } : {}),
+      });
+    if (k === "external_refresh_started" || k === "job_started") {
+      binding(p.binding_id, { status: "Running", work_key: p.work_key });
+      if (p.work_key)
+        state.jobs[p.work_key] = {
+          binding_id: p.binding_id,
+          status: "Running",
+        };
+    }
+    if (k === "external_refresh_ready") {
+      binding(p.binding_id, {
+        status: p.success === false ? "Failed" : "Returned",
+        work_key: p.work_key,
+      });
+      if (p.work_key)
+        state.jobs[p.work_key] = {
+          ...(state.jobs[p.work_key] || {}),
+          status: p.success === false ? "Failed" : "Returned",
+        };
+    }
+    if (k === "external_refresh_finished" || k === "job_finished") {
+      forWork(p.work_key, { status: "Read complete" });
+      state.returns++;
+    }
+    if (k === "binding_observation_updated" || k === "observation_available")
+      binding(p.binding_id, {
+        status: "Evidence available",
+        work_key: p.work_key,
+        version: p.version,
+      });
+    if (k === "cache_hit") binding(p.binding_id, { status: "Cached evidence" });
+    if (k === "cognitive_projection") {
+      binding(p.binding_id, { status: "Projected", projection: p.index });
+      state.projections++;
+    }
+    if (k === "job_deduplicated")
+      binding(p.binding_id, { status: "Shared job" });
+    if (k === "external_refresh_cancelled" || k === "stream_cancelled")
+      forWork(p.work_key, { status: "Cancelled" });
+    if (k === "quiescence_started") state.model = "Waiting for evidence";
+    if (k === "quiescence_resumed") state.model = "Resuming";
+    if (k === "loop_escape_applied") state.model = "Re-diffusing";
+    if (k === "trajectory_finalized") state.model = "Converged";
+    if (k === "trajectory_finished") {
+      state.model = p.converged ? "Converged" : "Stopped";
+      state.done = true;
+    }
+    frames.push(state);
+  }
+  return frames;
+}
+if (typeof module !== "undefined") module.exports = { buildReplay };
+
+if (typeof document !== "undefined")
+  (() => {
+    "use strict";
+    const data = JSON.parse(document.getElementById("replay-data").textContent);
+    const events = data.events || [],
+      frames = buildReplay(events),
+      $ = (id) => document.getElementById(id);
+    const esc = (x) =>
+      String(x ?? "").replace(
+        /[&<>"']/g,
+        (c) =>
+          ({
+            "&": "&amp;",
+            "<": "&lt;",
+            ">": "&gt;",
+            '"': "&quot;",
+            "'": "&#39;",
+          })[c],
+      );
+    const colors = {
+      active: "var(--active)",
+      waiting: "var(--waiting)",
+      stable: "var(--stable)",
+      retired: "var(--retired)",
+      empty: "var(--line)",
+    };
+    let index = 0,
+      timer = null,
+      selectedCell = null;
+    const lastTime = Math.max(
+      0,
+      ...events.map((e) => Number(e.timestamp_s) || 0),
+    );
+    const timeX = (t) => 100 + (884 * (Number(t) || 0)) / (lastTime || 1);
+    const lane = (k) =>
+      /external|binding|information_need|cache_hit|projection|job_|stream_|observation/.test(
+        k,
+      )
+        ? 1
+        : /cell_|lifecycle|compaction|loop_/.test(k)
+          ? 2
+          : k === "model_step_finished"
+            ? 3
+            : 0;
+    const laneColor = (n) =>
+      ["var(--indigo)", "var(--teal)", "var(--amber)", "var(--purple)"][n];
+    function story(e, s) {
+      const p = e.payload || {},
+        source = p.source || s.bindings[p.binding_id]?.source || "the tool";
+      const known = {
+        trajectory_started: [
+          "◎",
+          "The trajectory begins",
+          "The runtime starts iterative refinement for this prompt.",
+        ],
+        model_step_started: [
+          "↻",
+          "Refining the current state",
+          p.percepts
+            ? String(p.percepts) + " recorded percept(s) enter this model step."
+            : "The model updates its cognitive field and Display.",
+        ],
+        model_step_finished: [
+          "✦",
+          "The Display is materialized",
+          String(p.needs ?? 0) +
+            " information need(s) proposed. " +
+            (p.converged
+              ? "The model proposes convergence; the runtime still checks outstanding work."
+              : p.equilibrium
+                ? "The model reports equilibrium for its current information."
+                : "Compare this snapshot with the previous model step."),
+        ],
+        information_need: [
+          "↗",
+          "An information need emerges",
+          source +
+            " · confidence " +
+            (Number.isFinite(p.confidence)
+              ? p.confidence.toFixed(3)
+              : "not recorded") +
+            ". " +
+            (p.executable
+              ? "This need has the required tool arguments."
+              : "This need is not executable at this event."),
+        ],
+        binding_active: [
+          "⇄",
+          "A need is bound to a source",
+          source + " is bound to " + (p.need_id || "the recorded need") + ".",
+        ],
+        external_refresh_started: [
+          "↗",
+          "External work starts",
+          "A read is launched for " +
+            source +
+            ". Subsequent model steps and this read have separate events on the clock.",
+        ],
+        external_refresh_ready: [
+          "↙",
+          p.success === false
+            ? "The tool read failed"
+            : "The tool has returned",
+          p.success === false
+            ? "The completion callback reports failure."
+            : "The asynchronous read is ready. The runtime must still collect and project its observation.",
+        ],
+        external_refresh_finished: [
+          "✓",
+          "The runtime collects a result",
+          "The completed external read is drained; observation updates identify the receiving bindings.",
+        ],
+        binding_observation_updated: [
+          "↓",
+          "Evidence becomes available",
+          source +
+            " now has a recorded observation. A projection event shows when it is fed into the model.",
+        ],
+        cognitive_projection: [
+          "→",
+          "Evidence enters the cognitive field",
+          source +
+            " · projection " +
+            (p.index ?? "—") +
+            ". The observation is included in the next model context.",
+        ],
+        cache_hit: [
+          "↙",
+          "A cached observation is reused",
+          "An existing observation satisfies this binding without a new external read.",
+        ],
+        job_deduplicated: [
+          "⇄",
+          "Bindings share external work",
+          "This need reuses an already running job.",
+        ],
+        cell_allocated: [
+          "●",
+          "A cognitive cell is allocated",
+          (p.cell_id || "Cell") +
+            " enters the " +
+            (p.lifecycle || "recorded") +
+            " state.",
+        ],
+        lifecycle_transition: [
+          "◉",
+          "A cognitive cell changes state",
+          (p.cell_id || "Cell") + ": " + p.previous + " → " + p.current + ".",
+        ],
+        cell_reclaimed: [
+          "○",
+          "A retired cell is reclaimed",
+          (p.cell_id || "Cell") + " is archived and its slot becomes reusable.",
+        ],
+        cognitive_compaction: [
+          "⋮",
+          "The cognitive field is compacted",
+          String(p.reclaimed ?? 0) +
+            " cell(s) reclaimed; " +
+            String(p.empty_slots ?? "—") +
+            " empty slots reported.",
+        ],
+        quiescence_started: [
+          "Ⅱ",
+          "Model computation pauses",
+          "The runtime waits for external progress. Reason: " +
+            (p.reason || "not recorded") +
+            ".",
+        ],
+        quiescence_resumed: [
+          "↻",
+          "External progress resumes the loop",
+          "Reason: " +
+            (p.reason || "not recorded") +
+            ". The next recorded model step shows the continuation.",
+        ],
+        loop_detected: [
+          "↻",
+          "A repeated pattern is detected",
+          "The runtime records a " +
+            (p.mode || "") +
+            " cycle of period " +
+            (p.period ?? "—") +
+            ".",
+        ],
+        loop_escape_applied: [
+          "↻",
+          "The runtime re-diffuses selected positions",
+          "This is a recovery event. The next model snapshot reveals the updated Display.",
+        ],
+        trajectory_finalized: [
+          "✓",
+          "The runtime accepts convergence",
+          "The finalization conditions are satisfied.",
+        ],
+        trajectory_finished: [
+          s.model === "Converged" ? "✓" : "■",
+          s.model === "Converged"
+            ? "The run has converged"
+            : "The run stopped without convergence",
+          "The replay has reached the recorded end of model execution.",
+        ],
+        total_compute_budget_exhausted: [
+          "■",
+          "The model-step budget is reached",
+          "The run stops at its configured total compute limit.",
+        ],
+        compute_budget_exhausted: [
+          "■",
+          "The compute budget is reached",
+          "The runtime records a compute-budget stop.",
+        ],
+        wall_clock_budget_exhausted: [
+          "■",
+          "The wall-time budget is reached",
+          "The run stops at its configured wall-time limit.",
+        ],
+        loop_escape_exhausted: [
+          "■",
+          "Recovery attempts are exhausted",
+          "The runtime stops after its configured loop-escape attempts.",
+        ],
+      };
+      return (
+        known[e.kind] || [
+          "·",
+          e.kind.replaceAll("_", " "),
+          "Inspect the exact recorded payload below.",
+        ]
+      );
+    }
+    function displayMarkup(now, before) {
+      if (now === null || now === undefined)
+        return "No Display materialized yet.";
+      if (!now) return '<span class="micro">(empty Display)</span>';
+      const a = Array.from(now),
+        b = Array.from(before || "");
+      let start = 0,
+        end = 0;
+      while (start < a.length && start < b.length && a[start] === b[start])
+        start++;
+      while (
+        end < a.length - start &&
+        end < b.length - start &&
+        a[a.length - 1 - end] === b[b.length - 1 - end]
+      )
+        end++;
+      return (
+        esc(a.slice(0, start).join("")) +
+        (a.length - start - end
+          ? "<mark>" + esc(a.slice(start, a.length - end).join("")) + "</mark>"
+          : "") +
+        esc(end ? a.slice(-end).join("") : "")
+      );
+    }
+    function renderCells(s, e) {
+      const entries = Object.entries(s.cells),
+        count = entries.length;
+      $("field-empty").style.display = count ? "none" : "";
+      $("cells").innerHTML = entries
+        .map(([id, c], n) => {
+          const angle = n * 2.3999632297,
+            r = Math.sqrt((n + 0.5) / Math.max(count, 1));
+          const x = 150 + 112 * r * Math.cos(angle),
+            y = 112 + 82 * r * Math.sin(angle),
+            radius = Math.min(16, Math.max(4.5, 67 / Math.sqrt(count)));
+          return (
+            '<g data-cell="' +
+            esc(id) +
+            '" tabindex="0" role="button" aria-label="' +
+            esc(id) +
+            ": " +
+            esc(c.lifecycle) +
+            '"><title>' +
+            esc(id) +
+            " · " +
+            esc(c.lifecycle) +
+            '</title><circle class="cell ' +
+            (c.event === index || id === selectedCell ? "changed" : "") +
+            '" cx="' +
+            x +
+            '" cy="' +
+            y +
+            '" r="' +
+            radius +
+            '" fill="' +
+            (colors[c.lifecycle] || "var(--line)") +
+            '" ' +
+            (c.lifecycle === "retired" ? 'opacity=".42"' : "") +
+            "/>" +
+            (count <= 40
+              ? '<text class="cell-label" x="' +
+                x +
+                '" y="' +
+                (y + 2.6) +
+                '" text-anchor="middle">' +
+                (n + 1) +
+                "</text>"
+              : "") +
+            "</g>"
+          );
+        })
+        .join("");
+      const counts = {};
+      entries.forEach(
+        ([, c]) => (counts[c.lifecycle] = (counts[c.lifecycle] || 0) + 1),
+      );
+      $("cell-count").textContent = count
+        ? Object.entries(counts)
+            .map(([k, v]) => v + " " + k)
+            .join(" · ")
+        : "No cell lifecycle events recorded so far.";
+    }
+    function renderTools(s) {
+      const grouped = {};
+      for (const [id, b] of Object.entries(s.bindings))
+        (grouped[b.source] ??= []).push([id, b]);
+      $("tools").innerHTML =
+        Object.entries(grouped)
+          .map(([source, items]) => {
+            const current =
+              items.find(([id]) => id === events[index].payload?.binding_id) ||
+              items[items.length - 1];
+            const b = current[1],
+              busy = items.some(([, x]) => x.status === "Running"),
+              cls = busy
+                ? "busy"
+                : /Projected|Evidence|Cached|Returned|complete/i.test(b.status)
+                  ? "ready"
+                  : "";
+            return (
+              '<div class="tool-row ' +
+              cls +
+              '"><strong>' +
+              esc(source) +
+              "</strong><span>" +
+              esc(b.status) +
+              "</span><small>" +
+              items.length +
+              " observed binding" +
+              (items.length === 1 ? "" : "s") +
+              "</small></div>"
+            );
+          })
+          .join("") ||
+        '<div class="empty">' +
+          (s.done
+            ? "No tool binding was recorded in this run."
+            : "No tool binding recorded yet.") +
+          "</div>";
+      $("tool-count").textContent =
+        s.needs +
+        " needs · " +
+        s.returns +
+        " reads collected · " +
+        s.projections +
+        " projections";
+    }
+    function render() {
+      if (!events.length) return;
+      const e = events[index],
+        p = e.payload || {},
+        s = frames[index],
+        prev = s.previousDisplay;
+      $("scrubber").value = index;
+      $("step-label").textContent = "Step " + e.step;
+      $("time-label").textContent =
+        (Number(e.timestamp_s) || 0).toFixed(3) +
+        " s · event " +
+        (index + 1) +
+        "/" +
+        events.length;
+      $("prev").disabled = index === 0;
+      $("next").disabled = index === events.length - 1;
+      $("model-state").textContent = s.model;
+      $("run-badge").textContent = s.done ? s.model : "Trace replay";
+      const showFinal = s.done && typeof data.final_text === "string";
+      const text = showFinal ? data.final_text : s.display?.text;
+      $("answer").innerHTML = displayMarkup(text, prev?.text);
+      $("display-meta").textContent = showFinal
+        ? "Final runtime Display"
+        : s.display
+          ? "Snapshot at step " +
+            s.display.step +
+            (text === prev?.text
+              ? " · unchanged"
+              : text?.length < (prev?.text || "").length
+                ? " · revised / shortened"
+                : " · revised")
+          : "Awaiting the first recorded model snapshot.";
+      $("tokens").innerHTML = (s.display?.ids || [])
+        .map(
+          (id, i) =>
+            '<span class="token ' +
+            (id !== prev?.ids?.[i] ? "changed" : "") +
+            '" title="Position ' +
+            i +
+            " · token ID " +
+            id +
+            '"></span>',
+        )
+        .join("");
+      $("token-caption").textContent = s.display?.ids
+        ? String(s.display.ids.length) +
+          " recorded token positions · colored = changed ID"
+        : "";
+      renderCells(s, e);
+      renderTools(s);
+      const need =
+          /information_need|binding_active|external_refresh_started/.test(
+            e.kind,
+          ),
+        ret =
+          /binding_observation_updated|cache_hit|cognitive_projection|external_refresh_ready/.test(
+            e.kind,
+          );
+      $("request-path").classList.toggle("lit", need);
+      $("return-path").classList.toggle("lit", ret);
+      $("display-path").classList.toggle(
+        "lit",
+        e.kind === "model_step_finished",
+      );
+      const [icon, title, copy] = story(e, s);
+      $("event-icon").textContent = icon;
+      $("event-title").textContent = title;
+      $("event-copy").textContent = copy;
+      $("raw-event").textContent = JSON.stringify(
+        { event: index + 1, ...e },
+        null,
+        2,
+      );
+      const cursor = $("clock-cursor");
+      if (cursor) {
+        cursor.setAttribute("x1", timeX(e.timestamp_s));
+        cursor.setAttribute("x2", timeX(e.timestamp_s));
+      }
+      resize();
+    }
+    function pause() {
+      clearTimeout(timer);
+      timer = null;
+      document.querySelector(".replay").classList.remove("playing");
+      $("play").textContent =
+        index === events.length - 1 ? "↺ Replay" : "▶ Play";
+      $("play").setAttribute(
+        "aria-label",
+        index === events.length - 1 ? "Replay from start" : "Play replay",
+      );
+    }
+    function schedule() {
+      document.querySelector(".replay").classList.add("playing");
+      timer = setTimeout(
+        () => {
+          if (index >= events.length - 1) {
+            pause();
+            return;
+          }
+          index++;
+          render();
+          schedule();
+        },
+        Number($("speed").value),
+      );
+    }
+    function seek(i) {
+      pause();
+      index = Math.max(0, Math.min(events.length - 1, i));
+      render();
+    }
+    function makeTimeline() {
+      const labels = ["Model", "Tools", "TCT", "Display"];
+      let markup = labels
+        .map(
+          (label, n) =>
+            '<text x="0" y="' +
+            (18 + n * 24) +
+            '">' +
+            label +
+            '</text><line x1="100" x2="984" y1="' +
+            (14 + n * 24) +
+            '" y2="' +
+            (14 + n * 24) +
+            '" stroke="var(--line)"/>',
+        )
+        .join("");
+      let pending = null;
+      const reads = new Map();
+      events.forEach((e, i) => {
+        const p = e.payload || {};
+        if (e.kind === "external_refresh_started" && p.work_key)
+          reads.set(p.work_key, e);
+        if (
+          (e.kind === "external_refresh_ready" ||
+            e.kind === "external_refresh_finished") &&
+          reads.has(p.work_key)
+        ) {
+          const start = reads.get(p.work_key);
+          reads.delete(p.work_key);
+          markup +=
+            '<rect x="' +
+            timeX(start.timestamp_s) +
+            '" y="33" width="' +
+            Math.max(1, timeX(e.timestamp_s) - timeX(start.timestamp_s)) +
+            '" height="10" rx="2" fill="var(--teal)" opacity=".3"><title>External read · ' +
+            (Number(e.timestamp_s) - Number(start.timestamp_s)).toFixed(3) +
+            " s</title></rect>";
+        }
+        if (e.kind === "model_step_started") pending = e;
+        if (e.kind === "model_step_finished" && pending) {
+          markup +=
+            '<rect x="' +
+            timeX(pending.timestamp_s) +
+            '" y="9" width="' +
+            Math.max(1, timeX(e.timestamp_s) - timeX(pending.timestamp_s)) +
+            '" height="10" rx="2" fill="var(--indigo)" opacity=".2"/>';
+          pending = null;
+        }
+        const n = lane(e.kind);
+        markup +=
+          '<circle class="tick" data-event="' +
+          i +
+          '" tabindex="0" role="button" aria-label="Event ' +
+          (i + 1) +
+          ": " +
+          esc(e.kind) +
+          '" cx="' +
+          timeX(e.timestamp_s) +
+          '" cy="' +
+          (14 + n * 24) +
+          '" r="3" fill="' +
+          laneColor(n) +
+          '"><title>' +
+          esc(e.kind) +
+          " · " +
+          Number(e.timestamp_s || 0).toFixed(3) +
+          " s</title></circle>";
+      });
+      markup +=
+        '<line id="clock-cursor" class="cursor" x1="100" x2="100" y1="1" y2="97"/><text x="100" y="113">0 s</text><text x="984" y="113" text-anchor="end">' +
+        lastTime.toFixed(3) +
+        " s</text>";
+      $("timeline").innerHTML = markup;
+      $("duration-label").textContent =
+        events.length + " events · " + lastTime.toFixed(3) + " s recorded";
+      const jumps = [
+        ["First need", (e) => e.kind === "information_need"],
+        [
+          "Tool return",
+          (e) =>
+            e.kind === "external_refresh_ready" ||
+            e.kind === "external_refresh_finished",
+        ],
+        ["Evidence in", (e) => e.kind === "cognitive_projection"],
+        [
+          "First revision",
+          (e, i) =>
+            e.kind === "model_step_finished" &&
+            frames[i].previousDisplay &&
+            frames[i].display?.text !== frames[i].previousDisplay?.text,
+        ],
+        ["Recovery", (e) => e.kind === "loop_escape_applied"],
+        ["Run end", (e) => e.kind === "trajectory_finished"],
+      ];
+      $("jumps").innerHTML = jumps
+        .map(([label, test]) => {
+          const i = events.findIndex(test);
+          return i < 0
+            ? ""
+            : '<button data-jump="' + i + '">' + label + "</button>";
+        })
+        .join("");
+    }
+    function resize() {
+      requestAnimationFrame(() =>
+        parent.postMessage(
+          {
+            type: "cid-replay-height",
+            height:
+              Math.ceil(
+                document.querySelector(".replay").getBoundingClientRect()
+                  .height,
+              ) + 2,
+          },
+          "*",
+        ),
+      );
+    }
+    $("play").addEventListener("click", () => {
+      if (timer) {
+        pause();
+        return;
+      }
+      if (index === events.length - 1) index = 0;
+      render();
+      $("play").textContent = "Ⅱ Pause";
+      $("play").setAttribute("aria-label", "Pause replay");
+      schedule();
+    });
+    $("prev").addEventListener("click", () => seek(index - 1));
+    $("next").addEventListener("click", () => seek(index + 1));
+    $("scrubber").addEventListener("input", () =>
+      seek(Number($("scrubber").value)),
+    );
+    $("speed").addEventListener("change", () => {
+      if (timer) {
+        clearTimeout(timer);
+        schedule();
+      }
+    });
+    $("timeline").addEventListener("click", (e) => {
+      const mark = e.target.closest("[data-event]");
+      if (mark) seek(Number(mark.dataset.event));
+    });
+    $("timeline").addEventListener("keydown", (e) => {
+      if (e.key === "Enter" || e.key === " ") {
+        const mark = e.target.closest("[data-event]");
+        if (mark) {
+          e.preventDefault();
+          seek(Number(mark.dataset.event));
+        }
+      }
+    });
+    $("jumps").addEventListener("click", (e) => {
+      const b = e.target.closest("[data-jump]");
+      if (b) seek(Number(b.dataset.jump));
+    });
+    function selectCell(e) {
+      const g = e.target.closest("[data-cell]");
+      if (!g) return;
+      selectedCell = g.dataset.cell;
+      pause();
+      const s = frames[index];
+      $("event-title").textContent = "Cognitive cell · " + selectedCell;
+      $("event-copy").textContent =
+        "Last observed lifecycle: " +
+        s.cells[selectedCell].lifecycle +
+        ". Its latent semantic content is not recorded.";
+      renderCells(s, events[index]);
+    }
+    $("cells").addEventListener("click", selectCell);
+    $("cells").addEventListener("keydown", (e) => {
+      if (e.key === "Enter" || e.key === " ") {
+        e.preventDefault();
+        selectCell(e);
+      }
+    });
+    document.addEventListener("visibilitychange", () => {
+      if (document.hidden) pause();
+    });
+    $("event-details").addEventListener("toggle", resize);
+    window.addEventListener("resize", resize);
+    new ResizeObserver(resize).observe(document.querySelector(".replay"));
+    if (events.length) {
+      $("question").textContent = data.prompt || "Recorded CID trajectory";
+      $("play").disabled = false;
+      $("scrubber").disabled = false;
+      $("scrubber").max = events.length - 1;
+      makeTimeline();
+      render();
+    }
+    resize();
+  })();

cid_demo/assets/styles.css

@@ -188,3 +188,9 @@
         grid-template-columns: repeat(2, minmax(0, 1fr));
     }
 }
+
+#cid-mechanism { margin-top: 24px; }
+@media (max-width: 480px) {
+  #prompt-panel, #result-panel { min-width: 0 !important; }
+  #cid-hero .hero-title { font-size: 34px; }
+}

cid_demo/mechanism.py

@@ -0,0 +1,48 @@
+"""Self-contained, trace-grounded CID replay; no model work during playback."""
+from __future__ import annotations
+
+import html
+import json
+from pathlib import Path
+from typing import Any
+
+_ASSETS = Path(__file__).parent / "assets"
+
+# The opaque-origin frame can execute only its own bundled visualization code.
+# Match the sending window before accepting its responsive height.
+REPLAY_BRIDGE_JS = """() => {
+  if (window.__cidReplayResize) return;
+  window.__cidReplayResize = true;
+  window.addEventListener("message", (event) => {
+    if (event.data?.type !== "cid-replay-height") return;
+    for (const frame of document.querySelectorAll("iframe.cid-replay-frame")) {
+      if (frame.contentWindow === event.source) {
+        const height = Number(event.data.height);
+        if (Number.isFinite(height)) frame.style.height = Math.min(2400, Math.max(520, height)) + "px";
+      }
+    }
+  });
+}"""
+
+
+def replay_document(events: tuple[dict[str, Any], ...] = (), *, prompt: str = "", final_text: str = "") -> str:
+    # Escape script terminators as well as the outer srcdoc attribute. All runtime
+    # strings are rendered as text by the client, never inserted as trusted HTML.
+    data = json.dumps(
+        {"events": list(events), "prompt": prompt, "final_text": final_text},
+        ensure_ascii=False, separators=(",", ":"), default=str,
+    ).replace("&", "\\u0026").replace("<", "\\u003c").replace(">", "\\u003e")
+    template = (_ASSETS / "mechanism.html").read_text(encoding="utf-8")
+    return (template.replace("/* REPLAY_CSS */", (_ASSETS / "mechanism.css").read_text(encoding="utf-8"))
+            .replace("/* REPLAY_JS */", (_ASSETS / "mechanism.js").read_text(encoding="utf-8"))
+            .replace("/* REPLAY_DATA */", data))
+
+
+def mechanism_html(events: tuple[dict[str, Any], ...] = (), *, prompt: str = "", final_text: str = "") -> str:
+    return (
+        '<iframe class="cid-replay-frame" title="CID mechanism replay" '
+        'sandbox="allow-scripts" referrerpolicy="no-referrer" '
+        'style="width:100%;height:820px;border:0;display:block" srcdoc="'
+        + html.escape(replay_document(events, prompt=prompt, final_text=final_text), quote=True)
+        + '"></iframe>'
+    )

cid_demo/runtime.py

@@ -20,6 +20,7 @@ from .config import (
     MODEL_REVISION,
 )
 from .model import MODEL_BUNDLE
+from .mechanism import mechanism_html
 from .presentation import display_evolution, summary_html, trace_rows
 from .tools import (
     LIVE_MATH_DESCRIPTORS,
@@ -184,4 +185,5 @@ def run_cid(
         summary_html(summary),
         display_evolution(events),
         trace_rows(events),
+        mechanism_html(events, prompt=prompt, final_text=result.final_text or ""),
     )

cid_demo/ui.py

@@ -13,6 +13,7 @@ from .config import (
 from .examples import EXAMPLES, WORKSPACE_PLACEHOLDER
 from .presentation import CUSTOM_CSS, FOOTER_HTML, HERO_HTML, READY_SUMMARY_HTML
 from .runtime import run_cid
+from .mechanism import REPLAY_BRIDGE_JS, mechanism_html
 
 
 @dataclass(frozen=True)
@@ -36,6 +37,7 @@ class DemoOutputs:
     summary: gr.HTML
     display_evolution: gr.Markdown
     trace: gr.Dataframe
+    mechanism: gr.HTML
 
 
 def _build_input_panel() -> tuple[DemoInputs, gr.Button]:
@@ -193,6 +195,7 @@ def build_demo() -> gr.Blocks:
     with gr.Blocks(
         title="CID · Demo",
         css=CUSTOM_CSS,
+        js=REPLAY_BRIDGE_JS,
         theme=gr.themes.Soft(
             primary_hue=gr.themes.colors.indigo,
             neutral_hue=gr.themes.colors.slate,
@@ -206,8 +209,9 @@ def build_demo() -> gr.Blocks:
             with gr.Column(scale=5, min_width=360, elem_id="result-panel"):
                 final_display, summary = _build_result_panel()
 
+        mechanism = gr.HTML(mechanism_html(), elem_id="cid-mechanism")
         display_evolution, trace = _build_inspection_tabs()
-        outputs = DemoOutputs(final_display, summary, display_evolution, trace)
+        outputs = DemoOutputs(final_display, summary, display_evolution, trace, mechanism)
 
         run_button.click(
             fn=run_cid,
@@ -229,6 +233,7 @@ def build_demo() -> gr.Blocks:
                 outputs.summary,
                 outputs.display_evolution,
                 outputs.trace,
+                outputs.mechanism,
             ],
             concurrency_limit=1,
             api_name="run_cid",

tests/mechanism-state.test.cjs

@@ -0,0 +1,94 @@
+const test = require("node:test");
+const assert = require("node:assert/strict");
+const { buildReplay } = require("../cid_demo/assets/mechanism.js");
+const event = (kind, payload = {}, step = 0, timestamp_s = 0) => ({
+  kind,
+  payload,
+  step,
+  timestamp_s,
+});
+test("async completion stays in event order even when callback step goes backwards", () => {
+  const f = buildReplay([
+    event("binding_active", { binding_id: "b", source: "calculator" }),
+    event(
+      "external_refresh_started",
+      { binding_id: "b", work_key: "w" },
+      0,
+      0.1,
+    ),
+    event("model_step_started", {}, 1, 0.2),
+    event(
+      "external_refresh_ready",
+      { binding_id: "b", work_key: "w", success: true },
+      0,
+      0.3,
+    ),
+    event(
+      "binding_observation_updated",
+      { binding_id: "b", work_key: "w" },
+      1,
+      0.4,
+    ),
+    event("cognitive_projection", { binding_id: "b", index: 1 }, 2, 0.5),
+  ]);
+  assert.equal(f[2].bindings.b.status, "Running");
+  assert.equal(f[3].model, "Refining");
+  assert.equal(f[3].bindings.b.status, "Returned");
+  assert.equal(f[3].projections, 0);
+  assert.equal(f[5].projections, 1);
+  assert.equal(f[0].bindings.b.status, "Bound");
+});
+test("cell retirement and reclamation preserve earlier snapshots", () => {
+  const f = buildReplay([
+    event("cell_allocated", { cell_id: "c1", lifecycle: "active" }),
+    event("lifecycle_transition", {
+      cell_id: "c1",
+      previous: "active",
+      current: "retired",
+    }),
+    event("cell_reclaimed", { cell_id: "c1" }),
+  ]);
+  assert.equal(f[0].cells.c1.lifecycle, "active");
+  assert.equal(f[1].cells.c1.lifecycle, "retired");
+  assert.deepEqual(f[2].cells, {});
+});
+test("failed reads, cache reuse, and cancellation do not create projections", () => {
+  const f = buildReplay([
+    event("binding_active", { binding_id: "b", source: "calculator" }),
+    event("external_refresh_started", { binding_id: "b", work_key: "w" }),
+    event("external_refresh_ready", { binding_id: "b", success: false }),
+    event("external_refresh_cancelled", { work_key: "w" }),
+    event("cache_hit", { binding_id: "b" }),
+  ]);
+  assert.equal(f[2].bindings.b.status, "Failed");
+  assert.equal(f[3].bindings.b.status, "Cancelled");
+  assert.equal(f[4].bindings.b.status, "Cached evidence");
+  assert.equal(f[4].projections, 0);
+});
+test("Display snapshots remain distinct from convergence and final status", () => {
+  const f = buildReplay([
+    event("model_step_finished", {
+      display_materialized_text: "12.",
+      display_token_ids: [1, 2],
+      converged: true,
+    }),
+    event("model_step_finished", {
+      display_materialized_text: "12",
+      display_token_ids: [1],
+      converged: false,
+    }),
+    event("trajectory_finished", { converged: false }),
+  ]);
+  assert.equal(f[0].done, false);
+  assert.equal(f[1].previousDisplay.text, "12.");
+  assert.equal(f[1].display.text, "12");
+  assert.equal(f[2].model, "Stopped");
+  assert.equal(f[2].done, true);
+  assert.deepEqual(f[2].bindings, {});
+});
+test("empty and unknown events are safe; no fictitious cells or bindings", () => {
+  assert.deepEqual(buildReplay([]), []);
+  const [f] = buildReplay([event("future_runtime_event", { cell_id: "x" })]);
+  assert.deepEqual(f.cells, {});
+  assert.deepEqual(f.bindings, {});
+});

tests/test_mechanism.py

@@ -0,0 +1,35 @@
+import html
+import json
+from html.parser import HTMLParser
+
+from cid_demo.mechanism import mechanism_html, replay_document
+
+
+class FrameParser(HTMLParser):
+    def handle_starttag(self, tag, attrs):
+        if tag == "iframe":
+            self.attrs = dict(attrs)
+
+
+def test_full_trace_and_markup_are_isolated():
+    value = '</script><img src=x onerror="alert(1)"> & /* REPLAY_JS */'
+    events = [{"step": 0, "timestamp_s": 0, "kind": "model_step_finished",
+               "payload": {"display_materialized_text": value, "long": "x" * 6000}}]
+    frame = FrameParser()
+    frame.feed(mechanism_html(events, prompt=value, final_text=value))
+    assert frame.attrs["sandbox"] == "allow-scripts"
+    doc = frame.attrs["srcdoc"]
+    data = doc.split('<script id="replay-data" type="application/json">', 1)[1].split("</script>", 1)[0]
+    parsed = json.loads(data)
+    assert parsed["events"] == events
+    assert parsed["prompt"] == value
+    assert parsed["final_text"] == value
+    assert "<img" not in doc
+    assert "onerror" in data  # Preserved as text, never trusted markup.
+
+
+def test_empty_trace_has_disabled_controls_and_no_demo_trajectory():
+    doc = replay_document()
+    assert 'id="play" class="primary" disabled' in doc
+    assert '"events":[]' in doc
+    assert 'No cells recorded yet' in doc