From db88fb15f201e82cba00a5ee74ee9e413264d354 Mon Sep 17 00:00:00 2001 From: Jakub Zych Date: Fri, 13 Nov 2026 13:32:26 +0100 Subject: [PATCH] docs(31.1): capture phase context --- .../31.1-CONTEXT.md | 119 ++++++++++++++++ .../31.1-DISCUSSION-LOG.md | 131 ++++++++++++++++++ 2 files changed, 250 insertions(+) create mode 100644 .planning/phases/31.1-wavepath-messaging-parity/31.1-CONTEXT.md create mode 100644 .planning/phases/31.1-wavepath-messaging-parity/31.1-DISCUSSION-LOG.md diff --git a/.planning/phases/31.1-wavepath-messaging-parity/31.1-CONTEXT.md b/.planning/phases/31.1-wavepath-messaging-parity/31.1-CONTEXT.md new file mode 100644 index 00000000..7b9f8e9d --- /dev/null +++ b/.planning/phases/31.1-wavepath-messaging-parity/31.1-CONTEXT.md @@ -0,0 +1,119 @@ +# Phase 31.1: WavePath messaging parity - Context + +**Gathered:** 2026-11-13 +**Status:** Ready for planning + + +## Phase Boundary + +The messaging routes of the WavePath corpus recorded in Phase 31 replay green against Go: group chat, channels, direct messages, threads, commands, reactions, emoji, preferences, pins and attachments, including the attachment streaming delta with Range support (31 D-12) released in `sm-chat-plugin`. Broadcast goldens for writing cases are asserted. `sm-bm-app` and `sm-demo-app` build and pass with each released plugin version (31 D-14). Unit tests are the last plan. + +Out of scope (Phase 31.2): presence and status, notifications and push, full link-unfurl resolve/jobs, webhook CRUD/ingest, bot REST and token guard, search, video and guests, forums and shared notes, zero-pending close-out and the security review. + +**Repos touched:** `sm-wavepath-app` (messaging handlers, row decorator, image proxies); `sm-chat-plugin` (Range streamer release); other shared chat plugins only for parity fixes found by replay; `sm-demo-app`, `sm-bm-app` and vue layers to follow shared-plugin changes. + + + + +## Implementation Decisions + +### Carry-forward from Phase 31 (binding) +- **D-01:** Phase 31 D-01, D-03, D-10, D-11, D-12, D-13, D-14 and D-16 still bind. Thin `/_wave` aliases; app plugin ports controller logic; every writing case has broadcast goldens; case depth is client paths plus denials; Range delta and messaging close this phase; quirks reproduced except security defects; shared-plugin shape wins with the bm/demo consumer gate; whole-corpus zero-pending closes in 31.2. +- **D-02:** Messaging slice scope matches research area E and the roadmap: group chat, channels, DM, threads, commands, host-facing reactions/emoji/prefs/pins/attachments, plus the chat Range release and unit tests. + +### Attachment URL in JSON +- **D-03:** **App-side rewrite only.** The WavePath row decorator rewrites attachment `url` to the PHP legacy path; the shared `/_chat` serializer keeps today's Go path. No D-14 field change for bm/demo/layers. — **Reversibility:** reversible — local to the app decorator. +- **D-04:** **Absolute URLs.** Rewritten values match PHP `url(...)`: `{app_base}/api/chat/attachments/{messageId}/{fileId}`. +- **D-05:** **HTTP and broadcasts.** Every `/_wave` JSON body and every chat/`wave` publication that embeds attachments carries the rewritten absolute `url`. +- **D-06:** **Host from app config base URL.** Use the Summer app URL (PHP `APP_URL` equivalent), not the request `Host` header. + +### Reactions and thread mute (locked without deep dive) +- **D-07:** **Map reactions onto the existing chat reactions API.** Do not port host `golem15_wavepath_reactions`. Observable `/_wave` shape is adapted in the app decorator as needed. — **Reversibility:** costly — MariaDB import and any later host-table migration must map onto chat reactions instead of a parallel host table. +- **D-08:** **Map thread mute onto chat `ThreadMute`.** Do not keep a separate host `ThreadSubscription` table for mute. — **Reversibility:** costly — same import concern as D-07. + +### Image helper routes vs 31.2 +- **D-09:** **Port `unfurl-image` and `webhook-icon` GETs in 31.1.** Full link-unfurl resolve/jobs and webhook CRUD/ingest stay in 31.2. Success cases use a seeded cache so chat UI image fetches replay green without the fetch pipeline. +- **D-10:** **Port the full proxy classes now** (`WebhookIconProxy`-equivalent and unfurl image serving) using `fetchguard`, still without CRUD or resolve jobs. +- **D-11:** **No live egress in `go test ./parity`.** Proxy fetches are answered from fixtures and upstream sidecars only. + +### Claude's Discretion +- Exact decorator merge order for shared row vs host extras (beyond D-03…D-06). +- Package and type names for the Range streamer and image proxies. +- How seeded unfurl/icon rows are laid out in the Phase 31 scenario without expanding corpus scope. +- Plan count and wave split inside 31.1, subject to lean planning and "unit tests last". + + + + +## 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; messaging split (D-16); Range in 31.1; consumer gate (D-14). +- `.planning/phases/31-chat-polish-against-wavepath-clients/31-RESEARCH.md` — area E sizing, attachment URL analysis, Range delta notes, controller inventory, image helper routes. +- `.planning/ROADMAP.md` — Phase 31.1 goal and success criteria. +- `.planning/phases/19-chat-and-chatchannels/19-CONTEXT.md` — shared serializer, context registry, alias rewrite. +- `.planning/notes/core-plugins-own-repos.md` — plugin commit, tag and submodule pointer workflow. + +### PHP contract (read-only) +- `/media/nvme/dev/jz/wavepath.org/plugins/golem15/wavepath/routes.php` — messaging, attachment, unfurl-image and webhook-icon routes. +- `/media/nvme/dev/jz/wavepath.org/plugins/golem15/wavepath/controllers/api/CommunityChatController.php` — `unfurlImage`, `webhookIcon`, `serveUnfurlFile`, AttachmentStreamer usage. +- `/media/nvme/dev/jz/wavepath.org/plugins/golem15/wavepath/classes/services/WebhookIconProxy.php` — remote icon proxy behaviour. +- `/media/nvme/dev/jz/wavepath.org/plugins/golem15/chat` at pin `fbfbcf9` — `AttachmentStreamer` / Range commits. + +### Go assets +- `../sm-chat-plugin/api/download.go` — current download handler (no Range yet). +- `../sm-chat-plugin/classes/serialize.go` — shared message/attachment `url` shape. +- `modules/tide/README.md` — replay, broadcast goldens, upstream sidecars, recorded headers for Range. +- `../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`, `../sm-demo-app/chat_test.go` — D-14 consumer gate. + + + + +## Existing Code Insights + +### Reusable Assets +- `sm-chat-plugin` download path streams via `bucket.NewReader` today; research recommends an exported Range-aware streamer in `classes` shared by plugin and app handlers (`blob.NewRangeReader` available in pinned gocloud). +- WavePath PHP already streams unfurl/webhook-icon through `AttachmentStreamer::forFile` (Range-aware, private inline) — Go should reuse the same streamer for those GETs. +- App row decoration pattern from Phase 19/31: shared serializer base + host merge in the wavepath app plugin. +- `tide` upstream sidecars and broadcast goldens from Phase 31 harness. + +### Established Patterns +- Fail-closed parity: pending never counts as pass; phase gate reports messaging pending zero for 31.1 close. +- Plugin first (commit, push, tag), then submodule pointer bumps; changelog post on `/changelog/plugins`. +- PHP quirks win except security defects → accepted-differences (created in Phase 31). + +### Integration Points +- Messaging handlers and aliases in `sm-wavepath-app` `wavepath` plugin. +- Range release changes generic `/_chat/api/v1/attachments/...` headers (additive; D-14 still runs). +- Image proxy GETs attach to group/channel/DM message routes already in the messaging controllers. + + + + +## Specific Ideas + +- User: "2,3 - map into existing api" for reactions and thread mute — prefer chat plugin APIs over host parallel tables even where research favoured host tables for import fidelity. +- Attachment URL: research recommendation (app-side rewrite) accepted as-is. +- Image helpers: prefer full proxy classes early over minimal read models, but keep parity tests offline (fixtures/sidecars). + + + + +## Deferred Ideas + +- Full link-unfurl resolve pipeline, OG fetch jobs, and webhook CRUD/ingest — Phase 31.2. +- Search backend choice (Typesense vs null driver) — Phase 31.2 discussion (31 D-16 note). +- Presence, status, push, video, guests, forums, notes, bot REST, zero-pending close-out, security review — Phase 31.2. + +### Reviewed Todos (not folded) +- Thirteen keyword matches; slash-command escape, moderation seams and OIDC PHP recording already folded into Phase 31. Remaining matches were noise for messaging (changelog prev/next, forum/friends 401 refresh, menu plugin, README fences, fonoteka README, translate messages editor, MailBlocker, social first-password, gate scripts naming apps). + + + +--- + +*Phase: 31.1-wavepath-messaging-parity* +*Context gathered: 2026-11-13* diff --git a/.planning/phases/31.1-wavepath-messaging-parity/31.1-DISCUSSION-LOG.md b/.planning/phases/31.1-wavepath-messaging-parity/31.1-DISCUSSION-LOG.md new file mode 100644 index 00000000..5ed84060 --- /dev/null +++ b/.planning/phases/31.1-wavepath-messaging-parity/31.1-DISCUSSION-LOG.md @@ -0,0 +1,131 @@ +# Phase 31.1: WavePath messaging parity - 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.1-wavepath-messaging-parity +**Areas discussed:** Attachment URL in JSON, Image helper routes vs 31.2 (Reactions storage and Thread mute mapping locked without deep dive) + +--- + +## Area selection + +| Option | Description | Selected | +|--------|-------------|----------| +| Attachment URL in JSON | PHP legacy path vs Go path | ✓ | +| Reactions storage | Host table vs chat API | locked as map-to-existing | +| Thread mute mapping | Host subscription vs chat ThreadMute | locked as map-to-existing | +| Image helper routes vs 31.2 | Port GETs now vs leave pending | ✓ | + +**User's choice:** Discuss 1 and 4; for 2 and 3 map into existing API. +**Notes:** No todos folded into 31.1. + +--- + +## Reactions storage (no deep dive) + +| Option | Description | Selected | +|--------|-------------|----------| +| Host model | Port `golem15_wavepath_reactions` | | +| Map into existing API | Use chat plugin reactions | ✓ | + +**User's choice:** Map into existing API. +**Notes:** Overrides research preference for host tables (import fidelity). + +--- + +## Thread mute mapping (no deep dive) + +| Option | Description | Selected | +|--------|-------------|----------| +| Host table | Keep `ThreadSubscription` | | +| Map into existing API | Use chat `ThreadMute` | ✓ | + +**User's choice:** Map into existing API. + +--- + +## Attachment URL in JSON + +| Option | Description | Selected | +|--------|-------------|----------| +| App-side rewrite only | WavePath decorator; shared `/_chat` unchanged | ✓ | +| Shared serializer change | D-14 release for all consumers | | +| Accepted difference | Leave Go paths in `/_wave` | | + +**User's choice:** App-side rewrite only. + +| Option | Description | Selected | +|--------|-------------|----------| +| Absolute | Match PHP `url(...)` with host | ✓ | +| Path-only | `/api/chat/attachments/...` | | +| Fixture-driven | Match whatever one golden shows | | + +**User's choice:** Absolute. + +| Option | Description | Selected | +|--------|-------------|----------| +| HTTP and broadcasts | REST + publications with attachments | ✓ | +| HTTP only | Leave broadcast payloads as shared serializer | | +| You decide | Green replay is enough | | + +**User's choice:** HTTP and broadcasts. + +| Option | Description | Selected | +|--------|-------------|----------| +| App config base URL | Summer app URL / PHP APP_URL | ✓ | +| Request Host | Build from incoming request | | +| You decide | Fixtures agree | | + +**User's choice:** App config base URL. + +--- + +## Image helper routes vs 31.2 + +| Option | Description | Selected | +|--------|-------------|----------| +| Port the GETs in 31.1 | unfurl-image + webhook-icon; CRUD/jobs later | ✓ | +| Leave pending until 31.2 | Messaging gate ignores them | | +| Port unfurl-image only | webhook-icon with webhooks | | + +**User's choice:** Port the GETs in 31.1. + +| Option | Description | Selected | +|--------|-------------|----------| +| Seeded cache | Success from fixtures; miss matches PHP | ✓ | +| Always 404 until 31.2 | Only denials in 31.1 | | +| You decide | Green cases | | + +**User's choice:** Match PHP with seeded cache. + +| Option | Description | Selected | +|--------|-------------|----------| +| Minimal read models only | Fixture rows, no proxy classes | | +| Full proxy classes now | fetchguard proxies; no CRUD/jobs | ✓ | +| You decide | Green GETs | | + +**User's choice:** Port the full proxy classes now. + +| Option | Description | Selected | +|--------|-------------|----------| +| Fixture / sidecar only | No live egress in parity tests | ✓ | +| Allow live fetchguard | Real HTTP when allow-listed | | +| You decide | No flaky deps | | + +**User's choice:** Fixture / sidecar only. + +--- + +## Claude's Discretion + +- Decorator merge details beyond the locked URL rewrite rules +- Streamer and proxy type names +- Scenario seed layout for unfurl/icon rows +- Plan count inside the phase + +## Deferred Ideas + +- Full unfurl resolve/jobs and webhook CRUD → Phase 31.2 +- Search backend → Phase 31.2 discussion