docs(02-02): complete capture-sessions-and-manifest-coverage plan

Tasks completed: 3/3 - Capture a complete named session through the proxy - Replay stateful flows with safe capture and strict differences - Record manifest route cases and report complete coverage SUMMARY: .planning/phases/02-api-parity-harness-bootstrap/02-02-SUMMARY.md Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-17 12:37:17 +02:00
parent 24c1f43e84
commit 0824f31d08
1 changed files with 154 additions and 0 deletions
--- a/.planning/phases/02-api-parity-harness-bootstrap/02-02-SUMMARY.md
+++ b/.planning/phases/02-api-parity-harness-bootstrap/02-02-SUMMARY.md
@@ -0,0 +1,154 @@
+---
+phase: 02-api-parity-harness-bootstrap
+plan: 02
+subsystem: testing
+tags: [tide, parity, proxy, capture, normalize, manifest, coverage]
+
+requires:
+  - phase: 02-api-parity-harness-bootstrap
+    provides: Version-1 tide Flow/Step, LoadFlow/SaveFlow, RecordFlow/ReplayFlow, parity:record and parity:replay
+provides:
+  - Loopback httputil reverse proxy grouping named Nuxt/MCP sessions
+  - Named capture, private variable store, and credential scrub into placeholders
+  - Shape-aware JSON normalizer and D-13/D-14/D-15 comparison classes
+  - Generic manifest recorder with --next-batch 15 --resume and coverage table
+affects: [02-03, 02-04, 02-05]
+
+tech-stack:
+  added: []
+  patterns:
+    - ReverseProxy Rewrite/SetURL pins a loopback upstream; client Host is ignored
+    - Secrets live in a mode-0600 --vars file outside fixtures; YAML holds {{name}} placeholders
+    - Dates and integer ids are asserted then masked at compare time; slugs stay exact
+    - Manifest pending mismatches are measured; ported mismatches and --self-check fail the run
+
+key-files:
+  created:
+    - tide/proxy.go
+    - tide/rules.go
+    - tide/variables.go
+    - tide/normalize.go
+    - tide/manifest.go
+    - tide/report.go
+    - tide/proxy_test.go
+    - tide/rules_test.go
+    - tide/capture_test.go
+    - tide/normalize_test.go
+    - tide/diff_test.go
+    - tide/headers_test.go
+    - tide/flow_test.go
+    - tide/manifest_test.go
+  modified:
+    - tide/flow.go
+    - tide/fixture.go
+    - tide/record.go
+    - tide/replay.go
+    - tide/diff.go
+    - cmd/summer/parity.go
+    - cmd/summer/parity_test.go
+    - cmd/summer/main.go
+
+key-decisions:
+  - "Proxy bind and upstream must be loopback HTTP; incoming Host/URL never selects the PHP origin"
+  - "Capture rules and a private 0600 variable store drive {{jwt:alice}} substitution; unclassified credential shapes fail fixture writes"
+  - "Carbon *_at values must match +00:00 before masking; Z, string ids, null vs [] and missing keys fail at $.path"
+  - "154 is the app manifest's validated route count, not a framework constant; this workflow refuses --next-batch above 15"
+
+patterns-established:
+  - "Pattern: X-Parity-Session or --session names a flow written to nuxt/<session>.yaml or mcp/<session>.yaml"
+  - "Pattern: Replay continues after comparison diffs and skips only the remainder of a flow after a failed capture"
+  - "Pattern: --update is required to overwrite an existing case fixture; --resume skips valid hashed fixtures"
+
+requirements-completed: [QA-01, QA-02, QA-03]
+
+duration: 12min
+completed: 2026-09-17
+---
+
+# Phase 2 Plan 2: Capture Sessions and Manifest Coverage Summary
+
+**Loopback `parity:proxy` records scrubbed multi-step sessions, and `parity:record --manifest` resumes 15-route batches with a recorded/passing/failing/unrecorded coverage table**
+
+## Performance
+
+- **Duration:** 12 min
+- **Started:** 2026-09-17T10:24:42Z
+- **Completed:** 2026-09-17T10:36:58Z
+- **Tasks:** 3
+- **Files modified:** 21
+
+## Accomplishments
+
+- `parity:proxy` forwards a named session to a fixed loopback upstream, preserves cookies/redirects/bytes, and writes ordered flows without partial or credential-shaped fixtures
+- Named captures populate a private `--vars` store; replay expands placeholders before send and scrubs JWT, `inv_` tokens, OAuth codes, PKCE verifiers and `auth_token` cookies
+- Manifest mode records one-step route cases, refuses silent overwrite, resumes at most 15 unrecorded routes, and prints coverage; pending mismatches do not fail unless `--self-check`
+
+## Task Commits
+
+Each task was committed atomically:
+
+1. **Task 1: Capture a complete named session through the proxy** - `bb6a5a9` (feat)
+2. **Task 2: Replay stateful flows with safe capture and strict differences** - `aa165fe` (feat)
+3. **Task 3: Record manifest route cases and report complete coverage** - `24c1f43` (feat)
+
+**Plan metadata:** pending `docs(02-02)` commit
+
+## Files Created/Modified
+
+- `tide/proxy.go` - Loopback ReverseProxy, session grouping, overflow and flush
+- `tide/rules.go` - Strict YAML capture rules keyed by method and path pattern
+- `tide/variables.go` - Store, capture, placeholder expand and secret scrub
+- `tide/normalize.go` - Carbon `+00:00` and integer id assertions before masking
+- `tide/manifest.go` - Generic manifest load/validate/record/replay
+- `tide/report.go` - Coverage table and recorded/passing/failing/unrecorded counts
+- `tide/diff.go` / `tide/replay.go` / `tide/record.go` - Header allow-list, sidecar digest, continue-on-mismatch
+- `cmd/summer/parity.go` - `parity:proxy` plus `--manifest`, `--vars`, `--next-batch`, `--self-check`
+
+## Decisions Made
+
+- Keep the proxy on plain HTTP loopback with `Rewrite`/`SetURL`; tests may override upstream only with a loopback httptest URL
+- Persist seed captures only in `--vars` (mode 0600, outside the fixture tree); fixtures and logs hold placeholders
+- Compare global Content-Type/pagination/CORS plus per-route Cache-Control, Pragma, WWW-Authenticate and Content-Disposition; never Date, Server or request ids
+- `--next-batch` above 15 is refused; omitting the flag records all remaining synthetic routes so small tests stay simple
+
+## Deviations from Plan
+
+### Auto-fixed Issues
+
+None - plan executed as written. TDD_MODE=false used one green commit per task (tests + implementation together), matching 02-01. Toolchain `go1.27.0` was left untouched (no new module). SaveFlow still uses the dedicated YAML writer from 02-01.
+
+---
+
+**Total deviations:** 0 auto-fixed
+**Impact on plan:** None. 02-01 deviations (toolchain pin, SaveFlow encoder) were preserved.
+
+## Issues Encountered
+
+None. QA-01/QA-02/QA-03 remain phase-level: this plan delivers proxy sessions, strict diffs and a generic manifest runner, not the 154-route PHP corpus (Plan 03) or testcontainers (Plan 04). Frontmatter copies the plan's requirements list; they should not be treated as milestone-complete.
+
+## User Setup Required
+
+None - no external service configuration required.
+
+## Next Phase Readiness
+
+Ready for 02-03-PLAN.md (PHP capture and the app 154-route manifest). Public APIs added: `NewProxy`, `LoadRules`, `OpenStore`, `LoadManifest`, `RecordManifest`, `ReplayManifest`, `Coverage`.
+
+## Verification
+
+- Task 1: `go test ./tide ./cmd/summer -run 'TestProxy|TestParityCommands'` pass
+- Task 2: `go test ./tide -run 'TestProxy|TestCapture|TestScrub|TestNormalize|TestDiff|TestHeaders|TestFlow'` pass
+- Task 3: `go test ./tide ./cmd/summer -run 'TestManifest|TestCoverage|TestParityCommands'` pass
+- Plan: `go vet ./...` and `go test ./...` exit 0
+- No Fonoteka/Płytarium route names in `tide` or `cmd/summer` production sources
+
+## Self-Check: PASSED
+
+- [x] Key files exist on disk
+- [x] `git log --grep=02-02` returns Task 1, Task 2 and Task 3 commits
+- [x] Task acceptance criteria re-run and pass
+- [x] Plan verification commands pass
+
+---
+*Phase: 02-api-parity-harness-bootstrap*
+*Completed: 2026-09-17*