@cosmicdrift/kumiko-framework 0.159.1 → 0.161.0

package/src/engine/feature-ast/__tests__/patch.test.ts

@@ -384,3 +384,171 @@ defineFeature("legacy", (r) => {
     expect(text).not.toContain('r.entity("item"');
   });
 });
+
+describe("addPattern — error paths", () => {
+  test("throws when no defineFeature call is present", () => {
+    const sf = makeSourceFile("export const x = 1;");
+    expect(() => addPattern(sf, newSecretPattern)).toThrow(/no defineFeature/);
+  });
+});
+
+describe("callMatchesId — positional and object-form lookups", () => {
+  const LEGACY = `
+import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+
+defineFeature("legacy", (r) => {
+  r.relation("task", "owner", { kind: "belongsTo", to: "user" });
+
+  r.hook("postSave", "task", () => {});
+
+  r.hook("preDelete", { allOf: "task" }, () => {});
+
+  r.job("nightly", { trigger: { cron: "0 0 * * *" } }, async () => {});
+
+  r.writeHandler("task:create", z.object({}), async () => ({}));
+
+  r.queryHandler("task:list", z.object({}), async () => []);
+
+  r.notification("taskCreated", {
+    trigger: { on: "task" },
+    recipient: () => ({}),
+    data: () => ({}),
+  });
+});
+`;
+
+  test("removePattern finds a positional relation by entity+name", () => {
+    const sf = makeSourceFile(LEGACY);
+    removePattern(sf, { kind: "relation", entityName: "task", relationName: "owner" });
+    expect(parseSourceFile(sf).patterns.find((p) => p.kind === "relation")).toBeUndefined();
+  });
+
+  test("removePattern finds a positional hook by type+string target", () => {
+    const sf = makeSourceFile(LEGACY);
+    removePattern(sf, { kind: "hook", hookType: "postSave", target: "task" });
+    expect(parseSourceFile(sf).patterns.filter((p) => p.kind === "hook")).toHaveLength(1);
+  });
+
+  test("removePattern finds a positional hook with an allOf target", () => {
+    const sf = makeSourceFile(LEGACY);
+    removePattern(sf, { kind: "hook", hookType: "preDelete", target: { allOf: "task" } });
+    expect(parseSourceFile(sf).patterns.filter((p) => p.kind === "hook")).toHaveLength(1);
+  });
+
+  test("removePattern finds a positional job by name", () => {
+    const sf = makeSourceFile(LEGACY);
+    removePattern(sf, { kind: "job", jobName: "nightly" });
+    expect(parseSourceFile(sf).patterns.find((p) => p.kind === "job")).toBeUndefined();
+  });
+
+  test("removePattern finds a writeHandler by positional name", () => {
+    const sf = makeSourceFile(LEGACY);
+    removePattern(sf, { kind: "writeHandler", handlerName: "task:create" });
+    expect(parseSourceFile(sf).patterns.find((p) => p.kind === "writeHandler")).toBeUndefined();
+  });
+
+  test("removePattern finds a queryHandler by positional name", () => {
+    const sf = makeSourceFile(LEGACY);
+    removePattern(sf, { kind: "queryHandler", handlerName: "task:list" });
+    expect(parseSourceFile(sf).patterns.find((p) => p.kind === "queryHandler")).toBeUndefined();
+  });
+
+  test("removePattern finds a positional notification by name", () => {
+    const sf = makeSourceFile(LEGACY);
+    removePattern(sf, { kind: "notification", notificationName: "taskCreated" });
+    expect(parseSourceFile(sf).patterns.find((p) => p.kind === "notification")).toBeUndefined();
+  });
+});
+
+describe("removePattern — blank-line collapse", () => {
+  test("removing an appended pattern collapses the preceding blank line", () => {
+    const sf = makeSourceFile(STARTER);
+    addPattern(sf, newSecretPattern);
+    const linesBefore = sf.getFullText().split("\n").length;
+    removePattern(sf, { kind: "secret", shortName: "stripeKey" });
+    const linesAfter = sf.getFullText().split("\n").length;
+    expect(linesAfter).toBeLessThan(linesBefore);
+    expect(parseSourceFile(sf).patterns.map((p) => p.kind)).toEqual(["entity", "metric"]);
+  });
+});
+
+describe("replacePattern — object-form hook with allOf target", () => {
+  test("replaces an object-form hook registered with an allOf target", () => {
+    const file = `
+import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+
+defineFeature("hooks", (r) => {
+  r.hook({ type: "postSave", target: { allOf: "task" }, handler: () => {} });
+});
+`;
+    const sf = makeSourceFile(file);
+    replacePattern(
+      sf,
+      { kind: "hook", hookType: "postSave", target: { allOf: "task" } },
+      {
+        kind: "hook",
+        source: SAMPLE_LOC,
+        hookType: "postSave",
+        target: { allOf: "task" },
+        fnBody: { ...SAMPLE_LOC, raw: "() => { /* updated */ }" },
+      },
+    );
+    expect(sf.getFullText()).toContain("/* updated */");
+  });
+});
+describe("callMatchesId — object-form lookups", () => {
+  const OBJECT_FORM = `
+import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+
+defineFeature("object", (r) => {
+  r.relation({ entity: "task", name: "owner", kind: "belongsTo", to: "user" });
+
+  r.job({ name: "nightly", trigger: { cron: "0 0 * * *" }, handler: async () => {} });
+
+  r.useExtension({ name: "audit", entity: "task" });
+
+  r.writeHandler({
+    name: "task:create",
+    schema: z.object({}),
+    handler: async () => ({}),
+  });
+
+  r.notification({
+    name: "taskCreated",
+    trigger: { on: "task" },
+    recipient: () => ({}),
+    data: () => ({}),
+  });
+});
+`;
+
+  test("removePattern finds an object-form relation", () => {
+    const sf = makeSourceFile(OBJECT_FORM);
+    removePattern(sf, { kind: "relation", entityName: "task", relationName: "owner" });
+    expect(parseSourceFile(sf).patterns.find((p) => p.kind === "relation")).toBeUndefined();
+  });
+
+  test("removePattern finds an object-form job", () => {
+    const sf = makeSourceFile(OBJECT_FORM);
+    removePattern(sf, { kind: "job", jobName: "nightly" });
+    expect(parseSourceFile(sf).patterns.find((p) => p.kind === "job")).toBeUndefined();
+  });
+
+  test("removePattern finds an object-form useExtension", () => {
+    const sf = makeSourceFile(OBJECT_FORM);
+    removePattern(sf, { kind: "useExtension", extensionName: "audit", entityName: "task" });
+    expect(parseSourceFile(sf).patterns.find((p) => p.kind === "useExtension")).toBeUndefined();
+  });
+
+  test("removePattern finds an object-form writeHandler", () => {
+    const sf = makeSourceFile(OBJECT_FORM);
+    removePattern(sf, { kind: "writeHandler", handlerName: "task:create" });
+    expect(parseSourceFile(sf).patterns.find((p) => p.kind === "writeHandler")).toBeUndefined();
+  });
+
+  test("removePattern finds an object-form notification", () => {
+    const sf = makeSourceFile(OBJECT_FORM);
+    removePattern(sf, { kind: "notification", notificationName: "taskCreated" });
+    expect(parseSourceFile(sf).patterns.find((p) => p.kind === "notification")).toBeUndefined();
+  });
+});

package/src/engine/feature-ast/__tests__/patcher.test.ts

@@ -442,6 +442,12 @@ defineFeature("tasks", (r) => {
       handlerSource: "async (q, ctx) => []",
       access: { openToAll: true },
     });
+    p.addStreamHandler({
+      name: "task:stream",
+      schemaSource: "z.object({ prompt: z.string() })",
+      handlerSource: 'async function* (input, ctx) { yield "token"; }',
+      access: { roles: ["user"] },
+    });
     p.addHook({
       type: "postDelete",
       target: { allOf: "task" },
@@ -453,6 +459,7 @@ defineFeature("tasks", (r) => {
       "entity",
       "writeHandler",
       "queryHandler",
+      "streamHandler",
       "hook",
     ]);
   });

package/src/engine/feature-ast/__tests__/render-roundtrip.test.ts

@@ -206,6 +206,15 @@ defineFeature("workflow", (r) => {
     { access: { openToAll: true } },
   );
 
+  r.streamHandler(
+    "step:stream",
+    z.object({ prompt: z.string() }),
+    async function* (input, ctx) {
+      yield "token";
+    },
+    { access: { roles: ["user"] } },
+  );
+
   r.hook("postSave", "step", async (event, ctx) => {
     console.log("step saved");
   });

package/src/engine/feature-ast/extractors/handlers.ts

@@ -1,7 +1,7 @@
 import type { CallExpression, Node, SourceFile } from "ts-morph";
 import { SyntaxKind } from "ts-morph";
 import type { AccessRule, RateLimitOption } from "../../types/handlers";
-import type { QueryHandlerPattern, WriteHandlerPattern } from "../patterns";
+import type { QueryHandlerPattern, StreamHandlerPattern, WriteHandlerPattern } from "../patterns";
 import type { SourceLocation } from "../source-location";
 import { sourceLocationFromNode } from "../source-location";
 import { readOptionalAccessRule, readOptionalRateLimit } from "./hooks";
@@ -44,7 +44,7 @@ function resolveObjectLiteralArg(node: Node) {
 export function parseHandlerCall(
   call: CallExpression,
   sourceFile: SourceFile,
-  methodName: "writeHandler" | "queryHandler",
+  methodName: "writeHandler" | "queryHandler" | "streamHandler",
 ): ExtractOutput<ParsedHandlerCall> {
   const args = call.getArguments();
   const first = args[0];
@@ -220,3 +220,20 @@ export function extractQueryHandler(
     ...(parsed.pattern.rateLimit !== undefined && { rateLimit: parsed.pattern.rateLimit }),
   });
 }
+
+export function extractStreamHandler(
+  call: CallExpression,
+  sourceFile: SourceFile,
+): ExtractOutput<StreamHandlerPattern> {
+  const parsed = parseHandlerCall(call, sourceFile, "streamHandler");
+  if (parsed.kind === "error") return parsed;
+  return ok({
+    kind: "streamHandler",
+    source: parsed.pattern.source,
+    handlerName: parsed.pattern.handlerName,
+    schemaSource: parsed.pattern.schemaSource,
+    handlerBody: parsed.pattern.handlerBody,
+    ...(parsed.pattern.access !== undefined && { access: parsed.pattern.access }),
+    ...(parsed.pattern.rateLimit !== undefined && { rateLimit: parsed.pattern.rateLimit }),
+  });
+}

package/src/engine/feature-ast/extractors/index.ts

@@ -4,6 +4,7 @@ export {
 } from "./events";
 export {
   extractQueryHandler,
+  extractStreamHandler,
   extractWriteHandler,
   type ParsedHandlerCall,
   parseHandlerCall,

package/src/engine/feature-ast/index.ts

@@ -43,6 +43,7 @@ export type {
   AddRequiresArgs,
   AddScreenArgs,
   AddSecretArgs,
+  AddStreamHandlerArgs,
   AddToggleableArgs,
   AddTranslationsArgs,
   AddUseExtensionArgs,
@@ -79,6 +80,7 @@ export type {
   // Mixed patterns
   ScreenPattern,
   SecretPattern,
+  StreamHandlerPattern,
   SystemScopePattern,
   ToggleablePattern,
   TranslationsPattern,

package/src/engine/feature-ast/parse.ts

@@ -58,6 +58,7 @@ import {
   extractScreen,
   extractSecret,
   extractStoreTable,
+  extractStreamHandler,
   extractSystemScope,
   extractToggleable,
   extractTranslations,
@@ -447,6 +448,8 @@ function dispatchExtractor(
       return extractWriteHandler(call, sourceFile);
     case "queryHandler":
       return extractQueryHandler(call, sourceFile);
+    case "streamHandler":
+      return extractStreamHandler(call, sourceFile);
     case "job":
       return extractJob(call, sourceFile);
     case "httpRoute":

package/src/engine/feature-ast/patch.ts

@@ -53,6 +53,7 @@ export type PatternId =
   | { readonly kind: "screen"; readonly id: string }
   | { readonly kind: "writeHandler"; readonly handlerName: string }
   | { readonly kind: "queryHandler"; readonly handlerName: string }
+  | { readonly kind: "streamHandler"; readonly handlerName: string }
   | {
       readonly kind: "hook";
       readonly hookType: string;
@@ -353,6 +354,7 @@ function callMatchesId(call: CallExpression, id: PatternId): boolean {
       return matchObjectProperty(call, "id", id.id);
     case "writeHandler":
     case "queryHandler":
+    case "streamHandler":
       return (
         matchFirstArgString(call, id.handlerName) ||
         matchObjectProperty(call, "name", id.handlerName)

package/src/engine/feature-ast/patcher.ts

@@ -104,6 +104,14 @@ export type AddQueryHandlerArgs = {
   readonly rateLimit?: RateLimitOption;
 };
 
+export type AddStreamHandlerArgs = {
+  readonly name: string;
+  readonly schemaSource: string;
+  readonly handlerSource: string;
+  readonly access?: AccessRule;
+  readonly rateLimit?: RateLimitOption;
+};
+
 export type AddHookArgs = {
   readonly type: LifecycleHookType | "validation";
   // `{ allOf: entity }` — entity-wide target, fires for every write/query
@@ -233,6 +241,7 @@ export type FeaturePatcher = {
   readonly addScreen: (args: AddScreenArgs) => void;
   readonly addWriteHandler: (args: AddWriteHandlerArgs) => void;
   readonly addQueryHandler: (args: AddQueryHandlerArgs) => void;
+  readonly addStreamHandler: (args: AddStreamHandlerArgs) => void;
   readonly addHook: (args: AddHookArgs) => void;
   readonly addJob: (args: AddJobArgs) => void;
   readonly addNotification: (args: AddNotificationArgs) => void;
@@ -392,6 +401,18 @@ export function createFeaturePatcher(sourceFile: SourceFile): FeaturePatcher {
       });
     },
 
+    addStreamHandler({ name, schemaSource, handlerSource, access, rateLimit }) {
+      add({
+        kind: "streamHandler",
+        source: SYNTHETIC_LOC,
+        handlerName: name,
+        schemaSource: rawLoc(schemaSource),
+        handlerBody: rawLoc(handlerSource),
+        ...(access !== undefined && { access }),
+        ...(rateLimit !== undefined && { rateLimit }),
+      });
+    },
+
     addHook({ type, target, handlerSource, phase }) {
       add({
         kind: "hook",

package/src/engine/feature-ast/patterns.ts

@@ -374,6 +374,20 @@ export type QueryHandlerPattern = {
   readonly rateLimit?: RateLimitOption;
 };
 
+// `r.streamHandler(...)` — registers a streaming read handler: name, Zod
+// input schema, async-generator handler closure, plus optional `access` and
+// `rateLimit` rules. Same header/body split and opaque single-reference
+// case as QueryHandlerPattern.
+export type StreamHandlerPattern = {
+  readonly kind: "streamHandler";
+  readonly source: SourceLocation;
+  readonly handlerName?: string;
+  readonly schemaSource?: SourceLocation;
+  readonly handlerBody?: SourceLocation;
+  readonly access?: AccessRule;
+  readonly rateLimit?: RateLimitOption;
+};
+
 // `r.hook(type, target, fn, options?)` — attaches a lifecycle hook
 // (`validation`, `preSave`, `postSave`, `preDelete`, `postDelete`,
 // `preQuery`, `postQuery`) to one or more target handlers, or — for
@@ -592,6 +606,7 @@ export type FeaturePattern =
   | ScreenPattern
   | WriteHandlerPattern
   | QueryHandlerPattern
+  | StreamHandlerPattern
   | HookPattern
   | JobPattern
   | NotificationPattern
@@ -647,6 +662,7 @@ export function getEditability(pattern: FeaturePattern): Editability {
     case "screen":
     case "writeHandler":
     case "queryHandler":
+    case "streamHandler":
     case "hook":
     case "job":
     case "notification":

package/src/engine/feature-ast/render.ts

@@ -44,6 +44,7 @@ import type {
   RequiresPattern,
   ScreenPattern,
   SecretPattern,
+  StreamHandlerPattern,
   SystemScopePattern,
   ToggleablePattern,
   TranslationsPattern,
@@ -109,6 +110,8 @@ export function renderPattern(pattern: FeaturePattern): string {
       return renderWriteHandler(pattern);
     case "queryHandler":
       return renderQueryHandler(pattern);
+    case "streamHandler":
+      return renderStreamHandler(pattern);
     case "hook":
       return renderHook(pattern);
     case "job":
@@ -395,6 +398,18 @@ function renderQueryHandler(p: QueryHandlerPattern): string {
   return lines.join("\n");
 }
 
+function renderStreamHandler(p: StreamHandlerPattern): string {
+  if (p.handlerName === undefined) return p.source.raw;
+  const lines: string[] = ["r.streamHandler({"];
+  lines.push(`  name: ${JSON.stringify(p.handlerName)},`);
+  lines.push(`  schema: ${reindentBody(p.schemaSource?.raw ?? "", PATTERN_INDENT)},`);
+  lines.push(`  handler: ${reindentBody(p.handlerBody?.raw ?? "", PATTERN_INDENT)},`);
+  if (p.access !== undefined) lines.push(`  access: ${renderValue(p.access)},`);
+  if (p.rateLimit !== undefined) lines.push(`  rateLimit: ${renderValue(p.rateLimit)},`);
+  lines.push("});");
+  return lines.join("\n");
+}
+
 function renderHookTarget(target: HookPattern["target"]): string {
   if (typeof target === "string") return renderValue(target);
   if ("allOf" in target) return `{ allOf: ${JSON.stringify(target.allOf)} }`;

package/src/engine/feature-builder-state.ts

@@ -30,6 +30,7 @@ import type {
   SearchPayloadContributorFn,
   SecretKeyDefinition,
   StoreTableEntry,
+  StreamHandlerDef,
   TranslationKeys,
   TreeActionDef,
   UiHints,
@@ -57,6 +58,7 @@ export type FeatureBuilderState = {
   relations: Record<string, Record<string, RelationDefinition>>;
   writeHandlers: Record<string, WriteHandlerDef>;
   queryHandlers: Record<string, QueryHandlerDef>;
+  streamHandlers: Record<string, StreamHandlerDef>;
   validationHooks: Record<string, ValidationHookFn>;
   lifecycleHooks: Record<string, Record<string, OwnedFn<LifecycleHookFn>[]>>;
   phasedLifecycleHooks: Record<
@@ -119,6 +121,7 @@ export function createInitialFeatureBuilderState(): FeatureBuilderState {
     relations: {},
     writeHandlers: {},
     queryHandlers: {},
+    streamHandlers: {},
     validationHooks: {},
     lifecycleHooks,
     phasedLifecycleHooks: { postSave: {}, preDelete: {}, postDelete: {} },

package/src/engine/feature-entity-handlers.ts

@@ -1,6 +1,10 @@
 import type { ZodType, z } from "zod";
 import { toTableName } from "../db/table-builder";
-import type { QueryHandlerDefinition, WriteHandlerDefinition } from "./define-handler";
+import type {
+  QueryHandlerDefinition,
+  StreamHandlerDefinition,
+  WriteHandlerDefinition,
+} from "./define-handler";
 import type { RegisterEntityCrudOptions } from "./entity-handlers";
 import { registerEntityCrud } from "./entity-handlers";
 import type { FeatureBuilderState } from "./feature-builder-state";
@@ -15,6 +19,7 @@ import type {
   QueryHandlerFn,
   RateLimitOption,
   RelationDefinition,
+  StreamHandlerFn,
   WriteHandlerFn,
 } from "./types";
 import type { PipelineDef } from "./types/step";
@@ -164,6 +169,35 @@ export function buildEntityHandlerMethods<TName extends string>(
       tryMapEntity(state, name, nameOrDef);
       return { name: nameOrDef };
     },
+    streamHandler<TName extends string, TSchema extends ZodType>(
+      nameOrDef: string | StreamHandlerDefinition<TName, TSchema>,
+      schema?: TSchema,
+      handler?: StreamHandlerFn<z.infer<TSchema>>,
+      options?: { access?: AccessRule; rateLimit?: RateLimitOption },
+    ): HandlerRef {
+      if (typeof nameOrDef === "object") {
+        const def = nameOrDef;
+        state.streamHandlers[def.name] = {
+          name: def.name,
+          schema: def.schema,
+          // @cast-boundary engine-bridge — typed Dev-API → erased internal storage
+          handler: def.handler as StreamHandlerFn, // @cast-boundary engine-bridge
+          ...(def.access && { access: def.access }),
+          ...(def.rateLimit && { rateLimit: def.rateLimit }),
+        };
+        return { name: def.name };
+      }
+      if (!schema || !handler)
+        throw new Error("streamHandler inline form requires schema + handler");
+      state.streamHandlers[nameOrDef] = {
+        name: nameOrDef,
+        schema,
+        handler: handler as StreamHandlerFn, // @cast-boundary engine-bridge
+        ...(options?.access && { access: options.access }),
+        ...(options?.rateLimit && { rateLimit: options.rateLimit }),
+      };
+      return { name: nameOrDef };
+    },
   };
   return {
     ...methods,

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";
@@ -364,6 +365,8 @@ export type {
   SecretKeyHandle,
   SelectFieldDef,
   SessionUser,
+  StreamHandlerDef,
+  StreamHandlerFn,
   Subscribe,
   TargetRef,
   TenantId,

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(),