docs(31.1): capture phase context

This commit is contained in:
2026-11-13 13:32:26 +01:00
parent 3e29e6042e
commit db88fb15f2
2 changed files with 250 additions and 0 deletions

View File

@@ -0,0 +1,119 @@
# Phase 31.1: WavePath messaging parity - Context
**Gathered:** 2026-11-13
**Status:** Ready for planning
<domain>
## 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.
</domain>
<decisions>
## 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".
</decisions>
<canonical_refs>
## 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.
</canonical_refs>
<code_context>
## 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.
</code_context>
<specifics>
## 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).
</specifics>
<deferred>
## 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).
</deferred>
---
*Phase: 31.1-wavepath-messaging-parity*
*Context gathered: 2026-11-13*

View File

@@ -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