docs(31.1): capture phase context
This commit is contained in:
119
.planning/phases/31.1-wavepath-messaging-parity/31.1-CONTEXT.md
Normal file
119
.planning/phases/31.1-wavepath-messaging-parity/31.1-CONTEXT.md
Normal 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*
|
||||||
@@ -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
|
||||||
Reference in New Issue
Block a user