@cosmicdrift/kumiko-framework 0.391.1 → 0.392.0

package/agents/examples/record-detail-layout.md

@@ -443,7 +443,7 @@ function tabsLocator(page: Page) {
   return page.getByTestId("kumiko-screen-projection-detail-tabs");
 }
 
-test.describe("record-detail-layout — tab-panel height (fw#2778)", () => {
+test.describe("record-detail-layout — tab-panel height", () => {
   // The design refresh (#3381) made detail tabs a full-bleed "board": the
   // relatedList scroll region fills the panel down to the footer instead of
   // the card sizing to its rows (fw#2778's original behavior). What must
@@ -616,9 +616,7 @@ test("record-detail-layout — all tab kinds + screen actions, one screenshot pe
 
 import { expect, boundaryGuardedTest as test } from "@cosmicdrift/kumiko-testing/e2e";
 
-test("record-detail-layout — tab strip fits the phone viewport width (fw#3234)", async ({
-  page,
-}) => {
+test("record-detail-layout — tab strip fits the phone viewport width", async ({ page }) => {
   await page.goto("/");
   await expect(page.getByTestId("render-edit-form")).toBeVisible();
   await expect(page.getByTestId("kumiko-screen-projection-detail-tabs")).toBeVisible();
@@ -794,10 +792,11 @@ describe("record-detail-layout showcase — registration", () => {
     ]);
   });
 
-  test("screen-level actions carry a refresh-order navigate action", () => {
+  test("screen-level actions carry refresh-order and keep download-invoice inline", () => {
     const screen = registry.getScreen("order-desk:screen:order-detail");
     if (screen?.type !== "projectionDetail") throw new Error("expected projectionDetail");
-    expect(screen.actions?.map((a) => a.id)).toEqual(["refresh-order"]);
+    expect(screen.actions?.map((a) => a.id)).toEqual(["refresh-order", "download-invoice"]);
+    expect(screen.inlineActions).toEqual(["download-invoice"]);
   });
 
   test("relatedList columns collapse string shorthand into the object form", () => {
@@ -809,6 +808,21 @@ describe("record-detail-layout showcase — registration", () => {
   });
 });
 
+describe("record-detail-layout showcase — empty states", () => {
+  test("the payments tab declares a record-dependent empty text ahead of its default", () => {
+    const screen = registry.getScreen("order-desk:screen:order-detail");
+    if (screen?.type !== "projectionDetail") throw new Error("expected projectionDetail");
+    const payments = screen.layout.sections.find((section) => section.id === "payments");
+    if (payments?.kind !== "relatedList") throw new Error("expected the payments relatedList");
+    expect(payments.emptyState).toEqual({
+      title: "order-desk.payments.empty",
+      variants: [
+        { when: { field: "status", eq: "pending" }, title: "order-desk.payments.empty-pending" },
+      ],
+    });
+  });
+});
+
 describe("record-detail-layout showcase — boot-validator catches author mistakes", () => {
   test("metric with an empty label fails boot — no fallback to the raw column name", () => {
     const broken = defineFeature("broken-order-desk", (r) => {
@@ -868,8 +882,10 @@ describe("record-detail-layout showcase — boot-validator catches author mistak
 //      one `extension` section (a plugin-mounted component, fw#3234 padding-
 //      parity check — every tab kind must sit in the same Card padding, no
 //      section carries extra chrome of its own).
-//   4. A screen-level `actions` entry (fw#3234) renders next to the header,
-//      not inside any tab's Card.
+//   4. The payments tab's emptyState picks its text from the order record through `variants`.
+//   5. A screen-level `actions` entry (fw#3234) renders next to the header,
+//      not inside any tab's Card. `inlineActions` keeps download-invoice a visible
+//      button next to it where the page header would otherwise fold it into the menu.
 //
 // projectionDetail has no entity — it binds to an explicit query instead, so
 // every field name below (header, metrics, fields) is a column of that
@@ -965,6 +981,15 @@ export function createOrderDeskFeature(): FeatureDefinition {
               "method",
               "status",
             ],
+            emptyState: {
+              title: "order-desk.payments.empty",
+              variants: [
+                {
+                  when: { field: "status", eq: "pending" },
+                  title: "order-desk.payments.empty-pending",
+                },
+              ],
+            },
           },
           {
             id: "details",
@@ -989,7 +1014,15 @@ export function createOrderDeskFeature(): FeatureDefinition {
           screen: "order-detail",
           icon: "refresh",
         },
+        {
+          kind: "navigate",
+          id: "download-invoice",
+          label: "order-desk.action.downloadInvoice",
+          screen: "order-detail",
+          icon: "download",
+        },
       ],
+      inlineActions: ["download-invoice"],
       access: { roles: ["Support", "Admin"] },
     });
   });

package/agents/examples/seed-migration.md

@@ -105,41 +105,41 @@ Wenn eine kaputte Migration den Boot blockiert: setze `skippable: true` im seed-
 ```ts
 // biome-ignore-all lint/suspicious/noConsole: CLI tool output
 //
-// Lokaler Smoke-Test für seed-migrations.
+// Local smoke test for seed migrations.
 //
-// Was er prüft (offline, ohne Pod-Deploy):
-//   1. Alle seed-files in ./seeds/ können dynamic-import geladen werden
-//      → catched syntax-errors + missing default-exports + falsche paths
-//   2. Jeder handler-QN den die seeds referenzieren ist in der echten
-//      App-Registry registriert → catched camelCase-typos + drift
-//      (Bug-Klasse 3 aus Phase 1 retro)
-//   3. Jeder system-user (mit oder ohne tenantIdOverride) hat Access auf
-//      die referenzierten Handler → catched access-rule-Drift
-//      (Bug-Klasse 4 aus Phase 1 retro)
+// What it checks (offline, without a pod deploy):
+//   1. All seed files in ./seeds/ can be loaded via dynamic import
+//      → catches syntax errors + missing default exports + wrong paths
+//   2. Every handler QN the seeds reference is registered in the real
+//      app registry → catches camelCase typos + drift
+//      (bug class 3 from the phase 1 retro)
+//   3. Every system user (with or without tenantIdOverride) has access to
+//      the referenced handlers → catches access rule drift
+//      (bug class 4 from the phase 1 retro)
 //
-// Schreibt NICHTS in die DB. Reine Read-only Validation.
+// Writes NOTHING to the DB. Pure read-only validation.
 //
 // Usage:
-//   bun scripts/smoke.ts                  (gegen ./seeds/)
+//   bun scripts/smoke.ts                  (against ./seeds/)
 //   bun scripts/smoke.ts --seeds-dir foo  (custom path)
 //
-// In CI: vor `build`-Step laufen lassen — fängt 80% der Phase-1-Bugs
-// lokal in <5 Sekunden statt nach 8-Minuten-Docker-Build im Pod-Boot.
+// In CI: run before the `build` step — catches 80% of the phase 1 bugs
+// locally in <5 seconds instead of after an 8-minute Docker build in the pod boot.
 
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { resolve } from "node:path";
-// App-spezifisch: nimm die EFFEKTIVEN Features die deine App zur Runtime
-// nutzt. Im typischen Setup mit `runProdApp({ features, auth })`:
+// App-specific: take the EFFECTIVE features your app uses
+// at runtime. In the typical setup with `runProdApp({ features, auth })`:
 //
 //   import { composeFeatures } from "@cosmicdrift/kumiko-dev-server";
 //   import { APP_FEATURES } from "../src/run-config";
 //   const composed = composeFeatures(APP_FEATURES, { includeBundled: true, ... });
 //   const features = composed.features;
 //
-// Bei reiner App-Feature-Setup (kein auth-mode) reicht ein direkter
-// Import der App-Features. Hier im Recipe der minimale set für die
-// referenzierten Recipe-Seeds (tenant + config) — App-Author tauscht
-// gegen sein eigenes Feature-Set.
+// For a pure app-feature setup (no auth mode) a direct
+// import of the app features is enough. Here in the recipe the minimal set for the
+// referenced recipe seeds (tenant + config) — the app author swaps it
+// for their own feature set.
 import { createConfigFeature } from "@cosmicdrift/kumiko-bundled-features/config";
 import { createTenantFeature } from "@cosmicdrift/kumiko-bundled-features/tenant";
 import {
@@ -233,25 +233,25 @@ console.log(`\n✓ all ${seedFiles.length} seed-file(s) pass smoke.`);
 ### seeds/2026-01-01-initial-tenants.ts
 
 ```ts
-// Initial-Seed: Demo-Tenants anlegen.
+// Initial seed: create demo tenants.
 //
-// Note: in real apps wäre "initial tenants" wahrscheinlich nicht als
-// seed-migration sondern als `r.config({seeds})` oder `auth.admin`-
-// Config umgesetzt — die laufen jedes-Boot idempotent. Hier ist es als
-// seed-migration gezeigt um das Pattern zu demonstrieren.
+// Note: in real apps "initial tenants" would probably not be implemented as a
+// seed migration but as `r.config({seeds})` or `auth.admin`
+// config — those run idempotently on every boot. Here it is shown as a
+// seed migration to demonstrate the pattern.
 //
-// Pattern: jede seed-migration arbeitet write-only via `systemWriteAs`
-// damit alles als Event-Stream persistiert wird. Read-only Lookups
-// (find*) am Context oder direkt via ctx.db.
+// Pattern: every seed migration works write-only via `systemWriteAs`
+// so everything is persisted as an event stream. Read-only lookups
+// (find*) on the context or directly via ctx.db.
 
 import type { SeedMigration } from "@cosmicdrift/kumiko-framework/es-ops";
 
 export default {
   description: "initial demo tenants (alice-corp, beta-inc)",
   run: async (ctx) => {
-    // Idempotent-Check: wenn Tenants schon existieren (z.B. via auth.admin-
-    // seed), skip diese Migration. Verhindert Konflikt beim re-boot wenn
-    // jemand den Marker manuell gelöscht hat.
+    // Idempotency check: if tenants already exist (e.g. via an auth.admin
+    // seed), skip this migration. Prevents a conflict on re-boot if
+    // someone deleted the marker manually.
     const existing = await ctx.findTenants();
     if (existing.some((t) => t.tenantKey === "alice-corp")) return;
 
@@ -270,14 +270,14 @@ export default {
 ### seeds/2026-02-01-fix-admin-roles.ts
 
 ```ts
-// Driver-Pattern: ergänze fehlende Rolle auf existierenden Memberships.
-// Spiegelt den realen publicstatus-Bug 2026-05-20 (admin@publicstatus.eu
-// hatte "Admin" aber nicht "TenantAdmin" → text-content + legal-pages
-// access_denied weil bundled-features TenantAdmin erwarten).
+// Driver pattern: add a missing role to existing memberships.
+// Mirrors the real publicstatus bug of 2026-05-20 (admin@publicstatus.eu
+// had "Admin" but not "TenantAdmin" → text-content + legal-pages
+// access_denied because bundled-features expect TenantAdmin).
 //
-// Funktioniert für jede App mit dem gleichen Pattern: User-Lookup per
-// E-Mail → alle Memberships durchgehen → bei Bedarf via existierendem
-// updateMemberRoles-Handler korrigieren.
+// Works for any app with the same pattern: user lookup by
+// email → go through all memberships → correct via the existing
+// updateMemberRoles handler if needed.
 
 import type { SeedMigration } from "@cosmicdrift/kumiko-framework/es-ops";
 
@@ -297,12 +297,12 @@ export default {
           tenantId: m.tenantId,
           roles: Array.from(new Set([...m.roles, "TenantAdmin"])),
         },
-        // tenantIdOverride: stream-tenant aus kumiko_events.v1 — NICHT
-        // m.tenantId (payload-tenant). Beide stimmen oft überein, weichen
-        // aber ab wenn das Aggregate ursprünglich von einem fremden
-        // Executor angelegt wurde (seedTenantMembership by=systemAdmin —
-        // publicstatus-Pattern). findMembershipsOfUser liefert beide,
-        // kein eigener JOIN nötig.
+        // tenantIdOverride: stream tenant from kumiko_events.v1 — NOT
+        // m.tenantId (payload tenant). The two often match, but differ
+        // when the aggregate was originally created by a foreign
+        // executor (seedTenantMembership by=systemAdmin —
+        // publicstatus pattern). findMembershipsOfUser returns both,
+        // no separate JOIN needed.
         m.streamTenantId,
       );
     }

package/agents/examples/user-data-rights.md

@@ -134,15 +134,15 @@ export const features = [
 ### src/__tests__/feature.integration.test.ts
 
 ```ts
-// User-Data-Rights Recipe — Integration-Test.
+// User-data-rights recipe — integration test.
 //
-// Pinst dass die zwei Hooks aus feature.ts genau das tun was die Recipe-
-// README verspricht:
-//   1. Notes des Users landen via export-Hook im Bundle-Snippet.
-//   2. Forget-Cleanup-Cron entfernt die Notes via delete-Hook (strategy
+// Pins that the two hooks from feature.ts do exactly what the recipe
+// README promises:
+//   1. The user's notes land in the bundle snippet via the export hook.
+//   2. The forget-cleanup cron removes the notes via the delete hook (strategy
 //      "delete", default).
-//   3. Strategy "anonymize" (HR-Override) setzt authorId=null statt zu
-//      löschen — Row bleibt für Multi-User-Refs intakt.
+//   3. Strategy "anonymize" (HR override) sets authorId=null instead of
+//      deleting — the row stays intact for multi-user refs.
 
 import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
 import { createAuthFoundationFeature } from "@cosmicdrift/kumiko-bundled-features/auth-foundation";
@@ -294,7 +294,7 @@ describe("user-data-rights recipe :: EXT_USER_DATA-Hooks integrieren Notes-Domai
     expect(remaining.length).toBe(0);
   });
 
-  test("Strategy=anonymize: authorId=null, Row bleibt (HR-Compliance-Pfad)", async () => {
+  test("Strategy=anonymize: authorId=null, row remains (HR-Compliance path)", async () => {
     await seedAlice();
     await seedNote(noteId(1), "stays-anonymous");
 
@@ -436,23 +436,23 @@ describe("user-data-rights recipe :: retention run removes a hardDelete entity's
 ### src/feature.ts
 
 ```ts
-// User-Data-Rights — Recipe
+// User-Data-Rights — recipe
 //
-// Wie eine App-Domain DSGVO-Pipeline integriert: pro Entity einen
-// (export, delete)-Hook ueber EXT_USER_DATA. Forget-Cron, Export-ZIP-Bau
-// und Magic-Link-Versand kommen vollstaendig aus user-data-rights —
-// App-Author schreibt nur die zwei Hooks pro Entity.
+// How an app domain integrates the GDPR pipeline: one
+// (export, delete) hook per entity via EXT_USER_DATA. Forget cron, export ZIP build
+// and magic link delivery come entirely from user-data-rights —
+// the app author writes only the two hooks per entity.
 //
-// Demo-Domain: minimaler Note-Service. Note hat (id, tenantId, authorId,
-// title, body). Pinst:
-//   1. Hook export liefert Note-Rows als JSON-Snippet ins Export-Bundle.
-//   2. Hook delete entfernt Note-Rows beim Forget-Cleanup-Cron.
+// Demo domain: minimal note service. A note has (id, tenantId, authorId,
+// title, body). Pins:
+//   1. The export hook delivers note rows as a JSON snippet into the export bundle.
+//   2. The delete hook removes note rows during the forget-cleanup cron.
 //
-// Was nicht im Recipe ist (siehe samples/apps/user-data-rights-demo
-// fuer eine vollstaendige App):
+// What is not in the recipe (see samples/apps/user-data-rights-demo
+// for a complete app):
 //   - Strategy-aware delete (anonymize vs hardDelete)
-//   - HTTP-Endpoints fuer create/list
-//   - Compliance-Profile-Wiring + Cron-Scheduling
+//   - HTTP endpoints for create/list
+//   - Compliance profile wiring + cron scheduling
 
 import {
   deleteMany,

package/agents/examples/user-profile.md

@@ -98,10 +98,10 @@ matches `UserProfileHandlers.changeEmail`.
 ### src/__tests__/feature.test.ts
 
 ```ts
-// Boot-Validation der vollen user-profile-Komposition: Require-Kette
-// erfüllt, Screen + Nav registriert, change-email-Handler unter der
-// dokumentierten QN. Kein DB/HTTP nötig — der HTTP-Beweis lebt im
-// bundled-feature-Test (change-email.integration.test.ts).
+// Boot validation of the full user-profile composition: require chain
+// satisfied, screen + nav registered, change-email handler under the
+// documented QN. No DB/HTTP needed — the HTTP proof lives in the
+// bundled-feature test (change-email.integration.test.ts).
 
 import { describe, expect, test } from "bun:test";
 import { UserProfileHandlers } from "@cosmicdrift/kumiko-bundled-features/user-profile";
@@ -141,7 +141,7 @@ describe("user-profile recipe — boot validation", () => {
     ]);
   });
 
-  test("change-email QN entspricht der dokumentierten Konstante", () => {
+  test("change-email QN matches the documented constant", () => {
     expect(UserProfileHandlers.changeEmail).toBe("user-profile:write:change-email");
   });
 });

package/agents/examples/wizard-form.md

@@ -680,7 +680,7 @@ async function assertCssIsLive(page: Page): Promise<void> {
   expect(display).toBe("flex");
 }
 
-test.describe("wizard-form — 375px mobile chrome (#1917)", () => {
+test.describe("wizard-form — 375px mobile chrome", () => {
   test("step 1: step label and Next fit the viewport without overlap", async ({ page }) => {
     await gotoWizard(page);
     await assertCssIsLive(page);

package/agents/features.md

@@ -14,7 +14,7 @@ Administration group in the sidebar of this sample app.
 
 ## admin-shell
 
-Registers tenant-admin and platform-admin workspaces with provider nav into owner-feature screens (`tenant:screen:members`, `audit:screen:audit-log`, `audit:screen:audit-log-all-tenants`, `tenant:screen:tenant-list`, `jobs:screen:job-runs`, optional `tier-engine:screen:tier-admin`, optional `cap-overview:screen:my-caps`/`cap-overview:screen:tenant-cap-list`, optional `document-designer` template navs) and the two overview dashboards, built from the metrics list (`metrics` option, default DEFAULT_METRICS). Mount after user, tenant, audit, jobs, metrics and metrics-system; pass `workspaceIds` to match app URL conventions (e.g. Studio `d`/`s`, PublicStatus `admin`/`sysadmin`). Client: `adminShellClient()`, `tenantClient()`, `auditClient()`, `jobsClient()`, optional `tierEngineClient()`.
+Registers tenant-admin and platform-admin workspaces with provider nav into owner-feature screens (`tenant:screen:members`, `audit:screen:audit-log`, `audit:screen:audit-log-all-tenants`, `tenant:screen:tenant-list`, `jobs:screen:job-runs`, optional `tier-engine:screen:tier-admin`, optional `cap-overview:screen:my-caps`/`cap-overview:screen:tenant-cap-list`, optional `document-designer` template navs) and the two overview dashboards (the tenant one can be dropped with `includeTenantOverview: false`), built from the metrics list (`metrics` option, default DEFAULT_METRICS). Mount after user, tenant, audit, jobs, metrics and metrics-system; pass `workspaceIds` to match app URL conventions (e.g. Studio `d`/`s`, PublicStatus `admin`/`sysadmin`). Client: `adminShellClient()`, `tenantClient()`, `auditClient()`, `jobsClient()`, optional `tierEngineClient()`.
 
 Category: operations
 
@@ -381,7 +381,7 @@ Requires: `auth-foundation`, `tenant`
 
 ## inbound-mail-foundation
 
-Plugin host for inbound e-mail (inbox federation) — provider plugins (inbound-provider-imap, later M365 Graph / Gmail REST) register at the `inboundMailProvider` extension point with verify/fetch and optional oauth/watch (live push). The foundation owns three event-sourced streams (mail-account lifecycle, inbound-message with exactly-once ingest via deterministic aggregate ids, mail-thread rollup) and their projections `read_mail_accounts`/`read_inbound_messages`/`read_mail_threads`; PII fields are envelope-encrypted per tenant subject key before every append (crypto-shredding on tenant destroy). Wire `createInboundMailConnectRoutes` (OAuth connect + anonymous callback outside /api) and `createInboundMailSupervisor` (IDLE watch with backoff + reconciliation poll) in bin/server.ts. Consume `inbound-mail-foundation:event:inbound-message-received` from app features to attach business processes.
+Plugin host for inbound e-mail (inbox federation) — provider plugins (inbound-provider-imap, later M365 Graph / Gmail REST) register at the `inboundMailProvider` extension point with verify/fetch and optional oauth/watch (live push) and send. `sendMailFromAccount(ctx, { accountId, message })` sends from a connected mailbox through its provider (From = the mailbox address, no fallback to the app sender) and answers typed failures (not configured, login rejected, server unreachable, rejected, invalid message); app write handlers call it, it is no endpoint of its own. The foundation owns three event-sourced streams (mail-account lifecycle, inbound-message with exactly-once ingest via deterministic aggregate ids, mail-thread rollup) and their projections `read_mail_accounts`/`read_inbound_messages`/`read_mail_threads`; PII fields are envelope-encrypted per tenant subject key before every append (crypto-shredding on tenant destroy). Wire `createInboundMailConnectRoutes` (OAuth connect + anonymous callback outside /api) and `createInboundMailSupervisor` (IDLE watch with backoff + reconciliation poll) in bin/server.ts. Consume `inbound-mail-foundation:event:inbound-message-received` from app features to attach business processes.
 
 Category: notifications
 
@@ -389,7 +389,7 @@ Requires: `tenant-lifecycle`
 
 ## inbound-provider-imap
 
-Registers the `"imap"` provider for `inbound-mail-foundation` using imapflow — password/app-password auth covers classic IMAP hosts without any OAuth (plus an XOAUTH2 fallback consuming an access token from the secret slot). Incremental sync via a UIDVALIDITY:lastUid cursor (UIDVALIDITY change triggers a cursor-invalid full resync), initial backfill bounded by the foundation backfill window, and live push via IMAP IDLE for the watch supervisor. Store the per-account connection JSON (host/port/secure/user/password) in the account credential secret slot before the first sync.
+Registers the `"imap"` provider for `inbound-mail-foundation` using imapflow — password/app-password auth covers classic IMAP hosts without any OAuth (plus an XOAUTH2 fallback consuming an access token from the secret slot). Incremental sync via a UIDVALIDITY:lastUid cursor (UIDVALIDITY change triggers a cursor-invalid full resync), initial backfill bounded by the foundation backfill window, and live push via IMAP IDLE for the watch supervisor. Tenant admins connect a mailbox through the "Connect mailbox" form on the mail accounts list (`connect-mailbox` checks the IMAP login and the SMTP login of the outgoing server first, then creates the account and its credential secret in one transaction); programmatic setups store the per-account connection JSON (host/port/secure/user/password, plus smtpHost/smtpPort for sending) in the account credential secret slot before the first sync. Implements the provider `send`: `sendMailFromAccount` sends over the SMTP server of the mailbox itself (implicit TLS, same login) with the mailbox address as From and stores a copy in its sent folder.
 
 Category: notifications
 

package/dist/db/entity-column-meta.d.ts

@@ -0,0 +1,3 @@
+import type { EntityDefinition, FieldDefinition } from "@cosmicdrift/kumiko-types/fields";
+import type { ColumnMeta } from "./entity-table-meta-types.ts";
+export declare function fieldToColumnMeta(name: string, field: FieldDefinition, entity: EntityDefinition): readonly ColumnMeta[];

package/dist/db/entity-column-meta.js

@@ -0,0 +1,113 @@
+// Field definition → physical ColumnMeta[]. Lock-step twin of COLUMN_EMITTERS
+// in table-builder.ts: every field type must produce the same PG columns there.
+import { toSnakeCase } from "../utils/case.js";
+const EMPTY_JSONB_ARRAY = "'[]'::jsonb";
+const EMPTY_JSONB_OBJECT = "'{}'::jsonb";
+function quoteSql(literal) {
+    return `'${literal.replace(/'/g, "''")}'`;
+}
+function fieldDefaultLiteral(field) {
+    if (!("default" in field) || field.default === undefined)
+        return undefined;
+    const v = field.default;
+    if (typeof v === "string")
+        return quoteSql(v);
+    if (typeof v === "number")
+        return String(v);
+    if (typeof v === "boolean")
+        return v ? "true" : "false";
+    return undefined;
+}
+function declaredDefault(field) {
+    const literal = fieldDefaultLiteral(field);
+    return literal === undefined ? {} : { defaultSql: literal };
+}
+function scalarColumn(snake, pgType, field, extra = {}) {
+    return {
+        name: snake,
+        pgType,
+        notNull: field.required === true,
+        ...extra,
+        ...declaredDefault(field),
+    };
+}
+function requiredColumn(snake, pgType, field) {
+    return [{ name: snake, pgType, notNull: field.required === true }];
+}
+function jsonbColumn(snake, defaultSql) {
+    return [{ name: snake, pgType: "jsonb", notNull: true, defaultSql }];
+}
+// lookupable → HMAC blind-index counterpart. Nullable is mandatory:
+// managedChangeRequiresRecreate would diff a NOT-NULL column without
+// a default on existing tables as DROP+rebuild.
+const textColumnMeta = (snake, field) => {
+    const cols = [scalarColumn(snake, "text", field)];
+    if (field.type === "text" && field.lookupable === true) {
+        cols.push({ name: `${snake}_bidx`, pgType: "text", notNull: false });
+    }
+    return cols;
+};
+const booleanColumnMeta = (snake, field) => {
+    const declared = declaredDefault(field);
+    return [
+        {
+            name: snake,
+            pgType: "boolean",
+            notNull: declared.defaultSql !== undefined || field.required === true,
+            ...declared,
+        },
+    ];
+};
+const referenceColumnMeta = (snake, field) => field.multiple === true
+    ? jsonbColumn(snake, EMPTY_JSONB_ARRAY)
+    : requiredColumn(snake, "uuid", field);
+const moneyColumnMeta = (snake, field, entity) => [
+    { name: snake, pgType: "bigint", notNull: field.required === true, bigintJsMode: "bigint" },
+    {
+        name: `${snake}_currency`,
+        pgType: "text",
+        notNull: true,
+        defaultSql: quoteSql(entity.defaultCurrency ?? "EUR"),
+    },
+];
+const locatedTimestampColumnMeta = (snake, field) => [
+    { name: `${snake}_utc`, pgType: "timestamptz", notNull: field.required === true },
+    { name: `${snake}_tz`, pgType: "text", notNull: field.required === true },
+];
+const COLUMN_META_EMITTERS = {
+    text: textColumnMeta,
+    longText: textColumnMeta,
+    boolean: booleanColumnMeta,
+    select: (snake, field) => [scalarColumn(snake, "text", field)],
+    multiSelect: (snake) => jsonbColumn(snake, EMPTY_JSONB_ARRAY),
+    number: (snake, field) => [
+        scalarColumn(snake, field.integer === true ? "integer" : "double precision", field),
+    ],
+    bigInt: (snake, field) => [scalarColumn(snake, "bigint", field, { bigintJsMode: "number" })],
+    decimal: (snake, field) => [
+        scalarColumn(snake, `numeric(${field.precision},${field.scale})`, field),
+    ],
+    reference: referenceColumnMeta,
+    money: moneyColumnMeta,
+    embedded: (snake, field) => jsonbColumn(snake, field.multiple === true ? EMPTY_JSONB_ARRAY : EMPTY_JSONB_OBJECT),
+    jsonb: (snake) => jsonbColumn(snake, EMPTY_JSONB_OBJECT),
+    // Real PG `date` — Temporal.PlainDate, no time-of-day/timezone component.
+    date: (snake, field) => requiredColumn(snake, "date", field),
+    timestamp: (snake, field) => requiredColumn(snake, "timestamptz", field),
+    tz: (snake, field) => requiredColumn(snake, "text", field),
+    locatedTimestamp: locatedTimestampColumnMeta,
+    file: (snake, field) => requiredColumn(snake, "uuid", field),
+    image: (snake, field) => requiredColumn(snake, "uuid", field),
+    files: (snake) => jsonbColumn(snake, EMPTY_JSONB_ARRAY),
+    images: (snake) => jsonbColumn(snake, EMPTY_JSONB_ARRAY),
+};
+function emitColumnMeta(type, snake, field, entity) {
+    // A type from untyped input must not reach an Object.prototype member.
+    if (!Object.hasOwn(COLUMN_META_EMITTERS, type))
+        return [];
+    const emit = COLUMN_META_EMITTERS[type];
+    return emit(snake, field, entity);
+}
+export function fieldToColumnMeta(name, field, entity) {
+    return emitColumnMeta(field.type, toSnakeCase(name), field, entity);
+}

package/dist/db/entity-table-indexes.d.ts

@@ -0,0 +1,7 @@
+import type { EntityDefinition } from "@cosmicdrift/kumiko-types/fields";
+import { type ColumnHandle, type IndexBuilderWithCols } from "./dialect.ts";
+export declare const SOFT_DELETE_LIVE_ROW_PREDICATE = "\"is_deleted\" = false";
+type ColumnHandles = Readonly<Record<string, ColumnHandle>>;
+type IndexRecord = Record<string, IndexBuilderWithCols>;
+export declare function buildEntityIndexes(tableName: string, entity: EntityDefinition, handles: ColumnHandles, foreignKeyFields: ReadonlySet<string>): IndexRecord;
+export {};

package/dist/db/entity-table-indexes.js

@@ -0,0 +1,124 @@
+// Index set of a buildEntityTable table. Lock-step twin of the index derivation
+// in deriveEntityTableMeta (entity-table-meta.ts): both must name and shape
+// indexes identically.
+import { toSnakeCase } from "../utils/case.js";
+import { index, isSqlExpression, sql, uniqueIndex, } from "./dialect.js";
+// Partial-index predicate for soft-delete entities; table-builder and
+// entity-table-meta must render identical index definitions.
+export const SOFT_DELETE_LIVE_ROW_PREDICATE = `"is_deleted" = false`;
+function definedColumns(handles, keys) {
+    const cols = keys
+        .map((key) => handles[key])
+        .filter((col) => col !== undefined);
+    return cols.length === keys.length ? cols : undefined;
+}
+function foreignKeyIndexEntries(tableName, handles, foreignKeyFields) {
+    const entries = [];
+    for (const fieldName of foreignKeyFields) {
+        const column = handles[fieldName];
+        if (!column)
+            continue;
+        const indexName = `${tableName}_${toSnakeCase(fieldName)}_idx`;
+        entries.push([indexName, index(indexName).on(column)]);
+    }
+    return entries;
+}
+// lookupable fields: index the bidx column.
+function blindIndexEntries(tableName, entity, handles) {
+    const entries = [];
+    for (const [name, field] of Object.entries(entity.fields)) {
+        if (field.type !== "text" || field.lookupable !== true)
+            continue;
+        const column = handles[`${name}Bidx`];
+        if (!column)
+            continue;
+        const indexName = `${tableName}_${toSnakeCase(name)}_bidx_idx`;
+        entries.push([indexName, index(indexName).on(column)]);
+    }
+    return entries;
+}
+function lookupableBidxFieldNames(entity) {
+    const bidxFieldByField = new Map();
+    for (const [name, field] of Object.entries(entity.fields)) {
+        if (field.type === "text" && field.lookupable === true) {
+            bidxFieldByField.set(name, `${name}Bidx`);
+        }
+    }
+    return bidxFieldByField;
+}
+function declaredIndexName(tableName, def) {
+    const suffix = def.unique === true ? "unique" : "idx";
+    return def.name ?? `${tableName}_${def.columns.map((c) => toSnakeCase(c)).join("_")}_${suffix}`;
+}
+function declaredIndexWhere(tableName, indexName, entity, def) {
+    if (def.where !== undefined) {
+        // A silently dropped where would build a full (unique) index that
+        // entity-table-meta flags as needsManualWhere.
+        if (!isSqlExpression(def.where)) {
+            throw new Error(`[${tableName}] index "${indexName}": where must be a sql\`...\` expression`);
+        }
+        return def.where;
+    }
+    // Soft-deleted rows keep their value, so a full unique index would
+    // permanently block reuse; kept in lock-step with entity-table-meta.ts.
+    if (def.unique === true && entity.softDelete === true) {
+        return sql.raw(SOFT_DELETE_LIVE_ROW_PREDICATE);
+    }
+    return undefined;
+}
+// Partial bidx counterpart for unique indexes over lookupable fields.
+function bidxCounterpartEntry(indexName, entity, def, handles, bidxFieldByField) {
+    if (def.unique !== true || def.where !== undefined)
+        return undefined;
+    const bidxFieldNames = def.columns.map((c) => bidxFieldByField.get(c) ?? c);
+    const swapped = bidxFieldNames.filter((c, i) => c !== def.columns[i]);
+    if (swapped.length === 0)
+        return undefined;
+    const bidxCols = definedColumns(handles, bidxFieldNames);
+    if (!bidxCols)
+        return undefined;
+    const notNullParts = swapped.map((c) => `"${toSnakeCase(c)}" IS NOT NULL`);
+    // Soft-deleted rows keep their bidx hash — without this, a restored row
+    // can't reuse a value a soft-deleted sibling still holds.
+    const whereText = (entity.softDelete === true ? [...notNullParts, SOFT_DELETE_LIVE_ROW_PREDICATE] : notNullParts).join(" AND ");
+    const bidxIndexName = `${indexName}_bidx`;
+    return [
+        bidxIndexName,
+        uniqueIndex(bidxIndexName)
+            .on(...bidxCols)
+            .where(sql.raw(whereText)),
+    ];
+}
+// Columns are addressed by field name (camelCase); a def naming an unknown
+// column is skipped.
+function declaredIndexEntries(tableName, entity, handles) {
+    const bidxFieldByField = lookupableBidxFieldNames(entity);
+    return (entity.indexes ?? []).flatMap((def) => {
+        const cols = definedColumns(handles, def.columns);
+        if (!cols)
+            return [];
+        const indexName = declaredIndexName(tableName, def);
+        const builder = def.unique === true ? uniqueIndex(indexName) : index(indexName);
+        const where = declaredIndexWhere(tableName, indexName, entity, def);
+        const chain = builder.on(...cols);
+        const counterpart = bidxCounterpartEntry(indexName, entity, def, handles, bidxFieldByField);
+        return [
+            [indexName, where === undefined ? chain : chain.where(where)],
+            ...(counterpart ? [counterpart] : []),
+        ];
+    });
+}
+// Every multi-tenant query filters by tenant_id; without this index list
+// queries scan the whole table across all tenants.
+export function buildEntityIndexes(tableName, entity, handles, foreignKeyFields) {
+    const tenantIdColumn = handles["tenantId"];
+    if (!tenantIdColumn)
+        throw new Error(`[${tableName}] entity table has no tenantId column`);
+    const tenantIndexName = `${tableName}_tenant_id_idx`;
+    return Object.fromEntries([
+        [tenantIndexName, index(tenantIndexName).on(tenantIdColumn)],
+        ...foreignKeyIndexEntries(tableName, handles, foreignKeyFields),
+        ...blindIndexEntries(tableName, entity, handles),
+        ...declaredIndexEntries(tableName, entity, handles),
+    ]);
+}