@micha.bigler/ui-core-micha 2.11.0 → 2.13.0

package/tests/realtime.test.jsx

@@ -0,0 +1,192 @@
+// @vitest-environment jsdom
+import React from 'react';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { cleanup, fireEvent, render, screen, waitFor } from '@testing-library/react';
+
+const feedApi = vi.hoisted(() => ({
+  getNotificationFeed: vi.fn(),
+  getUnreadCount: vi.fn(),
+  markNotifications: vi.fn(),
+}));
+
+vi.mock('../src/notifications/feedApi', () => feedApi);
+
+import { AuthContext } from '../src/auth/AuthContext';
+import { NotificationsProvider, useNotifications } from '../src/notifications/NotificationsProvider';
+import { useRealtime } from '../src/notifications/realtime';
+
+class MockWebSocket {
+  static instances = [];
+
+  constructor(url) {
+    this.url = url;
+    this.close = vi.fn(() => this.onclose?.());
+    MockWebSocket.instances.push(this);
+  }
+}
+
+function StreamConsumer({ envelope, testId }) {
+  const { subscribe } = useRealtime();
+  const [received, setReceived] = React.useState([]);
+
+  React.useEffect(
+    () => subscribe(envelope, (data) => setReceived((prev) => [...prev, data])),
+    [subscribe, envelope],
+  );
+
+  return <output data-testid={testId}>{JSON.stringify(received)}</output>;
+}
+
+function NotificationsConsumer() {
+  const notifications = useNotifications();
+  return (
+    <>
+      <output data-testid="notifications">{JSON.stringify(notifications.notifications)}</output>
+      <output data-testid="unread-count">{notifications.unreadCount}</output>
+      <output data-testid="context-keys">{JSON.stringify(Object.keys(notifications).sort())}</output>
+    </>
+  );
+}
+
+function renderWithStreams({ streams = [], user = { id: 4 } } = {}) {
+  return render(
+    <AuthContext.Provider value={{ user }}>
+      <NotificationsProvider>
+        <NotificationsConsumer />
+        {streams.map(({ envelope, testId }) => (
+          <StreamConsumer key={testId} envelope={envelope} testId={testId} />
+        ))}
+      </NotificationsProvider>
+    </AuthContext.Provider>,
+  );
+}
+
+function received(testId) {
+  return JSON.parse(screen.getByTestId(testId).textContent);
+}
+
+describe('realtime primitive (NOTIF-13)', () => {
+  afterEach(() => {
+    cleanup();
+  });
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    MockWebSocket.instances = [];
+    vi.stubGlobal('WebSocket', MockWebSocket);
+    feedApi.getNotificationFeed.mockResolvedValue({ results: [] });
+    feedApi.getUnreadCount.mockResolvedValue({ count: 0 });
+    feedApi.markNotifications.mockResolvedValue({ updated: 1 });
+  });
+
+  it('ignores an unknown/unsubscribed envelope type — feed and unreadCount untouched', async () => {
+    renderWithStreams();
+    await waitFor(() => expect(MockWebSocket.instances).toHaveLength(1));
+
+    MockWebSocket.instances[0].onmessage({ data: JSON.stringify({
+      envelope: 'message',
+      type: 'chat.new',
+      body: 'hello',
+    }) });
+
+    expect(screen.getByTestId('unread-count').textContent).toBe('0');
+    expect(currentNotificationsAreEmpty()).toBe(true);
+  });
+
+  function currentNotificationsAreEmpty() {
+    return JSON.parse(screen.getByTestId('notifications').textContent).length === 0;
+  }
+
+  it('routes two subscribers on distinct envelope types from one socket, each seeing only their own', async () => {
+    renderWithStreams({ streams: [
+      { envelope: 'message', testId: 'message-stream' },
+      { envelope: 'other', testId: 'other-stream' },
+    ] });
+    await waitFor(() => expect(MockWebSocket.instances).toHaveLength(1));
+
+    MockWebSocket.instances[0].onmessage({ data: JSON.stringify({ envelope: 'message', body: 'a' }) });
+    MockWebSocket.instances[0].onmessage({ data: JSON.stringify({ envelope: 'other', body: 'b' }) });
+
+    await waitFor(() => expect(received('message-stream')).toHaveLength(1));
+    expect(received('message-stream')[0]).toEqual(expect.objectContaining({ body: 'a' }));
+    expect(received('other-stream')).toHaveLength(1);
+    expect(received('other-stream')[0]).toEqual(expect.objectContaining({ body: 'b' }));
+    expect(MockWebSocket.instances).toHaveLength(1);
+  });
+
+  it('unsubscribe stops delivery for that subscriber without affecting others', async () => {
+    function Harness() {
+      const { subscribe } = useRealtime();
+      const [messageReceived, setMessageReceived] = React.useState([]);
+      const [otherReceived, setOtherReceived] = React.useState([]);
+      const [messageSubscribed, setMessageSubscribed] = React.useState(true);
+
+      React.useEffect(() => {
+        if (!messageSubscribed) return undefined;
+        return subscribe('message', (data) => setMessageReceived((prev) => [...prev, data]));
+      }, [subscribe, messageSubscribed]);
+
+      React.useEffect(
+        () => subscribe('other', (data) => setOtherReceived((prev) => [...prev, data])),
+        [subscribe],
+      );
+
+      return (
+        <>
+          <output data-testid="message-received">{JSON.stringify(messageReceived)}</output>
+          <output data-testid="other-received">{JSON.stringify(otherReceived)}</output>
+          <button onClick={() => setMessageSubscribed(false)}>unsubscribe-message</button>
+        </>
+      );
+    }
+
+    const { unmount } = render(
+      <AuthContext.Provider value={{ user: { id: 4 } }}>
+        <NotificationsProvider>
+          <Harness />
+        </NotificationsProvider>
+      </AuthContext.Provider>,
+    );
+    await waitFor(() => expect(MockWebSocket.instances).toHaveLength(1));
+
+    fireEvent.click(screen.getByRole('button', { name: 'unsubscribe-message' }));
+
+    MockWebSocket.instances[0].onmessage({ data: JSON.stringify({ envelope: 'message', body: 'after-unsub' }) });
+    MockWebSocket.instances[0].onmessage({ data: JSON.stringify({ envelope: 'other', body: 'still-alive' }) });
+
+    await waitFor(() => expect(received('other-received')).toHaveLength(1));
+    expect(received('message-received')).toHaveLength(0);
+    expect(received('other-received')[0]).toEqual(expect.objectContaining({ body: 'still-alive' }));
+
+    unmount();
+  });
+
+  it('keeps a subscriber registered across a close/backoff/reopen cycle with no re-registration', async () => {
+    vi.useFakeTimers();
+    try {
+      renderWithStreams({ streams: [{ envelope: 'message', testId: 'message-stream' }] });
+      await vi.waitFor(() => expect(MockWebSocket.instances).toHaveLength(1));
+
+      const firstSocket = MockWebSocket.instances[0];
+      firstSocket.onclose();
+      await vi.advanceTimersByTimeAsync(1_000);
+
+      expect(MockWebSocket.instances).toHaveLength(2);
+      MockWebSocket.instances[1].onmessage({ data: JSON.stringify({ envelope: 'message', body: 'after-reopen' }) });
+
+      await vi.waitFor(() => expect(received('message-stream')).toHaveLength(1));
+      expect(received('message-stream')[0]).toEqual(expect.objectContaining({ body: 'after-reopen' }));
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it("NotificationsProvider's public context value is unchanged", async () => {
+    renderWithStreams();
+    await waitFor(() => expect(MockWebSocket.instances).toHaveLength(1));
+
+    expect(JSON.parse(screen.getByTestId('context-keys').textContent)).toEqual(
+      ['markDismissed', 'markDone', 'markSeen', 'notifications', 'refresh', 'unreadCount'].sort(),
+    );
+  });
+});

package/work-orders/NOTIF-12.md

@@ -0,0 +1,162 @@
+# WORK ORDER NOTIF-12 (ui-core-micha + django-core-micha) — popup channel via the wizard renderer
+
+**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 this
+file. Fall back to direct Claude implementation only on Codex quota / rate-limit / non-zero exit.
+
+Feature-level WO (Expertenchat envelope). Seams verified against ucm 2.12.0 / dcm 2.32.0.
+
+## HARD GATE — do not start before NOTIF-13 has landed and published
+NOTIF-12 consumes NOTIF-13's envelope contract and its `subscribe(type, handler)` primitive. Starting
+earlier means building on the catch-all in `NotificationsProvider.jsx:130-132` that NOTIF-13 removes.
+Both WOs also edit `ui-core-micha/src/notifications/` and `src/index.js`, so running them in parallel
+violates the AGENTS.md overlap rule. **Sequence: NOTIF-13 → publish → NOTIF-12.**
+
+## TIER
+Tier 2 — this extracts a renderer out of `OnboardingWizard`, which **cockpit and jg run in
+production**. The roadmap calls the popup channel "uncritical"; that refers to business urgency, not
+blast radius. Independent `reviewer` mandatory. `sec_reviewer` only on explicit operator request.
+
+## SCAFFOLDING NOTICE — READ FIRST
+**This channel ships with zero producers, deliberately.** Verified 2026-07-29 across dcm, jg-ferien,
+cockpit, hram, spesix and survey_app: **no notification type declares `popup` in `eligible_channels`**,
+so `resolve_channels()` will never route anything to it until some app opts a type in. The operator
+decided to build the scaffolding anyway (2026-07-29), having been shown this.
+
+Two obligations follow, and they are part of the acceptance criteria:
+1. **Do not overclaim.** The CHANGELOG entry and any docstring must state plainly that the popup
+   channel is wired but inactive until a notification type declares `popup`. Precedent: NOTIF-4's
+   reviewer (R1) had to soften a CHANGELOG that promised retry behaviour no shipped dispatcher could
+   reach. Do not repeat that.
+2. **Scaffolding must be tested scaffolding.** Register a test-local notification type that declares
+   `popup` and prove the whole path end-to-end. Untested dead code is not an acceptable outcome.
+
+## GOAL
+Make `popup` a real delivery channel: a notification whose type opts into `popup` is rendered to the
+recipient in a modal that reuses the onboarding **wizard renderer**, with its seen/dismissed status
+recorded on `NotificationRecipient` — **not** in the onboarding progress store.
+
+## EXPECTED OUTCOME
+- dcm's `PopupDispatcher` stops being a logging stub and delivers for real.
+- ucm exports a popup surface that renders popup-eligible notifications and marks them via the
+  existing `feed/mark/` path.
+- Onboarding behaviour is bit-for-bit unchanged for existing consumers.
+- With no producer registered, nothing visibly changes in any app.
+
+## CONTEXT PACKAGE — verified current state
+
+**dcm `notifications/dispatch.py`:**
+- `PopupDispatcher` (`:117-121`) is a stub: logs "queued for unimplemented popup channel" and returns
+  `DeliveryResult(ok=None, error="pending")`. It is registered in `_DISPATCHERS` (`:126-133`).
+- The model to copy is `ChipDispatcher` (`:62-74`): it calls
+  `push_to_users([recipient.user], {"type": notification.notification_type, "content": ..., "notification_id": ...})`
+  and returns `DeliveryResult(ok=True)`. **Note the `type` field carries the *domain* type** — this is
+  precisely the overload NOTIF-13 replaces with a proper envelope. Emit NOTIF-13's envelope, not this
+  legacy shape.
+- `_render_content(content, user)` (`:44-60`) renders `title_key`/`body_key`/`params` in the
+  recipient's language — reuse it rather than re-deriving text client-side if the payload needs text.
+- `prefs.py:22` already treats `popup` as a channel defaulting to True; `router.py:24` narrows to
+  `ntype.eligible_channels`. **No prefs or router change is needed** — only a type opting in.
+
+**ucm `src/onboarding/OnboardingWizard.jsx` (75 LOC)** is the renderer to reuse:
+- MUI `Dialog open fullWidth maxWidth="sm"` (`:59`), `DialogTitle` with a step counter +
+  `LinearProgress` (`:60-67`), `DialogContent` rendering
+  `<StepComponent onComplete={...} onDismiss={...} ctx={...} />` (`:69`).
+- Step contract: `{ id, Component, blocking, persistDismissed }`. `blocking` disables escape/backdrop
+  close (`:59`).
+- **The parts that must NOT come along** (design decision D-F7,
+  `django-core-micha/docs/design/notifications-platform.md:70-71`): `onboarding.markStepSeen` (`:35`),
+  `dismissStep` (`:54`), and the sequential progress store behind them. Popup status lives on
+  `NotificationRecipient`.
+- Exported at `src/index.js:61`; the four existing steps at `:62-65`.
+
+**ucm notification status API:** `useNotifications()` already returns `markSeen` / `markDismissed` /
+`markDone`, backed by `feed/mark/`. Use `markSeen` when a popup is shown and `markDismissed` when the
+user closes it. **Never `markDone`** — done is a todo-channel semantic.
+
+## SCOPE
+
+**A. ucm — extract the dialog shell.** Lift the presentational shell out of `OnboardingWizard` into a
+reusable renderer (dialog frame, counter/progress header, the `onComplete`/`onDismiss`/`ctx` child
+contract). `OnboardingWizard` keeps its current behaviour by composing that shell with the onboarding
+store; the popup surface composes the same shell with notification state.
+
+**B. ucm — the popup surface.** A component that selects popup-eligible notifications from
+notification state, renders them through the shell, marks `seen` on display and `dismissed` on close,
+and subscribes to NOTIF-13's popup envelope type so a popup can appear live. Export additively from
+`src/index.js`.
+
+**C. Coexistence rule with onboarding — specify and test it.** Both surfaces render a MUI `Dialog`, so
+two modals can be open at once. Required behaviour: **a blocking onboarding step wins**; the popup
+waits until no blocking onboarding step is active. Non-blocking coexistence must not stack two dialogs.
+
+**D. dcm — implement `PopupDispatcher.deliver`.** Emit NOTIF-13's envelope over `push_to_users` and
+return `DeliveryResult(ok=True)`. Keep the delivery-record semantics identical to `ChipDispatcher`
+(the surrounding `dispatch()` machinery already records pending → sent/failed; do not re-implement it).
+
+## DO NOT TOUCH
+- **The onboarding progress store** — `markStepSeen`, `dismissStep`, `persistDismissed` persistence,
+  `OnboardingProvider`'s step-selection semantics, `stepSelection.js`.
+- The four existing step components (`CookieConsentStep`, `CompleteNameStep`, `BrowserPushStep`,
+  `PwaInstallStep`) and their props.
+- NOTIF-13's realtime core — **consume** `subscribe()`, do not restructure it.
+- `feed/*` REST contract, `NotificationBell`, `NotificationSettings`.
+- `prefs.py`, `router.py`, `resolve_channels` — popup already works there; a type opting in is an
+  app-side change, not this WO's.
+- Schema, migrations, dependencies, CI.
+- **Do not register a `popup` producer in any app.** This WO ships the channel only.
+
+## RISKS
+- **Onboarding regression** is the main risk: the shell extraction touches a wizard that cockpit and jg
+  run in production. The step counter (`totalRef`/`completed`), the session-dismissed Set, and the
+  `blocking` escape-key behaviour are easy to break silently.
+- **Stacked modals** if C is skipped — two dialogs, neither reachable.
+- **Dead code rot:** with no producer, only the tests exercise the path. Hence the mandatory test-local
+  producer type.
+- **Status semantics drift:** marking a popup `done` instead of `dismissed` would pollute todo-channel
+  semantics.
+
+## REQUIRED TESTS / ACCEPTANCE
+ucm (`pnpm test`, vitest):
+- a popup-eligible notification renders in the shell; `markSeen` fires once on display;
+- closing it fires `markDismissed`, never `markDone`;
+- **coexistence:** with a blocking onboarding step active, no popup dialog renders; once it clears, the
+  popup appears — and never two dialogs at once;
+- **onboarding regression guard:** existing `OnboardingWizard` behaviour unchanged — step counter,
+  progress bar, session-dismissed set, `blocking` disabling escape/backdrop close, `persistDismissed`
+  still calling `dismissStep`;
+- with no popup-eligible notification present, nothing renders.
+
+dcm (`pytest` on the notifications package):
+- register a **test-local** notification type declaring `eligible_channels=["popup"]`, call `notify()`,
+  and assert the dispatcher delivered (`ok=True`) with NOTIF-13's envelope shape on the wire — the
+  end-to-end proof required by the scaffolding notice;
+- `resolve_channels` still excludes `popup` for types that do not declare it (no accidental widening);
+- the existing `test_dispatch.py` registry assertion (`:25`) still passes.
+
+Plus `pnpm build` (tsc) green.
+
+## RELEASE
+ucm minor bump + publish. dcm minor bump + publish (publish-from-main), with a **registry live-check
+before any app pin bump**. No app pin bumps in this WO. CHANGELOG in both repos must carry the
+inactive-until-a-producer-opts-in wording from the scaffolding notice.
+
+## TARGET REPO / WORKING DIRECTORY
+- Primary: `C:\Users\biglmi\Documents\webapps\ui-core-micha`
+- Secondary (scope D): `C:\Users\biglmi\Documents\webapps\django-core-micha`
+- Never the workspace root `…\webapps`.
+Both are platform repos: commit directly to the trunk, no feature branches.
+
+## PROGRESS CONTRACT
+Emit a `PLAN: <step1> | <step2> | …` line up front, then a single-line
+`PROGRESS: [<n>/<total>] <present-tense action>` **before every relevant action** (file opened, file
+edited, command/test run) and `PROGRESS: [<n>/<total>] done` on step completion, spaced so no gap
+exceeds ~2 min. stdout unbuffered. Exactly one final `RESULT: DONE|BLOCKED <reason>`.
+
+## MINI-HANDOVER (paste into a fresh Orchestrator session)
+```
+Orchestrator: implement work-orders/NOTIF-12.md in ui-core-micha (main; scope D also touches
+django-core-micha). Check the hard gate first — NOTIF-13 must be landed and published. git pull,
+read the WO, then follow orchestrate-codex (Codex-first, own independent review, commit on green).
+```

package/work-orders/NOTIF-13.md

@@ -0,0 +1,142 @@
+# WORK ORDER NOTIF-13 (ui-core-micha + django-core-micha) — Layer-1 transport extraction
+
+**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 this
+file. Fall back to direct Claude implementation only on Codex quota / rate-limit / non-zero exit.
+
+Feature-level WO (Expertenchat envelope). The seams below are **verified against the landed code**
+(ucm 2.12.0, dcm 2.32.0) and are the required scope. The Orchestrator fills the exact line map.
+
+## TIER
+Tier 2 — restructures a provider that **cockpit consumes in production**, and changes a WebSocket
+message contract shared across apps. Independent `reviewer` mandatory. Per AGENTS.md Tier 2,
+`sec_reviewer` is NOT auto-included; request it only if the operator asks.
+
+## GOAL
+Turn ucm's notification-only socket into a generic **Layer-1 realtime primitive**: one socket,
+subscribe-by-message-type, so a second domain (messaging) can ride it without being misread as a
+notification. **Additive**: `NotificationsProvider` remains the sole mount point and its public
+context value is unchanged (operator decision 2026-07-29).
+
+## EXPECTED OUTCOME
+- ucm exports a `useRealtime()`-style subscribe primitive alongside the unchanged `useNotifications()`.
+- An unknown/unsubscribed message type is **ignored** instead of being appended to the notification feed.
+- No app has to change its provider tree. cockpit and jg keep working untouched.
+- NOTIF-15 (jg bell adoption, retiring jg's local context) becomes implementable; Phase B messaging
+  gets its substrate.
+
+## CONTEXT PACKAGE — verified current state
+
+**ucm `src/notifications/NotificationsProvider.jsx` (232 LOC)** owns *both* the socket and the
+notifications domain state:
+- socket ownership: `socketRef`, `connect()`, exponential backoff `INITIAL_BACKOFF_MS` 1s →
+  `MAX_BACKOFF_MS` 30s, auth-gated effect keyed on `[authenticated, refresh, replaceNotifications, wsUrlBase]` (`:87-179`).
+- `handleMessage` (`:103-133`) dispatches on exactly **one** envelope type, `notification.status` (`:111`).
+- **The blocker:** everything else falls through to `normalizeNotificationPush(data)` and is appended
+  to the feed with `unreadCount + 1` (`:130-132`). A messaging payload on this socket becomes a fake
+  notification today.
+- **Field overload — the reason a third stream cannot simply be added:** in the status branch
+  `data.type` is the *envelope* type; in the new-notification branch `normalizeNotificationPush`
+  reads `data.type` as the *domain* notification-type key (`:25`). One field, two meanings. The
+  envelope contract must resolve this without breaking either reading.
+- WS URL hardcoded to `/ws/notifications/` (`:36`, `:40`).
+- exports in `src/index.js:48` (`NotificationsProvider`, `useNotifications`).
+
+**dcm transport is ALREADY generic — correct the roadmap wording here.** The roadmap §4 calls for a
+"dcm multi-stream consumer"; that overstates the dcm work:
+- `notifications/delivery.py::push_to_users(users, payload)` (`:20-43`) fans an **arbitrary** payload
+  into the per-user group `notifications_user_{id}`.
+- `notifications/consumers.py::NotificationConsumer.message()` (`:21-22`) is `send_json(event["payload"])` —
+  fully stream-agnostic. jg's messaging **already** rides this same group via `push_to_users`.
+- The only dcm-side envelope producer is `notifications/views.py:235` (`"type": "notification.status"`);
+  the contract is documented at `views.py:3`.
+- **So the dcm work is the envelope contract + a thin authoring helper + doc — NOT a consumer rewrite.**
+
+**Reference implementation to promote:** jg's `frontend/src/context/NotificationsContext.jsx` (91 LOC,
+docstring "WebSocket owner only") already does exactly this multiplexing with
+`registerMessageCallback` / `registerChatCallback`. Read it for the shape. **Do not edit jg here.**
+
+## SCOPE
+
+**A. ucm — extract the socket into an internal realtime core.** Single owner; preserve the existing
+backoff, reconnect, auth-gating and cleanup semantics **verbatim**. Expose
+`subscribe(type, handler) -> unsubscribe`.
+
+**B. ucm — `NotificationsProvider` becomes the first subscriber.** It registers handlers for the
+notification envelope types. Its returned context value stays **exactly**
+`{ notifications, unreadCount, markSeen, markDismissed, markDone, refresh }`.
+
+**C. Envelope contract.** Introduce an explicit envelope discriminator that does not collide with the
+domain `type` field (see the field-overload note above). Unknown / unsubscribed envelope types are
+**ignored** — the catch-all at `:130-132` dies. This is a deliberate behaviour change and must be
+called out in the CHANGELOG.
+
+**D. Backward compatibility in BOTH directions** — apps pin dcm and ucm independently, so mismatched
+versions are normal:
+- *new ucm + old dcm* (payload has no envelope field): must still be recognised as a new notification,
+  exactly as today. Without this the feed silently goes dead against an un-bumped backend.
+- *old ucm + new dcm*: dcm must keep emitting the legacy fields so a ucm 2.12.0 client is unaffected
+  (**cockpit runs 2.12.0 in staging/prod**).
+
+**E. dcm — formalize the contract.** Document the envelope next to `views.py:3` and add a thin
+authoring helper so producers stop hand-rolling the dict. `push_to_users`'s signature stays unchanged.
+
+## DO NOT TOUCH
+- **jg-ferien** (`NotificationsContext.jsx`, `MessagingContext.jsx`) — that is NOTIF-15.
+- The messaging domain itself — Phase B (`MSG-*`).
+- `NotificationBell.jsx`, `NotificationSettings.jsx`, `feedApi.js`, the `feed/*` REST contract.
+- `BaseSecureConsumer` / S112 permission model, `IsAuthenticatedWs`, the group name `notifications_user_{id}`.
+- **No standalone `RealtimeProvider` export that apps must mount.** Operator decision 2026-07-29:
+  additive only. A standalone provider is a later, separate WO if a second consumer ever needs it.
+- Reconnect/backoff semantics and the single-socket-owner invariant — preserve, do not "improve".
+- Schema, migrations, dependencies, CI.
+- **No app pin bumps** in this WO (cockpit/jg stay where they are).
+
+## RISKS
+- **Silent feed death** if C lands without D: an envelope-less payload from an older dcm would be
+  ignored instead of shown. D is not optional.
+- **cockpit is a live consumer** at ucm 2.12.0 — any change to the returned context shape breaks it.
+- **Subscription leaks / double delivery:** `subscribe` must return a stable unsubscribe, and handlers
+  must **survive reconnects** without the caller re-registering them.
+- **Reconnect loop:** the socket effect currently depends on `refresh` / `replaceNotifications`;
+  moving the socket out must not make the socket re-create on every feed update.
+
+## REQUIRED TESTS / ACCEPTANCE
+ucm runs `vitest` (`pnpm test`) and has **no tests under `src/notifications/` today** — this WO adds
+the first ones:
+- an unknown envelope type is ignored: feed and `unreadCount` both untouched (the regression that
+  protects messaging from being misread as a notification);
+- two subscribers on distinct types each receive only their own messages, from **one** socket —
+  assert exactly one `WebSocket` was constructed;
+- `unsubscribe` stops delivery for that subscriber and does not affect the others;
+- handlers keep receiving after a close → backoff → reopen cycle, with no re-registration by the caller;
+- a legacy envelope-less payload still lands in the feed (backward-compat D);
+- `notification.status` handling and the `unreadCount` delta are unchanged — this guards the NOTIF-6
+  R1 fix (badge went stale after a cross-device mark);
+- `NotificationsProvider`'s public context value is unchanged.
+
+Plus `pnpm build` (tsc) green. If E lands in dcm, run the dcm notifications `pytest` package.
+
+## RELEASE
+ucm minor bump + publish (publish-from-main). dcm only if E lands there — then publish-from-main with
+a **registry live-check before any app pin bump**. No app pin bumps in this WO.
+
+## TARGET REPO / WORKING DIRECTORY
+- Primary: `C:\Users\biglmi\Documents\webapps\ui-core-micha`
+- Secondary (scope E only): `C:\Users\biglmi\Documents\webapps\django-core-micha`
+- Never the workspace root `…\webapps`.
+Both are platform repos: commit directly to the trunk, no feature branches.
+
+## PROGRESS CONTRACT
+Emit a `PLAN: <step1> | <step2> | …` line up front, then a single-line
+`PROGRESS: [<n>/<total>] <present-tense action>` **before every relevant action** (file opened, file
+edited, command/test run) and `PROGRESS: [<n>/<total>] done` on step completion, spaced so no gap
+exceeds ~2 min. stdout unbuffered. Exactly one final `RESULT: DONE|BLOCKED <reason>`.
+
+## MINI-HANDOVER (paste into a fresh Orchestrator session)
+```
+Orchestrator: implement work-orders/NOTIF-13.md in ui-core-micha (main; scope E also touches
+django-core-micha). git pull first, read the WO, then follow orchestrate-codex (Codex-first, own
+independent review, commit on green).
+```