Loom — Generator Reference

Per-platform reference for every file the generators emit and the features they implement. This document maps each DSL construct to its output across the five backends and six frontends so you can answer questions like:

• "What does aggregate Order produce on .NET?"
• "Where does my derived total: Money = … end up in the React app?"
• "Does the Hono backend support per-DSL find with a where clause?"

For language syntax see language.md; for architecture see technical.md; for CLI / Docker / Playwright workflow see tools.md.

To see one identical domain lowered onto every backend, pick the Storefront trio from the playground dropdown — storefront-system (Hono + React), storefront-dotnet (.NET + embedded SPA), and storefront-elixir (Elixir/Phoenix LiveView). All three share the same aggregate tree (Order → OrderLine + Money), Wallet aggregate, and transactional checkout saga, so diffing their output is the fastest way to read this matrix concretely.

Cross-platform feature matrix

The persistence stack shown per column is the default adapter (Drizzle on node, EF Core on .NET). Persistence is a selectable realization axis — platform: dotnet { persistence: dapper }, platform: node { persistence: mikroorm } — see the "Realization axes" section of platforms.md. The alternates (dapper, mikroorm) share the domain layer below and only swap the repository/schema layer; both are now at full parity with their default (M-T6.9) — see platforms.md → "Realization axes". Schema evolution differs between them. Dapper applies the same versioned MigrationsIR chain as EF Core: Migrations/*.cs, run at boot by DbSchema.EnsureAsync behind public.__loom_migrations, projected onto its jsonb value-object layout. A database provisioned by the old CREATE TABLE IF NOT EXISTS bootstrap is baselined on its first migration-aware boot. See migrations.md → "persistence: dapper". MikroORM still self-provisions with schema.update(), and declared migration steps are refused on it.

Scope note. The construct-by-construct matrix below tracks the three reference platforms (TypeScript/Hono, .NET, React) for readability — it maps each DSL construct to its emitted shape in idiom. The other backends — Python/FastAPI, Java/Spring Boot, and Elixir/Phoenix — and the other frontends — Vue, Svelte, and Angular — consume the same LoomModel / wireShape IR contract and emit the analogous constructs in their own idiom. See platforms.md for the full registered set.

Five-backend feature parity

Which of the five domain-logic backends emits each gated feature vs. fails fast at validate. A cell is ✓ (emitted, build-gate-verified), 🚫 (gated — the validator rejects the combination with the named loom.* diagnostic, a reviewed decision), or ⚠ (partial — see the note). Elixir runs on plain Ecto/Phoenix only (the Ash foundation was removed; foundation: ash is a validation error). This grid is the live view, derived from the validator gate sets in src/ir/validate/checks/ and frozen against drift by test/platform/backend-parity-gates.test.ts (a backend can't be silently ungated-and-unemitting — the F1 class of bug). The dated baseline write-up is audits/backend-feature-parity-2026-06.md; remaining gaps + sequencing are in plans/backend-parity-plan.md.

envelope is a single-row find (M-T6.57, ratified 2026-09-10). find audit(): Order envelope means "read at most one Order": the repository answers Order, the route serialises the bare body, and an empty result set is the not-found rung (404). It carries no distinct wire shape — the { id, ts, body } wrapper was the P3 design and never shipped, because nothing in the IR can source ts. T envelope and T therefore emit identically on every backend, which is what the gate on that row asserts.

Until that landed, the row above carried five ticks on output that did not build: java named Envelope<Order> in the repository port, the Spring Data interface and the impl and declared it nowhere; .NET returned a bare Order from a Task<Envelope<Order>> (CS0029); Elixir Repo.all-ed every row and answered a JSON array against its own single-object OpenAPI. Only node and python were honest. Nothing caught it because no .ddd in the repo instantiated the carrier — every compile gate was blind to it by construction, which is why test/fixtures/corpus/envelope.ddd now exists.

Re-verified 2026-08-23 against src/ir/validate/checks/system-checks.ts: every gate set in this table held all five backends — so the per-backend support sets (EVENT_SOURCING_BACKENDS, SUPPORTED_UNION_BACKENDS, AUDIT_OP_BACKENDS, …) were later deleted outright; (universal) means no per-backend gate exists, and test/platform/backend-parity-gates.test.ts pins the emission per backend. The former open gaps (principal Python filters W1b, per-op/lifecycle audited beyond node/dotnet W3, event-sourced workflow on Elixir W4) are closed. The gaps that remain are language-level rather than per-backend — see audits/language-gaps-2026-08.md.

TypeScript backend (platform: node)

generate ts for legacy single-context sources; generate system for deployables marked platform: node.

File map

For a context with aggregates Order (containing parts) and Product:

<deployable>/
├── package.json                     # deps: hono, @hono/node-server, @hono/zod-openapi, zod, drizzle-orm, pg
├── tsconfig.json
├── index.ts                         # pg Pool → drizzle → createApp(db) → @hono/node-server.serve
├── scheduler.ts                     # timerSource jobs (when the deployable owns any) — see "Timer sources"
├── drizzle.config.ts                # Drizzle Kit config (db:generate, db:push, db:studio)
├── Dockerfile                       # multi-stage node:22-alpine; runtime serves `node out/index.js`
├── .dockerignore
├── certs/.gitkeep                   # proxy-CA escape hatch (drop *.crt files here at build time)
├── domain/
│   ├── ids.ts                       # branded id types: OrderId, OrderLineId, ProductId, …
│   ├── value-objects.ts             # enums + value-object classes with invariant ctors
│   ├── events.ts                    # discriminated event union + dispatcher type + Noop dispatcher
│   ├── errors.ts                    # DomainError, AggregateNotFoundError
│   ├── order.ts                     # Order class + OrderLine part class(es)
│   ├── order.test.ts                # vitest from `test "name" { … }` blocks (when present)
│   └── product.ts
├── db/
│   ├── schema.ts                    # Drizzle pgTable / enum value tuples
│   └── repositories/
│       ├── order-repository.ts      # findById / getById / save / find* / all() / toWire
│       └── product-repository.ts
└── http/
    ├── index.ts                     # Hono app composer: CORS, /health, sub-routers, /openapi.json
    ├── order.routes.ts              # OpenAPIHono router with createRoute() + Zod request/response schemas
    └── product.routes.ts

Timer sources (timerSource)

A system-scope timerSource { for: <Event>, cron: "…" | every: <dur> } (scheduling.md) fires a plain domain event on a wall-clock cadence; workflows react through the existing on/create … by triggers. When a deployable owns a timer (its subdomain is the for-event's migrationsOwner), the Hono backend emits scheduler.ts and wires it at boot. Phase 2 splits the two cadences by where durability matters:

• cron: timers → pg-boss (a Postgres-backed durable job queue). pg-boss owns single-fire across replicas natively (no advisory lock), persists each run, and retries a failed body with backoff (retryLimit: 3, retryBackoff: true). The schedule (boss.schedule) and worker (boss.work) live in the app's own Postgres.
• Missed-window catch-up. pg-boss does not back-fill a cron boundary that elapsed while every replica was down (its shouldSendIt only sends when the last boundary is < 60s old). A self-owned loom_timer_runs watermark (created by the scheduler on boot, like pg-boss creates its own schema — not in the domain MigrationsIR) drives a coalesce-once catch-up: on the first boot it records a baseline without retro-firing (a fresh deploy must not replay history); on a later boot, if the previous boundary is > 60s old and later than the last recorded run, it replays that boundary exactly once (a 20-minute outage over four 5-minute boundaries fires one catch-up, not four).
• every: (sub-minute) timers → in-process setInterval + a transaction-scoped pg_try_advisory_xact_lock (single-fire) with a running no-overlap guard. Durability is meaningless for a high-frequency poll (resume-at-next-tick is correct) and pg-boss cron is minute-granularity.
• Dispatch. The tick event is constructed (id fields minted, at stamped) and dispatched through the same in-process dispatcher the sagas use, so an on/create reactor fires with no new machinery.
• Observability. timer_fired / timer_skipped_overlap / timer_lock_contended / timer_emit_failed / timer_catchup on the catalog.

Delivery semantics (multi-pod). Still at-least-once: pg-boss gives single-fire per boundary and durable retry, but a clock-skewed peer or a catch-up replay can re-deliver, so tick reactors must be idempotent (the same contract event reactors already carry). Exactly-once-per-instant is not a goal — at-least-once + idempotent reactors is the contract.

A deployable owning no timer emits no scheduler.ts, no pg-boss dep, and no boot wiring — byte-identical to before.

Phase-2 durable drivers (M-T4.1). The advisory-lock path above is the in-process tier — correct for every: (sub-minute) cadences but at-least-once. cron: timers additionally get a durable, store-coordinated driver per backend, so a boundary missed while every replica was down is replayed once on recovery (missed-run catch-up) and fires exactly once across replicas (single-fire), with retries. Each backend uses its ecosystem's Postgres-native job store: node → pg-boss, .NET → Hangfire, Java → JobRunr, Python → procrastinate, Elixir → Oban. The every: tier stays the in-process interval loop + pg_try_advisory_xact_lock on every backend.

Per-aggregate detail

domain/<aggregate>.ts — class with:

• Private state fields, private constructor for rehydration
• static <Agg>.create(input) factory: allocates a fresh id, calls the constructor, runs invariants
• static <Agg>._create(state) for the repo to rehydrate from rows
• Public method per public operation; private method per private op
• Private method per function
• Getter per derived
• private _assertInvariants() invoked from every mutator
• _events: DomainEvent[] + pullEvents() drained by the repo

Entity parts are sibling classes in the same file with _parentId set on construction; mutations on parts go through their parent's operations.

http/<aggregate>.routes.ts — built by routes-builder.ts:

• Zod schemas for every value object, enum, and per-route DTO; named via .openapi("Foo") so they appear in /openapi.json's components.schemas
• One route per shape:
  • POST / → create (body = Create<Agg>Request, returns {id})
  • GET / → all (auto findAll; returns <Agg>ListResponse)
  • GET /{id} → findById (returns <Agg>Response)
  • POST /{id}/<snake_op> → operation (body = <Op>Request, returns 204)
  • GET /<snake_find> → user-declared find (query params = <Find>Query)
• Domain-error handler maps DomainError → 422 (RS-15), AggregateNotFoundError → 404

Response schemas carry the full wire shape: every field, every contained part nested, every derived value (except the reserved inspect derived, which stays host-language-only — see below), value objects as nested objects. Decimals are JSON numbers; datetimes are ISO strings.

Aggregate stringification hooks: when an aggregate declares derived inspect: string = ... (auto-injected when omitted), each backend emits a host-language debug-string hook that delegates to the inspect value — public override string ToString() (.NET, auto-invoked by $"{x}" / Console.WriteLine), toString() + [Symbol.for("nodejs.util.inspect.custom")] (TS, auto-invoked by String(x) / ${x} / console.log), a public def inspect(record) module function (Phoenix, invoked explicitly as MyApp.Catalog.Customer.inspect(record) — the loom-emitted form lives at the module-function level to avoid an Inspect-protocol collision under mix compile --warnings-as-errors), a __repr__ (Python, auto-invoked by repr(x) / f-strings), and a toString() override (Java). Honours sensitive(...) field tags by substituting <redacted> for the value while keeping the field name in the structural output. VO-typed fields are inlined structurally one level deep — price: Money shows as price: Money(amount: 99, currency: 'USD') rather than the opaque price: [Money] placeholder; further nesting (VO inside VO, arrays, optionals) falls back to the placeholder so the expression stays bounded and self-recursive VO shapes can't cycle. A sensitive(...) tag on the parent's VO-typed field redacts the whole VO; per-field sensitive(...) inside the VO redacts only that slot. Never reached by string(aggregate) or implicit "x " + aggregate — the user-facing form is derived display: string = ... (opt-in), routed through the Loom expression layer and the React Select picker.

db/repositories/<aggregate>-repository.ts — built by repository-builder.ts:

• findById(id) — load root + every part collection in one transaction, hydrate aggregate
• getById(id) — same but throws AggregateNotFoundError on missing
• save(aggregate) — upsert root, diff-sync each contained collection (insert new + update existing + delete removed) and each reference-collection join table (delete removed pairs; upsert current pairs carrying their ordinal position so reorders persist) in a transaction, drain events via dispatcher.dispatch
• all() — auto-included; loads all rows and hydrates with parts
• <find>(...) — one method per user-declared find; a where clause lowers to a Drizzle predicate (lowerToDrizzle in repository-find-predicate.ts) over the queryable subset (comparisons, &&/||, !, bare-boolean columns, value-object sub-columns, currentUser.<field>, enum values, and <refColl>.contains(x) join-table subqueries); a paramless find falls back to convention-matching its params to columns. The IR validator (firstNonQueryableNode) gates where clauses to exactly this subset, so lowering never silently drops a predicate.
• toWire(root) — domain → wire DTO projection used by route handlers

db/schema.ts — Drizzle pgTable per aggregate root and per contained part (parts get a parent_id FK), a value tuple per enum (the column is TEXT, matching the emitted migration), value-object fields flattened into prefix-named columns (price_amount, price_currency).

Every X id[] reference-collection field on an aggregate also gets its own join table, snake(owner)_snake(field) (e.g. trainer_party, trainer_caught) — two FK columns (<owner>_id text not null, <target>_id text not null), an ordinal integer not null carrying the collection's position, a composite primary key (owner_fk, target_fk), and an index on the target FK so the reverse membership subquery (this.party.contains(pokemon)) stays index-backed. The field is not persisted as a column on the owner table.

http/index.ts — composer:

• app.use("*", cors()) (permissive; pin in .loomignore for prod)
• app.get("/health", ...)
• app.route("/<plural>", <agg>Routes(new <Agg>Repository(db, events)))
• app.doc("/openapi.json", { openapi: "3.1.0", … })

.NET backend (platform: dotnet)

generate dotnet for legacy single-context sources; generate system for deployables marked platform: dotnet.

File map

<deployable>/
├── <Namespace>.csproj               # net10.0, EF Core 10, Mediator source-gen, Swashbuckle, EF Tools
├── Program.cs                       # AddDbContext, AddMediator, AddCors, AddSwaggerGen, MapControllers,
│                                    # camelCase JSON, EnsureCreated, /health
├── Dockerfile                       # multi-stage dotnet/sdk → dotnet/aspnet
├── .dockerignore
├── certs/.gitkeep                   # proxy-CA escape hatch
├── Domain/
│   ├── Common/DomainException.cs
│   ├── Ids/                         # OrderId.cs, OrderLineId.cs, ProductId.cs, …
│   ├── Enums/                       # one .cs per enum + a _namespace.cs marker so empty namespaces compile
│   ├── ValueObjects/                # one .cs per value object + _namespace.cs marker
│   ├── Events/
│   │   ├── IDomainEvent.cs
│   │   └── OrderConfirmed.cs        # one .cs per event
│   └── Orders/                      # one folder per aggregate (plural)
│       ├── Order.cs                 # aggregate root class
│       ├── OrderLine.cs             # entity-part classes
│       └── IOrderRepository.cs      # interface
├── Application/
│   └── Orders/
│       ├── Requests/OrderRequests.cs    # CreateOrderRequest, AddLineRequest, …
│       ├── Responses/OrderResponses.cs  # OrderResponse, OrderLineResponse, MoneyResponse, CreateOrderResponse
│       ├── Commands/                    # one Command + Handler per public operation + Create<Agg>
│       │   ├── CreateOrderCommand.cs
│       │   ├── CreateOrderHandler.cs
│       │   ├── ConfirmCommand.cs
│       │   ├── ConfirmHandler.cs
│       │   ├── AddLineCommand.cs
│       │   └── AddLineHandler.cs
│       └── Queries/                     # one Query + Handler per find (incl. auto findById / all)
│           ├── GetOrderByIdQuery.cs
│           ├── GetOrderByIdHandler.cs
│           ├── AllQuery.cs
│           ├── AllHandler.cs
│           ├── ByCustomerQuery.cs
│           └── ByCustomerHandler.cs
├── Infrastructure/
│   ├── Persistence/
│   │   ├── AppDbContext.cs              # DbSet<Order>, DbSet<Product>, …
│   │   └── Configurations/
│   │       ├── OrderConfiguration.cs    # IEntityTypeConfiguration: OwnsMany lines, OwnsOne for VOs, HasConversion for ids/enums
│   │       └── ProductConfiguration.cs
│   ├── Repositories/
│   │   ├── OrderRepository.cs           # implements IOrderRepository: GetByIdAsync, SaveAsync, All, …
│   │   └── ProductRepository.cs
│   └── Events/NoopDomainEventDispatcher.cs
├── Api/
│   ├── DomainExceptionFilter.cs         # DomainException → 422, AggregateNotFoundException → 404
│   ├── ValidationProblem.cs             # model-binding/DataAnnotations failures → the same 422 + errors[]
│   ├── OrdersController.cs              # [HttpPost], [HttpGet], [HttpPost("{id}/<op>")], [HttpGet("<find>")]
│   └── ProductsController.cs
└── Tests/<Namespace>.Tests/             # xUnit project — emitted only when `test` blocks exist
    ├── <Namespace>.Tests.csproj
    └── Orders/OrderTests.cs

Per-aggregate detail

Domain/<Plural>/<Aggregate>.cs — sealed class with:

• public <Agg>Id Id { get; private set; }
• Private setter on every property; parameterless ctor for EF
• public static <Agg> Create(...) factory
• Public method per public op; private method per private op
• Private expression-bodied member per function
• Computed property per derived
• private void AssertInvariants() invoked from every mutator
• private readonly List<IDomainEvent> _events + PullEvents()

Infrastructure/Persistence/Configurations/<Aggregate>Configuration.cs — IEntityTypeConfiguration<<Aggregate>>:

• OwnsMany per contained collection (parts as owned entities)
• OwnsOne per value-object property
• HasConversion for ids and enums

Application/<Plural>/Commands/... — for every public DSL operation: a record Command implementing ICommand<TResponse> plus a Handler that loads the aggregate, invokes the method, saves. Preconditions are checked inside the aggregate, never duplicated in the handler.

Application/<Plural>/Queries/... — for every find (including auto findById and all): a record Query + a Handler that calls the repository and projects through <Agg>Mapper.ToDto(...) (lives in the Responses module via dto-mapping.ts).

Application/<Plural>/Requests/<Aggregate>Requests.cs — wire-shape records: Create<Agg>Request, <Op>Request per public op, <Vo>Request per used value object. Datetimes are string on the wire (Hono parity); the controllers parse with DateTimeStyles.AssumeUniversal | AdjustToUniversal → UTC.

Application/<Plural>/Responses/<Aggregate>Responses.cs — wire- shape records (<Agg>Response, <Part>Response, <Vo>Response, Create<Agg>Response). Datetimes round-trip via ToUniversalTime().ToString("o") so .NET's spec matches Hono's.

Api/<Plural>Controller.cs — [ApiController] with one route per shape; converts wire-DTOs to commands, dispatches via IMediator, returns DTOs. DomainExceptionFilter turns precondition failures into HTTP 422 (RS-15) and missing-aggregate into 404.

Api/ValidationProblem.cs — the faults that never reach a controller. Model binding and DataAnnotations run before the action, so DomainExceptionFilter never sees them and MVC answered with its own ValidationProblemDetails (rfc9110 type, errors as an object-of-arrays, traceId inline, status 400 where the other backends send 422). Wired as ApiBehaviorOptions.InvalidModelStateResponseFactory, this replaces it with the emitted envelope — 422 + errors[] for an invalid body, 400 for an unreadable one (RS-9's split). Program.cs pairs it with UseStatusCodePages (404/405, which routing refuses with no body at all) and a CustomizeProblemDetails hook that normalises the ProblemDetails the framework builds itself (415).

Middleware/EmptyJsonBodyMiddleware.cs — an empty request body reads as {} (RS-39), so a parameterless operation answers a body-less POST. It swaps the body, its framing headers and IHttpRequestBodyDetectionFeature — MVC's body binder reads the feature, not the stream. The other backends' twins: hono emptyBodyAsEmptyObject, python JsonBodyMiddleware, java EmptyJsonBodyFilter, the Phoenix BodyParser.

Program.cs — hosting entry:

• AddDbContext<AppDbContext> over ConnectionStrings:Default
• AddMediator (source-gen)
• AddSingleton<IDomainEventDispatcher, NoopDomainEventDispatcher>
• AddScoped<I<Agg>Repository, <Agg>Repository> per aggregate
• AddControllers().AddJsonOptions(...) — camelCase property naming
• AddCors (permissive default; pin to tighten in prod)
• AddSwaggerGen — spec at /openapi.json (aligned across backends)
• app.MapGet("/health", ...) + UseCors() / UseSwagger() / MapControllers()
• db.Database.EnsureCreated() on first scope (per-deployable DB, no race — see tools.md)

React frontend (platform: react)

generate system for deployables marked platform: react. No single-deployable CLI entry — react frontends only make sense in system mode where they can resolve a targets: peer.

File map

For a frontend webApp targeting api (which hosts Order + Product):

web_app/
├── package.json                     # deps: react, react-router, @tanstack/react-query, zod,
│                                    # @mantine/* (core, hooks, form, notifications, dates, modals),
│                                    # mantine-form-zod-resolver
├── tsconfig.json + tsconfig.node.json
├── vite.config.ts                   # @vitejs/plugin-react, dev/preview bind 0.0.0.0:<port:> (PORT overrides; the image passes --port 3000)
├── index.html
├── Dockerfile                       # multi-stage node:22-alpine; runtime: vite preview
├── .dockerignore                    # excludes e2e/, dist/, playwright-report/, test-results/
├── certs/.gitkeep
├── src/
│   ├── main.tsx                     # MantineProvider + QueryClientProvider + Router + Notifications + ModalsProvider
│   ├── App.tsx                      # AppShell + <Routes>: home, /<plural>, /<plural>/new, /<plural>/:id — each page a React.lazy chunk behind a Suspense (pack loader fallback)
│   ├── api/
│   │   ├── client.ts                # fetch wrapper, ApiError
│   │   ├── config.ts                # API_BASE_URL = /api (relative, same-origin); window.__LOOM_API_BASE__ or VITE_API_BASE_URL override
│   │   ├── order.ts                 # Zod schemas + RQ hooks
│   │   └── product.ts
│   └── pages/
│       ├── home.tsx                 # link cards per aggregate
│       ├── orders/
│       │   ├── list.tsx             # /orders — Mantine <Table> from useAllOrders
│       │   ├── new.tsx              # /orders/new — Mantine form on Create<Agg>Request
│       │   └── detail.tsx           # /orders/:id — fields + parts + operation buttons (modal-form per op)
│       └── products/
│           ├── list.tsx
│           ├── new.tsx
│           └── detail.tsx
└── e2e/                             # standalone Playwright suite (separate package.json so the
    │                                # runtime image stays slim — @playwright/test isn't pulled into prod)
    ├── package.json                 # @playwright/test, @types/node
    ├── tsconfig.json                # includes ../src/api/**/*.ts so page objects can use response types
    ├── playwright.config.ts         # baseURL = http://localhost:3001 (override via E2E_BASE_URL)
    ├── smoke.spec.ts                # auto-generated: every aggregate's list page loads
    └── pages/                       # auto-generated page-object classes
        ├── order.ts                 # OrderListPage / OrderNewPage / OrderDetailPage
        └── product.ts

Stores (store Cart { state … action … })

A top-level ui member store Cart { state { … } action … } (a shared client-side container, sibling to page/component — named-actions-and-stores.md §3) emits one Zustand module per store at src/stores/<snake>.ts: export const useCart = create<CartState>((set) => ({ …fields, …actions })). The action bodies reuse the same :=/+= statement lowering a page action does, targeting Zustand's set((s) => ({ … })) instead of a useState setter (zustand is added to the generated package.json). At a use site a page/component references the store by dotted name — Cart.lines (a store-field read) and Cart.clear() (a store-action call). Each consuming shell derives its store dependency from those resolved refs (derive-don't- stamp), imports useCart, and hoists one selector binding per used member (const lines = useCart((s) => s.lines)); the body / action handlers reference the bare local. The persist: lifetime ladder ships on the SPA frontends — store <Name> persist: memory|local|session|url { … } is real grammar, and React / Vue / Svelte / Angular honour it, so the blanket loom.store-lifetime-unsupported is retired (a bad value is rejected earlier as loom.store-lifetime-invalid). Feliz honours it too, differently: a Feliz store has no module of its own — it folds into the single Elmish Model, so the ladder rides that fold (generator/feliz/store-persist.ts). init seeds each persisted field through a StorePersist.load<Store><Field> () loader, an updateWithPersist wrapper mirrors the Model back after every message, and the url tier adds a popstate Elmish subscription so back/forward moves the state. Keys and shapes match the JS builders byte-for-byte (loom.store.<Name> + a JSON object keyed by the bare field name; one query param per field, empties dropped), so the same blob and the same URL round-trip across frontends. Every frontend now implements the ladder; the one target that does not is Phoenix LiveView, which refuses a non-memory lifetime rather than degrading silently (loom.store-lifetime-liveview-invalid — a server-side per-process struct has no browser storage, and URL state belongs to the page's handle_params). What survives of loom.store-lifetime-target-unsupported is FIELD-scoped, on the two frontends whose persistence crosses an untyped boundary per field: on Feliz a type with no total F# conversion (datetime / duration / guid / enum / entity / value object, and arrays of them), and on Flutter one with no total Dart conversion (json / File / entity / value object / optional). Both are tracked as one gap row in src/diagnostics/unsupported-register.ts. A persist: url store reflects its fields into query params, which carry only scalars, so an array / entity / value-object field there is rejected (loom.store-url-field-invalid). sync: remains reserved. Validator gates: a store action can't call a view-scoped effect (navigate/toast — loom.store-action-view-effect), a page can't write store state inline (loom.store-state-inline-write), and a store→store call cycle is rejected (loom.store-action-cycle).

Phoenix LiveView also ships stores (the loom.store-on-liveview-unsupported gate was lifted): a store Cart { … } emits a dedicated lib/<app>_web/stores/cart.ex module — a defstruct carrying the state fields (with their defaults) plus one public pure function per action (def clear(%__MODULE__{} = state), do: %{state | …}). Each LiveView page that touches the store seeds one per-process assign in mount/3 (|> assign(:cart, %Cart{}) + an alias <App>Web.Stores.Cart); a Cart.count read renders @cart.count (template) / socket.assigns.cart.count (handler), and a Cart.clear() call renders |> update(:cart, &Cart.clear/1) (0 args) or |> update(:cart, fn c -> Cart.add(c, sku) end) (with args). Because each store is its own per-page assign, a store action calling a different store's action is gated (loom.store-cross-store-on-liveview-invalid) — same-store action→action composition is fine (a pure in-module call).

Vue/Svelte/Angular store-module emit is a fan-out follow-up and throws loudly until ported.

Per-aggregate detail

src/api/<aggregate>.ts — built by api-builder.ts:

• Zod schemas for every value object, enum, and per-route DTO:
  • <Vo>Schema, <Enum>Schema
  • Create<Agg>Request, per-op <Op>Request, per-find <Find>Query
  • <Part>Response, <Agg>Response, <Agg>ListResponse
• React Query hooks:
  • useAll<Agg>() → useQuery(["<plural>"], …), parses with <Agg>ListResponse
  • use<Agg>ById(id) → useQuery(["<plural>", id], …), enabled: !!id
  • useCreate<Agg>() → useMutation, invalidates ["<plural>"] on success
  • use<Op><Agg>(id) → useMutation, invalidates ["<plural>", id] and ["<plural>"] on success
  • use<FindName><Agg>(query) → useQuery per user-declared find (the auto all find is the dedicated useAll<Agg> hook above)

All hooks parse the response with the matching Zod schema before returning, so callers get type-checked, validated data.

src/pages/<plural>/list.tsx — built by body-walker.ts + pages-emitter.ts (the legacy pages-builder.ts archetype renderer has been removed; bodies — scaffolded or hand-written — all route through the walker now):

• Mantine <Table> with one column per primitive / enum field
• Each row links to /<plural>/<id>
• "Create" button routes to /<plural>/new
• data-testid on every interactive element (see table below)

src/pages/<plural>/new.tsx:

• Mantine <form> over the Create<Agg>Request schema
• One Mantine input per required aggregate field — see Mantine input mapping below
• useForm + zodResolver(Create<Agg>Request) for validation
• Submit calls useCreate<Agg>(); success navigates to detail; error surfaces via @mantine/notifications

src/pages/<plural>/detail.tsx:

• Loads via use<Agg>ById(id)
• Mantine <Card> with field display (one per primitive / enum / VO field)
• Sub-<Table> per contains collection (master-detail)
• One Mantine <Button> per public operation; click opens a Mantine modal whose form binds to the matching <Op>Request schema
• Submit calls the matching mutation hook; success closes the modal and shows a notification; error surfaces via notification
• React Query invalidation runs on success so the page reflects the new state automatically

Mantine input mapping

Form-input emission walks the field type:

data-testid map

The body-walker sprinkles a stable data-testid on every interactive element so the page-objects-builder can write selector-free test code. Walker-stdlib primitives accept an explicit testid: named arg; the walker threads it through the rendered component.

Route-level code splitting

Every routed page is its own chunk; only the shell (layouts, sidebar, NotFound, error boundary) is in the entry bundle. App.tsx binds each page as const OrderList = React.lazy(() => import("./pages/orders/list")) and wraps each layout's <Outlet /> — plus the whole <Routes>, for layout: none pages — in <React.Suspense fallback={<RouteLoading />}>, where RouteLoading renders the pack's own loader (Loader / CircularProgress / Spinner / Loader2) with data-testid="route-loading". The generated smoke spec waits for that fallback to clear before asserting the page did not crash; the page objects already wait on each page's root testid. Vue (component: () => import(…)) and Angular (loadComponent) split the same way — on vuetify each .vue file also imports the components its template renders (import { VBtn, VCard } from "vuetify/components", derived from the emitted markup) rather than createVuetify registering the whole library, so those components ride the page's chunk; SvelteKit splits per +page.svelte on its own. Pinned by test/generator/_frontend/lazy-route-pages.test.ts.

Page-object classes

page-objects-builder.ts emits one TS module per aggregate at <deployable>/e2e/pages/<aggregate>.ts. Each module exports three classes that mirror the page set:

export class <Agg>ListPage {
  static readonly url = "/<plural>";
  constructor(public readonly page: Page);
  goto(): Promise<this>;
  create(): Promise<<Agg>NewPage>;
  row(id: string): Locator;
  open(id: string): Promise<<Agg>DetailPage>;
  expectRow(id: string): Promise<void>;
}

export class <Agg>NewPage {
  static readonly url = "/<plural>/new";
  constructor(public readonly page: Page);
  goto(): Promise<this>;
  fill(input: Partial<Create<Agg>Request>): Promise<this>;
  submit(): Promise<<Agg>DetailPage>;
}

export class <Agg>DetailPage {
  constructor(public readonly page: Page, public readonly id: string);
  goto(): Promise<this>;
  field<K extends keyof <Agg>Response>(name: K): Promise<string>;
  // For each `contains <name>: Part[]`:
  <name>Row(id: string): Locator;
  <name>Count(): Promise<number>;
  // For each public operation `op(p1: T1, …)`:
  op(input: <Op>Request): Promise<this>;
}

The fill() body branches per type — selectOption for enums (via the dropdown), .fill() for text inputs, .click() toggles for bools, slice-to-YYYY-MM-DDTHH:mm for datetime — and walks nested VO fields.

Design pack selection

The file map above is for the default design: "mantine". Picking a different pack swaps the rendered component library, the package.json dep set, and the theme bootstrapping — the rest of the project (routing, RQ hooks, page objects, smoke tests) is identical.

Pack selection per platform when design: is omitted:

Picking a pack also locks in a stack (a coherent React + router + Zod + Vite + TypeScript dep bundle). Each pack version declares its stack in its pack.json; the bundler reads that declaration and emits the matching package.json. See design-packs.md for the full pack authoring surface, including the stack catalogue and the recipe for adding a new pack version.

A bareword design: "mantine" resolves to the family's current default version; pinning is via family@version (e.g. design: "mui@v7"). The per-version folder under designs/<family>/<vN>/ is what the bundler actually loads.

Svelte frontend (platform: svelte)

The second frontend generator (src/generator/svelte/). Emits a Svelte 5 / SvelteKit static SPA per svelte deployable — @sveltejs/adapter-static with ssr = false and an index.html fallback, served by vite preview in docker exactly like the React SPA. Pages flow through the same shared markup walker the React generator uses (src/generator/_walker/walker-core.ts) with svelteTarget + a svelte-format design pack (shadcnSvelte default, flowbite); see D-SVELTE-FRONTEND in decisions.md.

Vue frontend (platform: vue)

The structural mirror of the React frontend, driven by the SAME shared markup walker (src/generator/_walker/) through vueTarget and the SAME _frontend/ api/workflows module builders (only the TanStack Query import specifier differs). Design packs: vuetify (default) and shadcnVue (reka-ui + Tailwind 4, source-copy). See D-VUE-FRONTEND and [docs/old/plans/vue-frontend-plan.md](https://github.com/Loom-Harness/Loc/blob/cadbe3ba12fb833565704cb9d628c8f41b2090a8/docs/old/plans/vue-frontend-plan.md).

File map (deltas vs the React project)

web_app/
├── package.json            # vue, vue-router, @tanstack/vue-query, zod (+ vuetify/@mdi or
│                           # reka-ui/tailwindcss/cva/clsx/tailwind-merge/lucide-vue-next)
├── vite.config.ts          # @vitejs/plugin-vue (+ @tailwindcss/vite and the @ alias on shadcnVue)
├── src/
│   ├── main.ts             # createApp + router + VueQueryPlugin (+ vuetify instance / globals.css)
│   ├── App.vue             # app chrome + <router-view/> + onErrorCaptured boundary
│   ├── router.ts           # createRouter(createWebHistory) route table (each page `component: () => import(…)`, its own chunk) + NotFound catch-all
│   ├── theme.ts            # createVuetify tokens, no global component registration (vuetify) / `export {}` stub (shadcnVue — CSS vars)
│   ├── lib/form.ts         # useLoomForm — vee-validate useForm over the shared zod schema (local toTypedSchema) + per-field error map
│   ├── lib/format.ts       # formatting FUNCTIONS (the React packs' format components, fn-style)
│   ├── lib/toast.ts        # channels only: reactive pushToast() queue the app-shell host renders
│   ├── api/realtime.ts     # channels only: EventSource client (broadcast wire → subscribeRealtime)
│   ├── components/RealtimeHandlers.vue  # channels only: renderless on-mount switch → pushToast
│   ├── components/<Name>.vue # user components — typed defineProps SFC, walked <template>
│   ├── lib/<extern>.ts + lib/extern/<extern>.signature.ts  # extern frontend fns (shim + signature)
│   ├── components/ui/      # shadcnVue only: source-copied SFCs + index.ts barrel
│   ├── layouts/<Name>.vue + layouts/DefaultLayout.vue  # named layouts only: chrome moves out of App.vue, router nests
│   └── pages/**/*.vue      # SFC pages — <script setup lang="ts"> + walked <template>
└── e2e/                    # identical harness/page objects to React (testid/DOM only)

Key behaviours

• vue-query handles hoist as reactive(useX(...)) so nested refs (.data, .isPending) read uniformly in template + script.
• Forms: useLoomForm(schema, drafts) — vee-validate's useForm over the shared zod schema (adapted by a locally-emitted toTypedSchema, since @vee-validate/zod's peer pins zod 3 while the stack is zod 4); create forms, operation v-dialogs (the pack-owned op-dialog template), and workflow run-forms are wired.
• Operation/find hook args, navigate, match-in-child-position, and state reads/writes all flow through the WalkerTarget seams — zero forked walker code.
• Backend hosts (dotnet / java / phoenix) embed a framework: vue ui exactly like a React one (vue ∈ STATIC_BUNDLE_FRAMEWORKS).
• User components (component <Name>(p: T)) emit src/components/<Name>.vue (typed defineProps, walked body); an extern component emits a typed <Name>.props.ts + a <Name>.ts re-export shim (call sites import components/<Name> without the .vue). Extern frontend functions emit the shared signature + conformance shim (tsc is the fail-fast).
• Channels (on <channel>.<Event>) emit the SSE client, a renderless RealtimeHandlers.vue, and a pushToast() queue the app-shell renders (a <v-alert> stack on vuetify, an Alert stack on shadcnVue).
• Find-filter live-refetch: a parameterised find hook takes a MaybeRefOrGetter<Query> (queryKey tracks computed(toValue(query))) and the list page passes () => ({ … }), so a bound filter input re-fetches (React re-renders, so its hook stays a plain object param).
• A component body can host a CreateForm/WorkflowForm (the useLoomForm + mutation wiring transplants from the page shell); operation forms (Action dialogs) inside a component also work — the op-dialog host + per-op LoomForm transplant from the page shell, with the instance idExpr read off the aggregate-typed prop (order.id → props.order.id).
• Named layouts (layout <Name> { header / main / footer }) restructure into nested vue-router routes: the layout SFC's inner <router-view /> is the main outlet, layout: none mounts top-level, and the default chrome moves to src/layouts/DefaultLayout.vue with App.vue a thin host. Default-only uis keep the flat chrome-in-App.vue shape.
• A slot param on an extern component maps to a typed <Name>Slots contract (for defineSlots), kept out of <Name>Props (Vue slots are <slot> template content, not props).
• No known gaps — full parity with the React page DSL, with compile-time (LOOM_VUE_BUILD) and runtime (LOOM_VUE_E2E) CI coverage.

Angular frontend (platform: angular)

The fourth frontend generator (src/generator/angular/). Emits a standalone Angular 22 SPA per angular deployable — bootstrapApplication + appConfig (no NgModules), built with the @angular/build:application builder and served the same vite preview-style way as the other SPAs in docker. Pages flow through the same shared markup walker the React / Vue / Svelte generators use (src/generator/_walker/walker-core.ts) with angularTarget + the angularMaterial design pack. See docs/old/plans/angular-frontend-plan.md.

Angular renders idiomatic Angular, not a transliterated React app: standalone @Components, signals/computed for view state, typed Reactive Forms, and — for server state — TanStack Angular Query (injectQuery / injectMutation), the senior-Angular-idiomatic caching layer, so reads share a query cache (dedup + caching) and mutations invalidate exactly the keys the generator knows they touch. Several walker seams fork the shared (React-shaped) emission rather than reuse it — each is opt-in (only angularTarget implements it), so the other JSX/markup frontends (React/Vue/Svelte) stay byte-identical (pipeline-layering + the full suite gate this).

Feliz frontend (platform: feliz)

The fifth frontend generator (src/generator/feliz/). Emits a Feliz (F#/Fable/Elmish) SPA per feliz deployable, built with dotnet fable + vite (not the vite-only static pipeline of the JS frontends). Pages flow through the same shared markup walker the other frontends use (src/generator/_walker/walker-core.ts) via feliz-target.ts — but Feliz is the one frontend whose embedded language is F#, not JS, so instead of consuming the wire shape only, it supplies its own F# expression leaves (src/generator/feliz/fs-expr.ts, the FS_LEAVES table) through the shared emitExpr dispatcher. See docs/old/plans/feliz-frontend-build.md.

Known frontier (M-T1.16): modal open-state, typed in-flight form state, enum DU wire decoder, per-page sub-models, multi-param routes; and the interactive-Table sort/pagination/filter seams degrade (Elmish needs Set-Msg/update plumbing) rather than emit.

Flutter mobile (platform: flutter, framework: flutter)

The mobile axis — a new development branch outside the web-target matrix, not a sixth web SPA. src/generator/flutter/ emits a Dart/Flutter (Material 3) app on Riverpod per flutter deployable. Like Feliz it is self-hosting (own SDK build, not the vite static pipeline) so it hosts only its own framework: flutter UI.

One Dart source, three build surfaces. The emitted project's Makefile builds web (make web → flutter build web, the surface compose serves via the emitted nginx Dockerfile), Android (make apk), and iOS (make ipa) from the same UI — "web-vs-native is a build target, not a modelling mode." The native android//ios/ folders are SDK-owned boilerplate and are not vendored; make prepare (flutter create --platforms=…) materialises them on demand. Compose serves only the web surface (mobile artifacts aren't a compose concern), and CI gates only the web build — see the CI row. Structurally Flutter is a Feliz clone: a non-JSX, function-call-tree target (Column(children: [ … ])) that rides the same shared markup walker (walker-core.ts) through flutter-target.ts + a Dart expression-leaf table, and — like Feliz — supplies its own interChildSeparator seam because Dart list literals are comma-separated.

Modal { trigger: Button(…), OperationForm(of:, op:) } renders as a trigger ElevatedButton whose onPressed opens an AlertDialog wrapping the op-form widget (showDialog); the op-form pops its own route on success, dismissing the dialog. WorkflowForm(runs: <wf>) renders as a StatefulWidget (like CreateForm) that POSTs the workflow params to the command route /workflows/<wf>.

match await <api>.<Agg>.<op>() (async effect) projects an async Riverpod Notifier method (Future<void> <action>(String id) async): it POSTs the instance op to /<coll>/$id/<op>, reifies a non-2xx ProblemDetails back into the error variant (clobbering the wire type tag), then a Dart-3 switch over result['type'] reifies each arm via fromJson and runs the arm body as a state.copyWith write. The page-shell binds the action as an id-capturing closure (final <a> = () => notifier.<a>(id);) so the button's bare <a>() call is unchanged (riverpod-emit.ts).

View effects from an action body (navigate(<Page>), toast(<expr>)) ship through two generated OUT-OF-TREE bridges, because a ui action projects to a Riverpod Notifier method and a Notifier holds no BuildContext: lib/nav.dart installs a GlobalKey<NavigatorState> on MaterialApp and the statement renders navigateTo('/route'), and lib/toast.dart installs a GlobalKey<ScaffoldMessengerState> and the statement renders showToast(<expr>) (Object?, so a non-string argument coerces). Both files and both MaterialApp arguments are emitted only when some emitted Dart actually calls into them, so an app that uses neither is byte-identical to one built before the bridges existed. A REALTIME handler's toast is in the widget tree (LoomRealtime on MaterialApp.builder) and keeps ScaffoldMessenger.maybeOf(context) instead.

A scalar array form field (tags: string[] / scores: int[]) renders as a repeatable add/remove row list (one TextEditingController per row, managed in state; numeric arrays parse each row on submit).

Stores (store X { … }) project onto the same Riverpod triad a stateful page does (store-builder.ts), and the persist: local|session|url lifetime ladder ships (store-persist.ts): build() seeds each cell from its backing store, a ref.listenSelf mirror writes the whole state back after every transition, local/session ride shared_preferences with setPrefix('') (so the web key is the bare loom.store.<Name> the JS builders write) and url rides Uri.base.queryParameters + SystemNavigator.routeInformationUpdated with a LoomUrlStoreSync back/forward observer. session is the same backing CLEARED at boot — Dart has no per-tab store on every surface. A field type with no total Dart codec (json / File / entity / value-object / optional) is refused rather than silently dropped (loom.store-lifetime-target-unsupported, #flutter-field).

auth: ui ships (auth-gate.ts): a sessionProvider (FutureProvider<CurrentUser?>) over GET /auth/me, sign-in / sign-out redirects to the backend's own handshake via url_launcher, an AuthGate on MaterialApp.builder (spinner → sign-in prompt → routes; on the builder and not around MaterialApp, so its Material widgets have Theme/Directionality ancestors and the app never unmounts mid-probe), a page requires guard rendering ForbiddenView, and Action-button gating on a currentUser-only op requires.

Realtime (on <channel>.<Event>) ships (realtime.ts): one subscription against /realtime/events mounted on MaterialApp.builder, a SnackBar per toast(…), and ref.invalidate(<var>Provider) per refetch(<Agg>) — invalidating a .family refetches every live instance, so a server-paged table reloads the page the user is on. The transport is a conditional import: the browser's own EventSource on the web (package:web; package:http's browser client buffers the whole body, so it cannot stream) and a line parser over a streamed package:http response natively.

ProvenanceInfo renders a native ExpansionTile disclosure over the co-located <field>_provenance (a ProvLineage? on the decoded model — dart-model-emit.ts).

A user component Foo(params) { body } emits a Dart widget into lib/components.dart (component-emit.ts); an invocation Foo(a: x) renders as a widget constructor call and the page imports ../components.dart. A stateless component (value params, no own state) becomes a StatelessWidget (one final field per param, the walked body as build). A stateful component (state {} + named actions) becomes a StatefulWidget whose State holds an immutable <Comp>Model (the same data-class shape a Riverpod page projects), built in initState, exposes each param as a widget.<param> getter, and wraps each action body in setState — reusing the page path's renderNotifierStmt (a write is state = state.copyWith(field: value)). State is per-instance (each Foo(...) its own State), which a shared Riverpod provider would get wrong. A read-bearing component (a QueryView { of: … } body, no own state {}) becomes a Riverpod ConsumerWidget — exactly the shape a read-bearing PAGE takes: build(BuildContext context, WidgetRef ref) hoists final <var> = ref.watch(<var>Provider…) through the same renderApiHoisting seam, and collectFlutterReads scans component bodies so the provider it watches is emitted into lib/reads.dart. Only USED components are emitted; an extern component, a derived binding, an async-effect (match await) action, a store read, a byId read (the route id is a local only a page shell binds), or a stateful component that ALSO reads (that would need ConsumerStatefulWidget) falls back to the diagnostic comment.

An array-of-value-object form field (lines: LineItem[]) renders each row as a group of TextFormFields over the VO's scalar sub-fields (a List<List<TextEditingController>> in state), submitting a {sub: value, …} map per row — when every sub-field is text/numeric (a bool/enum/datetime/nested sub-field defers the whole array).

Known frontier: VO-array fields with non-scalar sub-fields, and the remaining user-component variants (extern / derived / stateful-plus-read / byId-read / store-read / async-effect actions), are deferred (fall back to a diagnostic comment — never broken Dart). Inline := state writes in render-tree lambdas are rejected upstream (loom.effect-in-lambda); named-action writes emit through the Riverpod Notifier — a nested target (draft.address.zip := v) folds into an immutable copyWith chain (state.draft.copyWith(address: state.draft.address.copyWith(zip: v))), so every wire model carries a copyWith. (End-to-end record-typed page state additionally needs the VO.create({…}) state initializer, a separate universal gap — see docs/old/proposals/nested-state-writes-copywith-frontends.md.) See docs/old/plans/flutter-mobile-implementation.md.

Phoenix LiveView fullstack (platform: elixir)

generate system for deployables marked platform: elixir. Single project that both serves a context-derived API (when serves: is populated) AND mounts a ui: rendered as Phoenix LiveView modules. Owns its own Postgres database (needsDb: true). Plain Ecto/Phoenix — the Ash foundation was removed (and with it the foundation: axis, which had collapsed to a single value everywhere; a would-be foundation: clause no longer parses).

File map

For a fullstack phoenixApp with contexts: [Sales] + matching dataSources: [salesState], serves: SalesApi, ui: SalesAdmin:

phoenix_app/
├── mix.exs                                       # phoenix, phoenix_live_view, ecto, ecto_sql, postgrex
├── .formatter.exs
├── Dockerfile                                    # multi-stage hexpm/elixir → debian, mix release
├── .dockerignore
├── config/{config,dev,prod,runtime}.exs          # Phoenix + Ecto config
├── priv/repo/
│   └── migrations/<ts>_create_<table>.exs        # one per aggregate, stable ordering, FK indexes
                                                  # NOTE: no seeds.exs — `seed` datasets emit NOTHING on
                                                  # this backend today (B19 / M-T6.37); the layout adapter
                                                  # reserves the slot but no emitter writes it.
├── rel/{env.sh.eex,overlays/bin/server}          # release scaffolding
├── lib/phoenix_app/
│   ├── application.ex                            # supervision tree: Repo, Endpoint, PubSub
│   ├── repo.ex                                   # Ecto.Repo
│   ├── request_context.ex                        # ambient exec-context carrier (Plug → Logger.metadata: correlation_id/scope_id/actor_id) — see architecture/request-context.md
│   └── sales/                                    # one folder per BoundedContext
│       ├── customer.ex                           # Ecto.Schema per aggregate
│       ├── order.ex
│       ├── order_line.ex                         # entity-part as embedded_schema
│       ├── order_status.ex                       # enums as Ecto.Enum
│       ├── email.ex                              # a CONSTRAINED value object → a schemaless-changeset
│                                                #   validator module.  An UNCONSTRAINED VO (Money) emits
│                                                #   no module at all — it is a :map column on the owner.
│       ├── events/order_confirmed.ex             # plain defstruct modules
│       ├── workflows/place_order.ex              # context fns wrapping Repo.transaction
│       ├── dispatcher.ex                         # in-process event router (when a channel carries a subscribed event)
│       ├── workflows/order_fulfillment_state.ex  # saga-state Ecto.Schema (correlation-keyed)
│       ├── workflows/order_fulfillment/start_order_placed.ex   # event-create starter handle/1
│       └── workflows/order_fulfillment/on_shipment_requested.ex # on(...) reactor handle/1
│   └── sales.ex                                  # context module — schema list + public functions
├── lib/phoenix_app_web.ex                        # __using__ macro
└── lib/phoenix_app_web/
    ├── endpoint.ex                               # Phoenix.Endpoint
    ├── router.ex                                 # `live "<route>", <Page>Live` per PageIR
    ├── controllers/realtime_controller.ex        # broadcast channels only: chunked SSE at GET /api/realtime/events
    ├── components/
    │   ├── core_components.ex                    # <.input>, <.button>, <.modal>, <.simple_form>, <.table>
    │   ├── layouts.ex                            # use Phoenix.Component
    │   └── layouts/{root,app}.html.heex
    └── live/
        ├── customer_list_live.ex                 # one per scaffolded PageIR
        ├── customer_new_live.ex
        └── customer_detail_live.ex

Per-aggregate detail

Aggregate IR maps onto Ecto/Phoenix:

Per-page detail

PageIR maps onto LiveView:

The framework-specific seams (state read/write, hook hoisting, match, navigate, helper imports) live behind the WalkerTarget interface in src/generator/_walker/target.ts — see page-metamodel.md §16 for the full mapping table.

Java backend (platform: java)

Spring Boot 4.1 / Spring Data JPA (Hibernate) / Postgres, built with Gradle (Kotlin DSL, Boot plugin + BOM import, Java 25 toolchain; no wrapper jar is committed — the generator emits text only, and the Dockerfile/CI/dev environments provide Gradle ≥ 9.1 — required for the Java 25 toolchain — or run gradle wrapper once). Emission lives in src/generator/java/; the surface is src/platform/java.ts (java@v1). Per-aggregate placement routes through the layout adapter (byFeature default — package-by-feature; byLayer — package-by-layer), which owns BOTH the package and the file path.

Per deployable it emits:

Expression rendering is the JAVA_TARGET leaf table over the shared ExprTarget dispatcher: BigDecimal method arithmetic with compareTo comparisons, Objects.equals reference equality, Instant ordering via isBefore/isAfter, find-anywhere regex via Pattern…find(), Streams collection ops with type-directed sum reduction.

Both the ui: embedded-SPA mount and the D-PHOENIX-SURFACE hosts: UI hosting are implemented (M-T6.5): a hosts: binding onto a framework:-owning ui { } block embeds that framework's SPA (react / vue / svelte) into the Spring project — controllers under /api/*, SpaWebConfig serving UI_DIR with an index.html fallback, the SPA under ClientApp/, and a node spa-build Dockerfile stage — the dotnet hosts: twin, at full hosting parity.

Not yet implemented — every gap fails fast at validate time (never a silent downgrade): the reserved axon event-store adapter and jooq persistence adapter (both stubAdapter — the default JPA persistence does emit persistedAs: eventLog), resource-op clients, a principal-referencing capability filter on a non-relational aggregate (loom.context-filter-no-principal — each half ships alone; only the actor + jsonb intersection is deferred), and provenance/audited (gated — no runtime emitted; the node and .NET backends do implement these). See docs/old/plans/java-backend-implementation.md for the execution record.

Value-object read-model fields ARE implemented. A VO-typed workflow-instance field or projection row field emits its <Vo>Response record co-located in the consuming package (application.workflows for instance/projection reads), the read-model analogue of an aggregate response's nested VO records. Only an entity (containment part) read-model field stays gated (loom.java-workflow-instance-field-unsupported / loom.java-projection-field-unsupported) — a defensive backstop, since a part type never resolves in workflow / projection scope.

Discriminated unions (operation returns; union finds take the untagged optional-style path — see payloads.md), shape: document / shape: embedded persistence, event-sourced (persistedAs: eventLog) JPA streams, and non-principal capability filters on those non-relational shapes are all implemented (no per-backend gate refuses them on java; PLATFORM_SAVING_SHAPES.java carries all three shapes).

Names that are Java reserved words

A .ddd member, parameter, operation or enum value may be called case, do, final, native, … — anything the .ddd grammar admits. Java has no verbatim identifier (JLS §3.9), so the emitted host identifier is mangled with a trailing underscore (case → case_, the spelling the emitters already used for let bindings), and the wire spelling is pinned back on wherever that identifier would otherwise have become the wire name:

Nothing about the wire, the OpenAPI document or the stored data differs from the other four backends; the mangle is visible only in the generated Java. Emission for a keyword-free model is byte-identical to before.

Python backend (platform: python)

FastAPI / SQLAlchemy 2 (typed declarative, async) / asyncpg / Postgres, managed by uv (Python 3.12) and held to ruff check + mypy --strict + pytest by the LOOM_PYTHON_BUILD gate. Emission lives in src/generator/python/; the surface is src/platform/python.ts (python@v1; python is the only spelling — the fastapi platform alias was retired the way phoenix/hono were). Async end-to-end: async def handlers over a per-request AsyncSession — repositories flush(), the session dependency commits once after the handler returns, so multi-save workflows are atomic by construction.

Per deployable it emits:

Expression rendering is the PY_TARGET leaf table over the shared ExprTarget dispatcher: native Decimal money arithmetic, comprehension-shaped collection ops, re.search regex, snake_case member folding.

Conformance: a pythonApi deployable ships in examples/showcase.ddd and the e2e OpenAPI cross-check compares it pairwise against Hono / .NET / Phoenix / Java (all five backends are diffed — strict in conformance-parity.yml).

Resource verb clients (objectStore → boto3, queue → aio-pika, api → httpx, mailer → aiosmtplib) are emitted under app/resources/<sourceType>.py; workflow / saga <resource>.<verb>(...) calls import + await them. (Cross-backend the mailer client is nodemailer / MailKit / Swoosh / Jakarta Mail — see resources.md for the full kind × backend matrix.)

Not yet implemented (fails fast / follow-ups): durable-channel outbox tier, --trace domain instrumentation, and provenance/audited (gated — no runtime emitted; the node and .NET backends do implement these). shape: document / shape: embedded persistence (all three shapes are in PLATFORM_SAVING_SHAPES.python) and when can-queries are implemented.

Names that are Python keywords

The python twin of Java's reserved words (eval item 6, ruling D-TARGET-RESERVED-NAMES). Python has no verbatim identifier, and every .ddd member lands in an identifier position — a keyword argument, an attribute, a def name — so one funnel in src/util/naming.ts spells them all: pythonIdent(name) (the snake_cased domain/ORM spelling, def → def_) and pythonWireIdent(name) (the camelCase pydantic spelling, def → def_). The two names the outside world sees are pinned back on:

aggregate Thing with crudish {
  def: string
  operation class(except: int) { … }
}
repository Things for Thing { find byDef(def: string): Thing? where this.def == def }

Emission for a keyword-free model is byte-identical: pythonIdent equals snake for every other name. Not yet funnelled: folded / query-time projection read models and the auth.user claim record still spell a member name bare (a keyword there remains a syntax error, not a silent defect).

Generated-helper collisions. A member may also take the name of a private helper the entity emitter generates. The invariant check was the one that collided: .NET emitted private void AssertInvariants() beside the AssertInvariants property of a member assertInvariants (CS0102), node's backing field private _assertInvariants: string duplicated the method, and python's backing field self._assert_invariants overwrote the method (a TypeError on the first invariant check). On all three the helper now steps aside — AssertInvariants_ / _assertInvariants_ / _assert_invariants_ — only when a member takes its name. Java (_assertInvariants beside the field assertInvariants) and Elixir (functions and struct keys are separate namespaces) never collided. Pinned by the python-reserved-words corpus row (every compile tier + the wire-golden differential) and test/generator/target-reserved-member-names.test.ts.

The per-target reserved-identifier table (every backend)

The Java and Python sections above are two instances of one contract. Every target's reserved words now live in ONE table, src/util/target-identifiers.ts — ts, csharp, java, python, elixir, fsharp, dart — with ONE escaping path, escapeTargetIdent(target, name) (C# @base, F# ``member``, a trailing _ everywhere else) and a pure isReserved(target, name). The per-language helpers (escapeCsharpIdent / escapeTsIdent / escapeJavaIdent / escapePythonIdent / escapeElixirIdent in naming.ts, java's jid and package segments, F#'s fsIdent, Dart's dartMember) are views of it, so no backend carries a keyword list of its own. One table closes the drift the per-backend copies had: Java's two copies disagreed on record / yield / sealed / permits; TS lacked the strict-mode arguments / eval; C# lacked await (illegal inside the async handlers every command runs in); python lacked the method receivers self / cls and the builtin / BaseModel names a generated class body shadows (str, dict, …).

A second table, escapeTargetMember, holds names a target reserves as a class MEMBER although they are legal bindings — TS constructor and then (an operation named then makes every aggregate a thenable, so await repo.getById(…) breaks), and Dart's inherited Object members (hashCode, toString, noSuchMethod, runtimeType).

Scope collisions are a separate concern and stay with each backend's namer: a .ddd name landing on a local the generated method declares for itself (javaLocals, csLocalNamer, csParamIdent, dartComponentMember) is not a keyword, and those namers build on the table rather than replace it.

The gate is test/fixtures/corpus/target-reserved-words.ddd (row ALL): every table word the .ddd grammar admits, as a field, an enum value, an operation, and that operation's parameter — ~180 names at once — on every backend's compile leg (tsc, dotnet build /warnaserror incl. Dapper, gradle, uv + ruff + mypy + pytest, mix compile --warnings-as-errors). test/util/target-identifiers.test.ts keeps the table and the fixture from drifting (a table word the grammar admits but the fixture omits fails), and checks the tables with an authoritative source against it (python's keyword module, the TypeScript scanner's reserved-word range).

Not covered yet — tracked by #4213: a FIELD named constructor on node (its getter cannot carry that name), TYPE names that shadow a target's globals / BCL / framework types (valueobject Promise / String / Symbol on node; .NET handles Task-like names via dotnet-bcl-type-collision), and the frontends (the fixture declares no ui).

System orchestration

generate system (in src/system/index.ts) runs each deployable through its respective backend, scoped to its hosted contexts, and writes everything to a flat tree:

<outdir>/
├── api/                  # one folder per deployable
├── catalog_web/
├── web_app/
├── docker-compose.yml    # postgres + every deployable + healthchecks
├── docker-compose.obs.yml       # opt-in: prometheus + jaeger + the OTLP export env
├── monitoring/prometheus.yml    # the overlay's scrape config, one job per backend
├── db-init/
│   └── 00-create-databases.sql  # CREATE DATABASE per backend deployable
└── e2e/                  # generated DSL-level e2e suite (vitest+fetch)
    ├── package.json
    ├── tsconfig.json
    └── <System>.e2e.test.ts

Per-platform compose service shape

Frontend same-origin in compose. A vite-served frontend's built bundle fetches /api relative, and its image runs vite preview. So compose injects VITE_API_PROXY_TARGET (→ the target backend's compose service, e.g. http://api:3000, not localhost) and the generated vite.config.ts proxies /api to it on both server (dev) and preview (the compose runtime). Result: one origin, no CORS, no separate API host — the compose twin of the k8s same-origin Ingress. (Local vite dev falls back to the baked http://localhost:<port> target.)

The platform contract decides UI mount admissibility and DB ownership via two PlatformSurface flags (src/platform/surface.ts): mountsUi (true on react, static, phoenixLiveView) and needsDb (true on dotnet, node, phoenixLiveView). The system orchestrator consults these instead of hardcoding platform names, so adding a new platform extends the registry + the two flags only.

Per-deployable databases

The init script db-init/00-create-databases.sql creates one database per backend deployable. Each backend's connection string points to its own DB. This sidesteps a real bug observed on .NET: EF Core's EnsureCreated is all-or-nothing per database, so two backends sharing one DB silently leave the loser-of-the-race's tables uncreated. React deployables don't connect to a DB and don't appear in the init script.

Every statement is idempotent (SELECT 'CREATE DATABASE x' WHERE NOT EXISTS (…) \gexec): Postgres runs docker-entrypoint-initdb.d only on an EMPTY volume, so the compose stack also carries a one-shot db-bootstrap service that re-applies the same file over TCP on every up, and each database-backed service waits for it with condition: service_completed_successfully. A deployable added in a later generation therefore gets its database on an existing volume (B-26 of the banking evaluation — it used to crash-loop on database "x" does not exist).

Migrations

Schema changes flow through a platform-neutral MigrationsIR (src/ir/types/migrations-ir.ts), one per entry of the committed migration chain (migrations/ beside the .ddd, recorded by ddd migrate add). The builder (src/system/migrations-builder.ts) derives each module's delta against the chain's head for every (subdomain, storage) pair owned by a deployable (migrationsOwner enrichment in src/ir/enrich/enrichments.ts). Backends only translate steps to their syntax via the per-platform emitters listed below — they never recompute the schema themselves. Shared SQL rendering for the Postgres-backed emitters lives in src/generator/sql-pg.ts.

Phoenix stays in Ecto DSL because its output is Elixir. Hono and .NET share src/generator/sql-pg.ts for bit-identical Postgres DDL.

Every generate system renders the whole chain: one file per backend per recorded generation, the first of each subdomain its "Initial". Recording a new property with migrate add adds a single ALTER TABLE … ADD COLUMN … per backend. A source with no chain yet renders each subdomain's "Initial" derived from the model.

Regenerating is deterministic: the same source and chain render the same files into any output tree. Renames are declared in a migration block (see migrations.md).

test e2e lowering

A test e2e "name" against <deployable> { … } block lowers via src/system/e2e-render.ts into typed fetch calls in <outdir>/e2e/<System>.e2e.test.ts:

expect(<x>).<matcher>(…) lowers to the native matcher; expect(<call>).toThrow() becomes expect(() => <call>).toThrow().

What the generators don't do

Out of scope for v1 (intentional):

• Production identity provider: auth: required + a user {} block emit a first-class auth surface on every backend — a typed principal, a request boundary (401), requires 403 gates on operations / pages, currentUser/tenancy capability filters, and an OIDC turnkey verifier — but the default verifier is an accept-all dev stub. Wiring a real IdP (or replacing the stub) is the deployment's job; see auth.md. (Fine-grained RBAC beyond predicate requires is not modelled.)
• Pagination on findAll — stale, corrected 2026-09-10. The implicit find all is paged by default (M-T2.6): enrichment synthesises it with a paged<T> return rather than T[] (src/ir/enrich/enrichments.ts, the all FindIR), and the four shapes that stay bare T[] each have a reason recorded at the site — persistedAs: eventLog (the read folds a stream, there is no LIMIT/OFFSET query), shape: document (one opaque JSONB blob, no queryable column to page or ORDER BY), shape: embedded (backend support for paging its queryable root diverges, so it stays uniform rather than paged on some), and an inheritance subtype (the polymorphic find all <Base> reader concatenates each subtype's all(), which cannot be page-sliced correctly before the merge). The IR carries paged only where a controller honours it, so the flag is never a lie.
• Multi-target frontends: a react deployable has exactly one targets:. Hosting against several APIs is deferred.
• Typeahead lookups for X id form fields — stale, corrected 2026-09-10. An X id field renders a Select picker populated from the target's own list hook whenever the target declares derived display: string (prepareFormFieldVM → field-input-id-select, src/generator/_walker/form-fields-vm.ts); the option label is read off the wire display field, so a compound (firstName + " " + lastName), member-access or conditional display works without the picker knowing the source expression. Several packs make it searchable client-side (mantine's <Select searchable>). It falls back to field-input-id-text in exactly two cases — the target aggregate is unresolved, or it declares no derived display — and the text input's placeholder then names which. What is still out of scope is a server-side typeahead: the picker loads the target's list, so a target with more rows than a page is not searchable beyond what it loaded.
• Ordering on X id[] collections: Target id[] is a set (D-REFCOLL-SET). On all five backends the join table is only the composite (owner, target) key — no ordinal column — and every backend reads the rows back sorted by the target FK id (Drizzle/EF/Dapper/SQLAlchemy ORDER BY it, JPA's argument-less @OrderBy, Ecto's preload_order: [asc: :id]). So the order is stable, but it is an id order the domain never chose: treat party[0] as "some element of party," not "the first element of party." When position is part of the domain (a battle slot, a draft pick number), model it as an explicit ordinal field on a separate child aggregate instead of relying on collection order.
• Server-side rendering: client-only Vite. Next.js variant would be a separate platform.
• Generated CI pipelines: project-init concerns, not derived from the .ddd source. (k8s manifests are no longer on this list — the opt-in generate system --k8s flag emits a Helm chart + raw manifests; see kubernetes.md.)

These are all addressable as either generator extensions or .loomignore-pinned customizations.