fix(viewer): render chronicle narration exactly once, in order, via a stable key (#405)

[100yenadmin]

The bug (live full-arc playtest — MAJOR)

In the OpenWorlds Chronicle panel, DM narration appeared 4+ times and out of chronological order during a multi-beat session ("Opening narration appears 3 times"; "narrations 4+ times, entries out of chronological order").

Root cause

The chronicle reconciled its two live narration sources by TEXT, which is fragile:

• /events tails the engine session log (sessions/<sid>.jsonl), where the DM streams each paragraph mid-turn via log_event(kind="narration") — one line per paragraph (the [playtest][P0] Per-beat DM latency (~60-90s) with no streaming → impatient players give up mid-session #393 give-up fix). recentEvents (the history band) is the same file's trailing window.
• /chat tails a separate file (<run>.chat.jsonl), one {"role":"dm","text":RESULT} line per turn — the DM's whole reply, often the entire turn's prose as one blob.

The existing dedup (claimNarration / dedupedRecent, whitespace+case-normalized text key) broke two ways:

1. Reword — the DM rewording its turn-END /chat reply hashes differently from the streamed copy, so the beat shows twice. The DM skill (skills/dungeon-master/SKILL.md line 66) explicitly warns "a reworded reply defeats the de-dup and the player sees the beat twice." We can't stop the LLM rewording (the skill is out of scope).
2. Blob-vs-paragraph — even verbatim, the /chat blob's key (the whole turn) matches no single /events paragraph key, so the whole turn renders again after its paragraphs already streamed = "opening appears 3 times".

Ordering broke because the two sources interleaved (a turn's /chat blob lands after a later beat's paragraphs already streamed).

The fix — render each beat EXACTLY ONCE, in order, by a STABLE key

• Stable key, not text. The server now stamps every /events entry (and the recentEvents band) with its absolute session-log line index as seq — the engine's sole-writer per-beat identity, independent of the prose. Purely additive (server.py: _read_events, _session_event_tail_from_dir, _session_recent_events).
• One canonical source per beat. /events (the session log) is the canonical live-narration source; dedup + ordering key off seq. A /chat DM line is a turn-resolution signal (it still clears the "narrating…" indicator) but adds no narration row when the current turn streamed via /events. It renders narration only as a per-turn fallback when nothing streamed (a terse turn, or the human/native path where /chat is the sole source) — text-keyed, since a chat-only beat has no seq and there is no /events stream to collide with.
• Chronological by seq. Live narration now shares the session-log line order, so the two sources structurally cannot interleave out of order.
• Re-ingest immunity. A windowing re-mount or a session-rotation cursor rewind re-reads the same line; keyed by seq, it collapses to one row.
• The chronicle merge/dedup/order is extracted to a pure, exported buildChronicleLog so the contract is unit-testable.

Why not a fully shared id across both files?

/chat is a different file written by the runner/skill (out of scope — wire contracts and the DM lane are owned elsewhere). A truly shared beat-id would need the runner to correlate both files. The "one canonical source + idempotent other" design (the task's preferred option) achieves exactly-once without that bigger change, so it is the right minimal fix.

How I verified (actually exercised, not just read)

• 8 new tests, single-process (extend the existing real-.jsx-via-Babel+Node harness + the server import test):
  • reword does not duplicate a streamed beat; /chat blob does not duplicate the per-paragraph stream; same-seq re-ingest shown once; chronicle orders by session-log seq; a terse turn after a streamed turn still renders; recentEvents deduped against the live tail by seq; /events + recentEvents carry monotonic absolute seq (stable across polls). Each duplication test is red before / green after.
• Live server over HTTP (booted on :8880, seeded session log): /events and /session-surface both carry seq on the wire; the cursor-advance poll returns absolute seq (not reset), and a freshly-appended line gets the next absolute index.
• End-to-end render through the real transpiled useLiveSession + buildChronicleLog: the full multi-beat scenario (3 streamed paragraphs + a mechanics row + a reworded /chat blob + a windowing re-ingest + the recentEvents band, all carrying the same beats) renders exactly 3 narration rows, in order, pending cleared, the mechanics row preserved.
• Full viewer suite green: 208 passed, 1 skipped (single-process, -p no:xdist). license_check clean.

Scope / invariants

Viewer-only (viewer/openworlds/*.jsx + a minimal additive seq stamp in viewer/server.py). The engine stays the sole writer (seq is a pure read-projection of the line index it already wrote); no DM-skill / --resume / persist_beat / wire-contract changes. Windowing (≤50 rows), the bounded live tail, and auto-scroll are unchanged. _private/ untouched.

Do NOT close on merge — verify on the next full-arc playtest.

Summary by CodeRabbit

• New Features

  • Introduced stable sequence-based deduplication for narration entries across live event streams and chat responses.

• Bug Fixes

  • Fixed duplicate narration appearing in live session chronicles (issue #405).
  • Resolved inconsistent narration ordering between streamed and chat-delivered content.

• Tests

  • Added regression tests validating narration deduplication and chronological ordering in live sessions.

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR implements stable seq-based deduplication for narration across server and client. The server stamps absolute line indices into session log events; the client uses those seq values to deduplicate narration between recentEvents and live feeds, suppress /chat when /events already streamed per-turn, and order chronicle entries canonically.

Changes

Narration Seq-Based Deduplication and Reconciliation

Layer / File(s)	Summary
Server-side seq stamping into session events viewer/server.py	_session_recent_events, _session_event_tail_from_dir, and _read_events now compute and stamp stable integer seq values (absolute line indices within the session log) into each event dict, enabling consistent seq-keyed deduplication on the client.
Client-side chronicle helper extraction and integration viewer/openworlds/screen-table.jsx	New pure function buildChronicleLog merges recentEvents, live chat beats, and local log entries into an ordered/deduped chronicle using seq keys (fallback to sanitized narration text). ScreenTable replaces inline merge/sort/dedup logic with calls to buildChronicleLog.
Live session narration dedup and /chat suppression viewer/openworlds/app.jsx	useLiveSession introduces dual dedup sets (seq-keyed and text-fallback), a per-turn flag tracking whether /events has streamed narration, and suppresses /chat narration when the turn has already streamed via /events. The per-turn flag resets on /chat DM arrival so later terse turns can still render /chat-only prose.
Test infrastructure and seq/dedup validation viewer/tests/test_session_surface.py, viewer/tests/test_live_narration_stream.py	New test helpers (_env context manager, chronicleNarration/chronicle accessors) and regression test suite (#405) validate seq stamping stability across server projections, seq-based deduplication, per-turn suppression, chronicle ordering, and dedup across recentEvents history and live tail.

Sequence Diagram(s)

sequenceDiagram
  participant EventsFeed as /events Feed
  participant AppSession as useLiveSession
  participant ChatFeed as /chat Poll
  participant Dedup as Dedup Sets<br/>(seenSeq, seenText)
  participant TurnFlag as eventsStreamedThisTurnRef
  
  EventsFeed->>AppSession: stream narration row
  AppSession->>Dedup: claim by seq or text fallback
  alt narration not seen
    Dedup-->>AppSession: accepted
    AppSession->>TurnFlag: mark = true
    AppSession-->>EventsFeed: render narration beat
  else narration already deduped
    Dedup-->>AppSession: rejected
  end
  
  ChatFeed->>AppSession: DM line (turn resolution)
  alt TurnFlag is true
    AppSession-->>ChatFeed: suppress narration
  else TurnFlag is false
    ChatFeed->>Dedup: claim narration text
    alt text not seen
      Dedup-->>ChatFeed: accepted
      ChatFeed-->>AppSession: render narration
    end
  end
  
  ChatFeed->>AppSession: DM arrive signal
  AppSession->>TurnFlag: reset = false

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

• electricsheephq/WorldOS#394: Extends the prior live-session narration merge logic in app.jsx and screen-table.jsx from text-key dedup to stable seq-based canonicalization for reconciling /events and /chat narration.
• electricsheephq/WorldOS#349: Updates sanitizeNarration function that is now invoked by the new buildChronicleLog helper to strip DM scaffolding from narration text.
• electricsheephq/WorldOS#128: Introduces the /session-surface log/read-model and recentEvents plumbing that this PR builds on for seq-based chronicle merging and server projection stamping.

Poem

🐰 A tale of narration, twice-told no more,
Seq marks each whisper at the session door.
Events stream freely, Chat claims the turn,
Dedup keys spin—no duplicates churn.
One truth, one order, one chronicle song! 🎭

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (1 warning, 1 inconclusive)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 16.67% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.
Description check	❓ Inconclusive	The description is comprehensive, covering the bug, root cause, fix strategy, verification, and scope. However, it is missing the required CLA and validation checkboxes from the template.	Complete the description template by checking the CLA checkbox, confirming no confidential data was included, and listing all validation checks performed.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and specifically summarizes the main fix: using a stable key (seq) to render chronicle narration exactly once and in order, directly addressing issue #405.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

🧹 Nitpick comments (2)

viewer/openworlds/app.jsx (1)

461-461: 💤 Low value

Missing claimNarrationSeq in useEffect dependencies.

claimNarrationSeq is called inside pollOnce (line 429) but is not listed in the dependency array. While it's stable (empty deps on the useCallback), this inconsistency with claimNarration being listed could trigger exhaustive-deps warnings and is a minor code smell.

🔧 Suggested fix

-  }, [campaignId, source, runId, notePendingProgress, claimNarration]);
+  }, [campaignId, source, runId, notePendingProgress, claimNarration, claimNarrationSeq]);

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@viewer/openworlds/app.jsx` at line 461, Add claimNarrationSeq to the
useEffect dependency array that currently lists [campaignId, source, runId,
notePendingProgress, claimNarration]; the function pollOnce (which calls
claimNarrationSeq) should have claimNarrationSeq included to match its usage and
the stable callback signature—update the dependency array accordingly so it
reads include claimNarrationSeq alongside the existing dependencies.

viewer/tests/test_live_narration_stream.py (1)

528-528: 💤 Low value

Optional: Replace ambiguous multiplication sign with 'x'.

Static analysis detected an ambiguous × (MULTIPLICATION SIGN) character. Consider using 'x' or the phrase "3-4 times" for clarity.

Suggested fix

-    # `#405`: the narration-DUPLICATION regression fix. The chronicle showed DM narration 3-4× and
+    # `#405`: the narration-DUPLICATION regression fix. The chronicle showed DM narration 3-4x and

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@viewer/tests/test_live_narration_stream.py` at line 528, Replace the
ambiguous MULTIPLICATION SIGN in the comment string "the chronicle showed DM
narration 3-4× and" with a clear character or word (e.g., "3-4x" or "3-4 times")
so the comment in viewer/tests/test_live_narration_stream.py is unambiguous;
update the comment containing "narration 3-4×" accordingly.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@viewer/openworlds/app.jsx`:
- Line 461: Add claimNarrationSeq to the useEffect dependency array that
currently lists [campaignId, source, runId, notePendingProgress,
claimNarration]; the function pollOnce (which calls claimNarrationSeq) should
have claimNarrationSeq included to match its usage and the stable callback
signature—update the dependency array accordingly so it reads include
claimNarrationSeq alongside the existing dependencies.

In `@viewer/tests/test_live_narration_stream.py`:
- Line 528: Replace the ambiguous MULTIPLICATION SIGN in the comment string "the
chronicle showed DM narration 3-4× and" with a clear character or word (e.g.,
"3-4x" or "3-4 times") so the comment in
viewer/tests/test_live_narration_stream.py is unambiguous; update the comment
containing "narration 3-4×" accordingly.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: b4a84d23-a217-49c0-b507-4af78961e0d0

📥 Commits

Reviewing files that changed from the base of the PR and between 6310750 and 9ca4e38.

📒 Files selected for processing (5)

• viewer/openworlds/app.jsx
• viewer/openworlds/screen-table.jsx
• viewer/server.py
• viewer/tests/test_live_narration_stream.py
• viewer/tests/test_session_surface.py