@cosmicdrift/kumiko-framework 0.164.0 → 0.165.1

package/src/db/replay-migration-sql.ts

@@ -12,6 +12,23 @@
 import type { Snapshot } from "./migrate-generator";
 import { loadMigrationsFromDir } from "./migrate-runner";
 
+// Migration files comment out destructive ops (DROP TABLE/COLUMN) as
+// `-- DESTRUCTIVE: <stmt>;  -- uncomment + ensure backup` so the real
+// migrate-runner never executes them unattended. For replay purposes the
+// snapshot represents the INTENDED end state, so a commented-out drop must
+// still count as applied here — otherwise a table/column the snapshot
+// already omits shows up as "unexpected" forever. splitSqlStatements (the
+// real runner's splitter) strips `--`-comments outright, which would erase
+// these markers before they ever reach applyStatement.
+const DESTRUCTIVE_MARKER = /^--\s*DESTRUCTIVE:\s*(.+?;)/i;
+
+function expandDestructiveMarkers(sqlText: string): string {
+  return sqlText
+    .split("\n")
+    .map((line) => DESTRUCTIVE_MARKER.exec(line.trim())?.[1] ?? line)
+    .join("\n");
+}
+
 export type ReplayedTable = {
   readonly columns: ReadonlySet<string>;
 };
@@ -39,28 +56,67 @@ function splitTopLevel(body: string): readonly string[] {
   return parts;
 }
 
+// Identifiers in hand-written migrations aren't always quoted (the generator
+// always quotes, but the header explicitly invites hand-editing) — optional
+// quotes so `CREATE TABLE foo (...)` parses the same as `CREATE TABLE "foo" (...)`.
+const IDENT = `"?([^"\\s(;,.]+)"?`;
+
 function parseColumnNames(body: string): Set<string> {
   const columns = new Set<string>();
   for (const part of splitTopLevel(body)) {
     const trimmed = part.trim();
-    if (/^CONSTRAINT\b/i.test(trimmed)) continue; // composite-PK line, not a column
-    const match = trimmed.match(/^"([^"]+)"/);
+    if (/^(CONSTRAINT|PRIMARY|UNIQUE|CHECK|FOREIGN|EXCLUDE|LIKE)\b/i.test(trimmed)) continue; // table-constraint or LIKE clause, not a column
+    const match = trimmed.match(new RegExp(`^${IDENT}`));
     if (match?.[1] !== undefined) columns.add(match[1]);
   }
   return columns;
 }
 
-function applyStatement(schema: Map<string, { columns: Set<string> }>, statement: string): void {
+// Clauses that can appear inside an ALTER TABLE body which do NOT change the
+// table/column shape this replay tracks (presence only, not types/
+// constraints/RLS/ownership) — recognized explicitly so they don't fall
+// through to the fail-loud check as "unparsed". Deliberately does NOT
+// include RENAME TO / RENAME COLUMN: those DO change identity in a way this
+// replay can't track, so they must keep failing loud.
+const SHAPE_NEUTRAL_ALTER_CLAUSE_RE = new RegExp(
+  [
+    `ALTER COLUMN\\s+${IDENT}\\s+TYPE\\b`, // #1085 int/bigint-catchup fixes
+    `ALTER COLUMN\\s+${IDENT}\\s+(SET|DROP)\\s+NOT NULL\\b`,
+    `ALTER COLUMN\\s+${IDENT}\\s+(SET DEFAULT\\b|DROP DEFAULT\\b)`,
+    `(ADD|DROP)\\s+CONSTRAINT\\s+${IDENT}`,
+    `\\b(ENABLE|DISABLE)\\s+ROW LEVEL SECURITY\\b`,
+    `^OWNER TO\\b`,
+  ].join("|"),
+  "gi",
+);
+
+function applyStatement(
+  schema: Map<string, { columns: Set<string> }>,
+  statement: string,
+  context: { readonly file: string },
+): void {
   const create = statement.match(
-    /^CREATE TABLE\s+(?:IF NOT EXISTS\s+)?"([^"]+)"\s*\(([\s\S]*)\);?\s*$/i,
+    new RegExp(`^CREATE TABLE\\s+(IF NOT EXISTS\\s+)?${IDENT}\\s*\\(([\\s\\S]*)\\);?\\s*$`, "i"),
   );
-  if (create?.[1] !== undefined && create[2] !== undefined) {
-    schema.set(create[1], { columns: parseColumnNames(create[2]) });
+  if (create?.[2] !== undefined && create[3] !== undefined) {
+    const hasIfNotExists = create[1] !== undefined;
+    // A real Postgres CREATE TABLE IF NOT EXISTS is a no-op when the table
+    // already exists — treating it as an overwrite here loses any columns
+    // an earlier ALTER TABLE added in between (0001 CREATE, 0002 ALTER ADD
+    // COLUMN, 0003 an accidental copy-paste of 0001) and reports a false
+    // column-drift for exactly the copy-paste bug this replay exists to
+    // catch. A bare CREATE TABLE (no IF NOT EXISTS) still overwrites — the
+    // explicit recreate path (migrate-generator.ts) always DROPs first, so
+    // reaching a second CREATE for the same name there is itself already
+    // the bug the replay should surface via the resulting drift.
+    if (!(hasIfNotExists && schema.has(create[2]))) {
+      schema.set(create[2], { columns: parseColumnNames(create[3]) });
+    }
     // skip: CREATE TABLE fully handled above, no other clause can also match
     return;
   }
 
-  const dropTable = statement.match(/^DROP TABLE\s+(?:IF EXISTS\s+)?"([^"]+)"/i);
+  const dropTable = statement.match(new RegExp(`^DROP TABLE\\s+(?:IF EXISTS\\s+)?${IDENT}`, "i"));
   if (dropTable?.[1] !== undefined) {
     schema.delete(dropTable[1]);
     // skip: DROP TABLE fully handled above, no other clause can also match
@@ -73,29 +129,75 @@ function applyStatement(schema: Map<string, { columns: Set<string> }>, statement
   // instead of matching only the first clause, in statement order so an
   // add-then-drop of the same column (unusual, but not impossible) resolves
   // correctly.
-  const alterTable = statement.match(/^ALTER TABLE\s+"([^"]+)"\s+([\s\S]*?);?\s*$/i);
+  const alterTable = statement.match(
+    new RegExp(`^ALTER TABLE\\s+${IDENT}\\s+([\\s\\S]*?);?\\s*$`, "i"),
+  );
   const alterTableName = alterTable?.[1];
   const alterBody = alterTable?.[2];
   if (alterTableName !== undefined && alterBody !== undefined) {
     const table = schema.get(alterTableName) ?? { columns: new Set<string>() };
     schema.set(alterTableName, table);
-    const clauseRe = /(ADD|DROP)\s+COLUMN\s+(?:IF (?:NOT )?EXISTS\s+)?"([^"]+)"/gi;
+    const clauseRe = new RegExp(
+      `(ADD|DROP)\\s+COLUMN\\s+(?:IF (?:NOT )?EXISTS\\s+)?${IDENT}`,
+      "gi",
+    );
+    let matchedAClause = false;
     for (const [, verb, name] of alterBody.matchAll(clauseRe)) {
       if (verb === undefined || name === undefined) continue;
+      matchedAClause = true;
       if (verb.toUpperCase() === "ADD") table.columns.add(name);
       else table.columns.delete(name);
     }
+    // Shape-neutral clauses (ALTER COLUMN TYPE, SET/DROP NOT NULL, SET/DROP
+    // DEFAULT, ADD/DROP CONSTRAINT, ENABLE/DISABLE ROW LEVEL SECURITY, OWNER
+    // TO) — none add/remove/rename a column, so this replay (which only
+    // tracks column presence) correctly has nothing to do for them.
+    if (alterBody.match(SHAPE_NEUTRAL_ALTER_CLAUSE_RE)) matchedAClause = true;
+    // An ALTER TABLE that matched the outer "ALTER TABLE <name> <body>" shape
+    // but whose body contains no recognized clause (e.g. RENAME TO/RENAME
+    // COLUMN, which DO change identity) would otherwise silently no-op here
+    // — fall through to the fail-loud check below instead of returning, so
+    // it's reported rather than vanishing.
+    // skip: at least one recognized clause matched — this ALTER TABLE is
+    // fully handled, nothing left to do.
+    if (matchedAClause) return;
   }
   // else: CREATE INDEX and everything else don't change the table/column
-  // shape this replay tracks.
+  // shape this replay tracks — but a statement that clearly INTENDED to
+  // touch a table's shape (starts with CREATE/ALTER/DROP TABLE) and matched
+  // none of the recognized patterns above must fail loud, not vanish
+  // silently. Concretely this is RENAME TO / RENAME COLUMN (identity change
+  // this replay can't track) or genuinely unparsed hand-written DDL — either
+  // way a misleading missing-table/column-drift report is worse than
+  // pointing at the actual unparsed statement.
+  if (/^(CREATE|ALTER|DROP)\s+TABLE\b/i.test(statement)) {
+    const prefix = statement.slice(0, 200).replace(/\s+/g, " ").trim();
+    throw new Error(
+      `replayMigrationsDir: unparsed table-DDL statement in ${context.file} — ` +
+        `starts with CREATE/ALTER/DROP TABLE but matched none of the replay's ` +
+        `recognized patterns (CREATE TABLE, DROP TABLE, ALTER TABLE ADD/DROP ` +
+        `COLUMN, ALTER COLUMN ... TYPE, SET/DROP NOT NULL, SET/DROP DEFAULT, ` +
+        `ADD/DROP CONSTRAINT, ENABLE/DISABLE ROW LEVEL SECURITY, OWNER TO — ` +
+        `optionally-quoted identifiers). Likely RENAME TO/RENAME COLUMN (real ` +
+        `identity change, not trackable here) or genuinely unparsed hand-written ` +
+        `DDL. Statement: ${prefix}${statement.length > 200 ? "…" : ""}`,
+    );
+  }
 }
 
 // Reads `<migrationsDir>/*.sql` in sequence order and replays every
 // CREATE/ALTER/DROP TABLE statement to reconstruct the resulting schema.
+// Reuses the real runner's file-discovery + statement-splitting
+// (loadMigrationsFromDir) instead of a second copy, so any future change to
+// sub-directory handling, numeric sort order, or the .sql filter can't
+// silently drift between the runner and this replay (#1522/9).
 export function replayMigrationsDir(migrationsDir: string): ReplayedSchema {
   const schema = new Map<string, { columns: Set<string> }>();
-  for (const migration of loadMigrationsFromDir(migrationsDir)) {
-    for (const statement of migration.statements) applyStatement(schema, statement);
+  const migrations = loadMigrationsFromDir(migrationsDir, expandDestructiveMarkers);
+  for (const migration of migrations) {
+    for (const statement of migration.statements) {
+      applyStatement(schema, statement, { file: migration.id });
+    }
   }
   return schema;
 }

package/src/db/tenant-db.ts

@@ -1,4 +1,4 @@
-import type { SchemaTable } from "@cosmicdrift/kumiko-types/schema-table-types";
+import { KUMIKO_NAME_SYMBOL, type SchemaTable } from "@cosmicdrift/kumiko-types/schema-table-types";
 import type { TenantDb, TenantDbMode } from "@cosmicdrift/kumiko-types/tenant-db-types";
 import {
   asEntityTableMeta,
@@ -24,10 +24,8 @@ export function castTenantRows<T>(rows: readonly Record<string, unknown>[]): rea
   return rows as unknown as readonly T[];
 }
 
-const KUMIKO_NAME_SYMBOL = Symbol.for("kumiko:schema:Name");
-
 function tableNameOf(table: Table): string {
-  const sym = (table as unknown as Record<symbol, unknown>)[KUMIKO_NAME_SYMBOL];
+  const sym = table[KUMIKO_NAME_SYMBOL];
   return typeof sym === "string" ? sym : "<unknown>";
 }
 

package/src/engine/__tests__/boot-validator.test.ts

@@ -599,6 +599,20 @@ describe("boot-validator", () => {
     expect(() => validateBoot(features)).toThrow(/a:stream:chat:complete.*missing an access rule/i);
   });
 
+  test("object-form streamHandler with access rule passes boot", () => {
+    const features = [
+      defineFeature("a", (r) => {
+        r.streamHandler({
+          name: "chat:complete",
+          schema: z.object({}),
+          handler: async function* () {},
+          access: { roles: ["User"] },
+        });
+      }),
+    ];
+    expect(() => validateBoot(features)).not.toThrow();
+  });
+
   test("accepts openToAll access rule on a stream handler", () => {
     const features = [
       defineFeature("a", (r) => {

package/src/engine/__tests__/engine.test.ts

@@ -739,6 +739,36 @@ describe("createApp", () => {
     ).not.toThrow();
   });
 
+  test("validates stream handler roles against app-defined roles (#1442)", () => {
+    const feature = defineFeature("admin", (r) => {
+      r.streamHandler("admin.tail", z.object({}), async function* () {}, {
+        access: { roles: ["SuperAdmin"] },
+      });
+    });
+
+    expect(() =>
+      createApp({
+        roles: ["Admin", "User"] as const,
+        features: [feature],
+      }),
+    ).toThrow(/unknown role.*SuperAdmin/i);
+  });
+
+  test("passes when stream handler roles are valid (#1442)", () => {
+    const feature = defineFeature("admin", (r) => {
+      r.streamHandler("admin.tail", z.object({}), async function* () {}, {
+        access: { roles: ["Admin"] },
+      });
+    });
+
+    expect(() =>
+      createApp({
+        roles: ["Admin", "User"] as const,
+        features: [feature],
+      }),
+    ).not.toThrow();
+  });
+
   test("createApp returns registry", () => {
     const feature = defineFeature("test", () => {});
     const app = createApp({ roles: ["Admin"] as const, features: [feature] });

package/src/engine/__tests__/registry.test.ts

@@ -139,6 +139,42 @@ describe("getAllStreamHandlers", () => {
     });
     expect(() => createRegistry([aiFeature, otherFeature])).not.toThrow();
   });
+
+  test("two distinct feature names that kebab-collide throw on the qualified stream-handler clash", () => {
+    // "registry-test-kebab-dup" and "registryTestKebabDup" are different raw
+    // feature.name values (so the earlier Duplicate-feature guard doesn't
+    // fire) but toKebab() collapses both to the same qualified name.
+    const featureA = defineFeature("registry-test-kebab-dup", (r) => {
+      r.streamHandler("chat:complete", z.object({}), async function* () {});
+    });
+    const featureB = defineFeature("registryTestKebabDup", (r) => {
+      r.streamHandler("chat:complete", z.object({}), async function* () {});
+    });
+    expect(() => createRegistry([featureA, featureB])).toThrow(/Duplicate stream handler/);
+  });
+
+  test("object-form streamHandler registration preserves schema/access/rateLimit", () => {
+    const schema = z.object({ prompt: z.string() });
+    const handlerFn = async function* () {};
+    const feature = defineFeature("registry-test-object-form", (r) => {
+      r.streamHandler({
+        name: "chat:complete",
+        schema,
+        handler: handlerFn,
+        access: { openToAll: true },
+        rateLimit: { per: "ip+handler", limit: 5, windowSeconds: 60 },
+      });
+    });
+
+    const registry = createRegistry([feature]);
+    const registered = registry.getStreamHandler("registry-test-object-form:stream:chat:complete");
+
+    expect(registered).toBeDefined();
+    expect(registered?.schema).toBe(schema);
+    expect(registered?.handler).toBe(handlerFn);
+    expect(registered?.access).toEqual({ openToAll: true });
+    expect(registered?.rateLimit).toEqual({ per: "ip+handler", limit: 5, windowSeconds: 60 });
+  });
 });
 
 describe("extensionSelector boot-validation", () => {

package/src/engine/__tests__/schema-builder.test.ts

@@ -113,6 +113,24 @@ describe("buildInsertSchema", () => {
       valid: { age: 25 },
       invalid: { age: "old" },
     },
+    {
+      name: "number field rejects below min",
+      fields: { age: createNumberField({ min: 0 }) },
+      valid: { age: 0 },
+      invalid: { age: -1 },
+    },
+    {
+      name: "number field rejects above max",
+      fields: { age: createNumberField({ max: 100 }) },
+      valid: { age: 100 },
+      invalid: { age: 101 },
+    },
+    {
+      name: "number field min+max bounds",
+      fields: { age: createNumberField({ min: 1, max: 10 }) },
+      valid: { age: 5 },
+      invalid: { age: 11 },
+    },
     {
       name: "date field",
       fields: { born: createDateField() },

package/src/engine/__tests__/store-table.test.ts

@@ -142,7 +142,7 @@ describe("createRegistry — storeTable aggregation", () => {
       r.storeTable(probeMeta, { reason: "second" });
     });
     expect(() => createRegistry([featA, featB])).toThrow(
-      /Raw-table "rt_probe" registered by both feature "a" and "b"/,
+      /Store-table "rt_probe" registered by both feature "a" and "b"/,
     );
   });
 
@@ -177,7 +177,7 @@ describe("createRegistry — storeTable aggregation", () => {
 
     // Entity registered first, then the colliding store table.
     expect(() => createRegistry([entityFeature, tableFeature])).toThrow(
-      new RegExp(`Raw-table "${physical}".*collides with the physical table of entity "widget"`),
+      new RegExp(`Store-table "${physical}".*collides with the physical table of entity "widget"`),
     );
 
     // Order-independent: store table registered first, then the entity.

package/src/engine/boot-validator/entity-handler.ts

@@ -101,32 +101,21 @@ const USER_BUCKETED_RATE_LIMIT_PER: ReadonlySet<string> = new Set(["user", "user
 // at runtime, but we fail at boot to turn an easy-to-miss security regression
 // into a loud configuration error.
 export function validateHandlerAccess(feature: FeatureDefinition): void {
-  for (const [name, handler] of Object.entries(feature.writeHandlers)) {
-    if (!handler.access) {
-      throw new Error(
-        `Write handler "${feature.name}:write:${name}" is missing an access rule. ` +
-          `Set { roles: [...] } for role-based access, or { openToAll: true } for any authenticated user.`,
-      );
-    }
-    validateAnonymousRateLimit(feature.name, "write", name, handler.access, handler.rateLimit);
-  }
-  for (const [name, handler] of Object.entries(feature.queryHandlers)) {
-    if (!handler.access) {
-      throw new Error(
-        `Query handler "${feature.name}:query:${name}" is missing an access rule. ` +
-          `Set { roles: [...] } for role-based access, or { openToAll: true } for any authenticated user.`,
-      );
-    }
-    validateAnonymousRateLimit(feature.name, "query", name, handler.access, handler.rateLimit);
-  }
-  for (const [name, handler] of Object.entries(feature.streamHandlers)) {
-    if (!handler.access) {
-      throw new Error(
-        `Stream handler "${feature.name}:stream:${name}" is missing an access rule. ` +
-          `Set { roles: [...] } for role-based access, or { openToAll: true } for any authenticated user.`,
-      );
+  const kinds = [
+    { kind: "write" as const, label: "Write", handlers: feature.writeHandlers },
+    { kind: "query" as const, label: "Query", handlers: feature.queryHandlers },
+    { kind: "stream" as const, label: "Stream", handlers: feature.streamHandlers },
+  ];
+  for (const { kind, label, handlers } of kinds) {
+    for (const [name, handler] of Object.entries(handlers)) {
+      if (!handler.access) {
+        throw new Error(
+          `${label} handler "${feature.name}:${kind}:${name}" is missing an access rule. ` +
+            `Set { roles: [...] } for role-based access, or { openToAll: true } for any authenticated user.`,
+        );
+      }
+      validateAnonymousRateLimit(feature.name, kind, name, handler.access, handler.rateLimit);
     }
-    validateAnonymousRateLimit(feature.name, "stream", name, handler.access, handler.rateLimit);
   }
 }
 

package/src/engine/boot-validator/nav.ts

@@ -115,6 +115,11 @@ export function collectKnownRoles(features: readonly FeatureDefinition[]): Set<s
         for (const r of def.access.roles) roles.add(r);
       }
     }
+    for (const def of Object.values(f.streamHandlers)) {
+      if (def.access && "roles" in def.access) {
+        for (const r of def.access.roles) roles.add(r);
+      }
+    }
   }
   return roles;
 }

package/src/engine/constants.ts

@@ -1,3 +1,6 @@
+import type { ConcurrencyMode } from "@cosmicdrift/kumiko-types/concurrency-mode";
+import type { ConfigScope } from "@cosmicdrift/kumiko-types/config-scope";
+import type { OnDeleteStrategy as OnDeleteStrategyType } from "@cosmicdrift/kumiko-types/relations";
 import type { TenantId } from "./types/identifiers";
 
 // All framework constants as `as const` objects with inferred union types.
@@ -47,14 +50,23 @@ export const LifecycleHookTypes = {
 export type LifecycleHookType = (typeof LifecycleHookTypes)[keyof typeof LifecycleHookTypes];
 
 // --- Config Scopes ---
+// Value object satisfies the canonical ConfigScope union from kumiko-types —
+// a scope added here without a matching kumiko-types member is now a
+// compile error instead of silent drift (#1423/#1439).
 
 export const ConfigScopes = {
   system: "system",
   tenant: "tenant",
   user: "user",
-} as const;
+} as const satisfies Record<string, ConfigScope>;
+
+export type { ConfigScope };
 
-export type ConfigScope = (typeof ConfigScopes)[keyof typeof ConfigScopes];
+// Reverse direction: a member added only to kumiko-types' ConfigScope
+// (not to ConfigScopes above) would otherwise pass the `satisfies` check
+// above unnoticed — this line forces exhaustiveness the other way too.
+const _configScopeExhaustive: Record<ConfigScope, unknown> = ConfigScopes;
+void _configScopeExhaustive;
 
 // --- On Delete Strategies ---
 
@@ -63,11 +75,13 @@ export const OnDeleteStrategies = {
   restrict: "restrict",
   setNull: "setNull",
   nothing: "nothing",
-} as const;
+} as const satisfies Record<OnDeleteStrategyType, OnDeleteStrategyType>;
 
-export type OnDeleteStrategy = (typeof OnDeleteStrategies)[keyof typeof OnDeleteStrategies];
+export type OnDeleteStrategy = OnDeleteStrategyType;
 
 // --- Concurrency Modes ---
+// Value object satisfies the canonical ConcurrencyMode union from
+// kumiko-types — same drift-guard as ConfigScopes above.
 
 export const ConcurrencyModes = {
   parallel: "parallel",
@@ -75,12 +89,24 @@ export const ConcurrencyModes = {
   replace: "replace",
   sequential: "sequential",
   debounce: "debounce",
-} as const;
+} as const satisfies Record<string, ConcurrencyMode>;
 
-export type ConcurrencyMode = (typeof ConcurrencyModes)[keyof typeof ConcurrencyModes];
+export type { ConcurrencyMode };
+
+// Reverse-direction exhaustiveness guard — see the ConfigScope one above.
+const _concurrencyModeExhaustive: Record<ConcurrencyMode, unknown> = ConcurrencyModes;
+void _concurrencyModeExhaustive;
 
 // --- SSE Channels ---
 
 export function tenantChannel(tenantId: TenantId): string {
   return `tenant:${tenantId}`;
 }
+
+// Access-invalidation channel key for a single user's live streams. Both
+// the subscribe side (dispatch-stream.ts) and the publish side (session-
+// revoke / tenant-membership consumers, issue #1559/#1560) must derive the
+// key through this helper — never build the string inline on either side.
+export function userAccessChannel(userId: string): string {
+  return `user:${userId}:access`;
+}

package/src/engine/create-app.ts

@@ -53,6 +53,17 @@ export function createApp(config: AppConfig): App {
         }
       }
     }
+    for (const handler of Object.values(feature.streamHandlers)) {
+      if (handler.access && "roles" in handler.access) {
+        for (const role of handler.access.roles) {
+          if (!validRoles.has(role)) {
+            throw new Error(
+              `Unknown role "${role}" in stream handler "${handler.name}" of feature "${feature.name}". Valid roles: ${config.roles.join(", ")}`,
+            );
+          }
+        }
+      }
+    }
     for (const [key, keyDef] of Object.entries(feature.configKeys)) {
       for (const role of [...keyDef.access.read, ...keyDef.access.write]) {
         if (!systemRoles.has(role) && !validRoles.has(role)) {

package/src/engine/effective-features.ts

@@ -1,4 +1,4 @@
-import type { Registry } from "./types";
+import type { FeatureDefinition, Registry } from "./types";
 
 // Callback that returns the current global-toggle override for a feature.
 // `true`  = explicit global row says enabled.
@@ -11,6 +11,16 @@ import type { Registry } from "./types";
 // a Map lookup to keep compute() allocation-light.
 export type ToggleReader = (featureName: string) => boolean | undefined;
 
+// A feature is toggleable iff it declared r.toggleable() at define-time
+// (toggleableDefault set). Non-toggleable features are always-on and ignore
+// overrides entirely — used here, by compose-tier-resolver, and by
+// tier-engine's always-on set to agree on the same rule.
+export function isToggleableFeature(
+  feature: FeatureDefinition,
+): feature is FeatureDefinition & { toggleableDefault: boolean } {
+  return feature.toggleableDefault !== undefined;
+}
+
 // Compute the set of effectively-enabled features for the current call.
 //
 // Rules (AND-combined, any false wins):
@@ -35,7 +45,7 @@ export function computeEffectiveFeatures(
   // Raw enablement, before cascade.
   const raw = new Map<string, boolean>();
   for (const feature of registry.features.values()) {
-    if (feature.toggleableDefault === undefined) {
+    if (!isToggleableFeature(feature)) {
       raw.set(feature.name, true);
       continue;
     }

package/src/engine/extensions/user-data.ts

@@ -150,14 +150,22 @@ export type UserDataExportHook = (ctx: UserDataHookCtx) => Promise<UserDataExpor
  * `{status:"incomplete", reason}` to signal a partial success to the
  * cleanup runner (e.g. an external provider call failed) without
  * throwing/rolling back the sub-transaction. Existing `void` returners
- * stay valid unchanged.
+ * stay valid unchanged — including ones explicitly typed
+ * `Promise<void>` (an explicitly-annotated hook, unlike a contextually-
+ * typed arrow literal, needs `void` in the union itself: `void` is not
+ * assignable to `undefined`).
  */
+// Intentional: void (not undefined) is required here so an explicitly-typed
+// `Promise<void>` hook stays assignable (see UserDataDeleteHook's doc
+// comment above).
+export type UserDataDeleteHookResult =
+  // biome-ignore lint/suspicious/noConfusingVoidType: see comment above
+  void | { readonly status: "ok" } | { readonly status: "incomplete"; readonly reason: string };
+
 export type UserDataDeleteHook = (
   ctx: UserDataHookCtx,
   strategy: UserDataDeleteStrategy,
-) => Promise<
-  undefined | { readonly status: "ok" } | { readonly status: "incomplete"; readonly reason: string }
->;
+) => Promise<UserDataDeleteHookResult>;
 
 /**
  * Komplette Hook-Tafel für EXT_USER_DATA. Sprint 2 user-data-rights

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

@@ -258,6 +258,7 @@ describe("render → parse roundtrip — mixed patterns (header data + opaque bo
 // from the parsed FeaturePattern shape alone.
 const RAW_REF_FEATURE = `
 import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import { chatCompleteHandler } from "./handlers";
 
 const eventEntity = {
   fields: { name: { type: "text", required: true } },
@@ -284,6 +285,7 @@ defineFeature("refs", (r) => {
   r.entity("event", eventEntity);
   r.entity("task", { fields: buildFields() });
   r.writeHandler(makeHandler());
+  r.streamHandler(chatCompleteHandler);
   r.screen(eventListScreen);
 });
 `;
@@ -297,6 +299,7 @@ describe("render → parse roundtrip — unresolved references (raw-ref sentinel
       { kind: "entity", entityName: "event", definition: { __raw: "eventEntity" } },
       { kind: "entity", entityName: "task", definition: { fields: { __raw: "buildFields()" } } },
       { kind: "writeHandler", handlerName: undefined },
+      { kind: "streamHandler", handlerName: undefined },
       { kind: "screen", definition: { __raw: "eventListScreen" } },
     ]);
   });
@@ -310,6 +313,7 @@ describe("render → parse roundtrip — unresolved references (raw-ref sentinel
     expect(rendered).toContain("eventEntity");
     expect(rendered).toContain("buildFields()");
     expect(rendered).toContain("r.writeHandler(makeHandler())");
+    expect(rendered).toContain("r.streamHandler(chatCompleteHandler)");
     expect(rendered).toContain("r.screen(eventListScreen);");
     // Would only appear if buildFields()'s return value got inlined.
     expect(rendered).not.toContain("title:");

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

@@ -204,21 +204,24 @@ export function extractWriteHandler(
   });
 }
 
-export function extractQueryHandler(
-  call: CallExpression,
-  sourceFile: SourceFile,
-): ExtractOutput<QueryHandlerPattern> {
-  const parsed = parseHandlerCall(call, sourceFile, "queryHandler");
-  if (parsed.kind === "error") return parsed;
-  return ok({
-    kind: "queryHandler",
+function readHandlerFields(parsed: Extract<ExtractOutput<ParsedHandlerCall>, { kind: "pattern" }>) {
+  return {
     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 }),
-  });
+  };
+}
+
+export function extractQueryHandler(
+  call: CallExpression,
+  sourceFile: SourceFile,
+): ExtractOutput<QueryHandlerPattern> {
+  const parsed = parseHandlerCall(call, sourceFile, "queryHandler");
+  if (parsed.kind === "error") return parsed;
+  return ok({ kind: "queryHandler", ...readHandlerFields(parsed) });
 }
 
 export function extractStreamHandler(
@@ -227,13 +230,5 @@ export function extractStreamHandler(
 ): 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 }),
-  });
+  return ok({ kind: "streamHandler", ...readHandlerFields(parsed) });
 }