@cosmicdrift/kumiko-framework 0.290.0 → 0.292.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.290.0",
+  "version": "0.292.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>",
@@ -198,8 +198,8 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-http": "0.290.0",
-    "@cosmicdrift/kumiko-types": "0.290.0",
+    "@cosmicdrift/kumiko-http": "0.292.0",
+    "@cosmicdrift/kumiko-types": "0.292.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.13.1",
@@ -215,7 +215,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.290.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.292.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/__tests__/pii-personal-migration-report-codemod.test.ts

@@ -0,0 +1,160 @@
+import { describe, expect, it } from "bun:test";
+import { reportStanceForSource } from "../scripts/codemod/pii-personal-migration";
+
+function wrapField(fieldSrc: string): string {
+  return `
+const entity = createEntity({
+  table: "entity_table",
+  fields: {
+    ${fieldSrc}
+  },
+});
+`;
+}
+
+describe("reportStanceForSource", () => {
+  it("classifies an exact PII_DIRECT_NAME_HINTS match", () => {
+    const [site] = reportStanceForSource(wrapField("email: createTextField({}),"), "t.ts");
+    expect(site?.stance).toBe("direct");
+    expect(site?.hint).toBe("email");
+  });
+
+  it("classifies an exact PII_USER_OWNED_NAME_HINTS match", () => {
+    const [site] = reportStanceForSource(wrapField("note: createTextField({}),"), "t.ts");
+    expect(site?.stance).toBe("user-owned");
+    expect(site?.hint).toBe("note");
+  });
+
+  it("classifies an exact PII_USER_REFERENCE_NAME_HINTS match", () => {
+    const [site] = reportStanceForSource(wrapField("authorId: createTextField({}),"), "t.ts");
+    expect(site?.stance).toBe("user-reference");
+    expect(site?.hint).toBe("authorid");
+  });
+
+  it("classifies a near-miss when a hint occurs at a segment boundary", () => {
+    const [site] = reportStanceForSource(
+      wrapField("advisorDisplayName: createTextField({}),"),
+      "t.ts",
+    );
+    expect(site?.stance).toBe("near-miss");
+    expect(site?.hint).toBe("displayname");
+  });
+
+  it("picks the longest hint on multiple boundary matches", () => {
+    const [site] = reportStanceForSource(
+      wrapField("customerEmailAddress: createTextField({}),"),
+      "t.ts",
+    );
+    expect(site?.stance).toBe("near-miss");
+    expect(site?.hint).toBe("address");
+  });
+
+  // No hint entry is a substring of "performedbyuserid" itself, but its
+  // segment-aligned suffix "userid" (>= 5 chars) is a substring of the
+  // full-name hints "createdbyuserid"/"updatedbyuserid"/"assigneeuserid" —
+  // the shortest of the three, "assigneeuserid", is reported.
+  it.each([
+    ["performedByUserId", "assigneeuserid"],
+    ["portalUserId", "assigneeuserid"],
+    ["ownerUserId", "assigneeuserid"],
+  ])("classifies %s as near-miss via its segment-aligned suffix", (field, expectedHint) => {
+    const [site] = reportStanceForSource(wrapField(`${field}: createTextField({}),`), "t.ts");
+    expect(site?.stance).toBe("near-miss");
+    expect(site?.hint).toBe(expectedHint);
+  });
+
+  it.each([
+    "contextId",
+    "stepKey",
+    "runId",
+    "scheduleId",
+    "costCategoryId",
+    "toolCallId",
+    "conversationId",
+    "handlerQn",
+  ])("classifies %s as unclassified — no hint containment or suffix match", (field) => {
+    const [site] = reportStanceForSource(wrapField(`${field}: createTextField({}),`), "t.ts");
+    expect(site?.stance).toBe("unclassified");
+    expect(site?.hint).toBeUndefined();
+  });
+
+  it("does not report a call already annotated with a personal stance", () => {
+    const sites = reportStanceForSource(
+      wrapField('email: createTextField({ personal: false, reason: "x" }),'),
+      "t.ts",
+    );
+    expect(sites).toHaveLength(0);
+  });
+
+  it("reports a call whose personal value is undefined", () => {
+    const sites = reportStanceForSource(
+      wrapField("email: createTextField({ personal: undefined }),"),
+      "t.ts",
+    );
+    expect(sites).toHaveLength(1);
+  });
+
+  it("does not report a call whose options literal contains a spread", () => {
+    const sites = reportStanceForSource(wrapField("email: createTextField({ ...base }),"), "t.ts");
+    expect(sites).toHaveLength(0);
+  });
+
+  it("does not report a call with a non-literal options argument", () => {
+    const sites = reportStanceForSource(wrapField("email: createTextField(options),"), "t.ts");
+    expect(sites).toHaveLength(0);
+  });
+
+  it("reports a bare createTextField() call with no arguments", () => {
+    const sites = reportStanceForSource(wrapField("stepKey: createTextField(),"), "t.ts");
+    expect(sites).toHaveLength(1);
+    expect(sites[0]?.stance).toBe("unclassified");
+    expect(sites[0]?.hint).toBeUndefined();
+    expect(sites[0]?.field).toBe("stepKey");
+  });
+
+  it("falls back to a synthetic field name and stays unclassified when there is no enclosing PropertyAssignment", () => {
+    const source = `
+const x = [createTextField({})];
+`;
+    const sites = reportStanceForSource(source, "t.ts");
+    expect(sites).toHaveLength(1);
+    expect(sites[0]?.field).toBe("createTextField(...)");
+    expect(sites[0]?.stance).toBe("unclassified");
+    expect(sites[0]?.hint).toBeUndefined();
+  });
+
+  it("resolves the entity from createEntity's table property", () => {
+    const [site] = reportStanceForSource(wrapField("email: createTextField({}),"), "t.ts");
+    expect(site?.entity).toBe("entity_table");
+  });
+
+  it("falls back to the enclosing variable name when createEntity has no table property", () => {
+    const source = `
+const fields = createEntity({
+  fields: {
+    email: createTextField({}),
+  },
+});
+`;
+    const [site] = reportStanceForSource(source, "t.ts");
+    expect(site?.entity).toBe("fields");
+  });
+
+  it("resolves entity to null when the call is not inside a createEntity call", () => {
+    const source = `
+const standalone = { email: createTextField({}) };
+`;
+    const [site] = reportStanceForSource(source, "t.ts");
+    expect(site?.entity).toBeNull();
+  });
+
+  it("captures createLongTextField the same way as createTextField", () => {
+    const [site] = reportStanceForSource(
+      wrapField("description: createLongTextField({}),"),
+      "t.ts",
+    );
+    expect(site?.callee).toBe("createLongTextField");
+    expect(site?.stance).toBe("user-owned");
+    expect(site?.hint).toBe("description");
+  });
+});

package/src/api/__tests__/server-error-logging.test.ts

@@ -1,6 +1,7 @@
-import { describe, expect, spyOn, test } from "bun:test";
+import { afterEach, beforeEach, describe, expect, spyOn, test } from "bun:test";
 import { z } from "zod";
 import { createRegistry, defineFeature } from "../../engine";
+import { RateLimitError, UnprocessableError } from "../../errors";
 import { TestUsers } from "../../stack";
 import { ensureTemporalPolyfill } from "../../time";
 import { buildServer } from "../server";
@@ -13,6 +14,10 @@ await ensureTemporalPolyfill();
 
 const JWT_SECRET = "test-secret-at-least-32-chars-long!!";
 
+const openToAll = {
+  access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
+} as const;
+
 const boomFeature = defineFeature("boom", (r) => {
   r.queryHandler(
     "explode",
@@ -20,7 +25,38 @@ const boomFeature = defineFeature("boom", (r) => {
     async () => {
       throw new Error("disk on fire");
     },
-    { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
+    openToAll,
+  );
+  r.queryHandler(
+    "decode",
+    z.object({}),
+    async () => {
+      throw new UnprocessableError("vin_not_decodable", {
+        details: { vin: "WDB0000000SECRET" },
+      });
+    },
+    openToAll,
+  );
+  r.queryHandler(
+    "throttled",
+    z.object({}),
+    async () => {
+      throw new RateLimitError({
+        bucket: "ip:203.0.113.7",
+        limit: 1,
+        windowSeconds: 60,
+        remaining: 0,
+        retryAfterSeconds: 60,
+        resetAt: "2026-01-01T00:00:00.000Z",
+      });
+    },
+    openToAll,
+  );
+  r.queryHandler(
+    "login",
+    z.object({ email: z.email(), password: z.string().min(8) }),
+    async () => ({ ok: true }),
+    openToAll,
   );
 });
 
@@ -45,6 +81,43 @@ function apiFaultLog(calls: unknown[][]): string | undefined {
   return hit ? JSON.stringify(hit) : undefined;
 }
 
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+// The `[api] handler rejected` warn line logServerFault emits for 4xx.
+function apiRejectionLog(calls: unknown[][]): Record<string, unknown> | undefined {
+  const hit = calls.find(
+    (args) => typeof args[0] === "string" && args[0].includes("[api] handler rejected"),
+  );
+  return isRecord(hit?.[1]) ? hit[1] : undefined;
+}
+
+async function queryWithCapturedWarnings(
+  type: string,
+  payload: unknown,
+): Promise<{ status: number; warnings: unknown[][]; errors: unknown[][] }> {
+  const warnings: unknown[][] = [];
+  const errors: unknown[][] = [];
+  const warnSpy = spyOn(console, "warn").mockImplementation((...args) => {
+    warnings.push(args);
+  });
+  const errorSpy = spyOn(console, "error").mockImplementation((...args) => {
+    errors.push(args);
+  });
+  try {
+    const res = await app.request("/api/query", {
+      method: "POST",
+      headers: await auth(),
+      body: JSON.stringify({ type, payload }),
+    });
+    return { status: res.status, warnings, errors };
+  } finally {
+    warnSpy.mockRestore();
+    errorSpy.mockRestore();
+  }
+}
+
 describe("HTTP layer logs unexpected 5xx faults", () => {
   test("a throwing query 500s AND the cause stack reaches the log", async () => {
     const calls: unknown[][] = [];
@@ -67,21 +140,99 @@ describe("HTTP layer logs unexpected 5xx faults", () => {
     }
   });
 
-  test("an expected 404 does NOT log a server fault (no 4xx noise)", async () => {
-    const calls: unknown[][] = [];
-    const spy = spyOn(console, "error").mockImplementation((...args) => {
-      calls.push(args);
+  test("a 404 stays off the error level (it is a client outcome, not a server fault)", async () => {
+    const { status, errors } = await queryWithCapturedWarnings("nope:query:nothing", {});
+    expect(status).toBe(404);
+    expect(apiFaultLog(errors)).toBeUndefined();
+  });
+});
+
+describe("HTTP layer logs 4xx client faults on warn (#3077)", () => {
+  let previousLogLevel: string | undefined;
+
+  beforeEach(() => {
+    previousLogLevel = process.env["LOG_LEVEL"];
+    process.env["LOG_LEVEL"] = "info";
+  });
+
+  afterEach(() => {
+    if (previousLogLevel === undefined) delete process.env["LOG_LEVEL"];
+    else process.env["LOG_LEVEL"] = previousLogLevel;
+  });
+
+  test("a 422 leaves a log line with status, code and duration", async () => {
+    const { status, warnings } = await queryWithCapturedWarnings("boom:query:decode", {});
+    expect(status).toBe(422);
+    const logged = apiRejectionLog(warnings);
+    expect(logged).toBeDefined();
+    expect(logged?.["status"]).toBe(422);
+    expect(logged?.["code"]).toBe("unprocessable");
+    expect(logged?.["type"]).toBe("boom:query:decode");
+    expect(typeof logged?.["durationMs"]).toBe("number");
+    expect(logged?.["durationMs"]).toBeGreaterThanOrEqual(0);
+  });
+
+  test("a 429 leaves a log line", async () => {
+    const { status, warnings } = await queryWithCapturedWarnings("boom:query:throttled", {});
+    expect(status).toBe(429);
+    expect(apiRejectionLog(warnings)?.["status"]).toBe(429);
+    expect(apiRejectionLog(warnings)?.["code"]).toBe("rate_limited");
+  });
+
+  test("a 400 validation failure leaves a log line", async () => {
+    const { status, warnings } = await queryWithCapturedWarnings("boom:query:login", {
+      email: "nope",
+      password: "short",
     });
-    try {
-      const res = await app.request("/api/query", {
-        method: "POST",
-        headers: await auth(),
-        body: JSON.stringify({ type: "nope:query:nothing", payload: {} }),
-      });
-      expect(res.status).toBe(404);
-      expect(apiFaultLog(calls)).toBeUndefined();
-    } finally {
-      spy.mockRestore();
-    }
+    expect(status).toBe(400);
+    expect(apiRejectionLog(warnings)?.["status"]).toBe(400);
+    expect(apiRejectionLog(warnings)?.["code"]).toBe("validation_error");
+  });
+
+  test("a 404 leaves a log line and truncates the client-supplied type", async () => {
+    const longType = `ghost:query:${"x".repeat(500)}`;
+    const { status, warnings } = await queryWithCapturedWarnings(longType, {});
+    expect(status).toBe(404);
+    const loggedType = apiRejectionLog(warnings)?.["type"];
+    expect(typeof loggedType).toBe("string");
+    expect(String(loggedType).length).toBeLessThanOrEqual(120);
+  });
+
+  test("the 4xx line carries no submitted values, no message, no details, no stack", async () => {
+    const { warnings } = await queryWithCapturedWarnings("boom:query:login", {
+      email: "victim-at-example.com",
+      password: "hunter2-super-secret",
+      apiKey: "sk-live-0000000000",
+    });
+    const logged = apiRejectionLog(warnings);
+    expect(logged).toBeDefined();
+    expect(Object.keys(logged ?? {}).sort()).toEqual([
+      "code",
+      "durationMs",
+      "requestId",
+      "status",
+      "type",
+    ]);
+    const serialized = JSON.stringify(logged);
+    expect(serialized).not.toContain("victim-at-example.com");
+    expect(serialized).not.toContain("hunter2-super-secret");
+    expect(serialized).not.toContain("sk-live-0000000000");
+  });
+
+  test("a 422 does NOT reach the error level (5xx contract unchanged)", async () => {
+    const { errors } = await queryWithCapturedWarnings("boom:query:decode", {});
+    expect(apiFaultLog(errors)).toBeUndefined();
+  });
+
+  test("LOG_LEVEL=error silences the 4xx lines but keeps 5xx", async () => {
+    process.env["LOG_LEVEL"] = "error";
+
+    const rejected = await queryWithCapturedWarnings("boom:query:decode", {});
+    expect(rejected.status).toBe(422);
+    expect(apiRejectionLog(rejected.warnings)).toBeUndefined();
+
+    const exploded = await queryWithCapturedWarnings("boom:query:explode", {});
+    expect(exploded.status).toBe(500);
+    expect(apiFaultLog(exploded.errors)).toBeDefined();
   });
 });

package/src/api/request-context.ts

@@ -44,6 +44,9 @@ export type RequestContextData = {
   // event written under this scope.
   readonly feature?: string;
   readonly handler?: string;
+  // performance.now() at request entry, so a failing request can report how
+  // long it ran. Monotonic — a wall-clock step cannot make it negative.
+  readonly startedAt?: number;
 };
 
 const storage = new AsyncLocalStorage<RequestContextData>();

package/src/api/request-id-middleware.ts

@@ -62,6 +62,7 @@ export function buildRequestContextDataFromRequest(req: Request): RequestContext
   return {
     requestId,
     correlationId,
+    startedAt: performance.now(),
     ...(signal ? { signal } : {}),
     ...(ip && ip.length > 0 ? { ip } : {}),
     ...(userAgent !== undefined ? { userAgent } : {}),
@@ -81,7 +82,7 @@ export function buildRequestContextData(c: Context): RequestContextData {
   // instead of letting req.headers.get() throw on every request.
   if (!c.req.raw) {
     const requestId = requestContext.generateId();
-    return { requestId, correlationId: requestId };
+    return { requestId, correlationId: requestId, startedAt: performance.now() };
   }
   return buildRequestContextDataFromRequest(c.req.raw);
 }

package/src/api/routes.ts

@@ -333,15 +333,47 @@ function assertPatAllowed(user: SessionUser, type: string): void {
   }
 }
 
+// Log levels that silence the 4xx tier. Checked here and not in the logger
+// because this module uses the console fallback, which pino's level never
+// reaches — LOG_LEVEL is the volume knob for client faults.
+const FAULT_LOG_SILENCED_LEVELS = new Set(["error", "fatal", "silent"]);
+
+// `type` is client-supplied on an unknown-handler 404, so cap it before it
+// reaches the log — an unbounded field would let a caller flood the sink.
+const MAX_LOGGED_TYPE_LENGTH = 120;
+
+function clientFaultLoggingEnabled(): boolean {
+  return !FAULT_LOG_SILENCED_LEVELS.has(process.env["LOG_LEVEL"] ?? "");
+}
+
+// A failing request must leave a trace even when it ends in 4xx — a paid
+// external call that 422s was invisible before (offlot#117). Status, error
+// code and duration only: message/details/stack can carry submitted values.
+function logClientFault(err: KumikoError, requestId: string | undefined, type?: string): void {
+  if (!clientFaultLoggingEnabled()) {
+    // skip: LOG_LEVEL silences the 4xx tier — the deployment opted out of client-fault volume
+    return;
+  }
+  const startedAt = requestContext.get()?.startedAt;
+  createFallbackLogger("api").warn("handler rejected", {
+    requestId,
+    type: type?.slice(0, MAX_LOGGED_TYPE_LENGTH),
+    status: err.httpStatus,
+    code: err.code,
+    ...(startedAt === undefined ? {} : { durationMs: Math.round(performance.now() - startedAt) }),
+  });
+}
+
 // Unexpected server faults (5xx) carry their diagnostic stack only on the
 // in-process error — serializeError strips cause/details from the wire body.
 // Without this a wrapped throw (InternalError{cause}) returns a 500 with zero
-// log lines, leaving ops nothing to debug (the bug this guards). 4xx are
-// expected client outcomes and stay unlogged. `type` is the only handler
+// log lines, leaving ops nothing to debug (the bug this guards). 4xx take the
+// redacted `warn` line above instead. `type` is the only handler
 // discriminator — every request hits the same /api/{query,command} path.
 function logServerFault(err: KumikoError, requestId: string | undefined, type?: string): void {
   if (err.httpStatus < 500) {
-    // skip: 4xx are expected client outcomes (not-found, validation, denied) — logging them is noise
+    logClientFault(err, requestId, type);
+    // skip: 4xx already logged on warn by logClientFault — the error level stays 5xx-only
     return;
   }
   const cause = err.cause;

package/src/changes.json

@@ -1,4 +1,67 @@
 [
+  {
+    "version": "0.292.0",
+    "type": "fix",
+    "title": "Validate changeset folding in PR CI",
+    "detail": "The release-time `changes fold` now also runs as a dry run on every PR, so a changeset with an unresolvable feature fails its own PR instead of the next release."
+  },
+  {
+    "version": "0.292.0",
+    "type": "improvement",
+    "title": "A projectionList can declare a time-range filter",
+    "detail": "A list bound to a query that already accepts time bounds had no way to expose them: `ListFacetSpec` knew `select`, `boolean` and `reference`, so every list with a timestamp — which, through `createdAt`, is practically every list — could be searched but not narrowed to \"the week the incident happened\". The audit log shipped a `description` promising date filters that no control backed.\n`{ type: \"dateRange\", field, label, params: { from, to } }` closes that. The renderer maps it to two native `<input type=\"date\">` next to the facet dropdowns (no date dependency; the browser supplies the calendar, the locale and the keyboard handling) and sends the picked bounds as the two query params the facet names — explicit rather than a `from`/`to` convention, since a query is free to call them anything, and checked against the handler's Zod schema at boot. Filtering stays server-side; either bound alone is a valid open interval; changing the range resets the page like every other facet; an inverted range is clamped in the UI instead of reaching the handler's `from <= to` refine.\nA calendar date covers a whole day in the viewer's time zone: \"to the 14th\" includes everything through the last instant of the 14th, computed across DST boundaries rather than by adding 24 hours. `audit:screen:audit-log` now declares the facet on `createdAt`, so its description holds."
+  },
+  {
+    "version": "0.291.0",
+    "type": "breaking",
+    "title": "projection-rebuild aborts instead of silently NULLing populated blind-index columns (fw#3091)",
+    "detail": "`kumiko schema apply` rebuilds a projection through a fresh shadow table replay, and the shadow always recomputes every `<field>_bidx` column with whatever blind-index key is configured in the running process. A projection rebuilt in a process without `KUMIKO_BLIND_INDEX_KEY` set — most commonly the `migrate-db` init container that runs `kumiko schema apply` on deploy — silently swapped the live table for one where every bidx column had gone NULL, breaking equality lookups (login, password reset) with no error anywhere. `rebuildProjection` now checks, right before the swap, whether the live table already has populated bidx columns while no key is configured in this process; if so it throws and leaves the live table untouched instead of completing the swap.",
+    "migration": "Plaintext installations and the fw#1610 case (KMS configured, no blind-index\nkey) are unaffected — their bidx columns are NULL already, so there is\nnothing for the rebuild to lose. This only blocks a rebuild that would\notherwise destroy already-populated bidx columns: any process running\n`kumiko schema apply` (or another projection rebuild) against a table with\nlive blind-index data must have `KUMIKO_BLIND_INDEX_KEY` set. Wire that env\nvar into the `migrate-db` init container (or wherever schema apply runs in\ndeploy) alongside the app's own KUMIKO_BLIND_INDEX_KEY, or the rebuild aborts\ninstead of quietly breaking equality lookups."
+  },
+  {
+    "version": "0.291.0",
+    "type": "breaking",
+    "title": "Declared event PII fails closed without a subject KMS (fw#2776)",
+    "detail": "`defineEvent` has required an explicit PII stance since fw#2558, but a declared stance still did not guarantee ciphertext in `kumiko_events`. Two paths leaked silently and now fail closed.\nBoot: `assertPiiBootInvariants` only looked at entity annotations, so an app whose PII lives exclusively in catalogued events booted without a `kms` adapter and wrote plaintext. It now collects events with a non-`\"none\"` stance alongside the PII entities — prod aborts, dev warns, `allowPlaintextPii: \"<reason>\"` acknowledges, same as for entities.\nAppend: `{ personal: { of: \"<ownerField>\" } }` skipped encryption whenever the owner field carried no id, so the same event type was ciphertext for user-triggered writes and plaintext for system-triggered ones with no signal. The stance now carries `whenAbsent`: `\"tenant\"` encrypts under the envelope tenant key, `\"plaintext\"` is an explicit acknowledgement that the value cannot be crypto-shredded. Registration rejects a nullable owner field without one, and an owner that is empty at append time with no declared fallback aborts the write instead of storing the value in the clear.\n`delivery:event:attempt` declares `whenAbsent: \"tenant\"` — a send whose `recipientId` is null now stores the recipient address under the tenant key instead of in plaintext.",
+    "migration": "Three things can newly fail. (1) Boot aborts with `BOOT ABORTED — ... events\n[...]` when a mounted feature declares a non-`\"none\"` `piiFields` stance and\n`runProdApp`/`runWorkerApp` gets no `kms`. Pass\n`kms: createPgKmsAdapter({ databaseUrl, platformKek })`, or acknowledge the\nplaintext with `allowPlaintextPii: \"<reason>\"` until the KMS is provisioned;\n`runDevApp` only warns. (2) Registration aborts when a\n`{ personal: { of: \"<ownerField>\" } }` stance names an owner field the payload\nschema allows to be null or undefined. Add `whenAbsent: \"tenant\"` to encrypt\nthose writes under the envelope tenant key, or `whenAbsent: \"plaintext\"` to\ndeclare that the value ships unencrypted and is not crypto-shreddable. The\ndeprecated `{ subjectField: \"<ownerField>\" }` form cannot express `whenAbsent`\n— move it to the canonical `{ personal: { of: ... } }` form. (3) `append()`\nthrows `SubjectResolutionError` when the owner field is empty at write time\nand the event declared no `whenAbsent`. Registration catches this for\nZodObject payload schemas; a non-object schema surfaces it here. An owner\nvalue that is not a non-empty string — a numeric id, an empty string — counts\nas absent, so it takes the same path and needs the same declaration.\nSeparately, `delivery:event:attempt` rows written with a null `recipientId`\nused to hold a plaintext recipient address in `kumiko_events` and in\n`store_delivery_attempts`. New rows are tenant-subject ciphertext.\n`delivery:query:log` decrypts either form, so the admin log view is unchanged;\ntooling that reads `store_delivery_attempts.recipient_address` directly must\ngo through `decryptStoredPii`. Existing plaintext rows stay readable and are\nre-encrypted by `backfillEventPiiEncryption`."
+  },
+  {
+    "version": "0.291.0",
+    "type": "improvement",
+    "title": "Boot warns for text/longText fields without a personal stance (fw#2918).",
+    "detail": "`validatePiiAndRetention` so far only warned when an unannotated field name hit one of the PII name heuristics. It now warns for every `text`/`longText` field that declares no stance at all — naming feature, entity, field and all valid stances verbatim — so consumers can work off their own baseline before fw#2810 turns the missing stance into a compile error and a throw. Annotated fields (including `personal: false` with a reason and `personal: \"ref\"`) stay silent, other field types are untouched.\nA clean boot does not mean \"ready for fw#2810\": `validatePiiAndRetention` only walks `feature.entities[*].fields`, so embedded sub-schemas and call sites that never boot (fixtures, helper modules) produce no warning while still breaking later. The completeness instrument is and stays `guard-text-field-stance` — ready means a guard count of 0. The reverse does not hold either: the guard counts `createTextField()` call sites, the boot validator walks resolved field defs, so a raw field-def object literal warns at boot without ever showing up in the guard's baseline."
+  },
+  {
+    "version": "0.291.0",
+    "type": "fix",
+    "title": "API handler rejections (4xx) now leave a log line instead of being silently dropped",
+    "detail": "`logServerFault` returned early for every `httpStatus < 500`, so a failing request (validation, unprocessable, rate-limited) left no log trace at all — a paid external call that 422'd was invisible end to end (offlot#117). 4xx now log on `warn` via the same fallback logger 5xx already used, with status, error code and duration only — no message, details, stack or cause, so submitted values never reach the log line. 5xx behavior on the `error` level is unchanged.\nConsumers that set `LOG_LEVEL=error`, `fatal` or `silent` suppress the new 4xx lines; anything else (including the default) now logs them. Expect more log volume on routes with frequent client-side validation failures."
+  },
+  {
+    "version": "0.291.0",
+    "type": "improvement",
+    "title": "pii-personal-migration codemod gets a --report-stance mode (fw#2919)",
+    "detail": "`bun scripts/codemod/pii-personal-migration.ts <dir> --report-stance` scans every `createTextField`/`createLongTextField` call without a `personal` stance and classifies its field name against the `entity-handler.ts` PII name hints (direct/user-owned/user-reference/near-miss/unclassified) — no files are written."
+  },
+  {
+    "version": "0.291.0",
+    "type": "improvement",
+    "title": "Generic job-liveness metric kumiko_job_last_success_timestamp_seconds{job} (fw#3052).",
+    "detail": "The job-runner now stamps a standard gauge with the Unix timestamp of the last successful run of every job registered via `r.job`, so any consumer gets a real dead-man for all its crons with `time() - kumiko_job_last_success_timestamp_seconds{job=\"…\"} > <interval + buffer>`. A failed run leaves the value untouched. The k8s CronJob alerts never covered these jobs — they run in-process in a long-lived pod and create no CronJob object. Note that the series is absent until the first success after a restart; `docs/reference/job-liveness-metric.md` explains the `for:` that implies for the alert side."
+  },
+  {
+    "version": "0.291.0",
+    "type": "breaking",
+    "title": "money fields on actionForm/secretMint screens declare their currency source (fw#2839)",
+    "detail": "`actionForm` and `secretMint` have no entity, so their money fields never received `entity.defaultCurrency`: an untouched one seeded a bare `0` that the handler's zod schema then rejected on submit. fw#2763 closed the prefill half of this; the default half stayed open. `MoneyCurrencySource` gains `{ kind: \"literal\", code }` next to the existing `{ kind: \"tenant\" }`, and the field maps of `actionForm`, `secretMint` and its `confirm` step are narrowed so a money field there requires `currency` — enforced by the compiler at bump time and by the boot validator for untyped callers. A literal code is checked against the app's `currencies` list, the same rule `entity.defaultCurrency` already follows. Entity fields, embedded-list money cells and `configEdit`'s plain-number contract are unchanged.",
+    "migration": "Only affects entity-less form screens — `actionForm`, `secretMint` and a\nsecretMint's `confirm` step — that hold a `money` field. Entity money fields\nare unchanged (`entity.defaultCurrency` is already boot-enforced for them),\nas are embedded-list money cells (currency at the head, fw#2764) and\n`configEdit`, which keeps its plain-number contract.\nAdd a `currency` to each money field in such a screen's `fields` map:\n`currency: { kind: \"literal\", code: \"EUR\" }` for one fixed currency, or\n`currency: { kind: \"tenant\" }` for the tenant's own currency.\nA `literal` code must be in the app's `currencies` list (`createApp({ currencies })`,\nwhich already includes the defaults). A `tenant`-declared field resolves through\nthe tenant-settings bundle and holds the form until the value has landed, so that\nbundle has to be mounted. Missing declarations fail at compile time; an untyped\ncaller fails at boot with the screen and field name in the message."
+  },
+  {
+    "version": "0.291.0",
+    "type": "improvement",
+    "title": "Reference fields can source their picker from a query handler",
+    "detail": "`labelField` names one column of the referenced entity, so an entity whose identity is composed from joined rows — a lease identified by its tenant and unit, not by any column on the lease row — has no right answer, only a least-wrong one, and its picker lists raw dates or UUIDs. `ReferenceFieldDef.optionsQuery` (also on a reference sub-field of an embedded field) names a query handler that returns `{ rows: { id, label }[] }` and receives `{ limit, search? }` like the default list handler, so the app composes the label itself. The picker, the read-only display of a reference value and an embedded-list reference cell all read it; the QN is pinned at boot against the registered handlers, the same treatment `DashboardFilterDefinition.optionsQuery` gets.\nIt is additive, not a replacement: `labelField` keeps serving the paths a query handler cannot back, since list cells, `searchable` and `sortable` all resolve to an SQL column on the referenced table. A field without `optionsQuery` behaves exactly as before."
+  },
   {
     "version": "0.290.0",
     "type": "improvement",