@cosmicdrift/kumiko-framework 0.320.0 → 0.321.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.320.0",
+  "version": "0.321.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>",
@@ -202,8 +202,8 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-http": "0.320.0",
-    "@cosmicdrift/kumiko-types": "0.320.0",
+    "@cosmicdrift/kumiko-http": "0.321.0",
+    "@cosmicdrift/kumiko-types": "0.321.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.13.1",
@@ -219,7 +219,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.320.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.321.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/__tests__/schema-cli.integration.test.ts

@@ -54,6 +54,17 @@ describe("runSchemaCli — no-DB paths", () => {
     expect(cap.err).toHaveLength(0);
   });
 
+  test.each(["--help", "-h", "help"])(
+    "%s prints the same usage as no subcommand and exits 0",
+    async (helpArg) => {
+      const cap = captureOut();
+      const code = await runSchemaCli([helpArg], appCwd, cap.out);
+      expect(code).toBe(0);
+      expect(cap.log.join("\n")).toContain("Subcommands:");
+      expect(cap.err).toHaveLength(0);
+    },
+  );
+
   test("unknown subcommand exits 1 and reports it on stderr", async () => {
     const cap = captureOut();
     const code = await runSchemaCli(["cutover"], appCwd, cap.out);

package/src/__tests__/upgrade-cli.test.ts

@@ -14,8 +14,8 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import {
   findCodemodScriptsRoot,
-  findCoreChangelogFile,
   findFeaturesDirs,
+  findPackageChangelogFiles,
   resolveCodemodScript,
   runUpgradeCli,
   type UpgradeCliOut,
@@ -92,6 +92,23 @@ async function runJson(cwd: string, from: string): Promise<{ pending: Array<{ ti
   return JSON.parse(spy.logs.join("\n"));
 }
 
+describe("upgrade command — --help", () => {
+  test("--help prints usage and exits 0 without touching the filesystem", async () => {
+    const spy = makeSpyOutput();
+    const exit = await runUpgradeCli(["--help"], "/nonexistent-cwd", spy.out);
+    expect(exit).toBe(0);
+    expect(spy.logs.join("\n")).toContain("kumiko-upgrade");
+    expect(spy.errs).toEqual([]);
+  });
+
+  test("-h behaves the same as --help", async () => {
+    const spy = makeSpyOutput();
+    const exit = await runUpgradeCli(["-h"], "/nonexistent-cwd", spy.out);
+    expect(exit).toBe(0);
+    expect(spy.logs.join("\n")).toContain("--apply");
+  });
+});
+
 describe("upgrade command — framework core changelog", () => {
   test("collects core changes.json from the framework repo layout", async () => {
     const cwd = tmp({
@@ -198,6 +215,37 @@ describe("upgrade command — framework core changelog", () => {
   });
 });
 
+describe("upgrade command — every package's changelog, not just framework core", () => {
+  const SERVER_RUNTIME_ENTRY = JSON.stringify([
+    { version: "0.168.0", type: "breaking", title: "server-runtime breaking change" },
+  ]);
+
+  test("a hoisted non-framework, non-bundled-features package's changes.json shows up in pending", async () => {
+    const cwd = tmp({
+      "node_modules/@cosmicdrift/kumiko-server-runtime/src/changes.json": SERVER_RUNTIME_ENTRY,
+      "apps/web/package.json": "{}",
+    });
+
+    const result = await runJson(`${cwd}/apps/web`, "0.165.0");
+
+    expect(result.pending.map((e) => e.title)).toEqual(["server-runtime breaking change"]);
+  });
+
+  test("bundled-features is never double-counted alongside findFeaturesDirs's own collection", async () => {
+    const cwd = tmp({
+      "node_modules/@cosmicdrift/kumiko-server-runtime/src/changes.json": SERVER_RUNTIME_ENTRY,
+      "node_modules/@cosmicdrift/kumiko-bundled-features/src/user/changes.json": FEATURE_ENTRY,
+      "apps/web/package.json": "{}",
+    });
+
+    const result = await runJson(`${cwd}/apps/web`, "0.165.0");
+
+    expect(result.pending.map((e) => e.title).sort()).toEqual(
+      ["feature fix", "server-runtime breaking change"].sort(),
+    );
+  });
+});
+
 describe("upgrade command — enterprise package layout", () => {
   // Layout is detected by presence of changes.json, not an "ai-" name
   // prefix — the old heuristic silently dropped every enterprise package
@@ -641,9 +689,8 @@ describe("changes.json codemod fields resolve to real published scripts", () =>
   }
 
   test("every codemod field is a scripts/codemod/*.ts path that resolves to an existing published script", () => {
-    const coreChangelog = findCoreChangelogFile(REAL_REPO_ROOT);
     const changesJsonFiles = [
-      ...(coreChangelog ? [coreChangelog] : []),
+      ...findPackageChangelogFiles(REAL_REPO_ROOT),
       ...findFeaturesDirs(REAL_REPO_ROOT).flatMap((dir) => findChangesJsonFiles(dir)),
     ];
     expect(changesJsonFiles.length).toBeGreaterThan(0);

package/src/api/__tests__/client-ip.test.ts

@@ -9,6 +9,7 @@ import {
   assertValidTrustedProxyHops,
   type ClientIpHeaderSource,
   createClientIpResolver,
+  parseTrustedProxyHopsEnv,
 } from "../client-ip";
 
 function sourceOf(headers: Record<string, string>, socketAddress?: string): ClientIpHeaderSource {
@@ -137,3 +138,27 @@ describe("createClientIpResolver", () => {
     expect(() => createClientIpResolver(-1, "test")).toThrow(/non-negative integer/);
   });
 });
+
+describe("parseTrustedProxyHopsEnv", () => {
+  test("undefined -> undefined (no env set)", () => {
+    expect(parseTrustedProxyHopsEnv(undefined, "test")).toBeUndefined();
+  });
+
+  test("valid digits-only string -> parsed integer", () => {
+    expect(parseTrustedProxyHopsEnv("1", "test")).toBe(1);
+    expect(parseTrustedProxyHopsEnv("0", "test")).toBe(0);
+    expect(parseTrustedProxyHopsEnv("42", "test")).toBe(42);
+  });
+
+  test("hex/exponent/negative notation throws instead of silently coercing", () => {
+    expect(() => parseTrustedProxyHopsEnv("0x10", "test")).toThrow(/non-negative integer/);
+    expect(() => parseTrustedProxyHopsEnv("1e3", "test")).toThrow(/non-negative integer/);
+    expect(() => parseTrustedProxyHopsEnv("-1", "test")).toThrow(/non-negative integer/);
+  });
+
+  test("error message carries the context prefix and the raw value", () => {
+    expect(() => parseTrustedProxyHopsEnv("x", "runProdApp")).toThrow(
+      'runProdApp: KUMIKO_TRUSTED_PROXY_HOPS must be a non-negative integer, got "x".',
+    );
+  });
+});

package/src/api/__tests__/extra-routes.integration.test.ts

@@ -585,6 +585,48 @@ describe("extraRoutes: entry:signature", () => {
   });
 });
 
+describe("extraRoutes: entry:anonymous deps.clientIp", () => {
+  const clientIpRoute: AnonymousExtraRoute = {
+    method: "GET",
+    path: "/public/client-ip-probe",
+    entry: "anonymous",
+    handler: async (c, deps) => c.json({ clientIp: deps.clientIp }),
+  };
+
+  test("default trustedProxyHops (0): a spoofed X-Forwarded-For is ignored, socket address wins", async () => {
+    const stack = await setupTestStack({
+      features: [probeFeature],
+      extraRoutes: [clientIpRoute],
+    });
+    try {
+      const res = await stack.app.request(
+        "/public/client-ip-probe",
+        { headers: { "x-forwarded-for": "203.0.113.10" } },
+        "198.51.100.9",
+      );
+      expect(await res.json()).toEqual({ clientIp: "198.51.100.9" });
+    } finally {
+      await stack.cleanup();
+    }
+  });
+
+  test("trustedProxyHops: 1 — the rightmost X-Forwarded-For entry is trusted", async () => {
+    const stack = await setupTestStack({
+      features: [probeFeature],
+      extraRoutes: [clientIpRoute],
+      trustedProxyHops: 1,
+    });
+    try {
+      const res = await stack.app.request("/public/client-ip-probe", {
+        headers: { "x-forwarded-for": "203.0.113.10" },
+      });
+      expect(await res.json()).toEqual({ clientIp: "203.0.113.10" });
+    } finally {
+      await stack.cleanup();
+    }
+  });
+});
+
 // Type-level contract for ExtraRouteDefinition (kumiko-framework#3050): the
 // bodies below are never invoked — tsc checks them, bun:test does not run
 // them. Each `@ts-expect-error` turns into an "unused directive" compile

package/src/api/client-ip.ts

@@ -44,6 +44,33 @@ export function assertValidTrustedProxyHops(value: number | undefined, context:
   }
 }
 
+export const TRUSTED_PROXY_HOPS_ENV = "KUMIKO_TRUSTED_PROXY_HOPS";
+
+// Fail loud on a garbage env value rather than silently coercing to NaN:
+// a resolver built from NaN treats it like "always short chain" and returns
+// "unknown" for every request, which collapses an IP-keyed rate limiter
+// into one shared bucket for the whole deployment — a self-inflicted DoS,
+// worse than staying on the default. Digits-only (not parseInt) —
+// parseInt("0x10")/("1e3")/("2x") would silently coerce instead of failing.
+export function parseTrustedProxyHopsEnv(
+  raw: string | undefined,
+  context: string,
+): number | undefined {
+  if (raw === undefined) return undefined;
+  if (!/^\d+$/.test(raw)) {
+    throw new Error(
+      `${context}: ${TRUSTED_PROXY_HOPS_ENV} must be a non-negative integer, got "${raw}".`,
+    );
+  }
+  const parsed = Number.parseInt(raw, 10);
+  if (!Number.isInteger(parsed) || parsed < 0) {
+    throw new Error(
+      `${context}: ${TRUSTED_PROXY_HOPS_ENV} must be a non-negative integer, got "${raw}".`,
+    );
+  }
+  return parsed;
+}
+
 // Instance-scoped, NOT a module singleton: the warn-once flag must reset
 // per server boot (and per test), otherwise the first test to trigger it
 // consumes the warning for the whole process and later tests can't observe

package/src/api/extra-route.ts

@@ -32,6 +32,9 @@ export type AnonymousExtraRouteDeps = {
    *  user, same request-resolved tenant (never overridable), only under
    *  "/api/" (the only path that populates a session user). */
   readonly write: (type: string, payload: unknown) => Promise<WriteResult>;
+  /** Resolved by the server's single trustedProxyHops-aware resolver —
+   *  never read X-Forwarded-For yourself. */
+  readonly clientIp: string;
 };
 
 export type AnonymousExtraRoute = {

package/src/api/index.ts

@@ -34,6 +34,8 @@ export {
   clientIpSourceFromHonoContext,
   createClientIpResolver,
   extractSocketAddress,
+  parseTrustedProxyHopsEnv,
+  TRUSTED_PROXY_HOPS_ENV,
   UNKNOWN_CLIENT_IP,
 } from "./client-ip";
 export type {

package/src/api/server.ts

@@ -617,6 +617,7 @@ export function buildServer(options: ServerOptions): KumikoServer {
         userId: event.metadata.userId,
         ...(mspOwner && { callerFeature: mspOwner }),
         ...(mspFiles && { files: mspFiles }),
+        ...(contextWithObservability.secrets && { secrets: contextWithObservability.secrets }),
         ...(mspFiles && {
           derivatives: createDerivativesContext({
             files: mspFiles,
@@ -1260,7 +1261,7 @@ type ExtraRouteHonoHandlerDeps = {
   readonly secrets: import("../secrets").SecretsContext | undefined;
   readonly dispatchSystemWrite: (args: SystemDispatchArgs) => Promise<WriteResult>;
   readonly dispatchSystemQuery: (args: SystemDispatchArgs) => Promise<unknown>;
-  readonly clientIpResolver?: ClientIpResolver;
+  readonly clientIpResolver: ClientIpResolver;
 };
 
 function buildExtraRouteHonoHandler(
@@ -1276,6 +1277,7 @@ function buildExtraRouteHonoHandler(
           registry: shared.registry,
           systemQuery: makeSystemQuery(c, shared.dispatcher, shared.clientIpResolver),
           write: makeAnonymousWrite(c, shared.dispatcher),
+          clientIp: shared.clientIpResolver.resolve(clientIpSourceFromHonoContext(c)),
         });
     case ExtraRouteEntries.user:
       return async (c) => {

package/src/changes.json

@@ -1,4 +1,52 @@
 [
+  {
+    "version": "0.321.0",
+    "type": "improvement",
+    "title": "kumiko-schema gained --help/-h/help",
+    "detail": "Prints usage listing the available subcommands and exits 0.",
+    "migration": "No action needed."
+  },
+  {
+    "version": "0.321.0",
+    "type": "improvement",
+    "title": "parseTrustedProxyHopsEnv/TRUSTED_PROXY_HOPS_ENV factored out of runProdApp for runDevApp and consumer tooling to share",
+    "detail": "`packages/framework/src/api/client-ip.ts` gained\n`parseTrustedProxyHopsEnv(raw, context)` and the\n`TRUSTED_PROXY_HOPS_ENV = \"KUMIKO_TRUSTED_PROXY_HOPS\"` constant (both\nexported via the `api` barrel), moved out of `runProdApp`'s inline\nparsing. Same validation and error message as before.",
+    "migration": "No action needed; runProdApp's behavior and error message are unchanged."
+  },
+  {
+    "version": "0.321.0",
+    "type": "improvement",
+    "title": "AnonymousExtraRouteDeps gained clientIp, resolved by the server's trustedProxyHops-aware resolver",
+    "detail": "`AnonymousExtraRouteDeps.clientIp: string`, populated the same way as the\nhttpRoute path via `shared.clientIpResolver.resolve\n(clientIpSourceFromHonoContext(c))`. `ExtraRouteHonoHandlerDeps\n.clientIpResolver` is now required (its only caller always supplied it).",
+    "migration": "Anonymous extra routes that need the caller's IP should read\n`deps.clientIp` instead of reading `X-Forwarded-For` (or any other\nheader) themselves — the latter is attacker-controlled unless you also\nknow the exact trusted-hop count. Tests that build an\n`AnonymousExtraRouteDeps` literal by hand must add a `clientIp` string."
+  },
+  {
+    "version": "0.321.0",
+    "type": "improvement",
+    "title": "feature-ast resolves imported constants and registrar wrappers without building a TypeScript program",
+    "detail": "Imported `const` initializers (named imports, aliases, `export { X as Y }`,\nre-export chains, `export *`) and imported registrar-wrapper functions are\nresolved through `ts.resolveModuleName` plus a syntactic export walk.\nSame-file lookups walk enclosing block scopes instead of the file top level. Parse\noutput is unchanged; parsing a feature file drops from hundreds of\nmilliseconds to a few milliseconds."
+  },
+  {
+    "version": "0.321.0",
+    "type": "breaking",
+    "title": "webhook.send step auth secretRef renamed to secret; MultiStreamApplyContext gained an optional secrets field",
+    "detail": "`r.step.webhook.send`'s `auth` union renamed `secretRef` → `secret` (see\nthe step-dispatcher entry for the full rationale). `MultiStreamApplyContext`\n(and `createMultiStreamApplyContext`'s deps) gained an optional\n`secrets?: SecretsContext` field, mirroring `files`/`derivatives` — present\nwhen the app booted with the secrets feature, letting a saga/process-\nmanager MSP apply read a tenant secret with its own audit context. The\nserver's MSP consumer wiring now threads the boot-time `AppContext.secrets`\nthrough automatically; `rebuildMultiStreamProjection`'s rebuild context\ndeliberately does not carry `secrets` (rebuild must stay side-effect-free).",
+    "migration": "Rename `auth.secretRef` → `auth.secret` at every `r.step.webhook.send`\ncall site. No action needed for `MultiStreamApplyContext` consumers that\ndon't read `ctx.secrets` — the field is optional and additive."
+  },
+  {
+    "version": "0.321.0",
+    "type": "improvement",
+    "title": "New event-store primitive transferAggregateStreams for tenant-to-tenant aggregate moves",
+    "detail": "`transferAggregateStreams(db, { sourceTenantId, destinationTenantId,\naggregateType, aggregateIds, transferredBy })` (event-store/transfer.ts)\nmoves an aggregate's events, drops its snapshot, and carries its archive\nmarker from one tenant to another, then appends one\n`kumiko:system:aggregate.transferred` system event per moved aggregate\n(own fresh stream, destination tenant, payload carries aggregateType/\naggregateId/sourceTenantId/destinationTenantId). An id with no events\nunder the given tenant/aggregateType is left untouched and gets no event.\nBacked by db/queries/event-store-transfer.ts.",
+    "migration": "No action for existing consumers — this is a new, additive primitive."
+  },
+  {
+    "version": "0.321.0",
+    "type": "fix",
+    "title": "upgrade-cli now collects every package's changes.json, not just framework's",
+    "detail": "`findCoreChangelogFile(cwd): string | null` is replaced by\n`findPackageChangelogFiles(cwd): string[]`. In the framework repo itself\nit collects every `packages/<dir>/src/changes.json` except\n`packages/bundled-features` (bundled features are already collected per\nfeature dir). In a consumer repo it walks up to 10 levels looking for\n`node_modules/@cosmicdrift/*/src/changes.json`, skipping\n`kumiko-bundled-features`, deduping by package name (nearest\n`node_modules` wins) and by realpath (symlinked workspace copies).",
+    "migration": "No action needed — `kumiko upgrade` now surfaces more relevant breaking\nchanges than before, it never hides ones it previously showed."
+  },
   {
     "version": "0.320.0",
     "type": "breaking",

package/src/db/queries/event-store-transfer.ts

@@ -0,0 +1,73 @@
+// Raw SQL backing event-store/transfer.ts — the framework's own tenant-transfer
+// primitive for streams. Kept in db/queries alongside the rest of the
+// event-store's raw statements (see event-store.ts, event-store-admin.ts,
+// backfill-pii.ts): the one place in the repo allowed to write tenant_id
+// directly onto kumiko_events / kumiko_snapshots / kumiko_archived_streams.
+
+import type { AnyDb } from "../query";
+import { asRawClient } from "../query";
+
+export type TransferEventRowsParams = {
+  readonly sourceTenantId: string;
+  readonly destinationTenantId: string;
+  readonly aggregateType: string;
+  readonly aggregateIds: readonly string[];
+};
+
+// Postgres' RETURNING clause has no DISTINCT keyword — dedupe the
+// per-event-row hits in-process instead of relying on invalid SQL.
+export async function transferEventRows(
+  db: AnyDb,
+  params: TransferEventRowsParams,
+): Promise<readonly string[]> {
+  const rows = (await asRawClient(db).unsafe(
+    `UPDATE "kumiko_events" SET "tenant_id" = $1 ` +
+      `WHERE "tenant_id" = $2 AND "aggregate_type" = $3 AND "aggregate_id" = ANY($4) ` +
+      `RETURNING "aggregate_id" AS id`,
+    [params.destinationTenantId, params.sourceTenantId, params.aggregateType, params.aggregateIds],
+  )) as ReadonlyArray<{ id: string }>;
+  return [...new Set(rows.map((row) => row.id))];
+}
+
+export type DeleteSnapshotsForAggregatesParams = {
+  readonly tenantId: string;
+  readonly aggregateIds: readonly string[];
+};
+
+// Snapshots are a pure read-performance cache (event-store/snapshot.ts) —
+// dropped rather than rewritten, forcing a full replay from the just-moved
+// events on next read instead of carrying the snapshot's own generation
+// bookkeeping across the tenant boundary.
+export async function deleteSnapshotsForAggregates(
+  db: AnyDb,
+  params: DeleteSnapshotsForAggregatesParams,
+): Promise<void> {
+  await asRawClient(db).unsafe(
+    `DELETE FROM "kumiko_snapshots" WHERE "tenant_id" = $1 AND "aggregate_id" = ANY($2)`,
+    [params.tenantId, params.aggregateIds],
+  );
+}
+
+export type TransferArchivedStreamRowsParams = {
+  readonly sourceTenantId: string;
+  readonly destinationTenantId: string;
+  readonly aggregateType: string;
+  readonly aggregateIds: readonly string[];
+};
+
+// An archived stream's marker must move with it — leaving it behind would
+// make the stream writable again the instant it lands in the destination
+// tenant (archive.ts's isStreamArchived check is itself tenant-scoped).
+// `aggregate_type` is part of the match, same as transferEventRows — an
+// archived marker for a DIFFERENT aggregate type that happens to share the
+// moved aggregate's id must stay in the source tenant.
+export async function transferArchivedStreamRows(
+  db: AnyDb,
+  params: TransferArchivedStreamRowsParams,
+): Promise<void> {
+  await asRawClient(db).unsafe(
+    `UPDATE "kumiko_archived_streams" SET "tenant_id" = $1 ` +
+      `WHERE "tenant_id" = $2 AND "aggregate_type" = $3 AND "aggregate_id" = ANY($4)`,
+    [params.destinationTenantId, params.sourceTenantId, params.aggregateType, params.aggregateIds],
+  );
+}

package/src/engine/__tests__/steps-webhook-send.test.ts

@@ -39,7 +39,7 @@ describe("buildWebhookSendStep", () => {
       method: "PUT",
       headers: { "X-Custom": "val" },
       body: { event: "test" },
-      auth: { kind: "bearer", secretRef: "MY_SECRET" },
+      auth: { kind: "bearer", secret: "MY_SECRET" },
       retry: { times: 5, backoff: "linear" },
       mode: "deferred",
     });
@@ -125,7 +125,7 @@ describe("webhook.send run", () => {
 
   it("passes auth config through when provided", async () => {
     const stepDef = getStep("webhook.send");
-    const auth = { kind: "bearer" as const, secretRef: "WEBHOOK_TOKEN" };
+    const auth = { kind: "bearer" as const, secret: "WEBHOOK_TOKEN" };
 
     await stepDef!.run({ url: "https://hooks.example/secured", mode: "deferred", auth }, mockCtx);
 

package/src/engine/feature-ast/__tests__/fixtures/resolve-import/alias-reexport.ts

@@ -0,0 +1 @@
+export { ORIGIN_VALUE as ALIASED } from "./origin";

package/src/engine/feature-ast/__tests__/fixtures/resolve-import/cycle-a.ts

@@ -0,0 +1 @@
+export * from "./cycle-b";

package/src/engine/feature-ast/__tests__/fixtures/resolve-import/cycle-b.ts

@@ -0,0 +1 @@
+export * from "./cycle-a";

package/src/engine/feature-ast/__tests__/fixtures/resolve-import/entry.ts

@@ -0,0 +1,3 @@
+import { ALIASED as RENAMED } from "./star-barrel";
+
+export const marker: string = RENAMED;

package/src/engine/feature-ast/__tests__/fixtures/resolve-import/local-rebind.ts

@@ -0,0 +1,3 @@
+import { ORIGIN_VALUE } from "./origin";
+
+export { ORIGIN_VALUE as LOCAL_EXPORT };

package/src/engine/feature-ast/__tests__/fixtures/resolve-import/origin.ts

@@ -0,0 +1 @@
+export const ORIGIN_VALUE = "origin-value" as const;

package/src/engine/feature-ast/__tests__/fixtures/resolve-import/star-barrel.ts

@@ -0,0 +1 @@
+export * from "./alias-reexport";

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

@@ -2799,10 +2799,10 @@ defineFeature("showpony", (r) => {
 
   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.
+    // isn't a real file, so resolveModuleFile() 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);
   });
 });

package/src/engine/feature-ast/__tests__/resolve-import.test.ts

@@ -0,0 +1,138 @@
+import { describe, expect, test } from "bun:test";
+import { resolve } from "node:path";
+import { Project, type SourceFile } from "ts-morph";
+import {
+  findImportBindingForLocalName,
+  resolveExportedVariable,
+  resolveModuleFile,
+} from "../extractors/resolve-import";
+import { parseFeatureFile, parseSourceFile } from "../parse";
+
+function loadFixture(relPath: string): SourceFile {
+  const project = new Project({
+    skipAddingFilesFromTsConfig: true,
+    skipFileDependencyResolution: true,
+  });
+  return project.addSourceFileAtPath(resolve(__dirname, relPath));
+}
+
+describe("resolveModuleFile", () => {
+  test("resolves a relative specifier to the real source file", () => {
+    const entry = loadFixture("fixtures/resolve-import/entry.ts");
+    const resolved = resolveModuleFile(entry, "./star-barrel");
+    expect(String(resolved?.getFilePath())).toBe(
+      resolve(__dirname, "fixtures/resolve-import/star-barrel.ts"),
+    );
+  });
+
+  test("returns undefined for an unresolvable package", () => {
+    const entry = loadFixture("fixtures/resolve-import/entry.ts");
+    const resolved = resolveModuleFile(entry, "@totally-unresolvable/not-a-real-package");
+    expect(resolved).toBeUndefined();
+  });
+});
+
+describe("findImportBindingForLocalName", () => {
+  test("follows an aliased named import to the module's original export name", () => {
+    const entry = loadFixture("fixtures/resolve-import/entry.ts");
+    const binding = findImportBindingForLocalName(entry, "RENAMED");
+    expect(binding).toEqual({ moduleSpecifier: "./star-barrel", importedName: "ALIASED" });
+  });
+
+  test("returns undefined for a name with no import declaration", () => {
+    const entry = loadFixture("fixtures/resolve-import/entry.ts");
+    expect(findImportBindingForLocalName(entry, "NOT_IMPORTED")).toBeUndefined();
+  });
+});
+
+describe("resolveExportedVariable", () => {
+  test("follows a cross-file aliased re-export (export { X as Y } from ...)", () => {
+    const aliasFile = loadFixture("fixtures/resolve-import/alias-reexport.ts");
+    const decl = resolveExportedVariable(aliasFile, "ALIASED");
+    expect(decl?.getName()).toBe("ORIGIN_VALUE");
+    expect(decl?.getInitializer()?.getText()).toContain("origin-value");
+  });
+
+  test("follows an export * barrel to a nested aliased re-export", () => {
+    const barrelFile = loadFixture("fixtures/resolve-import/star-barrel.ts");
+    const decl = resolveExportedVariable(barrelFile, "ALIASED");
+    expect(decl?.getName()).toBe("ORIGIN_VALUE");
+  });
+
+  test("follows a local re-export of an imported binding (import + export {} with no from)", () => {
+    const localRebindFile = loadFixture("fixtures/resolve-import/local-rebind.ts");
+    const decl = resolveExportedVariable(localRebindFile, "LOCAL_EXPORT");
+    expect(decl?.getName()).toBe("ORIGIN_VALUE");
+    expect(String(decl?.getSourceFile().getFilePath())).toBe(
+      resolve(__dirname, "fixtures/resolve-import/origin.ts"),
+    );
+  });
+
+  test("terminates instead of looping forever on a mutual export * cycle", () => {
+    const cycleFile = loadFixture("fixtures/resolve-import/cycle-a.ts");
+    const decl = resolveExportedVariable(cycleFile, "NOTHING_EXPORTED_HERE");
+    expect(decl).toBeUndefined();
+  });
+
+  test("returns undefined for a name that is never exported anywhere in the chain", () => {
+    const barrelFile = loadFixture("fixtures/resolve-import/star-barrel.ts");
+    expect(resolveExportedVariable(barrelFile, "DOES_NOT_EXIST")).toBeUndefined();
+  });
+});
+
+describe("same-file shadowing (regression for the getSymbol()/getDefinitionNodes() removal)", () => {
+  function makeSourceFile(content: string): SourceFile {
+    const project = new Project({
+      skipAddingFilesFromTsConfig: true,
+      skipFileDependencyResolution: true,
+      useInMemoryFileSystem: true,
+    });
+    return project.createSourceFile("shadow.ts", content);
+  }
+
+  test("an inner const declared inside setup() shadows a same-named outer const", () => {
+    const sf = makeSourceFile(`
+import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+
+const NAME = "outer";
+
+defineFeature("f", (r) => {
+  const NAME = "inner";
+  r.extendsRegistrar(NAME, {});
+});
+`);
+    const result = parseSourceFile(sf);
+    expect(result.errors).toEqual([]);
+    expect(result.patterns).toMatchObject([{ kind: "extendsRegistrar", extensionName: "inner" }]);
+  });
+
+  test("a function parameter shadowing an outer const yields an unresolvable reference, not the outer value", () => {
+    const sf = makeSourceFile(`
+import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+
+const NAME = "outer";
+
+defineFeature("f", (r) => {
+  function wrap(NAME) {
+    r.extendsRegistrar(NAME, {});
+  }
+  wrap("shadowed-by-param");
+});
+`);
+    const result = parseSourceFile(sf);
+    expect(result.patterns).toEqual([]);
+    expect(result.errors).toEqual([expect.objectContaining({ methodName: "extendsRegistrar" })]);
+  });
+});
+
+describe("parseFeatureFile resolves cross-file constants without a Program", () => {
+  test("sessions' imported event-name constant resolves to its real value", () => {
+    const result = parseFeatureFile(
+      resolve(__dirname, "../../../../../bundled-features/src/sessions/feature.ts"),
+    );
+    const defineEvent = result.patterns.find((p) => p.kind === "defineEvent");
+    // SESSION_REVOKED_EVENT_SHORT is imported from ./session-revoked-event —
+    // only resolves through the cross-file resolver this change replaces.
+    expect(defineEvent).toMatchObject({ eventName: "session-revoked" });
+  });
+});

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

@@ -35,6 +35,10 @@ export {
   readApplyBodies,
   readScreenStatic,
 } from "./projections-screens";
+export {
+  findImportBindingForLocalName,
+  resolveModuleFile,
+} from "./resolve-import";
 export {
   extractDescribe,
   extractOptionalRequires,