@cosmicdrift/kumiko-framework 0.290.0 → 0.292.0

package/src/jobs/job-runner.ts

@@ -18,10 +18,12 @@ import {
   SYSTEM_TENANT_ID,
   type TenantId,
 } from "../engine/types";
+import { isKumikoError } from "../errors/kumiko-error";
 import { createFileContext } from "../files/file-handle";
 import { createFallbackLogger } from "../logging";
 import type { Logger } from "../logging/types";
 import {
+  emitJobLastSuccess,
   emitJobQueueDepth,
   getFallbackTracer,
   type Meter,
@@ -139,6 +141,55 @@ export type JobMeta = {
   priority?: number | undefined;
 };
 
+// What a finished run tells the run-logger about the tenant-visible failure
+// record (`JobDefinition.tenantVisibleFailure`). `tenantVisible` is set only
+// when the job opted in; `messageKey` is null on the success path, where the
+// record is cleared rather than written.
+export type JobOutcomeMeta = {
+  readonly tenantId: string;
+  readonly finalAttempt: boolean;
+  readonly tenantVisible?:
+    | { readonly subject: string | null; readonly messageKey: string | null }
+    | undefined;
+};
+
+// Stable identity for the declared payload fields: sorted keys, so two runs
+// with the same subject values produce the same string and the later one
+// replaces the earlier record. Non-primitives would serialize into something
+// no caller can reconstruct for a lookup, so they fail the run loudly.
+function jobSubjectKey(
+  jobName: string,
+  payload: Record<string, unknown>,
+  fields: readonly string[] | undefined,
+): string | null {
+  if (fields === undefined || fields.length === 0) return null;
+  const entries: [string, string | number | boolean | null][] = [];
+  for (const field of [...fields].sort()) {
+    const value = payload[field] ?? null;
+    if (value !== null && typeof value === "object") {
+      throw new Error(
+        `Job "${jobName}": tenantVisibleFailure.subjectFields["${field}"] must be a primitive, got ${typeof value}`,
+      );
+    }
+    entries.push([field, value as string | number | boolean | null]);
+  }
+  return JSON.stringify(entries);
+}
+
+// Only a translation key ever travels to the tenant: the thrown error's own
+// i18nKey when it carries one, otherwise the key declared at the job. The
+// error message itself can echo provider or payload content and stays on the
+// run row and in the run log.
+function tenantFailureMessageKey(
+  err: unknown,
+  declaration: JobDefinition["tenantVisibleFailure"],
+): string | null {
+  // skip: job did not opt in — nothing tenant-visible to record
+  if (!declaration) return null;
+  if (isKumikoError(err) && err.i18nKey.length > 0) return err.i18nKey;
+  return declaration.messageKey;
+}
+
 export type JobRunner = {
   start(): Promise<void>;
   stop(): Promise<void>;
@@ -176,8 +227,20 @@ export type JobRunnerOptions = {
   bootRedisTimeoutMs?: number | undefined;
   getActiveTenantIds?: () => Promise<TenantId[]>;
   onJobStart?: (jobName: string, jobId: string, meta: JobMeta) => void;
-  onJobComplete?: (jobName: string, jobId: string, duration: number, logs: JobLogEntry[]) => void;
-  onJobFailed?: (jobName: string, jobId: string, error: string, logs: JobLogEntry[]) => void;
+  onJobComplete?: (
+    jobName: string,
+    jobId: string,
+    duration: number,
+    logs: JobLogEntry[],
+    outcome?: JobOutcomeMeta,
+  ) => void;
+  onJobFailed?: (
+    jobName: string,
+    jobId: string,
+    error: string,
+    logs: JobLogEntry[],
+    outcome?: JobOutcomeMeta,
+  ) => void;
 };
 
 // Serialized trace context lives under this key in the BullMQ job data.
@@ -527,6 +590,24 @@ export function createJobRunner(options: JobRunnerOptions): JobRunner {
       SYSTEM_TENANT_ID;
     const triggeredById = (rawData["_triggeredById"] as string | undefined) ?? null; // @cast-boundary dynamic-key
 
+    // Tenant-visible failure record (JobDefinition.tenantVisibleFailure). The
+    // subject is read from the handler payload, so it is resolved here where
+    // the payload is built, not in the callbacks.
+    const tenantVisibleDecl = jobDef.tenantVisibleFailure;
+    const tenantVisibleSubject = tenantVisibleDecl
+      ? jobSubjectKey(jobName, payload, tenantVisibleDecl.subjectFields)
+      : null;
+    // BullMQ stops retrying once attemptsMade reaches the configured attempts
+    // (`retries + 1`), so this is the attempt whose failure is final.
+    const finalAttempt = bullJob.attemptsMade + 1 >= (jobDef.retries ?? 0) + 1;
+    const outcomeMeta = (messageKey: string | null): JobOutcomeMeta => ({
+      tenantId,
+      finalAttempt,
+      ...(tenantVisibleDecl && {
+        tenantVisible: { subject: tenantVisibleSubject, messageKey },
+      }),
+    });
+
     // Carry `_triggerName` from rawData when set — handleEvent injects it on
     // multi-trigger dispatch; exposed as jobContext.triggerName so handlers
     // don't dig through the raw payload themselves.
@@ -676,12 +757,21 @@ export function createJobRunner(options: JobRunnerOptions): JobRunner {
           },
           () => jobDef.handler(payload, jobContext),
         );
+        // Stamped before the observer hook: a throwing onJobComplete must not
+        // make a run that actually succeeded look dead to the liveness alert.
+        if (context.meter) emitJobLastSuccess(context.meter, jobName);
         const duration = Date.now() - startTime;
-        await options.onJobComplete?.(jobName, jobId, duration, logs);
+        await options.onJobComplete?.(jobName, jobId, duration, logs, outcomeMeta(null));
       } catch (err) {
         const errorMsg = err instanceof Error ? err.message : String(err);
         logs.push({ level: "error", message: errorMsg, timestamp: Temporal.Now.instant() });
-        await options.onJobFailed?.(jobName, jobId, errorMsg, logs);
+        await options.onJobFailed?.(
+          jobName,
+          jobId,
+          errorMsg,
+          logs,
+          outcomeMeta(tenantFailureMessageKey(err, tenantVisibleDecl)),
+        );
         throw err;
       }
     };

package/src/logging/utils.ts

@@ -2,18 +2,27 @@ import type { Logger } from "./types";
 
 type FallbackLogger = {
   error(msg: string, data?: Record<string, unknown>): void;
+  warn(msg: string, data?: Record<string, unknown>): void;
   debug(msg: string, data?: Record<string, unknown>): void;
 };
 
 export function createFallbackLogger(
   namespace: string,
-  logger?: (Pick<Logger, "error"> & Partial<Pick<Logger, "debug">>) | undefined,
+  logger?: (Pick<Logger, "error"> & Partial<Pick<Logger, "warn" | "debug">>) | undefined,
 ): FallbackLogger {
   if (logger) {
     return {
       error(msg, data) {
         logger.error(`[${namespace}] ${msg}`, data);
       },
+      warn(msg, data) {
+        if (logger.warn) {
+          logger.warn(`[${namespace}] ${msg}`, data);
+        } else {
+          // biome-ignore lint/suspicious/noConsole: ops-visible fallback when the wrapped logger has no warn method
+          console.warn(`[${namespace}] ${msg}`, data);
+        }
+      },
       debug(msg, data) {
         if (logger.debug) {
           logger.debug(`[${namespace}] ${msg}`, data);
@@ -29,6 +38,10 @@ export function createFallbackLogger(
       // biome-ignore lint/suspicious/noConsole: ops-visible fallback when no logger is wired
       console.error(`[${namespace}] ${msg}`, data);
     },
+    warn(msg, data) {
+      // biome-ignore lint/suspicious/noConsole: ops-visible fallback when no logger is wired
+      console.warn(`[${namespace}] ${msg}`, data);
+    },
     debug(msg, data) {
       // biome-ignore lint/suspicious/noConsole: ops-visible fallback when no logger is wired
       console.debug(`[${namespace}] ${msg}`, data);

package/src/observability/index.ts

@@ -54,6 +54,7 @@ export {
   emitEventConsumerRearmExhausted,
   emitEventDispatcherListenConnected,
   emitHttpRequest,
+  emitJobLastSuccess,
   emitJobQueueDepth,
   registerStandardMetrics,
   STANDARD_METRIC_DEFS,

package/src/observability/standard-metrics.ts

@@ -123,6 +123,19 @@ export const STANDARD_METRIC_DEFS: readonly MetricDefinition[] = [
     description: "BullMQ job counts per lane and state.",
     labels: ["lane", "state"],
   },
+  // Dead-man for in-process jobs: the k8s CronJob alerts never fire for them
+  // (no CronJob object exists), and a gauge the job itself sets freezes on its
+  // last value when the job dies, so neither `absent()` nor a threshold
+  // catches a silently stopped cron. This one is stamped by the runner, so
+  // `time() - kumiko_job_last_success_timestamp_seconds{job="…"} > interval`
+  // is a true liveness check. Absent until the first success after a restart —
+  // see docs/reference/job-liveness-metric.md for the `for:` that implies.
+  {
+    name: "kumiko_job_last_success_timestamp_seconds",
+    type: "gauge",
+    description: "Unix timestamp of the last successful run, per registered job.",
+    labels: ["job"],
+  },
 ] as const;
 
 export function registerStandardMetrics(meter: Meter): void {
@@ -273,3 +286,10 @@ export function emitJobQueueDepth(
     meter.gauge("kumiko_job_queue_depth").set(count, { lane, state });
   }
 }
+
+// `job` is the registry-declared job name — handleJob rejects an unknown name
+// before it can reach here, so the label set is bounded by the app's r.job
+// registrations and carries no tenant or user input.
+export function emitJobLastSuccess(meter: Meter, job: string): void {
+  meter.gauge("kumiko_job_last_success_timestamp_seconds").set(Date.now() / 1000, { job });
+}

package/src/pipeline/__tests__/blind-index-rebuild-guard.integration.test.ts

@@ -0,0 +1,96 @@
+// projection-rebuild aborts instead of silently NULLing an already-populated
+// blind-index column when this process has no blind-index key configured
+// (fw#3091) — see assertNoBlindIndexLoss in db/queries/shadow-swap.ts.
+
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { resetBlindIndexKeyForTests } from "@cosmicdrift/kumiko-framework/testing";
+import { computeBlindIndex, configureBlindIndexKey, decodeBlindIndexKey } from "../../crypto";
+import { createEventStoreExecutor } from "../../db/event-store-executor";
+import { asRawClient } from "../../db/query";
+import { buildEntityTable } from "../../db/table-builder";
+import { createTenantDb, type TenantDb } from "../../db/tenant-db";
+import { createEntity, createRegistry, createTextField, defineFeature } from "../../engine";
+import { createEventsTable } from "../../event-store";
+import { createProjectionStateTable, rebuildProjection } from "../../pipeline";
+import { createTestDb, type TestDb, TestUsers, unsafeCreateEntityTable } from "../../stack";
+
+const TEST_KEY_B64 = Buffer.alloc(32, 9).toString("base64");
+const TEST_KEY = decodeBlindIndexKey(TEST_KEY_B64);
+
+const personEntity = createEntity({
+  table: "read_bidx_guard_persons",
+  fields: {
+    email: createTextField({ required: true, personal: "self", find: "exact" }),
+  },
+});
+const personFeature = defineFeature("bidxguardtest", (r) => {
+  r.entity("person", personEntity);
+});
+const personTable = buildEntityTable("person", personEntity);
+const implicitName = "bidxguardtest:projection:person-entity";
+
+const admin = TestUsers.admin;
+let testDb: TestDb;
+let tdb: TenantDb;
+const registry = createRegistry([personFeature]);
+const crud = createEventStoreExecutor(personTable, personEntity, { entityName: "person" });
+
+beforeAll(async () => {
+  testDb = await createTestDb();
+  await unsafeCreateEntityTable(testDb.db, personEntity, "person");
+  await createEventsTable(testDb.db);
+  await createProjectionStateTable(testDb.db);
+  tdb = createTenantDb(testDb.db, admin.tenantId);
+});
+
+afterAll(async () => {
+  await testDb.cleanup();
+});
+
+beforeEach(async () => {
+  await asRawClient(testDb.db).unsafe(
+    `TRUNCATE kumiko_events, read_bidx_guard_persons, kumiko_projections RESTART IDENTITY CASCADE`,
+  );
+  configureBlindIndexKey(TEST_KEY_B64);
+});
+
+afterEach(() => {
+  resetBlindIndexKeyForTests();
+});
+
+async function rawRow(id: string): Promise<Record<string, unknown>> {
+  const rows = await asRawClient(testDb.db).unsafe<Record<string, unknown>>(
+    `SELECT * FROM read_bidx_guard_persons WHERE id = $1`,
+    [id],
+  );
+  const row = rows[0];
+  if (!row) throw new Error(`no row for ${id}`);
+  return row;
+}
+
+describe("projection-rebuild — blind-index loss guard (fw#3091)", () => {
+  test("populated bidx column + no key in this process → rebuild throws, live table untouched", async () => {
+    const created = await crud.create({ email: "marc@example.com" }, admin, tdb);
+    if (!created.isSuccess) throw new Error("create failed");
+    const before = await rawRow(String(created.data.id));
+    expect(before["email_bidx"]).toBe(computeBlindIndex(TEST_KEY, "marc@example.com"));
+
+    resetBlindIndexKeyForTests();
+    await expect(rebuildProjection(implicitName, { db: testDb.db, registry })).rejects.toThrow(
+      /KUMIKO_BLIND_INDEX_KEY/,
+    );
+
+    const after = await rawRow(String(created.data.id));
+    expect(after).toEqual(before);
+  });
+
+  test("populated bidx column + key configured → rebuild succeeds, bidx recomputed", async () => {
+    const created = await crud.create({ email: "marc@example.com" }, admin, tdb);
+    if (!created.isSuccess) throw new Error("create failed");
+
+    await rebuildProjection(implicitName, { db: testDb.db, registry });
+
+    const after = await rawRow(String(created.data.id));
+    expect(after["email_bidx"]).toBe(computeBlindIndex(TEST_KEY, "marc@example.com"));
+  });
+});

package/src/pipeline/projection-rebuild.ts

@@ -9,6 +9,7 @@ import {
 import {
   assertLiveColumnsMatchMeta,
   assertLiveTableHasNoRowLevelSecurity,
+  assertNoBlindIndexLoss,
   assertNoUnreachableLiveRows,
   buildShadowTable,
   type ColumnDriftResult,
@@ -358,6 +359,12 @@ export async function rebuildProjection(
       if (skipped.length > 0) {
         await recordRebuildDeadLetters(tx, projectionName, skipped);
       }
+      // Guard the swap: abort if the process has no blind-index key configured
+      // but the live table already has populated bidx columns — the rebuild
+      // would otherwise silently null them out (fw#3091). Applies to every
+      // projection, not just implicit ones: the shadow always gets a fresh
+      // computeBlindIndexValues() pass regardless of projection kind.
+      await assertNoBlindIndexLoss(tx, meta.tableName, meta, projectionName);
       // Guard the swap: abort if the live table holds a row no event can
       // reconstruct (#498 ghost — direct-inserted without a .created event),
       // which the swap would silently drop. Implicit projections only.

package/src/schema-cli.ts

@@ -10,6 +10,12 @@
 
 import { existsSync, mkdirSync, readdirSync, writeFileSync } from "node:fs";
 import { join, resolve as resolvePath } from "node:path";
+import {
+  configureBlindIndexKey,
+  configurePiiSubjectKms,
+  type KmsWiring,
+  resolveKmsWiringAsync,
+} from "./crypto";
 import {
   assertValidMigrationName,
   baselineMigrations,
@@ -316,6 +322,7 @@ export async function runSchemaCli(
         return 1;
       }
       const { db, close } = createDbConnection(dbUrl);
+      let wiring: KmsWiring | undefined;
       try {
         const result = await runMigrationsFromDir(db, migrationsDir);
         // Framework-Infra-Tabellen (event-store + pipeline-state) — die erfasst
@@ -346,6 +353,19 @@ export async function runSchemaCli(
         // retry it — otherwise a failed rebuild is silently never retried,
         // since the migration itself is already tracked applied (#2464).
         if (options.features) {
+          // A rebuild replays applyEntityEvent, which computes bidx columns from
+          // configureBlindIndexKey/configurePiiSubjectKms — both boot-injected by
+          // run{Prod,Dev}App but never by this standalone CLI (the migrate-db
+          // initContainer). Without wiring them here, a rebuild would silently
+          // null out bidx columns and, for ciphertext, throw only once it hits
+          // the row (fw#3091).
+          wiring = await resolveKmsWiringAsync(process.env, {
+            logPrefix: "[kumiko schema apply]",
+          });
+          if ("kms" in wiring) {
+            configurePiiSubjectKms(wiring.kms);
+            configureBlindIndexKey(wiring.blindIndexKey);
+          }
           const thisRunTables = await queueRebuildsFromMarkers(db, {
             migrationsDir,
             appliedIds: result.applied,
@@ -376,6 +396,7 @@ export async function runSchemaCli(
         out.err("");
         return 1;
       } finally {
+        await wiring?.close();
         await close();
       }
     }

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

@@ -23,9 +23,11 @@
 //
 // Usage: bun scripts/codemod/pii-personal-migration.ts <targetDir> [--dry-run]
 
+import { readFileSync } from "node:fs";
 import { relative, resolve } from "node:path";
 import { Glob } from "bun";
 import {
+  type CallExpression,
   Node,
   type ObjectLiteralExpression,
   Project,
@@ -33,6 +35,11 @@ import {
   type SourceFile,
   SyntaxKind,
 } from "ts-morph";
+import {
+  PII_DIRECT_NAME_HINTS,
+  PII_USER_OWNED_NAME_HINTS,
+  PII_USER_REFERENCE_NAME_HINTS,
+} from "../../engine/boot-validator/entity-handler";
 
 const SUBJECT_FLAG_NAMES = [
   "pii",
@@ -431,11 +438,242 @@ function findTargetFiles(rootDir: string): string[] {
   return files.sort();
 }
 
+export type StanceClass = "direct" | "user-owned" | "user-reference" | "near-miss" | "unclassified";
+
+export type StanceSite = {
+  readonly line: number;
+  readonly field: string;
+  readonly entity: string | null;
+  readonly callee: string;
+  readonly stance: StanceClass;
+  readonly hint: string | undefined;
+};
+
+const ALL_PII_NAME_HINTS: readonly string[] = [
+  ...PII_DIRECT_NAME_HINTS,
+  ...PII_USER_OWNED_NAME_HINTS,
+  ...PII_USER_REFERENCE_NAME_HINTS,
+];
+
+const REPORT_STANCE_CALLEES = new Set(["createTextField", "createLongTextField"]);
+
+// Mirrors guard-text-field-stance.ts's hasPersonalStance exactly.
+function reportStanceHasPersonalStance(obj: ObjectLiteralExpression): boolean {
+  const prop = obj.getProperty("personal");
+  if (!prop || !Node.isPropertyAssignment(prop)) return false;
+  const init = prop.getInitializer();
+  return (
+    init !== undefined &&
+    init.getKind() !== SyntaxKind.UndefinedKeyword &&
+    !(Node.isIdentifier(init) && init.getText() === "undefined") &&
+    init.getKind() !== SyntaxKind.NullKeyword
+  );
+}
+
+function reportStanceEnclosingFieldName(call: CallExpression): string | undefined {
+  let node = call.getParent();
+  while (node) {
+    if (Node.isPropertyAssignment(node)) return node.getName();
+    node = node.getParent();
+  }
+  return undefined;
+}
+
+function reportStanceResolveEntity(call: CallExpression): string | null {
+  let node: Node | undefined = call.getParent();
+  let entityCall: CallExpression | undefined;
+  while (node) {
+    if (Node.isCallExpression(node)) {
+      const expr = node.getExpression();
+      if (Node.isIdentifier(expr) && expr.getText() === "createEntity") {
+        entityCall = node;
+        break;
+      }
+    }
+    node = node.getParent();
+  }
+  if (!entityCall) return null;
+
+  const firstArg = entityCall.getArguments()[0];
+  if (firstArg && Node.isObjectLiteralExpression(firstArg)) {
+    const tableProp = firstArg.getProperty("table");
+    if (tableProp && Node.isPropertyAssignment(tableProp)) {
+      const init = tableProp.getInitializer();
+      if (init && Node.isStringLiteral(init)) return init.getLiteralText();
+    }
+  }
+  const varDecl = entityCall.getParentIfKind(SyntaxKind.VariableDeclaration);
+  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 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;
+    searchFrom = index + 1;
+  }
+}
+
+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;
+  }
+  return best;
+}
+
+function segmentAlignedSuffixes(fieldOriginal: string): string[] {
+  const fieldLower = fieldOriginal.toLowerCase();
+  const suffixes: string[] = [];
+  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));
+  }
+  return suffixes;
+}
+
+// The hint sets only carry exact full names, so a suffix variant of one
+// (e.g. "...UserId" of "assigneeUserId") otherwise slips through undetected.
+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 (!best || hint.length < best.length) best = hint;
+    }
+  }
+  return best;
+}
+
+function classifyFieldStance(field: string): { stance: StanceClass; hint: string | undefined } {
+  const fieldLower = field.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);
+  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);
+
+  const sites: StanceSite[] = [];
+  for (const call of sourceFile.getDescendantsOfKind(SyntaxKind.CallExpression)) {
+    const exprNode = call.getExpression();
+    if (!Node.isIdentifier(exprNode)) continue;
+    const callee = exprNode.getText();
+    if (!REPORT_STANCE_CALLEES.has(callee)) continue;
+
+    const args = call.getArguments();
+    if (args.length > 0) {
+      const options = args[0];
+      if (!options || !Node.isObjectLiteralExpression(options)) continue;
+      if (options.getProperties().some((p) => p.isKind(SyntaxKind.SpreadAssignment))) continue;
+      if (reportStanceHasPersonalStance(options)) continue;
+    }
+
+    const enclosingField = reportStanceEnclosingFieldName(call);
+    // 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
+      ? classifyFieldStance(enclosingField)
+      : { stance: "unclassified" as const, hint: undefined };
+
+    sites.push({
+      line: call.getStartLineNumber(),
+      field: enclosingField ?? `${callee}(...)`,
+      entity: reportStanceResolveEntity(call),
+      callee,
+      stance,
+      hint,
+    });
+  }
+  return sites;
+}
+
+function findReportStanceFiles(rootDir: string): string[] {
+  const glob = new Glob("**/*.{ts,tsx}");
+  const EXCLUDE = ["/node_modules/", "/dist/", "/build/"];
+  const files: string[] = [];
+  for (const file of glob.scanSync({ cwd: rootDir, dot: false })) {
+    if (file.endsWith(".d.ts")) continue;
+    const abs = resolve(rootDir, file);
+    if (EXCLUDE.some((p) => abs.includes(p))) continue;
+    files.push(abs);
+  }
+  return files.sort();
+}
+
+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.`,
+  );
+
+  const totals: Record<StanceClass, number> = {
+    direct: 0,
+    "user-owned": 0,
+    "user-reference": 0,
+    "near-miss": 0,
+    unclassified: 0,
+  };
+  let total = 0;
+
+  for (const file of findReportStanceFiles(rootDir)) {
+    const sites = reportStanceForSource(readFileSync(file, "utf8"), file);
+    if (sites.length === 0) continue;
+
+    console.log(`\n${relative(rootDir, file)}`);
+    for (const site of sites) {
+      totals[site.stance]++;
+      total++;
+      const entity = site.entity ?? "<unresolved>";
+      const hintSuffix = site.hint ? ` (hint: ${site.hint})` : "";
+      console.log(
+        `  ${site.line}  ${site.field}  entity=${entity}  ${site.callee}  ${site.stance}${hintSuffix}`,
+      );
+    }
+  }
+
+  console.log("\nBy stance:");
+  for (const [stance, count] of Object.entries(totals)) {
+    if (count > 0) console.log(`  ${stance}: ${count}`);
+  }
+  console.log(`Total: ${total}`);
+
+  if (totals["near-miss"] > 0) {
+    console.log(
+      "\nHint sets in entity-handler.ts are exact name matches — near-miss field names slip past the boot heuristic.",
+    );
+  }
+}
+
 async function main(): Promise<void> {
   const positional = process.argv.slice(2).filter((a) => !a.startsWith("--"));
-  const dryRun = process.argv.includes("--dry-run");
   const rootDir = resolve(positional[0] ?? process.cwd());
 
+  if (process.argv.includes("--report-stance")) {
+    reportStance(rootDir);
+    // skip: report mode never rewrites, so the transform path below must not run
+    return;
+  }
+
+  const dryRun = process.argv.includes("--dry-run");
   const files = findTargetFiles(rootDir);
   const project = new Project({
     skipAddingFilesFromTsConfig: true,
@@ -477,4 +715,6 @@ async function main(): Promise<void> {
   }
 }
 
-await main();
+if (import.meta.main) {
+  await main();
+}

package/src/ui-types/list-row-meta.ts

@@ -12,7 +12,7 @@
 // deletedById) — this is also the SAME set the boot-validator's entityList
 // column checks accept, so a softDelete column stays a boot-time error
 // instead of a renderer-side throw (see screens.ts / entity-list-screens.ts).
-import { SYSTEM_TENANT_ID } from "../engine/types/identifiers";
+import { SYSTEM_TENANT_ID, SYSTEM_USER_ID } from "../engine/types/identifiers";
 
 export type ListRowMetaColumnType = "text" | "number" | "timestamp";
 
@@ -56,4 +56,7 @@ export type SystemReferenceLabel = {
 // entity, not just delivery-log (fw#2662).
 export const SYSTEM_REFERENCE_LABELS: Readonly<Record<string, SystemReferenceLabel>> = {
   "tenant:tenant": { id: SYSTEM_TENANT_ID, labelKey: "kumiko.reference.system-tenant" },
+  // createdBy on a system write (fw#3103) — SYSTEM_USER_ID is an alias for
+  // "no human caller", so read_users never holds a matching row.
+  "user:user": { id: SYSTEM_USER_ID, labelKey: "kumiko.reference.system-user" },
 };