Phase 5: Data layer full fidelity - Discussion Log
Audit trail only. Do not use as input to planning, research, or execution agents.
Decisions are captured in CONTEXT.md — this log preserves the alternatives considered.
Date: 2026-09-18
Phase: 5-Data layer full fidelity
Areas discussed: Todo folding, Migration granularity, Model DX (fillable, hidden, rules), Encrypted cast compatibility, Attachments depth (DATA-08)
Todo folding
| Option |
Description |
Selected |
| Fold in as first task |
Run the models-leaf probe on keios.eu, jz and pxpx plugins at the start of Phase 5; amend the note if an "other" edge appears |
✓ |
| Keep it separate |
Leave as a pending todo; apply the rule on Fonoteka evidence only |
|
User's choice: Fold in as first task
Migration granularity
Context raised: P3 D-16 (squash per table) conflicts with roadmap criterion 1 ("all 27 migrations run up and down individually"); version.yaml actually lists 38 files across 26 versions.
Relation to PHP history
| Option |
Description |
Selected |
| Squash per table |
Keep P3 D-16; one create migration per final-state table, commented with folded PHP files; reword criterion 1 |
✓ |
| Mirror PHP one-to-one |
One Go migration per PHP file including renames and the items-to-albums flatten |
|
| Squash per PHP version |
One Go migration per version.yaml entry with a final-state effect |
|
Proving schema equality
| Option |
Description |
Selected |
| Schema-diff test vs PHP dump |
Committed normalized snapshot of PHP's final Postgres schema; testcontainers test diffs information_schema with a documented allow-list |
✓ |
| Hand-audited checklist |
Reviewer reads migration comments against PHP |
|
| You decide |
Researcher picks after checking PHP migrations on Postgres |
|
Widening the Phase 3 tables
| Option |
Description |
Selected |
| One widen migration per table |
widen_albums, widen_collections, widen_users after the Phase 3 pair |
✓ |
| Single "phase 5 widen" migration |
One ALTER migration for all three |
|
| You decide |
Planner orders by FK needs |
|
Data seeds
| Option |
Description |
Selected |
| Idempotent data migrations |
Same as genres seed (P3 D-18) |
✓ |
| Separate seed command |
Schema-only migrations plus fonoteka:seed |
|
Model DX: fillable, hidden, rules
Context raised: PHP API never serializes models via toArray() (SerializesFonoteka builds payloads); AlbumWriteService::FILL_FIELDS is a strict subset of Album::$fillable.
Declaring fillable
| Option |
Description |
Selected |
| Declared list + lagoon.Fill |
Fillable() []string copied from PHP; lagoon.Fill intersects requested and fillable names; services pass narrower lists |
✓ |
| Struct tags |
summer:"fillable" tags read by reflection |
|
| Hand-written DTO copy only |
No framework concept; DTO shape is the only boundary |
|
Unknown / non-fillable keys
| Option |
Description |
Selected |
| Silently ignored, as PHP |
Dropped, never persisted; logged once in non-production |
✓ |
| Reject with 422 |
Stricter than PHP; changes the contract |
|
Proving criterion 3 without write routes
| Option |
Description |
Selected |
| Service-level fuzz now |
Port write services' fill boundary and fuzz against Postgres; HTTP fuzz in Phase 12 |
✓ |
| One real write route now |
Pull a write route forward as the DTO reference |
|
| Framework-only test |
Fuzz lagoon.Fill on a fixture model only |
|
Hidden
| Option |
Description |
Selected |
| json:"-" + explicit serializers |
json:"-" on secrets, Hidden() list, marshal test, named Reveal override |
✓ |
| Generic lagoon.Serialize(model, opts) |
Reflection serializer with WithVisible option |
|
Rules
| Option |
Description |
Selected |
| Rules() map on model, validated on save |
PHP strings verbatim; lagoon translates to validator; Laravel-shaped 422 |
✓ |
| validate struct tags |
Hand-translated go-playground tags per field |
|
| You decide |
Researcher evaluates grammar coverage first |
|
Encrypted cast compatibility
Existing Laravel ciphertext
| Option |
Description |
Selected |
| GCM only; re-encrypt at import |
Cast handles only AES-GCM; ship a Laravel decrypt helper for the Phase 15 import |
✓ |
| Cast reads both, writes GCM |
CBC decrypt on the live read path, lazy re-encrypt |
|
| No migration of secrets |
Users re-enter keys after cutover |
|
Key source
| Option |
Description |
Selected |
| app.key, fail boot if missing |
32-byte base64, HKDF-derived column key, summer key:generate |
✓ |
| Dedicated database.encryption_key |
Separate secret for column encryption |
|
Rotation
| Option |
Description |
Selected |
| Versioned format + previous keys |
Key-id prefix; app.previous_keys decrypt-only |
✓ |
| Single key, no version prefix |
Simplest; rotation needs a format change later |
|
Go type
| Option |
Description |
Selected |
| lagoon.Encrypted type |
Scanner/Valuer; redacting MarshalJSON/String; explicit Reveal() |
✓ |
| Plain string + serializer tag |
gorm:"serializer:encrypted" on a string |
|
Attachments depth (DATA-08)
Table
| Option |
Description |
Selected |
| Winter's system_files shape |
Same table and columns, PHP class strings as morph names, framework-owned |
✓ |
| New clean table |
Go-native summer_files |
|
Storage depth
| Option |
Description |
Selected |
| Table, relations and path/URL math only |
Recommended cut; blob and thumbs later |
|
| Full blob storage now |
gocloud.dev/blob in this phase, thumbs later |
|
| Everything incl. thumbnails |
Blob storage plus 200x200 crop thumbs |
✓ |
Notes: User picked the largest scope over the recommendation. HTTP upload endpoint remains Phase 12.
Thumb shape
| Option |
Description |
Selected |
| Same name and path, lazy on first call |
Winter's thumb filename next to the original, generated when missing |
✓ |
| Same name, eager at attach time |
Generate declared sizes on attach |
|
| You decide |
Researcher confirms Winter's rules first |
|
Image library
| Option |
Description |
Selected |
| stdlib image + x/image/draw |
No cgo, quasi-stdlib |
|
| disintegration/imaging |
Convenient, unmaintained since 2020 |
|
| Researcher picks |
Maintained pure-Go option recorded in RESEARCH.md; no cgo |
✓ |
Bucket and serving
| Option |
Description |
Selected |
| fileblob at storage/app, config-driven URL, Go static handler |
Mirrors cms.php storage.uploads; memblob in tests |
✓ |
| Same, no Go static handler |
Reverse proxy serves files |
|
Delete behavior
| Option |
Description |
Selected |
| As Winter |
Soft delete keeps files; force delete removes rows in-tx and blobs after commit |
✓ |
| Never delete blobs automatically |
Prune command later |
|
Claude's Discretion
Hook naming and base model embed; pivot model shape; money cast type; jsonable cast shape; pagination helper API; callback-registry API and the cross-plugin extension demo pair; soft-delete + unique index strategy; which Serialize* functions are ported now; CLI-03 details; plan count and split.
Deferred Ideas
HTTP-level DTO fuzz (Phase 12/13); upload endpoint, manual cover URL, Discogs cover import (Phase 12/14); re-encrypt command; cutover import of secrets and files (Phase 15); S3/GCS bucket; Typesense and Centrifugo hooks on Album (Phase 11); roadmap wording fixes ("27 migrations", criterion 3 endpoint clause) at plan time.
