@cosmicdrift/kumiko-framework 0.234.0 → 0.235.1

package/src/jobs/__tests__/jobs.integration.test.ts

@@ -15,6 +15,7 @@ import { createInMemoryFileProvider } from "../../files/in-memory-provider";
 import { createTestRedis, type TestRedis, TestUsers } from "../../stack";
 import { sleep, waitFor } from "../../testing";
 import {
+  bootJobIdForJobName,
   createJobRunner,
   type JobLogEntry,
   type JobMeta,
@@ -1222,3 +1223,129 @@ describe("job registry", () => {
     expect(job?.runOnBoot).toBe(true);
   });
 });
+
+// --- Boot gates: only an inline gate can abort a boot (fw#2590) ---
+
+describe("boot gates", () => {
+  const gateLog: string[] = [];
+  const GATE_FAILURE = "required legal blocks are not seeded";
+
+  function uniquePrefix(): string {
+    return `kumiko-gate-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+  }
+
+  function createGateRunner(
+    feature: ReturnType<typeof defineFeature>,
+    queueNamePrefix: string,
+  ): JobRunner {
+    const context: AppContext = {};
+    return createJobRunner({
+      registry: createRegistry([feature]),
+      context,
+      redisUrl,
+      consumerLane: "worker",
+      queueNamePrefix,
+    });
+  }
+
+  async function purge(queueNamePrefix: string): Promise<void> {
+    const keys = await testRedis.redis.keys(`bull:${queueNamePrefix}-worker:*`);
+    if (keys.length > 0) await testRedis.redis.del(...keys);
+  }
+
+  test("a throwing gate rejects start() and stops the remaining boot wiring", async () => {
+    const feature = defineFeature("failgate", (r) => {
+      r.job("check", { trigger: { manual: true }, bootGate: true }, async () => {
+        throw new Error(GATE_FAILURE);
+      });
+      r.job("afterGate", { trigger: { manual: true }, runOnBoot: true }, async () => {
+        gateLog.push("after-gate");
+      });
+    });
+    const prefix = uniquePrefix();
+    const runner = createGateRunner(feature, prefix);
+    gateLog.length = 0;
+
+    // Pin the qualified name the boot-job-id assertion below is built on —
+    // a typo there would make that assertion pass vacuously.
+    const afterGateName = "failgate:job:after-gate";
+    expect(createRegistry([feature]).getJob(afterGateName)).toBeDefined();
+
+    const queue = new Queue(`${prefix}-worker`, {
+      connection: { host: testRedis.redis.options.host, port: testRedis.redis.options.port },
+    });
+    // A post-close 'error' here is otherwise unhandled and bun:test
+    // attributes it to whichever test runs next (fw#1805).
+    queue.on("error", () => {});
+
+    try {
+      // The gate's own message must survive — which blocks are missing is the
+      // entire operational value, and onJobFailed runs before the re-throw.
+      await expect(runner.start()).rejects.toThrow(GATE_FAILURE);
+      await sleep(300);
+      // The gate aborted start() before any further boot wiring ran: the
+      // runOnBoot job was never even enqueued, and never executed.
+      const bootJob = await queue.getJob(bootJobIdForJobName(afterGateName));
+      expect(bootJob).toBeUndefined();
+      expect(gateLog).toEqual([]);
+    } finally {
+      await queue.close();
+      await runner.stop();
+      await purge(prefix);
+    }
+  });
+
+  test("a gate runs on every start, unlike a deduped runOnBoot job", async () => {
+    const feature = defineFeature("everygate", (r) => {
+      r.job("check", { trigger: { manual: true }, bootGate: true }, async () => {
+        gateLog.push("gate");
+      });
+      r.job("once", { trigger: { manual: true }, runOnBoot: true }, async () => {
+        gateLog.push("boot");
+      });
+    });
+    const prefix = uniquePrefix();
+    gateLog.length = 0;
+
+    const first = createGateRunner(feature, prefix);
+    await first.start();
+    await waitFor(() => {
+      expect(gateLog.filter((e) => e === "boot").length).toBe(1);
+    });
+    await first.stop();
+
+    const second = createGateRunner(feature, prefix);
+    try {
+      await second.start();
+      await sleep(300);
+      expect(gateLog.filter((e) => e === "gate").length).toBe(2);
+      // Same fixed boot job id, still present in Redis from the first start,
+      // so BullMQ drops the second enqueue — that dedup is why runOnBoot
+      // cannot gate a deploy.
+      expect(gateLog.filter((e) => e === "boot").length).toBe(1);
+    } finally {
+      await second.stop();
+      await purge(prefix);
+    }
+  });
+
+  test("bootGate is rejected for perTenant and sequential jobs", () => {
+    const perTenantGate = defineFeature("pergate", (r) => {
+      r.job("check", { trigger: { manual: true }, bootGate: true, perTenant: true }, async () => {
+        gateLog.push("never");
+      });
+    });
+    expect(() => createRegistry([perTenantGate])).toThrow(/bootGate with perTenant/);
+
+    const sequentialGate = defineFeature("seqgate", (r) => {
+      r.job(
+        "check",
+        { trigger: { manual: true }, bootGate: true, concurrency: "sequential" },
+        async () => {
+          gateLog.push("never");
+        },
+      );
+    });
+    expect(() => createRegistry([sequentialGate])).toThrow(/bootGate with concurrency/);
+  });
+});

package/src/jobs/job-runner.ts

@@ -1,4 +1,4 @@
-import { type Job, Queue, Worker } from "bullmq";
+import { Queue, Worker } from "bullmq";
 import { Redis } from "ioredis";
 import { requestContext } from "../api/request-context";
 import type { DbConnection, DbRow } from "../db/connection";
@@ -395,7 +395,17 @@ export function createJobRunner(options: JobRunnerOptions): JobRunner {
     return false;
   }
 
-  async function handleJob(bullJob: Job): Promise<void> {
+  // Structural instead of BullMQ's `Job` so boot gates can invoke the same
+  // execution path inline. A real `Job` stays assignable, so handleJob is
+  // still a valid BullMQ Processor.
+  type JobInvocation = {
+    readonly id?: string | undefined;
+    readonly name: string;
+    readonly data: Record<string, unknown>;
+    readonly attemptsMade: number;
+  };
+
+  async function handleJob(bullJob: JobInvocation): Promise<void> {
     const rawName = bullJob.name;
 
     // Handle perTenant dispatch jobs — fan out to one job per tenant. The
@@ -651,6 +661,27 @@ export function createJobRunner(options: JobRunnerOptions): JobRunner {
     }
   }
 
+  // Boot gates run inline and are awaited, so a throwing gate rejects start()
+  // — and with it the entrypoint's start() and runProdApp's boot, before the
+  // process reports ready. Enqueuing them (as runOnBoot does) would only fail
+  // a queue job and let the deploy through (fw#2590).
+  async function runBootGates(lane: JobRunIn): Promise<void> {
+    for (const [name, jobDef] of allJobs) {
+      if (laneForJob(jobDef) !== lane) continue;
+      if (!jobDef.bootGate) continue;
+      try {
+        await handleJob({ id: bootJobIdForJobName(name), name, data: {}, attemptsMade: 0 });
+      } catch (err) {
+        // The worker is already consuming here; leaving its Redis connections
+        // open would keep the event loop alive and turn the aborted boot into
+        // a hanging process instead of a non-zero exit.
+        await worker?.close();
+        worker = null;
+        throw err;
+      }
+    }
+  }
+
   const runnerApi: JobRunner = {
     async start(): Promise<void> {
       // skip: enqueuer-only runner — no BullMQ worker, no cron schedules,
@@ -689,6 +720,10 @@ export function createJobRunner(options: JobRunnerOptions): JobRunner {
         bootTimeout.cancel();
       }
 
+      // Ahead of cron/runOnBoot wiring on purpose: a failed gate must not
+      // leave recurring schedulers behind.
+      await runBootGates(consumerLane);
+
       // Only schedule cron + boot for jobs that belong to this lane. Jobs
       // assigned to the other lane get their cron/boot wiring from the
       // runner running on that lane. Running both here would double-fire.

package/src/pipeline/__tests__/event-dispatcher-start-from.integration.test.ts

@@ -0,0 +1,176 @@
+// EventConsumer.startFrom — opt-in cursor seed on FIRST registration
+// (fw#2482/1). Mounting a NEW consumer into an app whose event log is
+// already populated must not replay history and fire every side-effect
+// step retroactively.
+//
+// setupTestStack's own dispatcher pre-registers every consumer eagerly at
+// stack construction time (test-stack.ts: "Pre-register consumer state
+// rows..."), before any test body can seed historical events — so it can't
+// reproduce "mount into an already-running app" the way this fix needs.
+// This test instead builds its own EventDispatcher via createEventDispatcher()
+// against a plain createTestDb(), and only calls ensureRegistered() AFTER
+// historical events already exist — the same order a real deploy of a new
+// event-triggered workflow hits in production.
+
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import type { DbTx } from "../../db/connection";
+import { insertOne } from "../../db/query";
+import type { AppContext } from "../../engine/types";
+import { eventsTable } from "../../event-store";
+import { createTestDb, type TestDb, TestUsers } from "../../stack";
+import { createEventConsumerStateTable } from "../event-consumer-state";
+import { createEventDispatcher, type EventConsumer, getConsumerState } from "../event-dispatcher";
+import { fetchPendingEvents } from "../event-dispatcher-delivery";
+
+const admin = TestUsers.admin;
+let testDb: TestDb;
+let historicalEventCount = 0;
+
+function stubContext(): AppContext {
+  return {
+    db: {} as unknown as AppContext["db"],
+    redis: {} as unknown as AppContext["redis"],
+    registry: {} as unknown as AppContext["registry"],
+  } as AppContext;
+}
+
+async function appendHistoricalEvent(type: string): Promise<void> {
+  await insertOne(testDb.db, eventsTable, {
+    aggregateId: crypto.randomUUID(),
+    aggregateType: "start-from-test-source",
+    tenantId: admin.tenantId,
+    version: 1,
+    type,
+    eventVersion: 1,
+    payload: {},
+    metadata: { userId: admin.id },
+    createdBy: admin.id,
+  });
+  historicalEventCount += 1;
+}
+
+beforeAll(async () => {
+  // createTestDb() already materializes kumiko_events (see stack/db.ts).
+  testDb = await createTestDb();
+  await createEventConsumerStateTable(testDb.db);
+});
+
+afterAll(async () => {
+  await testDb.cleanup();
+});
+
+describe("EventConsumer.startFrom", () => {
+  test("'now' seeds the cursor at MAX(events.id) on first registration and skips the historical log", async () => {
+    await appendHistoricalEvent("start-from-test.one");
+    await appendHistoricalEvent("start-from-test.two");
+    await appendHistoricalEvent("start-from-test.three");
+    const headAtMount = BigInt(historicalEventCount);
+
+    const captured: string[] = [];
+    const consumer: EventConsumer = {
+      name: "test:consumer:mounted-now",
+      startFrom: "now",
+      handler: async (event) => {
+        captured.push(event.type);
+      },
+    };
+
+    // Mirrors mounting a new event-triggered workflow into a production app
+    // that already has a populated event log: the dispatcher (and its
+    // consumer) is only constructed AFTER the historical events above exist.
+    const dispatcher = createEventDispatcher({
+      db: testDb.db,
+      consumers: [consumer],
+      context: stubContext(),
+    });
+    await dispatcher.ensureRegistered();
+
+    const state = await getConsumerState(testDb.db, consumer.name);
+    expect(state?.lastProcessedEventId).toBe(headAtMount);
+    expect(state?.status).toBe("idle");
+
+    const result = await dispatcher.runOnce();
+    expect(result.byConsumer[consumer.name]).toEqual({ processed: 0, failed: 0 });
+    expect(captured).toHaveLength(0);
+
+    // Not just "not delivered" — proves the id > cursor contract directly:
+    // no historical row is even fetched on the first pass.
+    await testDb.db.begin(async (tx: DbTx) => {
+      const pending = await fetchPendingEvents(tx, headAtMount, 100);
+      expect(pending).toHaveLength(0);
+    });
+  });
+
+  test("without startFrom (default 'beginning') a freshly-registered consumer replays the full historical log", async () => {
+    await appendHistoricalEvent("start-from-test.four");
+    await appendHistoricalEvent("start-from-test.five");
+    const expectedReplayCount = historicalEventCount;
+
+    const captured: string[] = [];
+    const consumer: EventConsumer = {
+      name: "test:consumer:mounted-beginning",
+      handler: async (event) => {
+        captured.push(event.type);
+      },
+    };
+
+    const dispatcher = createEventDispatcher({
+      db: testDb.db,
+      consumers: [consumer],
+      context: stubContext(),
+    });
+    await dispatcher.ensureRegistered();
+
+    const stateBefore = await getConsumerState(testDb.db, consumer.name);
+    expect(stateBefore?.lastProcessedEventId).toBe(0n);
+
+    const result = await dispatcher.runOnce();
+    expect(result.byConsumer[consumer.name]).toEqual({ processed: expectedReplayCount, failed: 0 });
+    expect(captured).toEqual([
+      "start-from-test.one",
+      "start-from-test.two",
+      "start-from-test.three",
+      "start-from-test.four",
+      "start-from-test.five",
+    ]);
+  });
+
+  test("re-registering an already-registered consumer never clobbers an advanced cursor", async () => {
+    const consumer: EventConsumer = {
+      name: "test:consumer:advanced-then-remounted",
+      startFrom: "now",
+      handler: async () => {},
+    };
+
+    const dispatcher = createEventDispatcher({
+      db: testDb.db,
+      consumers: [consumer],
+      context: stubContext(),
+    });
+    await dispatcher.ensureRegistered();
+    const seeded = await getConsumerState(testDb.db, consumer.name);
+    expect(seeded?.lastProcessedEventId).toBe(BigInt(historicalEventCount));
+
+    await appendHistoricalEvent("start-from-test.six");
+    await dispatcher.runOnce();
+    const advanced = await getConsumerState(testDb.db, consumer.name);
+    expect(advanced?.lastProcessedEventId).toBe(BigInt(historicalEventCount));
+
+    // A new historical event exists again, not yet consumed by this consumer.
+    await appendHistoricalEvent("start-from-test.seven");
+
+    // A second dispatcher instance for the SAME consumer name simulates a
+    // process restart re-running the boot-time pre-registration — the row
+    // already exists, so ON CONFLICT DO NOTHING must leave its advanced
+    // cursor untouched, not reseed it at the new (higher) MAX(events.id).
+    const redeployedDispatcher = createEventDispatcher({
+      db: testDb.db,
+      consumers: [consumer],
+      context: stubContext(),
+    });
+    await redeployedDispatcher.ensureRegistered();
+
+    const afterRedeploy = await getConsumerState(testDb.db, consumer.name);
+    expect(afterRedeploy?.lastProcessedEventId).toBe(advanced?.lastProcessedEventId);
+  });
+});

package/src/pipeline/event-dispatcher-delivery.ts

@@ -155,7 +155,7 @@ export async function preRegisterConsumers(
 ): Promise<void> {
   for (const consumer of consumers) {
     const instanceId = consumerInstanceId(consumer, dispatcherInstanceId);
-    await insertConsumerIfAbsent(db, consumer.name, instanceId);
+    await insertConsumerIfAbsent(db, consumer.name, instanceId, consumer.startFrom);
   }
 }
 

package/src/pipeline/event-dispatcher.ts

@@ -94,6 +94,12 @@ export type EventConsumer = {
   //                   respect to shared storage (no DB writes), otherwise
   //                   each instance duplicates the effect.
   readonly delivery?: "shared" | "per-instance";
+  // Where the consumer's cursor starts on its FIRST registration. Default
+  // "beginning" replays the full log. "now" seeds the cursor at the current
+  // MAX(events.id) so mounting the consumer into an existing app does not
+  // retroactively fire side effects for historical events. Only affects the
+  // first registration — an existing cursor row is never clobbered.
+  readonly startFrom?: "beginning" | "now";
 };
 
 // Result of a dispatcher pass (runOnce / doPass). Shared across the public

package/src/pipeline/multi-stream-apply-context.ts

@@ -11,10 +11,10 @@ export type { MultiStreamApplyContext } from "@cosmicdrift/kumiko-types/multi-st
 
 export type MultiStreamApplyContextDeps = {
   readonly registry: Registry;
-  // TX-scoped DbRunner — the same `tx` the applyFn receives as the 2nd
-  // arg. ctx.appendEvent + inline-projections run inside this tx so a
-  // throw rolls the whole hop back (consumer retries the triggering
-  // event on the next pass).
+  // Same DbRunner the applyFn receives as its 2nd arg. In the server's MSP
+  // consumer wiring (api/server.ts) that's the unbound pool, not the
+  // dispatcher's cursor tx — a throw does NOT roll back appends/inline
+  // projections already made; apply must be idempotent for the retry.
   readonly db: DbRunner;
   // tenantId + userId of the TRIGGERING event. appendEvent stamps these
   // onto the new event so the causal chain stays tenant-consistent and

package/src/scripts/codemod/unprocessable-error-details-reason.ts

@@ -0,0 +1,273 @@
+#!/usr/bin/env bun
+// `UnprocessableOpts.details` was tightened (fw#2460) to `& { readonly reason?:
+// never }` — `reason` is owned exclusively by the ctor's first positional
+// argument, which already folds it into `details` internally
+// (`{ ...opts?.details, reason }`). Any consumer that ALSO puts `reason`
+// inside its `details` object literal now fails with TS2322. This codemod
+// removes that redundant `reason` property; the value is never lost, it was
+// already duplicated from the positional argument.
+//
+// Usage: bun scripts/codemod/unprocessable-error-details-reason.ts <targetDir> [--dry-run]
+
+import { type Dirent, readdirSync } from "node:fs";
+import { join, relative, resolve } from "node:path";
+import {
+  type Identifier,
+  Node,
+  type ObjectLiteralExpression,
+  Project,
+  type SourceFile,
+  SyntaxKind,
+} from "ts-morph";
+
+const EXCLUDE_DIRS = new Set(["node_modules", "dist", "build"]);
+const KUMIKO_MODULE_RE = /^@cosmicdrift\/kumiko-/;
+
+function findTargetFiles(rootDir: string): string[] {
+  // Walk the tree and skip excluded dirs while descending — filtering the
+  // absolute path after a full scan silently no-ops when the repo root
+  // itself contains "/build/" or "/node_modules/" (fw#2289).
+  const files: string[] = [];
+  const walk = (dir: string): void => {
+    let entries: Dirent[];
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      // skip: unreadable directory during walk — treat as empty.
+      return;
+    }
+    for (const ent of entries) {
+      if (ent.isDirectory()) {
+        if (EXCLUDE_DIRS.has(ent.name) || ent.name.startsWith(".")) continue;
+        walk(join(dir, ent.name));
+        continue;
+      }
+      if (ent.isFile() && /\.(ts|tsx)$/.test(ent.name)) {
+        files.push(join(dir, ent.name));
+      }
+    }
+  };
+  walk(rootDir);
+  return files.sort();
+}
+
+type ImportedBinding = { readonly importedName: string; readonly moduleSpecifier: string };
+
+/** Local-name -> where it's imported from, for every named value import in the file. */
+function collectImportedNames(sourceFile: SourceFile): Map<string, ImportedBinding> {
+  const bindings = new Map<string, ImportedBinding>();
+  for (const imp of sourceFile.getImportDeclarations()) {
+    if (imp.isTypeOnly()) continue;
+    const moduleSpecifier = imp.getModuleSpecifierValue();
+    for (const spec of imp.getNamedImports()) {
+      if (spec.isTypeOnly()) continue;
+      const importedName = spec.getName();
+      const localName = spec.getAliasNode()?.getText() ?? importedName;
+      bindings.set(localName, { importedName, moduleSpecifier });
+    }
+  }
+  return bindings;
+}
+
+type DetailsResolution =
+  | { readonly kind: "object-literal"; readonly literal: ObjectLiteralExpression }
+  | { readonly kind: "unresolvable"; readonly note: string }
+  | { readonly kind: "absent" };
+
+/** Resolves `opts.details` to a statically-inspectable object literal, or explains why it can't be. */
+function resolveDetailsProperty(optsLiteral: ObjectLiteralExpression): DetailsResolution {
+  const prop = optsLiteral.getProperty("details");
+  if (!prop) return { kind: "absent" };
+
+  if (Node.isShorthandPropertyAssignment(prop)) {
+    return { kind: "unresolvable", note: "details is a shorthand property (a variable)" };
+  }
+  if (!Node.isPropertyAssignment(prop)) {
+    return { kind: "unresolvable", note: "details is not a plain property assignment" };
+  }
+  if (Node.isComputedPropertyName(prop.getNameNode())) {
+    return { kind: "unresolvable", note: "details key is computed" };
+  }
+  const init = prop.getInitializer();
+  if (!init) return { kind: "unresolvable", note: "details has no initializer" };
+  if (Node.isObjectLiteralExpression(init)) return { kind: "object-literal", literal: init };
+
+  const note = Node.isIdentifier(init)
+    ? `details is a variable ("${init.getText()}")`
+    : Node.isCallExpression(init)
+      ? "details is a call-expression result"
+      : Node.isConditionalExpression(init)
+        ? "details is a conditional expression"
+        : `details is not a statically-analyzable object literal (${init.getKindName()})`;
+  return { kind: "unresolvable", note };
+}
+
+/** True if removing this shorthand-bound identifier would leave its declaration with no other use. */
+function wouldLeaveUnusedVariable(nameNode: Identifier): boolean {
+  try {
+    const refs = nameNode.findReferencesAsNodes();
+    const others = refs.filter((r) => r !== nameNode);
+    return others.length === 0;
+  } catch {
+    // Can't verify — treat as unsafe rather than guess.
+    return true;
+  }
+}
+
+type RemovalResult =
+  | { readonly kind: "removed" }
+  | { readonly kind: "absent" }
+  | { readonly kind: "skip"; readonly note: string };
+
+/** Removes the `reason` property from a `details` object literal, in place. */
+function removeReasonProperty(detailsLiteral: ObjectLiteralExpression): RemovalResult {
+  const properties = detailsLiteral.getProperties();
+  if (properties.some((p) => Node.isSpreadAssignment(p))) {
+    return {
+      kind: "skip",
+      note: "details object literal contains a spread — not statically decidable",
+    };
+  }
+
+  for (const prop of properties) {
+    if (Node.isPropertyAssignment(prop)) {
+      const nameNode = prop.getNameNode();
+      if (Node.isComputedPropertyName(nameNode)) {
+        const expr = nameNode.getExpression();
+        if (Node.isStringLiteral(expr) && expr.getLiteralText() === "reason") {
+          return { kind: "skip", note: "reason key is computed — not safe to remove mechanically" };
+        }
+        continue;
+      }
+      const propName = Node.isIdentifier(nameNode)
+        ? nameNode.getText()
+        : Node.isStringLiteral(nameNode)
+          ? nameNode.getLiteralText()
+          : undefined;
+      if (propName === "reason") {
+        prop.remove();
+        return { kind: "removed" };
+      }
+      continue;
+    }
+    if (Node.isShorthandPropertyAssignment(prop) && prop.getName() === "reason") {
+      if (wouldLeaveUnusedVariable(prop.getNameNode())) {
+        return {
+          kind: "skip",
+          note: "reason is a shorthand property; removing it would leave the bound variable unused",
+        };
+      }
+      prop.remove();
+      return { kind: "removed" };
+    }
+  }
+  return { kind: "absent" };
+}
+
+type CallOutcome = "changed" | "skipped" | "not-a-match";
+
+function processNewExpression(args: readonly Node[], report: (note: string) => void): CallOutcome {
+  const optsArg = args[1];
+  if (!optsArg) return "not-a-match";
+
+  if (!Node.isObjectLiteralExpression(optsArg)) {
+    report(
+      "second argument (opts) is not a statically-analyzable object literal — cannot verify details.reason",
+    );
+    return "skipped";
+  }
+
+  const detailsRes = resolveDetailsProperty(optsArg);
+  if (detailsRes.kind === "absent") return "not-a-match";
+  if (detailsRes.kind === "unresolvable") {
+    report(detailsRes.note);
+    return "skipped";
+  }
+
+  const removal = removeReasonProperty(detailsRes.literal);
+  if (removal.kind === "absent") return "not-a-match";
+  if (removal.kind === "skip") {
+    report(removal.note);
+    return "skipped";
+  }
+  return "changed";
+}
+
+type SkipEntry = { readonly file: string; readonly line: number; readonly note: string };
+
+/** Migrates one file in place. Returns how many `reason` properties were removed. */
+function migrateFile(sourceFile: SourceFile, skips: SkipEntry[]): number {
+  const importedNames = collectImportedNames(sourceFile);
+  let removedCount = 0;
+
+  for (const newExpr of sourceFile.getDescendantsOfKind(SyntaxKind.NewExpression)) {
+    const callee = newExpr.getExpression();
+    if (!Node.isIdentifier(callee)) continue;
+    const localName = callee.getText();
+
+    const binding = importedNames.get(localName);
+    const isFrameworkUnprocessableError = binding?.importedName === "UnprocessableError";
+
+    if (!isFrameworkUnprocessableError) {
+      if (localName !== "UnprocessableError") continue;
+      const note = binding
+        ? `UnprocessableError is imported from "${binding.moduleSpecifier}", not a @cosmicdrift/kumiko-* package`
+        : "UnprocessableError has no @cosmicdrift/kumiko-* import in this file (likely a locally defined class)";
+      skips.push({ file: sourceFile.getFilePath(), line: newExpr.getStartLineNumber(), note });
+      continue;
+    }
+    if (!KUMIKO_MODULE_RE.test(binding.moduleSpecifier)) {
+      skips.push({
+        file: sourceFile.getFilePath(),
+        line: newExpr.getStartLineNumber(),
+        note: `UnprocessableError is imported from "${binding.moduleSpecifier}", not a @cosmicdrift/kumiko-* package`,
+      });
+      continue;
+    }
+
+    const outcome = processNewExpression(newExpr.getArguments(), (note) => {
+      skips.push({ file: sourceFile.getFilePath(), line: newExpr.getStartLineNumber(), note });
+    });
+    if (outcome === "changed") removedCount++;
+  }
+
+  return removedCount;
+}
+
+async function main(): Promise<void> {
+  const positional = process.argv.slice(2).filter((a) => !a.startsWith("--"));
+  const dryRun = process.argv.includes("--dry-run");
+  const rootDir = resolve(positional[0] ?? process.cwd());
+
+  const files = findTargetFiles(rootDir);
+  const project = new Project({
+    skipAddingFilesFromTsConfig: true,
+    skipFileDependencyResolution: true,
+  });
+
+  let touchedFiles = 0;
+  let removedTotal = 0;
+  const skips: SkipEntry[] = [];
+
+  for (const file of files) {
+    const sourceFile = project.addSourceFileAtPath(file);
+    const removed = migrateFile(sourceFile, skips);
+    if (removed === 0) continue;
+
+    touchedFiles++;
+    removedTotal += removed;
+    if (!dryRun) sourceFile.saveSync();
+  }
+
+  console.log(`\nScanned ${files.length} files under ${rootDir}${dryRun ? " (dry-run)" : ""}.`);
+  console.log(
+    `Touched ${touchedFiles} files, removed ${removedTotal} redundant "reason" propert(y/ies).`,
+  );
+  console.log(`Skipped ${skips.length} site(s):`);
+  for (const s of skips) {
+    console.log(`  ${relative(rootDir, s.file)}:${s.line} — ${s.note}`);
+  }
+  console.log();
+}
+
+await main();