@cosmicdrift/kumiko-framework 0.387.0 → 0.388.0

package/src/changes.json

@@ -1,4 +1,314 @@
 [
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "runProdApp passes errorDocs and instanceId to the server",
+    "detail": "ApiEntrypointOptions now carries errorDocs and instanceId and createApiEntrypoint forwards them to the server. Before, runProdApp dropped its errorDocs option, and a KUMIKO_INSTANCE_ID set only in a custom envSource never reached the server, which fell back to process.env. The boot-abort cleanup of runProdApp also moved into a helper that swallows synchronously throwing cleanups."
+  },
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "Physical-table collisions use the DDL table name",
+    "detail": "createRegistry compared entity tables under a feature-prefixed name that no DDL path creates, so an entity whose explicit table equals another feature's derived table name, or two entities with the same explicit table in different features, registered fine and then emitted the same CREATE TABLE twice. The check now uses the unprefixed physical name, the same as the store-table check and the migrate runner.",
+    "migration": "Apps where two entities share a physical table name fail at boot with \"has physical table ... which collides with entity ...\". Give one of them a different `table`."
+  },
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "Worker entrypoint takes instanceId",
+    "detail": "WorkerEntrypointOptions now carries instanceId (moved to BaseEntrypointOptions, so the API and all-in-one options keep it) and createWorkerEntrypoint forwards it to the server. runWorkerApp reads KUMIKO_INSTANCE_ID from its envSource like runProdApp, so with KUMIKO_INSTANCE_ID set, per-instance consumers in the worker and its app.started event use the same id. Before, the worker server only saw process.env."
+  },
+  {
+    "version": "0.388.0",
+    "type": "improvement",
+    "title": "PII, retention and cascade-delete rules as tables, English dev messages",
+    "detail": "validatePiiAndRetention runs one checker per rule in a fixed order, and the cascade-delete hook dispatches each relation through a table of onDelete strategies. Error and warning texts, their order, transaction boundaries and event order are unchanged. buildAppSchema forwards field properties through an ordered table, and kumiko-upgrade and the pii-personal-migration codemod run one function per step; their output is byte-identical. The dev warnings of normalizeListColumn and buildAppSchema are now English."
+  },
+  {
+    "version": "0.388.0",
+    "type": "improvement",
+    "title": "Named steps for list reads, field columns, table metadata and table diffs",
+    "detail": "The list read verb runs search, sort, cursor boundary, filters, stream-version projection, row rehydration and the next cursor as named steps in their own files next to event-store-executor-read.ts, and detail() shares the ownership and row rehydration steps. Field columns come from one emitter per field type in a typed table, so a new field type fails the typecheck until it has an emitter, and an unknown type from untyped input still throws \"unhandled field type\". deriveEntityTableMeta collects columns, foreign-key, blind-index and declared indexes in separate steps with the same overloads and error texts. diffOneTable compares columns and indexes through one comparator per kind and keeps the order of added, dropped and changed entries."
+  },
+  {
+    "version": "0.388.0",
+    "type": "improvement",
+    "title": "Per-kind tables for feature-AST id matching, editability and rendering",
+    "detail": "callMatchesId() looks up one matcher per PatternId kind in a typed table in feature-ast/pattern-id-matchers.ts next to patch.ts. getEditability() reads a table keyed by pattern kind, and renderPattern() dispatches through one renderer per pattern kind. All three tables are typed over their kind union, so a new kind does not compile until it has an entry. The feature-ast barrel exports the same names as before."
+  },
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "Boot enforces the projection allowlist",
+    "detail": "The projection allowlist validator existed but was never called from validateBoot. It now runs as the last cross-feature check. It also keys aggregate tables by the physical table name (entity.table or the derived read_* name) instead of the entity name, so unsafeProjection steps on the table of an entity without an explicit table, and duplicate tables between a derived and an explicit name, are detected.",
+    "migration": "Apps with such violations fail at boot. Add the missing r.requires.projection or r.requires.step declaration, or use r.step.aggregate.* for aggregate tables."
+  },
+  {
+    "version": "0.388.0",
+    "type": "improvement",
+    "title": "Recipe for Input kind \"code\" in a confirmation step",
+    "detail": "samples/recipes/auth-mfa has a ConfirmationCodeStep for e-mail or invite codes that uses Input kind \"code\" with length, autoFocus and onComplete, clears and refocuses after a rejected code, and has a DOM test. The agent example for auth-mfa includes it."
+  },
+  {
+    "version": "0.388.0",
+    "type": "improvement",
+    "title": "Groups and sums on the entity list query",
+    "detail": "Pass aggregate with an optional groupBy field and up to 20 measures (sum, avg, count, min, max per field) to a list query. The answer is groups with key, count, one value per measure in request order and, for a reference groupBy, the label of the referenced row. Screen filters, search, ownership and field read access apply exactly as for rows; a field the caller may not read yields null or no groups, and encrypted, personal or secret fields and unsuitable field types are rejected with a validation error. At most 200 groups are returned, with truncated set beyond that. Custom query handlers use executor.aggregate or answerListAggregate."
+  },
+  {
+    "version": "0.388.0",
+    "type": "improvement",
+    "title": "buildServer split into middleware installers and route mounters",
+    "detail": "buildServer() keeps its signature and behavior. Boot checks, pre-app wiring, the event dispatcher, middleware installers and route mounters now live in server-*.ts files next to server.ts. withFileProviderResolver and makeDispatchSystemWrite/makeDispatchWriteAs/makeDispatchSystemQuery are still exported from the api barrel under the same names."
+  },
+  {
+    "version": "0.388.0",
+    "type": "improvement",
+    "title": "Where-clause emitters, coercer table and named write steps",
+    "detail": "buildWhereClause() now dispatches through one emitter per WhereOperator key in a typed table, and coerceDriverRow() looks up one coercer per pgType. Table introspection, value preparation, row coercion, closed-connection handling and aggregate SQL live in their own files next to db/query.ts. The create and update write verbs run preSave, field and ownership checks, the record-lock guard, select-option checks, the version check, the append and the projection as named steps. The db barrel exports the same names as before."
+  },
+  {
+    "version": "0.388.0",
+    "type": "improvement",
+    "title": "Job runner run path split into named steps",
+    "detail": "handleJob() in jobs/job-runner.ts now composes the perTenant fan-out, the unknown-job check, the maxPerTenant defer gate and the sequential lock (job-runner-gates.ts), the run context with its db, service and dispatch facets (job-runner-context.ts), the job.execute span with success and failure recording (job-runner-execution.ts) and the handler deferral. The runner's shared state travels in one scope object (job-runner-scope.ts). The jobs barrel exports the same names as before. New integration tests cover unknown jobs taken from the queue, a perTenant wrapper for an unknown job, a perTenant job without a tenant resolver and ctx.defer with a non-positive delay."
+  },
+  {
+    "version": "0.388.0",
+    "type": "improvement",
+    "title": "Handler context and write pipeline split into named steps",
+    "detail": "buildHandlerContext() in pipeline/dispatch-shared.ts now composes one builder per facet of the flat HandlerContext: the shared scope (handler-context-scope.ts), the tenant-scoped db handles, forTenant and file contexts (handler-context-db.ts), the commit sinks with ctx.query/write/queryAs/writeAs and nested writes in savepoints (handler-context-dispatch.ts), ctx.notify (handler-context-notify.ts), config, configFor, tz and locale (handler-context-config.ts), the event store surfaces and ctx.queryProjection (handler-context-events.ts), the identity-gated auth surfaces and ctx.hasFeature (handler-context-auth.ts) and log, tracer and metrics (handler-context-observability.ts). executeWriteInner() in pipeline/dispatch-write.ts runs the entry checks, the pre-handler gates with the reservation, the transition guard, the handler call and the settle step with reservation confirm, lifecycle and after-commit hooks as separate functions; executeNestedWrite() checks the nested foreign keys, verifies the parent row and writes the children in their own steps. Public exports are unchanged. New tests cover the ctx.snapshotAggregate/ctx.loadAggregateWithSnapshot roundtrip with tenant isolation and the no-database error text of the event store surfaces."
+  },
+  {
+    "version": "0.388.0",
+    "type": "improvement",
+    "title": "kumiko-schema output in English, schema CLI and screen key collection split per kind",
+    "detail": "Visible change: kumiko-schema (and the dev `kumiko schema` command) now prints \"is missing\", \"App convention\", \"No schema changes detected — no new migration file written.\", \"Review, hand-edit if needed, then git add + commit.\", \"is missing — run schema generate <name> first.\", \"No kumiko/migrations/ — the app is still on the legacy drizzle path.\", \"Unknown subcommand\" / \"Allowed\", \"must declare `export const ENTITY_METAS: EntityTableMeta[]`\" and an English help text instead of the German lines. The standalone `kumiko schema apply` of production bundles prints \"Creating framework infrastructure tables (idempotent)…\", \"Applying kumiko migrations (…)…\", \"… is missing — kumiko/migrations/ must be part of the image.\" and \"Unknown command: kumiko … / The standalone bundle only supports 'kumiko schema apply'.\". Scripts that matched the German text need the English one. Exit codes, the order of the output lines and which lines go to stderr are unchanged. runSchemaCli() keeps its signature; each subcommand lives in its own file under schema-cli/. requiredKeysFromScreen() returns the same keys in the same order; a screen with an unknown type (only reachable through a cast) yields just its title key."
+  },
+  {
+    "version": "0.388.0",
+    "type": "improvement",
+    "title": "validateScreens split into one validator per screen kind",
+    "detail": "validateScreens() keeps its signature, its error messages and the order in which it reports the first error. The per-kind validators live in screens-kind-*.ts next to screens.ts, and checks shared by several kinds (empty columns or sections, header actions, write-handler registration) live in screens-kind-shared.ts and screens-actions.ts. A screen whose type is not a known kind now fails boot with an explicit \"unknown type\" error."
+  },
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "Sequential job lock released when run setup fails",
+    "detail": "handleJob() claimed the sequential lock before prepareJobRun() and the onJobStart hook, but only released it in the finally block that started after them. A throwing onJobStart left the lock until its TTL (305 s) and every further invocation of that job was requeued behind it. Both calls now run inside the try and the lock is released by job name. A failure there is logged and, on the final attempt, reported through onJobFailed. The seed-migration failure message starts with systemWriteAs(...) instead of the duplicated [es-ops/seed-migration] prefix."
+  },
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "Reconnect after an outage no longer waits out connect_timeout",
+    "detail": "The postgres.js fork left the write buffer of a dead socket in place, so the first query after a database outage queued its startup message behind stale bytes and failed with CONNECT_TIMEOUT after 30 seconds. The fork now resets the buffer when the socket closes, and the next query opens a fresh connection immediately."
+  },
+  {
+    "version": "0.388.0",
+    "type": "improvement",
+    "title": "rateLimitCost for write handlers",
+    "detail": "A write handler can declare `rateLimitCost: (payload) => number`. The result is booked on every declared `rateLimit` bucket instead of the options' static `cost`; values below 1 count as 1 and non-finite values fail the request. The bucket is charged after schema validation, so an invalid payload costs nothing, and a rejected request consumes no tokens. Boot fails when `rateLimitCost` is set without an active `rateLimit`, or on an anonymous or ip-limited handler, because the cost books after the parse and such a handler would lose its pre-parse protection.",
+    "migration": "Optional. Bulk handlers should add `rateLimitCost: (p) => p.files.length` so a request with many items is not counted as one."
+  },
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "Codemods no longer drop side-effect imports or miss moved index files",
+    "detail": "The testing-move codemod repoints side-effect and empty imports instead of deleting them. The feature-layout codemod rewrites directory imports such as \"./components\" when the moved file is components/index.ts."
+  },
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "Review fixes for notify, form derivations, i18n keys, feature AST, nav stripping and escape-hatch audit",
+    "detail": "A deferred ctx.notify with Temporal values in data no longer fails the write. Form derivations take the literal currency or the source currency before the client value, reject mixed-currency operands, and the boot validator now rejects derive definitions that mix money with number/decimal units or use non-numeric sources. Metric labels of projectionDetail screens are required i18n keys. The feature AST keeps backingTable on spread entity definitions. Pure grouping navs emptied by disabled features are removed. db.global() writes are audited per table."
+  },
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "Client-error rate limit survives address rotation",
+    "detail": "Without Redis, the per-process limiter now drops the least recently seen IPs when more than 10000 are tracked, so a flood of fresh addresses no longer resets the window of every other IP."
+  },
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "Stalled SSE clients are dropped without further broadcasts",
+    "detail": "The heartbeat ping is written and tracked like entity frames instead of awaited, so a client that stopped reading is aborted at the next heartbeat after the stall timeout and releases its broker slot."
+  },
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "Leftover __Host- cookies are expired with secureCookies:false too",
+    "detail": "Clearing the session cookies now always sends the Secure delete for the __Host- auth and csrf variants when the configured names are unprefixed, so an app switched to secureCookies:false behind a TLS proxy no longer keeps a stale __Host- csrf cookie."
+  },
+  {
+    "version": "0.388.0",
+    "type": "breaking",
+    "title": "runAsDirectCallEntry renamed to runAsAgentToolCallEntry",
+    "detail": "The internal request-context helper also marks its scope as an agent tool call, so the name now says so; it stays reserved for dispatchToolCall.",
+    "migration": "replace imports of runAsDirectCallEntry from @cosmicdrift/kumiko-framework/internal/request-context with runAsAgentToolCallEntry; the signature is unchanged"
+  },
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "Version conflicts skip the extra stream-version lookup",
+    "detail": "The CRUD executor reports the current version carried by the event store conflict and queries the stream again only when the conflict carries none."
+  },
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "distinctOn documents that system reference rows compete for newest",
+    "detail": "The tenant-scoped read set includes system reference rows, so they take part in the newest-row pick; the docs name the tenantId filter that restricts it to own rows, and tests pin both behaviours. Tests also cover the createDbConnection ssl and onNotice options, the version-conflict race over HTTP, and the advisory-lock waiter probe is scoped to its own lock."
+  },
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "Empty and exclusion tenant filters no longer widen a read",
+    "detail": "A where.tenantId of { in: [] } now returns no rows, and { ne } or { notIn } keep excluding the named tenants instead of falling back to the caller's full scope. scopeTenantDbToTenant keeps the write denial of its source TenantDb."
+  },
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "Boot seeding re-creates soft-deleted reference rows",
+    "detail": "The seed lookup only considers live system-tenant rows, so a soft-deleted reference row is created anew instead of aborting the boot with a not-found error."
+  },
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "Version conflict on update reports the appended-against version",
+    "detail": "The racing update path now reports expectedVersion as the stream version it appended against, also with skipOptimisticLock or an expect precondition. A failed advisory unlock after a dropped session no longer hides the migration error."
+  },
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "Unknown keys in a handler field references meta fail the boot",
+    "detail": "A references meta such as `{ entity: \"channel\", bY: \"key\" }` is reported as invalid instead of silently reading as an id reference, so a misspelled `by` can no longer turn a business-key field into an id field."
+  },
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "r.requires rejects malformed arguments",
+    "detail": "`r.requires` now throws when called with more than one argument or without a `features` string array, instead of dropping extra arguments or registering the object as a dependency name."
+  },
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "r.bootCheck failures keep the check's own message",
+    "detail": "The boot error no longer appends a generic sentence, so messages ending in a period are not doubled and the check's text is the whole explanation."
+  },
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "Embedded list minimum stays in the JSON schema",
+    "detail": "A required or `minItems` embedded list again reports `minItems` in `z.toJSONSchema` output, so agent manifests tell callers that at least one row is needed."
+  },
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "Failing trial gate no longer breaks GET /api/schema",
+    "detail": "The trial gates of all disabled toggleable features run in parallel; a gate that throws counts as not unlocked, hides the add-on and is logged, so the client still boots."
+  },
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "No docsUrl for app error codes without a framework page",
+    "detail": "An app subclass that overrides the error code with an uncovered reason no longer links to a framework page that does not exist; the field is absent unless errorDocs covers the reason."
+  },
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "Anonymous sessions cannot bind pending uploads on save",
+    "detail": "The save pipeline now applies the same anonymous-session exclusion as the pending file ref helpers, so one visitor cannot attach another visitor's pending upload to their record."
+  },
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "Failed uploads drop their upload ledger row",
+    "detail": "When the fileRef create fails after the bytes were written, POST /files and createFileRefFromBytes now delete the bytes and forget the ledger row instead of leaving it for the next sweep."
+  },
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "More HTML roots are kept out of the XML content type",
+    "detail": "Uploads without a declared content type whose root element is a common HTML element (form, iframe, input, table parts, media and others) are no longer labelled application/xml."
+  },
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "POST /files uses the tenant file context and a transaction-safe upload ledger",
+    "detail": "The upload route records and forgets upload bytes through the resolver's ledger like every other file context, and createFileUploadLedger throws when given a connection already inside a transaction."
+  },
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "A failed runner start no longer leaves a scheduler refresh timer behind",
+    "detail": "The scheduler-seen refresh timer starts only after the rest of start() succeeded, so a failed start does not keep stamping for a runner that is not running."
+  },
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "Job runs survive a failing tenant timezone config read",
+    "detail": "A throwing tenant timezone config read now logs a warning and falls back to UTC for ctx.tz instead of failing a job that never uses ctx.tz."
+  },
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "Escape-hatch process dedup no longer grows without bound",
+    "detail": "Entries older than the daily re-audit interval are swept, so row-level cross-tenant read targets in long-lived workers are not kept forever."
+  },
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "Handler cross-tenant reads count in the escape-hatch metric",
+    "detail": "Handlers now report to the escape-hatch meter like jobs do, so every ctx.crossTenantReads call is counted while the audit event stays deduplicated per report window."
+  },
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "beforeTransaction phase and handler share one parsed payload",
+    "detail": "The payload parsed for the pre-transaction phases is handed to the handler as is, so schema defaults or transforms that generate values no longer differ between the phase and the handler."
+  },
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "Cascade delete and set-null load only child ids",
+    "detail": "The cascade handler selects the id column instead of full child rows before calling the executor per child."
+  },
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "Codemods stop miscompiling or skipping ambiguous sites",
+    "detail": "testing-injection rewrites named re-exports of moved names and reports export-star, testing-move reports namespace destructuring and qualified type references of split names, and object-form no longer rewrites r.requires(identifier) but reports it for a manual check."
+  },
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "schema validate names the violated FeatureDefinition key",
+    "detail": "A malformed FEATURES entry now reports the first key that is missing or has the wrong type instead of always pointing at the name."
+  },
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "Upgrade check names the codemod an improvement runs on apply",
+    "detail": "kumiko-upgrade without --apply now prints the codemod of each improvement entry, the same way it prints the migration of breaking entries."
+  },
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "Package-merge codemod keeps one entry per target package",
+    "detail": "When the merge target is already listed in dependencies, the old devDependencies entry is dropped; when the old entry is in dependencies and the target only in devDependencies, the target moves to dependencies so the runtime entry wins."
+  },
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "NotificationTemplateMeta declares senderName and replyTo",
+    "detail": "The type now matches the mail template meta schema of the template resolver, which accepts senderName and replyTo."
+  },
+  {
+    "version": "0.388.0",
+    "type": "fix",
+    "title": "Seed writes run the save lifecycle, so seeded files bind to their records",
+    "detail": "runProdApp built the boot seed dispatcher without lifecycle hooks, so seed writes and seed migrations skipped file binding (entity_id stayed null, other users got 404), the pre/post save and delete hooks, the tenant check of file references and the disposal of removed file references. The seed dispatcher now reuses the lifecycle hooks of the API dispatcher, exposed as lifecycleHooks on the entrypoints and on KumikoServer. A hook that throws inside the transaction now fails the seed and the boot."
+  },
   {
     "version": "0.387.0",
     "type": "improvement",

package/src/scripts/codemod/feature-layout.ts

@@ -122,16 +122,24 @@ function movedTargetOf(
   moved: ReadonlyMap<string, string>,
 ): string | undefined {
   const { base, extension } = stripScriptExtension(absoluteSpecifier);
-  const candidates =
+  const candidates: string[] =
     extension === ".js" || extension === ".ts" || extension === ".tsx" || extension === ""
       ? [absoluteSpecifier, `${base}.ts`, `${base}.tsx`]
       : [absoluteSpecifier];
+  if (extension === "")
+    candidates.push(`${absoluteSpecifier}/index.ts`, `${absoluteSpecifier}/index.tsx`);
   for (const candidate of candidates) {
     if (moved.has(candidate)) return candidate;
   }
   return undefined;
 }
 
+// A moved `<dir>/index.ts` is imported as `<dir>`, so the file name alone never appears in the importer.
+function importableNameOf(file: string): string {
+  const { base } = stripScriptExtension(baseName(file));
+  return base === "index" ? baseName(dirname(file)) : base;
+}
+
 function relativeSpecifierFrom(fromDir: string, target: string): string {
   const path = relative(fromDir, target).split("\\").join("/");
   return path.startsWith(".") ? path : `./${path}`;
@@ -258,7 +266,7 @@ function buildWrites(
   importRewrites: CodemodSite[],
 ): Map<string, string> {
   const writes = new Map<string, string>();
-  const basenames = [...moved.keys()].map((file) => stripScriptExtension(baseName(file)).base);
+  const basenames = [...moved.keys()].map(importableNameOf);
   for (const [file, original] of files) {
     const content = stripped.get(file) ?? original;
     const newFile = moved.get(file) ?? file;

package/src/scripts/codemod/object-form.ts

@@ -139,8 +139,27 @@ function isAssumedRegistrar(receiver: Node, assumeRegistrarNames: ReadonlySet<st
   );
 }
 
+function isFeatureNameLiteral(arg: Node): boolean {
+  return (
+    Node.isStringLiteral(arg) ||
+    Node.isNoSubstitutionTemplateLiteral(arg) ||
+    Node.isTemplateExpression(arg) ||
+    Node.isSpreadElement(arg)
+  );
+}
+
+// An identifier or call argument could be a features object (already the object form) or a name,
+// so it is neither rewritten nor skipped silently.
+function isAmbiguousRequires(method: RegistrarMethod, args: readonly Node[]): boolean {
+  return (
+    method === "requires" &&
+    !args.some(isFeatureNameLiteral) &&
+    args.some((arg) => !Node.isObjectLiteralExpression(arg))
+  );
+}
+
 export function isPositionalShape(method: RegistrarMethod, args: readonly Node[]): boolean {
-  if (method === "requires") return args.some((arg) => !Node.isObjectLiteralExpression(arg));
+  if (method === "requires") return args.some(isFeatureNameLiteral);
   // The object form takes exactly one argument, so a spread can only be a positional call.
   if (args.some((arg) => Node.isSpreadElement(arg))) return true;
   return args.length >= (method === "hook" ? 3 : 2);
@@ -477,13 +496,31 @@ function visitRegistrarCall(
   if (
     !Node.isPropertyAccessExpression(callee) ||
     method === undefined ||
-    !isRegistrarMethod(method) ||
-    !isPositionalShape(method, call.getArguments())
+    !isRegistrarMethod(method)
   ) {
-    // skip: not a positional registrar call, nothing to rewrite
+    // skip: not a registrar method call, nothing to rewrite
     return;
   }
+  const args = call.getArguments();
   const receiver = callee.getExpression();
+  if (isAmbiguousRequires(method, args)) {
+    if (
+      isFeatureRegistrarReceiver(receiver) ||
+      isAssumedRegistrar(receiver, assumeRegistrarNames)
+    ) {
+      rewriter.recordManual(
+        call,
+        method,
+        "argument is not a string literal, so it may already be the object form — check by hand",
+      );
+    }
+    // skip: an ambiguous argument is never rewritten; registrar receivers were reported above
+    return;
+  }
+  if (!isPositionalShape(method, args)) {
+    // skip: not a positional registrar call, nothing to rewrite
+    return;
+  }
   if (isFeatureRegistrarReceiver(receiver) || isAssumedRegistrar(receiver, assumeRegistrarNames)) {
     rewriter.recordPlan(call, method, planRegistrarCall(rewriter, call, method));
   } else if (isUnresolvedRegistrarLookalike(receiver)) {

package/src/scripts/codemod/package-merge.ts

@@ -162,6 +162,10 @@ function mergeDependencyBlock(
   moved: ReadonlyMap<string, string>,
   ownName: unknown,
   describe: (description: string) => void,
+  hooks: {
+    readonly isDuplicatedElsewhere: (target: string) => boolean;
+    readonly onAdded: (target: string) => void;
+  },
 ): Record<string, string> | undefined {
   const next: Record<string, string> = {};
   let changed = false;
@@ -173,7 +177,10 @@ function mergeDependencyBlock(
     }
     changed = true;
     describe(`${name} -> ${target}`);
-    if (target !== ownName && !(target in block)) next[target] = range;
+    if (target !== ownName && !(target in block) && !hooks.isDuplicatedElsewhere(target)) {
+      next[target] = range;
+      hooks.onAdded(target);
+    }
   }
   if (!changed) return undefined;
   return isSortedKeys(block)
@@ -181,6 +188,31 @@ function mergeDependencyBlock(
     : next;
 }
 
+function dropAddedFromDevDependencies(
+  record: Record<string, unknown>,
+  addedToDependencies: ReadonlySet<string>,
+  filePath: string,
+  result: SiteLists,
+): boolean {
+  const devBlock = record["devDependencies"];
+  if (addedToDependencies.size === 0 || !isStringRecord(devBlock)) return false;
+  const kept = Object.fromEntries(
+    Object.entries(devBlock).filter(([name]) => !addedToDependencies.has(name)),
+  );
+  if (Object.keys(kept).length === Object.keys(devBlock).length) return false;
+  record["devDependencies"] = kept;
+  for (const target of addedToDependencies) {
+    if (target in devBlock) {
+      result.rewrites.push({
+        file: filePath,
+        line: 1,
+        description: `devDependencies: ${target} dropped, dependencies already lists it`,
+      });
+    }
+  }
+  return true;
+}
+
 function transformPackageJson(
   source: string,
   filePath: string,
@@ -198,20 +230,38 @@ function transformPackageJson(
   const moved = movedPackages(mappings);
   const record: Record<string, unknown> = { ...manifest };
   let changed = false;
+  const addedToDependencies = new Set<string>();
   for (const blockName of DEPENDENCY_BLOCKS) {
     const block = record[blockName];
     if (!isStringRecord(block)) continue;
-    const merged = mergeDependencyBlock(block, moved, record["name"], (description) => {
-      result.rewrites.push({
-        file: filePath,
-        line: 1,
-        description: `${blockName}: ${description}`,
-      });
-    });
+    const merged = mergeDependencyBlock(
+      block,
+      moved,
+      record["name"],
+      (description) => {
+        result.rewrites.push({
+          file: filePath,
+          line: 1,
+          description: `${blockName}: ${description}`,
+        });
+      },
+      {
+        // npm/bun resolve a package listed in both dependencies and devDependencies by
+        // block order, so the runtime entry wins and the dev copy is dropped below.
+        isDuplicatedElsewhere: (target) =>
+          blockName === "devDependencies" &&
+          isStringRecord(record["dependencies"]) &&
+          target in record["dependencies"],
+        onAdded: (target) => {
+          if (blockName === "dependencies") addedToDependencies.add(target);
+        },
+      },
+    );
     if (merged === undefined) continue;
     record[blockName] = merged;
     changed = true;
   }
+  if (dropAddedFromDevDependencies(record, addedToDependencies, filePath, result)) changed = true;
   if (!changed) return source;
   const trailingNewline = source.endsWith("\n") ? "\n" : "";
   return `${JSON.stringify(record, null, detectIndent(source))}${trailingNewline}`;