IU → 1-to-many Artifacts + Per-Region Drift #
Why #
An IU is a unit of intent (a regenerative grain). A file is an artifact of the compile target. Binding them 1:1 couples the grain to one implementation's file layout. Real backends need:
- one IU → many files (migration + schema + routes + …), and
- many IUs → one shared file (the migrations table, a shared schema, routing).
So the relationship is many-to-many, mediated by the architecture target. The target owns the file layout; the IU owns roles of content, some owned (exclusive file) and some contributions to a shared aggregate file.
The migration is the perfect first case: it is intrinsically shared (it's why we hit
the duplicate-CREATE TABLE bug — two IUs fought over one concern).
Increment 1 (this pass): shared migrations aggregate + per-region drift #
Model (models/manifest.ts) #
FileRegion { iu_id, role, content_hash, start_line, end_line }SharedFileManifest { path, content_hash, regions[] }GeneratedManifest.shared_files?: Record<path, SharedFileManifest>DriftEntrygains optionalrole,region(start/end line) so drift attributes to the owning IU and the specific region.
Artifact split (artifacts.ts, NEW) #
splitSharedArtifacts(results, target):
- Extract every
registerMigration('table', \…`)from each IU module (the migration is amigration`-role contribution, not module-owned content). - Remove it from the module; remap that module's
line_provenance(line indices shift when the block is removed) so inspector provenance stays exact. - Dedupe by table name (keep first owner) — kills duplicate
CREATE TABLEstructurally. - Assemble
src/generated/_migrations.ts: each contribution wrapped in// <<phx:region iu=… role=migration table=…>> … // <</phx:region>>. - Return updated results + the
SharedFileManifest+ the side-effect import path.
Manifest (manifest.ts) #
load()defaultsshared_files: {}.recordSharedFiles(SharedFileManifest[]).
Drift (drift.ts) #
- Iterate
shared_files. Fast path: whole-file hash matches → all regions clean. Else parse region markers on disk, hash each region body, compare to manifest region by(iu_id, role), emit oneDriftEntryper region (CLEAN/DRIFTED/WAIVED/MISSING) carryingiu_id,role,regionlines.
Scaffold (scaffold.ts) #
generateScaffold(..., sharedImports: string[])addsimport './generated/_migrations.js';toserver.tsbeforerunMigrations()so registrations still run.
CLI (cli.ts) #
cmdBootstrap+cmdRegen: aftergenerateAll, callsplitSharedArtifacts, write the shared file,recordSharedFiles, passsharedImportsto scaffold. Drift report prints per-region lines for shared files.
Tests #
artifacts.test.ts: extraction, line-provenance remap, dedupe, region offsets.drift-region.test.ts: clean / single-region drift attributed to the right IU.
Status: Increment 1 SHIPPED ✅ #
Verified end-to-end on Trail: 4 modules → 1 shared _migrations.ts with 4 owned
regions; modules no longer self-register; server.ts imports the aggregate before
runMigrations(); app boots on a fresh DB and serves /issue + /sprint (tables
created from the shared file); board renders with 0 console errors / 0 exceptions /
0 failed requests. phoenix drift localizes a single-region edit to
migration:sprints (sprint) L58–69 while every other region/file stays clean.
Partial regen (regen --iu=board) preserved the other 3 migration regions. 465 tests.
Bug found + fixed along the way (generator, per "fix Phoenix not output") #
The board shipped a browser-fatal SyntaxError. Root cause was TWO gate gaps:
- Cooked-form blindness — inline
<script>lives insidec.html(…), so the browser sees the TEMPLATE-LITERAL-COOKED text. Source', \'' +(valid escaped quote) collapses to', '' +(two adjacent strings) at render.validateInlineScriptschecked raw source → missed it. Now it cooks escapes + neutralizes${…}first. - Retry-only placement — inline validation ran only inside the fix loop, so a
first-try-clean typecheck skipped it. Now it gates the initial pass too.
Regenerating the board through the fixed gate produced correct
addEventListener+data-*code. Two regression tests added.
Compile Gate — "the assembled system must compile, honestly" (SHIPPED ✅) #
The purist follow-on. Per-IU typecheck during generation has incomplete sibling context, so cross-module / declaration-emit errors slipped through and shipped under a green ✔. Phoenix now treats the build as the most basic eval:
compile-gate.ts: after every IU + shared artifact + scaffold is written,tscthe WHOLE project. While the LLM is available, repair offending generated files (feeding tsc's own errors back) for a few rounds; never touch hand-written scaffold. Folds inline-<script>validation in too. Returns unresolved errors.- Honest reporting: repaired files refresh their manifest hash (drift stays clean) and
drop now-stale exact provenance; unresolved errors become negative knowledge +
diagnostics + a persisted
.phoenix/build-status.json; the trust dashboard showsBuild: compiles | N error(s). No silent ✔ on code that doesn't compile. - Generation rule added: narrow nullables INLINE (TS doesn't carry narrowing through a
stored boolean) — fixed the
sprint.capacityclass at the source.
The gate immediately earned its keep on Trail: it fixed sprint-rollup at the source,
then surfaced a previously-masked real error in the scaffold (db.ts TS4023 from
declaration: true on an app) and refused to auto-edit hand-written scaffold — root-
caused to the architecture target's tsconfig (apps don't emit .d.ts). After the fix:
tsc exits 0, gate reports project compiles, board renders with 0 console errors.
472 tests.
Later increments (not now) #
- Generalize roles beyond migration (schema, routing, OpenAPI) — target declares the layout + merge.
- Inspector renders shared files + region ownership.
output_files→artifacts: Artifact[]on the IU model (role-typed).