@cosmicdrift/kumiko-framework 0.200.0 → 0.201.0

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

@@ -6,6 +6,7 @@
 // here narrows the cause to patch.ts itself.
 
 import { describe, expect, test } from "bun:test";
+import { resolve } from "node:path";
 import { Project, type SourceFile } from "ts-morph";
 import { parseSourceFile } from "../parse";
 import { addPattern, applyChanges, type PatternId, removePattern, replacePattern } from "../patch";
@@ -552,3 +553,100 @@ defineFeature("object", (r) => {
     expect(parseSourceFile(sf).patterns.find((p) => p.kind === "notification")).toBeUndefined();
   });
 });
+
+// #2121 — findCallForId only accepted a StringLiteral first argument, so
+// it couldn't locate calls authored with an imported/local constant name
+// (the dominant style in the framework's own bundled-features, per #1746
+// on the parser side). Covers both the single-arg case (matchFirstArgString)
+// and the two-arg case (relation/hook/useExtension's second positional arg),
+// same-file and genuinely cross-file via a real filesystem Project.
+describe("findCallForId resolves identifier-authored names (#2121)", () => {
+  function loadFixture(relPath: string): SourceFile {
+    const project = new Project({
+      skipAddingFilesFromTsConfig: true,
+      skipFileDependencyResolution: true,
+    });
+    return project.addSourceFileAtPath(resolve(__dirname, relPath));
+  }
+
+  const SAME_FILE_CONST = `
+import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+
+const ENTITY = "task";
+
+defineFeature("inventory", (r) => {
+  r.entity(ENTITY, { fields: { name: { type: "text", required: true } } });
+});
+`;
+
+  test("removePattern finds a call whose name arg is a same-file const identifier", () => {
+    const sf = makeSourceFile(SAME_FILE_CONST);
+    removePattern(sf, { kind: "entity", entityName: "task" });
+    const reparsed = parseSourceFile(sf);
+    expect(reparsed.errors).toEqual([]);
+    expect(reparsed.patterns).toEqual([]);
+  });
+
+  test("replacePattern finds a call whose name arg is a same-file const identifier", () => {
+    const sf = makeSourceFile(SAME_FILE_CONST);
+    const replacement: FeaturePattern = {
+      kind: "entity",
+      source: SAMPLE_LOC,
+      entityName: "task",
+      definition: {
+        fields: { name: { type: "text", required: true }, sku: { type: "text" } },
+      } as never,
+    };
+    replacePattern(sf, { kind: "entity", entityName: "task" }, replacement);
+    const reparsed = parseSourceFile(sf);
+    expect(reparsed.errors).toEqual([]);
+    const entity = reparsed.patterns.find((p) => p.kind === "entity");
+    if (entity?.kind === "entity") {
+      const fields = (entity.definition as { fields: Record<string, unknown> }).fields;
+      expect(Object.keys(fields)).toEqual(["name", "sku"]);
+    } else {
+      throw new Error("expected an entity pattern");
+    }
+  });
+
+  test("does not match when the identifier resolves to a different string", () => {
+    const sf = makeSourceFile(SAME_FILE_CONST);
+    expect(() => removePattern(sf, { kind: "entity", entityName: "other" })).toThrow(
+      /no call found/,
+    );
+  });
+
+  test("removePattern finds an extendsRegistrar call authored with a cross-file imported constant (#1746 fixture)", () => {
+    const sf = loadFixture("fixtures/cross-file-name-const/feature.ts");
+    removePattern(sf, { kind: "extendsRegistrar", extensionName: "audit" });
+    const reparsed = parseSourceFile(sf);
+    expect(reparsed.errors).toEqual([]);
+    expect(reparsed.patterns).toEqual([]);
+  });
+
+  test("removePattern resolves both positional args when authored as cross-file imported constants", () => {
+    const sf = loadFixture("fixtures/cross-file-patch-const/feature.ts");
+    removePattern(sf, {
+      kind: "useExtension",
+      extensionName: "tenant-data",
+      entityName: "item",
+    });
+    const reparsed = parseSourceFile(sf);
+    expect(reparsed.errors).toEqual([]);
+    expect(reparsed.patterns).toEqual([]);
+  });
+
+  test("removePattern finds an object-form useExtension whose entity is an inline { name } ref", () => {
+    const sf = makeSourceFile(`
+import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+
+defineFeature("inventory", (r) => {
+  r.useExtension({ name: "audit", entity: { name: "item" } });
+});
+`);
+    removePattern(sf, { kind: "useExtension", extensionName: "audit", entityName: "item" });
+    const reparsed = parseSourceFile(sf);
+    expect(reparsed.errors).toEqual([]);
+    expect(reparsed.patterns).toEqual([]);
+  });
+});

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

@@ -380,6 +380,161 @@ describe("renderPattern — single-pattern shape", () => {
     });
     expect(out).toBe('r.metric({ name: "requests", type: "counter" });');
   });
+
+  // #2111 — a name-carrying pattern with a `*Raw` field re-emits the
+  // identifier verbatim; without it, the name flattens to its resolved
+  // literal same as before the fix.
+  test("useExtension pattern re-emits extensionNameRaw verbatim over the resolved literal", () => {
+    const out = renderPattern({
+      kind: "useExtension",
+      source: { file: "x", start: { line: 1, column: 1 }, end: { line: 1, column: 1 }, raw: "" },
+      extensionName: "tenant-data",
+      extensionNameRaw: "EXT_TENANT_DATA",
+      entityName: "document",
+    });
+    expect(out).toBe('r.useExtension(EXT_TENANT_DATA, "document");');
+  });
+
+  test("useExtension pattern falls back to the resolved literal when extensionNameRaw is absent", () => {
+    const out = renderPattern({
+      kind: "useExtension",
+      source: { file: "x", start: { line: 1, column: 1 }, end: { line: 1, column: 1 }, raw: "" },
+      extensionName: "tenant-data",
+      entityName: "document",
+    });
+    expect(out).toBe('r.useExtension({ name: "tenant-data", entity: "document" });');
+  });
+
+  test("useExtension pattern with extensionNameRaw indents a multi-line options object correctly", () => {
+    const out = renderPattern({
+      kind: "useExtension",
+      source: { file: "x", start: { line: 1, column: 1 }, end: { line: 1, column: 1 }, raw: "" },
+      extensionName: "tenant-data",
+      extensionNameRaw: "EXT_TENANT_DATA",
+      entityName: "document",
+      options: {
+        description:
+          "a fairly long description that pushes this object past eighty characters wide",
+        scope: "tenant",
+        exportable: true,
+      },
+    });
+    expect(out).toBe(
+      [
+        'r.useExtension(EXT_TENANT_DATA, "document", {',
+        '  description: "a fairly long description that pushes this object past eighty characters wide",',
+        '  scope: "tenant",',
+        "  exportable: true,",
+        "});",
+      ].join("\n"),
+    );
+  });
+
+  test("extendsRegistrar pattern re-emits extensionNameRaw verbatim over the resolved literal", () => {
+    const out = renderPattern({
+      kind: "extendsRegistrar",
+      source: { file: "x", start: { line: 1, column: 1 }, end: { line: 1, column: 1 }, raw: "" },
+      extensionName: "tenant-data",
+      extensionNameRaw: "EXT_TENANT_DATA",
+      defBody: { file: "x", start: { line: 1, column: 1 }, end: { line: 1, column: 1 }, raw: "{}" },
+    });
+    expect(out).toBe("r.extendsRegistrar(EXT_TENANT_DATA, {});");
+  });
+
+  test("defineEvent pattern re-emits eventNameRaw verbatim over the resolved literal", () => {
+    const out = renderPattern({
+      kind: "defineEvent",
+      source: { file: "x", start: { line: 1, column: 1 }, end: { line: 1, column: 1 }, raw: "" },
+      eventName: "docIngested",
+      eventNameRaw: "DOC_INGESTED_EVENT",
+      schemaSource: {
+        file: "x",
+        start: { line: 1, column: 1 },
+        end: { line: 1, column: 1 },
+        raw: "z.object({})",
+      },
+    });
+    expect(out).toBe("r.defineEvent(DOC_INGESTED_EVENT, z.object({}));");
+  });
+});
+
+// #2111 — registrar-call names authored as an imported/local constant
+// (`r.useExtension(EXT_TENANT_DATA, ...)`, the style #1746 taught the
+// parser to resolve) must not get inlined into their resolved string
+// literal on a render → parse round-trip — the framework's own
+// bundled-features rely on the identifier reference surviving edits made
+// through the Designer to unrelated fields on the same pattern.
+const NAME_CONST_FEATURE = `
+import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import { z } from "zod";
+
+const EXT_TENANT_DATA = "tenant-data" as const;
+const DOC_INGESTED_EVENT = "docIngested" as const;
+
+defineFeature("user-data-rights", (r) => {
+  r.extendsRegistrar(EXT_TENANT_DATA, { onRegister: () => {} });
+  r.useExtension(EXT_TENANT_DATA, "document", { description: "org-scoped" });
+  r.defineEvent(DOC_INGESTED_EVENT, z.object({ id: z.string() }));
+});
+`;
+
+describe("render → parse roundtrip — imported-constant registrar-call names (#2111)", () => {
+  const initial = parse(NAME_CONST_FEATURE);
+
+  test("parses the identifier-authored names, keeping the source text alongside the resolved value", () => {
+    expect(initial.patterns).toMatchObject([
+      {
+        kind: "extendsRegistrar",
+        extensionName: "tenant-data",
+        extensionNameRaw: "EXT_TENANT_DATA",
+      },
+      {
+        kind: "useExtension",
+        extensionName: "tenant-data",
+        extensionNameRaw: "EXT_TENANT_DATA",
+      },
+      { kind: "defineEvent", eventName: "docIngested", eventNameRaw: "DOC_INGESTED_EVENT" },
+    ]);
+  });
+
+  test("rendering re-emits the identifier verbatim instead of the resolved literal", () => {
+    const rendered = renderFeatureFile({
+      featureName: initial.featureName ?? "",
+      patterns: initial.patterns,
+    });
+    expect(rendered).toContain("r.extendsRegistrar(EXT_TENANT_DATA,");
+    expect(rendered).toContain("r.useExtension(EXT_TENANT_DATA,");
+    expect(rendered).toContain("r.defineEvent(DOC_INGESTED_EVENT,");
+    expect(rendered).not.toContain('"tenant-data"');
+    expect(rendered).not.toContain('"docIngested"');
+  });
+
+  test("editing an unrelated field on the useExtension pattern still preserves the identifier name", () => {
+    // Simulates a Designer save: only `options` changes; `extensionName` /
+    // `extensionNameRaw` pass through untouched, as replacePattern callers
+    // are expected to do (see UseExtensionPattern.extensionNameRaw doc).
+    const edited = initial.patterns.map((p) =>
+      p.kind === "useExtension"
+        ? { ...p, options: { ...p.options, description: "tenant-scoped" } }
+        : p,
+    );
+    const rendered = renderFeatureFile({
+      featureName: initial.featureName ?? "",
+      patterns: edited,
+    });
+    expect(rendered).toContain("r.useExtension(EXT_TENANT_DATA,");
+    expect(rendered).toContain("tenant-scoped");
+  });
+
+  // No "reparse the full renderFeatureFile output" case here, unlike the
+  // other roundtrip blocks in this file: renderFeatureFile only emits the
+  // version header + imports + defineFeature body (see its doc comment),
+  // so it drops the top-level `const EXT_TENANT_DATA = ...` this fixture
+  // relies on — reparsing would ParseError for an unrelated, pre-existing
+  // reason (the const is gone), not because the raw-preservation broke.
+  // The real edit path (`replacePattern` patching a single call in place
+  // on the *original* SourceFile, which keeps the const) is covered by
+  // patch.test.ts.
 });
 
 // Regression guard for the class of bug the r.exposesApi/r.usesApi fold

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

@@ -10,6 +10,7 @@ import {
   ok,
   readDataLiteralNode,
   readNameLiteral,
+  readNameLiteralRef,
   readNameOrRef,
   readPropertyKey,
 } from "./shared";
@@ -147,8 +148,8 @@ export function extractDefineEvent(
     });
   }
 
-  const eventName = readNameLiteral(first);
-  if (eventName === undefined) {
+  const eventNameRef = readNameLiteralRef(first);
+  if (eventNameRef === undefined) {
     return fail(
       "defineEvent",
       sourceLocationFromNode(call, sourceFile),
@@ -187,7 +188,8 @@ export function extractDefineEvent(
   return ok({
     kind: "defineEvent",
     source: sourceLocationFromNode(call, sourceFile),
-    eventName,
+    eventName: eventNameRef.value,
+    ...(eventNameRef.raw !== undefined && { eventNameRaw: eventNameRef.raw }),
     schemaSource: sourceLocationFromNode(schemaArg, sourceFile),
     ...(version !== undefined && { version }),
     ...(migrations !== undefined && { migrations }),

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

@@ -21,6 +21,7 @@ import {
   ok,
   readDataLiteralNode,
   readNameLiteral,
+  readNameLiteralRef,
   readNameOrRef,
 } from "./shared";
 
@@ -425,8 +426,8 @@ export function extractUseExtension(
     });
   }
 
-  const extensionName = readNameLiteral(first);
-  if (extensionName === undefined) {
+  const extensionNameRef = readNameLiteralRef(first);
+  if (extensionNameRef === undefined) {
     return fail(
       "useExtension",
       sourceLocationFromNode(call, sourceFile),
@@ -465,7 +466,8 @@ export function extractUseExtension(
   return ok({
     kind: "useExtension",
     source: sourceLocationFromNode(call, sourceFile),
-    extensionName,
+    extensionName: extensionNameRef.value,
+    ...(extensionNameRef.raw !== undefined && { extensionNameRaw: extensionNameRef.raw }),
     entityName,
     ...(options !== undefined && { options }),
   });

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

@@ -6,7 +6,7 @@ import type {
   UsesApiPattern,
 } from "../patterns";
 import { sourceLocationFromNode } from "../source-location";
-import { type ExtractOutput, fail, ok, readNameLiteral } from "./shared";
+import { type ExtractOutput, fail, ok, readNameLiteral, readNameLiteralRef } from "./shared";
 
 export function extractEnvSchema(
   call: CallExpression,
@@ -33,8 +33,8 @@ export function extractExtendsRegistrar(
 ): ExtractOutput<ExtendsRegistrarPattern> {
   const args = call.getArguments();
   const first = args[0];
-  const extensionName = first && readNameLiteral(first);
-  if (!extensionName) {
+  const extensionNameRef = first && readNameLiteralRef(first);
+  if (!extensionNameRef) {
     return fail(
       "extendsRegistrar",
       sourceLocationFromNode(call, sourceFile),
@@ -52,7 +52,8 @@ export function extractExtendsRegistrar(
   return ok({
     kind: "extendsRegistrar",
     source: sourceLocationFromNode(call, sourceFile),
-    extensionName,
+    extensionName: extensionNameRef.value,
+    ...(extensionNameRef.raw !== undefined && { extensionNameRaw: extensionNameRef.raw }),
     defBody: sourceLocationFromNode(defArg, sourceFile),
   });
 }

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

@@ -215,6 +215,32 @@ function resolveIdentifierToStringLiteral(identifier: Node): string | undefined
   return undefined;
 }
 
+/**
+ * Resolved name plus, when the source node was an identifier rather than
+ * a string literal, the identifier's exact source text. Mirrors
+ * `RawRefSentinel`'s round-trip contract: extractors that need to re-emit
+ * the original reference (not its resolved value) keep `raw` alongside
+ * `value`; extractors that only need the string keep using
+ * `readNameLiteral`, which discards it.
+ */
+export type NameLiteralRef = { readonly value: string; readonly raw?: string };
+
+/**
+ * Like `readNameLiteral`, but for callers that must preserve an
+ * identifier-authored name across a render → parse round-trip (see #2111).
+ * `raw` is populated only when the node resolved via an identifier — a
+ * string-literal node has nothing worth preserving beyond its value, and
+ * setting `raw` for it too would make `JSON.stringify(value)` and
+ * `node.getText()` diverge on quote style.
+ */
+export function readNameLiteralRef(node: Node): NameLiteralRef | undefined {
+  const literal = node.asKind(SyntaxKind.StringLiteral);
+  if (literal) return { value: literal.getLiteralValue() };
+  const resolved = resolveIdentifierToStringLiteral(node);
+  if (resolved === undefined) return undefined;
+  return { value: resolved, raw: node.getText() };
+}
+
 /**
  * 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
@@ -223,12 +249,11 @@ function resolveIdentifierToStringLiteral(identifier: Node): string | undefined
  * `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.
+ * fallback, no crash. Discards the original identifier text; use
+ * `readNameLiteralRef` when the caller must preserve it for rendering.
  */
 export function readNameLiteral(node: Node): string | undefined {
-  const literal = node.asKind(SyntaxKind.StringLiteral);
-  if (literal) return literal.getLiteralValue();
-  return resolveIdentifierToStringLiteral(node);
+  return readNameLiteralRef(node)?.value;
 }
 
 export function readNameOrRef(node: Node): string | undefined {

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

@@ -31,6 +31,7 @@
 // preserve prefixed `// kumiko-comment:` markers across roundtrips.
 
 import { type CallExpression, type Node, type SourceFile, SyntaxKind } from "ts-morph";
+import { readNameLiteral, readNameOrRef } from "./extractors/shared";
 import type { FeaturePattern, FeaturePatternKind } from "./patterns";
 import { indent, PATTERN_INDENT, renderPattern } from "./render";
 
@@ -341,8 +342,7 @@ function callMatchesId(call: CallExpression, id: PatternId): boolean {
     case "relation":
       // Positional: r.relation(entity, name, def) | Object: { entity, name, ... }
       if (matchFirstArgString(call, id.entityName)) {
-        const second = call.getArguments()[1]?.asKind(SyntaxKind.StringLiteral)?.getLiteralValue();
-        return second === id.relationName;
+        return matchArgString(call, 1, id.relationName);
       }
       return (
         matchObjectProperty(call, "entity", id.entityName) &&
@@ -374,8 +374,7 @@ function callMatchesId(call: CallExpression, id: PatternId): boolean {
         );
       }
       if (matchFirstArgString(call, id.hookType)) {
-        const target = call.getArguments()[1]?.asKind(SyntaxKind.StringLiteral)?.getLiteralValue();
-        return target === id.target;
+        return matchArgString(call, 1, id.target);
       }
       return (
         matchObjectProperty(call, "type", id.hookType) &&
@@ -395,8 +394,7 @@ function callMatchesId(call: CallExpression, id: PatternId): boolean {
     case "useExtension":
       // Positional: r.useExtension(name, entity) | Object: { name, entity }
       if (matchFirstArgString(call, id.extensionName)) {
-        const ent = call.getArguments()[1]?.asKind(SyntaxKind.StringLiteral)?.getLiteralValue();
-        return ent === id.entityName;
+        return matchArgString(call, 1, id.entityName);
       }
       return (
         matchObjectProperty(call, "name", id.extensionName) &&
@@ -430,33 +428,42 @@ function callMatchesId(call: CallExpression, id: PatternId): boolean {
   }
 }
 
+// Resolves an argument the same way the extractors do (readNameLiteral):
+// a string literal directly, or a bare identifier following its
+// declaration (same-file or imported) to a string-literal initializer —
+// the dominant naming style in the framework's own bundled-features
+// (`r.entity(ENTITY, ...)`, `r.useExtension(EXT_X, ...)`, see #1746).
+function matchArgString(call: CallExpression, index: number, expected: string): boolean {
+  const arg = call.getArguments()[index];
+  if (!arg) return false;
+  return readNameLiteral(arg) === expected;
+}
+
 function matchFirstArgString(call: CallExpression, expected: string): boolean {
-  const first = call.getArguments()[0];
-  const lit = first?.asKind(SyntaxKind.StringLiteral);
-  return lit?.getLiteralValue() === expected;
+  return matchArgString(call, 0, expected);
 }
 
+// Object-form property values are resolved via readNameOrRef, not the
+// narrower readNameLiteral — some properties (useExtension's `entity`,
+// hook's `target`/`allOf`) accept an inline `{ name: "..." }` ref in the
+// parser (see extractors/round3.ts, extractors/hooks.ts), not just a
+// literal or identifier. readNameOrRef is a superset of readNameLiteral,
+// so this is safe for every other property too.
 function matchObjectProperty(call: CallExpression, propName: string, expected: string): boolean {
   const obj = call.getArguments()[0]?.asKind(SyntaxKind.ObjectLiteralExpression);
   if (!obj) return false;
-  const init = obj
-    .getProperty(propName)
-    ?.asKind(SyntaxKind.PropertyAssignment)
-    ?.getInitializer()
-    ?.asKind(SyntaxKind.StringLiteral);
-  return init?.getLiteralValue() === expected;
+  const init = obj.getProperty(propName)?.asKind(SyntaxKind.PropertyAssignment)?.getInitializer();
+  if (!init) return false;
+  return readNameOrRef(init) === expected;
 }
 
 // Matches an r.hook `{ allOf: entity }` target — as the arg node directly
 // (positional call form) or as a nested object property (object call form).
 function matchAllOfArg(node: Node | undefined, expectedEntity: string): boolean {
   const obj = node?.asKind(SyntaxKind.ObjectLiteralExpression);
-  const init = obj
-    ?.getProperty("allOf")
-    ?.asKind(SyntaxKind.PropertyAssignment)
-    ?.getInitializer()
-    ?.asKind(SyntaxKind.StringLiteral);
-  return init?.getLiteralValue() === expectedEntity;
+  const init = obj?.getProperty("allOf")?.asKind(SyntaxKind.PropertyAssignment)?.getInitializer();
+  if (!init) return false;
+  return readNameOrRef(init) === expectedEntity;
 }
 
 function matchObjectAllOfProperty(

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

@@ -283,6 +283,14 @@ export type UseExtensionPattern = {
   readonly kind: "useExtension";
   readonly source: SourceLocation;
   readonly extensionName: string;
+  // Set only when `extensionName` was authored as an identifier resolving
+  // to a string constant (`r.useExtension(EXT_TENANT_DATA, ...)`) rather
+  // than a literal — the renderer emits this verbatim instead of
+  // `JSON.stringify(extensionName)` so the round-trip doesn't inline the
+  // reference (#2111). A caller constructing an edited pattern must omit
+  // this field (or recompute it) whenever it changes `extensionName`,
+  // otherwise the stale identifier text wins over the new value.
+  readonly extensionNameRaw?: string;
   readonly entityName: string;
   readonly options?: Readonly<Record<string, unknown>>;
 };
@@ -516,6 +524,11 @@ export type DefineEventPattern = {
   readonly kind: "defineEvent";
   readonly source: SourceLocation;
   readonly eventName: string;
+  // Set only when `eventName` was authored as an identifier resolving to
+  // a string constant rather than a literal — see UseExtensionPattern's
+  // `extensionNameRaw` doc for the round-trip contract (#2111). A caller
+  // editing `eventName` must omit or recompute this field.
+  readonly eventNameRaw?: string;
   readonly schemaSource: SourceLocation;
   readonly version?: number;
   // Map fromVersion (as string, e.g. "1") → SourceLocation of the transform
@@ -532,6 +545,11 @@ export type ExtendsRegistrarPattern = {
   readonly kind: "extendsRegistrar";
   readonly source: SourceLocation;
   readonly extensionName: string;
+  // Set only when `extensionName` was authored as an identifier resolving
+  // to a string constant rather than a literal — see UseExtensionPattern's
+  // `extensionNameRaw` doc for the round-trip contract (#2111). A caller
+  // editing `extensionName` must omit or recompute this field.
+  readonly extensionNameRaw?: string;
   // Meta-programming surface — kept fully opaque in the MVP. The
   // Designer shows "Custom Registrar Extension"; AI leaves it alone.
   readonly defBody: SourceLocation;

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

@@ -9,6 +9,11 @@
 //   - Mixed patterns (writeHandler, hook, screen) embed the original
 //     source-text of opaque bodies (handler/fn/closure) verbatim via
 //     SourceLocation.raw — the renderer doesn't re-print closure code.
+//   - Patterns carrying a RawRefSentinel value (e.g. entity/metric/secret
+//     `definition`/`options`) or a `*NameRaw` identifier reference
+//     (useExtension/defineEvent/extendsRegistrar) fall back to positional-arg
+//     form instead of Object-Form, since the raw source text can't be spread
+//     into a merged object literal without losing its verbatim-ness.
 //   - Comments inside an existing pattern are NOT preserved (Designer
 //     edits via forms; for AI generation the output is fresh anyway).
 //
@@ -306,8 +311,16 @@ function renderReferenceData(p: ReferenceDataPattern): string {
 }
 
 function renderUseExtension(p: UseExtensionPattern): string {
+  const nameLiteral = p.extensionNameRaw ?? JSON.stringify(p.extensionName);
   if (isRawRefSentinel(p.options)) {
-    return `r.useExtension(${JSON.stringify(p.extensionName)}, ${JSON.stringify(p.entityName)}, ${p.options.__raw});`;
+    return `r.useExtension(${nameLiteral}, ${JSON.stringify(p.entityName)}, ${p.options.__raw});`;
+  }
+  if (p.extensionNameRaw !== undefined) {
+    // A raw-ref name can't be spread into the merged Object-Form without
+    // losing it to renderValue's plain-string serialization — fall back
+    // to positional form, which keeps the reference verbatim (#2111).
+    const optionsArg = p.options !== undefined ? `, ${renderValue(p.options)}` : "";
+    return `r.useExtension(${nameLiteral}, ${JSON.stringify(p.entityName)}${optionsArg});`;
   }
   const merged: Record<string, unknown> = {
     name: p.extensionName,
@@ -506,14 +519,13 @@ function renderMultiStreamProjection(p: MultiStreamProjectionPattern): string {
 }
 
 function renderDefineEvent(p: DefineEventPattern): string {
+  const nameLiteral = p.eventNameRaw ?? JSON.stringify(p.eventName);
   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});`;
+    return `r.defineEvent(${nameLiteral}, ${p.schemaSource.raw});`;
   }
-  const lines: string[] = [
-    `r.defineEvent(${JSON.stringify(p.eventName)}, ${p.schemaSource.raw}, {`,
-  ];
+  const lines: string[] = [`r.defineEvent(${nameLiteral}, ${p.schemaSource.raw}, {`];
   if (p.version !== undefined) lines.push(`  version: ${p.version},`);
   if (migrationEntries.length > 0) {
     lines.push("  migrations: [");
@@ -530,7 +542,8 @@ function renderDefineEvent(p: DefineEventPattern): string {
 }
 
 function renderExtendsRegistrar(p: ExtendsRegistrarPattern): string {
-  return `r.extendsRegistrar(${JSON.stringify(p.extensionName)}, ${p.defBody.raw});`;
+  const nameLiteral = p.extensionNameRaw ?? JSON.stringify(p.extensionName);
+  return `r.extendsRegistrar(${nameLiteral}, ${p.defBody.raw});`;
 }
 
 function renderEnvSchema(p: EnvSchemaPattern): string {

package/src/engine/index.ts

@@ -70,6 +70,7 @@ export {
   defineProjectionQueryHandler,
   type EntityCrudRegistrar,
   entityListSchema,
+  MAX_LIST_LIMIT,
   type RegisterEntityCrudOptions,
   registerEntityCrud,
 } from "./entity-handlers";