S257 Handoff

Documentation for Sessions

S257 Handoff — Platform Generation Pipeline Overhaul

Session: 257 | Date: 2026-03-23 | Status: Complete Branch: session-257-263 (shared with concurrent sessions)

What Was Done

1. Preview SDK Stub Alignment (8 fixes)

Fix	Before	After	File
Filter methods noop	`setFilter: noop`	Real state management + doLoad() + filters in request	sdk-preview-stubs.ts
saveFn argument order	`saveFn(id, data)`	`saveFn(data, id)` matching real SDK	sdk-preview-stubs.ts
UniverseDataCrudService missing	Class not exported	Alias: `BaseCrudApiService as UniverseDataCrudService`	index.ts, sdk-preview-stubs.ts
BaseCrudApiService noop	Returns `of({ items: [] })`	Real native `fetch()` with correct URLs	sdk-preview-stubs.ts
Token replacement scope	Only `@libs-foundational/core-angular`	Also `@libs-core/module-base`	bundler-filesystem.service.ts
saveError missing	No error feedback	`saveError` input + error banner	ggs-crud-form-shell.component.*
formatDate missing on list	Not in useCrudList return	Added formatDate/formatDateTime/formatCurrency	use-crud-list.ts
GgsFilterPanel empty	`<ng-content>` only	Renders text/select/boolean/date controls	sdk-preview-stubs.ts

2. Auto-Correction Strategies

sdk-component-replacement.strategy.ts: <button class="btn"> → <ggs-button>, <span [attr.data-status]> → <ggs-badge>, {{ val | date }} → crud.formatDate(). Auto-adds getStatusVariant() method + SDK component imports.

scss-theme-replacement.strategy.ts: 50+ hex colors → var(--ux-*) with fallback values. Covers status (success/error/warning/info), surface, border, text, and primary colors.

3. Generation Pipeline Optimization

Change	File	Impact
Default outputMode → CODE	module-generation.controller.ts (3 endpoints), studio-vitto-bridge.service.ts	Activates progressive preview, halves EXECUTE LLM calls
Deferred visual → Haiku	execute.phase.ts	Visual metadata generated cheaply in background
Prompt caching	claude.provider.ts, llm.types.ts	cache_control on system prompt, 90% discount on modules 2-5
PARALLEL_MODULE_GEN_BATCH=5	.env.local	Single-batch execution for 5-module platforms
JSON re-prompt on parse failure	execute.phase.ts	Re-prompts with strict JSON when all 3 parsers fail
CONFIRM phase	module-gen-phase.executor.ts, module-generation.service.ts, controller	User gate before expensive EXECUTE phase
Progressive preview	preview.service.ts	Compile per-module, not on every file write

4. Preview Stability

Fix	Root Cause	Resolution	File
Flash/disappear	Blob URL revoked before new one ready	Keep old blob alive until new one is created	preview-server.service.ts
Recompilation cascade	Every VFS file write triggered recompile	Gate recompilation during generation; trigger per-module via filesReadyForReview$	preview.service.ts
Missing route components	LLM generates routes to non-existent components	Auto-generate placeholder components from route lazy imports	bundler-filesystem.service.ts
Missing services	LLM imports services at wrong paths	Auto-generate service stubs extending BaseCrudApiService (real HTTP)	bundler-filesystem.service.ts
CDN timeout black screen	No error handling on prerequisite script	Retry + visible error message	preview-server.service.ts

5. Real CRUD End-to-End

Fix	Root Cause	Impact	File
Schema field.key vs field.name	Validator used `field.key`, schemas store `field.name`	Silent insert rejection (201 but success:false)	entity-schema.service.ts
Auto-fields blocking inserts	id/createdAt/updatedAt marked required but backend-generated	Every insert failed validation	entity-schema.service.ts
Wrong API Explorer URLs	Paths like `/api/animal` instead of `/api/spaces/.../data/animals/insert`	404 on all API Explorer requests	api-explorer.component.ts, crud-generator.service.ts
Missing GET /list endpoint	LLM generates `GET /list`, backend only has `POST /query`	404 on list load	data.controller.ts
List not refreshing	useCrudList only loads data once on init	Stale data after save	sdk-preview-stubs.ts (hashchange listener)
CORS blocking blob:	isLocalhostOrigin didn't match blob: prefix	Preview requests rejected	cors.factory.ts

6. Infrastructure

Fix	Root Cause	Resolution	File
rspack-browser missing	`dist/rspack-browser/` not in build chain	NX `bundle-rspack` target with dependsOn	apps/gograb-space/project.json
R2 storage not wired	R2StorageModule never imported in backend-api	Added import + upload endpoint	app.module.ts, data.controller.ts

Key Architectural Decisions

Service stubs extend real BaseCrudApiService — When the LLM generates code importing a service that doesn't exist, the preview generates a stub that extends UniverseDataCrudService with real HTTP fetch. This means CRUD actually works even with missing generated files.
Three-layer stub generation — fixBrokenLibPaths() → generateMissingRouteComponents() → generateMissingImportStubs(). Each layer catches what the previous missed.
CODE-first, visual deferred — The visual JSON metadata path was removed from the critical path and runs as a background Haiku job. Users see code preview immediately.
Compilation gating during generation — VFS file changes are suppressed during active generation. Preview compiles once per complete module via filesReadyForReview$, not on every file write.
Schema validation supports both field.key and field.name — The generation pipeline creates schemas with name, but the validator read key. Now supports both + skips auto-generated fields.

Files Modified in S257

Backend API (`APIs/backend-api/`)

src/app/data/data.controller.ts — GET /list alias, R2 upload endpoint
src/app/data/entity-schema.service.ts — field.key→field.name fix, skip auto-fields
src/app/app.module.ts — R2StorageModule import
src/app/spaces/spaces.service.ts — (S255 cascade, unchanged this session)
src/app/spaces/spaces.module.ts — (S255 imports, unchanged this session)

Backend Vitto API (`APIs/backend-vitto-api/`)

src/app/module-generation/phases/execute.phase.ts — Deferred visual, JSON re-prompt, prompt caching flag
src/app/module-generation/phases/module-gen-phase.executor.ts — CONFIRM phase gate
src/app/module-generation/module-generation.service.ts — Confirmation promise management
src/app/module-generation/module-generation.controller.ts — CODE defaults, confirm endpoint
src/app/module-generation/module-generation.types.ts — New SSE event types
src/app/module-generation/validation/auto-correction.service.ts — Register 2 new strategies
src/app/module-generation/validation/corrections/strategies/sdk-component-replacement.strategy.ts — NEW
src/app/module-generation/validation/corrections/strategies/scss-theme-replacement.strategy.ts — NEW
src/app/module-generation/validation/corrections/strategies/index.ts — Export new strategies
src/app/llm/providers/claude.provider.ts — cache_control content blocks
src/app/llm/llm.types.ts — cacheSystemPrompt option
src/prompts/module-gen/implement.prompt.md — saveError in golden examples

Backend Core (`libs/libs-api/backend-core/`)

src/lib/config/cors.factory.ts — blob: URL support

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

src/lib/config/sdk-preview-stubs.ts — 8 stub fixes, logging, hashchange listener, service stubs
src/lib/services/preview-server.service.ts — Blob URL lifecycle, CDN retry
src/lib/services/bundler-filesystem.service.ts — Token replacement scope, 3 stub generators

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

src/lib/services/preview.service.ts — Compilation gating, filesReadyForReview$ subscription
src/lib/services/studio-vitto-bridge.service.ts — CODE output mode default
src/lib/components/api-explorer/api-explorer.component.ts — Correct universe data URLs, ID input
src/lib/components/api-explorer/api-explorer.component.html — Updated template
src/lib/services/crud-generator.service.ts — Correct endpoint paths

Core Libraries

libs/core/module-base/src/lib/crud/composables/use-crud-list.ts — formatDate/formatCurrency
libs/core/module-base/src/lib/crud/index.ts — UniverseDataCrudService alias
libs/core/ui-framework/src/lib/components/ggs-crud-form-shell/ — saveError input (.ts/.html/.scss)

Build Config

apps/gograb-space/project.json — bundle-rspack NX target

Env

.env.local — PARALLEL_MODULE_GEN_BATCH=5

What Was NOT Done (Future Work)

High Priority

Frontend CONFIRM phase UI — Backend emits module-gen.confirm-plan SSE event but no frontend dialog consumes it yet. Auto-approves after 5 min.
E2E generation test — Generate a fresh platform and verify full flow.
Edit/Delete verification — Update and delete operations in preview need testing.

Medium Priority

Structured output / tool_use — Use Claude's constrained JSON for code generation.
R2 per-universe media uploads — Upload endpoint exists but not wired into generated platform components.
Preview error overlay — Show errors as dismissible overlay, not replacing the preview.

Low Priority

SCSS variables/mixins — dart-sass WASM for advanced SCSS.
Automated prompt-stub audit — CI check that prompt components match stubs.

Specs & Plans

Spec: docs/superpowers/specs/2026-03-23-generation-pipeline-optimization-design.md
Plan: docs/superpowers/plans/2026-03-23-generation-pipeline-optimization.md
Progress Report: docs/english/sessions/S257/S257-progress-report.md