@cosmicdrift/kumiko-framework 0.291.0 → 0.292.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.291.0",
+  "version": "0.292.0",
   "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>",
@@ -198,8 +198,8 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-http": "0.291.0",
-    "@cosmicdrift/kumiko-types": "0.291.0",
+    "@cosmicdrift/kumiko-http": "0.292.0",
+    "@cosmicdrift/kumiko-types": "0.292.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.13.1",
@@ -215,7 +215,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.291.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.292.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/changes.json

@@ -1,4 +1,16 @@
 [
+  {
+    "version": "0.292.0",
+    "type": "fix",
+    "title": "Validate changeset folding in PR CI",
+    "detail": "The release-time `changes fold` now also runs as a dry run on every PR, so a changeset with an unresolvable feature fails its own PR instead of the next release."
+  },
+  {
+    "version": "0.292.0",
+    "type": "improvement",
+    "title": "A projectionList can declare a time-range filter",
+    "detail": "A list bound to a query that already accepts time bounds had no way to expose them: `ListFacetSpec` knew `select`, `boolean` and `reference`, so every list with a timestamp — which, through `createdAt`, is practically every list — could be searched but not narrowed to \"the week the incident happened\". The audit log shipped a `description` promising date filters that no control backed.\n`{ type: \"dateRange\", field, label, params: { from, to } }` closes that. The renderer maps it to two native `<input type=\"date\">` next to the facet dropdowns (no date dependency; the browser supplies the calendar, the locale and the keyboard handling) and sends the picked bounds as the two query params the facet names — explicit rather than a `from`/`to` convention, since a query is free to call them anything, and checked against the handler's Zod schema at boot. Filtering stays server-side; either bound alone is a valid open interval; changing the range resets the page like every other facet; an inverted range is clamped in the UI instead of reaching the handler's `from <= to` refine.\nA calendar date covers a whole day in the viewer's time zone: \"to the 14th\" includes everything through the last instant of the 14th, computed across DST boundaries rather than by adding 24 hours. `audit:screen:audit-log` now declares the facet on `createdAt`, so its description holds."
+  },
   {
     "version": "0.291.0",
     "type": "breaking",

package/src/engine/__tests__/boot-validator-projection-list.test.ts

@@ -443,6 +443,99 @@ describe("validateBoot — projectionList screens", () => {
       expect(() => validateBoot([feature])).not.toThrow();
     });
 
+    // fw#3104: a dateRange facet sends its two bounds as the top-level params
+    // it names, so `filters` is the wrong thing to require — the declared
+    // param names are.
+    test("a dateRange facet on a query that can't narrow by time is rejected at boot", () => {
+      const feature = defineFeature("ledger", (r) => {
+        r.queryHandler(
+          "schedule:list",
+          z.object({ from: z.iso.datetime().optional() }),
+          async () => ({ rows: [], nextCursor: null }),
+          { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
+        );
+        r.screen({
+          id: "schedule-list",
+          type: "projectionList",
+          query: "ledger:query:schedule:list",
+          columns: ["dueAt"],
+          facets: [
+            {
+              field: "dueAt",
+              type: "dateRange",
+              label: "Due",
+              params: { from: "from", to: "to" },
+            },
+          ],
+        });
+        r.translations({
+          keys: { "screen:schedule-list.title": { de: "Liste", en: "List" } },
+        });
+      });
+      expect(() => validateBoot([feature])).toThrow(/no "to" parameter/);
+    });
+
+    test('a dateRange facet does NOT require a "filters" parameter', () => {
+      const feature = defineFeature("ledger", (r) => {
+        r.queryHandler(
+          "schedule:list",
+          z.object({
+            since: z.iso.datetime().optional(),
+            until: z.iso.datetime().optional(),
+          }),
+          async () => ({ rows: [], nextCursor: null }),
+          { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
+        );
+        r.screen({
+          id: "schedule-list",
+          type: "projectionList",
+          query: "ledger:query:schedule:list",
+          columns: ["dueAt"],
+          facets: [
+            {
+              field: "dueAt",
+              type: "dateRange",
+              label: "Due",
+              params: { from: "since", to: "until" },
+            },
+          ],
+        });
+        r.translations({
+          keys: { "screen:schedule-list.title": { de: "Liste", en: "List" } },
+        });
+      });
+      expect(() => validateBoot([feature])).not.toThrow();
+    });
+
+    test("a dateRange facet naming a reserved list-payload key is rejected", () => {
+      const feature = defineFeature("ledger", (r) => {
+        r.queryHandler(
+          "schedule:list",
+          z.object({ limit: z.number().optional(), to: z.iso.datetime().optional() }),
+          async () => ({ rows: [], nextCursor: null }),
+          { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
+        );
+        r.screen({
+          id: "schedule-list",
+          type: "projectionList",
+          query: "ledger:query:schedule:list",
+          columns: ["dueAt"],
+          facets: [
+            {
+              field: "dueAt",
+              type: "dateRange",
+              label: "Due",
+              params: { from: "limit", to: "to" },
+            },
+          ],
+        });
+        r.translations({
+          keys: { "screen:schedule-list.title": { de: "Liste", en: "List" } },
+        });
+      });
+      expect(() => validateBoot([feature])).toThrow(/reserved list-payload key/);
+    });
+
     test("a reference facet targeting an unknown entity is rejected", () => {
       const feature = defineFeature("ledger", (r) => {
         r.queryHandler(

package/src/engine/boot-validator/index.ts

@@ -1,5 +1,6 @@
 import { validateEntityFieldEncryptionAvailable } from "../../db/entity-field-encryption";
 import { dedupeFeatures } from "../dedupe-features";
+import { FILE_STORAGE_PROVIDER_ENV } from "../extension-names";
 import { QnTypes, qualifyEntityName } from "../qualified-name";
 import type { FeatureDefinition } from "../types";
 import { validateAccessDeclarations } from "./access-declarations";
@@ -278,9 +279,9 @@ export function validateBoot(
     validateEntityFieldEncryptionAvailable();
   }
 
-  if (hasFileFields && !process.env["FILE_STORAGE_PROVIDER"]) {
+  if (hasFileFields && !process.env[FILE_STORAGE_PROVIDER_ENV]) {
     throw new Error(
-      "FILE_STORAGE_PROVIDER environment variable is required (file/image fields in use)",
+      `${FILE_STORAGE_PROVIDER_ENV} environment variable is required (file/image fields in use)`,
     );
   }
 

package/src/engine/boot-validator/projection-list-screens.ts

@@ -105,13 +105,63 @@ function validateProjectionListFilterSchemaAcceptance(
 // (fw#2165): definePagedQueryHandler doesn't auto-merge params into the
 // handler's own Zod schema, so a declared facet would 422 on every query
 // unless the author added `filters` themselves.
+// A dateRange facet (fw#3104) sends its two bounds as the top-level payload
+// keys it names in `params`, not as a `filters` entry — so the query has to
+// accept exactly those keys. Catches the facet pointed at a field the query
+// can't narrow by, which would otherwise 422 on the first date the user picks.
+// Keys buildListQueryPayload owns — a facet param naming one of them would
+// silently replace the list's own paging/sorting on every pick.
+const RESERVED_LIST_PAYLOAD_KEYS: ReadonlySet<string> = new Set([
+  "limit",
+  "search",
+  "sort",
+  "sortDirection",
+  "offset",
+  "totalCount",
+  "cursor",
+  "filter",
+  "filters",
+]);
+
+function validateProjectionListDateRangeFacets(
+  prefix: string,
+  screen: ProjectionListScreenDefinition,
+  schema: QueryHandlerDef["schema"] | undefined,
+): void {
+  for (const facet of screen.facets ?? []) {
+    if (facet.type !== "dateRange") continue;
+    if (facet.params.from === facet.params.to) {
+      throw new Error(
+        `${prefix}: dateRange facet on "${facet.field}" names the same param ` +
+          `"${facet.params.from}" for both bounds.`,
+      );
+    }
+    for (const param of [facet.params.from, facet.params.to]) {
+      if (RESERVED_LIST_PAYLOAD_KEYS.has(param)) {
+        throw new Error(
+          `${prefix}: dateRange facet on "${facet.field}" names "${param}" as a bound, ` +
+            `which is a reserved list-payload key — pick the query's own time-bound param names.`,
+        );
+      }
+      if (schemaAccepts(schema, param)) continue;
+      throw new Error(
+        `${prefix}: dateRange facet on "${facet.field}" sends "${param}" but query ` +
+          `"${screen.query}" has no "${param}" parameter in its Zod schema — add ` +
+          `${param}: z.iso.datetime().optional() to the handler's schema, or point ` +
+          `params at the keys it already accepts.`,
+      );
+    }
+  }
+}
+
 function validateProjectionListFacetsSchemaAcceptance(
   prefix: string,
   screen: ProjectionListScreenDefinition,
   schema: QueryHandlerDef["schema"] | undefined,
 ): void {
-  // skip: no facets declared — nothing to reject.
-  if (screen.facets === undefined || screen.facets.length === 0) return;
+  validateProjectionListDateRangeFacets(prefix, screen, schema);
+  // skip: no facets that travel via `filters` — nothing to reject.
+  if (screen.facets === undefined || !screen.facets.some((f) => f.type !== "dateRange")) return;
   // skip: the schema already accepts filters — nothing to reject.
   if (schemaAccepts(schema, "filters")) return;
   throw new Error(

package/src/engine/extension-names.ts

@@ -87,6 +87,16 @@ export const EXT_FILE_PROVIDER = "fileProvider" as const;
 // des file-foundation-Features MUSS diese Konstante mitziehen.
 export const FILE_PROVIDER_CONFIG_KEY = "file-foundation:config:provider" as const;
 
+// Two roles: boot gate (validateBoot requires its presence once file/image
+// fields are in use) AND the ENV source of the config key above, bridged via
+// keyDef.env. Tenant rows keep overriding the bridged value.
+export const FILE_STORAGE_PROVIDER_ENV = "FILE_STORAGE_PROVIDER" as const;
+
+// Presence placeholder runDevApp writes when an explicitly wired provider
+// (options.files) already satisfies the boot gate. It names no plugin, so
+// provider resolution treats it like an unset key.
+export const FILE_STORAGE_PROVIDER_BOOT_SENTINEL = "configured" as const;
+
 /**
  * `derivativeRenderer` — File-Derivative-Renderer-Plugin-Selection
  * (file-derivatives).

package/src/engine/index.ts

@@ -113,6 +113,8 @@ export {
   EXT_USER_DATA,
   EXT_USER_DATA_ORDER,
   FILE_PROVIDER_CONFIG_KEY,
+  FILE_STORAGE_PROVIDER_BOOT_SENTINEL,
+  FILE_STORAGE_PROVIDER_ENV,
   TENANT_MEMBERSHIPS_QUERY,
 } from "./extension-names";
 export { extensionUsageEscapeHatchReason } from "./extensions/escape-hatch-usage";

package/src/engine/system-user.ts

@@ -1,10 +1,8 @@
 import type { SessionUser } from "./types";
-import type { TenantId } from "./types/identifiers";
+import { SYSTEM_USER_ID, type TenantId } from "./types/identifiers";
+
+export { SYSTEM_USER_ID };
 
-// Stringified so it round-trips through SessionUser.id (string UUID-shape).
-// Not a real UUID — SYSTEM acts as an alias for "no human caller" and event-
-// store createdBy is text, so the literal suffices.
-export const SYSTEM_USER_ID = "00000000-0000-0000-0000-000000000000";
 export const SYSTEM_ROLE = "system" as const;
 
 // extraRoles: hasAccess kennt keinen System-Bypass — Handler gaten auf

package/src/files/provider-resolver.ts

@@ -15,7 +15,11 @@
 import type { FileProviderResolver } from "@cosmicdrift/kumiko-types/file-provider-resolver-types";
 import type { DbConnection } from "../db/connection";
 import type { TenantDb } from "../db/tenant-db";
-import { EXT_FILE_PROVIDER, FILE_PROVIDER_CONFIG_KEY } from "../engine/extension-names";
+import {
+  EXT_FILE_PROVIDER,
+  FILE_PROVIDER_CONFIG_KEY,
+  FILE_STORAGE_PROVIDER_BOOT_SENTINEL,
+} from "../engine/extension-names";
 import { SYSTEM_USER_ID } from "../engine/system-user";
 import type { ConfigAccessor, ConfigAccessorFactory, Registry } from "../engine/types";
 import type { SecretsContext } from "../secrets";
@@ -93,7 +97,10 @@ export async function createFileProviderForTenant(
 
   const raw = await ctxConfig(FILE_PROVIDER_CONFIG_KEY);
   const provider = typeof raw === "string" ? raw : raw == null ? "" : String(raw);
-  if (provider.length === 0) {
+  // The boot-gate placeholder names no plugin: treated as a provider name it
+  // would let FILE_STORAGE_PROVIDER=configured fake a selection through the
+  // ENV bridge.
+  if (provider.length === 0 || provider === FILE_STORAGE_PROVIDER_BOOT_SENTINEL) {
     const usages = ctx.registry.getExtensionUsages(EXT_FILE_PROVIDER);
     const known = usages.map((u) => u.entityName).join(", ") || "<none>";
     throw new Error(

package/src/ui-types/list-row-meta.ts

@@ -12,7 +12,7 @@
 // deletedById) — this is also the SAME set the boot-validator's entityList
 // column checks accept, so a softDelete column stays a boot-time error
 // instead of a renderer-side throw (see screens.ts / entity-list-screens.ts).
-import { SYSTEM_TENANT_ID } from "../engine/types/identifiers";
+import { SYSTEM_TENANT_ID, SYSTEM_USER_ID } from "../engine/types/identifiers";
 
 export type ListRowMetaColumnType = "text" | "number" | "timestamp";
 
@@ -56,4 +56,7 @@ export type SystemReferenceLabel = {
 // entity, not just delivery-log (fw#2662).
 export const SYSTEM_REFERENCE_LABELS: Readonly<Record<string, SystemReferenceLabel>> = {
   "tenant:tenant": { id: SYSTEM_TENANT_ID, labelKey: "kumiko.reference.system-tenant" },
+  // createdBy on a system write (fw#3103) — SYSTEM_USER_ID is an alias for
+  // "no human caller", so read_users never holds a matching row.
+  "user:user": { id: SYSTEM_USER_ID, labelKey: "kumiko.reference.system-user" },
 };