@cosmicdrift/kumiko-framework 0.199.1 → 0.200.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.199.1",
+  "version": "0.200.0",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -186,7 +186,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-types": "0.199.1",
+    "@cosmicdrift/kumiko-types": "0.200.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.13.1",
@@ -202,7 +202,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.199.1",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.200.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/engine/entity-handlers.ts

@@ -176,6 +176,19 @@ export function defineEntityWriteHandler(
   const table = buildEntityTable(entityName, entity);
   const executor = createEventStoreExecutor(table, entity, { entityName });
 
+  // r.systemScope() features (tenant, config, secrets, ...) hand their
+  // entity-convention handlers a fail-closed ctx.db — this generic layer
+  // has no per-call business reason to give assertTenantMatch, so it
+  // acknowledges cross-tenant access on the feature's behalf. This is
+  // behavior-preserving: ctx.db was already an unfiltered "system"-mode
+  // TenantDb for these handlers before the ctx.db cutover.
+  const dbFor = (ctx: HandlerContext): TenantDb =>
+    ctx.systemDb
+      ? ctx.systemDb.acknowledgeCrossTenant(
+          `entity convention handler for r.systemScope() feature (${name})`,
+        )
+      : ctx.db;
+
   let schema: ZodType;
   let handler: WriteHandlerDef["handler"];
 
@@ -184,7 +197,7 @@ export function defineEntityWriteHandler(
       schema = buildInsertSchema(entity);
       handler = async (event, ctx) => {
         const { runPreSave } = ctx;
-        return executor.create(event.payload as DbRow, event.user, ctx.db, {
+        return executor.create(event.payload as DbRow, event.user, dbFor(ctx), {
           preSave:
             runPreSave &&
             ((changes, previous, isNew) => runPreSave(event.type, changes, previous, isNew)),
@@ -205,7 +218,7 @@ export function defineEntityWriteHandler(
         // KEK-rotation, the user-data-rights #494 backfill) don't go through
         // this handler and keep today's always-re-encrypt behavior, which
         // they rely on to intentionally force a fresh event/ciphertext.
-        return executor.update(event.payload as UpdatePayload, event.user, ctx.db, {
+        return executor.update(event.payload as UpdatePayload, event.user, dbFor(ctx), {
           skipUnchanged: true,
           preSave:
             runPreSave &&
@@ -216,12 +229,12 @@ export function defineEntityWriteHandler(
     case "delete":
       schema = idSchema;
       handler = async (event, ctx) =>
-        executor.delete(event.payload as IdPayload, event.user, ctx.db); // @cast-boundary engine-payload
+        executor.delete(event.payload as IdPayload, event.user, dbFor(ctx)); // @cast-boundary engine-payload
       break;
     case "restore":
       schema = idSchema;
       handler = async (event, ctx) =>
-        executor.restore(event.payload as IdPayload, event.user, ctx.db); // @cast-boundary engine-payload
+        executor.restore(event.payload as IdPayload, event.user, dbFor(ctx)); // @cast-boundary engine-payload
       break;
     default:
       assertUnreachable(verb, "write verb");
@@ -271,24 +284,36 @@ export function defineEntityQueryHandler(
   let schema: ZodType;
   let handler: QueryHandlerDef["handler"];
 
-  // Tier 2.7e Server-Eagerload: wenn die entity reference-Felder hat,
-  // resolved der handler nach dem Haupt-Query die UUIDs gegen die
-  // referenced entities. Das `_refs`-Property landet auf jeder Row;
-  // Renderer-Side useReferenceLookup bleibt als Fallback bestehen
-  // (für Apps die manuell Custom-Handler schreiben ohne diesen
-  // Wrapper zu nutzen).
+  // Tier 2.7e server-eagerload: when the entity has reference fields, the
+  // handler resolves the UUIDs against the referenced entities after the
+  // main query. The `_refs` property lands on every row; the renderer-side
+  // useReferenceLookup stays as a fallback (for apps that write custom
+  // handlers by hand without this wrapper).
   const hasRefFields = collectReferenceFields(entity).length > 0;
 
-  // crossTenant: this ONE handler reads across every tenant (e.g. a
-  // SystemAdmin-only operator inspector) without making the whole feature
-  // r.systemScope() — that would drop tenant isolation from every OTHER
-  // handler the feature registers too. The executor's list()/detail() only
-  // add a tenant filter when db.mode === "tenant" (see event-store-executor
-  // .ts), so handing them a "system"-mode TenantDb built from the same raw
-  // connection is enough to skip it — access-control (who may call this
-  // handler at all) is unaffected, still gated by `options.access`.
-  const dbFor = (ctx: HandlerContext): TenantDb =>
-    options?.crossTenant ? createTenantDb(ctx.db.raw, ctx.db.tenantId, "system") : ctx.db;
+  // Preference order:
+  //  1. ctx.systemDb — the feature declared r.systemScope() (whole-feature
+  //     cutover, dispatch-shared.ts), so ctx.db is fail-closed. This is
+  //     behavior-preserving: ctx.db was already an unfiltered "system"-mode
+  //     TenantDb for these handlers before that cutover.
+  //  2. options.crossTenant — this ONE handler reads across every tenant
+  //     (e.g. a SystemAdmin-only operator inspector) without making the
+  //     whole feature r.systemScope() — that would drop tenant isolation
+  //     from every OTHER handler the feature registers too. The executor's
+  //     list()/detail() only add a tenant filter when db.mode === "tenant"
+  //     (see event-store-executor.ts), so handing them a "system"-mode
+  //     TenantDb built from the same raw connection is enough to skip it —
+  //     access-control (who may call this handler at all) is unaffected,
+  //     still gated by `options.access`.
+  //  3. plain ctx.db — the common case, tenant-filtered.
+  const dbFor = (ctx: HandlerContext): TenantDb => {
+    if (ctx.systemDb) {
+      return ctx.systemDb.acknowledgeCrossTenant(
+        `entity convention handler for r.systemScope() feature (${entityName}:${verb})`,
+      );
+    }
+    return options?.crossTenant ? createTenantDb(ctx.db.raw, ctx.db.tenantId, "system") : ctx.db;
+  };
 
   switch (verb) {
     case "list":

package/src/engine/feature-ast/__tests__/fixtures/cross-file-name-const/constants.ts

@@ -0,0 +1 @@
+export const EXT_AUDIT = "audit" as const;

package/src/engine/feature-ast/__tests__/fixtures/cross-file-name-const/feature.ts

@@ -0,0 +1,8 @@
+import { EXT_AUDIT } from "./constants";
+
+// biome-ignore lint/suspicious/noExplicitAny: structural parser test fixture, never executed or type-checked at runtime
+declare function defineFeature(name: string, setup: (r: any) => void): void;
+
+defineFeature("cross-file-name-const", (r) => {
+  r.extendsRegistrar(EXT_AUDIT, {});
+});

package/src/engine/feature-ast/__tests__/parse.test.ts

@@ -473,7 +473,7 @@ defineFeature("f", (r) => {
     expect(result.errors[0]?.methodName).toBe("entity");
   });
 
-  test("emits a ParseError when the name is not a string literal", () => {
+  test("resolves the name when it's an identifier initialized to a string literal", () => {
     const result = parseInline(`
 const ENTITY = "task";
 defineFeature("f", (r) => {
@@ -481,6 +481,22 @@ defineFeature("f", (r) => {
 });
 `);
 
+    expect(result.errors).toEqual([]);
+    expect(result.patterns[0]).toMatchObject({
+      kind: "entity",
+      entityName: "task",
+    });
+  });
+
+  test("emits a ParseError when the name identifier does not resolve to a string literal", () => {
+    const result = parseInline(`
+const ENTITY = computeEntityName();
+defineFeature("f", (r) => {
+  r.entity(ENTITY, { fields: {} });
+});
+`);
+
+    expect(result.patterns).toEqual([]);
     expect(result.errors[0]?.methodName).toBe("entity");
   });
 
@@ -2366,3 +2382,18 @@ describe("cross-file registrar-wrapper resolution against a real filesystem Proj
     expect(navPattern?.source.file).not.toBe(fixture);
   });
 });
+
+// #1746 — registrar-call name args authored as an imported constant
+// (`r.useExtension(EXT_TENANT_DATA, ...)`) instead of a string literal.
+// This is the dominant real-world style across the framework's own
+// bundled-features (see extension-names.ts), and previously ParseErrored
+// on every such call.
+describe("cross-file imported-constant name resolution against a real filesystem Project (#1746)", () => {
+  const fixture = resolve(__dirname, "fixtures/cross-file-name-const/feature.ts");
+  const result = parseFeatureFile(fixture);
+
+  test("resolves the identifier to the imported const's string value", () => {
+    expect(result.errors).toEqual([]);
+    expect(result.patterns).toMatchObject([{ kind: "extendsRegistrar", extensionName: "audit" }]);
+  });
+});

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

@@ -9,6 +9,7 @@ import {
   findFunctionLiteral,
   ok,
   readDataLiteralNode,
+  readNameLiteral,
   readNameOrRef,
   readPropertyKey,
 } from "./shared";
@@ -146,12 +147,12 @@ export function extractDefineEvent(
     });
   }
 
-  const nameArg = first.asKind(SyntaxKind.StringLiteral);
-  if (!nameArg) {
+  const eventName = readNameLiteral(first);
+  if (eventName === undefined) {
     return fail(
       "defineEvent",
       sourceLocationFromNode(call, sourceFile),
-      "first argument must be a string literal event name (or use the object form)",
+      "first argument must be a string literal event name, or an identifier resolving to one (or use the object form)",
     );
   }
   const schemaArg = args[1];
@@ -186,7 +187,7 @@ export function extractDefineEvent(
   return ok({
     kind: "defineEvent",
     source: sourceLocationFromNode(call, sourceFile),
-    eventName: nameArg.getLiteralValue(),
+    eventName,
     schemaSource: sourceLocationFromNode(schemaArg, sourceFile),
     ...(version !== undefined && { version }),
     ...(migrations !== undefined && { migrations }),
@@ -207,31 +208,32 @@ export function extractNotification(
     );
   }
 
-  let nameLiteral: ReturnType<typeof first.asKind<SyntaxKind.StringLiteral>>;
+  let notificationName: string | undefined;
   let defObj: ReturnType<typeof first.asKind<SyntaxKind.ObjectLiteralExpression>>;
 
   const firstObj = first.asKind(SyntaxKind.ObjectLiteralExpression);
   if (firstObj && args.length === 1) {
-    nameLiteral = firstObj
+    const nameInit = firstObj
       .getProperty("name")
       ?.asKind(SyntaxKind.PropertyAssignment)
       ?.getInitializer()
       ?.asKind(SyntaxKind.StringLiteral);
-    if (!nameLiteral) {
+    if (!nameInit) {
       return fail(
         "notification",
         sourceLocationFromNode(call, sourceFile),
         "object form requires a string-literal `name` property",
       );
     }
+    notificationName = nameInit.getLiteralValue();
     defObj = firstObj;
   } else {
-    nameLiteral = first.asKind(SyntaxKind.StringLiteral);
-    if (!nameLiteral) {
+    notificationName = readNameLiteral(first);
+    if (notificationName === undefined) {
       return fail(
         "notification",
         sourceLocationFromNode(call, sourceFile),
-        "first argument must be a string literal notification name (or use the object form)",
+        "first argument must be a string literal notification name, or an identifier resolving to one (or use the object form)",
       );
     }
     defObj = args[1]?.asKind(SyntaxKind.ObjectLiteralExpression);
@@ -243,7 +245,6 @@ export function extractNotification(
       );
     }
   }
-  const nameArg = nameLiteral;
   const triggerObj = defObj
     .getProperty("trigger")
     ?.asKind(SyntaxKind.PropertyAssignment)
@@ -313,7 +314,7 @@ export function extractNotification(
   return ok({
     kind: "notification",
     source: sourceLocationFromNode(call, sourceFile),
-    notificationName: nameArg.getLiteralValue(),
+    notificationName,
     trigger: { on: onName },
     recipientBody: sourceLocationFromNode(recipientFn, sourceFile),
     dataBody: sourceLocationFromNode(dataFn, sourceFile),

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

@@ -14,6 +14,7 @@ import {
   ok,
   readBooleanProperty,
   readDataLiteralNode,
+  readNameLiteral,
 } from "./shared";
 
 export type ParsedHandlerCall = {
@@ -134,12 +135,12 @@ export function parseHandlerCall(
   if (args.length === 1 && isRawRefSentinel(readDataLiteralNode(first))) {
     return ok({ source: sourceLocationFromNode(call, sourceFile) });
   }
-  const nameLiteral = first.asKind(SyntaxKind.StringLiteral);
-  if (!nameLiteral) {
+  const handlerName = readNameLiteral(first);
+  if (handlerName === undefined) {
     return fail(
       methodName,
       sourceLocationFromNode(call, sourceFile),
-      "first argument must be a string literal handler name (or use the object form)",
+      "first argument must be a string literal handler name, or an identifier resolving to one (or use the object form)",
     );
   }
   const schemaArg = args[1];
@@ -178,7 +179,7 @@ export function parseHandlerCall(
   }
   return ok({
     source: sourceLocationFromNode(call, sourceFile),
-    handlerName: nameLiteral.getLiteralValue(),
+    handlerName,
     schemaSource: sourceLocationFromNode(schemaArg, sourceFile),
     handlerBody: sourceLocationFromNode(fn, sourceFile),
     ...(access !== undefined && { access }),

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

@@ -12,6 +12,7 @@ import {
   isPlainObject,
   ok,
   readDataLiteralNode,
+  readNameLiteral,
   readNameOrRef,
   readNameOrRefOrList,
 } from "./shared";
@@ -155,15 +156,14 @@ export function extractHook(
     });
   }
 
-  const typeArg = first.asKind(SyntaxKind.StringLiteral);
-  if (!typeArg) {
+  const hookType = readNameLiteral(first);
+  if (hookType === undefined) {
     return fail(
       "hook",
       sourceLocationFromNode(call, sourceFile),
-      "first argument must be a string literal hook type (or use the object form)",
+      "first argument must be a string literal hook type, or an identifier resolving to one (or use the object form)",
     );
   }
-  const hookType = typeArg.getLiteralValue();
   if (!isHookType(hookType)) {
     return fail(
       "hook",

package/src/engine/feature-ast/extractors/jobs-routes.ts

@@ -12,6 +12,7 @@ import {
   ok,
   readBooleanProperty,
   readDataLiteralNode,
+  readNameLiteral,
   readPropertyKey,
 } from "./shared";
 
@@ -97,12 +98,12 @@ export function extractJob(
     });
   }
 
-  const nameArg = first.asKind(SyntaxKind.StringLiteral);
-  if (!nameArg) {
+  const jobName = readNameLiteral(first);
+  if (jobName === undefined) {
     return fail(
       "job",
       sourceLocationFromNode(call, sourceFile),
-      "first argument must be a string literal job name (or use the object form)",
+      "first argument must be a string literal job name, or an identifier resolving to one (or use the object form)",
     );
   }
   const optionsArg = args[1];
@@ -140,7 +141,7 @@ export function extractJob(
   return ok({
     kind: "job",
     source: sourceLocationFromNode(call, sourceFile),
-    jobName: nameArg.getLiteralValue(),
+    jobName,
     options: options as Omit<JobDefinition, "name" | "handler">,
     handlerBody: sourceLocationFromNode(fn, sourceFile),
   });

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

@@ -12,6 +12,7 @@ import {
   isPlainObject,
   ok,
   readDataLiteralNode,
+  readNameLiteral,
   readNameOrRef,
 } from "./shared";
 
@@ -60,12 +61,12 @@ export function extractEntity(
     });
   }
 
-  const nameArg = first.asKind(SyntaxKind.StringLiteral);
-  if (!nameArg) {
+  const entityName = readNameLiteral(first);
+  if (entityName === undefined) {
     return fail(
       "entity",
       sourceLocationFromNode(call, sourceFile),
-      "first argument must be a string literal name (or use the object form)",
+      "first argument must be a string literal name, or an identifier resolving to one (or use the object form)",
     );
   }
   const defArg = args[1];
@@ -87,7 +88,7 @@ export function extractEntity(
   return ok({
     kind: "entity",
     source: sourceLocationFromNode(call, sourceFile),
-    entityName: nameArg.getLiteralValue(),
+    entityName,
     definition: definition as EntityDefinition,
   });
 }
@@ -165,12 +166,13 @@ export function extractRelation(
       'first argument must be a string literal or an inline { name: "..." } object (or use the object form)',
     );
   }
-  const nameArg = args[1]?.asKind(SyntaxKind.StringLiteral);
-  if (!nameArg) {
+  const relationNameArg = args[1];
+  const relationName = relationNameArg && readNameLiteral(relationNameArg);
+  if (!relationName) {
     return fail(
       "relation",
       sourceLocationFromNode(call, sourceFile),
-      "second argument must be a string literal relation name",
+      "second argument must be a string literal relation name, or an identifier resolving to one",
     );
   }
   const defArg = args[2];
@@ -193,7 +195,7 @@ export function extractRelation(
     kind: "relation",
     source: sourceLocationFromNode(call, sourceFile),
     entityName,
-    relationName: nameArg.getLiteralValue(),
+    relationName,
     definition: definition as RelationDefinition,
   });
 }

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

@@ -20,6 +20,7 @@ import {
   isPlainObject,
   ok,
   readDataLiteralNode,
+  readNameLiteral,
   readNameOrRef,
 } from "./shared";
 
@@ -68,12 +69,12 @@ export function readNamedOptions(
     return { kind: "ok", name: nameInit.getLiteralValue(), options: optionsWithoutName };
   }
 
-  const nameLiteral = first.asKind(SyntaxKind.StringLiteral);
-  if (!nameLiteral) {
+  const name = readNameLiteral(first);
+  if (name === undefined) {
     return fail(
       methodName,
       sourceLocationFromNode(call, sourceFile),
-      "first argument must be a string literal name (or use the object form)",
+      "first argument must be a string literal name, or an identifier resolving to one (or use the object form)",
     );
   }
   const optionsArg = args[1];
@@ -92,7 +93,7 @@ export function readNamedOptions(
       "options could not be read as a plain object",
     );
   }
-  return { kind: "ok", name: nameLiteral.getLiteralValue(), options };
+  return { kind: "ok", name, options };
 }
 
 export function extractConfig(
@@ -424,12 +425,12 @@ export function extractUseExtension(
     });
   }
 
-  const nameArg = first.asKind(SyntaxKind.StringLiteral);
-  if (!nameArg) {
+  const extensionName = readNameLiteral(first);
+  if (extensionName === undefined) {
     return fail(
       "useExtension",
       sourceLocationFromNode(call, sourceFile),
-      "first argument must be a string literal extension name (or use the object form)",
+      "first argument must be a string literal extension name, or an identifier resolving to one (or use the object form)",
     );
   }
   const entityRefArg = args[1];
@@ -464,7 +465,7 @@ export function extractUseExtension(
   return ok({
     kind: "useExtension",
     source: sourceLocationFromNode(call, sourceFile),
-    extensionName: nameArg.getLiteralValue(),
+    extensionName,
     entityName,
     ...(options !== undefined && { options }),
   });

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

@@ -1,5 +1,4 @@
 import type { CallExpression, SourceFile } from "ts-morph";
-import { SyntaxKind } from "ts-morph";
 import type {
   EnvSchemaPattern,
   ExposesApiPattern,
@@ -7,7 +6,7 @@ import type {
   UsesApiPattern,
 } from "../patterns";
 import { sourceLocationFromNode } from "../source-location";
-import { type ExtractOutput, fail, ok } from "./shared";
+import { type ExtractOutput, fail, ok, readNameLiteral } from "./shared";
 
 export function extractEnvSchema(
   call: CallExpression,
@@ -33,12 +32,13 @@ export function extractExtendsRegistrar(
   sourceFile: SourceFile,
 ): ExtractOutput<ExtendsRegistrarPattern> {
   const args = call.getArguments();
-  const nameArg = args[0]?.asKind(SyntaxKind.StringLiteral);
-  if (!nameArg) {
+  const first = args[0];
+  const extensionName = first && readNameLiteral(first);
+  if (!extensionName) {
     return fail(
       "extendsRegistrar",
       sourceLocationFromNode(call, sourceFile),
-      "first argument must be a string literal extension name",
+      "first argument must be a string literal extension name, or an identifier resolving to one",
     );
   }
   const defArg = args[1];
@@ -52,7 +52,7 @@ export function extractExtendsRegistrar(
   return ok({
     kind: "extendsRegistrar",
     source: sourceLocationFromNode(call, sourceFile),
-    extensionName: nameArg.getLiteralValue(),
+    extensionName,
     defBody: sourceLocationFromNode(defArg, sourceFile),
   });
 }
@@ -61,18 +61,19 @@ export function extractUsesApi(
   call: CallExpression,
   sourceFile: SourceFile,
 ): ExtractOutput<UsesApiPattern> {
-  const arg = call.getArguments()[0]?.asKind(SyntaxKind.StringLiteral);
-  if (!arg) {
+  const arg = call.getArguments()[0];
+  const apiName = arg && readNameLiteral(arg);
+  if (!apiName) {
     return fail(
       "usesApi",
       sourceLocationFromNode(call, sourceFile),
-      'expected a single string-literal API name (e.g. "sessions.revokeAllForUser")',
+      'expected a single string-literal API name (e.g. "sessions.revokeAllForUser"), or an identifier resolving to one',
     );
   }
   return ok({
     kind: "usesApi",
     source: sourceLocationFromNode(call, sourceFile),
-    apiName: arg.getLiteralValue(),
+    apiName,
   });
 }
 
@@ -80,18 +81,19 @@ export function extractExposesApi(
   call: CallExpression,
   sourceFile: SourceFile,
 ): ExtractOutput<ExposesApiPattern> {
-  const arg = call.getArguments()[0]?.asKind(SyntaxKind.StringLiteral);
-  if (!arg) {
+  const arg = call.getArguments()[0];
+  const apiName = arg && readNameLiteral(arg);
+  if (!apiName) {
     return fail(
       "exposesApi",
       sourceLocationFromNode(call, sourceFile),
-      'expected a single string-literal API name (e.g. "sessions.revokeAllForUser")',
+      'expected a single string-literal API name (e.g. "sessions.revokeAllForUser"), or an identifier resolving to one',
     );
   }
   return ok({
     kind: "exposesApi",
     source: sourceLocationFromNode(call, sourceFile),
-    apiName: arg.getLiteralValue(),
+    apiName,
   });
 }
 

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

@@ -175,9 +175,65 @@ export function readPropertyKey(propAssign: import("ts-morph").PropertyAssignmen
   return propAssign.getName();
 }
 
-export function readNameOrRef(node: Node): string | undefined {
+function unwrapLiteralInitializer(node: Node): string | undefined {
+  const literal =
+    node.asKind(SyntaxKind.StringLiteral) ?? node.asKind(SyntaxKind.NoSubstitutionTemplateLiteral);
+  if (literal) return literal.getLiteralValue();
+  const asExpr = node.asKind(SyntaxKind.AsExpression);
+  if (asExpr) return unwrapLiteralInitializer(asExpr.getExpression());
+  const satisfiesExpr = node.asKind(SyntaxKind.SatisfiesExpression);
+  if (satisfiesExpr) return unwrapLiteralInitializer(satisfiesExpr.getExpression());
+  const paren = node.asKind(SyntaxKind.ParenthesizedExpression);
+  if (paren) return unwrapLiteralInitializer(paren.getExpression());
+  return undefined;
+}
+
+/**
+ * Resolves a bare Identifier to the string value of its declaration's
+ * initializer (`export const EXT_TENANT_DATA = "tenant-data" as const`),
+ * following imports via ts-morph's definition lookup — works across files
+ * and packages against a real-filesystem Project (see #1008 precedent in
+ * parse.ts). Only descends into VariableDeclaration initializers; a
+ * function/class/type definition or an unresolvable import (external
+ * package, ambient declaration) yields undefined, never a throw.
+ */
+function resolveIdentifierToStringLiteral(identifier: Node): string | undefined {
+  const id = identifier.asKind(SyntaxKind.Identifier);
+  if (!id) return undefined;
+  let defs: readonly Node[];
+  try {
+    defs = id.getDefinitionNodes();
+  } catch {
+    return undefined;
+  }
+  for (const def of defs) {
+    const init = def.asKind(SyntaxKind.VariableDeclaration)?.getInitializer();
+    if (!init) continue;
+    const value = unwrapLiteralInitializer(init);
+    if (value !== undefined) return value;
+  }
+  return undefined;
+}
+
+/**
+ * A node's string value when it's a string literal, or when it's a bare
+ * Identifier that resolves to one via a `const X = "..."` declaration
+ * (same-file or imported) — the pattern used throughout the framework's
+ * own bundled-features for registrar-call names (`EXT_TENANT_DATA`,
+ * `TENANT_SECRET_READ_EVENT`, ...) instead of repeating string literals.
+ * undefined for anything unresolvable (factory call, member access,
+ * external/ambient identifier) — callers keep their existing ParseError
+ * fallback, no crash.
+ */
+export function readNameLiteral(node: Node): string | undefined {
   const literal = node.asKind(SyntaxKind.StringLiteral);
   if (literal) return literal.getLiteralValue();
+  return resolveIdentifierToStringLiteral(node);
+}
+
+export function readNameOrRef(node: Node): string | undefined {
+  const literal = readNameLiteral(node);
+  if (literal !== undefined) return literal;
   const obj = readDataLiteralNode(node);
   if (isPlainObject(obj) && typeof obj["name"] === "string") return obj["name"];
   return undefined;

package/src/pipeline/__tests__/ctx-systemdb.integration.test.ts

@@ -13,13 +13,25 @@ const systemScopedFeature = defineFeature("ctxsystemdb-system", (r) => {
     "check",
     z.object({}),
     async (query, ctx) => {
-      if (!ctx.systemDb) return { present: false as const };
-      // assertTenantMatch returns the underlying TenantDb — proves systemDb
-      // is bound to the SAME internally-built TenantDb as ctx.db, not a
-      // separate instance (dispatch-shared.ts builds `as HandlerContext`,
-      // so a mis-wired property wouldn't be caught by tsc).
+      if (!ctx.systemDb)
+        return { present: false as const, tenantIdMatches: false, dbThrows: false };
+      // ctx.db is fail-closed for r.systemScope() handlers — dispatch-shared.ts
+      // builds `as HandlerContext`, so a mis-wired property wouldn't be caught
+      // by tsc. Prove it at runtime: assertTenantMatch must hand back a
+      // working, correctly-scoped TenantDb, and touching ctx.db itself must
+      // throw instead of silently returning an unfiltered db.
       const checked = ctx.systemDb.assertTenantMatch(query.user.tenantId);
-      return { present: true as const, boundToDb: checked === ctx.db };
+      let dbThrows = false;
+      try {
+        void ctx.db.tenantId;
+      } catch {
+        dbThrows = true;
+      }
+      return {
+        present: true as const,
+        tenantIdMatches: checked.tenantId === query.user.tenantId,
+        dbThrows,
+      };
     },
     { access: { roles: ["Admin"] } },
   );
@@ -29,7 +41,10 @@ const tenantScopedFeature = defineFeature("ctxsystemdb-tenant", (r) => {
   r.queryHandler(
     "check",
     z.object({}),
-    async (_query, ctx) => ({ present: ctx.systemDb !== undefined }),
+    async (query, ctx) => ({
+      present: ctx.systemDb !== undefined,
+      dbWorks: ctx.db.tenantId === query.user.tenantId,
+    }),
     { access: { roles: ["Admin"] } },
   );
 });
@@ -46,22 +61,24 @@ afterAll(async () => {
 });
 
 describe("ctx.systemDb", () => {
-  test("is present and bound to ctx.db for r.systemScope() handlers", async () => {
-    const result = await stack.http.queryOk<{ present: boolean; boundToDb: boolean }>(
-      "ctxsystemdb-system:query:check",
-      {},
-      admin,
-    );
+  test("is present for r.systemScope() handlers; ctx.db is fail-closed there", async () => {
+    const result = await stack.http.queryOk<{
+      present: boolean;
+      tenantIdMatches: boolean;
+      dbThrows: boolean;
+    }>("ctxsystemdb-system:query:check", {}, admin);
     expect(result.present).toBe(true);
-    expect(result.boundToDb).toBe(true);
+    expect(result.tenantIdMatches).toBe(true);
+    expect(result.dbThrows).toBe(true);
   });
 
-  test("is absent for non-system-scoped handlers", async () => {
-    const result = await stack.http.queryOk<{ present: boolean }>(
+  test("is absent for non-system-scoped handlers; ctx.db works normally there", async () => {
+    const result = await stack.http.queryOk<{ present: boolean; dbWorks: boolean }>(
       "ctxsystemdb-tenant:query:check",
       {},
       admin,
     );
     expect(result.present).toBe(false);
+    expect(result.dbWorks).toBe(true);
   });
 });

package/src/pipeline/cascade-handler.ts

@@ -17,13 +17,17 @@ export function createCascadeDeleteHook(
     priority: SystemHookPriorities.cascadeDelete,
     fn: async (payload, ctx) => {
       const entityName = payload.entityName;
-      if (!entityName || !ctx.db) {
+      const db = ctx.systemDb
+        ? ctx.systemDb.acknowledgeCrossTenant(
+            `cascade delete for r.systemScope() write handler (${entityName ?? "unknown"})`,
+          )
+        : ctx.db;
+      if (!entityName || !db) {
         ctx.log?.debug(
           `cascadeDelete: skipping — ${!entityName ? "no entityName" : "no db"} on payload ${payload.id}`,
         );
         return;
       }
-      const db = ctx.db;
 
       // Cascade applies to outgoing hasMany / manyToMany relations only —
       // the parent side of the link is where `onDelete` lives (see

package/src/pipeline/dispatch-shared.ts

@@ -3,7 +3,7 @@ import type { SseBroker } from "../api/sse-broker";
 import type { DbConnection, DbRunner, DbTx } from "../db/connection";
 import { runInSavepoint, selectMany } from "../db/query";
 import type { buildEntityTable } from "../db/table-builder";
-import { createTenantDb, createUncheckedSystemDb } from "../db/tenant-db";
+import { createTenantDb, createUncheckedSystemDb, type TenantDb } from "../db/tenant-db";
 import { createDerivativesContext } from "../derivatives/derivatives-context";
 import type { defineTransitions } from "../engine/state-machine";
 import type { EffectiveFeaturesResolver } from "../engine/tier-resolver-extension";
@@ -155,6 +155,27 @@ async function appendDomainEvent(
   );
 }
 
+// r.systemScope() handlers must go through ctx.systemDb's guarded methods
+// (assertTenantMatch / acknowledgeCrossTenant) instead of plain ctx.db —
+// "system" mode has no tenant filter at all, so silent ctx.db use there is a
+// cross-tenant leak. HandlerContext.db has no way to become optional per
+// handler (isSystem is a runtime-only registry lookup, not a type-level
+// discriminant), so instead of omitting the key we hand back a Proxy that
+// throws on first touch, naming the handler and pointing at ctx.systemDb.
+function createSystemScopedDbGuard(handlerType: string): TenantDb {
+  return new Proxy({} as TenantDb, {
+    get(_target, prop) {
+      throw new InternalError({
+        message:
+          `Handler "${handlerType}" is r.systemScope()'d — ctx.db is unavailable ` +
+          `(it would be unfiltered across every tenant). Use ` +
+          `ctx.systemDb.assertTenantMatch(...) or ctx.systemDb.acknowledgeCrossTenant(...) ` +
+          `instead (attempted to read "${String(prop)}").`,
+      });
+    },
+  });
+}
+
 export async function buildHandlerContext(
   ctx: DispatchContext,
   type: string,
@@ -184,6 +205,10 @@ export async function buildHandlerContext(
   // the rest of the chain instead of burning DB-CPU for results no one reads.
   const db = dbSource ? buildTenantScopedDb(dbSource, reqCtx?.signal) : undefined;
   const systemDb = isSystem && db ? createUncheckedSystemDb(db) : undefined;
+  // Exposed as ctx.db below — the internal `db` above stays the real,
+  // working TenantDb for this function's own use (config/derivatives
+  // accessors, systemDb construction).
+  const exposedDb = isSystem && db ? createSystemScopedDbGuard(type) : db;
   // Unbound pool, tenant-scoped like `db` but never tx-bound — writes
   // through it survive a rollback of the handler's own transaction. No
   // AbortSignal here: a client disconnect must not abort a durability write
@@ -572,7 +597,7 @@ export async function buildHandlerContext(
   return {
     ...context,
     registry,
-    db,
+    db: exposedDb,
     dbOutsideTransaction,
     ...(systemDb && { systemDb }),
     log,

package/src/pipeline/dispatch-write.ts

@@ -350,10 +350,19 @@ async function executeWriteInner(
 
   const handlerContext = await buildHandlerContext(ctx, type, user, tx, afterCommitHooks);
 
-  // Auto transition guard: if entity has transitions and handler doesn't skip it
+  // Auto transition guard: if entity has transitions and handler doesn't skip it.
+  // Reads via the guard's own db handle — for r.systemScope() handlers
+  // handlerContext.db is fail-closed, so this reaches for
+  // systemDb.acknowledgeCrossTenant like any other framework-internal
+  // mechanism that touches a system-scoped handler's data.
+  const transitionGuardDb = handlerContext.systemDb
+    ? handlerContext.systemDb.acknowledgeCrossTenant(
+        `auto transition guard for r.systemScope() write handler (${type})`,
+      )
+    : handlerContext.db;
   if (entityName && !handler.unsafeSkipTransitionGuard) {
     const entity = registry.getEntity(entityName);
-    if (entity?.transitions && handlerContext.db) {
+    if (entity?.transitions && transitionGuardDb) {
       const parsedData = parsed.data as DbRow; // @cast-boundary engine-payload
       const changes = (parsedData["changes"] as DbRow) ?? parsedData; // @cast-boundary engine-payload
       const id = (parsedData["id"] as number) ?? undefined; // @cast-boundary engine-payload
@@ -373,8 +382,8 @@ async function executeWriteInner(
         // active (tests without a DB connection).
         const tableName = asEntityTableMeta(table)?.tableName ?? "";
         const rows = tx
-          ? await selectRowForUpdateById(handlerContext.db, tableName, id)
-          : await selectMany(handlerContext.db, table, { id });
+          ? await selectRowForUpdateById(transitionGuardDb, tableName, id)
+          : await selectMany(transitionGuardDb, table, { id });
         const row = rows[0];
 
         if (!row) continue;

package/src/pipeline/projections-runner.ts

@@ -26,7 +26,15 @@ import type { StoredEvent } from "../event-store";
 export async function runProjections(result: LifecycleResult, ctx: HandlerContext): Promise<void> {
   // skip: hand-crafted result with no event — nothing to project
   if (!result.event) return;
-  await runProjectionsForEvent(result.event, ctx.registry, ctx.db.raw);
+  // r.systemScope() handlers: ctx.db is fail-closed — custom projections are
+  // framework-wired, not per-handler opt-in, so this reaches for systemDb
+  // itself rather than pushing the concern onto every r.projection() author.
+  const tx = ctx.systemDb
+    ? ctx.systemDb.acknowledgeCrossTenant(
+        `inline projection apply for r.systemScope() write (${result.event.aggregateType})`,
+      ).raw
+    : ctx.db.raw;
+  await runProjectionsForEvent(result.event, ctx.registry, tx);
 }
 
 // Fire every projection whose source matches the event's aggregate type AND