@cosmicdrift/kumiko-framework 0.154.0 → 0.154.2

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

@@ -106,19 +106,15 @@ export type AddQueryHandlerArgs = {
 
 export type AddHookArgs = {
   readonly type: LifecycleHookType | "validation";
-  readonly target: string | readonly string[];
+  // `{ allOf: entity }` — entity-wide target, fires for every write/query
+  // handler of that entity; replaces the old addEntityHook(). Only valid
+  // for postSave/preDelete/postDelete/postQuery, same as r.hook() itself.
+  readonly target: string | readonly string[] | { readonly allOf: string };
   /** Source text of the closure, e.g. `"async (event, ctx) => { ... }"`. */
   readonly handlerSource: string;
   readonly phase?: HookPhase;
 };
 
-export type AddEntityHookArgs = {
-  readonly type: "postSave" | "preDelete" | "postDelete";
-  readonly entity: string;
-  readonly handlerSource: string;
-  readonly phase?: HookPhase;
-};
-
 export type AddJobArgs = {
   readonly name: string;
   readonly options: Omit<JobDefinition, "name" | "handler">;
@@ -144,13 +140,10 @@ export type AddDefineEventArgs = {
   readonly name: string;
   readonly schemaSource: string;
   readonly version?: number;
-};
-
-export type AddEventMigrationArgs = {
-  readonly event: string;
-  readonly fromVersion: number;
-  readonly toVersion: number;
-  readonly transformSource: string;
+  // Keyed by fromVersion (as a string) → the transform source text for the
+  // fromVersion -> fromVersion+1 step. Folded in from the former
+  // addEventMigration (#1082 step 8).
+  readonly migrations?: Readonly<Record<string, string>>;
 };
 
 export type AddProjectionArgs = {
@@ -241,7 +234,6 @@ export type FeaturePatcher = {
   readonly addWriteHandler: (args: AddWriteHandlerArgs) => void;
   readonly addQueryHandler: (args: AddQueryHandlerArgs) => void;
   readonly addHook: (args: AddHookArgs) => void;
-  readonly addEntityHook: (args: AddEntityHookArgs) => void;
   readonly addJob: (args: AddJobArgs) => void;
   readonly addNotification: (args: AddNotificationArgs) => void;
   readonly addAuthClaims: (args: AddAuthClaimsArgs) => void;
@@ -249,7 +241,6 @@ export type FeaturePatcher = {
   readonly addProjection: (args: AddProjectionArgs) => void;
   readonly addMultiStreamProjection: (args: AddMultiStreamProjectionArgs) => void;
   readonly addDefineEvent: (args: AddDefineEventArgs) => void;
-  readonly addEventMigration: (args: AddEventMigrationArgs) => void;
   // --- Symmetric ops (id-driven) ---
   readonly replace: (id: PatternId, pattern: FeaturePattern) => void;
   readonly remove: (id: PatternId) => void;
@@ -412,17 +403,6 @@ export function createFeaturePatcher(sourceFile: SourceFile): FeaturePatcher {
       });
     },
 
-    addEntityHook({ type, entity, handlerSource, phase }) {
-      add({
-        kind: "entityHook",
-        source: SYNTHETIC_LOC,
-        hookType: type,
-        entityName: entity,
-        fnBody: rawLoc(handlerSource),
-        ...(phase !== undefined && { phase }),
-      });
-    },
-
     addJob({ name, options, handlerSource }) {
       add({
         kind: "job",
@@ -495,24 +475,22 @@ export function createFeaturePatcher(sourceFile: SourceFile): FeaturePatcher {
       });
     },
 
-    addDefineEvent({ name, schemaSource, version }) {
+    addDefineEvent({ name, schemaSource, version, migrations }) {
+      const migrationLocs = migrations
+        ? Object.fromEntries(
+            Object.entries(migrations).map(([fromVersion, source]) => [
+              fromVersion,
+              rawLoc(source),
+            ]),
+          )
+        : undefined;
       add({
         kind: "defineEvent",
         source: SYNTHETIC_LOC,
         eventName: name,
         schemaSource: rawLoc(schemaSource),
         ...(version !== undefined && { version }),
-      });
-    },
-
-    addEventMigration({ event, fromVersion, toVersion, transformSource }) {
-      add({
-        kind: "eventMigration",
-        source: SYNTHETIC_LOC,
-        eventName: event,
-        fromVersion,
-        toVersion,
-        transformBody: rawLoc(transformSource),
+        ...(migrationLocs !== undefined && { migrations: migrationLocs }),
       });
     },
 

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

@@ -376,30 +376,20 @@ export type QueryHandlerPattern = {
 
 // `r.hook(type, target, fn, options?)` — attaches a lifecycle hook
 // (`validation`, `preSave`, `postSave`, `preDelete`, `postDelete`,
-// `preQuery`, `postQuery`) to one or more target handlers. Post-hooks
-// accept a `phase` option; `preDelete` always runs in-transaction — it
-// guards the delete. The hook body is an opaque code span.
+// `preQuery`, `postQuery`) to one or more target handlers, or — for
+// postSave/preDelete/postDelete/postQuery — to `{ allOf: entityRef }`
+// ("every write/query handler of this entity", replacing the old
+// `r.entityHook(type, entity, fn)`). Post-hooks accept a `phase` option;
+// `preDelete` always runs in-transaction — it guards the delete. The hook
+// body is an opaque code span.
 export type HookPattern = {
   readonly kind: "hook";
   readonly source: SourceLocation;
   readonly hookType: LifecycleHookType | "validation";
-  // r.hook accepts a single target or a list; we keep both shapes so
-  // the Designer can render the original author intent.
-  readonly target: string | readonly string[];
-  readonly fnBody: SourceLocation;
-  readonly phase?: HookPhase;
-};
-
-// `r.entityHook(type, entity, fn, options?)` — like `r.hook`, but bound to
-// an entity instead of individual handlers: `postSave`, `preDelete`, and
-// `postDelete` fire on every matching write. The runtime API additionally
-// accepts `postQuery` (fires for all query-handlers of the entity), but
-// this pattern type only represents the three write-side hooks.
-export type EntityHookPattern = {
-  readonly kind: "entityHook";
-  readonly source: SourceLocation;
-  readonly hookType: "postSave" | "preDelete" | "postDelete";
-  readonly entityName: string;
+  // r.hook accepts a single target, a list, or an entity-wide { allOf }
+  // target; we keep all three shapes so the Designer can render the
+  // original author intent.
+  readonly target: string | readonly string[] | { readonly allOf: string };
   readonly fnBody: SourceLocation;
   readonly phase?: HookPhase;
 };
@@ -501,29 +491,22 @@ export type MultiStreamProjectionPattern = {
 // `r.defineEvent(name, schema, options?)` — registers an event payload
 // shape and returns the qualified `EventDef`, so callers pass `.name` to
 // `ctx.appendEvent` instead of hand-building `<feature>:event:<short>`.
-// `options.version` declares the CURRENT schema generation (default 1);
-// bump it together with an `r.eventMigration` step — the framework refuses
-// to boot if the chain from 1 to the current version has gaps.
+// `options.version` declares the CURRENT schema generation (default 1).
+// `options.migrations` is a step-wise upcast chain — keyed by fromVersion
+// (toVersion is always fromVersion + 1, enforced at registration, so it is
+// not stored separately); the framework refuses to boot if the chain from
+// 1 to `version` has gaps. Formerly a separate `r.eventMigration()` call
+// per step, folded in here (#1082 step 8) — an event and its schema
+// evolution are one lifecycle, not two registrar concepts.
 export type DefineEventPattern = {
   readonly kind: "defineEvent";
   readonly source: SourceLocation;
   readonly eventName: string;
   readonly schemaSource: SourceLocation;
   readonly version?: number;
-};
-
-// `r.eventMigration(eventName, fromVersion, toVersion, transform)` —
-// registers a step-wise payload upcast for event-schema evolution.
-// `toVersion` must be `fromVersion + 1`; chain larger jumps step by step.
-// Transforms are pure old-payload-in/new-payload-out functions and run once
-// per READ, not once per event persisted — keep them cheap.
-export type EventMigrationPattern = {
-  readonly kind: "eventMigration";
-  readonly source: SourceLocation;
-  readonly eventName: string;
-  readonly fromVersion: number;
-  readonly toVersion: number;
-  readonly transformBody: SourceLocation;
+  // Map fromVersion (as string, e.g. "1") → SourceLocation of the transform
+  // closure for the fromVersion → fromVersion+1 step.
+  readonly migrations?: Readonly<Record<string, SourceLocation>>;
 };
 
 // `r.extendsRegistrar(extensionName, def)` — declares a named, globally
@@ -610,7 +593,6 @@ export type FeaturePattern =
   | WriteHandlerPattern
   | QueryHandlerPattern
   | HookPattern
-  | EntityHookPattern
   | JobPattern
   | NotificationPattern
   | AuthClaimsPattern
@@ -618,7 +600,6 @@ export type FeaturePattern =
   | ProjectionPattern
   | MultiStreamProjectionPattern
   | DefineEventPattern
-  | EventMigrationPattern
   | ExtendsRegistrarPattern
   | EnvSchemaPattern
   // Catch-all
@@ -667,14 +648,12 @@ export function getEditability(pattern: FeaturePattern): Editability {
     case "writeHandler":
     case "queryHandler":
     case "hook":
-    case "entityHook":
     case "job":
     case "notification":
     case "httpRoute":
     case "projection":
     case "multiStreamProjection":
     case "defineEvent":
-    case "eventMigration":
       return "mixed";
     case "authClaims":
     case "extendsRegistrar":

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

@@ -23,10 +23,8 @@ import type {
   ConfigPattern,
   DefineEventPattern,
   DescribePattern,
-  EntityHookPattern,
   EntityPattern,
   EnvSchemaPattern,
-  EventMigrationPattern,
   ExposesApiPattern,
   ExtendsRegistrarPattern,
   FeaturePattern,
@@ -113,8 +111,6 @@ export function renderPattern(pattern: FeaturePattern): string {
       return renderQueryHandler(pattern);
     case "hook":
       return renderHook(pattern);
-    case "entityHook":
-      return renderEntityHook(pattern);
     case "job":
       return renderJob(pattern);
     case "notification":
@@ -129,8 +125,6 @@ export function renderPattern(pattern: FeaturePattern): string {
       return renderMultiStreamProjection(pattern);
     case "defineEvent":
       return renderDefineEvent(pattern);
-    case "eventMigration":
-      return renderEventMigration(pattern);
     case "extendsRegistrar":
       return renderExtendsRegistrar(pattern);
     case "usesApi":
@@ -401,20 +395,16 @@ function renderQueryHandler(p: QueryHandlerPattern): string {
   return lines.join("\n");
 }
 
-function renderHook(p: HookPattern): string {
-  const lines: string[] = ["r.hook({"];
-  lines.push(`  type: ${JSON.stringify(p.hookType)},`);
-  lines.push(`  target: ${renderValue(typeof p.target === "string" ? p.target : [...p.target])},`);
-  lines.push(`  handler: ${reindentBody(p.fnBody.raw, PATTERN_INDENT)},`);
-  if (p.phase !== undefined) lines.push(`  phase: ${JSON.stringify(p.phase)},`);
-  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)} }`;
+  return renderValue([...target]);
 }
 
-function renderEntityHook(p: EntityHookPattern): string {
-  const lines: string[] = ["r.entityHook({"];
+function renderHook(p: HookPattern): string {
+  const lines: string[] = ["r.hook({"];
   lines.push(`  type: ${JSON.stringify(p.hookType)},`);
-  lines.push(`  entity: ${JSON.stringify(p.entityName)},`);
+  lines.push(`  target: ${renderHookTarget(p.target)},`);
   lines.push(`  handler: ${reindentBody(p.fnBody.raw, PATTERN_INDENT)},`);
   if (p.phase !== undefined) lines.push(`  phase: ${JSON.stringify(p.phase)},`);
   lines.push("});");
@@ -505,16 +495,16 @@ function renderDefineEvent(p: DefineEventPattern): string {
   lines.push(`  name: ${JSON.stringify(p.eventName)},`);
   lines.push(`  schema: ${p.schemaSource.raw},`);
   if (p.version !== undefined) lines.push(`  version: ${p.version},`);
-  lines.push("});");
-  return lines.join("\n");
-}
-
-function renderEventMigration(p: EventMigrationPattern): string {
-  const lines: string[] = ["r.eventMigration({"];
-  lines.push(`  event: ${JSON.stringify(p.eventName)},`);
-  lines.push(`  fromVersion: ${p.fromVersion},`);
-  lines.push(`  toVersion: ${p.toVersion},`);
-  lines.push(`  transform: ${p.transformBody.raw},`);
+  if (p.migrations !== undefined) {
+    const entries = Object.entries(p.migrations);
+    if (entries.length > 0) {
+      lines.push("  migrations: {");
+      for (const [fromVersion, transformBody] of entries) {
+        lines.push(`    "${fromVersion}": ${transformBody.raw},`);
+      }
+      lines.push("  },");
+    }
+  }
   lines.push("});");
   return lines.join("\n");
 }

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 { splitNamedDefinition } from "./object-form";
 import { QnTypes, qn, toKebab } from "./qualified-name";
 import type {
   AuthClaimsFn,
@@ -93,41 +94,121 @@ export function buildConfigEventsJobsMethods<TName extends string>(
     return typeof arg1 === "string" ? handles[arg1] : handles; // @cast-boundary engine-bridge — overload impl signature widens to unknown, narrowed by the two public overloads above
   }
 
+  // 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(
-      jobName: string,
-      options: Omit<JobDefinition, "name" | "handler">,
-      handler: JobHandlerFn,
+      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 options.trigger
+        "on" in jobOptions.trigger
           ? {
-              on: Array.isArray(options.trigger.on)
-                ? options.trigger.on.map(resolveName)
-                : resolveName(options.trigger.on as NameOrRef), // @cast-boundary engine-bridge
+              on: Array.isArray(jobOptions.trigger.on)
+                ? jobOptions.trigger.on.map(resolveName)
+                : resolveName(jobOptions.trigger.on as NameOrRef), // @cast-boundary engine-bridge
             }
-          : options.trigger;
-      state.jobs[jobName] = { ...options, trigger, name: jobName, handler };
+          : jobOptions.trigger;
+      state.jobs[jobName] = { ...jobOptions, trigger, name: jobName, handler: jobHandler };
     },
     notification(
-      notificationName: string,
-      definition: {
+      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(definition.trigger.on) },
-        recipient: definition.recipient,
-        data: definition.data,
-        templates: definition.templates,
+        trigger: { on: resolveName(resolvedDefinition.trigger.on) },
+        recipient: resolvedDefinition.recipient,
+        data: resolvedDefinition.data,
+        templates: resolvedDefinition.templates,
       };
     },
     translations(def: TranslationsDef): void {
@@ -136,7 +217,20 @@ export function buildConfigEventsJobsMethods<TName extends string>(
     defineEvent: <const TInner extends string, TPayload>(
       eventName: TInner,
       schema: ZodType<TPayload>,
-      options?: { readonly version?: number; readonly piiFields?: EventPiiFields },
+      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
@@ -155,26 +249,9 @@ export function buildConfigEventsJobsMethods<TName extends string>(
           `[Feature ${name}] defineEvent("${eventName}"): version must be a positive integer, got ${String(version)}`,
         );
       }
-      // 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).
       const piiFields = options?.piiFields;
       if (piiFields) {
-        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.`,
-              );
-            }
-          }
-        }
+        validateEventPiiFields(eventName, schema, piiFields);
       }
       // @cast-boundary engine-bridge — runtime-string mirrors the
       // template-literal-type via QualifiedEventName + toKebab. Both
@@ -187,50 +264,34 @@ export function buildConfigEventsJobsMethods<TName extends string>(
         ...(piiFields !== undefined && { piiFields }),
       };
       state.events[eventName] = def;
+      for (const m of options?.migrations ?? []) {
+        registerEventMigration(eventName, m.fromVersion, m.toVersion, m.transform);
+      }
       return def;
     },
-    eventMigration(
-      eventName: string,
-      fromVersion: number,
-      toVersion: number,
-      transform: EventUpcastFn | DeclarativeEventMigration,
+    readsConfig(
+      ...args: readonly [{ readonly keys: readonly string[] }] | readonly string[]
     ): void {
-      if (toVersion !== fromVersion + 1) {
-        throw new Error(
-          `[Feature ${name}] eventMigration("${eventName}", ${fromVersion}, ${toVersion}): ` +
-            `only single-step migrations are allowed — toVersion must be fromVersion + 1. ` +
-            `Chain larger jumps by registering each step separately.`,
-        );
-      }
-      if (!Number.isInteger(fromVersion) || fromVersion < 1) {
-        throw new Error(
-          `[Feature ${name}] eventMigration("${eventName}", ...): 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}] eventMigration("${eventName}", ${fromVersion}, ${toVersion}): ` +
-            `a migration from v${fromVersion} is already registered. 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;
-    },
-    readsConfig(...qualifiedKeys: string[]): void {
+      const [first] = args;
+      const qualifiedKeys =
+        typeof first === "object" && first !== null ? first.keys : (args as readonly string[]);
       state.configReads.push(...qualifiedKeys);
     },
-    metric(shortName: string, options: MetricOptions): void {
+    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, ...options };
+      state.metrics[shortName] = { shortName, ...metricOptions };
     },
     envSchema(schema: z.ZodObject<z.ZodRawShape>): void {
       if (state.envSchema !== undefined) {
@@ -240,7 +301,14 @@ export function buildConfigEventsJobsMethods<TName extends string>(
       }
       state.envSchema = schema;
     },
-    secret(shortName: string, options: SecretOptions): SecretKeyHandle {
+    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. ` +
@@ -256,14 +324,22 @@ export function buildConfigEventsJobsMethods<TName extends string>(
       state.secretKeys[shortName] = {
         shortName,
         qualifiedName,
-        ...options,
+        ...secretOptions,
       };
       return { name: qualifiedName };
     },
     claimKey<T extends ClaimKeyType>(
-      shortName: string,
-      options: { readonly type: T },
+      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. ` +
@@ -280,9 +356,9 @@ export function buildConfigEventsJobsMethods<TName extends string>(
       state.claimKeys[shortName] = {
         shortName,
         qualifiedName,
-        type: options.type,
+        type: claimType,
       };
-      return { name: qualifiedName, type: options.type };
+      return { name: qualifiedName, type: claimType };
     },
     authClaims(fn: AuthClaimsFn): void {
       state.authClaimsHooks.push(fn);
@@ -296,7 +372,7 @@ 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 r.eventMigration() call time, not at replay.
+  // 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);