@cosmicdrift/kumiko-framework 0.335.0 → 0.336.0

package/dist/jobs/job-runner.js

@@ -228,6 +228,9 @@ const BOOT_REDIS_TIMEOUT_MS = 10_000;
 // Shutdown must fit a k8s grace period even when Redis is down, so the
 // readiness wait in stop() is capped well below the boot timeout.
 const STOP_QUEUE_READY_TIMEOUT_MS = 1_000;
+// A gate without an explicit `timeout` may legitimately run long (migration-style
+// checks), so it is never rejected; a hang just must not stay silent.
+const BOOT_GATE_SLOW_WARN_MS = 60_000;
 function timeoutReject(ms, message) {
     let timer;
     const promise = new Promise((_, reject) => {
@@ -875,14 +878,28 @@ export function createJobRunner(options) {
                 continue;
             if (!jobDef.bootGate)
                 continue;
+            const gateTimeout = jobDef.timeout !== undefined
+                ? timeoutReject(jobDef.timeout, `job-runner: boot gate "${name}" did not finish within ${jobDef.timeout}ms`)
+                : undefined;
+            const slowWarnTimer = gateTimeout === undefined
+                ? setTimeout(() => {
+                    errorLogger.warn("boot gate still running, no timeout configured", {
+                        gate: name,
+                        afterMs: BOOT_GATE_SLOW_WARN_MS,
+                    });
+                }, BOOT_GATE_SLOW_WARN_MS)
+                : undefined;
             try {
-                await handleJob({
-                    id: bootJobIdForJobName(name),
-                    name,
-                    data: {},
-                    attemptsMade: 0,
-                    retryable: false,
-                });
+                await Promise.race([
+                    handleJob({
+                        id: bootJobIdForJobName(name),
+                        name,
+                        data: {},
+                        attemptsMade: 0,
+                        retryable: false,
+                    }),
+                    ...(gateTimeout ? [gateTimeout.promise] : []),
+                ]);
             }
             catch (err) {
                 // The worker is already consuming here; leaving its Redis connections
@@ -892,6 +909,11 @@ export function createJobRunner(options) {
                 worker = null;
                 throw err;
             }
+            finally {
+                gateTimeout?.cancel();
+                if (slowWarnTimer !== undefined)
+                    clearTimeout(slowWarnTimer);
+            }
         }
     }
     const runnerApi = {

package/dist/observability/index.d.ts

@@ -12,5 +12,5 @@ export { type MetricEvent, type MetricEventHandler, RecordingMeter, } from "./re
 export { type RecordedSpan, RecordingTracer, type RecordingTracerOptions, serializeSpanContext, } from "./recording-tracer.js";
 export { wrapRedisClient } from "./redis-wrapper.js";
 export { DEFAULT_SENSITIVE_CONFIG, mergeSensitiveConfig, REDACTED, redactAttributes, redactHeaders, redactQueryString, redactValue, shouldRedactAttribute, } from "./sensitive-filter.js";
-export { emitDbQuery, emitDispatcherError, emitDispatcherHandler, emitEventConsumerLag, emitEventConsumerPassOutcome, emitEventConsumerRearmExhausted, emitEventDispatcherListenConnected, emitHttpRequest, emitJobLastSuccess, emitJobQueueDepth, registerStandardMetrics, STANDARD_METRIC_DEFS, } from "./standard-metrics.js";
+export { emitDbQuery, emitDispatcherError, emitDispatcherHandler, emitEventConsumerLag, emitEventConsumerPassOutcome, emitEventConsumerPassSkipped, emitEventConsumerRearmExhausted, emitEventDispatcherListenConnected, emitHttpRequest, emitJobLastSuccess, emitJobQueueDepth, registerStandardMetrics, STANDARD_METRIC_DEFS, } from "./standard-metrics.js";
 export type { Counter, Gauge, Histogram, Meter, MetricDefinition, MetricLabels, MetricsHandle, MetricType, ObservabilityOptions, ObservabilityProvider, SamplingConfig, SensitiveFilterConfig, SerializedTraceContext, Span, SpanAttributes, SpanAttributeValue, SpanKind, SpanStatus, StartSpanOptions, Tracer, } from "./types/index.js";

package/dist/observability/index.js

@@ -13,4 +13,4 @@ export { RecordingMeter, } from "./recording-meter.js";
 export { RecordingTracer, serializeSpanContext, } from "./recording-tracer.js";
 export { wrapRedisClient } from "./redis-wrapper.js";
 export { DEFAULT_SENSITIVE_CONFIG, mergeSensitiveConfig, REDACTED, redactAttributes, redactHeaders, redactQueryString, redactValue, shouldRedactAttribute, } from "./sensitive-filter.js";
-export { emitDbQuery, emitDispatcherError, emitDispatcherHandler, emitEventConsumerLag, emitEventConsumerPassOutcome, emitEventConsumerRearmExhausted, emitEventDispatcherListenConnected, emitHttpRequest, emitJobLastSuccess, emitJobQueueDepth, registerStandardMetrics, STANDARD_METRIC_DEFS, } from "./standard-metrics.js";
+export { emitDbQuery, emitDispatcherError, emitDispatcherHandler, emitEventConsumerLag, emitEventConsumerPassOutcome, emitEventConsumerPassSkipped, emitEventConsumerRearmExhausted, emitEventDispatcherListenConnected, emitHttpRequest, emitJobLastSuccess, emitJobQueueDepth, registerStandardMetrics, STANDARD_METRIC_DEFS, } from "./standard-metrics.js";

package/dist/observability/standard-metrics.d.ts

@@ -32,6 +32,10 @@ export declare function emitEventConsumerRearmExhausted(meter: Meter, labels: {
     readonly consumer: string;
     readonly instanceId: string;
 }): void;
+export declare function emitEventConsumerPassSkipped(meter: Meter, labels: {
+    readonly consumer: string;
+    readonly instanceId: string;
+}, reason: "idle"): void;
 export declare function emitEventDispatcherListenConnected(meter: Meter, connected: boolean): void;
 export declare function emitEventConsumerPassOutcome(meter: Meter, labels: {
     readonly consumer: string;

package/dist/observability/standard-metrics.js

@@ -93,6 +93,15 @@ export const STANDARD_METRIC_DEFS = [
         description: "Consumer transitioned to dead with its auto-rearm budget exhausted.",
         labels: ["consumer", "instance_id"],
     },
+    // An idle-gated consumer turn opens no events.consumer.pass span (the lock-free
+    // pre-check proves there is nothing to do), so this counter is the only trace of
+    // per-tick pass frequency for consumers that are idle or disabled.
+    {
+        name: "kumiko_event_consumer_pass_skipped_total",
+        type: "counter",
+        description: "Consumer turns skipped before opening a pass span because the idle pre-check proved nothing to deliver.",
+        labels: ["consumer", "instance_id", "reason"],
+    },
     // LISTEN-subscription health. 1 = active, 0 = dropped. Drops to 0 while
     // the dispatcher is running signal that delivery latency has regressed
     // from sub-millisecond (LISTEN) to pollIntervalMs (timer fallback); ops
@@ -203,6 +212,13 @@ export function emitEventConsumerRearmExhausted(meter, labels) {
         instance_id: labels.instanceId,
     });
 }
+export function emitEventConsumerPassSkipped(meter, labels, reason) {
+    meter.counter("kumiko_event_consumer_pass_skipped_total").inc(1, {
+        consumer: labels.consumer,
+        instance_id: labels.instanceId,
+        reason,
+    });
+}
 export function emitEventDispatcherListenConnected(meter, connected) {
     meter.gauge("kumiko_event_dispatcher_listen_connected").set(connected ? 1 : 0);
 }

package/dist/pipeline/event-dispatcher-delivery.js

@@ -105,6 +105,11 @@ export async function selectConsumerCursorForUpdate(db, name, instanceId) {
 // pre-check reads pending_gaps live on every pass, so it observes that gap
 // too. In short: this can under-report idleness for one tick, never
 // over-report it.
+//
+// Observability: an idle turn opens no events.consumer.pass span (so no
+// consumer.skip_reason either, including for a disabled consumer with nothing
+// pending); the dispatcher counts it in
+// kumiko_event_consumer_pass_skipped_total{reason="idle"} instead.
 export async function selectIdleConsumerKeys(db, pairs) {
     if (pairs.length === 0)
         return new Set();

package/dist/pipeline/event-dispatcher.js

@@ -1,7 +1,7 @@
 import { selectSnapshotXmax, selectSnapshotXmin } from "../db/queries/event-consumer.js";
 import { SYSTEM_TENANT_ID } from "../engine/types/identifiers.js";
 import { EVENTS_PUBSUB_CHANNEL } from "../event-store/index.js";
-import { emitEventConsumerPassOutcome, emitEventConsumerRearmExhausted, emitEventDispatcherListenConnected, getFallbackMeter, getFallbackTracer, } from "../observability/index.js";
+import { emitEventConsumerPassOutcome, emitEventConsumerPassSkipped, emitEventConsumerRearmExhausted, emitEventDispatcherListenConnected, getFallbackMeter, getFallbackTracer, } from "../observability/index.js";
 import { SHARED_INSTANCE_SENTINEL } from "./event-consumer-state.js";
 import { acquireConsumerState, consumerInstanceId, deliverEvents, emitLagFromTx, fetchPendingEvents, markProcessing, persistConsumerOutcome, persistConsumerPassFailure, preRegisterConsumers, selectIdleConsumerKeys, } from "./event-dispatcher-delivery.js";
 import { partitionBurntGaps, splitRangeExcludingIds, toIdRanges } from "./pending-gap-ranges.js";
@@ -132,8 +132,11 @@ export function createEventDispatcher(options) {
         // backoff-gate above already confirmed retryAtMs has elapsed, and
         // "provably nothing to deliver" is itself proof the consumer isn't
         // presently failing.
+        // No events.consumer.pass span is opened here (so no consumer.skip_reason either),
+        // which is why the skip is counted instead.
         if (idleKeys.has(key)) {
             consumerBackoff.delete(key);
+            emitEventConsumerPassSkipped(meter, { consumer: consumer.name, instanceId: consumerInstanceId(consumer, options.instanceId) }, "idle");
             return { processed: 0, failed: 0 };
         }
         // Registered before awaiting the slot — a turn queued behind the

package/dist/pipeline/system-hooks.js

@@ -366,19 +366,17 @@ export async function buildSearchDocument(entityName, entityId, state, registry)
 }
 // --- SSE Broadcast (async, via event-dispatcher) ---
 //
-// SSE-Broadcast läuft seit D.3 als async EventConsumer über den event-
-// dispatcher, nicht mehr als synchroner postSave/postDelete-hook. Das hat
-// zwei Konsequenzen:
+// The SSE broadcast runs as an async EventConsumer on the event dispatcher,
+// not as a synchronous postSave/postDelete hook. Two consequences:
 //
-// 1. **Event-native Payload-Shape.** Der SSE-event spiegelt den StoredEvent:
-//    `type` ist event.type ("user.created", "unit.updated"), `data` enthält
-//    id, aggregateType, version und die event-payload — keine künstliche
-//    "system:event:<entity>:<verb>" Hülle mehr. Clients haben direkten
-//    Zugriff auf `payload.changes` + `payload.previous` (wie im event-log).
-// 2. **Eventual consistency statt Read-after-Write.** Ein SSE-Event kommt
-//    ~10–100ms nach dem HTTP-200 (abhängig von pollIntervalMs). UI-Clients
-//    die auf optimistic-update setzen merken das nicht; strictly-waiting
-//    Clients müssten poll-after-write.
+// 1. **Signal only.** The frame mirrors the StoredEvent's identity: `type` is
+//    event.type ("user.created"), `data` holds id, aggregateType, version and
+//    createdAt, never the payload. The tenant channel fans out to every member
+//    and to anonymous connections, so field values must not enter the broker
+//    or Redis; the client refetches through a query with its own access check.
+// 2. **Eventual consistency, not read-after-write.** A frame arrives roughly
+//    10 to 100 ms after the HTTP 200 (depends on pollIntervalMs). Clients that
+//    must observe their own write poll after writing.
 //
 // Tests drain deterministically via `await stack.eventDispatcher.runOnce()`,
 // or via `drainEventConsumers` for this consumer name specifically.
@@ -402,7 +400,6 @@ export function createSseBroadcastEventConsumer(sseBroker) {
                     id: event.aggregateId,
                     aggregateType: event.aggregateType,
                     version: event.version,
-                    payload: event.payload,
                     createdAt: event.createdAt,
                 },
             });

package/dist/pipeline/write-origin.js

@@ -49,8 +49,14 @@ export function rootWriteOrigin(registry, type, user) {
 // Owner binding is ignored (honorOwnerBinding=false): all anonymous callers share one
 // user id, so from("user:id", ...) vouches for nobody.
 const personalDataTableMaps = new WeakMap();
+const personalColumnsByEntity = new WeakMap();
 function personalColumnNames(entity) {
-    return new Set([...personalFieldNames(entity, false)].map(toSnakeCase));
+    const cached = personalColumnsByEntity.get(entity);
+    if (cached)
+        return cached;
+    const columns = new Set([...personalFieldNames(entity, false)].map(toSnakeCase));
+    personalColumnsByEntity.set(entity, columns);
+    return columns;
 }
 function buildPersonalDataTableMap(registry) {
     const map = new Map();
@@ -73,21 +79,22 @@ function personalDataTableMap(registry) {
     personalDataTableMaps.set(registry, built);
     return built;
 }
-// Names fields only, never values: the error reaches the anonymous HTTP caller.
+// The error reaches the anonymous HTTP caller, so table and column names stay out of
+// message/details (they would map the DB schema); they travel in `cause`, which the
+// serializer never sends to clients. The 4xx log line carries only status and code, so
+// `cause` is not logged today; it is only available to in-process error handling.
 export function publicIntakeRequiredError(origin, target, fields) {
     return new AccessDeniedError({
-        message: `Anonymous root handler "${origin.rootHandler}" wrote personal-data field(s) ` +
-            `${fields.map((f) => `"${f}"`).join(", ")} on "${target}"` +
+        message: `Anonymous root handler "${origin.rootHandler}" wrote personal data` +
             (origin.viaJob ? ` via job "${origin.viaJob}"` : "") +
             '. Declare access: { roles: [..., "anonymous"], personalData: "public-intake" } on ' +
             `"${origin.rootHandler}" to allow anonymous callers to write personal data.`,
         details: {
             reason: FrameworkReasons.publicIntakeRequired,
             rootHandler: origin.rootHandler,
-            target,
-            fields,
             ...(origin.viaJob !== undefined && { job: origin.viaJob }),
         },
+        cause: new Error(`personal-data field(s) ${fields.map((f) => `"${f}"`).join(", ")} written on "${target}"`),
     });
 }
 // Without an entity the table name is looked up in the registry map; tables outside it

package/dist/stack/drain-event-consumers.js

@@ -17,6 +17,9 @@ export async function drainEventConsumers(stack, consumerNames, options) {
             "multiStreamProjection is wired for this stack.");
     }
     const maxPasses = options?.maxPasses ?? DEFAULT_MAX_PASSES;
+    if (!Number.isInteger(maxPasses) || maxPasses < 1) {
+        throw new Error("drainEventConsumers: maxPasses must be a positive integer");
+    }
     const target = await getEventsHighWaterMark(db);
     for (let pass = 0; pass < maxPasses; pass++) {
         await eventDispatcher.runOnce();

package/dist/stack/drain-jobs.d.ts

@@ -17,4 +17,6 @@ export type DrainJobsStack = {
     readonly eventDispatcher?: EventDispatcher;
     readonly jobRunner?: JobRunner;
 };
-export declare function drainJobs(stack: DrainJobsStack, tracker: JobFailureTracker): Promise<void>;
+export declare function drainJobs(stack: DrainJobsStack, tracker: JobFailureTracker, options?: {
+    readonly timeoutMs?: number;
+}): Promise<void>;

package/dist/stack/drain-jobs.js

@@ -12,6 +12,9 @@ const DRAIN_IDLE_POLL_MS = 25;
 // enqueue that lands just after the first idle read still gets picked up
 // by the second pass instead of racing straight past it.
 const REQUIRED_IDLE_PASSES = 2;
+// Below the 15s per-test budget so a stuck drain reports what is open rather
+// than surfacing as a bare test timeout.
+const DEFAULT_DRAIN_TIMEOUT_MS = 10_000;
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -47,6 +50,26 @@ export function createJobFailureTracker() {
         },
     };
 }
+// Diagnostic only: lets the deadline error name what was still open.
+async function describeLaggingConsumers(db, consumerNames) {
+    // skip: no shared consumers wired — nothing to catch up on.
+    if (consumerNames.length === 0)
+        return [];
+    const target = await getEventsHighWaterMark(db);
+    const lagging = [];
+    for (const name of consumerNames) {
+        const state = await getConsumerState(db, name);
+        if (state && state.lastProcessedEventId < target) {
+            lagging.push(`${name} (status=${state.status}, lastProcessedEventId=${state.lastProcessedEventId}, target=${target})`);
+        }
+    }
+    return lagging;
+}
+async function drainTimeoutError(db, consumerNames, timeoutMs, pending) {
+    const lagging = await describeLaggingConsumers(db, consumerNames);
+    return new Error(`drainJobs: not drained after ${timeoutMs}ms — pending jobs: ${pending}, ` +
+        `consumers behind: ${lagging.length === 0 ? "none" : lagging.join("; ")}`);
+}
 async function sharedConsumersCaughtUp(db, consumerNames) {
     // skip: no shared consumers wired — nothing to catch up on.
     if (consumerNames.length === 0)
@@ -66,8 +89,12 @@ async function sharedConsumersCaughtUp(db, consumerNames) {
     }
     return allCaughtUp;
 }
-export async function drainJobs(stack, tracker) {
+// Fails a stuck drain with a diagnosis instead of a generic test-runner timeout.
+// It only bounds the loop; it never replaces waiting for real work.
+export async function drainJobs(stack, tracker, options) {
     const { db, eventDispatcher, jobRunner } = stack;
+    const timeoutMs = options?.timeoutMs ?? DEFAULT_DRAIN_TIMEOUT_MS;
+    const deadline = Date.now() + timeoutMs;
     if (!jobRunner) {
         throw new Error("drainJobs: stack.jobRunner is undefined — pass `jobs: {...}` to setupTestStack and " +
             "register at least one r.job(...) so a runner is built.");
@@ -84,6 +111,9 @@ export async function drainJobs(stack, tracker) {
                 const caughtUp = await sharedConsumersCaughtUp(db, sharedConsumerNames);
                 consecutiveIdlePasses = pending === 0 && caughtUp ? consecutiveIdlePasses + 1 : 0;
                 if (consecutiveIdlePasses < REQUIRED_IDLE_PASSES) {
+                    if (Date.now() > deadline) {
+                        throw await drainTimeoutError(db, sharedConsumerNames, timeoutMs, pending);
+                    }
                     await Promise.race([tracker.waitForActivity(), sleep(DRAIN_IDLE_POLL_MS)]);
                 }
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.335.0",
+  "version": "0.336.0",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -206,8 +206,8 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-http": "0.335.0",
-    "@cosmicdrift/kumiko-types": "0.335.0",
+    "@cosmicdrift/kumiko-http": "0.336.0",
+    "@cosmicdrift/kumiko-types": "0.336.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.13.1",
@@ -223,7 +223,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.335.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.336.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/changes.json

@@ -1,4 +1,62 @@
 [
+  {
+    "version": "0.336.0",
+    "type": "fix",
+    "title": "Boot gates with an explicit timeout reject start() naming the gate; gates without one warn after 60s",
+    "detail": "A `bootGate` job with an explicit `timeout` now rejects `start()` with a message naming the gate once that timeout elapses. Without `timeout` the gate keeps waiting and logs a warning naming it after 60s instead of blocking boot silently."
+  },
+  {
+    "version": "0.336.0",
+    "type": "fix",
+    "title": "Boot rejects unknown visibleWhen fields, bootGate with runOnBoot, and unknown money currency kinds",
+    "detail": "Boot now rejects three misconfigurations that previously failed silently: a dashboard screen-panel `visibleWhen.field` that is missing from the query's declared `outputSchema`, a job that combines `bootGate` with `runOnBoot` (it ran twice under one job id), and a money field whose `currency` source has an unknown `kind`. `auth-mfa:query:user-mfa:status` now declares its `outputSchema`."
+  },
+  {
+    "version": "0.336.0",
+    "type": "fix",
+    "title": "Dry-run env output keeps multi-line field descriptions inside the comment",
+    "detail": "`KUMIKO_DRY_RUN_ENV` pulumi and k8s output now folds a multi-line `.describe()` text onto one comment line, so the continuation can no longer escape the `#` and run as a shell command or break the YAML stub. The `unprocessable-error-details-reason` codemod now skips a shorthand `reason` whose variable is only used in `details`."
+  },
+  {
+    "version": "0.336.0",
+    "type": "fix",
+    "title": "waitForEvent ne-match ignores payloads without the referenced path",
+    "detail": "`waitForEvent` match atoms no longer match events that lack the referenced payload path, so `ne` no longer wakes a workflow on an unrelated event shape. Explicit `undefined` optionals on `r.nav()` entries are dropped from the client schema."
+  },
+  {
+    "version": "0.336.0",
+    "type": "fix",
+    "title": "r.nav() explicit undefined optionals no longer reach the client schema"
+  },
+  {
+    "version": "0.336.0",
+    "type": "fix",
+    "title": "public_intake_required 403 no longer discloses table and column names to anonymous callers",
+    "detail": "The `public_intake_required` 403 no longer puts the physical table name and personal-data column names into `message` or `details` (it keeps `reason`, `rootHandler` and `job`); they travel in the error `cause` for the server log. The event dispatcher counts idle-gated consumer turns in the new `kumiko_event_consumer_pass_skipped_total{reason=\"idle\"}` counter, since those turns open no `events.consumer.pass` span. Personal-data column sets for the anonymous write gate are cached per entity."
+  },
+  {
+    "version": "0.336.0",
+    "type": "improvement",
+    "title": "Idle-gated event consumer turns are counted in kumiko_event_consumer_pass_skipped_total"
+  },
+  {
+    "version": "0.336.0",
+    "type": "breaking",
+    "title": "/api/sse sends change signals without field values; anonymous connections only for declared entities",
+    "detail": "The SSE broadcast consumer no longer puts the event payload (changes, previous) on the tenant channel, because that channel fans out to every tenant member and to anonymous connections. Entity frames carry `{ id, aggregateType, eventType, version, createdAt }`. Anonymous connections get entity signals only for entities named by an anonymously callable query via the new `liveEntities` option; the query name alone grants nothing, because a signal carries the id of every row, including rows the query filters out. Frames without an entity are delivered only when `data.userId` matches the connected user. Boot fails when `liveEntities` names an unregistered entity.",
+    "migration": "Code that reads `data.payload` from SSE frames must load the data with a query after the signal instead. Public pages that update anonymously add `liveEntities: [\"<entity>\"]` to the anonymous query they refetch (for example a `page:current` query), otherwise the live update stays off for anonymous visitors. `createSseRoute(broker)` now needs a second argument, `{ anonymousLiveEntities: collectAnonymousLiveEntities(registry) }`."
+  },
+  {
+    "version": "0.336.0",
+    "type": "fix",
+    "title": "drainEventConsumers rejects an invalid maxPasses and drainJobs fails a stuck drain with a diagnosis",
+    "detail": "`drainEventConsumers` rejects a non-positive or non-integer `maxPasses` instead of returning without draining, and `drainJobs` accepts `timeoutMs` (default 10s) and fails a stuck drain with the pending job count and the consumers still behind. The stance report names which hint category (direct, user-owned, user-reference) a near-miss field resembles, and the `UnprocessableError` reason codemod no longer reports spread literals without a `reason` key and lists non-analyzable `details` arguments as unverified."
+  },
+  {
+    "version": "0.336.0",
+    "type": "improvement",
+    "title": "Codemod reports name the near-miss hint category and separate unverified sites from manual skips"
+  },
   {
     "version": "0.335.0",
     "type": "fix",

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

@@ -440,6 +440,8 @@ function findTargetFiles(rootDir: string): string[] {
 
 export type StanceClass = "direct" | "user-owned" | "user-reference" | "near-miss" | "unclassified";
 
+export type HintCategory = "direct" | "user-owned" | "user-reference";
+
 export type StanceSite = {
   readonly line: number;
   readonly field: string;
@@ -447,14 +449,23 @@ export type StanceSite = {
   readonly callee: string;
   readonly stance: StanceClass;
   readonly hint: string | undefined;
+  readonly nearMissOf: HintCategory | undefined;
 };
 
-const ALL_PII_NAME_HINTS: readonly string[] = [
-  ...PII_DIRECT_NAME_HINTS,
-  ...PII_USER_OWNED_NAME_HINTS,
-  ...PII_USER_REFERENCE_NAME_HINTS,
+type CategorizedHint = readonly [hint: string, category: HintCategory];
+
+const ALL_PII_NAME_HINTS: readonly CategorizedHint[] = [
+  ...[...PII_DIRECT_NAME_HINTS].map((hint): CategorizedHint => [hint, "direct"]),
+  ...[...PII_USER_OWNED_NAME_HINTS].map((hint): CategorizedHint => [hint, "user-owned"]),
+  ...[...PII_USER_REFERENCE_NAME_HINTS].map((hint): CategorizedHint => [hint, "user-reference"]),
 ];
 
+type FieldClassification = {
+  readonly stance: StanceClass;
+  readonly hint: string | undefined;
+  readonly nearMissOf: HintCategory | undefined;
+};
+
 const REPORT_STANCE_CALLEES = new Set(["createTextField", "createLongTextField"]);
 
 // Mirrors guard-text-field-stance.ts's hasPersonalStance exactly.
@@ -539,11 +550,15 @@ function hintOccursAtBoundary(fieldLower: string, fieldOriginal: string, hint: s
   }
 }
 
-function findLongestBoundaryHint(fieldLower: string, fieldOriginal: string): string | undefined {
-  let best: string | undefined;
-  for (const hint of ALL_PII_NAME_HINTS) {
-    if (best && hint.length <= best.length) continue;
-    if (hintOccursAtBoundary(fieldLower, fieldOriginal, hint)) best = hint;
+function findLongestBoundaryHint(
+  fieldLower: string,
+  fieldOriginal: string,
+): CategorizedHint | undefined {
+  let best: CategorizedHint | undefined;
+  for (const entry of ALL_PII_NAME_HINTS) {
+    const [hint] = entry;
+    if (best && hint.length <= best[0].length) continue;
+    if (hintOccursAtBoundary(fieldLower, fieldOriginal, hint)) best = entry;
   }
   return best;
 }
@@ -564,29 +579,36 @@ function segmentAlignedSuffixes(fieldOriginal: string): string[] {
 // (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;
+function findShortestHintContainingSuffix(fieldOriginal: string): CategorizedHint | undefined {
+  let best: CategorizedHint | undefined;
   for (const suffix of segmentAlignedSuffixes(fieldOriginal)) {
     if (suffix.length < 5) continue;
-    for (const hint of ALL_PII_NAME_HINTS) {
+    for (const entry of ALL_PII_NAME_HINTS) {
+      const [hint] = entry;
       if (hint === suffix || !hint.endsWith(suffix)) continue;
-      if (!best || hint.length < best.length) best = hint;
+      if (!best || hint.length < best[0].length) best = entry;
     }
   }
   return best;
 }
 
-function classifyFieldStance(field: string): { stance: StanceClass; hint: string | undefined } {
+function classifyFieldStance(field: string): FieldClassification {
   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(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 };
+  if (PII_DIRECT_NAME_HINTS.has(fieldLower)) {
+    return { stance: "direct", hint: fieldLower, nearMissOf: undefined };
+  }
+  if (PII_USER_OWNED_NAME_HINTS.has(fieldLower)) {
+    return { stance: "user-owned", hint: fieldLower, nearMissOf: undefined };
+  }
+  if (PII_USER_REFERENCE_NAME_HINTS.has(fieldLower)) {
+    return { stance: "user-reference", hint: fieldLower, nearMissOf: undefined };
+  }
+  const nearMiss =
+    findLongestBoundaryHint(field.toLowerCase(), field) ?? findShortestHintContainingSuffix(field);
+  if (nearMiss) {
+    return { stance: "near-miss", hint: nearMiss[0], nearMissOf: nearMiss[1] };
+  }
+  return { stance: "unclassified", hint: undefined, nearMissOf: undefined };
 }
 
 function createReportStanceProject(): Project {
@@ -627,9 +649,9 @@ function collectStanceSites(sourceFile: SourceFile): StanceSite[] {
     // A call with no enclosing field (e.g. a bare createTextField() at top
     // level) has no real name to classify — `createTextField(...)` would
     // otherwise false-positive as a near-miss on its own "Text".
-    const { stance, hint } = enclosingField
+    const { stance, hint, nearMissOf }: FieldClassification = enclosingField
       ? classifyFieldStance(enclosingField)
-      : { stance: "unclassified" as const, hint: undefined };
+      : { stance: "unclassified", hint: undefined, nearMissOf: undefined };
 
     sites.push({
       line: call.getStartLineNumber(),
@@ -638,6 +660,7 @@ function collectStanceSites(sourceFile: SourceFile): StanceSite[] {
       callee,
       stance,
       hint,
+      nearMissOf,
     });
   }
   return sites;
@@ -656,6 +679,13 @@ function findReportStanceFiles(rootDir: string): string[] {
   return files.sort();
 }
 
+function formatHintSuffix(site: StanceSite): string {
+  if (!site.hint) return "";
+  return site.nearMissOf
+    ? ` (hint: ${site.hint}, near ${site.nearMissOf})`
+    : ` (hint: ${site.hint})`;
+}
+
 function reportStance(rootDir: string): void {
   console.log(
     `Scanning every .ts/.tsx under ${rootDir} except node_modules/dist/build/*.d.ts — guard-text-field-stance scans packages/*/src/** only, so counts can differ outside that scope.`,
@@ -680,7 +710,7 @@ function reportStance(rootDir: string): void {
       totals[site.stance]++;
       total++;
       const entity = site.entity ?? "<unresolved>";
-      const hintSuffix = site.hint ? ` (hint: ${site.hint})` : "";
+      const hintSuffix = formatHintSuffix(site);
       console.log(
         `  ${site.line}  ${site.field}  entity=${entity}  ${site.callee}  ${site.stance}${hintSuffix}`,
       );