@cosmicdrift/kumiko-framework 0.65.0 → 0.67.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.65.0",
+  "version": "0.67.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>",
@@ -181,7 +181,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.65.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.66.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/db/__tests__/event-store-executor-list.integration.test.ts

@@ -256,6 +256,71 @@ describe("event-store-executor.list — filter (Tier 2.7c)", () => {
     expect(res.rows).toHaveLength(4);
     expect(res.total).toBe(4);
   });
+
+  test("filters[] AND: zwei dynamische Filter werden mit AND verknüpft", async () => {
+    await seed(10);
+    const res = await exec.list(
+      {
+        limit: 50,
+        sort: "rank",
+        sortDirection: "asc",
+        filters: [
+          { field: "rank", op: "gt", value: 2 },
+          { field: "rank", op: "lt", value: 6 },
+        ],
+      },
+      admin,
+      tdb,
+    );
+    expect(res.rows.map((r) => r["rank"])).toEqual([3, 4, 5]);
+  });
+
+  test("filters[] in: Faceted-Multi-Select rank in [2,4,8]", async () => {
+    await seed(10);
+    const res = await exec.list(
+      {
+        limit: 50,
+        sort: "rank",
+        sortDirection: "asc",
+        filters: [{ field: "rank", op: "in", value: [2, 4, 8] }],
+      },
+      admin,
+      tdb,
+    );
+    expect(res.rows.map((r) => r["rank"])).toEqual([2, 4, 8]);
+  });
+
+  test("statischer filter + dynamische filters[] kombinieren mit AND", async () => {
+    await seed(10);
+    const res = await exec.list(
+      {
+        limit: 50,
+        sort: "rank",
+        sortDirection: "asc",
+        filter: { field: "rank", op: "gt", value: 2 },
+        filters: [{ field: "rank", op: "in", value: [1, 3, 5, 9] }],
+      },
+      admin,
+      tdb,
+    );
+    // gt:2 AND in[1,3,5,9] → 3,5,9 (1 fällt durch gt:2 raus)
+    expect(res.rows.map((r) => r["rank"])).toEqual([3, 5, 9]);
+  });
+
+  test("filters[] mit leerem in-Array: leeres Resultat (kein Match-All)", async () => {
+    await seed(5);
+    const res = await exec.list(
+      {
+        limit: 50,
+        sort: "rank",
+        sortDirection: "asc",
+        filters: [{ field: "rank", op: "in", value: [] }],
+      },
+      admin,
+      tdb,
+    );
+    expect(res.rows).toHaveLength(0);
+  });
 });
 
 describe("event-store-executor.list — runtime SearchAdapter (Tier 2.7e Audit-Fix #1)", () => {

package/src/db/event-store-executor.ts

@@ -200,6 +200,15 @@ export type EventStoreExecutor = {
             readonly value: unknown;
           }
         | undefined;
+      // User-gewählte Faceted-Filter (dynamisch, additiv zum statischen
+      // `filter`). Alle werden mit AND verknüpft.
+      filters?:
+        | ReadonlyArray<{
+            readonly field: string;
+            readonly op: "eq" | "ne" | "lt" | "gt" | "in";
+            readonly value: unknown;
+          }>
+        | undefined;
     },
     user: SessionUser,
     db: TenantDb,
@@ -875,45 +884,49 @@ export function createEventStoreExecutor(
         whereSql.push(shifted.sqlText);
         for (const p of shifted.params) params.push(p);
       }
-      if (payload.filter !== undefined) {
-        const col = table[payload.filter.field];
-        if (col !== undefined) {
-          const screen = buildFilterWhere(
-            payload.filter.field,
-            payload.filter.op,
-            payload.filter.value,
-          );
-          if (screen === null) {
-            whereSql.push("FALSE");
-          } else {
-            for (const [field, value] of Object.entries(screen)) {
-              if (Array.isArray(value)) {
-                const placeholders = value.map((v) => {
-                  params.push(v);
-                  return `$${params.length}`;
-                });
-                whereSql.push(`${colSql(field)} IN (${placeholders.join(", ")})`);
-              } else if (typeof value === "object" && value !== null) {
-                const opMap: Record<string, string> = {
-                  gt: ">",
-                  gte: ">=",
-                  lt: "<",
-                  lte: "<=",
-                  ne: "<>",
-                };
-                for (const [opKey, opSym] of Object.entries(opMap)) {
-                  if (!(opKey in value)) continue;
-                  params.push((value as Record<string, unknown>)[opKey]);
-                  whereSql.push(`${colSql(field)} ${opSym} $${params.length}`);
-                }
-              } else {
-                params.push(value);
-                whereSql.push(`${colSql(field)} = $${params.length}`);
-              }
+      const applyFilter = (f: {
+        readonly field: string;
+        readonly op: "eq" | "ne" | "lt" | "gt" | "in";
+        readonly value: unknown;
+      }): void => {
+        if (table[f.field] === undefined) {
+          // skip: unknown field — not a real column, drop the filter (injection guard)
+          return;
+        }
+        const screen = buildFilterWhere(f.field, f.op, f.value);
+        if (screen === null) {
+          whereSql.push("FALSE");
+          // skip: filter is unsatisfiable → emit FALSE, no params to bind
+          return;
+        }
+        for (const [field, value] of Object.entries(screen)) {
+          if (Array.isArray(value)) {
+            const placeholders = value.map((v) => {
+              params.push(v);
+              return `$${params.length}`;
+            });
+            whereSql.push(`${colSql(field)} IN (${placeholders.join(", ")})`);
+          } else if (typeof value === "object" && value !== null) {
+            const opMap: Record<string, string> = {
+              gt: ">",
+              gte: ">=",
+              lt: "<",
+              lte: "<=",
+              ne: "<>",
+            };
+            for (const [opKey, opSym] of Object.entries(opMap)) {
+              if (!(opKey in value)) continue;
+              params.push((value as Record<string, unknown>)[opKey]);
+              whereSql.push(`${colSql(field)} ${opSym} $${params.length}`);
             }
+          } else {
+            params.push(value);
+            whereSql.push(`${colSql(field)} = $${params.length}`);
           }
         }
-      }
+      };
+      if (payload.filter !== undefined) applyFilter(payload.filter);
+      if (payload.filters !== undefined) for (const f of payload.filters) applyFilter(f);
 
       const orderByClause =
         payload.sort && table[payload.sort]

package/src/engine/__tests__/build-app-schema.test.ts

@@ -134,6 +134,27 @@ describe("buildAppSchema", () => {
     expect(fields["label"]?.["default"]).toBe("");
   });
 
+  test("filterable kommt ins Client-Schema (steuert die Faceted-Filter)", () => {
+    const entity = {
+      fields: {
+        status: { type: "select", options: ["draft", "published"], filterable: true },
+        name: { type: "text" },
+      },
+    } as unknown as EntityDefinition;
+    const f = defineFeature("ent", (r) => {
+      r.entity("thing", entity);
+    });
+    const app = buildAppSchema(createRegistry([f]));
+    const fields = (
+      app.features[0]?.entities["thing"] as unknown as {
+        fields: Record<string, Record<string, unknown>>;
+      }
+    ).fields;
+    expect(fields["status"]?.["filterable"]).toBe(true);
+    // Felder ohne filterable tragen den Key nicht (kein false-Müll).
+    expect(fields["name"]?.["filterable"]).toBeUndefined();
+  });
+
   test("AppSchema ist via JSON.stringify roundtrip-sicher", () => {
     // Echter Smoke-Test des Vertrags — wenn jemand in den project-
     // Helper eine Function reinschmuggelt, würde das hier brennen.

package/src/engine/build-app-schema.ts

@@ -311,6 +311,9 @@ function projectField(fieldDef: FieldDefinition): FieldDefinition {
   if (typeof def["type"] === "string") out["type"] = def["type"];
   if (typeof def["required"] === "boolean") out["required"] = def["required"];
   if (typeof def["sortable"] === "boolean") out["sortable"] = def["sortable"];
+  // filterable steuert die Faceted-Filter-Dropdowns im Renderer (select/
+  // boolean) — muss daher ins Client-Schema.
+  if (typeof def["filterable"] === "boolean") out["filterable"] = def["filterable"];
   if (isLiteral(def["default"])) out["default"] = def["default"];
   // Select: options-Liste ist plain JSON, durchschicken.
   if (Array.isArray(def["options"])) out["options"] = def["options"];

package/src/engine/entity-handlers.ts

@@ -95,6 +95,17 @@ const listSchema = z.object({
       value: z.unknown(),
     })
     .optional(),
+  // User-gewählte Faceted-Filter (dynamisch). Additiv zum statischen
+  // `filter` — executor.list verknüpft alle mit AND.
+  filters: z
+    .array(
+      z.object({
+        field: z.string(),
+        op: z.enum(["eq", "ne", "lt", "gt", "in"]),
+        value: z.unknown(),
+      }),
+    )
+    .optional(),
 });
 
 function parseHandlerName<TVerb extends string>(

package/src/engine/index.ts

@@ -204,6 +204,7 @@ export {
   findTierResolverUsage,
   TENANT_TIER_RESOLVER_EXT,
   type TierResolverPlugin,
+  type TrialGate,
 } from "./tier-resolver-extension";
 // Types
 export type {

package/src/engine/tier-resolver-extension.ts

@@ -41,12 +41,29 @@ export const TENANT_TIER_RESOLVER_EXT = "tenantTierResolver";
  * **System-context convention:** call mit SYSTEM_TENANT_ID erwartet die union
  * aller tier-features (siehe DispatcherOptions.effectiveFeatures doc-block).
  */
-export type EffectiveFeaturesResolver = (tenantId: TenantId) => ReadonlySet<string>;
+export type EffectiveFeaturesResolver = ((tenantId: TenantId) => ReadonlySet<string>) & {
+  /**
+   * Optionaler Live-Trial-Gate, vom dispatcher-feature-gate NUR konsultiert
+   * wenn der synchrone Resolver ein Feature als disabled meldet. Liest das
+   * Signup-Datum des Tenants live (tenant.inserted_at) und returnt true wenn
+   * der Tenant im Trial-Fenster ist UND das Feature zum Trial-Tier gehört.
+   * Async + nicht im Boot-Cache, weil der Trial zeit-abgeleitet ist (ändert
+   * sich zwischen Requests). Nur die 2 Gate-Aufrufstellen awaiten ihn; der
+   * synchrone Hot-Path (ctx.hasFeature, Feature-Set) bleibt unberührt.
+   */
+  readonly trialGate?: TrialGate;
+};
+
+/**
+ * Live-Trial-Gate-Shape. Siehe EffectiveFeaturesResolver.trialGate.
+ */
+export type TrialGate = (tenantId: TenantId, featureName: string) => Promise<boolean>;
 
 /**
  * Plugin-shape für tier-resolver-extension. Plugins implementieren `build`
  * als boot-time factory: kriegen `db` + `registry` (post-stack-setup),
- * laden initial cache aus DB, returnen den synchronen resolver-callback.
+ * laden initial cache aus DB, returnen den synchronen resolver-callback
+ * (optional mit angehängtem `trialGate`).
  */
 export type TierResolverPlugin = {
   readonly build: (deps: {

package/src/engine/types/nav.ts

@@ -1,4 +1,6 @@
 import type { AccessRule } from "./handlers";
+import type { TargetRef } from "./target-ref";
+import type { TreeAction } from "./tree-node";
 
 // Nav entry declaration. Every feature that wants to appear in the app's
 // navigation tree registers one or more entries via r.nav(). The engine
@@ -34,6 +36,21 @@ export type NavDefinition = {
   // ("<feature>:screen:<id>"). Omit for pure grouping entries (a parent-only
   // nav node that renders a sub-tree but has no target screen itself).
   readonly screen?: string;
+  // Polymorphes Klick-Ziel (öffnet die EditorPanel-Maske via Target-
+  // Resolver) — Alternative zu `screen`. Ein Knoten trägt screen XOR
+  // target; der Renderer dispatcht das target statt einen Route-Link zu
+  // rendern. Gespiegelt aus dem alten Visual-Tree (TreeNode.target).
+  readonly target?: TargetRef;
+  // Hover-Actions rechts in der Zeile (VS-Code-Pattern) — erst bei Hover
+  // sichtbar. Reihenfolge wie deklariert.
+  readonly actions?: readonly TreeAction[];
+  // „+"-Affordance am Knoten. Klick dispatcht createAction.target; der
+  // Provider weiß was „leer befüllen" für ihn heißt (neuer Page-Slug etc.).
+  readonly createAction?: TreeAction;
+  // Children kommen zur Laufzeit aus einem registrierten nav-provider
+  // (lazy beim Ausklappen, SSE-live via treeEntities), keyed auf diese
+  // Nav-QN. Macht den Knoten expandable auch ohne statische children.
+  readonly provider?: boolean;
   // Role / openToAll gate. The nav resolver hides entries the user can't
   // reach; leave unset to always show (engine stays un-opinionated about
   // who sees what — apps that need default-deny can set { roles: [] }).

package/src/engine/types/screen.ts

@@ -309,7 +309,10 @@ export type EditSectionSpec = EditFieldsSection | EditExtensionSection;
 
 export type EditFieldsSection = {
   readonly kind?: "fields";
-  readonly title: string;
+  /** Optional. Ohne Titel rendert die Section nur ihre Felder (keine h3-
+   *  Überschrift) — für flache Forms (Card-Titel + Felder direkt, ein
+   *  einzelner Abschnitt) wie bei den meisten shadcn-Form-Mustern. */
+  readonly title?: string;
   readonly columns?: number;
   readonly fields: readonly EditFieldSpec[];
 };
@@ -333,6 +336,10 @@ export type EntityEditScreenDefinition = {
   readonly type: "entityEdit";
   readonly entity: string;
   readonly layout: EditLayout;
+  /** Optionaler i18n-Key (oder Roh-String) für den Submit-Button. Default
+   *  `kumiko.actions.save`. Lässt den Auto-Edit-Screen domain-spezifische
+   *  CTAs zeigen ("Save Address", "Create item") statt generisch "Speichern". */
+  readonly submitLabel?: string;
   /** Default true. `false` für Entities deren Create über einen eigenen
    *  Lifecycle-Write läuft (z.B. incident:open mit Event-Stream + Joins)
    *  statt über `<entity>:create`: unterdrückt den automatischen

package/src/pipeline/__tests__/dispatcher.test.ts

@@ -376,6 +376,37 @@ describe("dispatcher feature-gate", () => {
     });
   });
 
+  test("trialGate: disabled feature is allowed on the gate's cold path when trialGate returns true", async () => {
+    // Beweist die Live-Trial-Mechanik: der sync resolver hat das Feature NICHT
+    // im Set (alles disabled), aber checkFeatureEnabled konsultiert den async
+    // trialGate auf dem disabled-Pfad. Deckt beide Aufrufstellen ab (query =
+    // ensureFeatureEnabled, write = checkFeatureEnabled).
+    const registry = createRegistry([toggled()]);
+    let trialOpen = false;
+    const effectiveFeatures = Object.assign(() => new Set<string>(), {
+      trialGate: async (_tenantId: TenantId, feature: string) => trialOpen && feature === "toggled",
+    });
+    const dispatcher = createDispatcher(registry, {}, { effectiveFeatures });
+
+    // Trial zu → 403 (resolver-Set leer, Gate verweigert).
+    await expect(dispatcher.query("toggled:query:widget:list", {}, user)).rejects.toThrow(
+      /feature toggled is disabled/,
+    );
+    const writeClosed = await dispatcher.write("toggled:write:widget:create", { name: "x" }, user);
+    expect(writeClosed.isSuccess).toBe(false);
+    if (!writeClosed.isSuccess) expect(writeClosed.error.code).toBe("feature_disabled");
+
+    // Trial offen → Gate lässt durch, obwohl der Resolver das Feature nicht
+    // führt. Query passiert; Write passiert das Gate (scheitert ggf. später an
+    // fehlender DB, aber NICHT mehr an feature_disabled).
+    trialOpen = true;
+    await expect(dispatcher.query("toggled:query:widget:list", {}, user)).resolves.toEqual({
+      items: [],
+    });
+    const writeOpen = await dispatcher.write("toggled:write:widget:create", { name: "x" }, user);
+    if (!writeOpen.isSuccess) expect(writeOpen.error.code).not.toBe("feature_disabled");
+  });
+
   test("Sprint 8a: per-tenant gating — Tenant A passes, Tenant B gets feature_disabled", async () => {
     // Beweist die Phase-1-Architektur: dispatcher ruft effectiveFeatures
     // mit user.tenantId, resolver kann pro Tenant unterschiedliche Sets

package/src/pipeline/dispatcher.ts

@@ -659,10 +659,10 @@ export function createDispatcher(
   // When `effectiveFeatures` is not wired (tests, apps without feature-toggles
   // loaded), every handler is treated as enabled — the gate is a pure
   // pass-through in that common case.
-  function checkFeatureEnabled(
+  async function checkFeatureEnabled(
     qualifiedHandler: string,
     tenantId: TenantId,
-  ): import("../errors").FeatureDisabledError | undefined {
+  ): Promise<import("../errors").FeatureDisabledError | undefined> {
     if (!effectiveFeatures) return undefined;
     const owner = registry.getHandlerFeature(qualifiedHandler);
     // skip: handler without an owning feature cannot be toggled — shouldn't
@@ -671,11 +671,18 @@ export function createDispatcher(
     if (!owner) return undefined;
     const set = effectiveFeatures(tenantId);
     if (set.has(owner)) return undefined;
+    // Feature is off for the stored tier — give the live trial-gate a last
+    // chance. Time-derived (tenant.inserted_at + window), so it can't live in
+    // the boot-cached sync resolver; consulted only on this already-disabled
+    // cold path, never on the hot enabled path.
+    if (effectiveFeatures.trialGate && (await effectiveFeatures.trialGate(tenantId, owner))) {
+      return undefined;
+    }
     return new FeatureDisabledError(owner, qualifiedHandler);
   }
 
-  function ensureFeatureEnabled(qualifiedHandler: string, tenantId: TenantId): void {
-    const err = checkFeatureEnabled(qualifiedHandler, tenantId);
+  async function ensureFeatureEnabled(qualifiedHandler: string, tenantId: TenantId): Promise<void> {
+    const err = await checkFeatureEnabled(qualifiedHandler, tenantId);
     if (err) throw err;
   }
 
@@ -737,7 +744,7 @@ export function createDispatcher(
     // disabled feature must not consume the rate-limit quota — the call
     // never happened from the feature's perspective. Order is: lookup →
     // feature-gate → rate-limit → access → validation → handler.
-    ensureFeatureEnabled(type, user.tenantId);
+    await ensureFeatureEnabled(type, user.tenantId);
 
     // Rate-limit gate runs BEFORE access-check on purpose: anonymous /
     // unauthorized callers must hit the cap too (otherwise the limit
@@ -1028,7 +1035,7 @@ export function createDispatcher(
 
     // Feature-toggle gate: disabled handlers must short-circuit before any
     // rate-limit/access/validation work — see executeQueryInner comment.
-    const disabledErr = checkFeatureEnabled(type, user.tenantId);
+    const disabledErr = await checkFeatureEnabled(type, user.tenantId);
     if (disabledErr) return writeFailure(disabledErr);
 
     // Rate-limit gate before access (same reasoning as in executeQueryInner).

package/src/ui-types/index.ts

@@ -74,5 +74,7 @@ export {
   normalizeEditField,
   normalizeListColumn,
 } from "../engine/types/screen";
+export type { TargetRef } from "../engine/types/target-ref";
+export type { TreeAction, TreeNode, TreeNodeState } from "../engine/types/tree-node";
 export type { WorkspaceDefinition } from "../engine/types/workspace";
 export type { AppSchema, FeatureSchema, WorkspaceSchema } from "./app-schema";