@cosmicdrift/kumiko-framework 0.112.0 → 0.113.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.112.0",
+  "version": "0.113.1",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -181,7 +181,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.112.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.113.1",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/api/routes.ts

@@ -90,7 +90,10 @@ export function createApiRoutes(dispatcher: Dispatcher) {
       }
       return c.json(result);
     } catch (e) {
-      return writeErrorResponse(c, toKumiko(e));
+      // 615/1: pass the batch's command types, not undefined — a single
+      // "type" doesn't apply to a batch, but logging none loses the fault
+      // context entirely.
+      return writeErrorResponse(c, toKumiko(e), body.commands?.map((cmd) => cmd.type).join(","));
     }
   });
 

package/src/engine/__tests__/registry.test.ts

@@ -1,6 +1,8 @@
 import { describe, expect, test } from "bun:test";
+import { z } from "zod";
 import { createTenantConfig } from "../config-helpers";
 import { defineFeature } from "../define-feature";
+import { createEntity, createTextField } from "../factories";
 import { createRegistry } from "../registry";
 import type { FeatureDefinition } from "../types/feature";
 
@@ -130,4 +132,30 @@ describe("extensionSelector boot-validation", () => {
       }),
     ).toThrow(/declared twice/);
   });
+
+  // 437/2: createRegistry now delegates this check to
+  // validateExtensionPreSaveWiring (shared with validateBoot's standalone
+  // callers) instead of a duplicate inline computation — pins that
+  // createRegistry itself still enforces it, not just validateBoot.
+  test("throws when extension preSave targets entity with no mapped write handlers", () => {
+    const ext = defineFeature("cap-ext", (r) => {
+      r.extendsRegistrar("credit-cap", {
+        hooks: { preSave: async (changes) => changes },
+      });
+    });
+    const consumer = defineFeature("money-horse", (r) => {
+      r.requires("cap-ext");
+      r.entity("credit", createEntity({ table: "Credits", fields: { name: createTextField() } }));
+      r.writeHandler(
+        "doSomething",
+        z.object({}),
+        async () => ({ isSuccess: true as const, data: {} }),
+        { access: { openToAll: true } },
+      );
+      r.useExtension("credit-cap", "credit");
+    });
+    expect(() => createRegistry([ext, consumer])).toThrow(
+      /no write handler is entity-mapped to "credit"/i,
+    );
+  });
 });

package/src/engine/__tests__/screen.test.ts

@@ -45,6 +45,46 @@ describe("r.screen() — registration", () => {
     expect(feature.screens["product-list"]?.type).toBe("entityList");
   });
 
+  test("stores a projectionList screen bound to an explicit (cross-feature) query", () => {
+    const feature = defineFeature("app", (r) => {
+      r.screen({
+        id: "rent-list",
+        type: "projectionList",
+        query: "ledger:query:schedule:list",
+        columns: [
+          { field: "description", label: "app:col.desc" },
+          {
+            field: "amount",
+            label: "app:col.amount",
+            renderer: { react: { __component: "EuroCell" } },
+          },
+        ],
+      });
+    });
+    const screen = feature.screens["rent-list"];
+    expect(screen?.type).toBe("projectionList");
+    if (screen?.type !== "projectionList") throw new Error("type-narrow failed");
+    expect(screen.query).toBe("ledger:query:schedule:list");
+  });
+
+  test("validateBoot rejects a projectionList with empty columns", () => {
+    const features = [
+      defineFeature("app", (r) => {
+        r.screen({ id: "x", type: "projectionList", query: "app:query:foo:list", columns: [] });
+      }),
+    ];
+    expect(() => validateBoot(features)).toThrow(/empty columns list/i);
+  });
+
+  test("validateBoot rejects a projectionList with an empty query", () => {
+    const features = [
+      defineFeature("app", (r) => {
+        r.screen({ id: "x", type: "projectionList", query: "", columns: ["name"] });
+      }),
+    ];
+    expect(() => validateBoot(features)).toThrow(/empty or non-string query/i);
+  });
+
   test("stores an entityEdit screen with sections + conditional fields", () => {
     const feature = defineFeature("shop", (r) => {
       r.entity("product", productEntity());

package/src/engine/__tests__/soft-delete-cleanup.test.ts

@@ -31,6 +31,9 @@ describe("registry soft-delete auto-wiring", () => {
     const key = registry.getConfigKey(SOFT_DELETE_GRACE_DAYS_KEY);
     expect(key?.type).toBe("number");
     expect(key?.default).toBe(DEFAULT_GRACE_DAYS);
+    // 565/2: min must be 1, not 0 — graceDays: 0 means "hard-delete every
+    // currently soft-deleted row on the next cron run", not "no cleanup".
+    expect(key?.bounds?.min).toBe(1);
   });
 
   test("also injects the system-scope cleanup job (not perTenant)", () => {

package/src/engine/boot-validator/screens-nav.ts

@@ -141,6 +141,27 @@ export function validateScreens(
       continue;
     }
 
+    if (screen.type === "projectionList") {
+      // Query-getrieben, keine Entity → nur query + columns prüfen (die
+      // Column-Felder können nicht gegen eine Entity gecheckt werden; sie
+      // werden zur Render-Zeit gegen die Projection-Rows aufgelöst).
+      if (!screen.query || typeof screen.query !== "string") {
+        throw new Error(
+          `[Feature ${feature.name}] Screen "${screenId}" (projectionList) has empty or non-string query.`,
+        );
+      }
+      if (screen.columns.length === 0) {
+        throw new Error(
+          `[Feature ${feature.name}] Screen "${screenId}" (projectionList) has an empty columns list — ` +
+            `declare at least one column.`,
+        );
+      }
+      for (const col of screen.columns) {
+        validateColumnRendererForm(feature.name, screenId, normalizeListColumn(col));
+      }
+      continue;
+    }
+
     if (screen.type === "configEdit") {
       // configEdit: layout/fields wie actionForm validieren, plus
       // Cross-Check dass jeder qualifizierte Config-Key registriert

package/src/engine/index.ts

@@ -6,7 +6,6 @@ export {
   validateAppCustomScreenWriteQns,
   validateBoot,
 } from "./boot-validator";
-export { validateExtensionPreSaveWiring } from "./boot-validator/entity-handler";
 export { type BuildAppSchemaOptions, buildAppSchema } from "./build-app-schema";
 export type { ConfigFeatureSchema } from "./build-config-feature-schema";
 export {

package/src/engine/registry.ts

@@ -7,6 +7,7 @@ import {
 import { asEntityTableMeta } from "../db/query";
 import { buildEntityTable } from "../db/table-builder";
 import { buildMetricName, validateMetricName } from "../observability";
+import { validateExtensionPreSaveWiring } from "./boot-validator/entity-handler";
 import { type QnType, qualifyEntityName } from "./qualified-name";
 import {
   buildSoftDeleteCleanupJob,
@@ -1051,26 +1052,11 @@ export function createRegistry(features: readonly FeatureDefinition[]): Registry
     }
   }
 
-  // Extension preSave: useExtension on an entity must have at least one mapped write handler.
-  const extensionsWithPreSave = new Set<string>();
-  for (const f of features) {
-    for (const [extName, def] of Object.entries(f.registrarExtensions ?? {})) {
-      if (def.hooks?.preSave) extensionsWithPreSave.add(extName);
-    }
-  }
-  for (const usage of extensionUsages) {
-    if (!extensionsWithPreSave.has(usage.extensionName)) continue;
-    const hasMapped = [...writeHandlerMap.keys()].some(
-      (qn) => handlerEntityMap.get(qn) === usage.entityName,
-    );
-    if (!hasMapped) {
-      throw new Error(
-        `Feature "${usage.featureName}" uses extension "${usage.extensionName}" with preSave on entity "${usage.entityName}" ` +
-          `but no write handler is entity-mapped to "${usage.entityName}". ` +
-          `Use create/update/delete on a matching entity or name the handler "entity:verb".`,
-      );
-    }
-  }
+  // Extension preSave: useExtension on an entity must have at least one mapped
+  // write handler. Shared with validateBoot's standalone callers (437/2) —
+  // schema-cli's `validate` runs validateBoot on raw FEATURES without ever
+  // building a Registry, so this can't live only here.
+  validateExtensionPreSaveWiring(features);
 
   // Validate: all relation targets must reference existing entities
   for (const [entityName, rels] of relationMap) {

package/src/engine/soft-delete-cleanup.ts

@@ -29,7 +29,11 @@ export const softDeleteGraceDaysConfig: ConfigKeyDefinition = {
   default: DEFAULT_GRACE_DAYS,
   scope: "tenant",
   access: { read: ["TenantAdmin", "SystemAdmin"], write: ["SystemAdmin"] },
-  bounds: { min: 0 },
+  // min: 1, not 0 (565/2) — graceDays: 0 doesn't mean "no cleanup", it means
+  // "hard-delete every currently soft-deleted row on the next cron run".
+  // Clamping (not rejecting) keeps the resolve-config-or-param clamp path's
+  // existing silent-below-bound / audited-crossing behavior.
+  bounds: { min: 1 },
 };
 
 export const softDeleteCleanupJob: JobHandlerFn = async (_payload, ctx) => {
@@ -56,7 +60,7 @@ export const softDeleteCleanupJob: JobHandlerFn = async (_payload, ctx) => {
         db,
       )
     : undefined;
-  const graceDays = typeof resolved === "number" && resolved >= 0 ? resolved : DEFAULT_GRACE_DAYS;
+  const graceDays = typeof resolved === "number" && resolved >= 1 ? resolved : DEFAULT_GRACE_DAYS;
   const cutoff = Temporal.Now.instant().subtract({ hours: graceDays * 24 });
 
   for (const proj of registry.getAllProjections().values()) {

package/src/engine/types/fields.ts

@@ -524,7 +524,9 @@ export function isFileField(field: FieldDefinition | undefined): field is AnyFil
 // --- Derived (computed) fields ---
 //
 // A derived field is read-time only: its value is computed from the stored row
-// (and the clock) when a list/detail query runs, never persisted. It lives in
+// (and the clock) when an entityList query runs (676/2 — NOT detail; only the
+// "list" case in entity-handlers.ts calls augmentDerivedFields), never
+// persisted. It lives in
 // `EntityDefinition.derivedFields` — deliberately NOT in `fields`, so it
 // produces no DB column, never enters a write schema, and can't be the target
 // of an entityEdit. A declarative `entityList` can name it like any column and

package/src/engine/types/index.ts

@@ -230,6 +230,7 @@ export type {
   FormatSpec,
   ListColumnSpec,
   PlatformComponent,
+  ProjectionListScreenDefinition,
   RowAction,
   RowActionNavigate,
   RowActionWriteHandler,

package/src/engine/types/screen.ts

@@ -296,6 +296,34 @@ export type EntityListScreenDefinition = {
   readonly access?: AccessRule;
 };
 
+// --- projectionList ---
+
+// Like entityList, but bound to an EXPLICIT query instead of an entity. The
+// list-query is taken verbatim from `query` (a fully qualified QN like
+// "ledger:query:schedule:list") — NOT derived from the screen's own feature —
+// so a screen can render any read-projection, including one owned by a
+// different feature (the entityList feature-local resolution can't). Columns
+// carry their own labels (no entity to derive field-labels from); there is no
+// auto create-navigation (a projection isn't an editable entity list). Row
+// interaction is explicit via `rowActions`. The query must return the same
+// paged envelope as an entity list-query: `{ rows, nextCursor, total? }`.
+export type ProjectionListScreenDefinition = {
+  readonly id: string;
+  readonly type: "projectionList";
+  readonly query: string;
+  readonly columns: readonly ListColumnSpec[];
+  readonly rowRenderer?: PlatformComponent;
+  readonly cardRenderer?: PlatformComponent;
+  readonly rowActions?: readonly RowAction[];
+  readonly toolbarActions?: readonly ToolbarAction[];
+  readonly pagination?: ListPaginationMode;
+  readonly pageSize?: number;
+  readonly defaultSort?: ListSortSpec;
+  readonly searchable?: boolean;
+  readonly slots?: ScreenSlots;
+  readonly access?: AccessRule;
+};
+
 // --- entityEdit ---
 
 // camelCase `readOnly` instead of the spec's lowercase `readonly`: TS's
@@ -526,6 +554,7 @@ export type ScreenSlots = {
 
 export type ScreenDefinition =
   | EntityListScreenDefinition
+  | ProjectionListScreenDefinition
   | EntityEditScreenDefinition
   | ActionFormScreenDefinition
   | ConfigEditScreenDefinition

package/src/event-store/__tests__/row-to-stored-event.test.ts

@@ -48,8 +48,8 @@ describe("toStoredEvent", () => {
   });
 
   test("Feld-Vollständigkeit: das Mapping deckt genau die StoredEvent-Keys ab", () => {
-    // Pin gegen versehentliches Weglassen eines Feldes im Mapping. Muss mit
-    // der StoredEvent-Definition (event-store.ts) synchron bleiben.
+    // Guards required fields staying in sync with StoredEvent (event-store.ts);
+    // optional fields consistently omitted on both sides must be added manually.
     const expectedKeys: ReadonlyArray<keyof StoredEvent> = [
       "id",
       "aggregateId",

package/src/files/__tests__/provider-resolver.test.ts

@@ -0,0 +1,70 @@
+import { describe, expect, mock, test } from "bun:test";
+import type { Registry } from "../../engine/types";
+import { makeFileProviderResolver } from "../provider-resolver";
+import type { FileStorageProvider } from "../types";
+
+const fakeProvider = { name: "fake" } as unknown as FileStorageProvider;
+
+function fakeRegistry(): Registry {
+  return {
+    getExtensionUsages: () => [
+      {
+        entityName: "fake",
+        options: { build: async () => fakeProvider },
+      },
+    ],
+  } as unknown as Registry;
+}
+
+// 698/2: resolveProvider must not re-read config + secrets on every call —
+// the provider is effectively static per tenant for the process lifetime.
+describe("makeFileProviderResolver — per-tenant cache", () => {
+  test("a second resolve for the same tenant reuses the cached build, doesn't call configAccessorFactory again", async () => {
+    const configAccessorFactory = mock(() => async (_key: unknown) => "fake");
+    const resolver = makeFileProviderResolver({
+      registry: fakeRegistry(),
+      _configAccessorFactory: configAccessorFactory,
+      db: {} as never,
+    });
+
+    const first = await resolver("tenant-a" as never);
+    const second = await resolver("tenant-a" as never);
+
+    expect(first).toBe(fakeProvider);
+    expect(second).toBe(fakeProvider);
+    expect(configAccessorFactory).toHaveBeenCalledTimes(1);
+  });
+
+  test("different tenants get independent cache entries", async () => {
+    const configAccessorFactory = mock(() => async (_key: unknown) => "fake");
+    const resolver = makeFileProviderResolver({
+      registry: fakeRegistry(),
+      _configAccessorFactory: configAccessorFactory,
+      db: {} as never,
+    });
+
+    await resolver("tenant-a" as never);
+    await resolver("tenant-b" as never);
+
+    expect(configAccessorFactory).toHaveBeenCalledTimes(2);
+  });
+
+  test("a rejected build is evicted — the next call retries instead of staying poisoned", async () => {
+    let calls = 0;
+    const resolver = makeFileProviderResolver({
+      registry: {
+        getExtensionUsages: () => {
+          calls++;
+          if (calls === 1) throw new Error("transient failure");
+          return [{ entityName: "fake", options: { build: async () => fakeProvider } }];
+        },
+      } as unknown as Registry,
+      _configAccessorFactory: () => async (_key: unknown) => "fake",
+      db: {} as never,
+    });
+
+    await expect(resolver("tenant-a" as never)).rejects.toThrow("transient failure");
+    const second = await resolver("tenant-a" as never);
+    expect(second).toBe(fakeProvider);
+  });
+});

package/src/files/provider-resolver.ts

@@ -138,21 +138,34 @@ export type FileProviderResolverDeps = {
 // SYSTEM identity: provider construction is an infra read, distinct from the
 // request user's authorization which stays at the route accessGuard.
 export function makeFileProviderResolver(deps: FileProviderResolverDeps): FileProviderResolver {
-  return async (tenantId) => {
-    if (!deps.registry || !deps._configAccessorFactory || !deps.db) {
-      throw new Error(
-        "makeFileProviderResolver: registry/_configAccessorFactory/db missing — " +
-          "mount the config + file-foundation features and wire context.db",
+  // Per-tenant cache (698/2) — without it, every resolveProvider(tenantId)
+  // call re-reads config + secrets from the DB, even though the provider is
+  // effectively static per tenant for the process lifetime. A rejected
+  // promise is evicted so a transient failure (or a secret genuinely not
+  // configured yet) doesn't permanently poison this tenant's entry.
+  const cache = new Map<string, Promise<FileStorageProvider>>();
+  return (tenantId) => {
+    const cached = cache.get(tenantId);
+    if (cached) return cached;
+    const built = (async () => {
+      if (!deps.registry || !deps._configAccessorFactory || !deps.db) {
+        throw new Error(
+          "makeFileProviderResolver: registry/_configAccessorFactory/db missing — " +
+            "mount the config + file-foundation features and wire context.db",
+        );
+      }
+      const config = deps._configAccessorFactory({
+        user: { id: SYSTEM_USER_ID, tenantId },
+        db: deps.db,
+        secrets: deps.secrets,
+      });
+      return createFileProviderForTenant(
+        { config, registry: deps.registry, secrets: deps.secrets, _userId: SYSTEM_USER_ID },
+        tenantId,
       );
-    }
-    const config = deps._configAccessorFactory({
-      user: { id: SYSTEM_USER_ID, tenantId },
-      db: deps.db,
-      secrets: deps.secrets,
-    });
-    return createFileProviderForTenant(
-      { config, registry: deps.registry, secrets: deps.secrets, _userId: SYSTEM_USER_ID },
-      tenantId,
-    );
+    })();
+    built.catch(() => cache.delete(tenantId));
+    cache.set(tenantId, built);
+    return built;
   };
 }

package/src/i18n/required-surface-keys.ts

@@ -5,6 +5,7 @@ import type {
   EntityListScreenDefinition,
   FeatureDefinition,
   NavDefinition,
+  ProjectionListScreenDefinition,
   RowAction,
   ScreenDefinition,
   ToolbarAction,
@@ -76,6 +77,17 @@ export function requiredKeysFromScreen(
       for (const action of list.toolbarActions ?? []) pushToolbarActionKeys(out, action);
       break;
     }
+    case "projectionList": {
+      const list = screen as ProjectionListScreenDefinition;
+      // Keine Entity → keine field-label-Fallbacks; nur explizite Column-Labels.
+      for (const col of list.columns) {
+        const normalized = normalizeListColumn(col);
+        if (normalized.label !== undefined) pushKey(out, normalized.label);
+      }
+      for (const action of list.rowActions ?? []) pushRowActionKeys(out, action);
+      for (const action of list.toolbarActions ?? []) pushToolbarActionKeys(out, action);
+      break;
+    }
     case "entityEdit": {
       const edit = screen as EntityEditScreenDefinition;
       pushKey(out, edit.submitLabel);

package/src/pipeline/projection-rebuild.ts

@@ -306,6 +306,18 @@ export async function rebuildProjection(
           while ((await drainBatch(tx)) === REBUILD_BATCH_SIZE) {
             // re-replay the full log into the fresh shadow
           }
+          // 656/2: drainBatch increments eventsProcessed for every drained row
+          // regardless of quarantine (skipApplyErrors), so this must hold
+          // exactly under the fence — a mismatch means drainBatch silently
+          // dropped a row instead of counting it, which the rest of this
+          // function has no other way to detect.
+          if (eventsProcessed < Number(expectedEvents)) {
+            throw new Error(
+              `projection-rebuild "${projectionName}": fenced re-replay processed ` +
+                `${eventsProcessed} events but ${expectedEvents} were expected — drainBatch ` +
+                "silently dropped rows instead of counting them.",
+            );
+          }
         }
       }
 

package/src/testing/e2e-generator.ts

@@ -112,6 +112,9 @@ export function generateE2ESpec(
     // pro Field geschrieben, ohne CRUD-Zustand zu generieren wäre der
     // Spec wertlos. Branding/SMTP/etc. sind Author-spezifisch.
     if (screen.type === "configEdit") continue;
+    // projectionList: query-getrieben, Author-spezifische Projection —
+    // kein generischer CRUD-Spec ableitbar (wie actionForm/configEdit).
+    if (screen.type === "projectionList") continue;
     const { scope: feature, name: short } = parseQn(screenQn);
     const urlPath = `/t/${tenant}/${feature}/${short}`;
     const title = `${feature}/${short}`;

package/src/time/__tests__/tz-dateline.test.ts

@@ -1,9 +1,7 @@
-// Pacific/Apia (Samoa) liegt weit östlich der Datumsgrenze bei UTC+13/+14 —
-// eine Vormittags-Wall-Clock dort fällt in UTC auf den VORHERIGEN Kalendertag.
-// Das Plan-Doc (timezones.md) nennt Apia explizit als Datumsgrenzen-Edge-Case
-// der TZ-Matrix. Als Datums-Ordnungs-Eigenschaft formuliert, damit der Test
-// unabhängig von der DST-Sicht der tzdata grün bleibt (UTC+13 wie +14 schieben
-// 10:00 auf den Vortag).
+// Pacific/Apia sits far east of the dateline at UTC+13/+14 — a morning wall
+// clock there falls on the PREVIOUS UTC calendar day. Phrased as a date-
+// ordering property (not a fixed offset) so the test stays green regardless
+// of the tzdata DST view (UTC+13 and +14 both push 10:00 to the prior day).
 
 import { beforeAll, describe, expect, test } from "bun:test";
 import { ensureTemporalPolyfill } from "../polyfill";
@@ -13,8 +11,8 @@ beforeAll(async () => {
   await ensureTemporalPolyfill();
 });
 
-describe("ctx.tz — Pacific/Apia Datumsgrenze", () => {
-  test("Vormittags-Wall-Clock in Apia mappt auf den vorherigen UTC-Kalendertag", () => {
+describe("ctx.tz — Pacific/Apia dateline", () => {
+  test("a morning wall clock in Apia maps to the previous UTC calendar day", () => {
     const tz = createTzContext();
     const zdt = tz.parse("2026-01-15T10:00:00", "Pacific/Apia");
     expect(zdt.timeZoneId).toBe("Pacific/Apia");
@@ -22,11 +20,11 @@ describe("ctx.tz — Pacific/Apia Datumsgrenze", () => {
     const utcDate = zdt.toInstant().toZonedDateTimeISO("UTC").toPlainDate().toString();
     expect(utcDate).toBe("2026-01-14");
 
-    // Offset ist ein großer positiver Wert (UTC+13 oder +14).
+    // Offset is a large positive value (UTC+13 or +14).
     expect(zdt.offsetNanoseconds).toBeGreaterThan(12 * 3600 * 1e9);
   });
 
-  test("Round-Trip bewahrt Wall-Clock + Instant über die Datumsgrenze", () => {
+  test("round-trip preserves wall clock + instant across the dateline", () => {
     const tz = createTzContext();
     const original = tz.parse("2026-01-15T10:00:00", "Pacific/Apia");
     const restored = tz.fromLocatedJson(tz.toLocatedJson(original));

package/src/ui-types/index.ts

@@ -57,6 +57,7 @@ export type {
   FieldRenderer,
   ListColumnSpec,
   PlatformComponent,
+  ProjectionListScreenDefinition,
   RowAction,
   RowActionNavigate,
   RowActionWriteHandler,