S255 Handoff — Platform Generation Quality & Universe Data Lifecycle

Session: 255 | Date: 2026-03-23 | Status: Complete Branch: session-252-256_5 (shared with concurrent sessions)

What Was Done

1. Generation Pipeline — Template Variable Resolution (CRITICAL FIX)

Problem: Every generated file had undefined in its name: models/undefined.model.ts, components/undefined-list/undefined-list.component.ts.

Root Cause: preGenerateTemplateFiles() set entityName and entityNamePlural, but interpolate() read entity, Entity, entities, Entities — completely different variable names. JavaScript .replace() converts undefined to the string "undefined".

Secondary Bug: extractPrimaryEntity("manage players") returned "players" (plural). The pluralizer then produced "playerses".

Fix:

• phase-orchestrator.service.ts: Now populates ALL canonical template variables + added singularize() method
• template-registry.service.ts: interpolate() has fallback chain — if canonical vars are missing, resolves from aliases

Files:

• APIs/backend-ai-api/src/app/workflow/phase-executor/phase-orchestrator.service.ts
• APIs/backend-ai-api/src/app/workflow/templates/template-registry.service.ts

Verified: Test generation produces player.model.ts, player-list.component.ts correctly.

2. Preview Runtime — SDK Stub Contract Fixes

All fixes in libs/libs-structural/platform-preview/src/lib/config/sdk-preview-stubs.ts:

3. Preview Runtime — JIT Compiler Loading

Problem: @angular/compiler is not available error in blob URL preview iframe.

Root Cause: rspack drops import '@angular/compiler' (side-effect-only external). esm.sh may not trigger Angular's publishFacade().

Fix (three layers):

1. Named import: import { VERSION } from '@angular/compiler' (prevents rspack from dropping)
2. Prerequisite script: also imports @angular/platform-browser-dynamic (registers JIT internally)
3. Explicit: if (compiler.publishFacade) compiler.publishFacade(globalThis)

Files:

• libs/libs-structural/platform-preview/src/lib/services/preview-server.service.ts
• libs/libs-structural/platform-preview/src/lib/services/bundler-filesystem.service.ts

4. Universe Deletion Cascade

Problem: Deleting a universe left orphaned data in 6+ collections and git repos.

Fix: Added cascade cleanup to SpacesService.deleteUniverse():

Files:

• APIs/backend-api/src/app/spaces/spaces.service.ts
• APIs/backend-api/src/app/spaces/spaces.module.ts

5. Other Preview Improvements

What Was NOT Done (Future Work)

High Priority

1. Cross-service orphan cleanup for backend-ai-api data

   • Configuration sessions, generated modules, deployment snapshots remain when universe is deleted
   • Recommended: Event-driven cascade (emit UniverseDeleted event from backend-api, backend-ai-api subscribes and cleans its own data)
   • Alternative: Scheduled orphan cleanup job that scans for universeIds that no longer exist

2. Full E2E generation test

   • The Vitto backend (port 3003) was down due to MongoDB timeout to Hetzner (34.56.108.77:27017)
   • Once Hetzner MongoDB is reachable, test full generation → preview flow

3. Preview stub filter implementation

   • setFilter, removeFilter, clearFilters are currently no-ops
   • Filters appear functional in UI but don't actually filter the list
   • Need to implement client-side filtering in the stub's doLoad() function

4. GgsCrudFormShellComponent missing saveError input

   • Shell component has no @Input() saveError — save failures don't display in the shell
   • Either add the input to the stub or update the prompt to have generated templates handle errors outside the shell

Medium Priority

5. Automated prompt-stub audit

   • Currently manual. Should be a script that parses implement.prompt.md for SDK imports/components and verifies each has a matching stub export
   • Could run as a pre-commit hook or CI check

6. SCSS flattener v2

   • Current flattener handles nesting + & only. Variables, mixins, @use are not supported
   • If generated code ever uses these, need dart-sass WASM compiler

Key Architectural Decisions

1. No hard cross-service dependencies: Universe deletion in backend-api does NOT call backend-ai-api. Each backend must be able to operate independently.

2. Stubs mirror real contracts: Preview stubs must exactly match the real useCrudList/useCrudForm/useCrudDetail signatures from libs/core/module-base. Any drift causes runtime errors.

3. Three-layer JIT defense: CDN module loading is unreliable — multiple fallback paths ensure Angular JIT compiler is available regardless of how esm.sh packages modules.

4. Template variable defensive fallbacks: Both the producer (preGenerateTemplateFiles) and consumer (interpolate) now handle missing variables gracefully.

Files Modified in S255

Backend API (APIs/backend-api/)

• src/app/spaces/spaces.service.ts — Universe deletion cascade
• src/app/spaces/spaces.module.ts — Import GitProviderModule, GenerationsModule

Backend AI API (APIs/backend-ai-api/)

• src/app/workflow/phase-executor/phase-orchestrator.service.ts — Template variable resolution + singularize()
• src/app/workflow/templates/template-registry.service.ts — interpolate() fallback chain

Platform Preview (libs/libs-structural/platform-preview/)

• src/lib/config/sdk-preview-stubs.ts — deleteFn, update, query, read, GgsToggle, GgsTable, form validation
• src/lib/services/preview-server.service.ts — JIT compiler loading, modulepreload hints
• src/lib/services/bundler-filesystem.service.ts — Named compiler import, VFS path fixer

Vitto Studio (libs/libs-structural/vitto-studio/)

• src/lib/services/preview.service.ts — API_BASE_URL injection, debounce tuning

MCP Decisions Logged

Conventions Added