@micha.bigler/ui-core-micha 3.14.4 → 4.0.1

package/work-orders/MSG-3c.md

@@ -1,378 +0,0 @@
-# MSG-3c — deliver the rows MSG-3b left blocked against a stale dcm version
-
-Status: planned · Tier 2 · Target repo: `ui-core-micha` (main)
-**Binding spec:** `django-core-micha/docs/design/messaging-platform.md`. Extends the landed MSG-3b
-(published ucm 2.17.0), same convention as `MSG-2b` / `MSG-2c` / `NOTIF-8b`.
-
----
-
-## Part A — Envelope (Expertenchat, 2026-07-31)
-
-### Goal
-
-Deliver the seven checklist rows MSG-3b correctly refused to fake — and which became buildable while
-MSG-3b was still running, without the session ever learning.
-
-### Why this WO exists
-
-MSG-3b started against dcm **2.36.1** and pinned that version explicitly in every BLOCKED entry of
-`docs/messaging-deviations.md`. dcm **2.37.0** (MSG-2c) landed mid-flight and delivered exactly what
-those entries said was missing. The WO closed — six chunks, per-chunk reviews, a clean WO-end
-`ui_reviewer` row-by-row cross-check — with seven rows recorded as blocked on "a future dcm work order"
-that had in fact already shipped.
-
-The WO-end review did not catch it because it cross-checked the checklist against **ucm's** landed code
-and took the dependency's state from the WO text. That is the third occurrence of one pattern in this
-workstream: a side verified against itself, with the seam assumed rather than read. See §5 of
-`notifications-messaging-roadmap.md`.
-
-**Credit where it is due, and the reason this was cheap to find:** MSG-3b wrote the dcm version into
-every BLOCKED entry. Without that pin the staleness would have been invisible instead of a two-minute
-check. Keep doing it — this WO makes it a rule.
-
-### Verified as deliverable against dcm 2.37.0
-
-Checked in `django-core-micha` at 2.37.0 before this WO was written:
-
-| Row | What MSG-3b recorded | Actual state in 2.37.0 |
-|---|---|---|
-| 38 | "dcm does not serialize `last_message`" | `serialize_last_message` exists; `last_message` is on the conversation payload |
-| 51 | "no poll read serialization" | `serialize_poll` exists, embedded in `serialize_message` for `kind == "poll"` |
-| 52 | "per-option voter names absent" | `voters` is in the poll projection (user ids, every conversation kind) |
-| 53 | "closed state depends on the absent poll contract" | `closed_at` is in the projection |
-| 56 | "dcm 2.36.1 does not emit `reaction`" | emitted (MSG-2c wired 8 frames) |
-| 57 | "dcm 2.36.1 does not emit `poll_updated`" | emitted |
-| 58 | "reorder/preview need the missing `last_message`" | available per row 38 |
-
-### Expected outcome
-
-The seven rows above delivered per the MSG-3b checklist's original descriptions:
-
-- **38 / 58** — real last-message preview in `ConversationList`, and list reorder plus preview refresh
-  on new / edited / deleted messages.
-- **51-53** — `PollCard` renders question, options, per-option `vote_count` and `voters`, closed state
-  with voting disabled. Read `voted_option_ids` **only** from the three poll REST responses; it is
-  deliberately absent from `serialize_poll` and from every realtime frame, so do not look for it there
-  and do not reconstruct it from a frame.
-- **56 / 57** — the existing `reaction` and `poll_updated` handlers stop being dead code; verify they
-  merge correctly now that frames actually arrive, rather than assuming the untested paths are right.
-- `docs/messaging-deviations.md` corrected: these seven entries move from BLOCKED to delivered, and the
-  closing paragraph stops claiming they need a future dcm WO.
-
-**Still legitimately BLOCKED, do not touch:** rows **27** (no readable thread reply state) and **42**
-(`external_key` not serialized). Both are real dcm gaps that MSG-2c did not cover; both are addressed by
-dcm `MSG-2d`, and a later ucm WO delivers them. MSG-3b assessed these two correctly.
-
-### The rule this WO adds
-
-**A BLOCKED row is re-verified against the live dependency at WO close, not at WO start.** Concretely:
-
-1. Every BLOCKED entry in `docs/messaging-deviations.md` must name the dependency version it was
-   blocked at — MSG-3b already did this; make it explicit policy.
-2. Extend the contract-conformance test from MSG-3b chunk 1: it must fail when a BLOCKED entry carries
-   no version pin. A test cannot check whether dcm has since shipped — it has no access to it — but it
-   can guarantee the pin exists, which is what makes the manual re-check a two-minute job instead of an
-   archaeology exercise.
-3. The WO-end review instruction changes: cross-check BLOCKED rows against the **dependency repo at its
-   current version**, not against the WO text.
-
-### Non-goals / do-not-touch
-
-Rows 27 and 42 (blocked on dcm `MSG-2d`). Any dcm change. Any app-side code. The jg migration (MSG-5).
-Search, typing, client→server WS. The decomposition and component boundaries established in MSG-3 and
-held through MSG-3b — new rendering lands in the component that owns it, and the ~400 LOC soft trigger
-and one-harness-entry-per-component rule stay in force. Do not re-open rows already delivered or
-already recorded as deliberate deviations.
-
-### Required tests to WRITE
-
-- **Poll rendering** against a server-shaped payload — the projection as `serialize_poll` actually emits
-  it, not a client-constructed object. This is the MSG-3b lesson repeated: the threading tests passed
-  for a year of nobody noticing precisely because they used client-shaped fixtures.
-- **`voted_option_ids` comes only from REST:** a `poll_updated` frame carrying no such key must not
-  clear or invert the viewer's own vote state.
-- **`reaction` / `poll_updated` frame merge:** an arriving frame updates the rendered message for a
-  viewer who did not cause it; a duplicate `event_id` changes nothing.
-- **Last-message preview and reorder:** a new message moves its conversation to the top and updates the
-  preview; an edit updates it; a delete empties it.
-- **Conformance test extension:** a BLOCKED entry without a version pin fails the build — assert the
-  negative case, not only the positive.
-- Existing ucm suites stay green.
-
-### Risks
-
-- **The dead handlers were never exercised.** Rows 56/57 are the paths most likely to contain latent
-  bugs, because they have never run against a real frame. Treat them as new code under test, not as
-  already-working code being unblocked.
-- **Fixture shape** — see the poll test above; the single most repeated failure in this workstream is a
-  test that passes because it invented its own payload.
-- Deviation-doc drift: correcting seven entries by hand while leaving two correct ones intact is exactly
-  where an over-eager edit removes a real blocker.
-
-### Preconditions
-
-dcm 2.37.0 published (met). Approval Gate #1 = operator go on this envelope. Rows 27/42 additionally
-require dcm `MSG-2d`, which is **not** a precondition for this WO.
-
-### Release
-
-One version bump + npm publish at WO end.
-
-### Execution directive
-
-Implement through `codex exec` in the background — invoked **directly via Bash** (never the
-`debugger`/`*_coder` Agent wrappers) with **both** flags `--skip-git-repo-check` and
-`--dangerously-bypass-approvals-and-sandbox`, prompt passed as a positional argument from a file;
-fall back to direct Claude implementation only on Codex quota / rate-limit / non-zero exit.
-
-### Mini-handover (pastable)
-
-Orchestrator: implement `work-orders/MSG-3c.md` in `ui-core-micha` (main). `git pull` first, read the WO
-+ `django-core-micha/docs/design/messaging-platform.md`, then follow `orchestrate-codex` (Codex-first,
-own review per chunk, `ui_reviewer` at WO end, one publish at WO end). Rows 27 and 42 stay BLOCKED —
-they wait on dcm `MSG-2d`.
-
----
-
-## Part B — Implementation map (Orchestrator)
-
-**Target repo working directory (all chunks):** `C:\Users\biglmi\Documents\webapps\ui-core-micha` (repo
-root). **Chunk plan (Orchestrator's own — the envelope named rows, not chunks):**
-
-1. Last-message preview + reorder (rows 38, 58).
-2. Poll rendering (rows 51-53).
-3. Reaction/poll_updated frame-merge fixes (row 56/57 verification) + the conformance-test extension +
-   the deviation-doc rewrite for all seven rows.
-
-**Verified against dcm 2.37.0 while scoping** (do not re-derive these, they're settled): `serialize_last_message`/
-`serialize_conversation_core` (`django-core-micha/src/django_core_micha/messaging/serializers.py:89-113`),
-`serialize_poll`/`serialize_reactions` (`serializers.py:41-46,52-64`), `_poll_response` — the ONLY place
-`voted_option_ids` is added, view-level, on top of `serialize_poll` (`views.py:32-36`, used by the
-create/vote/close poll responses only — never by `serialize_message`'s embedded poll, never by the
-`poll_updated` frame), and the three `conversation_upsert` publish sites (`services.py:95,120,165` —
-**new-message send only**; `edit_message`/`soft_delete_message` publish `message_edited`/`message_deleted`
-but never `conversation_upsert`, so a background conversation's list preview cannot live-update on an
-edit/delete of its last message without a dcm change — out of scope, verify via REST refresh instead,
-per chunk 1 below, do not invent a frame dcm doesn't send).
-
-**Two additional bugs found during this scoping, in files this WO already touches — fix them here rather
-than filing separately:**
-- `MessagingProvider.jsx:144` (`applyFrame`'s `message_edited` case): `mergeById(state.messages, payload)`
-  where `payload` (no `.message` sub-key on this frame — it only ever carries `message_id`) falls through
-  to the raw `frame` object, and `idOf()` (`MessagingProvider.jsx:45`, `item?.id ?? item?.conversation_id
-  ?? item?.message_id ?? item?.poll_id`) checks `.conversation_id` **before** `.message_id` — every frame
-  envelope carries `conversation_id`, so a `message_edited` frame gets keyed into the cache by the
-  conversation's id instead of the message's id, silently creating a bogus cache entry and never touching
-  the real message. Zero test coverage anywhere in this repo caught it. Fix in chunk 1 (same file as the
-  conversation-preview work): merge with an explicit `id: frame.message_id`, not the `idOf` fallback chain.
-- `MessagingProvider.jsx:315-330` (`toggleReaction`) and the `reaction` frame case (`:145-149`): `serialize_reactions`
-  (verified above) returns `[{emoji, count}]` **only, never a per-viewer `reacted` flag, ever** — not in
-  REST responses, not in frames, by design (aggregate-only). `toggleReaction`'s optimistic update
-  correctly sets `reacted: true/false` locally on the user's own click, but then the REST-confirm step
-  (`:327`, `reactions: result?.reactions || ...`) and the frame handler (`:148`, `payload.reactions ||
-  frame.reactions || ...`) both prefer the server's `reacted`-less array over the optimistic one — so
-  confirming the user's own toggle, or literally any other viewer's reaction frame arriving for the same
-  message, silently wipes every emoji's locally-known `reacted` state. This is exactly what row 56 asks
-  to be verified rather than assumed. Fix in chunk 3 (bundled with the frame-merge verification, same
-  underlying fix in both places): merge the server's `{emoji,count}` list with previously-known `reacted`
-  flags by emoji key, never wholesale-replace.
-
-### Chunk 1 — last-message preview and conversation reorder (rows 38, 58)
-
-**Files:** `src/messaging/MessagingProvider.jsx` (the `message_edited` bug fix above; verify — do not
-rebuild — the existing `conversation_upsert` handling at `:160` and `EMPTY_CACHE`/reducer shape),
-`src/messaging/ConversationList.jsx` (verify — likely no change needed, see below), new tests.
-
-**Much of rows 38/58 turns out to already be built.** MSG-3b wrote `applyFrame`'s `conversation_upsert`
-case and `ConversationList`'s `last_message?.body` rendering + `last_message_at` sort defensively,
-against the design doc's frame contract, before dcm actually sent the data. Now that dcm 2.37.0 does
-(`conversation_upsert` on new-message send carries the real `serialize_conversation_core`, including
-`last_message`), this is primarily a **verification + test-writing chunk**, not a rebuild — confirm this
-by reading `ConversationList.jsx:11` (`ordered()`, sorts by `last_message_at`) and `:71`
-(`conversation.last_message?.body`) before writing anything new. If you find either needs a real change
-beyond the `message_edited` fix above, make it — but don't assume a rewrite is needed without checking.
-
-**Row 58's "an edit updates it; a delete empties it"** must be tested via **REST refresh**
-(`refreshConversations()`), not a live frame — dcm does not publish `conversation_upsert` on edit/delete
-(see the verified call-site list above). `serialize_last_message` (`serializers.py:89-97`) already
-returns `excerpt: ""` for a deleted last message — that's the server behavior a refresh test should
-assert against, mocked with a server-shaped `listConversations` response, not invented.
-
-**Required tests (chunk 1):**
-- A `conversation_upsert` frame with a real `last_message` moves that conversation to the top of
-  `ConversationList` and updates its preview text — server-shaped fixture (`last_message: {body, ...}`,
-  not a client-invented shape).
-- A REST refresh reflecting an edited last message updates the preview; reflecting a deleted one
-  (`last_message.excerpt: ""` — check the actual field name your fixture should use, verify against
-  `serialize_last_message`'s real key, which is `excerpt` not `body`, at the `last_message` level —
-  don't assume the `Conversation.last_message` shape matches `Message`'s own `body` field name) shows
-  the empty/no-preview state.
-- The `message_edited` frame-keying regression: a `message_edited` frame with only `{message_id,
-  conversation_id}` (the real minimal shape — verified above, it carries no other fields) must patch the
-  message keyed by `message_id`, and must NOT create/touch any cache entry keyed by `conversation_id`.
-- Existing ucm suites stay green.
-
-**Progress contract / preamble:** identical to MSG-3b's chunks — `PLAN:`/`PROGRESS:`/`RESULT:` lines, no
-git operations, write-and-run-only-the-new-tests, leave the diff uncommitted for the orchestrator's
-review.
-
-**Mini-handover:** repo `C:\Users\biglmi\Documents\webapps\ui-core-micha`, branch `main`, WO
-`work-orders/MSG-3c.md` chunk 1 (Part B above). Follow `orchestrate-codex`.
-
-**Note on chunk 1's actual execution:** Codex reported `workspace is out of credits` on invocation
-(not a transient rate limit) — the orchestrator implemented chunk 1 directly per the Codex→Claude
-fallback rule, and an independent reviewer ran (mandatory once the orchestrator is the author). Chunks
-2/3 below should still attempt Codex first per the execution directive, but expect the same
-out-of-credits failure and fall back the same way if it recurs — don't loop retrying it.
-
-### Chunk 2 — poll rendering (rows 51-53)
-
-**Files:** `src/messaging/PollCard.jsx` (all three rows land here), new tests. `PollCard.jsx` was built
-in MSG-3 speculatively, before dcm's poll read contract existed — it guesses at field names, and two of
-those guesses are confirmed wrong against the real server shape.
-
-**Verified against dcm 2.37.0 (`django-core-micha/src/django_core_micha/messaging/serializers.py:52-64`,
-`views.py:32-36`):** `serialize_poll` returns `{id, question, allow_multiple, closed_at, created_by_id,
-options: [{id, text, order, vote_count, voters}]}` — `voters` is an array of user ids (row 52).
-`voted_option_ids` is added **only** by `_poll_response` (`views.py:32-36`), a view-level enrichment
-used **only** by the create/vote/close poll REST responses — it is never in `serialize_poll` itself,
-never in `serialize_message`'s embedded poll (message list/thread loads), and never in the
-`poll_updated` realtime frame. This is the WO's explicit "read `voted_option_ids` only from the three
-poll REST responses" instruction, now with the exact citations.
-
-**Two confirmed bugs in `PollCard.jsx` against this real shape — fix both:**
-1. `PollCard.jsx:18` — `const creatorId = poll.created_by?.id ?? poll.created_by;` assumes a
-   `created_by` object or scalar; the real field is `created_by_id` (a plain id, verified above).
-   `poll.created_by` is always `undefined` against the real server, so `creatorId` is always
-   `undefined`, so `canClose`'s only non-host-supplied fallback (`creatorId === currentUser?.id`,
-   `:19`) can never be true for a genuine creator — close is effectively broken for every poll unless a
-   host explicitly passes `canClose`. Fix: read `poll.created_by_id` directly.
-2. `PollCard.jsx:15` — `useEffect(() => setSelected((poll?.options || []).filter((option) =>
-   option.selected || option.voted)...` assumes per-option `selected`/`voted` flags that don't exist
-   anywhere in the real projection (verified above: options only ever have `{id, text, order,
-   vote_count, voters}`). Selection must instead derive from `poll.voted_option_ids` **when present**
-   (only true right after a create/vote/close REST call — the WO's explicit constraint) and otherwise
-   default to empty (a poll loaded via `listMessages`/`listThread`, or updated via a `poll_updated`
-   frame, correctly has no way to know the current viewer's vote state from that payload alone — do not
-   guess, do not carry over stale local state across a payload that structurally cannot contain the
-   answer).
-
-**Row 52 (voters) — not rendered at all today:** add voter identification per option. dcm only gives
-user **ids** (`option.voters: [user_id, ...]`), never names — there is no user-directory endpoint
-(same constraint already established for the DM candidate list in `MSG-3b`). Render what's actually
-available: a count (`voters.length`) is always correct; showing the *current viewer's own* vote as
-"you voted for this" is derivable from `voted_option_ids` after a REST action, or otherwise left
-unmarked. Do not invent a name lookup — this is a real, structural limit of the dcm contract, not
-something to work around client-side. If host-supplied user resolution is later wanted, that is a
-future WO's host-prop pattern, not this chunk's job.
-
-**Row 53 (closed state, voting disabled)** — `PollCard.jsx:17` (`const closed =
-Boolean(poll.closed_at)`) is already correct; verify the disabled-while-closed wiring on the vote
-controls (`:32`) still works once selection is correctly derived from `voted_option_ids`, and add
-coverage — this row was previously untested against a real payload shape too.
-
-**Required tests (chunk 2):**
-- Poll rendering against a genuinely server-shaped `serialize_poll` payload (all the real keys above,
-  not a client-invented one) — question, options, `vote_count`, some indication of `voters`.
-- `voted_option_ids` present only in the vote/create/close REST response correctly drives selection
-  state; a `poll_updated` frame carrying no `voted_option_ids` key must not clear or invert the
-  viewer's own already-known vote state (this is the WO's explicitly named required test).
-- Close permission: `created_by_id === currentUser.id` correctly enables the close control; a
-  non-creator without a host-supplied `canClose` override does not get it.
-- Closed poll disables voting.
-- Existing ucm suites (chunk 1 inclusive) stay green.
-
-**Progress contract / preamble:** identical to chunk 1's — `PLAN:`/`PROGRESS:`/`RESULT:` lines, no git
-operations, write-and-run-only-the-new-tests, leave the diff uncommitted for the orchestrator's review.
-
-**Mini-handover:** repo `C:\Users\biglmi\Documents\webapps\ui-core-micha`, branch `main`, WO
-`work-orders/MSG-3c.md` chunk 2 (Part B above, after chunk 1 is committed). Follow `orchestrate-codex`.
-
-**Note from chunk 2:** the same defect class row 56/57 ask to be verified for (a `poll_updated`/
-`reaction` frame's viewer-independent projection silently wiping viewer-specific state the client
-learned from a REST response) was ALSO found and fixed in `poll_updated`'s handler while writing
-chunk 2's own tests (`MessagingProvider.jsx`'s `poll_updated` case now preserves a previously-known
-`voted_option_ids` when the incoming frame lacks it). Chunk 3 must check whether the `reaction` case
-has the analogous issue — it very likely does (see below), don't assume it's fine because it's a
-similar shape to the code that turned out to be wrong.
-
-### Chunk 3 — reaction frame-merge fix, conformance-test extension, deviation-doc rewrite (rows 56, 57 + the WO's new rule)
-
-**Files:** `src/messaging/MessagingProvider.jsx` (`applyFrame`'s `reaction` case, and `toggleReaction`'s
-REST-confirm path — same underlying bug, two call sites), `tests/messagingContractConformance.test.js`
-(the version-pin extension), `docs/messaging-deviations.md` (full rewrite of the seven now-delivered
-rows + the two still-BLOCKED rows, each BLOCKED entry now carrying an explicit version pin), new tests.
-
-**The reaction bug — verified, not hypothetical:** `django-core-micha/src/django_core_micha/messaging/serializers.py:41-46`
-(`serialize_reactions`) returns `[{emoji, count}]` **only, never a per-viewer `reacted` flag, in any
-context** — not REST, not frames, by design (the design doc's "aggregate only" rule). `MessagingProvider.jsx`'s
-`toggleReaction` (around `:315-330`) correctly sets `reacted: true/false` optimistically on the current
-user's own click, but then:
-- its own REST-confirm step merges `reactions: result?.reactions || result?.message?.reactions ||
-  nextReactions` — `result.reactions` (the real server array) is truthy and picked first, wiping the
-  optimistic `reacted` flags for every emoji on that message.
-- `applyFrame`'s `reaction` case (`:154` area) merges `reactions: payload.reactions || frame.reactions
-  || previous.reactions || []` — same problem: any `reaction` frame arriving for this message (the
-  user's own echoed toggle, or literally any other viewer reacting with a different emoji) wholesale-
-  replaces the reactions array with the server's `reacted`-less version, wiping every previously-known
-  `reacted` flag on that message, not just the one that changed.
-
-**Fix both call sites the same way:** merge the server's `{emoji,count}` list with previously-known
-`reacted` flags by emoji key — never wholesale-replace. For each emoji in the incoming server list, if
-a previous entry for that same emoji had `reacted: true`, carry it forward (unless this merge IS the
-direct result of the current user's own toggle action, in which case the just-computed optimistic value
-is correct and already known — don't let the REST-confirm step regress what the optimistic update just
-set). An emoji present in the previous list but absent from the incoming one means its count hit zero
-and it should simply not appear (matches the existing pattern at `:320`, `.filter((reaction) =>
-reaction.count !== 0)`).
-
-**Required tests (chunk 3, reaction part):**
-- A `reaction` frame for an emoji the viewer has NOT reacted with updates its count without touching
-  the viewer's `reacted` state on any OTHER emoji on the same message (the WO's explicitly named "an
-  arriving frame updates the rendered message for a viewer who did not cause it" case).
-- The viewer's own optimistically-set `reacted: true` on one emoji survives (a) the REST confirmation
-  of that same toggle, and (b) an unrelated `reaction` frame for a different emoji on the same message
-  arriving afterward.
-- A duplicate `event_id` changes nothing (verify the existing `seenEventsRef` de-dup in the provider's
-  `subscribe(...)` handler already covers this at the reducer-dispatch level — this may already be
-  correct and just need a test, not a code change; check before assuming otherwise).
-
-**Conformance-test extension (the WO's new rule, required, not optional):** add a check to
-`tests/messagingContractConformance.test.js` that reads `docs/messaging-deviations.md` and fails if any
-line containing `**BLOCKED**` does not also carry an explicit dependency-version pin (e.g. a regex for
-`dcm \d+\.\d+\.\d+` on that line or within its paragraph — check the actual final wording you land on
-in the doc rewrite below and match the regex to it, don't write the regex first and hope the prose
-matches). **Verified: this check does not currently exist, and would currently fail** — as of this
-WO's start, rows 27/38/42/51/52/53/58's `**BLOCKED**` lines in `docs/messaging-deviations.md` do NOT
-carry a version pin (only the doc's intro sentence and rows 56/57 happen to mention "dcm 2.36.1"); only
-rewriting the doc's BLOCKED rows to each name the version fixes this. **Required negative-case test**
-(the WO is explicit: "assert the negative case, not only the positive"): construct a small in-memory
-BLOCKED line missing a version pin and assert the check's own logic flags it — don't only test that the
-real file passes, prove the check can fail.
-
-**`docs/messaging-deviations.md` rewrite — the WO's central deliverable for this chunk:**
-- Rows 38, 51, 52, 53, 56, 57, 58 move from `BLOCKED` to their real delivered outcome (`OK`, matching
-  the pattern MSG-3b's own doc used for delivered rows) — each entry should reflect what was actually
-  built across chunks 1-3 of MSG-3c (last-message preview/reorder, poll rendering incl. the
-  `created_by_id`/`voted_option_ids` fixes, the `reaction`/`poll_updated` frame-merge fixes), not a
-  generic "delivered" note copy-pasted seven times.
-- Rows **27 and 42 stay BLOCKED** — do not touch their substance, only add the now-required version pin
-  if missing (e.g. "as of dcm 2.37.0" or whatever phrasing matches the new conformance-test regex).
-  These are real, still-open gaps (thread-receipt read state; `external_key` serialization) waiting on
-  a future dcm `MSG-2d`.
-- The closing "Required backend follow-up" paragraph (currently lists rows 27/38/42/51-53/56-58 as all
-  needing a future dcm WO) must be corrected to name only rows 27 and 42.
-- **Risk named in the WO, read before editing:** "correcting seven entries by hand while leaving two
-  correct ones intact is exactly where an over-eager edit removes a real blocker" — do not touch rows
-  27/42's substantive claims, only add the version pin to them if the doc rewrite's new house style
-  requires it project-wide.
-
-**Progress contract / preamble:** identical to prior chunks — `PLAN:`/`PROGRESS:`/`RESULT:` lines, no
-git operations, write-and-run-only-the-new-tests, leave the diff uncommitted for the orchestrator's
-review.
-
-**Mini-handover:** repo `C:\Users\biglmi\Documents\webapps\ui-core-micha`, branch `main`, WO
-`work-orders/MSG-3c.md` chunk 3 (Part B above, after chunk 2 is committed) — the WO's last content
-chunk. After this chunk's independent review and commit, run the WO-end `ui_reviewer` pass per the
-WO's changed instruction (cross-check BLOCKED rows against the dependency repo at its **current**
-version, not against the WO text), then one version bump + npm publish.

package/work-orders/MSG-3d.md

@@ -1,268 +0,0 @@
-# MSG-3d — the last two blocked rows: unread-reply marker and managed-conversation identity
-
-Status: planned · Tier 2 · Target repo: `ui-core-micha` (main)
-**Binding spec:** `django-core-micha/docs/design/messaging-platform.md` — §"Thread reply state and
-managed-conversation identity" and §Realtime's consumer obligation. Extends the landed MSG-3c
-(published ucm 2.18.0), same convention as `MSG-2b` / `MSG-3b` / `MSG-3c`.
-
----
-
-## Part A — Envelope (Expertenchat, 2026-08-01)
-
-### Goal
-
-Deliver checklist rows **27** and **42** — the last two entries still marked BLOCKED in
-`docs/messaging-deviations.md`. dcm 2.38.0 (MSG-2d) shipped the contract they were waiting for, on the
-same day MSG-3c closed. After this WO the deviation doc has **zero** BLOCKED entries.
-
-### Verified deliverable against dcm 2.38.0
-
-Checked in `django-core-micha` before this WO was written (`serializers.py`):
-
-| Row | Was blocked on | Present in 2.38.0 |
-|---|---|---|
-| 27 | no readable thread reply state | `reply_count` + `last_reply_at` on `serialize_message` (viewer-independent), `thread_last_read_at` added REST-only |
-| 42 | `external_key` not serialized | `external_key` on `serialize_conversation_core` |
-
-### Expected outcome
-
-**Row 27 — unread-reply marker on the thread toggle.** Render the marker when
-`last_reply_at > thread_last_read_at`; a `null` receipt with at least one reply counts as unread; no
-replies means no toggle and no marker. `reply_count` gives the toggle its count without expanding the
-thread. Opening a thread marks it read and updates the receipt **from the REST response** to
-`POST messages/{root_id}/thread/read/` — not from a frame, which cannot carry it.
-
-**Live root update on an incoming reply.** A new reply arrives as a `message` frame carrying *the
-reply's* projection — its own `reply_count` is 0 and `last_reply_at` null. Nothing in the frame updates
-the **root's** counters, so without explicit handling the marker only appears after the next refetch.
-jg updates the root live (`Thread.jsx:1488-1537`: increments `reply_count` and marks the thread unread
-when the sender is someone else), so parity requires the same here: on a `message` frame whose
-`reply_to_id` names a cached root, increment that root's `reply_count` and advance its `last_reply_at`.
-This was a gap in the first draft of this envelope, surfaced by review — do not leave it to discovery.
-
-**Row 42 — distinguish managed conversations.** Surface `external_key` so a host can tell one managed
-conversation from another. **ucm must not know what the values mean.** `event_all` and `event_team` are
-jg's vocabulary, not the platform's; baking them in would put app-specific code in a consumer-agnostic
-package and break the first non-jg adopter. Expose the value and let the host supply label and icon,
-mirroring the existing `groupLaunchers` host-supplied pattern.
-
-**Deviation doc.** Rows 27 and 42 move from BLOCKED to delivered. The doc then contains no BLOCKED
-entries at all — confirm MSG-3c's version-pin conformance check still passes on an empty set rather
-than erroring or vacuously "passing" for the wrong reason.
-
-### The trap this WO walks into — read before writing any merge code
-
-`thread_last_read_at` is **viewer-specific and REST-only**. `reply_count` and `last_reply_at` ride
-`serialize_message`, which is embedded verbatim into the `message` and `message_edited` frames. So every
-such frame carries a message projection **with** the reply fields and **without** the receipt.
-
-That is precisely the defect shape MSG-3c just fixed three times (`poll_updated`'s `voted_option_ids`,
-the `reaction` frame's `reacted` flags, `toggleReaction`'s REST confirm): a viewer-independent
-projection replacing a cached object and silently wiping viewer-specific state. This WO introduces a
-**fourth field of that shape**, arriving immediately after those fixes. Merge field-wise, preserve
-`thread_last_read_at`, never replace the message object wholesale — the contract obligation is now
-written into design §Realtime. It has a mandatory test below.
-
-### Non-goals / do-not-touch
-
-Any dcm change. Any app-specific vocabulary in ucm (see row 42). App-side code, the jg migration
-(MSG-5), search, typing, client→server WS. The component boundaries from MSG-3 — the marker belongs to
-whichever component owns the thread toggle, not to a regrown `Thread`; the ~400 LOC soft trigger and
-one-harness-entry-per-component rule stay in force. Do not re-open rows already delivered or already
-recorded as deliberate deviations.
-
-### Required tests to WRITE
-
-- **The merge trap (load-bearing):** a `message` and a `message_edited` frame — **server-shaped, copied
-  from real `serialize_message` output**, therefore without `thread_last_read_at` — must leave a
-  previously-fetched receipt intact. Assert the cached value after the merge, not just that no error
-  was thrown.
-- **Marker logic:** shown when `last_reply_at > thread_last_read_at`; hidden when the receipt is equal
-  or newer; shown when the receipt is `null` and `reply_count > 0`; absent entirely when
-  `reply_count == 0`.
-- **Read on open:** expanding a thread issues the REST read call and updates the receipt from its
-  response.
-- **Live root update:** a server-shaped `message` frame carrying a `reply_to_id` for a cached root
-  raises that root's `reply_count` and advances `last_reply_at`, and the marker appears without a
-  refetch when the sender is not the viewer.
-- **Row 42:** two managed conversations with different `external_key` values are distinguishable through
-  whatever the host supplies, and **no jg-specific string appears anywhere in `src/`** — assert that
-  directly, it is the constraint most likely to be quietly violated.
-- **Deviation doc / conformance:** zero BLOCKED entries and the version-pin check still meaningful.
-- Existing ucm suites stay green.
-
-**Fixture rule, non-negotiable:** every payload in these tests is copied from actual dcm serializer
-output. Two separate defects in this workstream (`reply_to` vs `reply_to_id`, `last_message.body` vs
-`.excerpt`) survived only because hand-written client-shaped fixtures agreed with the client's mistake.
-
-### Risks
-
-- **The merge trap**, above — the single most likely way this WO ships a regression, and the reason its
-  first test is mandatory rather than nice-to-have.
-- **jg vocabulary leaking into ucm** on row 42; it has its own assertion.
-- Small WO, low complexity — the risk is complacency, not difficulty.
-
-### Reviews
-
-**Tier 2, not Tier 1 — corrected on review.** The row count is small but the change lands in
-`MessagingProvider`'s frame-merge code, which is exactly where MSG-3c's Tier-2 pass found three shipped
-bugs, and this WO's own risk section calls its merge trap the most likely way it ships a regression.
-That is review-sensitive work by AGENTS.md's definition; size does not lower the tier.
-
-Independent `reviewer` plus **`ui_reviewer`** at WO end: the marker is a visual
-affordance and the harness exists to look at it. The `ui_reviewer` must also confirm the deviation doc
-reaches zero BLOCKED entries honestly — by delivery, not by deletion.
-
-### Preconditions
-
-dcm 2.38.0 published (met — verified in source, not assumed). Approval Gate #1 = operator go on this
-envelope.
-
-### Release
-
-One version bump + npm publish at WO end. **This closes the post-audit remediation**: with rows 27 and
-42 delivered, every row of the MSG-3b checklist is either implemented or a recorded deliberate
-deviation, and MSG-5 becomes unblocked.
-
-### Execution directive
-
-Implement through `codex exec` in the background — invoked **directly via Bash** (never the
-`debugger`/`*_coder` Agent wrappers) with **both** flags `--skip-git-repo-check` and
-`--dangerously-bypass-approvals-and-sandbox`, prompt passed as a positional argument from a file;
-fall back to direct Claude implementation only on Codex quota / rate-limit / non-zero exit. Codex has
-been out of workspace credits recently — verify before assuming the fallback, and if the fallback is
-used, the orchestrator becomes author and the independent review is mandatory, not routine.
-
-### Mini-handover (pastable)
-
-Orchestrator: implement `work-orders/MSG-3d.md` in `ui-core-micha` (main). `git pull` first, read the WO
-+ `django-core-micha/docs/design/messaging-platform.md` (§"Thread reply state and managed-conversation
-identity", §Realtime's consumer obligation), then follow `orchestrate-codex` (Codex-first, own
-independent review, `ui_reviewer` at WO end, one publish at WO end).
-
----
-
-## Part B — Implementation map (Orchestrator)
-
-**Single chunk** (the envelope's own framing: small WO, low complexity — Tier 2 for review rigor, not
-for decomposition). **Target repo working directory:** `C:\Users\biglmi\Documents\webapps\ui-core-micha`
-(repo root).
-
-**Verified against dcm 2.38.0 while scoping (do not re-derive):**
-- `serialize_message` (`django-core-micha/src/django_core_micha/messaging/serializers.py:80-95`) ALWAYS
-  includes `reply_count`/`last_reply_at` — annotated-queryset fast path when present
-  (`_with_reply_count`, `views.py:39-47`, used by `ConversationMessagesView`/`ThreadView`), a live
-  aggregate fallback otherwise (`_reply_stats`, `serializers.py:68-77`). Every `message`/`message_edited`
-  frame (built from `serialize_message` via `realtime.py`'s `publish_messaging_event`) therefore always
-  carries fresh, viewer-independent reply stats for that specific message.
-- `thread_last_read_at` is added **only** by `_message_response`/`_message_page_response`
-  (`views.py:50-74`) — REST-only, viewer-specific, from `MessageThreadReceipt`. `_with_reply_count`'s
-  list responses (`GET conversations/{id}/messages/`, `GET messages/{root_id}/thread/`) already attach
-  it per-row via one bulk query (not N+1) — so a normal `listMessages`/`listThread` load already gives
-  roots both their reply stats AND the viewer's own receipt in one response; no extra call needed on
-  mount.
-- `POST messages/{root_id}/thread/read/` (`views.py:342-347`, already wired as `markThreadRead` in
-  `api.js:41`) returns `{"last_read_at": ...}` — **note the field name differs from the cached message's
-  own `thread_last_read_at` key** — the provider action must map `last_read_at` from this response onto
-  the root message's `thread_last_read_at` cache field, they are not the same key name.
-- `serialize_conversation_core` (`serializers.py:107-115` area) now includes `external_key` (`null`
-  where the kind doesn't use one).
-
-**The merge trap — investigated, resolved by existing infrastructure, still needs its mandatory test:**
-`mergeById`/`reconcileMessage` (`MessagingProvider.jsx:45-79`) already do a **field-wise** merge
-(`{...previous, ...incoming}`), and neither the `message` nor `message_edited` `applyFrame` branches
-explicitly re-derive or strip `thread_last_read_at` the way the `reaction`/`poll_updated` branches used
-to explicitly recompute their own fields — so an incoming frame lacking `thread_last_read_at` (it always
-will) does NOT overwrite a previously-cached value through the current code path. This is a genuine
-finding from investigation, not an assumption: **do not skip the mandatory merge-trap test on the
-strength of this finding** — the WO requires it regardless, and any code added by this WO (the live
-root-update below in particular) must preserve this property rather than accidentally break it by
-constructing a replacement object that omits the key.
-
-**Row 27 implementation:**
-1. `MessagingProvider.jsx`'s `markReplyThreadRead` (currently `:262`,
-   `const markReplyThreadRead = useCallback((rootId, readAt) => api.markThreadRead(rootId, readAt),
-   [api]);`) fires the REST call and **discards the response** — nothing ever updates the cache, so the
-   receipt is never actually stored client-side today. Fix: on success, patch the root message's
-   `thread_last_read_at` from the response's `last_read_at` (field-name mapping per above).
-2. A marker component/affordance on the thread-toggle button (`Thread.jsx`'s existing
-   `toggleReplies`/reply-count button, around where `message.reply_count` is already read at `:93-96`
-   for the reply-count label) — show it when `message.last_reply_at > message.thread_last_read_at`, OR
-   when `message.thread_last_read_at` is `null`/absent and `message.reply_count > 0`. No marker at all
-   when `reply_count === 0` (matches the existing "no toggle button at all when there are no replies"
-   behavior — don't add a marker to a control that doesn't render). This belongs in `Thread.jsx` (or a
-   small collaborator it owns) — not a new top-level component, per the non-goals' "marker belongs to
-   whichever component owns the thread toggle."
-3. **Live root update on an incoming reply** — in `applyFrame`'s `message` case
-   (`MessagingProvider.jsx:126-143`): after the existing reply message itself is merged via
-   `reconcileMessage`, additionally check `message.reply_to_id` (server field name — reuse the pattern
-   already established, this is NOT the client-shaped `reply_to` used only by locally-built optimistic
-   rows) against `state.messages` for a cached root. If found, bump that root's `reply_count` by one and
-   set `last_reply_at` to the incoming message's `created_at`, via a **field-wise merge that explicitly
-   preserves the root's existing `thread_last_read_at`** (the exact discipline the merge-trap section
-   above is about — do this by spreading the previous root object and only overriding
-   `reply_count`/`last_reply_at`, never by constructing a fresh object from the frame's data). Apply this
-   unconditionally (regardless of who sent the reply) — `reply_count`/`last_reply_at` are
-   viewer-independent facts; do not add sender-based suppression logic that isn't explicitly required
-   (the required tests only ask for the "sender is not the viewer" case, the common path — don't invent
-   untested self-send special-casing beyond that).
-
-**Row 42 implementation:** `external_key` needs no new plumbing to reach the cache — `mergeById`/REST
-responses pass every field through transparently already. What's missing is a way for a host to render
-it. Add an optional host-supplied resolver prop to `ConversationList.jsx` (mirrors the existing
-`groupLaunchers`/`broadcastLauncher` host-supplied-data pattern already in this file) — e.g.
-`resolveManagedLabel(conversation)` — called instead of the existing `titleOf()` fallback specifically
-when `conversation.kind === 'managed'` and the prop is supplied; falls back to the existing `titleOf()`
-behavior otherwise (unset prop, or non-managed kind). **ucm must not hardcode or reference `event_all`/
-`event_team` or any other jg-specific vocabulary anywhere in `src/`** — the resolver receives the raw
-`conversation` object (including `external_key`) and the host owns all interpretation.
-
-**Deviation doc + conformance test:** move rows 27 and 42 from `BLOCKED` to their delivered outcome in
-`docs/messaging-deviations.md` (describe what was actually built, not a generic note, matching the
-established style from MSG-3c's rewrite). This leaves **zero** `BLOCKED` entries — verify
-`tests/messagingContractConformance.test.js`'s version-pin check (added in MSG-3c) still passes
-meaningfully against an empty set (i.e. `unpinnedBlockedLines()` naturally returns `[]` when there are no
-`**BLOCKED**` lines at all — confirm this is actually true of the regex-based approach, not just assumed
-because the test happens to pass; the WO's own text calls out the "passing vacuously for the wrong
-reason" risk explicitly).
-
-**Required tests to WRITE (all named explicitly in the WO's own "Required tests" section — treat that
-section as the checklist, not this paraphrase):**
-- The merge-trap test (load-bearing, per the WO: server-shaped `message` and `message_edited` frames,
-  copied from real `serialize_message` shape, must leave a previously-fetched
-  `thread_last_read_at` intact).
-- Marker visibility logic (shown/hidden/null-receipt/no-replies cases, all four named in the WO).
-- Read-on-open (expanding a thread issues the REST call and updates the receipt from its response).
-- Live root update (server-shaped `message` frame with `reply_to_id` raises the cached root's
-  `reply_count`/`last_reply_at`; marker appears without a refetch for the "sender is not the viewer"
-  case).
-- Row 42: two managed conversations with different `external_key` render distinguishable labels via a
-  host resolver; **a direct assertion that no jg-specific string (`event_all`, `event_team`) appears
-  anywhere in `src/`** — grep-based, mirroring the style of the existing contract-conformance test.
-- Deviation-doc/conformance: zero `BLOCKED` entries; the version-pin check's own logic still behaves
-  correctly against that empty set (not just "the real file happens to pass").
-- Existing ucm suites stay green.
-
-**Fixture rule (WO's own words, binding):** every payload in these tests is copied from actual dcm
-serializer output — this workstream has twice shipped a bug that survived only because a hand-written
-client-shaped fixture agreed with the client's own mistake (`reply_to` vs `reply_to_id`,
-`last_message.body` vs `.excerpt`). Do not hand-invent a payload shape without checking it against the
-serializer citations above first.
-
-**Invariants / do-not-break:** don't touch chunks/rows already delivered; keep the ~400 LOC soft trigger
-in mind for `Thread.jsx`/`ConversationList.jsx`/`MessagingProvider.jsx`; no new top-level component for
-the marker (lives in `Thread.jsx` or a small collaborator it owns); no new DX-1 harness entry needed
-unless a genuinely new independently-mountable component is added (it shouldn't be, per the above).
-
-**Progress contract / preamble:** `PLAN:`/`PROGRESS:`/`RESULT:` lines, no git operations, write-and-run-
-only-the-new-tests, leave the diff uncommitted for the orchestrator's review. Codex has been out of
-workspace credits recently across the last several WOs in this workstream — verify liveness before
-assuming success; if Codex fails (credits, quota, non-zero exit), the orchestrator implements directly
-per the fallback rule, which makes the orchestrator the author and independent review mandatory
-(not routine) — this has been true for every chunk of MSG-3c and should be expected here too.
-
-**Mini-handover:** repo `C:\Users\biglmi\Documents\webapps\ui-core-micha`, branch `main`, WO
-`work-orders/MSG-3d.md` (Part B above, single chunk). Follow `orchestrate-codex`. After the independent
-review and commit, run the WO-end `ui_reviewer` pass (per the WO's "Reviews" section — confirm the
-deviation doc reaches zero BLOCKED entries honestly, by delivery not deletion, and look at the marker
-as a rendered visual affordance via the DX-1 harness), then one version bump + npm publish.