@cosmicdrift/kumiko-framework 1.0.0 → 2.0.0

package/src/secrets/envelope-cipher.ts

@@ -0,0 +1,53 @@
+// String-in/string-out envelope encryption for TEXT-column stores (config
+// values, entity fields). The stored string is JSON of StoredEnvelope; the
+// kekVersion inside makes every value rotatable via the MasterKeyProvider
+// keyring.
+
+import type { EnvelopeCipher } from "@cosmicdrift/kumiko-types/envelope-cipher-types";
+import { InternalError } from "../errors/classes";
+import type { DekCache } from "./dek-cache";
+import { createDekCache, withDekCache } from "./dek-cache";
+import { decryptValue, encryptValue } from "./envelope";
+import { decodeStoredEnvelope, encodeStoredEnvelope, isStoredEnvelope } from "./stored-envelope";
+import type { MasterKeyProvider } from "./types";
+
+export type { EnvelopeCipher } from "@cosmicdrift/kumiko-types/envelope-cipher-types";
+
+export type EnvelopeCipherOptions = {
+  // Shared DEK cache — pass the app-wide instance so config/entity reads
+  // amortise KEK unwraps together with ctx.secrets.
+  readonly dekCache?: DekCache;
+};
+
+export function createEnvelopeCipher(
+  provider: MasterKeyProvider,
+  opts: EnvelopeCipherOptions = {},
+): EnvelopeCipher {
+  const cached = withDekCache(provider, opts.dekCache ?? createDekCache());
+
+  return {
+    async encrypt(plaintext, scope) {
+      const envelope = await encryptValue(plaintext, provider, scope);
+      return JSON.stringify(encodeStoredEnvelope(envelope));
+    },
+
+    async decrypt(stored, scope) {
+      let parsed: unknown;
+      try {
+        parsed = JSON.parse(stored);
+      } catch {
+        throw new InternalError({
+          message: "[envelope-cipher] stored value is not valid JSON",
+          i18nKey: "secrets.errors.envelope_malformed",
+        });
+      }
+      if (!isStoredEnvelope(parsed)) {
+        throw new InternalError({
+          message: "[envelope-cipher] stored JSON is not a StoredEnvelope",
+          i18nKey: "secrets.errors.envelope_malformed",
+        });
+      }
+      return decryptValue(decodeStoredEnvelope(parsed), cached, scope);
+    },
+  };
+}

package/src/secrets/envelope.ts

@@ -3,7 +3,7 @@
 // carries everything needed to decrypt later.
 
 import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto";
-import type { Envelope, MasterKeyProvider } from "./types";
+import type { Envelope, KeyScope, MasterKeyProvider } from "./types";
 
 const ALGORITHM = "aes-256-gcm";
 const DEK_LENGTH = 32; // AES-256
@@ -14,6 +14,7 @@ const IV_LENGTH = 12; // GCM standard nonce length
 export async function encryptValue(
   plaintext: string,
   provider: MasterKeyProvider,
+  scope?: KeyScope,
 ): Promise<Envelope> {
   // Fresh DEK per value. Reusing DEKs across rows would break forward
   // secrecy (one compromised ciphertext-IV pair leaks information about
@@ -26,7 +27,7 @@ export async function encryptValue(
     const ciphertext = Buffer.concat([cipher.update(plaintext, "utf8"), cipher.final()]);
     const authTag = cipher.getAuthTag();
 
-    const { encryptedDek, kekVersion } = await provider.wrapDek(dek);
+    const { encryptedDek, kekVersion } = await provider.wrapDek(dek, scope);
     return { ciphertext, iv, authTag, encryptedDek, kekVersion };
   } finally {
     // Zero the DEK on best effort regardless of success — if provider.wrapDek
@@ -42,8 +43,9 @@ export async function encryptValue(
 export async function decryptValue(
   envelope: Envelope,
   provider: MasterKeyProvider,
+  scope?: KeyScope,
 ): Promise<string> {
-  const dek = await provider.unwrapDek(envelope.encryptedDek, envelope.kekVersion);
+  const dek = await provider.unwrapDek(envelope.encryptedDek, envelope.kekVersion, scope);
   try {
     const decipher = createDecipheriv(ALGORITHM, dek, envelope.iv);
     decipher.setAuthTag(envelope.authTag);

package/src/secrets/index.ts

@@ -1,17 +1,29 @@
-export { createDekCache, type DekCache, type DekCacheOptions } from "./dek-cache";
+export { createDekCache, type DekCache, type DekCacheOptions, withDekCache } from "./dek-cache";
 export {
   createEnvMasterKeyProvider,
   type EnvMasterKeyProviderOptions,
   type Keyring,
 } from "./env-master-key-provider";
 export { decryptValue, encryptValue } from "./envelope";
+export {
+  createEnvelopeCipher,
+  type EnvelopeCipher,
+  type EnvelopeCipherOptions,
+} from "./envelope-cipher";
 export { assertNoSecretLeak } from "./leak-guard";
 export { rewrapDek } from "./rotation";
+export {
+  decodeStoredEnvelope,
+  encodeStoredEnvelope,
+  isStoredEnvelope,
+  type StoredEnvelope,
+} from "./stored-envelope";
 export {
   type ContainsSecret,
   createSecret,
   type Envelope,
   isSecret,
+  type KeyScope,
   type MasterKeyProvider,
   type Secret,
   type SecretAuditContext,

package/src/secrets/stored-envelope.ts

@@ -0,0 +1,46 @@
+// Canonical at-rest form of an Envelope: every Buffer as base64, ready for
+// jsonb columns (secrets feature) or JSON-stringified TEXT columns
+// (EnvelopeCipher for config values / entity fields). One wire shape for
+// every envelope-encrypted store in the framework.
+
+import type { Envelope } from "./types";
+
+export type StoredEnvelope = {
+  readonly ciphertext: string; // base64
+  readonly iv: string; // base64
+  readonly authTag: string; // base64
+  readonly encryptedDek: string; // base64
+  readonly kekVersion: number;
+};
+
+export function encodeStoredEnvelope(envelope: Envelope): StoredEnvelope {
+  return {
+    ciphertext: envelope.ciphertext.toString("base64"),
+    iv: envelope.iv.toString("base64"),
+    authTag: envelope.authTag.toString("base64"),
+    encryptedDek: envelope.encryptedDek.toString("base64"),
+    kekVersion: envelope.kekVersion,
+  };
+}
+
+export function decodeStoredEnvelope(stored: StoredEnvelope): Envelope {
+  return {
+    ciphertext: Buffer.from(stored.ciphertext, "base64"),
+    iv: Buffer.from(stored.iv, "base64"),
+    authTag: Buffer.from(stored.authTag, "base64"),
+    encryptedDek: Buffer.from(stored.encryptedDek, "base64"),
+    kekVersion: stored.kekVersion,
+  };
+}
+
+export function isStoredEnvelope(value: unknown): value is StoredEnvelope {
+  if (!value || typeof value !== "object") return false;
+  const v = value as Record<string, unknown>; // @cast-boundary parse-boundary after typeof check
+  return (
+    typeof v["ciphertext"] === "string" &&
+    typeof v["iv"] === "string" &&
+    typeof v["authTag"] === "string" &&
+    typeof v["encryptedDek"] === "string" &&
+    typeof v["kekVersion"] === "number"
+  );
+}

package/src/secrets/types.ts

@@ -1,162 +1,2 @@
-// Envelope Encryption types. Separating DEK (per-value) from KEK (central)
-// is what makes key rotation cheap: on rotation we only re-wrap the small
-// encryptedDek, never touch the ciphertext.
-
-import type { TenantId } from "../engine";
-
-// Plaintext-secret wrapper (branded). Carries the actual string internally
-// but the nominal typing stops it from landing in an HTTP response by
-// accident — a response-serializer guard + the reveal() cost make the leak
-// intentional. Framework code that sees `Secret<string>` knows the caller
-// has already gone through the audited ctx.secrets.get path.
-//
-// The brand is a real (non-registered) Symbol so it exists at runtime for
-// isSecret() without clashing with user-land symbols of the same name.
-const SecretBrand: unique symbol = Symbol("kumiko.secret");
-
-export type Secret<T = string> = {
-  readonly [SecretBrand]: true;
-  readonly reveal: () => T;
-};
-
-// Implementation helper — bundled-features uses this to wrap a plaintext after
-// decryption. Kept in the framework so both sides share one canonical brand.
-export function createSecret<T>(value: T): Secret<T> {
-  return {
-    [SecretBrand]: true as const,
-    reveal: () => value,
-  };
-}
-
-// True for any object carrying the Secret brand. Used by the response guard
-// to reject leaks before serialization.
-export function isSecret(v: unknown): v is Secret<unknown> {
-  return typeof v === "object" && v !== null && SecretBrand in v;
-}
-
-// --- Compile-time response guard (R6) --------------------------------------
-//
-// ContainsSecret<T> is `true` only when a Secret<> is DEFINITELY present
-// somewhere in T. The handler-registration guard (defineWriteHandler/
-// defineQueryHandler) turns a `true` into a compile error — the static twin of
-// assertNoSecretLeak's runtime walk.
-//
-// Biased to `false`: anything it cannot inspect — a bare generic type param (a
-// handler generic over its response), `unknown`/`any`, `never` — resolves to
-// `false` = allowed, with the runtime guard as the backstop. The alternative
-// (default-to-leak) false-flags every legitimate generic-over-response handler.
-//
-// Branch order is load-bearing: never/unknown/any first (uninspectable), then
-// Secret, then primitives (covers branded primitives like TenantId without
-// enumerating them), then the SafeLeaf allowlist (opaque class instances that
-// blind `{ [K in keyof T] }` recursion would mangle — the type-level mirror of
-// leak-guard.ts skipping non-plain objects), then arrays, then a "does any
-// field contain a secret" fold over plain objects.
-type Primitive = string | number | boolean | bigint | symbol | null | undefined;
-
-// Opaque built-in leaves a response legitimately carries; never recurse into
-// them. Extend when the bundled-features tsc sweep surfaces a real leaf type.
-type SafeLeaf =
-  | Date
-  | RegExp
-  | Temporal.Instant
-  | Temporal.ZonedDateTime
-  | Temporal.PlainDate
-  | Temporal.PlainDateTime
-  | Temporal.PlainTime
-  | Temporal.PlainYearMonth
-  | Temporal.PlainMonthDay
-  | Temporal.Duration;
-
-export type ContainsSecret<T> = [T] extends [never]
-  ? false
-  : unknown extends T
-    ? false
-    : T extends Secret<unknown>
-      ? true
-      : T extends Primitive
-        ? false
-        : T extends SafeLeaf
-          ? false
-          : T extends readonly (infer U)[]
-            ? ContainsSecret<U>
-            : T extends object
-              ? true extends { [K in keyof T]-?: ContainsSecret<T[K]> }[keyof T]
-                ? true
-                : false
-              : false;
-
-// Per-read audit context. Populated by requireSecretsContext() wrapper so
-// handlers don't need to pass userId/handlerName manually on every call.
-// Undefined for framework-internal reads (rotation job, tests) — the audit
-// table stays a "who touched this credential" log, not a crash-report sink.
-export type SecretAuditContext = {
-  readonly userId: string;
-  readonly handlerName: string;
-};
-
-// Feature code can pass either the raw qualified-name string or a typed
-// handle returned by r.secret. The handle form is safer — renaming the
-// r.secret call updates all references through the import graph.
-export type SecretKeyRef = string | { readonly name: string };
-
-// The ctx.secrets contract. Concrete implementation lives in bundled-features
-// (createSecretsContext) where the DB and MasterKeyProvider are known. This
-// lean interface is what the framework's HandlerContext carries so engine
-// code can talk about it without pulling in bundled-features.
-export interface SecretsContext {
-  get(
-    tenantId: TenantId,
-    key: SecretKeyRef,
-    auditCtx?: SecretAuditContext,
-  ): Promise<Secret<string> | undefined>;
-  // Metadata-only existence probe: no decryption, no read-audit event.
-  // For readiness checks — use get() when the value itself is needed.
-  has(tenantId: TenantId, key: SecretKeyRef): Promise<boolean>;
-  set(
-    tenantId: TenantId,
-    key: SecretKeyRef,
-    value: string,
-    opts?: { redact?: (plaintext: string) => string; hint?: string; updatedBy?: string },
-  ): Promise<void>;
-  delete(tenantId: TenantId, key: SecretKeyRef, opts?: { deletedBy?: string }): Promise<boolean>;
-}
-
-export type Envelope = {
-  // AES-256-GCM ciphertext of the plaintext, keyed with a DEK.
-  readonly ciphertext: Buffer;
-  // GCM nonce (12 bytes). Generated fresh per encryption.
-  readonly iv: Buffer;
-  // GCM auth tag (16 bytes). Guarantees the ciphertext wasn't tampered.
-  readonly authTag: Buffer;
-  // DEK wrapped with the current KEK. Decryption needs provider.unwrapDek
-  // with the kekVersion to recover the DEK.
-  readonly encryptedDek: Buffer;
-  // Which KEK version was used to wrap the DEK. On rotation, rows with old
-  // versions still decrypt — the provider keeps a keyring of historical KEKs.
-  readonly kekVersion: number;
-};
-
-// The contract a KEK backend must fulfil. The framework sees only this
-// interface; concrete implementations live in separate packages
-// (@cosmicdrift/kumiko-secrets-vault, @cosmicdrift/kumiko-secrets-aws-kms, ...). The default is
-// EnvMasterKeyProvider which reads keys from environment variables.
-export interface MasterKeyProvider {
-  // Wrap a fresh DEK with the current KEK. Returns the wrapped bytes + the
-  // KEK version used — the version ends up in the Envelope so decryption
-  // later knows which KEK to ask for.
-  wrapDek(dek: Buffer): Promise<{ encryptedDek: Buffer; kekVersion: number }>;
-
-  // Unwrap a previously-wrapped DEK. During rotation the provider must
-  // accept older kekVersion values (2-version window minimum), otherwise
-  // old rows become unreadable.
-  unwrapDek(encryptedDek: Buffer, kekVersion: number): Promise<Buffer>;
-
-  // Which KEK version new wraps use. Rotation flips this to a new value
-  // and older-version reads continue to work until rows are re-wrapped.
-  currentVersion(): number;
-
-  // Health check: can the provider talk to its backend? Used by
-  // /health/ready. Cheap probe, no KEK material read.
-  isAvailable(): Promise<boolean>;
-}
+// Legacy path — re-exported for callers still importing this module directly.
+export * from "@cosmicdrift/kumiko-types/secrets-types";

package/src/stack/__tests__/event-collector.test.ts

@@ -0,0 +1,42 @@
+import { describe, expect, test } from "bun:test";
+import type { SseEvent } from "../../api/sse-broker";
+import type { SaveContext } from "../../engine/types";
+import { createEventCollector } from "../event-collector";
+
+const probeSseEvent: SseEvent = { type: "probe", data: {} };
+const probeSaveContext: SaveContext = {
+  kind: "save",
+  id: "e1",
+  data: {},
+  changes: {},
+  previous: {},
+  isNew: true,
+};
+
+describe("createEventCollector", () => {
+  test("starts empty", () => {
+    const collector = createEventCollector();
+    expect(collector.sse).toEqual([]);
+    expect(collector.postSave).toEqual([]);
+  });
+
+  test("reset() clears both arrays in place, keeping the same references", () => {
+    const collector = createEventCollector();
+    const sseRef = collector.sse;
+    const postSaveRef = collector.postSave;
+    collector.sse.push(probeSseEvent);
+    collector.postSave.push(probeSaveContext);
+
+    expect(collector.sse).toHaveLength(1);
+    expect(collector.postSave).toHaveLength(1);
+
+    collector.reset();
+
+    expect(collector.sse).toHaveLength(0);
+    expect(collector.postSave).toHaveLength(0);
+    // Same array instances — callers that captured a reference before reset
+    // still see the cleared state, not a stale snapshot.
+    expect(collector.sse).toBe(sseRef);
+    expect(collector.postSave).toBe(postSaveRef);
+  });
+});

package/src/stack/__tests__/setup-test-stack-jobs.integration.test.ts

@@ -0,0 +1,125 @@
+// Drives the manual `ctx.jobRunner.dispatch(...)` path a write handler
+// uses directly — distinct from the auto-trigger path covered by
+// entrypoint-job-wiring.integration.test.ts, which reads a different
+// context slot and isn't guaranteed by this test passing.
+
+import { afterEach, describe, expect, test } from "bun:test";
+import { z } from "zod";
+import { defineFeature } from "../../engine";
+import { InternalError, writeFailure } from "../../errors";
+import { waitFor } from "../../testing";
+import { setupTestStack, type TestStack } from "../test-stack";
+import { TestUsers } from "../test-users";
+
+const jobRuns: Array<{ name: string; payload: Record<string, unknown> }> = [];
+
+const manualDispatchFeature = defineFeature("manualdispatch", (r) => {
+  r.writeHandler(
+    "create",
+    z.object({ note: z.string() }),
+    async (event, ctx) => {
+      // Exact repro from #983: bracket-access, dynamic context extension —
+      // not a typed HandlerContext field (mirrors trigger.write.ts).
+      const jobRunner = ctx["jobRunner"] as
+        | { dispatch: (name: string, payload: Record<string, unknown>) => Promise<string> }
+        | undefined;
+      if (!jobRunner) {
+        return writeFailure(new InternalError({ message: "no jobRunner on ctx" }));
+      }
+      await jobRunner.dispatch("manualdispatch:job:record", { note: event.payload.note });
+      return { isSuccess: true as const, data: { id: 1, note: event.payload.note } };
+    },
+    { access: { openToAll: true } },
+  );
+  r.job("record", { trigger: { manual: true }, runIn: "worker" }, async (payload) => {
+    jobRuns.push({ name: "manualdispatch:job:record", payload });
+  });
+});
+
+// kumiko-framework#1232: setupTestStack used to hand jobs a bare
+// `{ db, registry }` context literal — nothing else buildServer's request
+// path gets (tracer/meter, searchAdapter, ...). A job could pass in tests
+// while reading a field only prod's context has, then break silently on
+// deploy. This job records which fields actually arrived.
+const jobContextFields: Array<{
+  hasTracer: boolean;
+  hasSearchAdapter: boolean;
+  hasEffectiveFeatures: boolean;
+}> = [];
+
+const jobContextFeature = defineFeature("jobcontextcheck", (r) => {
+  r.job("record", { trigger: { manual: true }, runIn: "worker" }, async (_payload, context) => {
+    jobContextFields.push({
+      hasTracer: context.tracer !== undefined,
+      hasSearchAdapter: context.searchAdapter !== undefined,
+      hasEffectiveFeatures: context.effectiveFeatures !== undefined,
+    });
+  });
+});
+
+let stack: TestStack | undefined;
+
+afterEach(async () => {
+  if (stack) await stack.cleanup();
+  stack = undefined;
+});
+
+describe("setupTestStack({ jobs }) wires ctx.jobRunner for manual dispatch", () => {
+  test("write handler's ctx.jobRunner.dispatch(...) works end-to-end", async () => {
+    jobRuns.length = 0;
+    stack = await setupTestStack({
+      features: [manualDispatchFeature],
+      // consumerLane: this test has no separate consumer (unlike runDevApp's
+      // startDevJobRunners), so it must be the one running the job.
+      jobs: { consumerLane: "worker" },
+    });
+
+    await stack.http.writeOk("manualdispatch:write:create", { note: "hi" }, TestUsers.admin);
+
+    await waitFor(() => {
+      const run = jobRuns.find((e) => e.name === "manualdispatch:job:record");
+      expect(run).toBeDefined();
+      expect(run?.payload["note"]).toBe("hi");
+    });
+  });
+
+  test("without `jobs` opt-in, ctx.jobRunner stays undefined (no-op, not a throw)", async () => {
+    stack = await setupTestStack({ features: [manualDispatchFeature] });
+    expect(stack.jobRunner).toBeUndefined();
+
+    // The handler itself guards against a missing jobRunner (writeFailure,
+    // not a thrown TypeError) — same contract as trigger.write.ts's cast.
+    const err = await stack.http.writeErr(
+      "manualdispatch:write:create",
+      { note: "hi" },
+      TestUsers.admin,
+    );
+    expect(err.code).toBe("internal_error");
+  });
+});
+
+describe("setupTestStack({ jobs }) job context matches the request-path context", () => {
+  test("job handler's context carries tracer + searchAdapter, mirrors prod's effectiveFeatures-less job context", async () => {
+    jobContextFields.length = 0;
+    stack = await setupTestStack({
+      features: [jobContextFeature],
+      jobs: { consumerLane: "worker" },
+      effectiveFeatures: () => new Set(["jobcontextcheck"]),
+    });
+
+    await stack.jobRunner?.dispatch("jobcontextcheck:job:record");
+
+    await waitFor(() => {
+      expect(jobContextFields.length).toBeGreaterThan(0);
+    });
+    // #1255: effectiveFeatures deliberately stays OUT of the job/appContext
+    // (prod only carries it in dispatcherOptions.effectiveFeatures, consumed
+    // by the command-dispatcher) — putting it here would let a job read
+    // `ctx.effectiveFeatures` green in tests and break on deploy.
+    expect(jobContextFields[0]).toEqual({
+      hasTracer: true,
+      hasSearchAdapter: true,
+      hasEffectiveFeatures: false,
+    });
+  });
+});

package/src/stack/db.ts

@@ -2,6 +2,7 @@
 // Provider-agnostic via createConnection (DB_PROVIDER env).
 // postgres-js = default. DB_PROVIDER=bun = Bun.SQL (experimentell).
 
+import type { DbConnection } from "@cosmicdrift/kumiko-types/db-connection";
 import { createConnection } from "../db/api";
 import { createDatabase, databaseExists, dropDatabaseIfExists } from "../db/queries/test-stack";
 import { ensureTemporalPolyfill } from "../time/polyfill";
@@ -18,7 +19,7 @@ function requireEnv(name: string): string {
 }
 
 export type TestDb = {
-  db: unknown;
+  db: DbConnection;
   client: unknown;
   dbName: string;
   cleanup: () => Promise<void>;

package/src/stack/push-entity-projection-tables.ts

@@ -1,3 +1,4 @@
+import { KUMIKO_NAME_SYMBOL } from "@cosmicdrift/kumiko-types/schema-table-types";
 import { tableExists } from "../db/schema-inspection";
 import type { Registry } from "../engine/types";
 import { unsafePushTables } from "./table-helpers";
@@ -9,7 +10,7 @@ const logInfo = (msg: string): void => console.log(msg);
 /**
  * Push all implicit-projection tables — one per `r.entity()` — that the
  * registry knows about. setupTestStack already handles explicit
- * projections, MSPs, and `r.rawTable()` declarations in its own loop;
+ * projections, MSPs, and `r.storeTable()` declarations in its own loop;
  * implicit projections are the missing piece for a fresh boot.
  *
  * Idempotent via `tableExists` so a persistent dev DB
@@ -20,7 +21,7 @@ const logInfo = (msg: string): void => console.log(msg);
  * Lives next to `setupTestStack` because both are stack-bootstrap
  * helpers that legitimately speak the `unsafe*`-DDL layer; the
  * Table-DDL Guard's stack/** allowlist is the single shared exemption
- * site. Apps still declare data via `r.entity()` / `r.rawTable()` and
+ * site. Apps still declare data via `r.entity()` / `r.storeTable()` and
  * never call this directly.
  */
 export async function pushEntityProjectionTables(
@@ -35,7 +36,7 @@ export async function pushEntityProjectionTables(
     if (seen.has(proj.table)) continue;
     seen.add(proj.table);
     const tableRec = proj.table as unknown as Record<symbol, unknown>;
-    const physical = tableRec[Symbol.for("kumiko:schema:Name")] as string;
+    const physical = tableRec[KUMIKO_NAME_SYMBOL] as string;
     if (await tableExists(stack.db, `public.${physical}`)) {
       logInfo(`[kumiko-stack] table ${physical} already exists — skipping create`);
       continue;

package/src/stack/redis.ts

@@ -3,6 +3,13 @@ import { requireEnv } from "./db";
 
 export type TestRedis = {
   redis: import("ioredis").default;
+  // The exact REDIS_URL used to build `redis` above — for a second, unrelated
+  // connection (e.g. the test-stack's JobRunner) that needs its own client
+  // rather than sharing this one's keyPrefix. Reconstructing a URL from
+  // `redis.options` loses password/username/tls/path (pr-review
+  // kumiko-framework #1036/2) — callers needing a fresh connection should use
+  // this raw string, not rebuild one from parsed options.
+  redisUrl: string;
   /** Delete every key this test created (prefix-scoped). Replaces the old
    *  `redis.flushdb()` — that wiped other parallel tests' BullMQ state. */
   flushNamespace: () => Promise<void>;
@@ -35,6 +42,7 @@ export async function createTestRedis(): Promise<TestRedis> {
 
   return {
     redis,
+    redisUrl,
     flushNamespace,
     cleanup: async () => {
       await flushNamespace();

package/src/stack/request-helper.ts

@@ -1,4 +1,5 @@
 import type { Hono } from "hono";
+import type { SessionCreator } from "../api/auth-routes";
 import type { JwtHelper } from "../api/jwt";
 import type { SessionUser } from "../engine/types";
 
@@ -98,9 +99,44 @@ export type RequestHelper = {
   ) => Promise<Response>;
 };
 
-export function createRequestHelper(app: Hono, jwt: JwtHelper): RequestHelper {
+export type RequestHelperOptions = {
+  // When sessionChecker is wired (sessions feature), JWTs without jti are
+  // rejected as no_sid. Seed/test helpers that only jwt.sign(user) need a
+  // live sid — create one via the same sessionCreator login uses (#1372).
+  readonly sessionCreator?: SessionCreator;
+};
+
+export function createRequestHelper(
+  app: Hono,
+  jwt: JwtHelper,
+  options: RequestHelperOptions = {},
+): RequestHelper {
+  // sid per (user.id, tenantId), not one mint per authHeader() call:
+  // sessionCreator opens a live session row, so an unmemoized call mints a
+  // fresh one on every request a test makes for the same user — tests
+  // asserting on session counts / massRevoker / revokeAllOthers behavior
+  // then see extra live sids that have nothing to do with what they're
+  // testing. Keyed on tenantId too — the same user.id can hold sessions in
+  // more than one tenant, and sessionCreator writes the row scoped to
+  // `user.tenantId` (session-callbacks.ts), so a user.id-only key would
+  // hand a cross-tenant test its wrong tenant's sid.
+  // Cache the Promise (not the settled sid) so two concurrent authHeader
+  // calls for the same key share one mint instead of racing on a miss.
+  const sidByUserKey = new Map<string, Promise<string>>();
+
   async function authHeader(user: SessionUser): Promise<Record<string, string>> {
-    const token = await jwt.sign(user);
+    let forJwt = user;
+    if (options.sessionCreator && !user.sid) {
+      const key = `${user.id}:${user.tenantId}`;
+      let sidPromise = sidByUserKey.get(key);
+      if (sidPromise === undefined) {
+        sidPromise = options.sessionCreator(user, { ip: "test", userAgent: "request-helper" });
+        sidByUserKey.set(key, sidPromise);
+      }
+      const sid = await sidPromise;
+      forJwt = { ...user, sid };
+    }
+    const token = await jwt.sign(forJwt);
     return { Authorization: `Bearer ${token}` };
   }
 

package/src/stack/table-helpers.ts

@@ -1,3 +1,7 @@
+import {
+  KUMIKO_META_SYMBOL,
+  KUMIKO_NAME_SYMBOL,
+} from "@cosmicdrift/kumiko-types/schema-table-types";
 import type { DbConnection } from "../db/connection";
 import { pgTypeToSqlType } from "../db/dialect";
 import type { ColumnMeta, EntityTableMeta } from "../db/entity-table-meta";
@@ -5,15 +9,13 @@ import {
   alterTableAddColumn,
   createIndexIfNotExists,
   executeDdlStatement,
-  truncateTablesRestartIdentity,
-} from "../db/queries/test-stack";
+} from "../db/queries/ddl";
+import { truncateTablesRestartIdentity } from "../db/queries/test-stack";
 import { renderTableDdl } from "../db/render-ddl";
 import { tableExists } from "../db/schema-inspection";
 import { buildEntityTable, toTableName } from "../db/table-builder";
 import type { EventDispatcher } from "../pipeline";
 
-const KUMIKO_NAME_SYMBOL = Symbol.for("kumiko:schema:Name");
-const KUMIKO_META_SYMBOL = Symbol.for("kumiko:schema:Meta");
 function tableNameOf(table: unknown): string {
   if (typeof table !== "object" || table === null) {
     throw new Error("table-helpers: table is not a SchemaTable object");