31 KiB
31 KiB
phase, plan, type, wave, depends_on, files_modified, autonomous, requirements, must_haves
| phase | plan | type | wave | depends_on | files_modified | autonomous | requirements | must_haves | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 05-data-layer-full-fidelity | 01 | execute | 1 |
|
true |
|
|
Purpose: every later plan in this phase only ever adds new files under models/, updates/, classes/ — this plan is what makes that true, and it ships the framework primitives (D-05, D-06, D-08, DATA-03, DATA-10) with no real Płytarium model yet depending on them, so they get their own focused tests before 25 models start using them. The models-leaf probe is gated as its own task (Task 1) before the restructure (Task 2) actually moves code, so an "other"-classified edge stops the restructure rather than being discovered mid-move.
Output: 3 new dated evidence sections plus a closed folded todo; restructured fonoteka.go plugins with working registries and a still-green genres parity fixture; lagoon.Fill, lagoon's five lifecycle hook interfaces, lagoon.WithSoftDeleteCascade, lagoon.Paginate, lagoon.RegisterJoinTable; corrected ROADMAP.md/REQUIREMENTS.md wording.
<execution_context> @$HOME/.claude/get-shit-done/workflows/execute-plan.md @$HOME/.claude/get-shit-done/templates/summary.md </execution_context>
@.planning/PROJECT.md @.planning/ROADMAP.md @.planning/STATE.md @.planning/phases/05-data-layer-full-fidelity/05-CONTEXT.md @.planning/phases/05-data-layer-full-fidelity/05-RESEARCH.md @.planning/notes/plugin-layout-winter-directories.md @.planning/todos/pending/verify-models-leaf-rule.mdFrom lagoon/order.go (allow-list-then-apply shape to reuse for Fill and RegisterJoinTable):
func orderClause(column, dir string, allowed []string) (string, error) {
if !allowListed(column, allowed) {
return "", fmt.Errorf("lagoon: order column %q is not allow-listed", column)
}
...
}
func allowListed(column string, allowed []string) bool { ... }
From lagoon/migrations.go (per-plugin history table + migrator() helper, unexported, same package — the framework-owned attach migration set Plan 04 adds later will reuse migrator() with a synthetic plugin id; do not change this file's public signatures):
func migrator(gdb *gorm.DB, pluginID string, migrations []*gormigrate.Migration) (*gormigrate.Gormigrate, error)
func Migrate(gdb *gorm.DB, plugins []party.Plugin) error
From phrasebook/translator.go (once-per-key non-production log dedup to copy for Fill's dropped-key logging):
func (t *Translator) logMissing(key string) {
if t.production { return }
if _, loaded := t.missing.LoadOrStore(key, struct{}{}); loaded { return }
slog.Warn("phrasebook: missing translation key", "key", key)
}
From pact/capabilities.go (HasModels/HasMigrations — plugin.go's Models()/Migrations() must keep satisfying these):
type HasModels interface { Models() []any }
type HasMigrations interface { Migrations() []*gormigrate.Migration }
From internal/build/leaf.go (the enforcement this plan's restructure must pass):
var modelsSiblingLeaves = []string{"classes", "controllers", "console", "jobs", "middleware", "updates"}
// inspectModelsImports fails if any file under <plugin>/models imports <module>/<sibling>[/...]
Gate: if every edge across the three plugins is cast-or-hook, move `.planning/todos/pending/verify-models-leaf-rule.md` to `.planning/todos/done/verify-models-leaf-rule.md` (create `done/` if it does not exist) with a one-line resolution note referencing the new evidence, and Task 2 (the restructure) proceeds. If any edge is "other", stop here: amend the rule text in the same note describing the exception, leave the todo in `pending/`, and do not execute Task 2 in this run — the restructure must not proceed under an unconfirmed rule (flag this to the orchestrator as a blocker requiring a plan revision before Task 2 runs).
Under each of `fonoteka.go/plugins/golem15/fonoteka` and `fonoteka.go/plugins/golem15/user`, create `models/`, `classes/`, `updates/` subpackages (plus `controllers/` and `middleware/` for fonoteka only, since user has no HTTP handler yet). Move struct-only files verbatim into `models/` (package name `models`): `genre.go`'s `Genre`/`Album` structs -> `models/genre.go` + `models/album.go`; `active_collection.go`'s `Collection`/`CollectionEditor`/`UserCollectionContext` structs -> `models/collection.go`, `models/collection_editor.go`, `models/user_collection_context.go`; `user.go`'s `User` struct -> `models/user.go`. Move service-calling / DB-lookup functions into `classes/` (package name `classes`): `active_collection.go`'s `ResolveActiveCollection`, `AccessibleByMembership`, `findAccessibleCollection`, `firstAccessibleRealCollection`, `persistContext`, `kindRealCollection` -> `classes/active_collection.go`; `user.go`'s `gormUsers`, `jwtSecret` -> `classes/user_lookup.go`. Move `genre_handler.go` into `controllers/genre_controller.go` (package `controllers`). Move `password.go`'s `mustChangePassword` into `middleware/must_change_password.go` (package `middleware`). Move `migrations.go`'s `var migrations` slice into `updates/00_base.go` (package `updates`), unchanged byte-for-byte (P3 D-17: shipped migrations are never edited, only moved).
Add a self-registering collision-free registry to each plugin so future plans (05-02..05-05) only ever add new files: in `models/registry.go` (package `models`), declare `var all []any` and `func Register(models ...any) { all = append(all, models...) }` / `func All() []any { return all }`; each moved model file's own `init()` calls `models.Register(Genre{})` etc. (one `Register` call per file, at the bottom of the file that declares the type). Do the same in `updates/registry.go` (package `updates`): `var all []*gormigrate.Migration`, `Register(ms ...*gormigrate.Migration)`, `All() []*gormigrate.Migration`; `updates/00_base.go`'s `init()` calls `updates.Register(migrations...)` on its own moved slice. Do the same for `classes/registry.go` for future GORM-callback/hook registrants: `var hookRegistrars []func(*gorm.DB) error`, `func RegisterHook(fn func(*gorm.DB) error) { hookRegistrars = append(hookRegistrars, fn) }`, `func RegisterHooks(gdb *gorm.DB) error { for _, fn := range hookRegistrars { if err := fn(gdb); err != nil { return err } }; return nil }` — no registrant exists yet in this plan (Plan 02 adds the first, `ArtistResolver`'s callback), this file just establishes the collector so Plan 02/05 never edit `plugin.go`'s `Boot`.
Update `plugin.go` in both plugins to its final, never-edited-again form: `func (p *Plugin) Models() []any { return models.All() }`, `func (p *Plugin) Migrations() []*gormigrate.Migration { return updates.All() }`, and in `Boot(app *backpack.App) error`, after the existing body, add `gdb, ok := app.Lookup[*gorm.DB](); if ok { if err := classes.RegisterHooks(gdb); err != nil { return err } }` (guarded by `ok` because `Boot` can run before the DB handle is published in some test paths — mirror the existing nil-tolerant style in `active_collection.go`). Move `fonoteka`'s route registration (`Routes(r pact.Router) error`, currently inline in `plugin.go`) into `routes.go` at the plugin root, calling `controllers.ListGenres(p.app)`. Update every import across both plugin modules and in `fonoteka.go/parity/*_test.go` and `fonoteka.go/app/app.go` to the new subpackage import paths (e.g. `git.golem15.com/golem15/fonoteka/plugins/golem15/fonoteka/models`, `.../controllers`). Do not change any table name, column name, exported HTTP contract, or migration ID — this is a pure package-boundary move.
In `lagoon/lifecycle.go`: declare the five hook interfaces using GORM's own native hook signatures (so a model needs no adapter to satisfy both GORM and `lagoon`'s naming): `type HasBeforeValidate interface { BeforeValidate(tx *gorm.DB) error }`, `HasBeforeCreate`, `HasBeforeSave`, `HasBeforeDelete interface { BeforeDelete(tx *gorm.DB) error }`, `HasAfterDelete interface { AfterDelete(tx *gorm.DB) error }` — each named `Has*` for symmetry with `pact`'s `Has*` capability-interface convention, but note in a doc comment that GORM itself dispatches these automatically by method name/signature match (no registration call needed) once a model implements them; the `Has*` names exist purely so other `lagoon`/test code can type-assert "does this model declare hook X" without calling it. Implement `func WithSoftDeleteCascade(tx *gorm.DB, cascade func(tx *gorm.DB) error) error` as a one-line wrapper: `if tx == nil { return fmt.Errorf("lagoon: soft-delete cascade tx is nil") }; return cascade(tx)` — document above it that callers invoke this from their own `BeforeDelete(tx *gorm.DB) error` method (GORM already runs `BeforeDelete` inside the same transaction as the parent `.Delete()` call, so no new transaction is opened here; this function names the pattern and gives it one central place other model files reference, per the "Collection cascades to Album" worked case DATA-03 needs in Plan 02).
Create `lagoon/relations.go` with `func RegisterJoinTable(db *gorm.DB, owner any, field string, joinModel any) error` — a thin, fail-loud wrapper over `db.SetupJoinTable(owner, field, joinModel)` that returns `fmt.Errorf("lagoon: register join table: db is nil")` if `db == nil` before calling through (GORM's own `SetupJoinTable` panics on a nil receiver, which this wrapper avoids). Above it, write a doc comment stating the pivot-write contract other plans must follow: pivot tables with business columns (e.g. `sort_order`, `role`/`granted_at`/`granted_by`) are never written through `db.Model(&owner).Association(field).Append/Replace(...)` — GORM's Association Mode has no documented path to set those columns — writes go through an explicit delete-then-bulk-insert (or `ON CONFLICT DO UPDATE`) function against the join table directly, in the same transaction as the parent save; reads use `Preload(field)` plus `.Order(...)` on the pivot's own columns once `RegisterJoinTable` has run. This task ships the wrapper and the documented contract only — the first real callers (`AlbumArtist`, `CollectionEditor`) and their sync functions are Plan 05-02.
Separately, as its own commit (CLAUDE.md: planning docs and code in separate commits): edit `.planning/REQUIREMENTS.md`'s `DATA-09` bullet to stop stating "27 migrations" as a target — reword to "All 25 Płytarium models and their squashed migration set are ported with matching table names, columns, indexes and defaults (migration count is not itself an acceptance number — squashed per plan-time decision D-01 in 05-CONTEXT.md)". Edit `.planning/ROADMAP.md`'s Phase 5 success criterion 1 to read "...and every Go migration runs up and down individually; the final schema matches PHP's (migrations are squashed per final-state table, not a 1:1 port of PHP's 38 files — the historical migration count is not a target)." Edit ROADMAP.md Phase 5 success criterion 3 to split its HTTP-DTO-fuzz clause out: reword to "The fill boundary of the PHP write services (at minimum Album, Collection and the four credential models) is fuzzed against real Postgres with random extra and server-owned keys, asserting nothing outside the allow-list is persisted (service-level, this phase); a request-DTO-level fuzz over every write endpoint is Phase 12's criterion (the HTTP layer does not exist until Phase 6/12)." Append one clause to Phase 12's existing success-criteria list in ROADMAP.md noting it inherits the endpoint-level fuzz test (do not renumber or otherwise restructure Phase 12's still-TBD plan count).
<threat_model>
Trust Boundaries
| Boundary | Description |
|---|---|
| caller -> lagoon.Fill | untrusted request-shaped map reaches a model's fields via reflection |
| plugin restructure -> auth middleware | must-change-password middleware moves files; a name/registration mistake could silently stop gating the authenticated surface |
STRIDE Threat Register
| Threat ID | Category | Component | Disposition | Mitigation Plan |
|---|---|---|---|---|
| T-05-01 | Tampering | lagoon.Fill |
mitigate | Allow-list copy only; unknown/unlisted keys are dropped, never set via reflection, and logged once in non-production (D-05/D-06) |
| T-05-02 | Elevation of Privilege | middleware.mustChangePassword after the plugin restructure |
mitigate | Task 2's acceptance criteria re-run TestParityCorpus, which replays the recorded genres fixture through the full jwt.auth+inv.must-change-password middleware chain — any registration-name or wiring mistake fails the existing parity fixture, not a new bespoke check |
| T-05-03 | Information Disclosure | lagoon.HasHidden/json:"-" interfaces declared this plan |
accept | No real model implements them yet (first credential model lands in Plan 05-03); the enforcement test (marshal-every-registered-model, assert hidden absent) is Plan 05-06's job once real models exist |
| </threat_model> |
<success_criteria>
- The models-leaf rule is confirmed (or amended) against 3 additional real plugins and the folded todo is closed before the restructure runs.
- Both
fonoteka.goplugins are Winter-directory-shaped with self-registeringmodels/updates/classespackages;plugin.goin each never needs editing again by a later plan in this phase. lagoon.Fill,lagoon.HasFillable,lagoon.HasHidden, the five lifecycle hook interfaces,WithSoftDeleteCascade,lagoon.Paginate, andlagoon.RegisterJoinTableexist, are tested, andgo vet ./...is clean in both repos.- The genres route's recorded parity fixture is unchanged and green.
- ROADMAP.md/REQUIREMENTS.md no longer claim "27 migrations" as a target and note the criterion-3 HTTP-fuzz move to Phase 12, committed separately from code. </success_criteria>