@cosmicdrift/kumiko-framework 0.220.0 → 0.221.0

package/src/pipeline/__tests__/distributed-lock.integration.test.ts

@@ -90,6 +90,18 @@ describe("distributed lock", () => {
     expect(await lock.acquire("test-lock-7")).not.toBeNull();
   });
 
+  test("renew with ttlSeconds 0 does not drop the lock", async () => {
+    const lock = createDistributedLock(testRedis.redis);
+    const token = await lock.acquire("test-lock-ttl0", { ttlSeconds: 5 });
+    if (!token) throw new Error("expected token");
+    const renewed = await lock.renew("test-lock-ttl0", token, 0);
+    expect(renewed).toBe(false);
+    // Original lock still held — a peer acquire must fail.
+    const peer = await lock.acquire("test-lock-ttl0", { ttlSeconds: 5 });
+    expect(peer).toBeNull();
+    await lock.release("test-lock-ttl0", token);
+  });
+
   test("renew on an expired/absent key fails", async () => {
     const lock = createDistributedLock(testRedis.redis);
     const renewed = await lock.renew("test-lock-8-never-acquired", "some-token", 5);

package/src/pipeline/__tests__/event-dispatcher-pg-listen.integration.test.ts

@@ -1,36 +1,18 @@
 // E.4 — PG LISTEN/NOTIFY wake-up. Without this, delivery latency is
 // bounded below by pollIntervalMs. With LISTEN, event-store.append fires
-// `pg_notify` on commit and any subscribed dispatcher wakes immediately —
-// latency becomes TCP round-trip, typically sub-millisecond on localhost.
+// `pg_notify` on commit and any subscribed dispatcher wakes immediately.
 //
-// The polling timer stays on as a safety net for dropped subscriptions
-// and crashes between commit and wake. These tests pin:
-//
-//   1. NOTIFY → runOnce fires promptly, without waiting for the timer.
-//   2. The dispatcher starts cleanly when pgClient is wired and stops
-//      without leaking the LISTEN connection, and still wakes on NOTIFY
-//      after a restart cycle.
-//
-// #2042: these used to assert an absolute millisecond latency bound
-// (`< 40`, later `< 100`) against the test-stack's default 50ms polling
-// timer. On a shared CI runner a stalled event loop can push even a
-// working LISTEN's delivery past 100ms — measured up to 154ms — so no
-// millisecond bound both clears runner noise and stays under a 50ms
-// timer. Fix: push the polling timer out to 60s for this stack
-// (`eventDispatcherPollIntervalMs`) and assert delivery happens at all
-// inside a 5s window. If LISTEN is dead, nothing arrives before the 5s
-// deadline — a 12x margin under the 60s timer that no runner stall gets
-// anywhere near. If LISTEN works, delivery is near-instant regardless of
-// runner load. Verified by temporarily forcing pgClient to undefined in
-// test-stack.ts: both tests then fail at toHaveLength(1) with 0 received
-// after ~5s, confirming the assertion still discriminates.
+// The polling timer stays as a safety net. These tests pin NOTIFY wake
+// without waiting for the timer, and that start/stop still leaves LISTEN
+// working. #2042: poll interval is 60s here; assert delivery inside 5s —
+// if LISTEN is dead the timer cannot rescue the assertion.
 
 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
 import { createEventStoreExecutor } from "../../db/event-store-executor";
 import { createTenantDb, type TenantDb } from "../../db/tenant-db";
 import { defineFeature } from "../../engine";
 import { setupTestStack, type TestStack, TestUsers, unsafeCreateEntityTable } from "../../stack";
-import { sharedWidgetEntity, sharedWidgetTable } from "../../testing";
+import { sharedWidgetEntity, sharedWidgetTable, waitFor } from "../../testing";
 
 // --- Fixture ---
 
@@ -38,7 +20,7 @@ const executor = createEventStoreExecutor(sharedWidgetTable, sharedWidgetEntity,
   entityName: "widget",
 });
 
-const deliveryTimes: number[] = [];
+let deliveryCount = 0;
 
 const listenFeature = defineFeature("listen", (r) => {
   r.entity("widget", sharedWidgetEntity);
@@ -47,7 +29,7 @@ const listenFeature = defineFeature("listen", (r) => {
     name: "latency-probe",
     apply: {
       "widget.created": async () => {
-        deliveryTimes.push(Date.now());
+        deliveryCount += 1;
       },
     },
   });
@@ -79,42 +61,44 @@ afterAll(async () => {
 
 describe("E.4 — PG NOTIFY/LISTEN wake-up", () => {
   test("NOTIFY on commit triggers runOnce without waiting for the poll timer", async () => {
-    deliveryTimes.length = 0;
+    deliveryCount = 0;
 
     await stack.eventDispatcher?.start();
     try {
       await executor.create({ name: "latency-test" }, admin, tdb);
 
-      const deadline = Date.now() + 5000;
-      while (Date.now() < deadline && deliveryTimes.length === 0) {
-        await new Promise((r) => setTimeout(r, 5));
-      }
-      expect(deliveryTimes).toHaveLength(1);
+      await waitFor(
+        () => {
+          expect(deliveryCount).toBe(1);
+        },
+        { delays: [100, 500, 1000, 3500] },
+      );
     } finally {
       await stack.eventDispatcher?.stop();
     }
   });
 
   test("dispatcher start/stop cycle with LISTEN attached still delivers after restart", async () => {
-    // Repeated start/stop must not leak connections or break LISTEN. After
-    // 3 cycles the last .start() should still wake on NOTIFY — if the
-    // unlisten handle was mishandled, the subscription would either be
-    // stale (LISTEN on a closed connection) or double-registered.
+    // Repeated start/stop must not leak connections or break LISTEN.
+    // Two start/stop cycles, then a third start() that must still wake on
+    // NOTIFY — if the unlisten handle was mishandled, the subscription
+    // would be stale or double-registered.
     for (let i = 0; i < 2; i++) {
       await stack.eventDispatcher?.start();
       await stack.eventDispatcher?.stop();
     }
 
-    deliveryTimes.length = 0;
+    deliveryCount = 0;
     await stack.eventDispatcher?.start();
     try {
       await executor.create({ name: "restart-probe" }, admin, tdb);
 
-      const deadline = Date.now() + 5000;
-      while (Date.now() < deadline && deliveryTimes.length === 0) {
-        await new Promise((r) => setTimeout(r, 5));
-      }
-      expect(deliveryTimes).toHaveLength(1);
+      await waitFor(
+        () => {
+          expect(deliveryCount).toBe(1);
+        },
+        { delays: [100, 500, 1000, 3500] },
+      );
     } finally {
       await stack.eventDispatcher?.stop();
     }

package/src/pipeline/__tests__/load-aggregate-query.integration.test.ts

@@ -190,10 +190,12 @@ describe("ctx.loadAggregate via queryHandler — Marten AggregateStreamAsync equ
       { customer: "TimeTraveler", status: "draft" },
       admin,
     );
-    // Capture the event timestamp from the events-table for a precise cutoff.
-    // A too-small offset risks clock granularity flakes — we rely on the
-    // millisecond-precision timestamp column.
-    const preApprove = new Date();
+    // Cutoff must come from the event row's created_at (Postgres now()), not
+    // host wall-clock — Docker clock skew made Date()-based cutoffs exclude
+    // the create event (fw#2425).
+    const beforeApprove = await loadAggregateRaw(stack.db, created.id, admin.tenantId);
+    expect(beforeApprove).toHaveLength(1);
+    const preApprove = beforeApprove[0]!.createdAt;
     // Make sure the next event's createdAt is strictly after the cutoff.
     await new Promise((r) => setTimeout(r, 10));
     await stack.http.writeOk(
@@ -210,10 +212,10 @@ describe("ctx.loadAggregate via queryHandler — Marten AggregateStreamAsync equ
     );
     expect(now.approved).toBe(true);
 
-    // asOf preApprove: the approval is in the future, not yet visible.
+    // asOf create.createdAt: the approval is in the future, not yet visible.
     const past = await stack.http.queryOk<{ approved: boolean; status: string }>(
       "asoftest:query:invoice:state",
-      { id: created.id, asOf: preApprove.toISOString() },
+      { id: created.id, asOf: preApprove.toString() },
       admin,
     );
     expect(past.approved).toBe(false);

package/src/pipeline/distributed-lock.ts

@@ -50,6 +50,9 @@ export function createDistributedLock(
     },
 
     async renew(key, token, ttlSeconds) {
+      // EXPIRE with 0/negative deletes the key but still returns 1 — reject
+      // before we claim ownership while releasing the lock.
+      if (!Number.isInteger(ttlSeconds) || ttlSeconds < 1) return false;
       const result = (await redis.eval(
         renewScript,
         1,

package/src/schema-cli.ts

@@ -11,6 +11,7 @@
 import { existsSync, mkdirSync, readdirSync, writeFileSync } from "node:fs";
 import { join, resolve as resolvePath } from "node:path";
 import {
+  assertValidMigrationName,
   baselineMigrations,
   createDbConnection,
   type DbConnection,
@@ -151,10 +152,14 @@ export async function runSchemaCli(
         out.err("  Usage: schema generate <name>");
         return 1;
       }
-      // name lands unescaped in `${seq}_${name}.sql` (generateMigration) — this
-      // allowlist blocks flag-like names and path traversal (`../../x`).
-      if (name.startsWith("-") || !/^[A-Za-z0-9_-]+$/.test(name)) {
-        out.err(`  Invalid migration name "${name}" — use letters, digits, "-", "_" only.`);
+      // name lands unescaped in `${seq}_${name}.sql` (generateMigration) —
+      // shared allowlist blocks flag-like names, path traversal, and
+      // ENAMETOOLONG-length names.
+      try {
+        assertValidMigrationName(name);
+      } catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        out.err(`  ${msg}`);
         out.err("  Usage: schema generate <name>");
         return 1;
       }

package/src/scripts/codemod/crypto-shredding-testing-move.ts

@@ -8,47 +8,55 @@
 //
 // Usage: bun scripts/codemod/crypto-shredding-testing-move.ts <targetDir> [--dry-run]
 
-import { resolve } from "node:path";
-import { Glob } from "bun";
-import { Project } from "ts-morph";
+import { type Dirent, readdirSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { Project, type SourceFile } from "ts-morph";
 
 const OLD_SPECIFIER = "@cosmicdrift/kumiko-framework/crypto";
 const NEW_SPECIFIER = "@cosmicdrift/kumiko-framework/testing";
 const MOVED_NAMES = new Set(["resetPiiSubjectKmsForTests", "resetBlindIndexKeyForTests"]);
 
+const EXCLUDE_DIRS = new Set(["node_modules", "dist", "build"]);
+
 function findTargetFiles(rootDir: string): string[] {
-  const glob = new Glob("**/*.{ts,tsx}");
-  const EXCLUDE = ["/node_modules/", "/dist/", "/build/"];
+  // Walk the tree and skip excluded dirs while descending — filtering the
+  // absolute path after a full Glob scan silently no-ops when the repo root
+  // itself contains "/build/" or "/node_modules/" (fw#2289).
   const files: string[] = [];
-  for (const file of glob.scanSync({ cwd: rootDir, dot: false })) {
-    const abs = resolve(rootDir, file);
-    if (EXCLUDE.some((p) => abs.includes(p))) continue;
-    files.push(abs);
-  }
+  const walk = (dir: string): void => {
+    let entries: Dirent[];
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      // skip: unreadable directory during walk — treat as empty.
+      return;
+    }
+    for (const ent of entries) {
+      if (ent.isDirectory()) {
+        if (EXCLUDE_DIRS.has(ent.name) || ent.name.startsWith(".")) continue;
+        walk(join(dir, ent.name));
+        continue;
+      }
+      if (ent.isFile() && /\.(ts|tsx)$/.test(ent.name)) {
+        files.push(join(dir, ent.name));
+      }
+    }
+  };
+  walk(rootDir);
   return files.sort();
 }
 
-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());
-
-  const files = findTargetFiles(rootDir);
-  const project = new Project({
-    skipAddingFilesFromTsConfig: true,
-    skipFileDependencyResolution: true,
-  });
-
-  let touchedFiles = 0;
-  let movedNames = 0;
-
-  for (const file of files) {
-    const sourceFile = project.addSourceFileAtPath(file);
-    const oldImport = sourceFile
-      .getImportDeclarations()
-      .find((d) => d.getModuleSpecifierValue() === OLD_SPECIFIER);
-    if (!oldImport) continue;
+/** Move matching value imports from crypto → testing. Returns count of names moved. */
+function migrateFile(sourceFile: SourceFile): number {
+  // Value imports only — a pre-existing `import type { … } from testing`
+  // must not receive runtime helpers (they would be erased).
+  const oldImports = sourceFile
+    .getImportDeclarations()
+    .filter((d) => d.getModuleSpecifierValue() === OLD_SPECIFIER && !d.isTypeOnly());
+  if (oldImports.length === 0) return 0;
 
+  let fileMoved = 0;
+  for (const oldImport of oldImports) {
     const movedHere = oldImport.getNamedImports().filter((spec) => MOVED_NAMES.has(spec.getName()));
     if (movedHere.length === 0) continue;
 
@@ -56,7 +64,7 @@ async function main(): Promise<void> {
 
     const existingNewImport = sourceFile
       .getImportDeclarations()
-      .find((d) => d.getModuleSpecifierValue() === NEW_SPECIFIER);
+      .find((d) => d.getModuleSpecifierValue() === NEW_SPECIFIER && !d.isTypeOnly());
     if (existingNewImport) {
       const already = new Set(existingNewImport.getNamedImports().map((s) => s.getName()));
       for (const name of names) {
@@ -73,8 +81,32 @@ async function main(): Promise<void> {
       !!oldImport.getNamespaceImport();
     if (!remaining) oldImport.remove();
 
+    fileMoved += names.length;
+  }
+  return fileMoved;
+}
+
+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());
+
+  const files = findTargetFiles(rootDir);
+  const project = new Project({
+    skipAddingFilesFromTsConfig: true,
+    skipFileDependencyResolution: true,
+  });
+
+  let touchedFiles = 0;
+  let movedNames = 0;
+
+  for (const file of files) {
+    const sourceFile = project.addSourceFileAtPath(file);
+    const fileMoved = migrateFile(sourceFile);
+    if (fileMoved === 0) continue;
+
     touchedFiles++;
-    movedNames += names.length;
+    movedNames += fileMoved;
     if (!dryRun) sourceFile.saveSync();
   }
 

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

@@ -204,15 +204,22 @@ function processObjectLiteral(obj: ObjectLiteralExpression, factoryName: string)
   }
 
   if (subjectProps.length > 1) {
-    report(
-      subjectProps[0]!.prop,
-      `multiple subject annotations on one field (${subjectProps.map((s) => s.name).join(", ")}) — needs a human decision on which subject is correct`,
-    );
+    const first = subjectProps[0];
+    if (first) {
+      report(
+        first.prop,
+        `multiple subject annotations on one field (${subjectProps.map((s) => s.name).join(", ")}) — needs a human decision on which subject is correct`,
+      );
+    }
     // skip: reported above — multiple subject annotations need a human call on which one wins
     return;
   }
 
-  const subject = subjectProps[0]!;
+  const subject = subjectProps[0];
+  if (!subject) {
+    // skip: length===0 and length>1 already returned — empty [0] is unreachable
+    return;
+  }
 
   if (NO_PERSONAL_FACTORIES.has(factoryName)) {
     report(
@@ -276,12 +283,13 @@ function processObjectLiteral(obj: ObjectLiteralExpression, factoryName: string)
       return;
     }
     const ownerFieldProp = findProp(init, "ownerField");
-    if (!ownerFieldProp?.getInitializer()) {
+    const ownerFieldInit = ownerFieldProp?.getInitializer();
+    if (!ownerFieldInit) {
       report(subject.prop, 'userOwned is missing an "ownerField" property');
       // skip: reported above — userOwned is missing its ownerField property
       return;
     }
-    personalInit = `{ of: ${ownerFieldProp.getInitializer()!.getText()} }`;
+    personalInit = `{ of: ${ownerFieldInit.getText()} }`;
   }
 
   const subjectIsRefOrPlaintext =
@@ -331,9 +339,9 @@ function processObjectLiteral(obj: ObjectLiteralExpression, factoryName: string)
   const hasSearchable = !!searchableProp;
   const hasSensitive = !!sensitiveProp;
 
-  if (hasSensitive && (hasLookupable || hasSearchable)) {
+  if (sensitiveProp && (hasLookupable || hasSearchable)) {
     report(
-      sensitiveProp!,
+      sensitiveProp,
       'sensitive combined with lookupable/searchable — two find values ("secret" vs "exact"/"fuzzy"), needs a human decision',
     );
     // skip: reported above — sensitive plus lookupable/searchable is an ambiguous find value
@@ -348,10 +356,13 @@ function processObjectLiteral(obj: ObjectLiteralExpression, factoryName: string)
   else find = "none";
 
   if (isLongTextFind && (find === "exact" || find === "fuzzy")) {
-    report(
-      (lookupableProp ?? searchableProp)!,
-      'lookupable/searchable on createLongTextField — only "none"/"secret" are valid find values on longText',
-    );
+    const findSite = lookupableProp ?? searchableProp;
+    if (findSite) {
+      report(
+        findSite,
+        'lookupable/searchable on createLongTextField — only "none"/"secret" are valid find values on longText',
+      );
+    }
     // skip: reported above — exact/fuzzy find isn't valid on createLongTextField
     return;
   }
@@ -381,7 +392,12 @@ function applyTransform(
   next: { personal: string; reason: string | undefined; find: string | undefined },
 ): void {
   const properties = obj.getProperties();
-  const anchor = removedProps[0]!;
+  // Call sites always pass at least subject.prop; without an anchor there is nowhere to insert.
+  const anchor = removedProps[0];
+  if (!anchor) {
+    // skip: no removed prop to anchor inserts on — nothing to transform
+    return;
+  }
   const anchorIndex = properties.indexOf(anchor);
   const removedSet = new Set<PropertyAssignment>(removedProps);
   let insertIndex = 0;

package/src/search/purge-subject.ts

@@ -9,11 +9,12 @@
 //      that still carry the subject key in encrypted columns.
 
 import { quoteIdent, subjectCiphertextLikePattern } from "../crypto/ciphertext-pattern";
+import { isSelfPiiField } from "../crypto/is-self-pii-field";
 import type { SubjectId } from "../crypto/kms-adapter";
 import { collectSearchableSubjectFields } from "../crypto/subject-resolver";
 import type { DbRunner } from "../db/connection";
 import { resolveTableName } from "../db/entity-table-meta";
-import { executeRawQuery } from "../db/queries/raw-sql";
+import { executeRawQueryRead } from "../db/queries/raw-sql";
 import type { FeatureDefinition } from "../engine/types";
 import type { EntityDefinition } from "../engine/types/fields";
 import type { EntityId, TenantId } from "../engine/types/identifiers";
@@ -46,7 +47,7 @@ function ownershipPredicates(
           params.push(subject.userId);
           parts.push(`${quoteIdent(col)} = $${n}`);
         }
-      } else if ("pii" in field && field.pii === true && selfIdN === undefined) {
+      } else if (isSelfPiiField(field) && selfIdN === undefined) {
         selfIdN = nextParam();
         params.push(subject.userId);
         parts.push(`${quoteIdent("id")} = $${selfIdN}`);
@@ -78,7 +79,7 @@ async function collectMatchingRowsForEntity(
   let offset = 0;
   for (;;) {
     const offsetN = params.length + 1;
-    const page = await executeRawQuery<MatchedRow>(
+    const page = await executeRawQueryRead<MatchedRow>(
       db,
       `SELECT id, tenant_id FROM ${quoteIdent(tableName)} WHERE ${whereSql}
         ORDER BY ${quoteIdent("id")} ASC

package/src/search/reindex-entity.ts

@@ -7,7 +7,7 @@
 
 import type { DbRunner } from "../db/connection";
 import { resolveTableName } from "../db/entity-table-meta";
-import { executeRawQuery } from "../db/queries/raw-sql";
+import { executeRawQueryRead } from "../db/queries/raw-sql";
 import type { Registry, TenantId } from "../engine/types";
 import {
   buildSearchDocument,
@@ -112,7 +112,7 @@ export async function reindexEntity(
     // across both types needs a text cast that breaks integer ordering.
     // This is a one-time backfill over existing rows, not a live hot path;
     // switch to keyset if it ever needs to run against a churning table.
-    const rows = await executeRawQuery<Record<string, unknown>>(
+    const rows = await executeRawQueryRead<Record<string, unknown>>(
       db,
       `SELECT * FROM ${quoteIdent(tableName)}
         WHERE ${quoteIdent("tenant_id")} = $1 ${deletedFilter}

package/src/stack/__tests__/request-helper.integration.test.ts

@@ -10,7 +10,7 @@ import { NotFoundError, UnprocessableError, writeFailure } from "../../errors";
 import { setupTestStack, type TestStack } from "../test-stack";
 import { TestUsers } from "../test-users";
 
-let stack: TestStack;
+let stack: TestStack | undefined;
 
 const pingFeature = defineFeature("reqhelp", (r) => {
   r.writeHandler(
@@ -49,12 +49,12 @@ beforeAll(async () => {
 });
 
 afterAll(async () => {
-  await stack.cleanup();
+  await stack?.cleanup();
 });
 
 describe("createRequestHelper via setupTestStack.http", () => {
   test("writeOk posts to /api/write and returns handler data", async () => {
-    const data = await stack.http.writeOk<{ note: string; userId: string }>(
+    const data = await stack!.http.writeOk<{ note: string; userId: string }>(
       "reqhelp:write:echo",
       { note: "hello" },
       TestUsers.admin,
@@ -63,7 +63,7 @@ describe("createRequestHelper via setupTestStack.http", () => {
   });
 
   test("queryOk posts to /api/query and returns handler data", async () => {
-    const data = await stack.http.queryOk<{ id: string; ok: boolean }>(
+    const data = await stack!.http.queryOk<{ id: string; ok: boolean }>(
       "reqhelp:query:lookup",
       { id: "abc" },
       TestUsers.admin,
@@ -72,14 +72,14 @@ describe("createRequestHelper via setupTestStack.http", () => {
   });
 
   test("writeErr returns structured WriteErrorInfo with httpStatus", async () => {
-    const err = await stack.http.writeErr("reqhelp:write:boom", {}, TestUsers.admin);
+    const err = await stack!.http.writeErr("reqhelp:write:boom", {}, TestUsers.admin);
     expect(err.code).toBe("unprocessable");
-    expect(err.httpStatus).toBeGreaterThanOrEqual(400);
+    expect(err.httpStatus).toBe(422);
     expect(err.i18nKey).toBe("errors.unprocessable");
   });
 
   test("queryErr returns structured WriteErrorInfo for not-found", async () => {
-    const err = await stack.http.queryErr(
+    const err = await stack!.http.queryErr(
       "reqhelp:query:lookup",
       { id: "missing" },
       TestUsers.admin,
@@ -89,13 +89,13 @@ describe("createRequestHelper via setupTestStack.http", () => {
   });
 
   test("writeOk throws when the write fails (so suites cannot ignore failures)", async () => {
-    await expect(stack.http.writeOk("reqhelp:write:boom", {}, TestUsers.admin)).rejects.toThrow(
+    await expect(stack!.http.writeOk("reqhelp:write:boom", {}, TestUsers.admin)).rejects.toThrow(
       /reqhelp:write:boom/,
     );
   });
 
   test("batch posts commands and returns per-command results", async () => {
-    const res = await stack.http.batch(
+    const res = await stack!.http.batch(
       [
         { type: "reqhelp:write:echo", payload: { note: "a" } },
         { type: "reqhelp:write:echo", payload: { note: "b" } },
@@ -112,7 +112,7 @@ describe("createRequestHelper via setupTestStack.http", () => {
   });
 
   test("writeWithHeaders forwards extra headers alongside auth", async () => {
-    const res = await stack.http.writeWithHeaders(
+    const res = await stack!.http.writeWithHeaders(
       "reqhelp:write:echo",
       { note: "hdr" },
       TestUsers.admin,
@@ -122,5 +122,19 @@ describe("createRequestHelper via setupTestStack.http", () => {
     const body = (await res.json()) as { isSuccess?: boolean; data?: { note?: string } };
     expect(body.isSuccess).toBe(true);
     expect(body.data?.note).toBe("hdr");
+    expect(res.headers.get("X-Correlation-ID")).toBe("corr-42");
+  });
+
+  test("queryWithHeaders forwards extra headers alongside auth", async () => {
+    const res = await stack!.http.queryWithHeaders(
+      "reqhelp:query:lookup",
+      { id: "abc" },
+      TestUsers.admin,
+      { "X-Correlation-ID": "corr-query" },
+    );
+    expect(res.ok).toBe(true);
+    expect(res.headers.get("X-Correlation-ID")).toBe("corr-query");
+    const body = (await res.json()) as { data?: { id?: string; ok?: boolean } };
+    expect(body.data).toEqual({ id: "abc", ok: true });
   });
 });

package/src/stack/test-stack.ts

@@ -72,6 +72,8 @@ export type TestStackOptions = {
   jwtSecret?: string;
   /** Extra fields merged into the AppContext (e.g. _notifyFactory, configResolver).
    *  Can be a function receiving (registry, db, sseBroker) for late binding. */
+  /** Boot default locale (BCP-47) merged into AppContext before extraContext. */
+  defaultLocale?: string;
   extraContext?:
     | Record<string, unknown>
     | ((deps: {
@@ -294,6 +296,7 @@ export async function setupTestStack(options: TestStackOptions): Promise<TestSta
     registry,
     ...(options.masterKeyProvider ? { masterKeyProvider: options.masterKeyProvider } : {}),
     ...(fileProviderResolver ? { _fileProviderResolver: fileProviderResolver } : {}),
+    ...(options.defaultLocale !== undefined && { defaultLocale: options.defaultLocale }),
     ...(typeof options.extraContext === "function"
       ? options.extraContext({ registry, db: testDb.db, sseBroker, redis: testRedis.redis })
       : options.extraContext),

package/src/ui-types/index.ts

@@ -77,6 +77,7 @@ export type {
   EntityEditScreenDefinition,
   EntityListScreenDefinition,
   FieldCondition,
+  FieldIconKey,
   FieldRenderer,
   FormWidth,
   ListColumnSpec,