@cosmicdrift/kumiko-framework 0.158.2 → 0.160.0

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

@@ -101,6 +101,46 @@ describe("getAllQueryHandlers", () => {
   });
 });
 
+describe("getAllStreamHandlers", () => {
+  test("returns every registered stream handler, qualified, across multiple features", () => {
+    const aiFeature = defineFeature("registry-test-ai", (r) => {
+      r.streamHandler("chat:complete", z.object({ prompt: z.string() }), async function* () {}, {
+        access: { openToAll: true },
+      });
+    });
+    const otherFeature = defineFeature("registry-test-other", (r) => {
+      r.streamHandler("chat:complete", z.object({ prompt: z.string() }), async function* () {}, {
+        access: { openToAll: true },
+      });
+    });
+
+    const registry = createRegistry([aiFeature, otherFeature]);
+    const handlers = registry.getAllStreamHandlers();
+
+    expect(handlers.get("registry-test-ai:stream:chat:complete")).toBeDefined();
+    expect(handlers.get("registry-test-other:stream:chat:complete")).toBeDefined();
+    // Same Map instance getStreamHandler reads from, not a copy that can drift.
+    expect(handlers.get("registry-test-ai:stream:chat:complete")).toBe(
+      registry.getStreamHandler("registry-test-ai:stream:chat:complete"),
+    );
+  });
+
+  test("empty registry returns an empty map, not undefined", () => {
+    const registry = createRegistry([]);
+    expect(registry.getAllStreamHandlers().size).toBe(0);
+  });
+
+  test("duplicate stream-handler short-name across features qualifies independently, no collision", () => {
+    const aiFeature = defineFeature("registry-test-dup-a", (r) => {
+      r.streamHandler("chat:complete", z.object({}), async function* () {});
+    });
+    const otherFeature = defineFeature("registry-test-dup-b", (r) => {
+      r.streamHandler("chat:complete", z.object({}), async function* () {});
+    });
+    expect(() => createRegistry([aiFeature, otherFeature])).not.toThrow();
+  });
+});
+
 describe("extensionSelector boot-validation", () => {
   function foundationFeature() {
     return defineFeature("probe-foundation", (r) => {

package/src/engine/__tests__/store-table.test.ts

@@ -75,6 +75,18 @@ describe("r.storeTable — declaration", () => {
     ).toThrow(/requires source: "unmanaged"/);
   });
 
+  test("rejects a table name with the reserved read_ prefix (#1220)", () => {
+    const readPrefixed = defineUnmanagedTable({
+      tableName: "read_rt_probe",
+      columns: [{ name: "id", pgType: "text", notNull: true, primaryKey: true }],
+    });
+    expect(() =>
+      defineFeature("probe", (r) => {
+        r.storeTable(readPrefixed, { reason: "test" });
+      }),
+    ).toThrow(/the "read_" prefix is reserved/);
+  });
+
   test("accepts valid registration and stores meta + reason", () => {
     const feature = defineFeature("probe", (r) => {
       r.storeTable(probeMeta, {

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

@@ -5,7 +5,11 @@
 
 import { describe, expect, test } from "bun:test";
 import { createEntity, defineFeature } from "../index";
-import { findTierResolverUsage, TENANT_TIER_RESOLVER_EXT } from "../tier-resolver-extension";
+import {
+  findTierResolverUsage,
+  isTierResolverPlugin,
+  TENANT_TIER_RESOLVER_EXT,
+} from "../tier-resolver-extension";
 
 function tierResolverFeature(name: string) {
   return defineFeature(name, (r) => {
@@ -49,3 +53,17 @@ describe("findTierResolverUsage", () => {
     expect(findTierResolverUsage([])).toBeUndefined();
   });
 });
+
+describe("isTierResolverPlugin", () => {
+  test("true when build is a function", () => {
+    expect(isTierResolverPlugin({ build: async () => new Set() })).toBe(true);
+  });
+
+  test("false for null, non-objects, and missing/non-fn build", () => {
+    expect(isTierResolverPlugin(null)).toBe(false);
+    expect(isTierResolverPlugin(undefined)).toBe(false);
+    expect(isTierResolverPlugin("x")).toBe(false);
+    expect(isTierResolverPlugin({})).toBe(false);
+    expect(isTierResolverPlugin({ build: 1 })).toBe(false);
+  });
+});

package/src/engine/boot-validator/action-wiring.ts

@@ -1,3 +1,4 @@
+import { isExtensionEditSection, normalizeEditField, normalizeListColumn } from "../screen-helpers";
 import type {
   EditFieldSpec,
   EditLayout,
@@ -6,7 +7,6 @@ import type {
   RowAction,
   ToolbarAction,
 } from "../types";
-import { isExtensionEditSection, normalizeEditField, normalizeListColumn } from "../types/screen";
 
 const FUNCTION_DROPPED_HINT =
   "functions are dropped by JSON.stringify when the screen config reaches the client " +

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

@@ -0,0 +1,21 @@
+import type { BootCheckContext, FeatureDefinition } from "../types";
+
+// r.bootCheck(fn) lets a feature declare its own mount-invariant instead of
+// relying on framework-internal knowledge (the gdpr-storage.ts guards are
+// the framework-owned version of this same idea). Each registered fn gets
+// the full mounted-feature set and throws to fail the boot; we wrap the
+// message with the owning feature's name so the error text points back at
+// the feature that declared the check.
+export function validateFeatureBootChecks(features: readonly FeatureDefinition[]): void {
+  const ctx: BootCheckContext = { features };
+  for (const feature of features) {
+    for (const check of feature.bootChecks) {
+      try {
+        check(ctx);
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new Error(`[Feature ${feature.name}] r.bootCheck failed: ${message}`);
+      }
+    }
+  }
+}

package/src/engine/boot-validator/entity-handler.ts

@@ -119,11 +119,20 @@ export function validateHandlerAccess(feature: FeatureDefinition): void {
     }
     validateAnonymousRateLimit(feature.name, "query", name, handler.access, handler.rateLimit);
   }
+  for (const [name, handler] of Object.entries(feature.streamHandlers)) {
+    if (!handler.access) {
+      throw new Error(
+        `Stream handler "${feature.name}:stream:${name}" is missing an access rule. ` +
+          `Set { roles: [...] } for role-based access, or { openToAll: true } for any authenticated user.`,
+      );
+    }
+    validateAnonymousRateLimit(feature.name, "stream", name, handler.access, handler.rateLimit);
+  }
 }
 
 export function validateAnonymousRateLimit(
   featureName: string,
-  kind: "write" | "query",
+  kind: "write" | "query" | "stream",
   handlerName: string,
   access: NonNullable<FeatureDefinition["writeHandlers"][string]["access"]>,
   rateLimit: FeatureDefinition["writeHandlers"][string]["rateLimit"],

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

@@ -1,5 +1,5 @@
+import { normalizeListColumn } from "../screen-helpers";
 import type { EntityListScreenDefinition, FeatureDefinition } from "../types";
-import { normalizeListColumn } from "../types/screen";
 
 /** Operator lists default searchable; low-cardinality audit trails stay opt-out. */
 export const SEARCHABLE_FALSE_WHITELIST = new Set(["download-attempt-list"]);

package/src/engine/boot-validator/gdpr-storage.ts

@@ -1,22 +1,4 @@
-import { EXT_TENANT_DATA, EXT_USER_DATA } from "../extension-names";
 import type { FeatureDefinition } from "../types";
-import type { EntityDefinition, PiiAnnotations } from "../types/fields";
-
-// r.entity(...) is not the only way a feature exposes an entity shape:
-// r.projection(...) can carry an optional `entity` too (raw read-models with
-// no executor, e.g. billing-foundation's subscription table). Both V3 and V4
-// below need every entity a feature declares, not just the r.entity ones, or
-// a tenantOwned/pii field on a projection-only entity is invisible to the
-// guard it was annotated for.
-function entitiesOf(
-  feature: FeatureDefinition,
-): ReadonlyArray<readonly [string, EntityDefinition]> {
-  const fromEntities = Object.entries(feature.entities ?? {});
-  const fromProjections = Object.values(feature.projections ?? {})
-    .filter((p): p is typeof p & { entity: EntityDefinition } => p.entity !== undefined)
-    .map((p) => [p.name, p.entity] as const);
-  return [...fromEntities, ...fromProjections];
-}
 
 // Providers whose bytes do not survive a process restart. Only "inmemory"
 // today; extend if another ephemeral bundled provider lands.
@@ -75,97 +57,3 @@ export function validateGdprStoragePersistence(features: readonly FeatureDefinit
     }
   }
 }
-
-// V2: export-without-erase gate. A feature that registers an EXT_USER_DATA
-// export hook without a matching delete hook exports data under Art.20 but
-// never erases it on forget — an Art.17 violation. Hard boot failure: no app
-// should ship a GDPR export path with no erase path. Registry-level signal
-// only; runtime no-ops (a delete hook that silently skips) are not detectable
-// here — those are covered by the export/forget integration tests.
-export function validateGdprHookCompleteness(features: readonly FeatureDefinition[]): void {
-  for (const feature of features) {
-    for (const usage of feature.extensionUsages) {
-      if (usage.extensionName !== EXT_USER_DATA) continue;
-      const hasExport = typeof usage.options?.["export"] === "function";
-      const hasDelete = typeof usage.options?.["delete"] === "function";
-      if (hasExport && !hasDelete) {
-        throw new Error(
-          `[kumiko:boot] Feature "${feature.name}" exports entity "${usage.entityName}" via EXT_USER_DATA but registers no delete hook — data is included in Art.20 exports but never erased on forget (Art.17 violation). Add a delete hook. If erasure is intentionally handled elsewhere (e.g. crypto-shredding key-erase, parent cascade), register a no-op delete: async () => {} with a comment explaining why.`,
-        );
-      }
-    }
-  }
-}
-
-// V3: PII-entity-without-hook gate. V2 checks registered hooks for
-// completeness; V3 catches the entity nobody registered at all — fields
-// annotated as user-subject data (pii / userOwned) yet invisible to the
-// Art.15/20 export and Art.17 forget pipeline. Hard boot failure once
-// user-data-rights is mounted: a subject-data entity that skips the pipeline
-// is exactly the "feature built past GDPR" leak this gate exists to stop.
-// Matching is by entity name across all features (usage.entityName is
-// unqualified); a same-named entity in another feature can mask a gap —
-// accepted, as the common case is a distinct entity name.
-export function validateGdprPiiHookCoverage(features: readonly FeatureDefinition[]): void {
-  const featureNames = new Set(features.map((f) => f.name));
-  if (!featureNames.has("user-data-rights")) {
-    // skip: this guard only applies to apps that mount user-data-rights
-    return;
-  }
-
-  const hookedEntities = new Set<string>();
-  for (const f of features) {
-    for (const usage of f.extensionUsages) {
-      if (usage.extensionName === EXT_USER_DATA) hookedEntities.add(usage.entityName);
-    }
-  }
-
-  for (const feature of features) {
-    for (const [entityName, entity] of entitiesOf(feature)) {
-      if (hookedEntities.has(entityName)) continue;
-      const subjectFields = Object.entries(entity.fields)
-        .filter(([, field]) => {
-          const annot = field as PiiAnnotations; // @cast-boundary schema-walk
-          return Boolean(annot.pii) || Boolean(annot.userOwned);
-        })
-        .map(([name]) => name);
-      if (subjectFields.length === 0) continue;
-      throw new Error(
-        `[kumiko:boot] Entity "${entityName}" (feature "${feature.name}") has user-subject fields (${subjectFields.join(", ")}) but no feature registers an EXT_USER_DATA hook for it — the data never appears in Art.15/20 exports and is never erased on forget (Art.17 gap). Register r.useExtension(EXT_USER_DATA, "${entityName}", { export, delete }) in the owning feature or a defaults feature. If this entity is intentionally out of the pipeline (e.g. crypto-shredding key-erase covers it), register a no-op hook { export: async () => null, delete: async () => {} } with a comment explaining why.`,
-      );
-    }
-  }
-}
-
-// V4: tenantOwned-entity-without-hook gate. Mirrors validateGdprPiiHookCoverage
-// but for EXT_TENANT_DATA when tenant-lifecycle is mounted.
-export function validateTenantDataHookCoverage(features: readonly FeatureDefinition[]): void {
-  const featureNames = new Set(features.map((f) => f.name));
-  if (!featureNames.has("tenant-lifecycle")) {
-    // skip: this guard only applies to apps that mount tenant-lifecycle
-    return;
-  }
-
-  const hookedEntities = new Set<string>();
-  for (const f of features) {
-    for (const usage of f.extensionUsages) {
-      if (usage.extensionName === EXT_TENANT_DATA) hookedEntities.add(usage.entityName);
-    }
-  }
-
-  for (const feature of features) {
-    for (const [entityName, entity] of entitiesOf(feature)) {
-      if (hookedEntities.has(entityName)) continue;
-      const tenantSubjectFields = Object.entries(entity.fields)
-        .filter(([, field]) => {
-          const annot = field as PiiAnnotations;
-          return Boolean(annot.tenantOwned);
-        })
-        .map(([name]) => name);
-      if (tenantSubjectFields.length === 0) continue;
-      throw new Error(
-        `[kumiko:boot] Entity "${entityName}" (feature "${feature.name}") has tenant-subject fields (${tenantSubjectFields.join(", ")}) but no feature registers an EXT_TENANT_DATA destroy hook for it — tenant destroy never erases this data. Register r.useExtension(EXT_TENANT_DATA, "${entityName}", { destroy }) or a documented no-op if crypto-shredding covers it.`,
-      );
-    }
-  }
-}

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

@@ -3,6 +3,7 @@ import { QnTypes, qualifyEntityName } from "../qualified-name";
 import type { ClaimKeyDefinition, FeatureDefinition } from "../types";
 import { validateActionWiring, validateFieldWiring } from "./action-wiring";
 import { validateApiExposureMatching, validateExtensionUsages } from "./api-ext";
+import { validateFeatureBootChecks } from "./boot-check";
 import {
   validateCircularDeps,
   validateConfigKeyAllowPerRequest,
@@ -30,12 +31,7 @@ import {
   validateTransitions,
 } from "./entity-handler";
 import { validateEntityListScreens } from "./entity-list-screens";
-import {
-  validateGdprHookCompleteness,
-  validateGdprPiiHookCoverage,
-  validateGdprStoragePersistence,
-  validateTenantDataHookCoverage,
-} from "./gdpr-storage";
+import { validateGdprStoragePersistence } from "./gdpr-storage";
 import { validateI18nSurfaceKeys } from "./i18n-keys";
 import {
   collectKnownRoles,
@@ -198,9 +194,7 @@ export function validateBoot(features: readonly FeatureDefinition[]): void {
   validateEntityListScreens(features);
   validateExtensionPreSaveWiring(features);
   validateGdprStoragePersistence(features);
-  validateGdprHookCompleteness(features);
-  validateGdprPiiHookCoverage(features);
-  validateTenantDataHookCoverage(features);
+  validateFeatureBootChecks(features);
 
   if (hasEncryptedFields) {
     // Availability check, not env-presence: eagerly building the keyring

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

@@ -7,6 +7,7 @@
 import { rowMetaFieldNames } from "../../db/table-builder";
 import { qualifyEntityName } from "../qualified-name";
 import { getAllowedFilterOps, isFieldFilterable } from "../screen-filter-ops";
+import { isExtensionEditSection, normalizeEditField, normalizeListColumn } from "../screen-helpers";
 import type { FeatureDefinition } from "../types";
 import type {
   DashboardCustomPanel,
@@ -20,7 +21,6 @@ import type {
   ScreenDefinition,
   ToolbarAction,
 } from "../types/screen";
-import { isExtensionEditSection, normalizeEditField, normalizeListColumn } from "../types/screen";
 
 // --- Screen validation ---
 //

package/src/engine/define-feature.ts

@@ -106,6 +106,7 @@ export function defineFeature<const TName extends string, TExports = undefined>(
     relations: state.relations,
     writeHandlers: state.writeHandlers,
     queryHandlers: state.queryHandlers,
+    streamHandlers: state.streamHandlers,
     translations: state.translations,
     hooks: {
       validation: state.validationHooks,
@@ -136,6 +137,7 @@ export function defineFeature<const TName extends string, TExports = undefined>(
     extensionSelectors: state.extensionSelectors,
     exposedApis: state.exposedApis,
     usedApis: state.usedApis,
+    bootChecks: state.bootChecks,
     referenceData: state.referenceData,
     events: state.events,
     eventMigrations: state.eventMigrations,

package/src/engine/define-handler.ts

@@ -1,81 +1,19 @@
 import type { ZodType, z } from "zod";
 import type { ContainsSecret } from "../secrets/types";
 import { runPipeline } from "./run-pipeline";
+import type { HandlerContext, KumikoEventTypeMap, WriteEvent, WriteResult } from "./types";
 import type {
-  AccessRule,
-  HandlerContext,
-  KumikoEventTypeMap,
-  QueryEvent,
-  RateLimitOption,
-  WriteEvent,
-  WriteResult,
-} from "./types";
-import type { PipelineDef } from "./types/step";
+  QueryHandlerDefinition,
+  WriteHandlerDefinition,
+  WriteHandlerInput,
+} from "./types/define-handler";
 
-// --- Write Handler Definition ---
-//
-// TMap propagates the strict event-type-map through the handler's
-// HandlerContext. CRITICAL: TMap is declared as a generic parameter on the
-// FUNCTION (defineWriteHandler), not just on the type. Generic-functions
-// substitute TMap at the USE-site (the caller's compile context, where
-// the augmentation is visible); generic-type-aliases substitute at the
-// definition-site (framework's compile, where the augmentation isn't
-// visible) and collapse `keyof TMap` to `never`. See the spike-findings
-// memory for the empirical proof.
-//
-// Two authoring forms — `handler` (free-form) or `perform: stepsPipeline(...)`
-// (step-pipeline). A `perform` is compiled to a handler-function at
-// definition time; the dispatcher only ever sees `handler`.
-
-export type WriteHandlerDefinition<
-  TName extends string = string,
-  TSchema extends ZodType = ZodType,
-  TData = unknown,
-  TMap extends object = KumikoEventTypeMap,
-> = {
-  readonly name: TName;
-  readonly schema: TSchema;
-  readonly access?: AccessRule;
-  readonly unsafeSkipTransitionGuard?: boolean;
-  readonly rateLimit?: RateLimitOption;
-  readonly handler: (
-    event: WriteEvent<z.infer<TSchema>>,
-    context: HandlerContext<TMap>,
-  ) => Promise<WriteResult<TData>>;
-  // Preserved when the author wrote a `perform` block — the original
-  // PipelineDef. Designer/AI/AST tools read this when present; the
-  // dispatcher ignores it and just calls `handler`. Absent on free-form
-  // handlers.
-  readonly perform?: PipelineDef<z.infer<TSchema>, TData>;
-};
-
-// Author-facing input — accepts either the free-form `handler` or the
-// pipeline-form `perform`. defineWriteHandler narrows them to the
-// canonical WriteHandlerDefinition shape.
-export type WriteHandlerInput<
-  TName extends string = string,
-  TSchema extends ZodType = ZodType,
-  TData = unknown,
-  TMap extends object = KumikoEventTypeMap,
-> = {
-  readonly name: TName;
-  readonly schema: TSchema;
-  readonly access?: AccessRule;
-  readonly unsafeSkipTransitionGuard?: boolean;
-  readonly rateLimit?: RateLimitOption;
-} & (
-  | {
-      readonly handler: (
-        event: WriteEvent<z.infer<TSchema>>,
-        context: HandlerContext<TMap>,
-      ) => Promise<WriteResult<TData>>;
-      readonly perform?: never;
-    }
-  | {
-      readonly perform: PipelineDef<z.infer<TSchema>, TData>;
-      readonly handler?: never;
-    }
-);
+export type {
+  QueryHandlerDefinition,
+  StreamHandlerDefinition,
+  WriteHandlerDefinition,
+  WriteHandlerInput,
+} from "./types/define-handler";
 
 export function defineWriteHandler<
   const TName extends string,
@@ -160,24 +98,6 @@ export function defineWriteHandler<
   return { ...base, handler: def.handler };
 }
 
-// --- Query Handler Definition ---
-
-export type QueryHandlerDefinition<
-  TName extends string = string,
-  TSchema extends ZodType = ZodType,
-  TResult = unknown,
-  TMap extends object = KumikoEventTypeMap,
-> = {
-  readonly name: TName;
-  readonly schema: TSchema;
-  readonly access?: AccessRule;
-  readonly rateLimit?: RateLimitOption;
-  readonly handler: (
-    query: QueryEvent<z.infer<TSchema>>,
-    context: HandlerContext<TMap>,
-  ) => Promise<TResult>;
-};
-
 export function defineQueryHandler<
   const TName extends string,
   TSchema extends ZodType,

package/src/engine/entity-handlers.ts

@@ -18,6 +18,21 @@ import type {
   QueryHandlerDef,
   WriteHandlerDef,
 } from "./types";
+import type {
+  EntityCrudRegistrar,
+  EntityCrudVerb,
+  EntityHandlerOptions,
+  EntityQueryHandlerOptions,
+  RegisterEntityCrudOptions,
+} from "./types/entity-handlers";
+
+export type {
+  EntityCrudRegistrar,
+  EntityCrudVerb,
+  EntityHandlerOptions,
+  EntityQueryHandlerOptions,
+  RegisterEntityCrudOptions,
+} from "./types/entity-handlers";
 
 // Convention-based handler factories for event-sourced aggregates.
 //
@@ -330,16 +345,6 @@ export function defineEntityQueryHandler(
 // would need a Branded-EntityDefinition with `softDelete: true` literal
 // — feasible but not yet wired; the runtime guard catches misuse.
 
-type EntityHandlerOptions = { readonly access?: AccessRule };
-type EntityQueryHandlerOptions = EntityHandlerOptions & {
-  /** Reads across every tenant instead of the caller's own — for a
-   *  SystemAdmin-only operator inspector over an otherwise tenant-scoped
-   *  entity. Scope this to the ONE handler that needs it rather than making
-   *  the whole feature r.systemScope(), which would drop tenant isolation
-   *  from every other handler the feature registers too. */
-  readonly crossTenant?: boolean;
-};
-
 // @wrapper-known semantic-alias
 export function defineEntityCreateHandler(
   entityName: string,
@@ -446,23 +451,6 @@ export function defineProjectionQueryHandler(
   };
 }
 
-type EntityCrudVerb = "create" | "update" | "delete" | "restore" | "list" | "detail";
-
-export type RegisterEntityCrudOptions = {
-  readonly write?: EntityHandlerOptions;
-  readonly read?: EntityQueryHandlerOptions;
-  readonly verbs?: Partial<Record<EntityCrudVerb, boolean>>;
-  /** Default true. Set false when the entity was already registered (e.g. before r.relation). */
-  readonly registerEntity?: boolean;
-};
-
-/** Minimal registrar surface — keeps entity-handlers free of define-feature imports. */
-export type EntityCrudRegistrar = {
-  entity(name: string, definition: EntityDefinition): unknown;
-  writeHandler(def: WriteHandlerDef): unknown;
-  queryHandler(def: QueryHandlerDef): unknown;
-};
-
 function defaultCrudVerbs(entity: EntityDefinition): Record<EntityCrudVerb, boolean> {
   return {
     create: true,

package/src/engine/feature-ast/__tests__/canonical-form.test.ts

@@ -78,6 +78,15 @@ defineFeature("todoList", (r) => {
     access: { openToAll: true },
   });
 
+  r.streamHandler({
+    name: "task:stream",
+    schema: z.object({ prompt: z.string() }),
+    handler: async function* (input, ctx) {
+      yield "token";
+    },
+    access: { roles: ["user"] },
+  });
+
   r.hook({
     type: "postSave",
     target: "task",
@@ -195,7 +204,7 @@ describe("Canonical Object-Form — parser akzeptiert + extrahiert", () => {
     expect(unknowns).toEqual([]);
   });
 
-  test("alle 28 Pattern-Kinds sind erfasst", () => {
+  test("alle Pattern-Kinds sind erfasst", () => {
     const kinds: ReadonlySet<string> = new Set(result.patterns.map((p) => p.kind));
     const expected = [
       // Static
@@ -219,6 +228,7 @@ describe("Canonical Object-Form — parser akzeptiert + extrahiert", () => {
       "screen",
       "writeHandler",
       "queryHandler",
+      "streamHandler",
       "hook",
       "job",
       "notification",