@cosmicdrift/kumiko-framework 0.158.2 → 0.160.0

package/src/engine/index.ts

@@ -42,6 +42,7 @@ export { crossTenantOverrideDenied } from "./cross-tenant";
 export { defineFeature } from "./define-feature";
 export type {
   QueryHandlerDefinition,
+  StreamHandlerDefinition,
   WriteHandlerDefinition,
   WriteHandlerInput,
 } from "./define-handler";
@@ -177,6 +178,7 @@ export {
   checkWriteFieldRoles,
   filterReadFields,
 } from "./field-access";
+export { resolveName, withResponseData } from "./handler-helpers";
 // findForbiddenMembershipRole/isForbiddenMembershipRole/
 // stripForbiddenMembershipRoles/buildSessionRoles are Public API for host
 // apps that build their own membership handlers. FORBIDDEN_MEMBERSHIP_ROLES
@@ -203,6 +205,7 @@ export { runsInLane } from "./run-in";
 export type { StepListOutcome } from "./run-pipeline";
 export { runPipeline, runStepList } from "./run-pipeline";
 export { buildInsertSchema, buildUpdateSchema, fieldToZod } from "./schema-builder";
+export { isExtensionEditSection, normalizeEditField, normalizeListColumn } from "./screen-helpers";
 export type { TransitionGraph } from "./state-machine";
 export { defineTransitions, guardTransition } from "./state-machine";
 export {
@@ -362,6 +365,8 @@ export type {
   SecretKeyHandle,
   SelectFieldDef,
   SessionUser,
+  StreamHandlerDef,
+  StreamHandlerFn,
   Subscribe,
   TargetRef,
   TenantId,
@@ -385,9 +390,7 @@ export type {
   WriteResult,
 } from "./types";
 export { DEFAULT_CURRENCIES, HookPhases } from "./types";
-export { resolveName, withResponseData } from "./types/handlers";
 export { isSystemTenant, parseTenantId, SYSTEM_TENANT_ID } from "./types/identifiers";
-export { isExtensionEditSection, normalizeEditField, normalizeListColumn } from "./types/screen";
 export type {
   PipelineBuildCtx,
   PipelineCtx,

package/src/engine/ownership.ts

@@ -20,64 +20,28 @@
 import { toSnakeCase } from "../db/table-builder";
 import type { SessionUser } from "./types";
 
-// Parameterised SQL fragment — produced by buildOwnershipClause + by the
-// WhereRule escape-hatch. Caller weaves `sqlText` into a larger statement,
-// renumbering placeholders if needed (FragmentBuilder below).
-export type SqlFragment = {
-  readonly sqlText: string;
-  readonly params: readonly unknown[];
-};
-
-// Reference spec supported by `from()`:
-//   "user:id"                  → user.id
-//   "user:tenantId"            → user.tenantId (rarely needed — TenantDb scopes anyway)
-//   "claim:<featureName>:<key>" → user.claims["<featureName>:<key>"]
-//
-// The string form is keyed so the framework can look up the referenced
-// Registry entry at boot (Claim-QN exists? Column type compatible?). A typed
-// object form would force features to import each other's handles — the
-// whole point of H.2's unified path is string-based references, no imports.
-export type OwnershipRef = string;
-
-// Resolved during `from()` — the parser eagerly splits the prefix so the
-// runtime evaluator avoids string-parsing on every row. `kind` drives the
-// evaluator branch; the rest is the resolved metadata.
-export type FromRuleKind = "user" | "claim";
-
-export type FromRule = {
-  readonly kind: "from";
-  readonly refKind: FromRuleKind;
-  // For "user:id" → "id"; for "user:tenantId" → "tenantId".
-  // For "claim:<featureName>:<key>" → "<featureName>:<key>" (the full QN,
-  // which is exactly the key under which the JWT stores the value).
-  readonly refPath: string;
-  // Row-column to match against. For claim rules defaults to the claim's
-  // shortName (second segment of the claim QN). For user-rules the column
-  // is always explicit.
-  readonly column: string;
-};
-
-// Context passed to a WhereRule escape-hatch. The author returns a SqlFragment
-// whose placeholders start at `paramStart` ($N, $N+1, ...); the framework
-// concatenates the fragment into the larger query.
-export type WhereRuleContext<TTable = unknown> = {
-  readonly table: TTable;
-  readonly tableName: string;
-  readonly paramStart: number;
-};
-
-export type WhereRule<TTable = unknown> = {
-  readonly kind: "where";
-  readonly where: (user: SessionUser, ctx: WhereRuleContext<TTable>) => SqlFragment;
-};
-
-// "all" collapses to a primitive so map authors can write `Admin: "all"`
-// without importing a helper.
-export type OwnershipRule = "all" | FromRule | WhereRule;
-
-// Per-role map: every key is a role name, value is the rule that role
-// satisfies to pass the access check.
-export type OwnershipMap = Readonly<Record<string, OwnershipRule>>;
+// Types live in engine/types/ownership.ts (no runtime dependency); re-exported
+// here for backwards compatibility with existing importers of this file.
+export type {
+  FromRule,
+  FromRuleKind,
+  OwnershipClause,
+  OwnershipMap,
+  OwnershipRef,
+  OwnershipRule,
+  SqlFragment,
+  WhereRule,
+  WhereRuleContext,
+} from "./types/ownership";
+
+import type {
+  FromRule,
+  OwnershipClause,
+  OwnershipMap,
+  OwnershipRef,
+  OwnershipRule,
+  SqlFragment,
+} from "./types/ownership";
 
 // Parse an OwnershipRef into kind + resolved path + default column.
 // Throws on malformed input so the error surfaces at `from()`-call-site (in
@@ -254,24 +218,6 @@ export function userCanCreateFieldRow(
   return false;
 }
 
-// Result of buildOwnershipClause. The discriminant lets the caller handle
-// the three outcomes without inspecting SQL internals:
-//
-//   "pass"  → user is unrestricted. Run the query as-is.
-//   "empty" → user has a role mapped but no rule accepts any row (missing
-//             claim, empty array, role not in map). Skip the DB call entirely
-//             — returning [] is equivalent and avoids a pointless roundtrip.
-//   "sql"   → apply the parameterised fragment as an AND on the query.
-//             Caller is responsible for renumbering placeholders when
-//             concatenating with other fragments (see `shiftParams` below).
-//
-// "empty" vs. "pass" is the critical distinction for a safe default:
-// undefined/pass = allow, empty = deny-by-construction.
-export type OwnershipClause =
-  | { readonly kind: "pass" }
-  | { readonly kind: "empty" }
-  | { readonly kind: "sql"; readonly sqlText: string; readonly params: readonly unknown[] };
-
 const PASS_CLAUSE: OwnershipClause = { kind: "pass" };
 const EMPTY_CLAUSE: OwnershipClause = { kind: "empty" };
 

package/src/engine/pattern-library/__tests__/library.test.ts

@@ -46,6 +46,7 @@ const ALL_KINDS: FeaturePatternKind[] = [
   "screen",
   "writeHandler",
   "queryHandler",
+  "streamHandler",
   "hook",
   "job",
   "notification",
@@ -270,6 +271,14 @@ function makePlaceholderPattern(kind: FeaturePatternKind): FeaturePattern {
         schemaSource: PLACEHOLDER_BODY_LOC,
         handlerBody: PLACEHOLDER_BODY_LOC,
       };
+    case "streamHandler":
+      return {
+        kind,
+        source: PLACEHOLDER_LOC,
+        handlerName: "x",
+        schemaSource: PLACEHOLDER_BODY_LOC,
+        handlerBody: PLACEHOLDER_BODY_LOC,
+      };
     case "hook":
       return {
         kind,

package/src/engine/pattern-library/library.ts

@@ -25,6 +25,7 @@ import {
   projectionSchema,
   queryHandlerSchema,
   screenSchema,
+  streamHandlerSchema,
   writeHandlerSchema,
 } from "./mixed-schemas";
 import {
@@ -79,6 +80,7 @@ export const PATTERN_LIBRARY: Readonly<Record<FeaturePatternKind, PatternFormSch
   screen: screenSchema,
   writeHandler: writeHandlerSchema,
   queryHandler: queryHandlerSchema,
+  streamHandler: streamHandlerSchema,
   hook: hookSchema,
   job: jobSchema,
   notification: notificationSchema,

package/src/engine/pattern-library/mixed-schemas.ts

@@ -125,6 +125,43 @@ export const queryHandlerSchema: PatternFormSchema = {
   ],
 };
 
+export const streamHandlerSchema: PatternFormSchema = {
+  kind: "streamHandler",
+  label: { en: "Stream handler", de: "Stream-Handler" },
+  summary: { en: "Streaming read endpoint (SSE) with Zod schema + async-generator body." },
+  category: "behaviour",
+  editability: "mixed",
+  fields: [
+    {
+      path: "handlerName",
+      label: { en: "Name", de: "Name" },
+      input: "text",
+      required: true,
+      placeholder: "chat:complete",
+    },
+    {
+      path: "schemaSource",
+      label: { en: "Zod schema (source)", de: "Zod-Schema (Source)" },
+      input: "code-block",
+      language: "zod",
+      readOnly: true,
+    },
+    {
+      path: "handlerBody",
+      label: { en: "Handler body (source)", de: "Handler-Body (Source)" },
+      input: "code-block",
+      language: "typescript",
+      readOnly: true,
+    },
+    accessRuleField,
+    {
+      path: "rateLimit",
+      label: { en: "Rate limit", de: "Rate-Limit" },
+      input: "json-readonly",
+    },
+  ],
+};
+
 export const hookSchema: PatternFormSchema = {
   kind: "hook",
   label: { en: "Lifecycle hook", de: "Lifecycle-Hook" },

package/src/engine/registry-facade.ts

@@ -30,6 +30,7 @@ import type {
   SearchPayloadContributorFn,
   SecretKeyDefinition,
   StoreTableDef,
+  StreamHandlerDef,
   TranslationKeys,
   TreeActionDef,
   WorkspaceDefinition,
@@ -72,6 +73,14 @@ export function buildRegistryFacade(state: RegistryState): Registry {
       return state.queryHandlerMap;
     },
 
+    getStreamHandler(name: string): StreamHandlerDef | undefined {
+      return state.streamHandlerMap.get(name);
+    },
+
+    getAllStreamHandlers(): ReadonlyMap<string, StreamHandlerDef> {
+      return state.streamHandlerMap;
+    },
+
     getSearchableFields(entityName: string): readonly string[] {
       return state.searchableFieldsCache.get(entityName) ?? [];
     },

package/src/engine/registry-ingest.ts

@@ -80,6 +80,16 @@ export function populateHandlers(state: RegistryState, feature: FeatureDefinitio
     state.queryHandlerMap.set(qualified, { ...handler, name: qualified });
     state.handlerFeatureMap.set(qualified, feature.name);
   }
+
+  // Stream handlers: scope:stream:name
+  for (const [name, handler] of Object.entries(feature.streamHandlers ?? {})) {
+    const qualified = qualify(feature.name, "stream", name);
+    if (state.streamHandlerMap.has(qualified)) {
+      throw new Error(`Duplicate stream handler: "${qualified}" (registered by multiple features)`);
+    }
+    state.streamHandlerMap.set(qualified, { ...handler, name: qualified });
+    state.handlerFeatureMap.set(qualified, feature.name);
+  }
 }
 
 // Config keys: scope:config:name, duplicate-guarded.

package/src/engine/registry-state.ts

@@ -37,6 +37,7 @@ import type {
   SearchPayloadContributorFn,
   SecretKeyDefinition,
   StoreTableDef,
+  StreamHandlerDef,
   TreeActionDef,
   WorkspaceDefinition,
   WriteHandlerDef,
@@ -165,6 +166,7 @@ export type RegistryState = {
   relationMap: Map<string, Record<string, RelationDefinition>>;
   writeHandlerMap: Map<string, WriteHandlerDef>;
   queryHandlerMap: Map<string, QueryHandlerDef>;
+  streamHandlerMap: Map<string, StreamHandlerDef>;
   preSaveHooks: Map<string, OwnedFn<PreSaveHookFn>[]>;
   postSaveHooks: Map<string, PhasedHook<PostSaveHookFn>[]>;
   preDeleteHooks: Map<string, PhasedHook<PreDeleteHookFn>[]>;
@@ -229,6 +231,7 @@ export function createInitialState(): RegistryState {
     relationMap: new Map(),
     writeHandlerMap: new Map(),
     queryHandlerMap: new Map(),
+    streamHandlerMap: new Map(),
     preSaveHooks: new Map(),
     postSaveHooks: new Map(),
     preDeleteHooks: new Map(),

package/src/engine/registry-validate.ts

@@ -1,4 +1,5 @@
 import { configureEventPiiCatalog } from "../crypto/event-pii";
+import { resolveName } from "./handler-helpers";
 import type { RegistryState } from "./registry-state";
 import { buildImplicitProjection, hasFieldAccessRules, qualify } from "./registry-state";
 import {
@@ -11,7 +12,6 @@ import {
 } from "./soft-delete-cleanup";
 import type { EventPiiFields, EventUpcastFn, FeatureDefinition } from "./types";
 import { HookPhases } from "./types";
-import { resolveName } from "./types/handlers";
 
 function allHandlerQns(state: RegistryState): ReadonlySet<string> {
   return new Set([...state.writeHandlerMap.keys(), ...state.queryHandlerMap.keys()]);

package/src/engine/screen-helpers.ts

@@ -0,0 +1,54 @@
+import type {
+  EditExtensionSection,
+  EditFieldSpec,
+  EditSectionSpec,
+  FieldCondition,
+  FormatSpec,
+  ListColumnSpec,
+} from "./types/screen";
+
+export function isExtensionEditSection(section: EditSectionSpec): section is EditExtensionSection {
+  return section.kind === "extension";
+}
+
+// Type guard — narrows FieldRenderer to FormatSpec. Useful for renderer
+// authors who branch on the three FieldRenderer variants without manual
+// "format" in renderer checks.
+export function isFormatSpec(r: unknown): r is FormatSpec {
+  return typeof r === "object" && r !== null && "format" in r && typeof r.format === "string";
+}
+
+// Collapse the string-shorthand into the object form. Both the boot-validator
+// and (later) ui-core's view-model builder iterate over fields/columns — the
+// helper keeps that loop from growing two branches everywhere.
+export function normalizeListColumn(c: ListColumnSpec): Exclude<ListColumnSpec, string> {
+  const col = typeof c === "string" ? { field: c } : c;
+  if (
+    typeof process !== "undefined" &&
+    process.env.NODE_ENV !== "production" &&
+    col.renderer !== undefined &&
+    typeof col.renderer === "function"
+  ) {
+    // biome-ignore lint/suspicious/noConsole: dev-only warning
+    console.warn(
+      `[kumiko] normalizeListColumn: Feld "${col.field}" hat einen Funktions-Renderer — dieser wird von JSON.stringify verworfen. Bitte auf FormatSpec ({ format: "..." }) migrieren.`,
+    );
+  }
+  return col;
+}
+
+/** Evaluates a declarative FieldCondition against the current row/form
+ *  values. THE single implementation — renderer (row-action visibility),
+ *  headless view-model (visible/readOnly/required) and render-edit
+ *  (form-condition closures) reuse it; three hand-rolled copies had
+ *  already drifted in shape. */
+export function evalFieldCondition(cond: FieldCondition, values: Record<string, unknown>): boolean {
+  if (typeof cond === "boolean") return cond;
+  const val = values[cond.field];
+  if ("eq" in cond) return val === cond.eq;
+  return val !== cond.ne;
+}
+
+export function normalizeEditField(f: EditFieldSpec): Exclude<EditFieldSpec, string> {
+  return typeof f === "string" ? { field: f } : f;
+}

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

@@ -48,8 +48,9 @@ export type EffectiveFeaturesResolver = ((tenantId: TenantId) => ReadonlySet<str
    * 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.
+   * sich zwischen Requests). Konsultiert an 3 Stellen: den 2 Dispatch-Gate-
+   * Aufrufstellen (checkFeatureEnabled) UND ctx.hasFeature im Handler-Body
+   * (fällt darauf zurück, wenn der synchrone Feature-Set-Check negativ ist).
    */
   readonly trialGate?: TrialGate;
 };