@cosmicdrift/kumiko-framework 1.0.0 → 2.0.0

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

@@ -0,0 +1,403 @@
+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 {
+  AuthClaimsFn,
+  ClaimKeyHandle,
+  ClaimKeyType,
+  ConfigKeyDefinition,
+  ConfigKeyHandle,
+  ConfigKeyType,
+  ConfigSeedDef,
+  DeclarativeEventMigration,
+  EventDef,
+  EventPiiFields,
+  EventUpcastFn,
+  JobDefinition,
+  JobHandlerFn,
+  MetricOptions,
+  NameOrRef,
+  NotificationDataFn,
+  NotificationRecipientFn,
+  NotificationTemplateFn,
+  QualifiedEventName,
+  SecretKeyHandle,
+  SecretOptions,
+  TranslationsDef,
+} from "./types";
+
+// Builds config/secrets/claims/events/jobs/notifications registrar methods.
+export function buildConfigEventsJobsMethods<TName extends string>(
+  state: FeatureBuilderState,
+  name: TName,
+) {
+  // Overloaded: (keyName, def) for the single-key case, ({keys, seeds}) for
+  // the multi-key case — both funnel through the same qualify/register loop
+  // below, so a single-key call is byte-identical to what
+  // `{keys:{name:def}}` would have produced.
+  function config<T extends ConfigKeyType>(
+    keyName: string,
+    def: ConfigKeyDefinition<T>,
+  ): ConfigKeyHandle<T>;
+  function config<
+    TKeys extends Readonly<Record<string, ConfigKeyDefinition<ConfigKeyType>>>,
+  >(definition: {
+    readonly keys: TKeys;
+    readonly seeds?: Readonly<Record<string, ConfigSeedDef>>;
+  }): { readonly [K in keyof TKeys]: ConfigKeyHandle<TKeys[K]["type"]> };
+  function config(
+    arg1:
+      | string
+      | {
+          readonly keys: Record<string, ConfigKeyDefinition<ConfigKeyType>>;
+          readonly seeds?: Readonly<Record<string, ConfigSeedDef>>;
+        },
+    arg2?: ConfigKeyDefinition<ConfigKeyType>,
+  ): unknown {
+    // arg2 is always defined here — the two public overloads above guarantee
+    // it whenever arg1 is a string; the impl signature just has to widen it
+    // to optional to satisfy both call shapes.
+    const definition = typeof arg1 === "string" && arg2 ? { keys: { [arg1]: arg2 } } : arg1;
+    if (typeof definition === "string") {
+      throw new Error("config(): single-key form requires a definition as the second argument");
+    }
+    // Qualify eagerly (same as defineEvent) so the handle name matches what
+    // the registry stores — lazy qualification would break compile-time
+    // autocomplete and hand-built test registries.
+    const handles: Record<string, ConfigKeyHandle<ConfigKeyType>> = {};
+    for (const [key, keyDef] of Object.entries(definition.keys)) {
+      state.configKeys[key] = keyDef;
+      handles[key] = {
+        name: qn(toKebab(name), "config", toKebab(key)),
+        type: keyDef.type,
+      };
+    }
+    // Parse seeds: resolve qualified key names and validate scope
+    if (definition.seeds) {
+      for (const [shortKey, seedDef] of Object.entries(definition.seeds)) {
+        const keyDef = definition.keys[shortKey];
+        if (!keyDef) continue; // skip — boot-validator reports unknown keys
+        const qualifiedKey = qn(toKebab(name), "config", toKebab(shortKey));
+        const scope = seedDef.scope ?? keyDef.scope;
+        state.configSeeds.push({
+          key: qualifiedKey,
+          value: seedDef.value,
+          scope,
+          tenantId: seedDef.tenantId,
+          userId: seedDef.userId,
+        });
+      }
+    }
+    // Single-key call unwraps its own handle; multi-key returns the record.
+    return typeof arg1 === "string" ? handles[arg1] : handles;
+  }
+
+  // piiFields misconfiguration is a boot-time error, not a silent
+  // plaintext leak: both the pii field and its subjectField must exist
+  // on the payload schema (checkable when the schema is a ZodObject).
+  function validateEventPiiFields(
+    eventName: string,
+    schema: ZodType,
+    piiFields: EventPiiFields,
+  ): void {
+    const shape = schema instanceof ZodObject ? schema.shape : undefined;
+    for (const [field, spec] of Object.entries(piiFields)) {
+      if (field === spec.subjectField) {
+        throw new Error(
+          `[Feature ${name}] defineEvent("${eventName}"): piiFields."${field}" cannot use itself as subjectField — the subject id is a plaintext pseudonymous fk, the pii field is the value it owns.`,
+        );
+      }
+      for (const required of [field, spec.subjectField]) {
+        if (shape && !(required in shape)) {
+          throw new Error(
+            `[Feature ${name}] defineEvent("${eventName}"): piiFields references "${required}" which is not a field of the payload schema.`,
+          );
+        }
+      }
+    }
+  }
+
+  // Shared by defineEvent's `migrations` option — each entry registers a
+  // single upcast step, same validation/dedup as the old standalone
+  // r.eventMigration() call (folded into defineEvent, #1082 step 8).
+  function registerEventMigration(
+    eventName: string,
+    fromVersion: number,
+    toVersion: number,
+    transform: EventUpcastFn | DeclarativeEventMigration,
+  ): void {
+    if (toVersion !== fromVersion + 1) {
+      throw new Error(
+        `[Feature ${name}] defineEvent("${eventName}") migrations: only single-step migrations are allowed — toVersion must be fromVersion + 1 (got ${fromVersion} -> ${toVersion}). ` +
+          `Chain larger jumps by declaring each step separately.`,
+      );
+    }
+    if (!Number.isInteger(fromVersion) || fromVersion < 1) {
+      throw new Error(
+        `[Feature ${name}] defineEvent("${eventName}") migrations: fromVersion must be >= 1, got ${String(fromVersion)}`,
+      );
+    }
+    const qualified = qn(toKebab(name), "event", toKebab(eventName));
+    const list = state.eventMigrations[eventName] ?? [];
+    if (list.some((m) => m.fromVersion === fromVersion)) {
+      throw new Error(
+        `[Feature ${name}] defineEvent("${eventName}") migrations: a migration from v${fromVersion} is already declared. Each step may only be declared once.`,
+      );
+    }
+    const transformFn =
+      typeof transform === "function" ? transform : compileEventMigration(transform);
+    list.push({ eventName: qualified, fromVersion, toVersion, transform: transformFn });
+    state.eventMigrations[eventName] = list;
+  }
+
+  return {
+    config,
+    job(
+      jobNameOrDefinition: string | JobDefinition,
+      options?: Omit<JobDefinition, "name" | "handler">,
+      handler?: JobHandlerFn,
+    ): void {
+      const [jobName, jobOptions, jobHandler] =
+        typeof jobNameOrDefinition === "string"
+          ? [
+              jobNameOrDefinition,
+              options as Omit<JobDefinition, "name" | "handler">,
+              handler as JobHandlerFn,
+            ]
+          : (() => {
+              const { name, handler: h, ...rest } = jobNameOrDefinition;
+              return [name, rest, h] as const;
+            })();
+      // Resolve NameOrRef(s) in trigger.on. Multi-Trigger-Form: Array
+      // wird zu Array von resolved strings, Single bleibt single string —
+      // job-runner unterscheidet anhand Array.isArray.
+      const trigger =
+        "on" in jobOptions.trigger
+          ? {
+              on: Array.isArray(jobOptions.trigger.on)
+                ? jobOptions.trigger.on.map(resolveName)
+                : resolveName(jobOptions.trigger.on as NameOrRef), // @cast-boundary engine-bridge
+            }
+          : jobOptions.trigger;
+      state.jobs[jobName] = { ...jobOptions, trigger, name: jobName, handler: jobHandler };
+    },
+    notification(
+      notificationNameOrDefinition:
+        | string
+        | ({ readonly name: string } & {
+            readonly trigger: { readonly on: NameOrRef };
+            readonly recipient: NotificationRecipientFn;
+            readonly data: NotificationDataFn;
+            readonly templates?: Readonly<Record<string, NotificationTemplateFn>>;
+          }),
+      definition?: {
+        readonly trigger: { readonly on: NameOrRef };
+        readonly recipient: NotificationRecipientFn;
+        readonly data: NotificationDataFn;
+        readonly templates?: Readonly<Record<string, NotificationTemplateFn>>;
+      },
+    ): void {
+      const [notificationName, resolvedDefinition] =
+        typeof notificationNameOrDefinition === "string"
+          ? [notificationNameOrDefinition, definition as NonNullable<typeof definition>]
+          : splitNamedDefinition(notificationNameOrDefinition);
+      state.notifications[notificationName] = {
+        name: notificationName,
+        trigger: { on: resolveName(resolvedDefinition.trigger.on) },
+        recipient: resolvedDefinition.recipient,
+        data: resolvedDefinition.data,
+        templates: resolvedDefinition.templates,
+      };
+    },
+    translations(def: TranslationsDef): void {
+      state.translations = { ...state.translations, ...def.keys };
+    },
+    defineEvent: <const TInner extends string, TPayload>(
+      eventName: TInner,
+      schema: ZodType<TPayload>,
+      options?: {
+        readonly version?: number;
+        readonly piiFields?: EventPiiFields;
+        // Step-wise upcast chain for this event, folded in from the former
+        // standalone r.eventMigration() call (#1082 step 8) — an event and
+        // its schema evolution are one lifecycle, not two registrar
+        // concepts. Each entry's fromVersion must be unique and the chain
+        // from 1 to `version` must be gap-free (same validation as before).
+        readonly migrations?: readonly {
+          readonly fromVersion: number;
+          readonly toVersion: number;
+          readonly transform: EventUpcastFn | DeclarativeEventMigration;
+        }[];
+      },
+    ): EventDef<TPayload, QualifiedEventName<TName, TInner>> => {
+      // Return the fully-qualified event name so callers can pass it
+      // straight to ctx.appendEvent without hand-building the
+      // "<feature>:event:<name>" shape. Registry keeps events keyed by
+      // short name — qualification is the framework's job, not the feature
+      // author's.
+      //
+      // The runtime kebab-step (`qn(toKebab(feature), …)`) is mirrored at
+      // the type-level by `QualifiedEventName<TName, TInner>` so the
+      // returned `name` carries the literal qualified shape that the
+      // augmented `KumikoEventTypeMap` keys against.
+      const qualified = qn(toKebab(name), "event", toKebab(eventName));
+      const version = options?.version ?? 1;
+      if (!Number.isInteger(version) || version < 1) {
+        throw new Error(
+          `[Feature ${name}] defineEvent("${eventName}"): version must be a positive integer, got ${String(version)}`,
+        );
+      }
+      const piiFields = options?.piiFields;
+      if (piiFields) {
+        validateEventPiiFields(eventName, schema, piiFields);
+      }
+      // @cast-boundary engine-bridge — runtime-string mirrors the
+      // template-literal-type via QualifiedEventName + toKebab. Both
+      // sides are tested (CamelToKebab type-tests + scan-events kebab
+      // tests), so the cast is a contract, not a typing-loss.
+      const def: EventDef<TPayload, QualifiedEventName<TName, TInner>> = {
+        name: qualified as QualifiedEventName<TName, TInner>,
+        schema,
+        version,
+        ...(piiFields !== undefined && { piiFields }),
+      };
+      state.events[eventName] = def;
+      for (const m of options?.migrations ?? []) {
+        registerEventMigration(eventName, m.fromVersion, m.toVersion, m.transform);
+      }
+      return def;
+    },
+    readsConfig(
+      ...args: readonly [{ readonly keys: readonly string[] }] | readonly string[]
+    ): void {
+      state.configReads.push(...unwrapArrayForm(args, "keys"));
+    },
+    metric(
+      shortNameOrDefinition: string | ({ readonly name: string } & MetricOptions),
+      options?: MetricOptions,
+    ): void {
+      const [shortName, metricOptions] =
+        typeof shortNameOrDefinition === "string"
+          ? [shortNameOrDefinition, options as MetricOptions]
+          : splitNamedDefinition(shortNameOrDefinition);
+      if (state.metrics[shortName]) {
+        throw new Error(
+          `[Feature ${name}] Metric "${shortName}" already registered. ` +
+            `Metric names must be unique per feature.`,
+        );
+      }
+      state.metrics[shortName] = { shortName, ...metricOptions };
+    },
+    envSchema(schema: z.ZodObject<z.ZodRawShape>): void {
+      if (state.envSchema !== undefined) {
+        throw new Error(
+          `[Feature ${name}] r.envSchema() called twice — declare one composed Zod-object per feature.`,
+        );
+      }
+      state.envSchema = schema;
+    },
+    secret(
+      shortNameOrDefinition: string | ({ readonly name: string } & SecretOptions),
+      options?: SecretOptions,
+    ): SecretKeyHandle {
+      const [shortName, secretOptions] =
+        typeof shortNameOrDefinition === "string"
+          ? [shortNameOrDefinition, options as SecretOptions]
+          : splitNamedDefinition(shortNameOrDefinition);
+      if (state.secretKeys[shortName]) {
+        throw new Error(
+          `[Feature ${name}] Secret "${shortName}" already registered. ` +
+            `Secret key names must be unique per feature.`,
+        );
+      }
+      // Qualified name follows the framework's "<feature>:<type>:<name>"
+      // QN convention — same pattern config / jobs / events use. toKebab
+      // handles the common input shapes ("stripe.apiKey" → "stripe-api-key")
+      // so features can declare keys in their natural style without
+      // thinking about kebab-case on every call.
+      const qualifiedName = qn(toKebab(name), QnTypes.secret, toKebab(shortName));
+      state.secretKeys[shortName] = {
+        shortName,
+        qualifiedName,
+        ...secretOptions,
+      };
+      return { name: qualifiedName };
+    },
+    claimKey<T extends ClaimKeyType>(
+      shortNameOrDefinition: string | { readonly name: string; readonly type: T },
+      options?: { readonly type: T },
+    ): ClaimKeyHandle<T> {
+      const shortName =
+        typeof shortNameOrDefinition === "string"
+          ? shortNameOrDefinition
+          : shortNameOrDefinition.name;
+      const claimType: T =
+        typeof shortNameOrDefinition === "string"
+          ? (options as { readonly type: T }).type
+          : shortNameOrDefinition.type;
+      if (state.claimKeys[shortName]) {
+        throw new Error(
+          `[Feature ${name}] Claim key "${shortName}" already declared. ` +
+            "Claim short-names must be unique per feature.",
+        );
+      }
+      // Claim keys are NOT full QNs — the JWT shape is 2-segment
+      // "<featureName>:<shortName>" (same as Translation keys), not
+      // kebab-cased. The authClaims resolver prefixes with the raw
+      // feature.name + the raw inner key the hook returns, so the handle's
+      // `name` must match that literal string exactly for `readClaim` to
+      // find the value. kebab-conversion here would break the round-trip.
+      const qualifiedName = `${name}:${shortName}`;
+      state.claimKeys[shortName] = {
+        shortName,
+        qualifiedName,
+        type: claimType,
+      };
+      return { name: qualifiedName, type: claimType };
+    },
+    authClaims(fn: AuthClaimsFn): void {
+      state.authClaimsHooks.push(fn);
+    },
+  };
+}
+
+// Compile the declarative {rename, default, map} migration spec into an
+// EventUpcastFn. Fixed order: rename → default → map.
+function compileEventMigration(spec: DeclarativeEventMigration): EventUpcastFn {
+  // Registration-time (not replay-time) check: two rename sources mapping to
+  // the same target would silently drop one value on every future replay —
+  // event migrations run against the full production event history, so a
+  // typo here must fail loud at defineEvent() registration time, not at replay.
+  const renameTargets = new Map<string, string>();
+  for (const [from, to] of Object.entries(spec.rename ?? {})) {
+    const existing = renameTargets.get(to);
+    if (existing !== undefined) {
+      throw new Error(
+        `Declarative event migration: rename collision — both "${existing}" and "${from}" rename to "${to}". Only one source may map to a given target.`,
+      );
+    }
+    renameTargets.set(to, from);
+  }
+  return (payload) => {
+    if (payload === null || typeof payload !== "object" || Array.isArray(payload)) {
+      throw new Error("Declarative event migration expects an object payload");
+    }
+    // @cast-boundary parse — payload is guarded as a plain object above
+    const next = { ...(payload as Record<string, unknown>) };
+    for (const [from, to] of Object.entries(spec.rename ?? {})) {
+      if (from in next) {
+        next[to] = next[from];
+        delete next[from];
+      }
+    }
+    for (const [key, value] of Object.entries(spec.default ?? {})) {
+      if (!(key in next)) next[key] = value;
+    }
+    for (const [key, fn] of Object.entries(spec.map ?? {})) {
+      if (key in next) next[key] = fn(next[key]);
+    }
+    return next;
+  };
+}

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

@@ -0,0 +1,208 @@
+import type { ZodType, z } from "zod";
+import { toTableName } from "../db/table-builder";
+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,
+  EntityDefinition,
+  EntityRef,
+  HandlerRef,
+  NameOrRef,
+  QueryHandlerFn,
+  RateLimitOption,
+  RelationDefinition,
+  StreamHandlerFn,
+  WriteHandlerFn,
+} from "./types";
+import type { PipelineDef } from "./types/step";
+
+const CRUD_VERBS = new Set(["create", "update", "delete"]);
+
+// Map handler name to entity via colon convention.
+// "task:create" → entity "task". Bare CRUD verbs (create/update/delete) map
+// when feature name matches an entity or the feature owns exactly one entity.
+function tryMapEntity(state: FeatureBuilderState, name: string, handlerName: string): void {
+  const colonIdx = handlerName.indexOf(":");
+  if (colonIdx >= 0) {
+    const candidate = handlerName.slice(0, colonIdx);
+    if (state.entities[candidate]) {
+      state.handlerEntityMappings[handlerName] = candidate;
+    }
+    // skip: colon-prefixed handler processed (mapped or not), bare CRUD path not applicable
+    return;
+  }
+  if (CRUD_VERBS.has(handlerName)) {
+    if (state.entities[name]) {
+      state.handlerEntityMappings[handlerName] = name;
+      // skip: feature-name entity match is the preferred mapping
+      return;
+    }
+    const entityKeys = Object.keys(state.entities);
+    if (entityKeys.length === 1) {
+      state.handlerEntityMappings[handlerName] = entityKeys[0] as string;
+    }
+  }
+}
+
+// Builds entity/relation/writeHandler/queryHandler — the registrar
+// methods that create or reference entities.
+export function buildEntityHandlerMethods<TName extends string>(
+  state: FeatureBuilderState,
+  name: TName,
+) {
+  const methods = {
+    entity(
+      nameOrDefinition: string | ({ readonly name: string } & EntityDefinition),
+      definition?: EntityDefinition,
+      options?: { readonly table?: unknown },
+    ): EntityRef {
+      const [entityName, entityDefinition] =
+        typeof nameOrDefinition === "string"
+          ? [nameOrDefinition, definition as EntityDefinition]
+          : splitNamedDefinition(nameOrDefinition);
+      state.entities[entityName] = entityDefinition;
+      if (options?.table !== undefined) state.entityTables[entityName] = options.table;
+      return { name: entityName, table: entityDefinition.table ?? toTableName(entityName) };
+    },
+    relation(
+      entityRefOrDefinition:
+        | NameOrRef
+        | ({ readonly entity: NameOrRef; readonly name: string } & RelationDefinition),
+      relationName?: string,
+      definition?: RelationDefinition,
+    ): void {
+      const [entityRef, resolvedRelationName, resolvedDefinition] =
+        typeof entityRefOrDefinition === "object" && "entity" in entityRefOrDefinition
+          ? (() => {
+              const { entity, name: innerName, ...rest } = entityRefOrDefinition;
+              return [entity, innerName, rest as RelationDefinition] as const;
+            })()
+          : [entityRefOrDefinition, relationName as string, definition as RelationDefinition];
+      const entityName = resolveName(entityRef);
+      if (!state.relations[entityName]) state.relations[entityName] = {};
+      state.relations[entityName][resolvedRelationName] = resolvedDefinition;
+    },
+    writeHandler<TName extends string, TSchema extends ZodType>(
+      nameOrDef: string | WriteHandlerDefinition<TName, TSchema>,
+      schema?: TSchema,
+      handler?: WriteHandlerFn<z.infer<TSchema>>,
+      options?: { access?: AccessRule; rateLimit?: RateLimitOption },
+    ): HandlerRef {
+      if (typeof nameOrDef === "object") {
+        const def = nameOrDef;
+        state.writeHandlers[def.name] = {
+          name: def.name,
+          schema: def.schema,
+          // @cast-boundary engine-bridge — typed Dev-API's handler is
+          // generic over the schema's parsed payload (`WriteEvent<output<TSchema>>`),
+          // the storage form WriteHandlerFn carries `WriteEvent<unknown>`.
+          // Function-arg variance: TS sees the typed handler as stricter
+          // than the loose storage shape and rejects direct assignment.
+          // The runtime value is identical — the cast crosses that boundary.
+          // `satisfies` does not work here (it asserts assignability, which
+          // is what fails). Explicit cast is the right tool.
+          handler: def.handler as WriteHandlerFn,
+          ...(def.access && { access: def.access }),
+          ...(def.unsafeSkipTransitionGuard && { unsafeSkipTransitionGuard: true }),
+          ...(def.rateLimit && { rateLimit: def.rateLimit }),
+          // Forward the pipeline-build closure so boot-validators and
+          // Designer/AI tooling can inspect the step list. Absent on
+          // free-form handlers — defineWriteHandler only sets `perform`
+          // when the author used the pipeline form. Variance cast
+          // mirrors the handler-cast above: PipelineDef<output<TSchema>>
+          // is stricter than PipelineDef<unknown> for the same reason.
+          ...(def.perform !== undefined && {
+            perform: def.perform as PipelineDef,
+          }),
+        };
+        tryMapEntity(state, name, def.name);
+        return { name: def.name };
+      }
+      if (!schema || !handler)
+        throw new Error("writeHandler inline form requires schema + handler");
+      state.writeHandlers[nameOrDef] = {
+        name: nameOrDef,
+        schema,
+        handler: handler as WriteHandlerFn, // @cast-boundary engine-bridge
+        ...(options?.access && { access: options.access }),
+        ...(options?.rateLimit && { rateLimit: options.rateLimit }),
+      };
+      tryMapEntity(state, name, nameOrDef);
+      return { name: nameOrDef };
+    },
+    queryHandler<TName extends string, TSchema extends ZodType>(
+      nameOrDef: string | QueryHandlerDefinition<TName, TSchema>,
+      schema?: TSchema,
+      handler?: QueryHandlerFn<z.infer<TSchema>>,
+      options?: { access?: AccessRule; rateLimit?: RateLimitOption },
+    ): HandlerRef {
+      if (typeof nameOrDef === "object") {
+        const def = nameOrDef;
+        state.queryHandlers[def.name] = {
+          name: def.name,
+          schema: def.schema,
+          // @cast-boundary engine-bridge — typed Dev-API → erased internal storage
+          handler: def.handler as QueryHandlerFn, // @cast-boundary engine-bridge
+          ...(def.access && { access: def.access }),
+          ...(def.rateLimit && { rateLimit: def.rateLimit }),
+        };
+        tryMapEntity(state, name, def.name);
+        return { name: def.name };
+      }
+      if (!schema || !handler)
+        throw new Error("queryHandler inline form requires schema + handler");
+      state.queryHandlers[nameOrDef] = {
+        name: nameOrDef,
+        schema,
+        handler: handler as QueryHandlerFn, // @cast-boundary engine-bridge
+        ...(options?.access && { access: options.access }),
+        ...(options?.rateLimit && { rateLimit: options.rateLimit }),
+      };
+      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,
+    crud(entityName: string, entity: EntityDefinition, options?: RegisterEntityCrudOptions): void {
+      registerEntityCrud(methods, entityName, entity, options);
+    },
+  };
+}

package/src/engine/feature-manifest.ts

@@ -7,6 +7,7 @@
 // lesen.
 
 import { compareByCodepoint } from "../utils";
+import { isEncryptedAtRest } from "./config-helpers";
 import { qualifyEntityName } from "./qualified-name";
 import type { Registry, UiHints } from "./types/feature";
 
@@ -106,7 +107,7 @@ export function buildManifestFromRegistry(
         type: def.type,
         scope: def.scope,
         default: def.default ?? null,
-        encrypted: def.encrypted ?? false,
+        encrypted: isEncryptedAtRest(def),
         computed: def.computed !== undefined,
         options: def.options ?? null,
         bounds: def.bounds ?? null,