@cosmicdrift/kumiko-framework 0.333.0 → 0.335.0

package/src/changes.json

@@ -1,4 +1,222 @@
 [
+  {
+    "version": "0.335.0",
+    "type": "fix",
+    "title": "Agent tool manifests no longer offer the caller-chosen id on create tools",
+    "detail": "Agent tool manifests no longer offer the caller-chosen `id` on create tools, since agent dispatch never runs as a system identity and the value was silently dropped. Combobox options now carry a value-based `data-testid`."
+  },
+  {
+    "version": "0.335.0",
+    "type": "improvement",
+    "title": "Stricter boot checks for list outputSchema envelopes, detail section fields, reference facet list handlers, metric navigate, dashboard screen panels, refEntity columns and checkbox columns",
+    "detail": "Stricter boot checks for screens and handlers; apps that carried a latent typo or misconfiguration now fail at boot instead of rendering an empty cell or doing nothing at runtime.\n- A plain (non-paged) query handler whose `outputSchema` declares the row shape instead of `{ rows, nextCursor }` now fails when a projectionList, relatedList, expandableRow or dashboard list panel uses it.\n- `projectionDetail` layout section `fields` are checked against the query's `outputSchema`.\n- A `reference` list facet requires the target's list query handler (`<feature>:query:<entity>:list`, or its central lookup override) to be registered.\n- `MetricSpec.navigate.screen`/`entity` are validated even without `tab`; `navigate.entity` needs `entityId`.\n- A dashboard `screen` panel must not embed an `actionForm`/`secretMint` with `redirect` or `cancelTarget`.\n- `refEntity` on entityList columns and dashboard list-panel columns must resolve to a registered entity.\n- `multiSelect` `display: \"checkboxes\"` rejects `columns` outside 1-4.\n- Personal-data detection for `openToAll` write handlers now also looks inside `z.map`, `z.set`, `z.promise` and `.catchall()` schemas.\n- Fixes false boot failures for cross-feature rowActions / `listScreenId` written as a fully-qualified screen QN, and for where-rules that use a bare outer column next to a qualified subquery.",
+    "migration": "Boot now fails for configurations that previously rendered empty or did nothing. Fix the named screen or field: wrap a list handler's outputSchema in { rows, nextCursor }, correct detail section field names, register the entity list handler (defineEntityListHandler) behind a reference facet, add entityId to a metric navigate.entity, drop redirect/cancelTarget on forms embedded in a dashboard, and use a registered entity for refEntity."
+  },
+  {
+    "version": "0.335.0",
+    "type": "fix",
+    "title": "Encrypted-at-rest text config keys derive writeOnly settings fields; boot validator allows writeOnly on configEdit only for those keys"
+  },
+  {
+    "version": "0.335.0",
+    "type": "fix",
+    "title": "migrate-db-raw codemod lists own-tenant calls with a spread after tenantId for manual review instead of rewriting them",
+    "detail": "The `migrate-db-raw` codemod no longer auto-rewrites own-tenant calls whose filter object has a spread after `tenantId`, since the spread can override it at runtime; such sites are listed for manual review."
+  },
+  {
+    "version": "0.335.0",
+    "type": "fix",
+    "title": "switch-tenant validates tenantId, fault logger tolerates non-string type, PII guard matches full ciphertext shape",
+    "detail": "`POST /api/auth/switch-tenant` answers 400 `invalid_tenant` for a missing or non-string `tenantId` instead of feeding it into the membership lookup. A non-string `type` in a request body no longer turns a 4xx into a 500 inside the fault logger. The PII ciphertext response guard now matches the full ciphertext shape, so user text containing the bare `kumiko-pii:v` marker no longer 500s reads. `kumiko upgrade --apply` records `pendingManual` in the marker when no codemod runs."
+  },
+  {
+    "version": "0.335.0",
+    "type": "fix",
+    "title": "File-storage boot gate reads the injected env, derivative erasure matches lowercase hashes only",
+    "detail": "The `FILE_STORAGE_PROVIDER` boot gate now reads the `env` passed to `validateBoot` (falling back to `process.env`), so an `envSource` handed to `runProdApp` with an empty `process.env` no longer fails the gate. `runDevApp` stops mutating `process.env` for an explicitly wired file provider. The derivative-key recognizer used by forget and tenant-destroy now matches the hash segment case-sensitively."
+  },
+  {
+    "version": "0.335.0",
+    "type": "breaking",
+    "title": "Boot rejects multiple principalStatus providers, updateMany rejects unknown columns again",
+    "detail": "Several fail-loud fixes. `buildServer` now also rejects more than one `principalStatus` provider when `auth.membershipQuery` is registered (previously every login 500ed at runtime). `updateMany` throws again on a key that is not a column, and the replay of historical update events skips fields removed from the entity instead. `lt`/`gt`/`lte`/`gte`/`like` on a jsonb column match nothing in the where builder, like the event-store read path.",
+    "migration": "`updateMany` now throws when `set` or `where` contains a key that is not a column of the table; remove such keys from your calls. Replay of historical update events still skips removed fields."
+  },
+  {
+    "version": "0.335.0",
+    "type": "improvement",
+    "title": "Boot validator rejects overlapping dateRange facet params, unknown subtitleHref/countField fields and whitespace in redirect.idFrom; clearer refEntity, nav and where-probe diagnostics",
+    "detail": "Boot validator follow-ups.\n- A `dateRange` facet param name used by more than one dateRange facet on a projectionList screen now fails boot (the facets overwrote each other's bound).\n- `header.subtitleHref` and a section's `countField` on a projectionDetail screen are checked against the query's `outputSchema`.\n- `redirect.idFrom` with leading or trailing whitespace now fails boot instead of silently navigating without an id.\n- A `refEntity` pointing at a feature that is not mounted now says so and names `r.requires(...)` instead of listing \"(none)\" entities.\n- The nav inversion warning no longer prints `requires roles []` for a leaf with an invalid `openToAll`, and the unreachable-screen warning points workspace apps at `r.workspace({ nav })` instead of a non-existent allowlist.\n- The where-rule boot probe renders `ctx.tableName` with the real table name, matching runtime.",
+    "migration": "Boot now fails for configurations that silently misbehaved. Give each dateRange facet on a screen its own from/to params, point header.subtitleHref and section countField at fields of the query's outputSchema, and remove stray whitespace from redirect.idFrom."
+  },
+  {
+    "version": "0.335.0",
+    "type": "fix",
+    "title": "Malformed waitForEvent matchExpr rows are skipped instead of blocking the wakeup projection",
+    "detail": "Review round 2 fixes for waitForEvent matching, read steps, env parsing and agent reasons.\n- A pending workflow row with a malformed or unsupported `matchExpr` is now skipped and logged instead of aborting the wakeup projection for every other run waiting on the same event. `evaluateEventMatch` reports a structurally malformed AST as a readable `Malformed EventMatch` error.\n- `read.findOne` and `read.findMany` reject a non-object `unsafeAllTenants` (for example `true`) with an `InternalError` instead of a raw `TypeError`.\n- `parseEnv` reports a refinement that throws as a `KumikoBootError`, and the ciphertext-only slot caveat for refinements is documented.\n- Removed the unused `AgentReasons.permissionDenied` (`agent.permission_denied`) reason and its error-docs pages; nothing emitted it."
+  },
+  {
+    "version": "0.335.0",
+    "type": "breaking",
+    "title": "AgentReasons.permissionDenied removed",
+    "migration": "Drop references to `AgentReasons.permissionDenied` / `\"agent.permission_denied\"`. The framework never emitted this reason."
+  },
+  {
+    "version": "0.335.0",
+    "type": "fix",
+    "title": "ExtraRouteRejection retryAfterSeconds must be a safe integer; token-request routes stop logging rate_limited",
+    "detail": "`ExtraRouteRejection` now rejects a `retryAfterSeconds` beyond the safe-integer range, so the `Retry-After` header is always valid delta-seconds. Password-reset style token-request routes no longer log `rate_limited` handler results as errors."
+  },
+  {
+    "version": "0.335.0",
+    "type": "fix",
+    "title": "Feature-AST patcher handles quoted keys, stream-handler escapeHatch and shorthand piiFields",
+    "detail": "The feature-AST patcher now replaces and unsets string-literal keys such as `\"description\": \"old\"` instead of appending a duplicate key or skipping the unset. `addStreamHandler` accepts `escapeHatch`. The defineEvent extractor accepts a shorthand `{ piiFields }` stance and reports a non-literal options argument with its own message."
+  },
+  {
+    "version": "0.335.0",
+    "type": "fix",
+    "title": "File byte routes survive undecryptable fileName; loadAggregate and appendProvenanceEvent reject empty type parts",
+    "detail": "`GET /files/:id` and the download-url route now fall back to the filename \"download\" when the stored fileName cannot be decrypted (malformed ciphertext, erased subject, annotation drift) instead of returning 500 or leaking ciphertext into headers. `loadAggregate` rejects an empty `aggregateType` instead of loading the unfiltered stream, and `appendProvenanceEvent` rejects event types with an empty owner or name."
+  },
+  {
+    "version": "0.335.0",
+    "type": "breaking",
+    "title": "FileRef type drops the unreachable isDeleted field",
+    "detail": "The exported `FileRef` type no longer carries `isDeleted`. Soft-deleted rows were already filtered out before the guard sees a file, so the field was never reachable. Custom file access guards that read `fileRef.isDeleted` must drop that check.",
+    "migration": "Remove reads of `fileRef.isDeleted` in custom file access guards; soft-deleted rows never reach the guard."
+  },
+  {
+    "version": "0.335.0",
+    "type": "breaking",
+    "title": "File content check covers csv alias, local list scoped to prefix, provider contract checked, locale tags canonicalized",
+    "detail": "File storage and locale hardening. `validateFileContent` now rejects binary bytes for an extension with a declared-MIME alias (a real `.xls` renamed to `.csv`), so custom upload routes using `validateFile` + `validateFileContent` are covered. `tenantExportPrefix` and `tenantStoragePrefixes` throw for a tenant id equal to the reserved `exports` segment. The local provider's `list()` only walks the prefix directory instead of the whole storage root. A file-provider plugin whose built provider lacks a required method now fails loudly at resolve time. `canonicalizeLocaleTag` normalizes region and script subtags (`de-AT`, `zh-Hant-TW`), so `X-Locale: DE-at` finds a `de-AT` mail registration.",
+    "migration": "A file-provider plugin whose built provider lacks a required method now throws at resolve time; make sure custom file providers implement the full provider interface."
+  },
+  {
+    "version": "0.335.0",
+    "type": "breaking",
+    "title": "Global-table tenant writes reject loudly, restore maps unique violations, managed unique-index changes recreate",
+    "detail": "Tenant-mode `updateMany`/`deleteMany` on a `tenancy: \"global\"` table now reject with an `AccessDeniedError` pointing at `db.global(table)` instead of silently matching zero rows. `restore` on a soft-deleted row whose unique value was re-used now returns a 409 `unique_violation` instead of a raw 500. The migration generator now recreates a managed projection when an existing index becomes unique, changes columns or widens its WHERE.",
+    "migration": "Tenant-mode `updateMany`/`deleteMany` on a `tenancy: \"global\"` table now throws instead of matching zero rows; switch those calls to `db.global(table)`."
+  },
+  {
+    "version": "0.335.0",
+    "type": "fix",
+    "title": "Guard edge cases, extension entityName fallback and dispatcher drain waiting for in-flight passes",
+    "detail": "Guards: the runtime-isolation guard now follows value re-exports (`export * from`, `export { x } from`) and reads the `kumiko.runtime` marker in the repo-root `package.json`. The upgrade-state guard prefers the repo-local `node_modules/.bin/kumiko-upgrade` over a PATH entry. The error-reasons guard no longer flags prose reasons passed to `withUnsafeRawGrant`. Remaining German guard messages are now English. Blank `entityName` overrides on extension sections fall back to the host entity. `EventDispatcher.drain()` now also waits for a pass still in its idle pre-check."
+  },
+  {
+    "version": "0.335.0",
+    "type": "breaking",
+    "title": "i18n key guard covers multiSelect option labels and writeForm section descriptions",
+    "detail": "The i18n key guard now requires translations for filterable `multiSelect` option labels and for the `description` of a `projectionDetail` writeForm section. Missing translations used to fall back silently; they now fail the guard.",
+    "migration": "The i18n required-surface-keys check now requires translations for filterable `multiSelect` option labels and `projectionDetail` writeForm section descriptions; add the missing keys to your locale files."
+  },
+  {
+    "version": "0.335.0",
+    "type": "fix",
+    "title": "perTenant fan-out without context.db reports the missing db instead of a missing tenant feature",
+    "detail": "A perTenant job on a job runner built without `context.db` now fails with a message that names the missing `context.db` when the tenant feature is mounted, instead of telling the operator to mount it. A readiness failure during `stop()` is now logged at debug level."
+  },
+  {
+    "version": "0.335.0",
+    "type": "fix",
+    "title": "Key Manager boot resolves slots in parallel, validates the previous-KEK version up front and keeps the fetch error as cause",
+    "detail": "The Key Manager boot resolution now resolves all KEK slots in parallel, rejects a previous KEK without `PLATFORM_KEK_PREVIOUS_VERSION` before any Key Manager call, keeps the original network error as `cause`, and names the slot in the partial-wiring error. The boot log line names the source actually taken."
+  },
+  {
+    "version": "0.335.0",
+    "type": "fix",
+    "title": "Boot column check skips loose/catchall output schemas; schema-walk error names the handler",
+    "detail": "The query output-schema column check now skips `z.looseObject()` and `.catchall()` row schemas, since they accept keys beyond the declared shape. The schema-size guard for write-handler input schemas now names the feature and handler in its boot error."
+  },
+  {
+    "version": "0.335.0",
+    "type": "fix",
+    "title": "Multi-stream projection rebuild honors the shutdown AbortSignal",
+    "detail": "`rebuildMultiStreamProjection` now accepts an `AbortSignal` and checks it per replayed event. The boot backfill's shutdown signal reaches it, so a SIGTERM during a long multi-stream replay rolls the transaction back and releases the consumer lock instead of hanging until the pod is killed."
+  },
+  {
+    "version": "0.335.0",
+    "type": "fix",
+    "title": "multiSelect filters handle empty and non-string values and NULL columns; forget sweeps tolerate missing columns and serial ids",
+    "detail": "multiSelect list filters no longer return every row for an empty array value, no longer fail with a 500 on boolean or numeric client values, and `ne` now keeps rows whose column is NULL. The forget sweeps (blind-index nulling, search purge) skip lookupable or searchable fields whose columns are missing from a migrated table instead of aborting after the key was erased, and the self-PII tenant probe ignores serial-id entities instead of throwing on a uuid subject id."
+  },
+  {
+    "version": "0.335.0",
+    "type": "fix",
+    "title": "App-schema JSON-safety rejects NaN/Infinity and cyclic defaults",
+    "detail": "The app-schema JSON-safety check now rejects `NaN`/`Infinity` defaults and guards against self-referencing values. The agent doc lint reports exposed handlers whose input schema cannot be converted to JSON Schema (they were silently left out of the agent manifest). Icon-only list and edit action buttons now also set `title`, so sighted mouse users get the hover tooltip."
+  },
+  {
+    "version": "0.335.0",
+    "type": "fix",
+    "title": "Executor create/restore validate before connection binding; clearer rebuild and backfill errors",
+    "detail": "The event-store executor's `create()` and `restore()` now run their validation (global-tenancy guard, `soft_delete_not_enabled`) before resolving the connection, so callers get the proper 4xx error instead of an internal \"no connection bound\" error. List `totalCount` always counts over the full WHERE, and a PII backfill failure for an unresolvable catalog event subject no longer suggests the entity-only retry options. The shadow-swap RLS and blind-index error messages now state the concrete action (full KMS wiring for the blind-index key)."
+  },
+  {
+    "version": "0.335.0",
+    "type": "fix",
+    "title": "afterCommit hook writes run in their own transaction, plus cache, nested-write, skip-poison and search-consumer fixes",
+    "detail": "Writes from an afterCommit hook now run as their own transaction with their own afterCommit flush, so the nested write's hooks fire and a failing projection rolls it back. The tenant timezone cache no longer stores a value read before a concurrent config write. Nested-write ownership checks complete a partial parent row from the stored row. `skipPoisonEvent` locks the consumer row before computing pending gaps. The search consumer fails an event for retry when its context has no database instead of removing the index entry."
+  },
+  {
+    "version": "0.335.0",
+    "type": "fix",
+    "title": "Qualified redirects resolve in their named feature, update forms skip untouched required fields, secretMint confirm can restart",
+    "detail": "A qualified redirect target (`feature:screen:id`) is now resolved inside the named feature, so a same-id screen in the redirecting feature no longer swallows the created record id. An entityEdit update form only presence-checks required fields the user changed, so a legacy row with an empty, newly required field can still be saved. The secretMint confirm step always offers a cancel that restarts at the mint form when no redirect or cancelTarget is set."
+  },
+  {
+    "version": "0.335.0",
+    "type": "breaking",
+    "title": "totalsMatch rejects a payload that carries only one side of the pair",
+    "detail": "A `totalsMatch` pair is now validated as a unit. A payload that carries only the embedded list or only its sibling money field is rejected with a validation error, because update payloads only carry `changes` and the sum could otherwise drift away from the total.",
+    "migration": "Send the embedded list and its sibling money field together in every create and update payload. A partial update that changes only `total` or only the list now fails validation."
+  },
+  {
+    "version": "0.335.0",
+    "type": "fix",
+    "title": "Transfer-graph boot check rejects a multiple reference only when its target is transferable",
+    "detail": "The transfer-graph boot check now rejects a `multiple` reference on a transferable entity only when the target entity is itself transferable. A multiple reference to a plain lookup entity boots again."
+  },
+  {
+    "version": "0.335.0",
+    "type": "fix",
+    "title": "Empty KUMIKO_TRUSTED_PROXY_HOPS is treated as unset, and dist no longer ships compiled codemods",
+    "detail": "`parseTrustedProxyHopsEnv` treats an empty `KUMIKO_TRUSTED_PROXY_HOPS` as unset, so a blank `.env` template line no longer crashes the dev boot while prod ignored it. The published package also no longer ships the unusable compiled `dist/scripts/` codemod copies."
+  },
+  {
+    "version": "0.335.0",
+    "type": "fix",
+    "title": "Upgrade marker needs an installed version, Meilisearch drop keeps sibling prefixes, drainJobs sees pre-run job failures",
+    "detail": "`kumiko upgrade --apply` now refuses to write a marker when no installed Kumiko version can be found under the target, instead of recording the `--from` filter value. It also finds `node_modules/@cosmicdrift/*` packages that are workspace symlinks. `MeilisearchAdapter.dropAllIndexes()` only drops tenant indexes of its own prefix and leaves indexes of a longer sibling prefix alone. `drainJobs()` now rejects when a perTenant fan-out or an unknown job fails before the job body runs."
+  },
+  {
+    "version": "0.335.0",
+    "type": "fix",
+    "title": "SSE stream closes when access is revoked",
+    "detail": "The live event stream (GET /sse) now closes as soon as the session behind it is revoked or the user's tenant roles change or the membership is removed. User-addressed frames such as in-app notifications are delivered only to the addressed user instead of the whole tenant."
+  },
+  {
+    "version": "0.335.0",
+    "type": "improvement",
+    "title": "Boot validator checks redirect targets of writeHandler record actions",
+    "detail": "An unknown `redirect` screen on a projectionDetail or entityEdit action or section action fails boot, like entityEdit `redirect`.",
+    "migration": "If a writeHandler record action already carries a `redirect` that does not resolve to a registered screen, fix or remove it."
+  },
+  {
+    "version": "0.334.0",
+    "type": "improvement",
+    "title": "Settings form gaps: writeForm footer submit, option description/group, dependent optionsQueryPayload, config badge label, writeOnly secret fields",
+    "detail": "- A `writeForm` section that fills a whole tab puts its submit button into the pinned form footer.\n- `optionsQuery` rows may carry `description` (muted second line) and `group` (heading). The combobox and the radio list show both. Options with either one never render as segments.\n- `optionsQueryPayload` values may be `{ field: \"<sibling>\" }`. The select reloads when that field changes and clears a value the new rows no longer contain. A cleared config select resets the key, so the inherited value applies again. On config keys, `field` names another key of the same feature on the same settings mask. The boot validator checks the names, and `writeForm` fieldDefs now go through the select checks too.\n- The origin line and cascade level rows on `configEdit` fields show the option label instead of the raw value or id.\n- New `writeOnly: true` on entity text fields with `find: \"secret\"`. Reads return `true` (set) or `null` and never the value. On write, `\"\"` keeps the stored value and `null` clears it. The edit form shows a masked input with a \"set\" placeholder and a remove action. `maskWriteOnlyFields(entity, row)` is exported from `@cosmicdrift/kumiko-framework/engine` for custom query handlers that return executor rows."
+  },
+  {
+    "version": "0.334.0",
+    "type": "breaking",
+    "title": "Duplicate write/query handler names in one feature fail at definition time",
+    "migration": "Rename a custom handler that shares its name with another handler of the same feature, including names r.crud registers (<entity>:list, <entity>:detail, <entity>:create, <entity>:update, <entity>:delete, <entity>:restore). Before, the later registration replaced the earlier one silently."
+  },
   {
     "version": "0.332.0",
     "type": "fix",

package/src/scripts/codemod/migrate-cross-tenant.ts

@@ -168,8 +168,20 @@ export function migrateCrossTenantSource(
   const rewrites: Rewrite[] = [];
   const manual: ManualSite[] = [];
 
+  // Captured up front: a forgotten node can no longer report its position.
+  const lineByAssignment = new Map(targets.map((a) => [a, a.getStartLineNumber()]));
+
   for (const assignment of targets) {
-    if (assignment.wasForgotten()) continue;
+    // A forgotten node has no position or text left; a bare `continue` would
+    // drop a security-relevant crossTenant switch from the report entirely.
+    if (assignment.wasForgotten()) {
+      manual.push({
+        file: fileName,
+        line: lineByAssignment.get(assignment) ?? 0,
+        why: "node was invalidated by an earlier rewrite in this file — run the codemod on this file again",
+      });
+      continue;
+    }
     const line = assignment.getStartLineNumber();
     const init = assignment.getInitializer();
 
@@ -327,7 +339,7 @@ async function main(): Promise<void> {
     }
   }
 
-  process.exit(0);
+  process.exit(allManual.length > 0 ? 1 : 0);
 }
 
 if (import.meta.main) {

package/src/scripts/codemod/migrate-db-raw.ts

@@ -89,14 +89,22 @@ function isValidOwnTenantIdValue(valueNode: Node): boolean {
 
 function objectHasValidOwnTenantId(obj: Node): boolean {
   if (!Node.isObjectLiteralExpression(obj)) return false;
-  for (const prop of obj.getProperties()) {
-    if (Node.isPropertyAssignment(prop) && prop.getName() === "tenantId") {
-      const init = prop.getInitializer();
-      return init !== undefined && isValidOwnTenantIdValue(init);
-    }
-    if (Node.isShorthandPropertyAssignment(prop) && prop.getName() === "tenantId") {
-      return isConstTenantIdBinding(enclosingFunctionScope(prop), "tenantId");
-    }
+  const props = obj.getProperties();
+  const tenantIdIndex = props.findIndex(
+    (prop) =>
+      (Node.isPropertyAssignment(prop) || Node.isShorthandPropertyAssignment(prop)) &&
+      prop.getName() === "tenantId",
+  );
+  if (tenantIdIndex === -1) return false;
+  // A later spread can override the literal tenantId at runtime.
+  if (props.slice(tenantIdIndex + 1).some((prop) => Node.isSpreadAssignment(prop))) return false;
+  const prop = props[tenantIdIndex];
+  if (Node.isPropertyAssignment(prop)) {
+    const init = prop.getInitializer();
+    return init !== undefined && isValidOwnTenantIdValue(init);
+  }
+  if (Node.isShorthandPropertyAssignment(prop)) {
+    return isConstTenantIdBinding(enclosingFunctionScope(prop), "tenantId");
   }
   return false;
 }

package/src/scripts/codemod/migrate-open-to-all.ts

@@ -188,6 +188,12 @@ function collectFiles(paths: string[]): string[] {
   return files;
 }
 
+// Remaining manual sites still fail boot validation, so upgrade-cli must not
+// treat this run as a completed migration.
+export function exitCodeForManualSites(manualCount: number): 0 | 1 {
+  return manualCount > 0 ? 1 : 0;
+}
+
 async function main(): Promise<void> {
   let options: CliOptions;
   try {
@@ -241,7 +247,7 @@ async function main(): Promise<void> {
     }
   }
 
-  process.exit(0);
+  process.exit(exitCodeForManualSites(allManual.length));
 }
 
 if (import.meta.main) {

package/src/scripts/codemod/pii-personal-migration.ts

@@ -473,7 +473,14 @@ function reportStanceHasPersonalStance(obj: ObjectLiteralExpression): boolean {
 function reportStanceEnclosingFieldName(call: CallExpression): string | undefined {
   let node = call.getParent();
   while (node) {
-    if (Node.isPropertyAssignment(node)) return node.getName();
+    if (Node.isPropertyAssignment(node)) {
+      // getName() keeps the quotes of a string-literal key; computed keys have no static name.
+      const nameNode = node.getNameNode();
+      if (Node.isStringLiteral(nameNode) || Node.isNoSubstitutionTemplateLiteral(nameNode)) {
+        return nameNode.getLiteralText();
+      }
+      return Node.isIdentifier(nameNode) ? nameNode.getText() : undefined;
+    }
     node = node.getParent();
   }
   return undefined;
@@ -506,17 +513,28 @@ function reportStanceResolveEntity(call: CallExpression): string | null {
   return varDecl ? varDecl.getName() : null;
 }
 
-// A hint only counts at a segment boundary (index 0, an uppercase letter in
-// the original, or preceded by `_`) — otherwise a coincidental substring
-// like "text" inside "contextId" would false-positive.
+function isSegmentStart(fieldOriginal: string, index: number): boolean {
+  return (
+    index === 0 || /[A-Z]/.test(fieldOriginal[index] ?? "") || fieldOriginal[index - 1] === "_"
+  );
+}
+
+// A hint only counts when it starts and ends on a segment boundary (index 0 /
+// end of field, an uppercase letter in the original, or `_`) — otherwise a
+// coincidental substring like "text" in "contextId" or "type" in "contentType"
+// would false-positive.
 function hintOccursAtBoundary(fieldLower: string, fieldOriginal: string, hint: string): boolean {
   let searchFrom = 0;
   for (;;) {
     const index = fieldLower.indexOf(hint, searchFrom);
     if (index === -1) return false;
-    const atBoundary =
-      index === 0 || /[A-Z]/.test(fieldOriginal[index] ?? "") || fieldOriginal[index - 1] === "_";
-    if (atBoundary) return true;
+    const end = index + hint.length;
+    if (
+      isSegmentStart(fieldOriginal, index) &&
+      (end === fieldOriginal.length || isSegmentStart(fieldOriginal, end))
+    ) {
+      return true;
+    }
     searchFrom = index + 1;
   }
 }
@@ -532,23 +550,26 @@ function findLongestBoundaryHint(fieldLower: string, fieldOriginal: string): str
 
 function segmentAlignedSuffixes(fieldOriginal: string): string[] {
   const fieldLower = fieldOriginal.toLowerCase();
-  const suffixes: string[] = [];
+  const starts: number[] = [];
   for (let index = 0; index < fieldOriginal.length; index++) {
-    const atBoundary =
-      index === 0 || /[A-Z]/.test(fieldOriginal[index] ?? "") || fieldOriginal[index - 1] === "_";
-    if (atBoundary) suffixes.push(fieldLower.slice(index));
+    if (isSegmentStart(fieldOriginal, index)) starts.push(index);
   }
-  return suffixes;
+  // Hints are lowercase, so a hint's own segment boundary is unknowable. A
+  // single-segment tail ("Number", "Owner") is too generic to align with one;
+  // two or more segments ("UserId") are specific enough.
+  return starts.slice(0, -1).map((index) => fieldLower.slice(index));
 }
 
 // The hint sets only carry exact full names, so a suffix variant of one
 // (e.g. "...UserId" of "assigneeUserId") otherwise slips through undetected.
+// The suffix must be the tail of the hint: plain `includes` matched "number"
+// inside "phonenumber" for "orderNumber".
 function findShortestHintContainingSuffix(fieldOriginal: string): string | undefined {
   let best: string | undefined;
   for (const suffix of segmentAlignedSuffixes(fieldOriginal)) {
     if (suffix.length < 5) continue;
     for (const hint of ALL_PII_NAME_HINTS) {
-      if (!hint.includes(suffix)) continue;
+      if (hint === suffix || !hint.endsWith(suffix)) continue;
       if (!best || hint.length < best.length) best = hint;
     }
   }
@@ -556,22 +577,37 @@ function findShortestHintContainingSuffix(fieldOriginal: string): string | undef
 }
 
 function classifyFieldStance(field: string): { stance: StanceClass; hint: string | undefined } {
-  const fieldLower = field.toLowerCase();
+  const fieldLower = field.replaceAll("_", "").toLowerCase();
   if (PII_DIRECT_NAME_HINTS.has(fieldLower)) return { stance: "direct", hint: fieldLower };
   if (PII_USER_OWNED_NAME_HINTS.has(fieldLower)) return { stance: "user-owned", hint: fieldLower };
   if (PII_USER_REFERENCE_NAME_HINTS.has(fieldLower))
     return { stance: "user-reference", hint: fieldLower };
-  const containmentHint = findLongestBoundaryHint(fieldLower, field);
+  const containmentHint = findLongestBoundaryHint(field.toLowerCase(), field);
   if (containmentHint) return { stance: "near-miss", hint: containmentHint };
   const suffixHint = findShortestHintContainingSuffix(field);
   if (suffixHint) return { stance: "near-miss", hint: suffixHint };
   return { stance: "unclassified", hint: undefined };
 }
 
-export function reportStanceForSource(source: string, filePath: string): StanceSite[] {
-  const project = new Project({ useInMemoryFileSystem: true, skipFileDependencyResolution: true });
-  const sourceFile = project.createSourceFile(filePath, source);
+function createReportStanceProject(): Project {
+  return new Project({ useInMemoryFileSystem: true, skipFileDependencyResolution: true });
+}
+
+export function reportStanceForSource(
+  source: string,
+  filePath: string,
+  project: Project = createReportStanceProject(),
+): StanceSite[] {
+  const sourceFile = project.createSourceFile(filePath, source, { overwrite: true });
+  try {
+    return collectStanceSites(sourceFile);
+  } finally {
+    // A shared project would otherwise keep every scanned file's AST alive.
+    project.removeSourceFile(sourceFile);
+  }
+}
 
+function collectStanceSites(sourceFile: SourceFile): StanceSite[] {
   const sites: StanceSite[] = [];
   for (const call of sourceFile.getDescendantsOfKind(SyntaxKind.CallExpression)) {
     const exprNode = call.getExpression();
@@ -634,8 +670,9 @@ function reportStance(rootDir: string): void {
   };
   let total = 0;
 
+  const project = createReportStanceProject();
   for (const file of findReportStanceFiles(rootDir)) {
-    const sites = reportStanceForSource(readFileSync(file, "utf8"), file);
+    const sites = reportStanceForSource(readFileSync(file, "utf8"), file, project);
     if (sites.length === 0) continue;
 
     console.log(`\n${relative(rootDir, file)}`);

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

@@ -193,42 +193,99 @@ function processNewExpression(args: readonly Node[], report: (note: string) => v
   return "changed";
 }
 
+// `failUnprocessable(reason, details)` takes the details literal directly as
+// its second argument (no `{ details }` wrapper like the ctor's opts).
+function processFailUnprocessableCall(
+  args: readonly Node[],
+  report: (note: string) => void,
+): CallOutcome {
+  const detailsArg = args[1];
+  if (!detailsArg) return "not-a-match";
+
+  if (!Node.isObjectLiteralExpression(detailsArg)) {
+    report(
+      "second argument (details) is not a statically-analyzable object literal — cannot verify details.reason",
+    );
+    return "skipped";
+  }
+
+  const removal = removeReasonProperty(detailsArg);
+  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 };
 
+type MigratableCall = {
+  readonly exportName: "UnprocessableError" | "failUnprocessable";
+  readonly localKind: "class" | "function";
+  readonly process: (args: readonly Node[], report: (note: string) => void) => CallOutcome;
+};
+
+const UNPROCESSABLE_ERROR_CTOR: MigratableCall = {
+  exportName: "UnprocessableError",
+  localKind: "class",
+  process: processNewExpression,
+};
+const FAIL_UNPROCESSABLE_CALL: MigratableCall = {
+  exportName: "failUnprocessable",
+  localKind: "function",
+  process: processFailUnprocessableCall,
+};
+
+function migrateCallSite(
+  sourceFile: SourceFile,
+  importedNames: ReadonlyMap<string, ImportedBinding>,
+  site: Node & { getExpression(): Node; getArguments(): Node[] },
+  target: MigratableCall,
+  skips: SkipEntry[],
+): boolean {
+  const callee = site.getExpression();
+  if (!Node.isIdentifier(callee)) return false;
+  const localName = callee.getText();
+  const line = site.getStartLineNumber();
+  const file = sourceFile.getFilePath();
+
+  const binding = importedNames.get(localName);
+  if (binding?.importedName !== target.exportName) {
+    if (localName !== target.exportName) return false;
+    const note = binding
+      ? `${target.exportName} is imported from "${binding.moduleSpecifier}", not a @cosmicdrift/kumiko-* package`
+      : `${target.exportName} has no @cosmicdrift/kumiko-* import in this file (likely a locally defined ${target.localKind})`;
+    skips.push({ file, line, note });
+    return false;
+  }
+  if (!KUMIKO_MODULE_RE.test(binding.moduleSpecifier)) {
+    skips.push({
+      file,
+      line,
+      note: `${target.exportName} is imported from "${binding.moduleSpecifier}", not a @cosmicdrift/kumiko-* package`,
+    });
+    return false;
+  }
+
+  const outcome = target.process(site.getArguments(), (note) => skips.push({ file, line, note }));
+  return outcome === "changed";
+}
+
 /** 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 (migrateCallSite(sourceFile, importedNames, newExpr, UNPROCESSABLE_ERROR_CTOR, skips)) {
+      removedCount++;
     }
-    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;
+  }
+  for (const call of sourceFile.getDescendantsOfKind(SyntaxKind.CallExpression)) {
+    if (migrateCallSite(sourceFile, importedNames, call, FAIL_UNPROCESSABLE_CALL, skips)) {
+      removedCount++;
     }
-
-    const outcome = processNewExpression(newExpr.getArguments(), (note) => {
-      skips.push({ file: sourceFile.getFilePath(), line: newExpr.getStartLineNumber(), note });
-    });
-    if (outcome === "changed") removedCount++;
   }
 
   return removedCount;

package/dist/scripts/codemod/crypto-shredding-testing-move.d.ts

@@ -1,2 +0,0 @@
-#!/usr/bin/env bun
-export {};