---
phase: 04-shared-lists-live-sync
plan: "02"
subsystem: api-lib, test-harness
tags: [listEmitter, listAccess, scoped-fanout, D-04, tdd, eventEmitter, sse-primitive]
dependency_graph:
  requires:
    - 04-01 (lists/list_shares schema, test harness, vitest.config.ts)
  provides:
    - publishListEvent(listId, event): scoped in-process fan-out
    - subscribeListEvents(listId, handler): per-list subscription returning unsub closure
    - ListEvent type union
    - getAccessibleListIds(userId): owner OR list_shares access-scope query
    - fileParallelism:false vitest config (prevents DB test race conditions)
  affects:
    - apps/api/tests/lib/listEmitter.test.ts (stubs replaced with real assertions)
    - apps/api/vitest.config.ts (fileParallelism:false added)
tech_stack:
  added: []
  patterns:
    - Module-level EventEmitter singleton; per-list channel key list:${listId}
    - subscribeListEvents returns unsub closure (emitter.off)
    - Two-query union (owned + shared) with Set dedup for getAccessibleListIds
    - randomUUID() suffix in test seed helpers to avoid unique-key collisions
    - fileParallelism:false to serialize DB test file execution
key_files:
  created:
    - apps/api/src/lib/listEmitter.ts
    - apps/api/src/lib/listAccess.ts
    - apps/api/tests/lib/listAccess.test.ts
  modified:
    - apps/api/tests/lib/listEmitter.test.ts (it.todo stubs replaced with real assertions)
    - apps/api/vitest.config.ts (fileParallelism:false; sequence.concurrent:false)
decisions:
  - "D-04: In-memory EventEmitter per-list channel isolation confirmed by Test 2 (cross-list negative)"
  - "D-18: ioredis NOT introduced; abstraction boundary in listEmitter.ts makes future Redis swap mechanical"
  - "vitest fileParallelism:false: global afterEach in test/setup.ts truncates shared MariaDB state; parallel files caused FK violations mid-test"
  - "getAccessibleListIds: two-select + Set approach per RESEARCH Finding 3 (not single OR-join) — simpler, equally correct"
  - "listAccess.test.ts in tests/lib/ (not src/lib/) per tdd_note convention matching listEmitter placement"
metrics:
  duration: "~15 minutes"
  completed: "2026-06-09"
  task_count: 3
  file_count: 5
---

# Phase 4 Plan 2: Scoped Fan-out Primitives Summary

**One-liner:** In-memory per-list EventEmitter singleton (listEmitter.ts) + owner/shares access-scope query (listAccess.ts) with D-04 isolation proven by RED/GREEN TDD gate.

## TDD Gate Compliance

| Gate | Commit | Status |
|------|--------|--------|
| RED — failing tests | 2d250af | PASS — module-not-found; 6 tests failed as expected |
| GREEN — implementation | 792efeb | PASS — all 9 tests pass |
| REFACTOR | (skipped) | No refactoring needed — implementation was clean on first pass |

## Tasks Completed

| Task | Name | Commit | Files |
|------|------|--------|-------|
| RED | Write failing listEmitter + listAccess tests | 2d250af | listEmitter.test.ts (stubs → assertions), listAccess.test.ts (new) |
| GREEN | Implement listEmitter.ts + listAccess.ts | 792efeb | listEmitter.ts, listAccess.ts, listAccess.test.ts (UUID fix), vitest.config.ts |
| FIX | fileParallelism:false to eliminate DB race condition | 9e17853 | vitest.config.ts |

## Deviations from Plan

### Auto-fixed Issues

**1. [Rule 1 - Bug] Test seed helper oidc_sub collisions across runs**
- **Found during:** GREEN phase — running both test files together
- **Issue:** `seedUser('owner-5')` inserted `sub-owner-5` on first run; on the second run (or when running tests without cleanup of the users table), the `uniq_oidc_identity` key fired `ER_DUP_ENTRY`.
- **Fix:** Added `randomUUID()` suffix: `oidcSub: sub-${label}-${randomUUID()}` — unique per invocation regardless of table state.
- **Files modified:** `apps/api/tests/lib/listAccess.test.ts`
- **Commit:** 792efeb

**2. [Rule 1 - Bug] Concurrent test files race against shared-MariaDB global afterEach**
- **Found during:** GREEN phase — running both test files together (and during full suite run)
- **Issue:** vitest defaults to `fileParallelism: true`. The global `afterEach` in `test/setup.ts` runs in every worker and truncates `lists`/`listShares`. When two DB-backed test files ran concurrently, file A's `afterEach` deleted rows that file B's test was still reading — producing FK violations (`ER_NO_REFERENCED_ROW_2`) and incorrect empty results.
- **Fix:** Added `fileParallelism: false` to `vitest.config.ts`, serializing test file execution.
- **Files modified:** `apps/api/vitest.config.ts`
- **Commit:** 9e17853

## Verification Results

### TDD Tests
- listEmitter suite: 5 passed (Tests 1-4 + D-18 scale check)
- listAccess suite: 4 passed (Tests 5-8)
- **Test 2 (D-04 cross-list negative):** GREEN — handler subscribed to list 1 received 0 events when list 2 published
- **Test 7 (D-04 private-list negative):** GREEN — `getAccessibleListIds(otherUser)` did not return a list owned exclusively by another user

### Full API Suite
- 15 test files passed | 3 skipped (Wave-0 stubs, expected) | 117 passed | 38 todo
- No regressions from prior plans

### TypeScript
- `pnpm --filter @familysync/api exec tsc --noEmit` — PASS

### ioredis Check
- `grep -r "ioredis" apps/api/` — not present (D-18 confirmed)

## Known Stubs

None. Both modules are fully implemented and tested.

## Threat Surface Scan

| Flag | File | Description |
|------|------|-------------|
| T-04-02 (mitigated) | apps/api/src/lib/listEmitter.ts | Fan-out channel keyed by listId; cross-list isolation proven by Test 2 |
| T-04-03 (mitigated) | apps/api/src/lib/listAccess.ts | Access-scope query restricted to owner_id OR list_shares; over-return proven impossible by Test 7 |
| T-04-04 (accepted) | apps/api/src/lib/listEmitter.ts | setMaxListeners(200) headroom applied; DoS risk accepted for household scale |

## Self-Check: PASSED

- `apps/api/src/lib/listEmitter.ts` — FOUND
- `apps/api/src/lib/listAccess.ts` — FOUND
- `apps/api/tests/lib/listEmitter.test.ts` — FOUND (stubs replaced)
- `apps/api/tests/lib/listAccess.test.ts` — FOUND
- `apps/api/vitest.config.ts` — FOUND (fileParallelism:false)
- Commit 2d250af (RED) — FOUND
- Commit 792efeb (GREEN) — FOUND
- Commit 9e17853 (fix) — FOUND
