docs(03-03): complete typed params, rollback, and first real parity pass plan
Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
Jakub Zych
@@ -0,0 +1,159 @@
|
||||
---
|
||||
phase: 03-first-vertical-slice-genres-end-to-end
|
||||
plan: 03
|
||||
subsystem: api
|
||||
tags: [servemux, typed-params, gormigrate, rollback, parity, jwt, seed-hook]
|
||||
|
||||
requires:
|
||||
- phase: 03-first-vertical-slice-genres-end-to-end
|
||||
provides: Shared pgx-stdlib pool, JWT genre route, tenant-scoped album counts
|
||||
- phase: 02-api-parity-harness-bootstrap
|
||||
provides: App-owned newTarget/seedHooks seam and recorded GET genres fixture
|
||||
provides:
|
||||
- Typed integer path params plus registration-time regex and enum constraints
|
||||
- Per-plugin migrate:status IDs and migrate:rollback --plugin isolation
|
||||
- Temporary trusted genres seed hook and real-app fixture replay
|
||||
- Honest corpus counts: 154 recorded, 1 ported/passing, 153 pending
|
||||
affects: [03-04, 05, 06, 07, 12]
|
||||
|
||||
tech-stack:
|
||||
added: []
|
||||
patterns:
|
||||
- surf.Where/WhereIn compile constraints at registration; request text never builds regex or SQL
|
||||
- Ported routes with seed_hook skip global PHP bootstrap replay
|
||||
- Corpus passing increments only after the ported subtest succeeds
|
||||
|
||||
key-files:
|
||||
created:
|
||||
- surf/params.go
|
||||
- ../fonoteka.go/parity/genres_seed_test.go
|
||||
modified:
|
||||
- surf/router.go
|
||||
- pact/capabilities.go
|
||||
- lagoon/migrations.go
|
||||
- lagoon/commands.go
|
||||
- examples/hello/plugins/greeter/plugin.go
|
||||
- ../fonoteka.go/parity/parity_test.go
|
||||
- ../fonoteka.go/parity/manifest.yaml
|
||||
- ../fonoteka.go/README.md
|
||||
|
||||
key-decisions:
|
||||
- "Route constraints compile regex and enum allow-lists at registration; request path text is only matched"
|
||||
- "A ported route with a trusted seed_hook skips the global PHP bootstrap replay"
|
||||
- "Corpus passing increments only after the ported subtest succeeds; pending never counts as passing"
|
||||
- "Colliding fixture IDs are derived from CanonicalGenres seed order (rock=1, electronic=2, jazz=4)"
|
||||
|
||||
patterns-established:
|
||||
- "Pattern: pact.Router.Where/WhereIn plus surf.IntParam; malformed and unknown IDs both 404"
|
||||
- "Pattern: lagoon.ErrUnknownPlugin named error; rollback of golem15.fonoteka seed leaves user history intact"
|
||||
- "Pattern: seedHooks[\"genres\"] mints a test-only JWT into an in-memory tide.Store"
|
||||
|
||||
requirements-completed: [DATA-02, HTTP-01, HTTP-02, QA-04]
|
||||
|
||||
duration: 8min
|
||||
completed: 2026-09-17
|
||||
---
|
||||
|
||||
# Phase 03 Plan 03: Typed params, isolated rollback, first real parity pass Summary
|
||||
|
||||
**Typed ServeMux params, per-plugin `migrate:rollback`, and one honest Go pass of the recorded PHP genres fixture (154 recorded, 1 passing, 153 pending)**
|
||||
|
||||
## Performance
|
||||
|
||||
- **Duration:** 8 min
|
||||
- **Started:** 2026-09-17T18:14:59Z
|
||||
- **Completed:** 2026-09-17T18:23:20Z
|
||||
- **Tasks:** 2
|
||||
- **Files modified:** 17
|
||||
|
||||
## Accomplishments
|
||||
|
||||
- `surf.IntParam`, `Where`, and `WhereIn` compile regex/enum constraints at registration; `examples/hello` serves `/items/1`, 404s malformed and unknown IDs, and rejects enum values outside the allow-list.
|
||||
- `migrate:status` lists each plugin's applied IDs; `migrate:rollback --plugin=golem15.fonoteka` rolls back only the genre seed and returns `lagoon.ErrUnknownPlugin` for a missing plugin.
|
||||
- `newTarget` boots the real app; the temporary `genres` hook seeds Alice, an owned collection, a test-only JWT, and colliding IDs from CanonicalGenres order. The unmodified `get_genres_jwt.yaml` passes. Corpus: 154 recorded, 1 ported/passing, 153 pending.
|
||||
|
||||
## Task Commits
|
||||
|
||||
Each task was committed atomically (framework `summercms.go` then app `fonoteka.go` when both change):
|
||||
|
||||
1. **Task 1: Expose reversible plugin migrations and typed route parameters**
|
||||
- `8e3bf266d860c7416e8988845b70b190535c4b55` (feat, summercms.go)
|
||||
- `91e3df41e33c85818f4cc3470668853f04b67315` (feat, fonoteka.go)
|
||||
2. **Task 2: Turn the recorded genres route into one honest Go parity pass**
|
||||
- `0cc1a4da84ced8ed2451f2ea1c9a045f1c2ea682` (feat, fonoteka.go)
|
||||
|
||||
**Plan metadata:** (this commit)
|
||||
|
||||
## Files Created/Modified
|
||||
|
||||
- `surf/params.go` — `IntParam`, `Regex`, `Enum`; constraints compiled at registration
|
||||
- `pact/capabilities.go` — `Router.Where` / `WhereIn`
|
||||
- `lagoon/migrations.go` — `ErrUnknownPlugin`, `ErrNoMigrations`, isolated `RollbackLast`
|
||||
- `lagoon/commands.go` — `migrate:status` prints every applied ID
|
||||
- `examples/hello/plugins/greeter/plugin.go` — `{id}` regex route and enum `/kinds/{kind}`
|
||||
- `../fonoteka.go/parity/genres_seed_test.go` — trusted GORM Alice/collection hook and test-only JWT
|
||||
- `../fonoteka.go/parity/parity_test.go` — real `app.Handler`, skip global bootstrap when `seed_hook` is set, passing count after successful replay, mutated-response check
|
||||
- `../fonoteka.go/parity/manifest.yaml` — `GET /_fonoteka/api/v1/genres jwt` is `ported` with `seed_hook: genres`
|
||||
- `../fonoteka.go/README.md` — ICU `pl-PL` create, `migrate`, `migrate:status`, `migrate:rollback --plugin=golem15.fonoteka`, `serve`
|
||||
|
||||
## Decisions Made
|
||||
|
||||
- Constraints are compiled when the route is registered; enum values are an allow-list, not a regex built from request text.
|
||||
- A ported route with `seed_hook` does not replay unported global bootstrap endpoints.
|
||||
- Passing is incremented only after the ported subtest succeeds.
|
||||
- Fixture collisions `id:token=1`, `id:wishlist-album=2`, `id:genre=4` come from CanonicalGenres insertion order.
|
||||
|
||||
## Deviations from Plan
|
||||
|
||||
### Auto-fixed Issues
|
||||
|
||||
**1. [Rule 3 - Blocking] Synthetic proof tests kept `newSyntheticHandler` after `newTarget` became the real app**
|
||||
- **Found during:** Task 2 (real handler swap)
|
||||
- **Issue:** `TestParitySynthetic` and the contract `synthetic-postgres` subtest posted `/synthetic/items` through `newTarget`. The real app does not mount those routes.
|
||||
- **Fix:** Call `newSyntheticHandler` for the Phase 2 synthetic proof; `newTarget` boots `app.Handler`.
|
||||
- **Files modified:** `../fonoteka.go/parity/synthetic_test.go`, `../fonoteka.go/parity/parity_contract_test.go`, `../fonoteka.go/parity/parity_test.go`
|
||||
- **Verification:** `go test ./parity` including `TestParitySynthetic` and `TestParityCorpus`
|
||||
- **Committed in:** `0cc1a4d` (Task 2)
|
||||
|
||||
**2. [Rule 3 - Blocking] Rollback isolation uses a dedicated `rollback_iso` database**
|
||||
- **Found during:** Task 1 (rollback test)
|
||||
- **Issue:** Shared TestMain Postgres would lose the 15 genre rows (and shift serial IDs) if seed rollback ran in-place.
|
||||
- **Fix:** Create ICU `pl-PL` database `rollback_iso`, migrate/rollback there, leave the parity pool untouched.
|
||||
- **Files modified:** `../fonoteka.go/parity/migrate_test.go`
|
||||
- **Verification:** `TestRollbackLastIsolatesFonoteka` plus later genre/parity tests still see ids 1–15
|
||||
- **Committed in:** `91e3df4` (Task 1)
|
||||
|
||||
**3. [Discretion] `pact.Router` gained `Where`/`WhereIn`**
|
||||
- **Found during:** Task 1 (typed params)
|
||||
- **Issue:** Plan listed `surf/params.go` but plugins receive `pact.Router`; PHP `->where()` needs a method on that interface.
|
||||
- **Fix:** Add `Where`/`WhereIn` to `pact.Router` and implement them on `*surf.Router`/`*surf.Group`.
|
||||
- **Files modified:** `pact/capabilities.go`, `surf/router.go`
|
||||
- **Verification:** hello typed-route tests and `go vet ./...`
|
||||
- **Committed in:** `8e3bf26` (Task 1)
|
||||
|
||||
---
|
||||
|
||||
**Total deviations:** 3 (2 blocking test-isolation, 1 interface completeness)
|
||||
**Impact on plan:** No scope creep. QA-04 is green on one route; 153 remain pending.
|
||||
|
||||
## Issues Encountered
|
||||
|
||||
None that blocked the slice. `go.work.sum` and `.planning/config.json` `_auto_chain_active` were left uncommitted.
|
||||
|
||||
## User Setup Required
|
||||
|
||||
None - no external service configuration required beyond the existing Postgres ICU `pl-PL` database.
|
||||
|
||||
## Next Phase Readiness
|
||||
|
||||
Ready for `03-04-PLAN.md` (unit, integration, and security verification). The genres corpus route is `ported`. Do not treat pending routes as passing.
|
||||
|
||||
## Self-Check: PASSED
|
||||
|
||||
- Key files exist on disk (`surf/params.go`, `lagoon/commands.go`, `../fonoteka.go/parity/genres_seed_test.go`, `../fonoteka.go/parity/parity_test.go`)
|
||||
- `git log --grep=03-03` returns Task 1 and Task 2 commits in both repos
|
||||
- Acceptance: per-plugin rollback isolation, hello typed/enum 404s, unmodified `get_genres_jwt.yaml` 200 against the real handler, corpus 154/1/153, mutated response fails, no tide or fixture edits, `go vet`/`go test ./...` green in both repos
|
||||
|
||||
---
|
||||
*Phase: 03-first-vertical-slice-genres-end-to-end*
|
||||
*Completed: 2026-09-17*
|
||||
Reference in New Issue
Block a user