@cosmicdrift/kumiko-framework 1.0.0 → 2.0.0

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

@@ -341,14 +341,20 @@ export type ScreenPattern = {
 export type WriteHandlerPattern = {
   readonly kind: "writeHandler";
   readonly source: SourceLocation;
-  readonly handlerName: string;
+  // handlerName/schemaSource/handlerBody are set together, or all left
+  // undefined for a single reference standing in for the whole handler
+  // (`r.writeHandler(handlerRef)`) that couldn't be resolved to an object
+  // literal — see #1007. An opaque pattern re-emits `source.raw` verbatim
+  // and, like UnknownPattern, has no PatternId variant (not individually
+  // patchable).
+  readonly handlerName?: string;
   // schemaSource: the Zod call as source text (e.g. "z.object({...})").
   // We keep it as an opaque block instead of decoding it back to JSON
   // schema — Zod's full surface is too rich for a faithful round-trip.
-  readonly schemaSource: SourceLocation;
+  readonly schemaSource?: SourceLocation;
   // handlerBody: the closure body as source text. Always opaque — AI
   // generates raw TypeScript, no DSL interpretation.
-  readonly handlerBody: SourceLocation;
+  readonly handlerBody?: SourceLocation;
   readonly access?: AccessRule;
   readonly rateLimit?: RateLimitOption;
   readonly unsafeSkipTransitionGuard?: boolean;
@@ -356,43 +362,48 @@ export type WriteHandlerPattern = {
 
 // `r.queryHandler(...)` — registers a read handler: name, Zod input schema,
 // handler closure, plus optional `access` and `rateLimit` rules. Read-side
-// counterpart of `r.writeHandler` with the same header/body split.
+// counterpart of `r.writeHandler` with the same header/body split. Opaque
+// (no handlerName) for the same single-reference case as WriteHandlerPattern.
 export type QueryHandlerPattern = {
   readonly kind: "queryHandler";
   readonly source: SourceLocation;
-  readonly handlerName: string;
-  readonly schemaSource: SourceLocation;
-  readonly handlerBody: SourceLocation;
+  readonly handlerName?: string;
+  readonly schemaSource?: SourceLocation;
+  readonly handlerBody?: SourceLocation;
+  readonly access?: AccessRule;
+  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. 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;
 };
@@ -445,18 +456,6 @@ export type AuthClaimsPattern = {
   readonly fnBody: SourceLocation;
 };
 
-// `r.tree(provider)` — the feature's top-level tree provider: a subscribe
-// function (emit-fn in, unsubscribe-fn out) that feeds workspaces with
-// `navigation: "tree"`. Features without `r.tree()` are invisible there —
-// provider presence IS the filter, there is no workspace mapping.
-// Closure-only, no header form: the Designer renders a read-only code
-// block, the AI patcher overwrites the span verbatim.
-export type TreePattern = {
-  readonly kind: "tree";
-  readonly source: SourceLocation;
-  readonly providerBody: SourceLocation;
-};
-
 // `r.httpRoute(definition)` — mounts an HTTP route owned by the feature,
 // outside the dispatcher pipeline (not under `/api/write|query|batch`) —
 // for RSS/Atom feeds, OG images, OpenAPI specs and similar. Duplicate
@@ -506,29 +505,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
@@ -614,8 +606,8 @@ export type FeaturePattern =
   | ScreenPattern
   | WriteHandlerPattern
   | QueryHandlerPattern
+  | StreamHandlerPattern
   | HookPattern
-  | EntityHookPattern
   | JobPattern
   | NotificationPattern
   | AuthClaimsPattern
@@ -623,9 +615,7 @@ export type FeaturePattern =
   | ProjectionPattern
   | MultiStreamProjectionPattern
   | DefineEventPattern
-  | EventMigrationPattern
   | ExtendsRegistrarPattern
-  | TreePattern
   | EnvSchemaPattern
   // Catch-all
   | UnknownPattern;
@@ -672,19 +662,17 @@ export function getEditability(pattern: FeaturePattern): Editability {
     case "screen":
     case "writeHandler":
     case "queryHandler":
+    case "streamHandler":
     case "hook":
-    case "entityHook":
     case "job":
     case "notification":
     case "httpRoute":
     case "projection":
     case "multiStreamProjection":
     case "defineEvent":
-    case "eventMigration":
       return "mixed";
     case "authClaims":
     case "extendsRegistrar":
-    case "tree":
     case "envSchema":
     case "uiHints":
     case "unknown":

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

@@ -16,16 +16,15 @@
 // `// kumiko-feature-version: 1`. Future format bumps run a dedicated
 // migrator over the version comment.
 
+import { isRawRefSentinel } from "./extractors/shared";
 import type {
   AuthClaimsPattern,
   ClaimKeyPattern,
   ConfigPattern,
   DefineEventPattern,
   DescribePattern,
-  EntityHookPattern,
   EntityPattern,
   EnvSchemaPattern,
-  EventMigrationPattern,
   ExposesApiPattern,
   ExtendsRegistrarPattern,
   FeaturePattern,
@@ -45,11 +44,11 @@ import type {
   RequiresPattern,
   ScreenPattern,
   SecretPattern,
+  StreamHandlerPattern,
   SystemScopePattern,
   ToggleablePattern,
   TranslationsPattern,
   TreeActionsPattern,
-  TreePattern,
   UiHintsPattern,
   UnknownPattern,
   UseExtensionPattern,
@@ -111,10 +110,10 @@ 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 "entityHook":
-      return renderEntityHook(pattern);
     case "job":
       return renderJob(pattern);
     case "notification":
@@ -129,8 +128,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":
@@ -139,8 +136,6 @@ export function renderPattern(pattern: FeaturePattern): string {
       return renderExposesApi(pattern);
     case "treeActions":
       return renderTreeActions(pattern);
-    case "tree":
-      return renderTree(pattern);
     case "envSchema":
       return renderEnvSchema(pattern);
     case "unknown":
@@ -177,6 +172,7 @@ const SINGLE_LINE_WIDTH = 80;
  * multi-line otherwise — biome-stable in both branches.
  */
 export function renderValue(value: unknown, indent = 0): string {
+  if (isRawRefSentinel(value)) return value.__raw;
   if (value === null) return "null";
   if (typeof value === "string") return JSON.stringify(value);
   if (typeof value === "number" || typeof value === "boolean") return String(value);
@@ -243,6 +239,13 @@ function renderDescribe(p: DescribePattern): string {
 }
 
 function renderEntity(p: EntityPattern): string {
+  // A whole-value raw-ref (`r.entity("x", eventEntity)`) can't be spread
+  // into the merged Object-Form without losing `name` to the sentinel
+  // shortcut in renderValue — fall back to the classic positional form,
+  // which keeps the reference verbatim alongside the name.
+  if (isRawRefSentinel(p.definition)) {
+    return `r.entity(${JSON.stringify(p.entityName)}, ${p.definition.__raw});`;
+  }
   // Inline `name` into the definition object — canonical Object-Form
   // is a single arg with name-as-property.
   const merged = { name: p.entityName, ...p.definition };
@@ -250,6 +253,9 @@ function renderEntity(p: EntityPattern): string {
 }
 
 function renderRelation(p: RelationPattern): string {
+  if (isRawRefSentinel(p.definition)) {
+    return `r.relation(${JSON.stringify(p.entityName)}, ${JSON.stringify(p.relationName)}, ${p.definition.__raw});`;
+  }
   const merged = { entity: p.entityName, name: p.relationName, ...p.definition };
   return `r.relation(${renderValue(merged)});`;
 }
@@ -271,11 +277,17 @@ function renderTranslations(p: TranslationsPattern): string {
 }
 
 function renderMetric(p: MetricPattern): string {
+  if (isRawRefSentinel(p.options)) {
+    return `r.metric(${JSON.stringify(p.shortName)}, ${p.options.__raw});`;
+  }
   const merged = { name: p.shortName, ...p.options };
   return `r.metric(${renderValue(merged)});`;
 }
 
 function renderSecret(p: SecretPattern): string {
+  if (isRawRefSentinel(p.options)) {
+    return `r.secret(${JSON.stringify(p.shortName)}, ${p.options.__raw});`;
+  }
   const merged = { name: p.shortName, ...p.options };
   return `r.secret(${renderValue(merged)});`;
 }
@@ -294,6 +306,9 @@ function renderReferenceData(p: ReferenceDataPattern): string {
 }
 
 function renderUseExtension(p: UseExtensionPattern): string {
+  if (isRawRefSentinel(p.options)) {
+    return `r.useExtension(${JSON.stringify(p.extensionName)}, ${JSON.stringify(p.entityName)}, ${p.options.__raw});`;
+  }
   const merged: Record<string, unknown> = {
     name: p.extensionName,
     entity: p.entityName,
@@ -359,10 +374,11 @@ function reindentBody(raw: string, newIndent: string): string {
 }
 
 function renderWriteHandler(p: WriteHandlerPattern): string {
+  if (p.handlerName === undefined) return p.source.raw;
   const lines: string[] = ["r.writeHandler({"];
   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)},`);
+  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)},`);
   if (p.unsafeSkipTransitionGuard === true) lines.push("  unsafeSkipTransitionGuard: true,");
@@ -371,30 +387,39 @@ function renderWriteHandler(p: WriteHandlerPattern): string {
 }
 
 function renderQueryHandler(p: QueryHandlerPattern): string {
+  if (p.handlerName === undefined) return p.source.raw;
   const lines: string[] = ["r.queryHandler({"];
   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)},`);
+  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 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)},`);
+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 renderEntityHook(p: EntityHookPattern): string {
-  const lines: string[] = ["r.entityHook({"];
+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 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("});");
@@ -433,16 +458,11 @@ function renderAuthClaims(p: AuthClaimsPattern): string {
   return `r.authClaims(${p.fnBody.raw});`;
 }
 
-// Visual-Tree patterns. treeActions is a static object-literal (mirrors
-// renderWorkspace), tree is opaque-only (mirrors renderAuthClaims).
+// treeActions is a static object-literal (mirrors renderWorkspace).
 function renderTreeActions(p: TreeActionsPattern): string {
   return `r.treeActions(${renderValue(p.definitions)});`;
 }
 
-function renderTree(p: TreePattern): string {
-  return `r.tree(${p.providerBody.raw});`;
-}
-
 function renderHttpRoute(p: HttpRoutePattern): string {
   const lines: string[] = ["r.httpRoute({"];
   lines.push(`  method: ${JSON.stringify(p.method)},`);
@@ -486,20 +506,25 @@ function renderMultiStreamProjection(p: MultiStreamProjectionPattern): string {
 }
 
 function renderDefineEvent(p: DefineEventPattern): string {
-  const lines: string[] = ["r.defineEvent({"];
-  lines.push(`  name: ${JSON.stringify(p.eventName)},`);
-  lines.push(`  schema: ${p.schemaSource.raw},`);
+  const migrationEntries = p.migrations !== undefined ? Object.entries(p.migrations) : [];
+  const hasOptions = p.version !== undefined || migrationEntries.length > 0;
+  if (!hasOptions) {
+    return `r.defineEvent(${JSON.stringify(p.eventName)}, ${p.schemaSource.raw});`;
+  }
+  const lines: string[] = [
+    `r.defineEvent(${JSON.stringify(p.eventName)}, ${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 (migrationEntries.length > 0) {
+    lines.push("  migrations: [");
+    for (const [fromVersion, transformBody] of migrationEntries) {
+      const from = Number(fromVersion);
+      lines.push(
+        `    { fromVersion: ${from}, toVersion: ${from + 1}, transform: ${transformBody.raw} },`,
+      );
+    }
+    lines.push("  ],");
+  }
   lines.push("});");
   return lines.join("\n");
 }
@@ -571,9 +596,7 @@ function weaveOpaque(
 }
 
 function renderValueWithRawSlots(value: WovenValue, indent: number): string {
-  if (value !== null && typeof value === "object" && !Array.isArray(value) && "__raw" in value) {
-    return (value as { __raw: string }).__raw;
-  }
+  if (isRawRefSentinel(value)) return value.__raw;
   if (Array.isArray(value)) {
     if (value.length === 0) return "[]";
     const inner = value

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

@@ -0,0 +1,168 @@
+import type { ZodType, z } from "zod";
+import { LifecycleHookTypes } from "./constants";
+import type {
+  AuthClaimsFn,
+  BootCheckFn,
+  ClaimKeyDefinition,
+  ConfigKeyDefinition,
+  ConfigSeedDef,
+  EntityDefinition,
+  EntityProjectionExtension,
+  EventMigrationDef,
+  ExtensionSelectorDef,
+  FeatureMetricDef,
+  JobDefinition,
+  LifecycleHookFn,
+  MultiStreamProjectionDefinition,
+  NotificationDefinition,
+  OwnedFn,
+  PhasedHook,
+  PostDeleteHookFn,
+  PostQueryHookFn,
+  PostSaveHookFn,
+  PreDeleteHookFn,
+  ProjectionDefinition,
+  QueryHandlerDef,
+  ReferenceDataDef,
+  RegistrarExtensionDef,
+  RegistrarExtensionRegistration,
+  RelationDefinition,
+  SearchPayloadContributorFn,
+  SecretKeyDefinition,
+  StoreTableEntry,
+  StreamHandlerDef,
+  TranslationKeys,
+  TreeActionDef,
+  UiHints,
+  ValidationHookFn,
+  WriteHandlerDef,
+} from "./types";
+import type { HttpRouteDefinition } from "./types/http-route";
+import type { NavDefinition } from "./types/nav";
+import type { ScreenDefinition } from "./types/screen";
+import type { WorkspaceDefinition } from "./types/workspace";
+
+const LIFECYCLE_TYPES = Object.values(LifecycleHookTypes);
+
+// Bundles every Record/Set/array/scalar defineFeature populates while the
+// registrar's ~40 methods run — hoisted out of defineFeature's closure so a
+// future move-diff (extracting each method into its own module) can thread
+// it explicitly. Every field is held BY REFERENCE — no destructured copies.
+export type FeatureBuilderState = {
+  requires: string[];
+  optionalRequires: string[];
+  requiredProjections: Set<string>;
+  requiredSteps: Set<string>;
+  entities: Record<string, EntityDefinition>;
+  entityTables: Record<string, unknown>;
+  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<
+    "postSave" | "preDelete" | "postDelete",
+    Record<string, PhasedHook<LifecycleHookFn>[]>
+  >;
+  configKeys: Record<string, ConfigKeyDefinition>;
+  configSeeds: ConfigSeedDef[];
+  jobs: Record<string, JobDefinition>;
+  events: Record<string, { name: string; schema: ZodType; version: number }>;
+  eventMigrations: Record<string, EventMigrationDef[]>;
+  configReads: string[];
+  entityPostSave: Record<string, PhasedHook<PostSaveHookFn>[]>;
+  entityPreDelete: Record<string, PhasedHook<PreDeleteHookFn>[]>;
+  entityPostDelete: Record<string, PhasedHook<PostDeleteHookFn>[]>;
+  entityPostQuery: Record<string, OwnedFn<PostQueryHookFn>[]>;
+  searchPayloadExtensions: Record<string, OwnedFn<SearchPayloadContributorFn>[]>;
+  notifications: Record<string, NotificationDefinition>;
+  registrarExtensions: Record<string, RegistrarExtensionDef>;
+  extensionUsages: RegistrarExtensionRegistration[];
+  extensionSelectors: ExtensionSelectorDef[];
+  exposedApis: Set<string>;
+  usedApis: Set<string>;
+  bootChecks: BootCheckFn[];
+  referenceData: ReferenceDataDef[];
+  handlerEntityMappings: Record<string, string>;
+  metrics: Record<string, FeatureMetricDef>;
+  secretKeys: Record<string, SecretKeyDefinition>;
+  projections: Record<string, ProjectionDefinition>;
+  multiStreamProjections: Record<string, MultiStreamProjectionDefinition>;
+  entityProjectionExtensions: Record<string, EntityProjectionExtension[]>;
+  storeTables: Record<string, StoreTableEntry>;
+  authClaimsHooks: AuthClaimsFn[];
+  claimKeys: Record<string, ClaimKeyDefinition>;
+  screens: Record<string, ScreenDefinition>;
+  navs: Record<string, NavDefinition>;
+  workspaces: Record<string, WorkspaceDefinition>;
+  httpRoutes: Record<string, HttpRouteDefinition>;
+  translations: TranslationKeys;
+  isSystemScoped: boolean;
+  toggleableDefault: boolean | undefined;
+  description: string | undefined;
+  uiHints: UiHints | undefined;
+  treeActions: Readonly<Record<string, TreeActionDef>> | undefined;
+  envSchema: z.ZodObject<z.ZodRawShape> | undefined;
+};
+
+export function createInitialFeatureBuilderState(): FeatureBuilderState {
+  const lifecycleHooks: Record<string, Record<string, OwnedFn<LifecycleHookFn>[]>> = {};
+  for (const t of LIFECYCLE_TYPES) {
+    lifecycleHooks[t] = {};
+  }
+  return {
+    requires: [],
+    optionalRequires: [],
+    requiredProjections: new Set<string>(),
+    requiredSteps: new Set<string>(),
+    entities: {},
+    entityTables: {},
+    relations: {},
+    writeHandlers: {},
+    queryHandlers: {},
+    streamHandlers: {},
+    validationHooks: {},
+    lifecycleHooks,
+    phasedLifecycleHooks: { postSave: {}, preDelete: {}, postDelete: {} },
+    configKeys: {},
+    configSeeds: [],
+    jobs: {},
+    events: {},
+    eventMigrations: {},
+    configReads: [],
+    entityPostSave: {},
+    entityPreDelete: {},
+    entityPostDelete: {},
+    entityPostQuery: {},
+    searchPayloadExtensions: {},
+    notifications: {},
+    registrarExtensions: {},
+    extensionUsages: [],
+    extensionSelectors: [],
+    exposedApis: new Set(),
+    usedApis: new Set(),
+    bootChecks: [],
+    referenceData: [],
+    handlerEntityMappings: {},
+    metrics: {},
+    secretKeys: {},
+    projections: {},
+    multiStreamProjections: {},
+    entityProjectionExtensions: {},
+    storeTables: {},
+    authClaimsHooks: [],
+    claimKeys: {},
+    screens: {},
+    navs: {},
+    workspaces: {},
+    httpRoutes: {},
+    translations: {},
+    isSystemScoped: false,
+    toggleableDefault: undefined,
+    description: undefined,
+    uiHints: undefined,
+    treeActions: undefined,
+    envSchema: undefined,
+  };
+}