@cosmicdrift/kumiko-framework 1.0.0 → 2.0.0

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

@@ -11,8 +11,10 @@
 // Designer/AI know the call exists.
 
 import { describe, expect, test } from "bun:test";
+import { resolve } from "node:path";
 import { Project } from "ts-morph";
-import { parseSourceFile } from "../parse";
+import { isRawRefSentinel, readDataLiteralNode } from "../extractors/shared";
+import { parseFeatureFile, parseSourceFile } from "../parse";
 
 function createProject() {
   return new Project({
@@ -122,6 +124,102 @@ defineFeature("isolated", (r) => {
     expect(result.featureName).toBe("nameOnly");
     expect(result.patterns).toEqual([]);
   });
+
+  test("recurses into a locally declared registrar-wrapper function", () => {
+    const result = parseInline(`
+function registerTaskScreens(registrar) {
+  registrar.entity("task", { fields: {} });
+  registrar.requires("auth");
+}
+defineFeature("wrapped", (r) => {
+  r.systemScope();
+  registerTaskScreens(r);
+});
+`);
+
+    expect(result.errors).toEqual([]);
+    expect(result.patterns.map((p) => p.kind)).toEqual(["systemScope", "entity", "requires"]);
+  });
+
+  test("recurses into a registrar-wrapper declared as a const arrow function", () => {
+    const result = parseInline(`
+const registerTaskScreens = (registrar) => {
+  registrar.entity("task", { fields: {} });
+};
+defineFeature("wrapped", (r) => {
+  registerTaskScreens(r);
+});
+`);
+
+    expect(result.errors).toEqual([]);
+    expect(result.patterns).toMatchObject([{ kind: "entity", entityName: "task" }]);
+  });
+
+  test("ignores a bare call that does not receive the registrar as an argument", () => {
+    const result = parseInline(`
+function unrelated() {
+  return 1;
+}
+defineFeature("f", (r) => {
+  unrelated();
+  r.systemScope();
+});
+`);
+
+    expect(result.errors).toEqual([]);
+    expect(result.patterns).toMatchObject([{ kind: "systemScope" }]);
+  });
+
+  test("does not infinite-loop on a registrar-wrapper cycle", () => {
+    const result = parseInline(`
+function a(registrar) {
+  registrar.systemScope();
+  b(registrar);
+}
+function b(registrar) {
+  a(registrar);
+}
+defineFeature("f", (r) => {
+  a(r);
+});
+`);
+
+    expect(result.errors).toEqual([]);
+    expect(result.patterns).toMatchObject([{ kind: "systemScope" }]);
+  });
+});
+
+describe("readDataLiteralNode — raw-ref sentinel", () => {
+  function readExpression(source: string) {
+    const project = createProject();
+    const sourceFile = project.createSourceFile("inline.ts", `const __probe__ = (${source});`);
+    const decl = sourceFile.getVariableDeclarationOrThrow("__probe__");
+    return readDataLiteralNode(decl.getInitializerOrThrow());
+  }
+
+  test("Identifier reference resolves to a raw-ref sentinel with the exact source text", () => {
+    const value = readExpression("eventEntity");
+    expect(isRawRefSentinel(value)).toBe(true);
+    expect(value).toEqual({ __raw: "eventEntity" });
+  });
+
+  test("zero-arg call expression resolves to a raw-ref sentinel with the exact source text", () => {
+    const value = readExpression("createInviteBrandingQuery()");
+    expect(isRawRefSentinel(value)).toBe(true);
+    expect(value).toEqual({ __raw: "createInviteBrandingQuery()" });
+  });
+
+  test("member access resolves to a raw-ref sentinel", () => {
+    const value = readExpression("config.timeout");
+    expect(isRawRefSentinel(value)).toBe(true);
+    expect(value).toEqual({ __raw: "config.timeout" });
+  });
+
+  test("a single unresolvable property no longer bubbles the whole object to undefined", () => {
+    const value = readExpression("{ timeout: 30, query: createQuery() }");
+    expect(isRawRefSentinel(value)).toBe(false);
+    expect(value).toEqual({ timeout: 30, query: { __raw: "createQuery()" } });
+  });
 });
 
 // =============================================================================
@@ -143,12 +241,26 @@ defineFeature("f", (r) => {
     expect(result.errors).toEqual([]);
   });
 
-  test("emits a ParseError when an argument is not a string literal", () => {
+  test("resolves a local const identifier arg via the raw-ref sentinel (#1009)", () => {
     const result = parseInline(`
 const dep = "auth";
 defineFeature("f", (r) => {
   r.requires(dep);
 });
+`);
+
+    expect(result.patterns[0]).toMatchObject({
+      kind: "requires",
+      featureNames: [{ __raw: "dep" }],
+    });
+    expect(result.errors).toEqual([]);
+  });
+
+  test("emits a ParseError when an argument cannot be resolved at all", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.requires(5);
+});
 `);
 
     expect(result.patterns).toEqual([]);
@@ -170,6 +282,21 @@ defineFeature("f", (r) => {
       featureNames: ["billing"],
     });
   });
+
+  test("keeps a computed feature-name arg as a raw-ref sentinel instead of failing (#1009)", () => {
+    const result = parseInline(`
+const someFeature = { name: "billing" };
+defineFeature("f", (r) => {
+  r.optionalRequires(someFeature.name);
+});
+`);
+
+    expect(result.patterns[0]).toMatchObject({
+      kind: "optionalRequires",
+      featureNames: [{ __raw: "someFeature.name" }],
+    });
+    expect(result.errors).toEqual([]);
+  });
 });
 
 describe("extractReadsConfig", () => {
@@ -185,6 +312,21 @@ defineFeature("f", (r) => {
       qualifiedKeys: ["auth:config:jwt-ttl", "tenant:config:locale"],
     });
   });
+
+  test("keeps a computed key arg as a raw-ref sentinel instead of failing (#1009)", () => {
+    const result = parseInline(`
+const cfg = { key: "auth:config:jwt-ttl" };
+defineFeature("f", (r) => {
+  r.readsConfig(cfg.key, "tenant:config:locale");
+});
+`);
+
+    expect(result.patterns[0]).toMatchObject({
+      kind: "readsConfig",
+      qualifiedKeys: [{ __raw: "cfg.key" }, "tenant:config:locale"],
+    });
+    expect(result.errors).toEqual([]);
+  });
 });
 
 describe("extractSystemScope", () => {
@@ -269,6 +411,40 @@ defineFeature("f", (r) => {
     expect(result.errors).toEqual([]);
   });
 
+  test("keeps an unresolved const reference as a raw-ref sentinel instead of erroring", () => {
+    const result = parseInline(`
+const eventEntity = { fields: { name: { type: "text" } } };
+defineFeature("f", (r) => {
+  r.entity("event", eventEntity);
+});
+`);
+
+    expect(result.errors).toEqual([]);
+    expect(result.patterns[0]).toMatchObject({
+      kind: "entity",
+      entityName: "event",
+      definition: { __raw: "eventEntity" },
+    });
+  });
+
+  test("keeps a factory call reference inside a nested property as a raw-ref sentinel", () => {
+    const result = parseInline(`
+function buildFields() {
+  return { name: { type: "text" } };
+}
+defineFeature("f", (r) => {
+  r.entity("task", { fields: buildFields() });
+});
+`);
+
+    expect(result.errors).toEqual([]);
+    expect(result.patterns[0]).toMatchObject({
+      kind: "entity",
+      entityName: "task",
+      definition: { fields: { __raw: "buildFields()" } },
+    });
+  });
+
   test("walks through `as const` and `satisfies` wrappers", () => {
     const result = parseInline(`
 defineFeature("f", (r) => {
@@ -303,6 +479,60 @@ const ENTITY = "task";
 defineFeature("f", (r) => {
   r.entity(ENTITY, { fields: {} });
 });
+`);
+
+    expect(result.errors[0]?.methodName).toBe("entity");
+  });
+
+  test("object form captures name + definition", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.entity({ name: "task", fields: { title: { type: "text" } } });
+});
+`);
+
+    expect(result.patterns[0]).toMatchObject({
+      kind: "entity",
+      entityName: "task",
+      definition: { fields: { title: { type: "text" } } },
+    });
+  });
+
+  test("emits ParseError when called with no arguments", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.entity();
+});
+`);
+
+    expect(result.errors[0]?.methodName).toBe("entity");
+  });
+
+  test("emits ParseError when object form is missing the name property", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.entity({ fields: {} });
+});
+`);
+
+    expect(result.errors[0]?.methodName).toBe("entity");
+  });
+
+  test("emits ParseError when object form definition contains a function value", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.entity({ name: "task", fields: { title: { type: "text", default: () => "x" } } });
+});
+`);
+
+    expect(result.errors[0]?.methodName).toBe("entity");
+  });
+
+  test("emits ParseError when the positional definition argument is missing", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.entity("task");
+});
 `);
 
     expect(result.errors[0]?.methodName).toBe("entity");
@@ -345,6 +575,71 @@ const taskRef = { name: "task" };
 defineFeature("f", (r) => {
   r.relation(taskRef, "owner", { kind: "belongsTo", to: "user" });
 });
+`);
+
+    expect(result.errors[0]?.methodName).toBe("relation");
+  });
+
+  test("object form captures entity, name and definition", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.relation({ entity: "task", name: "owner", kind: "belongsTo", to: "user" });
+});
+`);
+
+    expect(result.patterns[0]).toMatchObject({
+      kind: "relation",
+      entityName: "task",
+      relationName: "owner",
+      definition: { kind: "belongsTo", to: "user" },
+    });
+  });
+
+  test("emits ParseError when called with no arguments", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.relation();
+});
+`);
+
+    expect(result.errors[0]?.methodName).toBe("relation");
+  });
+
+  test("emits ParseError when object form is missing the entity property", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.relation({ name: "owner", kind: "belongsTo" });
+});
+`);
+
+    expect(result.errors[0]?.methodName).toBe("relation");
+  });
+
+  test("emits ParseError when object form is missing the name property", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.relation({ entity: "task", kind: "belongsTo" });
+});
+`);
+
+    expect(result.errors[0]?.methodName).toBe("relation");
+  });
+
+  test("emits ParseError when the relation name is not a string literal", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.relation("task", REL, { kind: "belongsTo" });
+});
+`);
+
+    expect(result.errors[0]?.methodName).toBe("relation");
+  });
+
+  test("emits ParseError when the positional definition argument is missing", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.relation("task", "owner");
+});
 `);
 
     expect(result.errors[0]?.methodName).toBe("relation");
@@ -364,6 +659,26 @@ defineFeature("f", (r) => {
       definition: { id: "tasks", label: "Tasks", screen: "tasks:screen:list" },
     });
   });
+
+  test("emits ParseError when called with no arguments", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.nav();
+});
+`);
+
+    expect(result.errors[0]?.methodName).toBe("nav");
+  });
+
+  test("emits ParseError when the definition is not a plain object", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.nav(() => {});
+});
+`);
+
+    expect(result.errors[0]?.methodName).toBe("nav");
+  });
 });
 
 describe("extractWorkspace", () => {
@@ -379,6 +694,16 @@ defineFeature("f", (r) => {
       definition: { id: "admin", label: "Admin" },
     });
   });
+
+  test("emits ParseError when called with no arguments", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.workspace();
+});
+`);
+
+    expect(result.errors[0]?.methodName).toBe("workspace");
+  });
 });
 
 // =============================================================================
@@ -412,6 +737,26 @@ defineFeature("f", (r) => {
 defineFeature("f", (r) => {
   r.config({});
 });
+`);
+
+    expect(result.errors[0]?.methodName).toBe("config");
+  });
+
+  test("emits ParseError when called with no arguments", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.config();
+});
+`);
+
+    expect(result.errors[0]?.methodName).toBe("config");
+  });
+
+  test("emits ParseError when the argument is not a plain object", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.config(() => {});
+});
 `);
 
     expect(result.errors[0]?.methodName).toBe("config");
@@ -439,6 +784,26 @@ defineFeature("f", (r) => {
       },
     });
   });
+
+  test("emits ParseError when called with no arguments", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.translations();
+});
+`);
+
+    expect(result.errors[0]?.methodName).toBe("translations");
+  });
+
+  test("emits ParseError when keys property is missing", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.translations({});
+});
+`);
+
+    expect(result.errors[0]?.methodName).toBe("translations");
+  });
 });
 
 describe("extractMetric", () => {
@@ -455,336 +820,1372 @@ defineFeature("f", (r) => {
       options: { type: "counter", description: "API requests" },
     });
   });
-});
+
+  test("object form captures name + options", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.metric({ name: "requests", type: "counter", description: "API requests" });
+});
+`);
+
+    expect(result.patterns[0]).toMatchObject({
+      kind: "metric",
+      shortName: "requests",
+      options: { type: "counter", description: "API requests" },
+    });
+  });
+
+  test("emits ParseError when called with no arguments", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.metric();
+});
+`);
+
+    expect(result.errors[0]?.methodName).toBe("metric");
+  });
+
+  test("emits ParseError when object form is missing the name property", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.metric({ type: "counter" });
+});
+`);
+
+    expect(result.errors[0]?.methodName).toBe("metric");
+  });
+
+  test("emits ParseError when the name is not a string literal", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.metric(NAME, { type: "counter" });
+});
+`);
+
+    expect(result.errors[0]?.methodName).toBe("metric");
+  });
+
+  test("emits ParseError when the options argument is missing", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.metric("requests");
+});
+`);
+
+    expect(result.errors[0]?.methodName).toBe("metric");
+  });
+
+  test("emits ParseError when options is not a plain object", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.metric("requests", () => {});
+});
+`);
+
+    expect(result.errors[0]?.methodName).toBe("metric");
+  });
+});
 
 describe("extractSecret", () => {
   test("captures shortName + options", () => {
     const result = parseInline(`
 defineFeature("f", (r) => {
-  r.secret("apiKey", { description: "Stripe API key" });
+  r.secret("apiKey", { description: "Stripe API key" });
+});
+`);
+
+    expect(result.patterns[0]).toMatchObject({
+      kind: "secret",
+      shortName: "apiKey",
+      options: { description: "Stripe API key" },
+    });
+  });
+
+  test("object form captures name + options", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.secret({ name: "apiKey", description: "Stripe API key" });
+});
+`);
+
+    expect(result.patterns[0]).toMatchObject({
+      kind: "secret",
+      shortName: "apiKey",
+      options: { description: "Stripe API key" },
+    });
+  });
+
+  test("emits ParseError when called with no arguments", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.secret();
+});
+`);
+
+    expect(result.errors[0]?.methodName).toBe("secret");
+  });
+});
+
+describe("extractClaimKey", () => {
+  test("captures shortName + claim type", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.claimKey("teamId", { type: "string" });
+});
+`);
+
+    expect(result.patterns[0]).toMatchObject({
+      kind: "claimKey",
+      shortName: "teamId",
+      claimType: "string",
+    });
+  });
+
+  test("emits ParseError on invalid claim type", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.claimKey("teamId", { type: "bigint" });
+});
+`);
+
+    expect(result.errors[0]?.methodName).toBe("claimKey");
+  });
+
+  test("object form captures name + type", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.claimKey({ name: "teamId", type: "string" });
+});
+`);
+
+    expect(result.patterns[0]).toMatchObject({
+      kind: "claimKey",
+      shortName: "teamId",
+      claimType: "string",
+    });
+  });
+
+  test("emits ParseError when called with no arguments", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.claimKey();
+});
+`);
+
+    expect(result.errors[0]?.methodName).toBe("claimKey");
+  });
+});
+
+describe("extractReferenceData", () => {
+  test("captures entity name + data array", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.referenceData("status", [
+    { id: "open", label: "Open" },
+    { id: "closed", label: "Closed" },
+  ]);
+});
+`);
+
+    expect(result.patterns[0]).toMatchObject({
+      kind: "referenceData",
+      entityName: "status",
+      data: [
+        { id: "open", label: "Open" },
+        { id: "closed", label: "Closed" },
+      ],
+    });
+  });
+
+  test("captures the optional upsertKey", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.referenceData("status", [{ id: "open" }], { upsertKey: "id" });
+});
+`);
+
+    expect(result.patterns[0]).toMatchObject({
+      kind: "referenceData",
+      entityName: "status",
+      upsertKey: "id",
+    });
+  });
+
+  test("object form captures entity, data and upsertKey", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.referenceData({
+    entity: "status",
+    data: [{ id: "open" }, { id: "closed" }],
+    upsertKey: "id",
+  });
+});
+`);
+
+    expect(result.errors).toEqual([]);
+    expect(result.patterns[0]).toMatchObject({
+      kind: "referenceData",
+      entityName: "status",
+      data: [{ id: "open" }, { id: "closed" }],
+      upsertKey: "id",
+    });
+  });
+
+  test("accepts an inline { name: '...' } entity ref, both forms", () => {
+    const positional = parseInline(`
+defineFeature("f", (r) => {
+  r.referenceData({ name: "status" }, [{ id: "open" }]);
+});
+`);
+    expect(positional.patterns[0]).toMatchObject({ kind: "referenceData", entityName: "status" });
+
+    const objectForm = parseInline(`
+defineFeature("f", (r) => {
+  r.referenceData({ entity: { name: "status" }, data: [{ id: "open" }] });
+});
+`);
+    expect(objectForm.patterns[0]).toMatchObject({ kind: "referenceData", entityName: "status" });
+  });
+
+  test("emits ParseError when called with no arguments", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.referenceData();
+});
+`);
+
+    expect(result.patterns).toEqual([]);
+    expect(result.errors[0]?.methodName).toBe("referenceData");
+  });
+
+  test("emits ParseError when object form is missing the data property", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.referenceData({ entity: "status" });
+});
+`);
+
+    expect(result.errors[0]?.methodName).toBe("referenceData");
+  });
+
+  test("emits ParseError when object form is missing the entity property", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.referenceData({ data: [{ id: "open" }] });
+});
+`);
+
+    expect(result.errors[0]?.methodName).toBe("referenceData");
+  });
+
+  test("emits ParseError when object form's data is not an array of plain objects", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.referenceData({ entity: "status", data: "not-an-array" });
+});
+`);
+
+    expect(result.errors[0]?.methodName).toBe("referenceData");
+  });
+
+  test("emits ParseError when the positional data argument is missing", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.referenceData("status");
+});
+`);
+
+    expect(result.errors[0]?.methodName).toBe("referenceData");
+  });
+
+  test("emits ParseError when positional upsertKey option is not a string", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.referenceData("status", [{ id: "open" }], { upsertKey: 123 });
+});
+`);
+
+    expect(result.errors[0]?.methodName).toBe("referenceData");
+  });
+
+  test("emits ParseError when object form entity ref is unresolvable", () => {
+    const result = parseInline(`
+const ent = { name: "status" };
+defineFeature("f", (r) => {
+  r.referenceData({ entity: ent, data: [{ id: "open" }] });
+});
+`);
+
+    expect(result.errors[0]?.methodName).toBe("referenceData");
+  });
+
+  test("emits ParseError when positional data is not an array of plain objects", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.referenceData("status", "not-an-array");
+});
+`);
+
+    expect(result.errors[0]?.methodName).toBe("referenceData");
+  });
+
+  test("emits ParseError when positional options is not a plain object", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.referenceData("status", [{ id: "open" }], () => {});
+});
+`);
+
+    expect(result.errors[0]?.methodName).toBe("referenceData");
+  });
+});
+
+describe("extractUseExtension", () => {
+  test("captures extension name + entity ref", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.useExtension("audit", "task");
+});
+`);
+
+    expect(result.patterns[0]).toMatchObject({
+      kind: "useExtension",
+      extensionName: "audit",
+      entityName: "task",
+    });
+  });
+
+  test("captures optional options", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.useExtension("audit", "task", { mode: "verbose" });
+});
+`);
+
+    expect(result.patterns[0]).toMatchObject({
+      kind: "useExtension",
+      extensionName: "audit",
+      entityName: "task",
+      options: { mode: "verbose" },
+    });
+  });
+
+  test("object form captures name, entity ref and options", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.useExtension({ name: "audit", entity: "task", options: { mode: "verbose" } });
+});
+`);
+
+    expect(result.errors).toEqual([]);
+    expect(result.patterns[0]).toMatchObject({
+      kind: "useExtension",
+      extensionName: "audit",
+      entityName: "task",
+      options: { mode: "verbose" },
+    });
+  });
+
+  test("accepts an inline { name: '...' } entity ref, both forms", () => {
+    const positional = parseInline(`
+defineFeature("f", (r) => {
+  r.useExtension("audit", { name: "task" });
+});
+`);
+    expect(positional.patterns[0]).toMatchObject({ kind: "useExtension", entityName: "task" });
+
+    const objectForm = parseInline(`
+defineFeature("f", (r) => {
+  r.useExtension({ name: "audit", entity: { name: "task" } });
+});
+`);
+    expect(objectForm.patterns[0]).toMatchObject({ kind: "useExtension", entityName: "task" });
+  });
+
+  test("emits ParseError when called with no arguments", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.useExtension();
+});
+`);
+
+    expect(result.patterns).toEqual([]);
+    expect(result.errors[0]?.methodName).toBe("useExtension");
+  });
+
+  test("emits ParseError when object form is missing the entity property", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.useExtension({ name: "audit" });
+});
+`);
+
+    expect(result.errors[0]?.methodName).toBe("useExtension");
+  });
+
+  test("emits ParseError when object form's options is not a plain object", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.useExtension({ name: "audit", entity: "task", options: "not-an-object" });
+});
+`);
+
+    expect(result.errors[0]?.methodName).toBe("useExtension");
+  });
+
+  test("emits ParseError when the positional entity argument is missing", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.useExtension("audit");
+});
+`);
+
+    expect(result.errors[0]?.methodName).toBe("useExtension");
+  });
+
+  test("emits ParseError when positional options argument is not a plain object", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.useExtension("audit", "task", "not-an-object");
+});
+`);
+
+    expect(result.errors[0]?.methodName).toBe("useExtension");
+  });
+
+  test("emits ParseError when the extension name is not a string literal", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.useExtension(EXT, "task");
+});
+`);
+
+    expect(result.errors[0]?.methodName).toBe("useExtension");
+  });
+
+  test("emits ParseError when the positional entity ref is unresolvable", () => {
+    const result = parseInline(`
+const ent = { name: "task" };
+defineFeature("f", (r) => {
+  r.useExtension("audit", ent);
+});
+`);
+
+    expect(result.errors[0]?.methodName).toBe("useExtension");
+  });
+
+  test("emits ParseError when object form is missing the name property", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.useExtension({ entity: "task" });
+});
+`);
+
+    expect(result.errors[0]?.methodName).toBe("useExtension");
+  });
+});
+
+// =============================================================================
+// Round 4 extractors — mixed patterns (header data + opaque body source)
+// =============================================================================
+
+describe("extractHook", () => {
+  test("captures hookType, target and the function body", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.hook("postSave", "task", (event, ctx) => { console.log(event); });
+});
+`);
+
+    expect(result.patterns[0]).toMatchObject({
+      kind: "hook",
+      hookType: "postSave",
+      target: "task",
+    });
+    const fnBody = (result.patterns[0] as { fnBody?: { raw: string } } | undefined)?.fnBody;
+    expect(fnBody?.raw).toContain("(event, ctx)");
+  });
+
+  test("captures the optional phase from the options object", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.hook("postSave", "task", (event, ctx) => {}, { phase: "afterCommit" });
+});
+`);
+
+    expect(result.patterns[0]).toMatchObject({ kind: "hook", phase: "afterCommit" });
+  });
+
+  test("rejects an unknown hook type", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.hook("postCommit", "task", () => {});
+});
+`);
+
+    expect(result.errors[0]?.methodName).toBe("hook");
+  });
+
+  test("object form captures type, target and handler", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.hook({ type: "preSave", target: "task", handler: (event, ctx) => {} });
+});
+`);
+
+    expect(result.patterns[0]).toMatchObject({
+      kind: "hook",
+      hookType: "preSave",
+      target: "task",
+    });
+  });
+
+  test("emits ParseError when object form has an unknown hook type", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.hook({ type: "postCommit", target: "task", handler: () => {} });
+});
+`);
+
+    expect(result.errors[0]?.methodName).toBe("hook");
+  });
+
+  test("emits ParseError when object form is missing the handler property", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.hook({ type: "postSave", target: "task" });
+});
+`);
+
+    expect(result.errors[0]?.methodName).toBe("hook");
+  });
+
+  test("emits ParseError when object form handler is not an inline function", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.hook({ type: "postSave", target: "task", handler: handlerRef });
+});
+`);
+
+    expect(result.errors[0]?.methodName).toBe("hook");
+  });
+
+  test("captures a multi-entity target array", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.hook("postSave", ["task", "note"], () => {});
+});
+`);
+
+    expect(result.patterns[0]).toMatchObject({
+      kind: "hook",
+      target: ["task", "note"],
+    });
+  });
+
+  test("emits ParseError when called with no arguments", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.hook();
+});
+`);
+
+    expect(result.errors[0]?.methodName).toBe("hook");
+  });
+
+  test("emits ParseError when object form is missing the type property", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.hook({ target: "task", handler: () => {} });
+});
+`);
+
+    expect(result.errors[0]?.methodName).toBe("hook");
+  });
+
+  test("emits ParseError when object form is missing the target property", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.hook({ type: "postSave", handler: () => {} });
+});
+`);
+
+    expect(result.errors[0]?.methodName).toBe("hook");
+  });
+
+  test("emits ParseError when the handler is not an inline function", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.hook("postSave", "task", handlerRef);
+});
+`);
+
+    expect(result.errors[0]?.methodName).toBe("hook");
+  });
+
+  test("emits ParseError when the hook type is not a string literal", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.hook(TYPE, "task", () => {});
+});
+`);
+
+    expect(result.errors[0]?.methodName).toBe("hook");
+  });
+
+  test("emits ParseError when the target argument is missing", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.hook("postSave");
+});
+`);
+
+    expect(result.errors[0]?.methodName).toBe("hook");
+  });
+
+  test("emits ParseError when object form target is not a valid ref", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.hook({ type: "postSave", target: 123, handler: () => {} });
+});
+`);
+
+    expect(result.errors[0]?.methodName).toBe("hook");
+  });
+
+  test("emits ParseError when the hook function argument is missing", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.hook("postSave", "task");
+});
+`);
+
+    expect(result.errors[0]?.methodName).toBe("hook");
+  });
+});
+
+describe("extractHook — entity-wide { allOf } target", () => {
+  test("captures hookType and the allOf entity from positional form", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.hook("postSave", { allOf: "task" }, (event, ctx) => {});
+});
+`);
+
+    expect(result.patterns[0]).toMatchObject({
+      kind: "hook",
+      hookType: "postSave",
+      target: { allOf: "task" },
+    });
+  });
+
+  test("captures hookType and the allOf entity from object form", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.hook({ type: "postDelete", target: { allOf: "task" }, handler: () => {} });
+});
+`);
+
+    expect(result.patterns[0]).toMatchObject({
+      kind: "hook",
+      hookType: "postDelete",
+      target: { allOf: "task" },
+    });
+  });
+
+  test("rejects a malformed allOf value (not a string/ref)", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.hook("postSave", { allOf: 123 }, () => {});
+});
+`);
+
+    expect(result.errors[0]?.methodName).toBe("hook");
+  });
+});
+
+describe("extractAuthClaims", () => {
+  test("captures the function body as a SourceLocation", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.authClaims(async (user, ctx) => ({ teamId: "t1" }));
+});
+`);
+
+    expect(result.patterns[0]).toMatchObject({ kind: "authClaims" });
+  });
+
+  test("emits ParseError when called with no arguments", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.authClaims();
+});
+`);
+
+    expect(result.errors[0]?.methodName).toBe("authClaims");
+  });
+
+  test("emits ParseError when the argument is not an inline function", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.authClaims(handlerRef);
+});
+`);
+
+    expect(result.errors[0]?.methodName).toBe("authClaims");
+  });
+});
+
+describe("extractWriteHandler", () => {
+  test("inline form: name, schema, handler, options", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.writeHandler("task:create", z.object({ title: z.string() }), async (event, ctx) => {
+    return { isSuccess: true, data: {} };
+  }, { access: { roles: ["admin"] } });
+});
+`);
+
+    expect(result.patterns[0]).toMatchObject({
+      kind: "writeHandler",
+      handlerName: "task:create",
+      access: { roles: ["admin"] },
+    });
+  });
+
+  test("object form: defineWriteHandler shape", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.writeHandler({
+    name: "task:approve",
+    schema: z.object({ id: z.string() }),
+    handler: async (event, ctx) => ({ isSuccess: true, data: {} }),
+    access: { openToAll: true },
+  });
+});
+`);
+
+    expect(result.patterns[0]).toMatchObject({
+      kind: "writeHandler",
+      handlerName: "task:approve",
+      access: { openToAll: true },
+    });
+  });
+
+  test("resolves a same-file identifier arg to its object-literal form (#1007)", () => {
+    const result = parseInline(`
+const h = {
+  name: "task:archive",
+  schema: z.object({ id: z.string() }),
+  handler: async (event, ctx) => ({ isSuccess: true, data: {} }),
+};
+defineFeature("f", (r) => {
+  r.writeHandler(h);
+});
+`);
+
+    expect(result.patterns[0]).toMatchObject({
+      kind: "writeHandler",
+      handlerName: "task:archive",
+    });
+    expect(result.errors).toEqual([]);
+  });
+
+  test("keeps an unresolvable ref (import, factory call) as an opaque pattern instead of failing (#1007)", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.writeHandler(eventCreateHandler);
+});
+`);
+
+    expect(result.patterns[0]).toMatchObject({
+      kind: "writeHandler",
+      handlerName: undefined,
+      source: { raw: "r.writeHandler(eventCreateHandler)" },
+    });
+    expect(result.errors).toEqual([]);
+  });
+});
+
+describe("extractQueryHandler", () => {
+  test("inline form returns kind=queryHandler", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.queryHandler("task:list", z.object({}), async (q, ctx) => []);
+});
+`);
+
+    expect(result.patterns[0]).toMatchObject({
+      kind: "queryHandler",
+      handlerName: "task:list",
+    });
+  });
+});
+
+describe("extractStreamHandler", () => {
+  test("inline form: name, schema, handler, options", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.streamHandler("chat:complete", z.object({ prompt: z.string() }), async function* (input, ctx) {
+    yield "token";
+  }, { access: { roles: ["User"] } });
+});
+`);
+
+    expect(result.patterns[0]).toMatchObject({
+      kind: "streamHandler",
+      handlerName: "chat:complete",
+      access: { roles: ["User"] },
+    });
+  });
+
+  test("object form: name, schema, handler", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.streamHandler({
+    name: "chat:complete",
+    schema: z.object({ prompt: z.string() }),
+    handler: async function* (input, ctx) { yield "token"; },
+    access: { openToAll: true },
+  });
+});
+`);
+
+    expect(result.patterns[0]).toMatchObject({
+      kind: "streamHandler",
+      handlerName: "chat:complete",
+      access: { openToAll: true },
+    });
+  });
+
+  test("keeps an unresolvable ref as an opaque pattern instead of failing", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.streamHandler(chatCompleteHandler);
+});
+`);
+
+    expect(result.patterns[0]).toMatchObject({
+      kind: "streamHandler",
+      handlerName: undefined,
+      source: { raw: "r.streamHandler(chatCompleteHandler)" },
+    });
+    expect(result.errors).toEqual([]);
+  });
+});
+
+describe("extractJob", () => {
+  test("captures jobName, options and handler body", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.job("daily-cleanup", { trigger: { cron: "0 3 * * *" } }, async (ctx) => {});
+});
+`);
+
+    expect(result.patterns[0]).toMatchObject({
+      kind: "job",
+      jobName: "daily-cleanup",
+    });
+  });
+
+  test("object form captures name, handler and extra options", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.job({
+    name: "daily-cleanup",
+    trigger: { cron: "0 3 * * *" },
+    handler: async (ctx) => {},
+  });
+});
+`);
+
+    expect(result.patterns[0]).toMatchObject({
+      kind: "job",
+      jobName: "daily-cleanup",
+      options: { trigger: { cron: "0 3 * * *" } },
+    });
+  });
+
+  test("emits ParseError when called with no arguments", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.job();
+});
+`);
+
+    expect(result.errors[0]?.methodName).toBe("job");
+  });
+
+  test("emits ParseError when object form is missing the name property", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.job({ handler: async () => {} });
+});
+`);
+
+    expect(result.errors[0]?.methodName).toBe("job");
+  });
+
+  test("emits ParseError when object form is missing the handler property", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.job({ name: "daily-cleanup", trigger: { cron: "0 3 * * *" } });
+});
+`);
+
+    expect(result.errors[0]?.methodName).toBe("job");
+  });
+
+  test("emits ParseError when object form option value is not readable", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.job({ name: "daily-cleanup", handler: async () => {}, onComplete: () => {} });
+});
+`);
+
+    expect(result.errors[0]?.methodName).toBe("job");
+  });
+
+  test("emits ParseError when object form handler is not an inline function", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.job({ name: "daily-cleanup", handler: handlerRef });
+});
+`);
+
+    expect(result.errors[0]?.methodName).toBe("job");
+  });
+
+  test("emits ParseError when the job name is not a string literal", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.job(NAME, {}, async () => {});
+});
+`);
+
+    expect(result.errors[0]?.methodName).toBe("job");
+  });
+
+  test("emits ParseError when the options argument is missing", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.job("daily-cleanup");
+});
+`);
+
+    expect(result.errors[0]?.methodName).toBe("job");
+  });
+
+  test("emits ParseError when the handler argument is missing", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.job("daily-cleanup", { trigger: { cron: "0 3 * * *" } });
+});
+`);
+
+    expect(result.errors[0]?.methodName).toBe("job");
+  });
+
+  test("emits ParseError when options is not a plain object", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.job("daily-cleanup", () => {}, async () => {});
+});
+`);
+
+    expect(result.errors[0]?.methodName).toBe("job");
+  });
+
+  test("emits ParseError when the positional handler is not an inline function", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.job("daily-cleanup", { trigger: { cron: "0 3 * * *" } }, handlerRef);
+});
+`);
+
+    expect(result.errors[0]?.methodName).toBe("job");
+  });
+});
+
+describe("extractHttpRoute", () => {
+  test("captures method, path, anonymous, handler", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.httpRoute({
+    method: "GET",
+    path: "/feed.xml",
+    anonymous: true,
+    handler: async (c) => new Response("ok"),
+  });
+});
+`);
+
+    expect(result.patterns[0]).toMatchObject({
+      kind: "httpRoute",
+      method: "GET",
+      path: "/feed.xml",
+      anonymous: true,
+    });
+  });
+
+  test("emits ParseError when the argument is not an inline object", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.httpRoute("GET", "/feed.xml");
+});
+`);
+
+    expect(result.errors[0]?.methodName).toBe("httpRoute");
+  });
+
+  test("emits ParseError when method is missing", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.httpRoute({ path: "/feed.xml", handler: async () => {} });
 });
 `);
 
-    expect(result.patterns[0]).toMatchObject({
-      kind: "secret",
-      shortName: "apiKey",
-      options: { description: "Stripe API key" },
-    });
+    expect(result.errors[0]?.methodName).toBe("httpRoute");
   });
-});
 
-describe("extractClaimKey", () => {
-  test("captures shortName + claim type", () => {
+  test("emits ParseError when method is not a valid HTTP verb", () => {
     const result = parseInline(`
 defineFeature("f", (r) => {
-  r.claimKey("teamId", { type: "string" });
+  r.httpRoute({ method: "FETCH", path: "/feed.xml", handler: async () => {} });
 });
 `);
 
-    expect(result.patterns[0]).toMatchObject({
-      kind: "claimKey",
-      shortName: "teamId",
-      claimType: "string",
-    });
+    expect(result.errors[0]?.methodName).toBe("httpRoute");
   });
 
-  test("emits ParseError on invalid claim type", () => {
+  test("emits ParseError when path is missing", () => {
     const result = parseInline(`
 defineFeature("f", (r) => {
-  r.claimKey("teamId", { type: "bigint" });
+  r.httpRoute({ method: "GET", handler: async () => {} });
 });
 `);
 
-    expect(result.errors[0]?.methodName).toBe("claimKey");
+    expect(result.errors[0]?.methodName).toBe("httpRoute");
   });
-});
 
-describe("extractReferenceData", () => {
-  test("captures entity name + data array", () => {
+  test("emits ParseError when handler is missing", () => {
     const result = parseInline(`
 defineFeature("f", (r) => {
-  r.referenceData("status", [
-    { id: "open", label: "Open" },
-    { id: "closed", label: "Closed" },
-  ]);
+  r.httpRoute({ method: "GET", path: "/feed.xml" });
 });
 `);
 
-    expect(result.patterns[0]).toMatchObject({
-      kind: "referenceData",
-      entityName: "status",
-      data: [
-        { id: "open", label: "Open" },
-        { id: "closed", label: "Closed" },
-      ],
-    });
+    expect(result.errors[0]?.methodName).toBe("httpRoute");
   });
 
-  test("captures the optional upsertKey", () => {
+  test("emits ParseError when handler is not an inline function", () => {
     const result = parseInline(`
 defineFeature("f", (r) => {
-  r.referenceData("status", [{ id: "open" }], { upsertKey: "id" });
+  r.httpRoute({ method: "GET", path: "/feed.xml", handler: handlerRef });
 });
 `);
 
-    expect(result.patterns[0]).toMatchObject({
-      kind: "referenceData",
-      entityName: "status",
-      upsertKey: "id",
-    });
+    expect(result.errors[0]?.methodName).toBe("httpRoute");
   });
 });
 
-describe("extractUseExtension", () => {
-  test("captures extension name + entity ref", () => {
+describe("extractDefineEvent", () => {
+  test("captures eventName + version", () => {
     const result = parseInline(`
 defineFeature("f", (r) => {
-  r.useExtension("audit", "task");
+  r.defineEvent("incidentOpened", z.object({ id: z.string() }), { version: 2 });
 });
 `);
 
     expect(result.patterns[0]).toMatchObject({
-      kind: "useExtension",
-      extensionName: "audit",
-      entityName: "task",
+      kind: "defineEvent",
+      eventName: "incidentOpened",
+      version: 2,
     });
   });
 
-  test("captures optional options", () => {
+  test("object form captures name, schema, version and migrations", () => {
     const result = parseInline(`
 defineFeature("f", (r) => {
-  r.useExtension("audit", "task", { mode: "verbose" });
+  r.defineEvent({
+    name: "incidentOpened",
+    schema: z.object({ id: z.string() }),
+    version: 2,
+    migrations: { "1": (payload) => payload },
+  });
 });
 `);
 
     expect(result.patterns[0]).toMatchObject({
-      kind: "useExtension",
-      extensionName: "audit",
-      entityName: "task",
-      options: { mode: "verbose" },
+      kind: "defineEvent",
+      eventName: "incidentOpened",
+      version: 2,
+      migrations: { "1": expect.anything() },
     });
   });
-});
 
-// =============================================================================
-// Round 4 extractors — mixed patterns (header data + opaque body source)
-// =============================================================================
-
-describe("extractHook", () => {
-  test("captures hookType, target and the function body", () => {
+  test("emits ParseError when called with no arguments", () => {
     const result = parseInline(`
 defineFeature("f", (r) => {
-  r.hook("postSave", "task", (event, ctx) => { console.log(event); });
+  r.defineEvent();
 });
 `);
 
-    expect(result.patterns[0]).toMatchObject({
-      kind: "hook",
-      hookType: "postSave",
-      target: "task",
-    });
-    const fnBody = (result.patterns[0] as { fnBody?: { raw: string } } | undefined)?.fnBody;
-    expect(fnBody?.raw).toContain("(event, ctx)");
+    expect(result.errors[0]?.methodName).toBe("defineEvent");
   });
 
-  test("captures the optional phase from the options object", () => {
+  test("emits ParseError when object form is missing the name property", () => {
     const result = parseInline(`
 defineFeature("f", (r) => {
-  r.hook("postSave", "task", (event, ctx) => {}, { phase: "afterCommit" });
+  r.defineEvent({ schema: z.object({ id: z.string() }) });
 });
 `);
 
-    expect(result.patterns[0]).toMatchObject({ kind: "hook", phase: "afterCommit" });
+    expect(result.errors[0]?.methodName).toBe("defineEvent");
   });
 
-  test("rejects an unknown hook type", () => {
+  test("emits ParseError when object form is missing the schema property", () => {
     const result = parseInline(`
 defineFeature("f", (r) => {
-  r.hook("postCommit", "task", () => {});
+  r.defineEvent({ name: "incidentOpened" });
 });
 `);
 
-    expect(result.errors[0]?.methodName).toBe("hook");
+    expect(result.errors[0]?.methodName).toBe("defineEvent");
   });
-});
 
-describe("extractEntityHook", () => {
-  test("captures hookType, entity and the function body", () => {
+  test("emits ParseError when the event name is not a string literal", () => {
     const result = parseInline(`
 defineFeature("f", (r) => {
-  r.entityHook("postSave", "task", (event, ctx) => {});
+  r.defineEvent(EVENT, z.object({ id: z.string() }));
 });
 `);
 
-    expect(result.patterns[0]).toMatchObject({
-      kind: "entityHook",
-      hookType: "postSave",
-      entityName: "task",
-    });
+    expect(result.errors[0]?.methodName).toBe("defineEvent");
   });
 
-  test("rejects validation as entity-hook type (only postSave/preDelete/postDelete allowed)", () => {
+  test("emits ParseError when the schema argument is missing", () => {
     const result = parseInline(`
 defineFeature("f", (r) => {
-  r.entityHook("validation", "task", () => {});
+  r.defineEvent("incidentOpened");
 });
 `);
 
-    expect(result.errors[0]?.methodName).toBe("entityHook");
+    expect(result.errors[0]?.methodName).toBe("defineEvent");
   });
 });
 
-describe("extractAuthClaims", () => {
-  test("captures the function body as a SourceLocation", () => {
+describe("extractDefineEvent — migrations (formerly extractEventMigration)", () => {
+  test("positional-form migrations array captures the fromVersion→transform step", () => {
     const result = parseInline(`
 defineFeature("f", (r) => {
-  r.authClaims(async (user, ctx) => ({ teamId: "t1" }));
+  r.defineEvent("incidentOpened", z.object({ id: z.string() }), {
+    version: 2,
+    migrations: [
+      { fromVersion: 1, toVersion: 2, transform: (payload) => ({ ...payload, severity: "low" }) },
+    ],
+  });
 });
 `);
 
-    expect(result.patterns[0]).toMatchObject({ kind: "authClaims" });
+    expect(result.patterns[0]).toMatchObject({
+      kind: "defineEvent",
+      eventName: "incidentOpened",
+      version: 2,
+      migrations: { "1": expect.anything() },
+    });
   });
-});
 
-describe("extractWriteHandler", () => {
-  test("inline form: name, schema, handler, options", () => {
+  test("object-form migrations map captures the fromVersion→transform step", () => {
     const result = parseInline(`
 defineFeature("f", (r) => {
-  r.writeHandler("task:create", z.object({ title: z.string() }), async (event, ctx) => {
-    return { isSuccess: true, data: {} };
-  }, { access: { roles: ["admin"] } });
+  r.defineEvent({
+    name: "incidentOpened",
+    schema: z.object({ id: z.string() }),
+    version: 2,
+    migrations: {
+      "1": (payload) => ({ ...payload, severity: "low" }),
+    },
+  });
 });
 `);
 
     expect(result.patterns[0]).toMatchObject({
-      kind: "writeHandler",
-      handlerName: "task:create",
-      access: { roles: ["admin"] },
+      kind: "defineEvent",
+      eventName: "incidentOpened",
+      version: 2,
+      migrations: { "1": expect.anything() },
     });
   });
 
-  test("object form: defineWriteHandler shape", () => {
+  test("skips malformed migration array entries instead of failing the whole extract", () => {
     const result = parseInline(`
 defineFeature("f", (r) => {
-  r.writeHandler({
-    name: "task:approve",
-    schema: z.object({ id: z.string() }),
-    handler: async (event, ctx) => ({ isSuccess: true, data: {} }),
-    access: { openToAll: true },
+  r.defineEvent("incidentOpened", z.object({ id: z.string() }), {
+    migrations: [
+      "skip-me",
+      { fromVersion: "bad", transform: (payload) => payload },
+      { fromVersion: 1, transform: (payload) => ({ ...payload, ok: true }) },
+    ],
   });
 });
 `);
 
+    expect(result.errors).toEqual([]);
     expect(result.patterns[0]).toMatchObject({
-      kind: "writeHandler",
-      handlerName: "task:approve",
-      access: { openToAll: true },
+      kind: "defineEvent",
+      migrations: { "1": expect.anything() },
     });
   });
 });
 
-describe("extractQueryHandler", () => {
-  test("inline form returns kind=queryHandler", () => {
+describe("extractNotification", () => {
+  test("captures trigger + recipient + data bodies", () => {
     const result = parseInline(`
 defineFeature("f", (r) => {
-  r.queryHandler("task:list", z.object({}), async (q, ctx) => []);
+  r.notification("incidentOpened", {
+    trigger: { on: "incident:create" },
+    recipient: (event) => ({ tenant: event.tenantId }),
+    data: (event) => ({ id: event.id }),
+  });
 });
 `);
 
     expect(result.patterns[0]).toMatchObject({
-      kind: "queryHandler",
-      handlerName: "task:list",
+      kind: "notification",
+      notificationName: "incidentOpened",
+      trigger: { on: "incident:create" },
     });
   });
-});
 
-describe("extractJob", () => {
-  test("captures jobName, options and handler body", () => {
+  test("object form captures name + trigger/recipient/data", () => {
     const result = parseInline(`
 defineFeature("f", (r) => {
-  r.job("daily-cleanup", { trigger: { cron: "0 3 * * *" } }, async (ctx) => {});
+  r.notification({
+    name: "incidentOpened",
+    trigger: { on: "incident:create" },
+    recipient: (event) => ({ tenant: event.tenantId }),
+    data: (event) => ({ id: event.id }),
+  });
 });
 `);
 
     expect(result.patterns[0]).toMatchObject({
-      kind: "job",
-      jobName: "daily-cleanup",
+      kind: "notification",
+      notificationName: "incidentOpened",
     });
   });
+
+  test("captures optional template bodies", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.notification("incidentOpened", {
+    trigger: { on: "incident:create" },
+    recipient: (event) => ({}),
+    data: (event) => ({}),
+    templates: {
+      email: (payload) => payload.subject,
+      inApp: (payload) => payload.title,
+    },
+  });
 });
+`);
 
-describe("extractHttpRoute", () => {
-  test("captures method, path, anonymous, handler", () => {
+    const templates = (result.patterns[0] as { templates?: Record<string, unknown> } | undefined)
+      ?.templates;
+    expect(Object.keys(templates ?? {})).toEqual(["email", "inApp"]);
+  });
+
+  test("emits ParseError when called with no arguments", () => {
     const result = parseInline(`
 defineFeature("f", (r) => {
-  r.httpRoute({
-    method: "GET",
-    path: "/feed.xml",
-    anonymous: true,
-    handler: async (c) => new Response("ok"),
+  r.notification();
+});
+`);
+
+    expect(result.errors[0]?.methodName).toBe("notification");
   });
+
+  test("emits ParseError when object form is missing the name property", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.notification({ trigger: { on: "x" }, recipient: () => ({}), data: () => ({}) });
 });
 `);
 
-    expect(result.patterns[0]).toMatchObject({
-      kind: "httpRoute",
-      method: "GET",
-      path: "/feed.xml",
-      anonymous: true,
-    });
+    expect(result.errors[0]?.methodName).toBe("notification");
   });
+
+  test("emits ParseError when the notification name is not a string literal", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.notification(NAME, { trigger: { on: "x" }, recipient: () => ({}), data: () => ({}) });
 });
+`);
 
-describe("extractDefineEvent", () => {
-  test("captures eventName + version", () => {
+    expect(result.errors[0]?.methodName).toBe("notification");
+  });
+
+  test("emits ParseError when the definition object is missing", () => {
     const result = parseInline(`
 defineFeature("f", (r) => {
-  r.defineEvent("incidentOpened", z.object({ id: z.string() }), { version: 2 });
+  r.notification("incidentOpened");
 });
 `);
 
-    expect(result.patterns[0]).toMatchObject({
-      kind: "defineEvent",
-      eventName: "incidentOpened",
-      version: 2,
-    });
+    expect(result.errors[0]?.methodName).toBe("notification");
   });
+
+  test("emits ParseError when trigger is missing", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.notification("incidentOpened", { recipient: () => ({}), data: () => ({}) });
 });
+`);
+
+    expect(result.errors[0]?.methodName).toBe("notification");
+  });
 
-describe("extractEventMigration", () => {
-  test("captures fromVersion / toVersion / transform body", () => {
+  test("emits ParseError when trigger.on is not a string/ref", () => {
     const result = parseInline(`
 defineFeature("f", (r) => {
-  r.eventMigration("incidentOpened", 1, 2, (payload) => ({ ...payload, severity: "low" }));
+  r.notification("incidentOpened", {
+    trigger: { on: 123 },
+    recipient: () => ({}),
+    data: () => ({}),
+  });
 });
 `);
 
-    expect(result.patterns[0]).toMatchObject({
-      kind: "eventMigration",
-      eventName: "incidentOpened",
-      fromVersion: 1,
-      toVersion: 2,
-    });
+    expect(result.errors[0]?.methodName).toBe("notification");
+  });
+
+  test("emits ParseError when recipient is not an inline function", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.notification("incidentOpened", {
+    trigger: { on: "incident:create" },
+    recipient: recipientRef,
+    data: () => ({}),
   });
 });
+`);
 
-describe("extractNotification", () => {
-  test("captures trigger + recipient + data bodies", () => {
+    expect(result.errors[0]?.methodName).toBe("notification");
+  });
+
+  test("emits ParseError when data is not an inline function", () => {
     const result = parseInline(`
 defineFeature("f", (r) => {
   r.notification("incidentOpened", {
     trigger: { on: "incident:create" },
-    recipient: (event) => ({ tenant: event.tenantId }),
-    data: (event) => ({ id: event.id }),
+    recipient: () => ({}),
+    data: dataRef,
   });
 });
 `);
 
-    expect(result.patterns[0]).toMatchObject({
-      kind: "notification",
-      notificationName: "incidentOpened",
-      trigger: { on: "incident:create" },
-    });
+    expect(result.errors[0]?.methodName).toBe("notification");
   });
 });
 
@@ -886,3 +2287,82 @@ defineFeature("f", (r) => {
     });
   });
 });
+
+// =============================================================================
+// Regression — show-pony-shaped feature (#998)
+// =============================================================================
+// Mirrors the real-world idioms from show-pony/src/features/show-pony/feature.ts
+// that motivated #998 — inline here (not the live external repo path) so this
+// test doesn't depend on the show-pony checkout being present in this repo's CI.
+
+describe("show-pony-shaped feature (regression, #998)", () => {
+  const result = parseInline(`
+import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import { eventEntity } from "./schema";
+import { eventCreateHandler } from "./handlers/event-create.write";
+import { createInviteBrandingQuery } from "./handlers/invite-branding.query";
+import { registerShowPonyScreens } from "./register/screens";
+
+const someFeature = { name: "mail-foundation" };
+
+defineFeature("showpony", (r) => {
+  r.requires(someFeature.name, "config");
+  r.entity("event", eventEntity);
+  r.writeHandler(eventCreateHandler);
+  r.queryHandler(createInviteBrandingQuery());
+  registerShowPonyScreens(r);
+});
+`);
+
+  test("requires()'s computed name and entity's imported const resolve via the raw-ref sentinel (#998/#1009 fix)", () => {
+    expect(result.patterns[0]).toMatchObject({
+      kind: "requires",
+      featureNames: [{ __raw: "someFeature.name" }, "config"],
+    });
+    expect(result.patterns[1]).toMatchObject({
+      kind: "entity",
+      entityName: "event",
+      definition: { __raw: "eventEntity" },
+    });
+  });
+
+  test("writeHandler/queryHandler(handlerRef) resolve as opaque patterns (#998/#1007 fix)", () => {
+    expect(result.patterns).toMatchObject([
+      { kind: "requires" },
+      { kind: "entity" },
+      { kind: "writeHandler", handlerName: undefined },
+      { kind: "queryHandler", handlerName: undefined },
+    ]);
+    expect(result.errors).toEqual([]);
+  });
+
+  test("an imported registrar-wrapper stays invisible when its file can't be resolved (in-memory project, #1008)", () => {
+    // parseInline uses an in-memory ts-morph Project — "./register/screens"
+    // isn't a real file, so getModuleSpecifierSourceFile() returns
+    // undefined and the wrapper is skipped like any other unresolvable
+    // call. Real cross-file resolution against on-disk files is covered by
+    // the parseFeatureFile fixture tests below.
+    expect(result.patterns.some((p) => p.kind === "screen" || p.kind === "nav")).toBe(false);
+  });
+});
+
+describe("cross-file registrar-wrapper resolution against a real filesystem Project (#1008)", () => {
+  const fixture = resolve(__dirname, "fixtures/cross-file-registrar/feature.ts");
+  const result = parseFeatureFile(fixture);
+
+  test("resolves the imported wrapper and recognises the nav pattern it registers", () => {
+    expect(result.errors).toEqual([]);
+    expect(result.patterns).toMatchObject([
+      { kind: "requires", featureNames: ["config"] },
+      { kind: "nav", definition: { id: "foo", label: "Foo" } },
+    ]);
+  });
+
+  test("the resolved pattern's source points at the imported file, not the entry file", () => {
+    const navPattern = result.patterns.find((p) => p.kind === "nav");
+    expect(navPattern?.source.file).toBe(
+      resolve(__dirname, "fixtures/cross-file-registrar/screens.ts"),
+    );
+    expect(navPattern?.source.file).not.toBe(fixture);
+  });
+});