@cosmicdrift/kumiko-framework 0.158.2 → 0.160.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

@@ -2,6 +2,7 @@ import type { ZodType, z } from "zod";
 import { LifecycleHookTypes } from "./constants";
 import type {
   AuthClaimsFn,
+  BootCheckFn,
   ClaimKeyDefinition,
   ConfigKeyDefinition,
   ConfigSeedDef,
@@ -29,6 +30,7 @@ import type {
   SearchPayloadContributorFn,
   SecretKeyDefinition,
   StoreTableEntry,
+  StreamHandlerDef,
   TranslationKeys,
   TreeActionDef,
   UiHints,
@@ -56,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<
@@ -79,6 +82,7 @@ export type FeatureBuilderState = {
   extensionSelectors: ExtensionSelectorDef[];
   exposedApis: Set<string>;
   usedApis: Set<string>;
+  bootChecks: BootCheckFn[];
   referenceData: ReferenceDataDef[];
   handlerEntityMappings: Record<string, string>;
   metrics: Record<string, FeatureMetricDef>;
@@ -117,6 +121,7 @@ export function createInitialFeatureBuilderState(): FeatureBuilderState {
     relations: {},
     writeHandlers: {},
     queryHandlers: {},
+    streamHandlers: {},
     validationHooks: {},
     lifecycleHooks,
     phasedLifecycleHooks: { postSave: {}, preDelete: {}, postDelete: {} },
@@ -137,6 +142,7 @@ export function createInitialFeatureBuilderState(): FeatureBuilderState {
     extensionSelectors: [],
     exposedApis: new Set(),
     usedApis: new Set(),
+    bootChecks: [],
     referenceData: [],
     handlerEntityMappings: {},
     metrics: {},

package/src/engine/feature-config-events-jobs.ts

@@ -1,5 +1,6 @@
 import { ZodObject, type ZodType, type z } from "zod";
 import type { FeatureBuilderState } from "./feature-builder-state";
+import { resolveName } from "./handler-helpers";
 import { splitNamedDefinition, unwrapArrayForm } from "./object-form";
 import { QnTypes, qn, toKebab } from "./qualified-name";
 import type {
@@ -26,7 +27,6 @@ import type {
   SecretOptions,
   TranslationsDef,
 } from "./types";
-import { resolveName } from "./types/handlers";
 
 // Builds config/secrets/claims/events/jobs/notifications registrar methods.
 export function buildConfigEventsJobsMethods<TName extends string>(

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

@@ -1,9 +1,14 @@
 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";
+import { resolveName } from "./handler-helpers";
 import { splitNamedDefinition } from "./object-form";
 import type {
   AccessRule,
@@ -14,9 +19,9 @@ import type {
   QueryHandlerFn,
   RateLimitOption,
   RelationDefinition,
+  StreamHandlerFn,
   WriteHandlerFn,
 } from "./types";
-import { resolveName } from "./types/handlers";
 import type { PipelineDef } from "./types/step";
 
 const CRUD_VERBS = new Set(["create", "update", "delete"]);
@@ -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/feature-ui-extensions.ts

@@ -1,8 +1,10 @@
 import type { EntityTableMeta } from "../db/entity-table-meta";
 import { LifecycleHookTypes } from "./constants";
 import type { FeatureBuilderState } from "./feature-builder-state";
+import { resolveName } from "./handler-helpers";
 import { isKebabSegment, toKebab } from "./qualified-name";
 import type {
+  BootCheckFn,
   EntityProjectionExtension,
   HookPhase,
   LifecycleHookFn,
@@ -22,7 +24,6 @@ import type {
   ValidationHookFn,
 } from "./types";
 import { HookPhases } from "./types";
-import { resolveName } from "./types/handlers";
 import type { HttpRouteDefinition } from "./types/http-route";
 import type { NavDefinition } from "./types/nav";
 import type { ScreenDefinition } from "./types/screen";
@@ -255,6 +256,9 @@ export function buildUiExtensionsMethods<TName extends string>(
     usesApi(apiName: string): void {
       state.usedApis.add(apiName);
     },
+    bootCheck(fn: BootCheckFn): void {
+      state.bootChecks.push(fn);
+    },
     projection(definition: ProjectionDefinition): void {
       // Reject names that would blow up at registry-boot when we qualify them.
       // Catch it at the registration site so the stack trace points at the

package/src/engine/field-helpers.ts

@@ -0,0 +1,31 @@
+import type { AnyFileFieldDef, FieldDefinition } from "./types/fields";
+
+// --- Currency ---
+
+export const DEFAULT_CURRENCIES = [
+  "EUR",
+  "USD",
+  "GBP",
+  "CHF",
+  "JPY",
+  "SEK",
+  "NOK",
+  "DKK",
+  "PLN",
+  "CZK",
+  "CAD",
+  "AUD",
+  "NZD",
+  "CNY",
+  "INR",
+] as const;
+
+export function isFileField(field: FieldDefinition | undefined): field is AnyFileFieldDef {
+  if (!field) return false;
+  return (
+    field.type === "file" ||
+    field.type === "image" ||
+    field.type === "files" ||
+    field.type === "images"
+  );
+}

package/src/engine/handler-helpers.ts

@@ -0,0 +1,26 @@
+import type { NameOrRef, WriteResult } from "./types/handlers";
+
+/**
+ * Override the success-side `data` of a WriteResult while forwarding the
+ * failure half untouched. Useful for handlers that delegate to the
+ * event-store executor (which returns a SaveContext / DeleteContext
+ * envelope) but want to keep their own response shape — caller contract
+ * stays flat instead of leaking the executor's internals.
+ *
+ * ```ts
+ * const result = await executor.delete({ id }, user, db);
+ * return withResponseData(result, { userId, tenantId });
+ * ```
+ *
+ * On failure the same WriteFailure instance is returned — the error
+ * object round-trips without any wrapping, so the dispatcher / HTTP layer
+ * still read the original error code + httpStatus + i18nKey.
+ */
+export function withResponseData<T>(result: WriteResult<unknown>, data: T): WriteResult<T> {
+  if (!result.isSuccess) return result;
+  return { isSuccess: true, data };
+}
+
+export function resolveName(ref: NameOrRef): string {
+  return typeof ref === "string" ? ref : ref.name;
+}

package/src/engine/hook-helpers.ts

@@ -0,0 +1,14 @@
+// --- Hook Phases ---
+//
+// inTransaction: Hook runs inside the DB transaction. Failures roll back
+//   the entire write. Use for: DB-based side-effects (counter updates,
+//   dependent entity writes).
+//
+// afterCommit (default): Hook runs after the transaction commits. Failures
+//   are logged but don't affect the write. Use for: external systems
+//   (SSE broadcast, search index, email, webhooks).
+
+export const HookPhases = {
+  inTransaction: "inTransaction",
+  afterCommit: "afterCommit",
+} as const;