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