diff --git a/.planning/phases/31.2-wavepath-satellites-parity-and-close-out/31.2-CONTEXT.md b/.planning/phases/31.2-wavepath-satellites-parity-and-close-out/31.2-CONTEXT.md new file mode 100644 index 00000000..00fe9403 --- /dev/null +++ b/.planning/phases/31.2-wavepath-satellites-parity-and-close-out/31.2-CONTEXT.md @@ -0,0 +1,125 @@ +# Phase 31.2: WavePath satellites parity and close-out - Context + +**Gathered:** 2026-11-13 +**Status:** Ready for planning + + +## Phase Boundary + +The rest of the WavePath corpus replays green against Go and the corpus closes at zero pending (31 D-15): presence and status, notifications and push, full link-unfurl resolve/jobs, webhook CRUD/ingest, bot REST with the token guard, search, video and guests (including the guest thread and guest identity freeze delta), forums and shared notes (on the minimal provisional diary read model from 31 D-18). Broadcast goldens and upstream sidecars are asserted. The fail-closed gate in `sm-wavepath-app` requires zero pending and that `sm-bm-app` and `sm-demo-app` build and pass. Accepted-differences are signed off in a batch at close-out. The security review of guest, bot/token, webhook and access resolvers runs as part of that close-out and its findings are resolved before the phase ends. Unit tests are the last plan. The unattended re-record-with-drift path remains runnable (31 D-06); the pre-freeze re-record itself stays a WavePath cutover task. + +Out of scope: MariaDB→Postgres import and production cutover; diary/practices/trainings/stats beyond the provisional notes read model; `wavepath-mcp` diary surface; desktop clients as recording clients. + +**Repos touched:** `sm-wavepath-app` (satellite handlers, host seams, provisional diary, gate at zero pending); shared plugin repos for parity fixes; `sm-demo-app`, `sm-bm-app` and vue layers to follow; folded vue-forum / vue-userfriends 401 refresh. + + + + +## Implementation Decisions + +### Carry-forward from Phases 31 and 31.1 (binding) +- **D-01:** Phase 31 D-01, D-03, D-06, D-10, D-11, D-12, D-13, D-14, D-15, D-16 and D-18 still bind. Thin `/_wave` aliases; app plugin ports host controller logic; broadcast goldens and upstream sidecars; case depth; freeze at recording commit with guest delta here; quirks except security defects → accepted-differences; shared-plugin shape wins with bm/demo consumer gate; zero pending closes this phase; notes on a minimal provisional `DiaryEntry` read model; re-record path left runnable unattended. +- **D-02:** Phase 31.1 D-03…D-06 (attachment URL rewrite), D-09…D-11 (image helper GETs already ported; no live egress in `go test ./parity`) still bind. Full unfurl resolve/jobs and webhook CRUD/ingest are in this phase and stay parity-offline for tests (see D-04). + +### Search backend +- **D-03:** **Typesense on both sides for the search cases.** Run Typesense containers for PHP recording and Go replay so `GET …/search` exercises a real indexed result set, not the null-driver empty response. — **Reversibility:** costly — recording and goldens assume Typesense-backed hits; switching to null later invalidates search fixtures. + +### Unfurl resolve and webhook ingest +- **D-04:** **Keep parity offline.** Recording may capture real upstream responses into tidecars once; `go test ./parity` never performs live egress for unfurl resolve/jobs or webhook outbound fetches. Replay answers from fixtures and upstream sidecars only (same rule as 31.1 D-11 for image helpers). — **Reversibility:** reversible — local to the parity harness. + +### Satellite port order +- **D-05:** **Port by the suggested bundles, in this order:** (1) presence, status, notifications and push; (2) webhooks, bot REST with token guard, and search; (3) video and guests (including guest thread/identity delta); (4) forums and shared notes; (5) close-out (accepted-differences batch sign-off, security review and findings, zero-pending gate, consumer builds, unit tests last). — **Reversibility:** reversible — plan-wave ordering only. + +### Close-out +- **D-06:** **Batch accepted-differences sign-off at the end.** Entries may be drafted while routes are ported, but the user signs the file once at close-out, not route-by-route. — **Reversibility:** reversible — process only. +- **D-07:** **Security review is part of close-out, before the phase is done.** Run it over guest access, bot and token authentication, webhook and access resolvers; resolve findings before the zero-pending gate is accepted as green. Prefer review after the satellite code exists (after bundles 1–4), not before zero pending is reachable. — **Reversibility:** reversible — sequencing only. + +### Claude's Discretion +- Exact package/type/handler names inside the app plugin and how provisional diary rows are laid out beyond 31 D-18. +- Typesense image tag and how PHP Scout / Go search wire into the parity stack, as long as D-03 holds. +- Plan count and wave split inside D-05, subject to lean planning and "unit tests last". +- Gate script and accepted-differences file names (already Claude's discretion in Phase 31). + +### Folded Todos +- **Single-flight 401 refresh in the forum and friends clients** (`forum-friends-client-401-refresh.md`, `vue-forum-layer` / `vue-userfriends-layer`). Forum and friends hooks never retry on 401; after JWT expiry forum shows "thread not found" while chat still works. Give both clients the chat-shaped `{token, refresh, unauthorized}` auth hook, single-flight refresh-and-retry, and a signed-out message instead of not-found. Fits because forums land in this phase's corpus and the layers must follow shared/forum consumer behaviour. + + + + +## Canonical References + +**Downstream agents MUST read these before planning or implementing.** + +### Prior phase contract +- `.planning/phases/31-chat-polish-against-wavepath-clients/31-CONTEXT.md` — D-01…D-22; corpus boundary; D-15/D-16 zero-pending in 31.2; D-18 notes; security review deferred here. +- `.planning/phases/31-chat-polish-against-wavepath-clients/31-RESEARCH.md` — area F sizing, Pitfall 7 (Typesense vs null), controller inventory, rate buckets. +- `.planning/phases/31.1-wavepath-messaging-parity/31.1-CONTEXT.md` — messaging closed; image helpers offline; attachment URL rewrite; unfurl/webhook full pipeline deferred here. +- `.planning/phases/19.1-chat-satellites/19.1-CONTEXT.md` — herald push, LiveKit, forum, chatbots, userfriends generic APIs and seams. +- `.planning/phases/19-chat-and-chatchannels/19-CONTEXT.md` — serializer, context registry, alias rewrite, lighthouse namespaces. +- `.planning/ROADMAP.md` — Phase 31.2 goal and success criteria. +- `.planning/notes/core-plugins-own-repos.md` — plugin commit, tag and submodule pointer workflow. +- `.planning/notes/2026-10-18-webpush-go.md` — herald webpush-go pin. +- `.planning/notes/2026-10-18-livekit-server-sdk-go.md` — chatvideo LiveKit pin. + +### PHP contract (read-only) +- `/media/nvme/dev/jz/wavepath.org/plugins/golem15/wavepath/routes.php` — presence, status, push, unfurl, webhooks, bot/token, search, video, guest, forums, notes. +- `/media/nvme/dev/jz/wavepath.org/plugins/golem15/wavepath/controllers/api/` — community satellite controllers (`CommunityPresenceController`, `CommunityStatusController`, `PushSubscriptionController`, unfurl/webhook controllers, `BotRestController`, search, video/guest, forum, shared notes). +- `/media/nvme/dev/jz/wavepath.org/plugins/golem15/wavepath/Plugin.php` — host seam bindings and group lifecycle. +- `/media/nvme/dev/jz/wavepath.org/plugins/golem15/wavepath/classes/{notifications,forum,video,chatbots}/` — host seam implementations. + +### Go / harness assets +- `modules/tide/README.md` — replay, broadcast goldens, upstream sidecars. +- `../sm-herald-plugin/`, `../sm-chatvideo-plugin/`, `../sm-forum-plugin/`, `../sm-chatbots-plugin/`, `../sm-chatchannels-plugin/` — satellite plugins (search indexer / Typesense seam lives with channels research notes). +- `../sm-bm-app/summer.yaml`, `../sm-bm-app/chat_test.go`, `../sm-bm-app/realtime_test.go` — D-14 consumer gate. +- `../sm-demo-app/summer.yaml` and its chat/realtime/video tests — D-14 consumer gate. +- `.planning/todos/pending/forum-friends-client-401-refresh.md` — folded todo. + + + + +## Existing Code Insights + +### Reusable Assets +- Shared satellite plugins already expose typed services and `/_x/api/v1` APIs; WavePath `/_wave` handlers are thin aliases plus host merge (31 D-01/D-03). +- Herald push through `webpush-go` + fetchguard; chatvideo LiveKit + upstream sidecars; forum Markdown + deny-all resolver — all from Phase 19.1. +- 31.1 image proxies and attachment URL decorator patterns for extending unfurl/webhook host routes. +- `tide` upstream sidecars and broadcast goldens for push and LiveKit assertions. + +### Established Patterns +- Fail-closed parity: pending never counts as pass; Phase 31.2 gate requires total zero pending. +- Plugin first (commit, push, tag), then submodule pointer bumps; changelog on `/changelog/plugins`. +- PHP quirks win except security defects → accepted-differences (final batch sign-off this phase). +- No live egress in `go test ./parity` (31.1 D-11 extended by D-04). + +### Integration Points +- App plugin: presence/`wave` authorizers, herald profile and presence gate, notification dispatch, bot auth resolver, forum access resolver, video/guest host logic, provisional diary for notes, webhook ingest. +- Typesense containers on the Phase 31 isolated PHP stack and on Go parity for search cases (D-03). +- Folded 401 refresh in `vue-forum-layer` and `vue-userfriends-layer` alongside forum route parity. + + + + +## Specific Ideas + +- User skipped point-by-point discussion and locked all four gray areas in one reply: Typesense; keep parity offline; suggested satellite order; batch accepted-differences at the end. +- Security review placed in close-out after satellite code exists, findings resolved before phase done. + + + + +## Deferred Ideas + +- Pre-freeze corpus re-record with drift report — WavePath cutover phase (31 D-06). +- Full diary/practices/trainings/stats and MariaDB import — later WavePath phases. +- `wavepath-mcp` as a recording client — later WavePath backend corpus. + +### Reviewed Todos (not folded) +- OIDC PHP parity recording, chat slash-command escape, and moderation seams — already folded into Phase 31. +- Remaining keyword matches were noise for this phase (changelog prev/next, menu plugin, README fences, fonoteka README, translate messages editor, MailBlocker, social first-password, gate scripts naming apps, Winter vs Summer benchmark). + + + +--- + +*Phase: 31.2-wavepath-satellites-parity-and-close-out* +*Context gathered: 2026-11-13* diff --git a/.planning/phases/31.2-wavepath-satellites-parity-and-close-out/31.2-DISCUSSION-LOG.md b/.planning/phases/31.2-wavepath-satellites-parity-and-close-out/31.2-DISCUSSION-LOG.md new file mode 100644 index 00000000..dfbc40e4 --- /dev/null +++ b/.planning/phases/31.2-wavepath-satellites-parity-and-close-out/31.2-DISCUSSION-LOG.md @@ -0,0 +1,82 @@ +# Phase 31.2: WavePath satellites parity and close-out - Discussion Log + +> **Audit trail only.** Do not use as input to planning, research, or execution agents. +> Decisions are captured in CONTEXT.md — this log preserves the alternatives considered. + +**Date:** 2026-11-13 +**Phase:** 31.2-wavepath-satellites-parity-and-close-out +**Areas discussed:** Search backend, Unfurl resolve & webhook ingest, Satellite port order, Close-out gates (batch answers; no point-by-point deep dive) + +--- + +## Todos fold-in + +| Option | Description | Selected | +|--------|-------------|----------| +| Forum/friends 401 refresh | Single-flight 401 refresh in forum and friends vue layers | ✓ | +| OIDC PHP parity | Already in Phase 31 | | +| Chat slash escape | Already in Phase 31 | | +| Moderation seams | Already in Phase 31 | | +| None | Leave all out | | + +**User's choice:** Forum/friends 401 refresh +**Notes:** Folded into 31.2 because forums are in this corpus. + +--- + +## Search backend + +| Option | Description | Selected | +|--------|-------------|----------| +| Typesense containers both sides | Real indexed search cases | ✓ | +| SCOUT_DRIVER=null | Empty results; weaker fixture | | + +**User's choice:** Typesense +**Notes:** Locked without deep dive ("1 typesense"). + +--- + +## Unfurl resolve & webhook ingest + +| Option | Description | Selected | +|--------|-------------|----------| +| Keep parity offline | Fixtures + upstream sidecars only in `go test ./parity` | ✓ | +| Controlled live during recording | Live fetch allowed in some harness paths | | + +**User's choice:** Keep parity offline +**Notes:** Aligns with 31.1 D-11 for image helpers. + +--- + +## Satellite port order + +| Option | Description | Selected | +|--------|-------------|----------| +| Suggested bundles | presence/push → webhooks/bot/search → video/guests → forums/notes → close-out | ✓ | +| Different cut | User-defined reordering | | + +**User's choice:** As suggested +**Notes:** No alternative order proposed. + +--- + +## Close-out gates + +| Option | Description | Selected | +|--------|-------------|----------| +| Sign accepted-differences as routes land | Continuous sign-off | | +| Batch at the end | One sign-off at close-out | ✓ | +| Security review before vs after zero pending | (clarified in CONTEXT as close-out after code exists, findings before done) | ✓ (batch/close-out) | + +**User's choice:** Batch at the end +**Notes:** User answered area 4 as "batch at the end"; security review interpreted as part of that close-out sequence. + +--- + +## the agent's Discretion + +- Package/type names, Typesense wiring details under D-03, plan/wave split inside D-05, gate and accepted-differences file names. + +## Deferred Ideas + +- Pre-freeze re-record (WavePath cutover); full diary backend; wavepath-mcp recording client.