Files

Jakub Zych 9368a18530 docs(02): research parity harness and validation

2026-09-16 15:55:53 +02:00

phase, slug, status, nyquist_compliant, wave_0_complete, created

phase	slug	status	nyquist_compliant	wave_0_complete	created
02	api-parity-harness-bootstrap	draft	false	false	2026-09-16

Phase 2 — Validation Strategy

Test Infrastructure

Property	Value
Framework	Go 1.27 `testing`, `httptest`; Testcontainers Postgres for app integration
Config file	Root `go.mod`; app `../fonoteka.go/go.mod`; no separate test config
Quick run	`go vet ./... && go test ./...` in root, then the same from `../fonoteka.go` once code exists
Full suite	Quick run plus `go test -race ./...` in both modules, CLI synthetic smoke, PHP self-replay on isolated local DB, route coverage audit
Estimated runtime	Measure during execution; Testcontainers and PHP checks are slower than package tests

After every implementation task commit: root go vet ./... && go test ./...; once app files exist, also run the app module checks.
After each plan wave: run the above and the slice's CLI smoke against a local httptest.Server or isolated PHP server as applicable.
Before $gsd-verify-work: run both modules' vet, test and race suites; run testcontainers Postgres integration; run PHP self-replay and inspect the 154-route coverage report.
Keep quick checks in seconds after build cache warmup. Measure actual runtime; no arbitrary latency promise is set.

Plan/task IDs are assigned after the required plan-count checkpoint. The planner must attach each row to an exact task and automated command.

Slice	Requirement	Threat Ref	Secure behavior	Test type	Automated command or assertion	Initial status
One-fixture record and replay through `summer`	QA-01, QA-02	T-02-01	Loopback target and bounded body handling	integration	`go test ./tide ./cmd/summer` with `httptest.Server`, fixture written then diffed	Pending
Live PHP proxy and scripted route recording	QA-01	T-02-01, T-02-02	Fixed upstream, scrub before write, no credential log	integration + operator smoke	`go test ./tide ./cmd/summer`; CLI capture from isolated PHP server	Pending
Structural JSON/byte diff and rule assertions	QA-02	T-02-03	Normalization rejects wrong token type or malformed date	unit	`go test ./tide -run 'Diff	Normalize
154-route manifest and client flows	QA-01	T-02-02	Only deterministic test identities committed	manifest audit + PHP replay	manifest validator reports `154/154 recorded`; PHP self-replay zero failures	Pending
Go replay seam and Postgres state	QA-02, QA-03	T-02-04	No false green for pending routes; seed hook allow-list	integration	`go test ./parity` in app module with testcontainers Postgres	Pending
Phase-wide test plan	QA-03	T-02-01 to T-02-04	Regression tests for all listed secure behaviors	unit + race + CLI	`go vet ./... && go test ./... && go test -race ./...` in both modules	Pending

First implementation slice adds tide package tests and cmd/summer command smoke test so record/replay is executable from its first commit.
App integration slice creates ../fonoteka.go/parity/parity_test.go, a Postgres-backed synthetic handler, and a pending-route fixture status check before any real Go API port exists.
Manifest validation rejects duplicate/missing route ids and reports exactly 154 PHP route definitions as the source snapshot.

Behavior	Requirement	Why manual	Test instructions
Fresh PHP backend capture and self-replay	QA-01, QA-02	Requires isolated PHP backend and database with local credentials	Start PHP on the agreed port with fresh parity DB, run seed/record, route manifest, Nuxt and MCP flows through proxy, then replay corpus against PHP; save command output and confirm zero failures.
Nuxt and MCP real sessions	QA-01	Browser consent and external MCP interaction cannot be fully represented by synthetic handler	Point `NUXT_DEV_BACKEND_ORIGIN` and `FONOTEKA_API_URL` at proxy, perform documented flows, confirm committed fixtures under `nuxt/` and `mcp/` contain placeholders and no credentials.

Each finalized plan task has an automated verify or an explicit manual gate.
No three consecutive tasks lack automated feedback.
Testcontainers Postgres test executes; it is not silently skipped in the phase completion run.
Root and app module go vet, go test, and go test -race pass.
PHP self-replay and 154-route coverage evidence are recorded.
Set nyquist_compliant: true only after all mapped checks exist and pass.

Approval: Pending execution evidence.