@cosmicdrift/kumiko-framework 0.166.0 → 0.167.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.166.0",
+  "version": "0.167.1",
   "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>",
@@ -182,9 +182,10 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
+    "@cosmicdrift/kumiko-types": "0.167.1",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
-    "hono": "^4.12.18",
+    "hono": "^4.12.27",
     "i18next": "^26.1.0",
     "ioredis": "^5.10.1",
     "jose": "^6.2.3",
@@ -196,11 +197,8 @@
     "uuid": "^14.0.0",
     "zod": "^4.4.3"
   },
-  "peerDependencies": {
-    "@cosmicdrift/kumiko-types": "^0.166.0"
-  },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.166.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.167.1",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/api/__tests__/jwt.test.ts

@@ -82,6 +82,18 @@ describe("createJwtHelper.verify — payload validation (KF-2)", () => {
       .sign(new TextEncoder().encode(SECRET));
     await expect(jwt.verify(token)).rejects.toThrow(/sub/);
   });
+
+  // fw#1636 — SessionUser.timezone must survive the sign/verify roundtrip
+  // (jwt.sign silently drops any field it doesn't explicitly copy).
+  it("round-trips the timezone claim when set", async () => {
+    const payload = await jwt.verify(await jwt.sign({ ...user, timezone: "Asia/Tokyo" }));
+    expect(payload.timezone).toBe("Asia/Tokyo");
+  });
+
+  it("omits the timezone claim when unset", async () => {
+    const payload = await jwt.verify(await jwt.sign(user));
+    expect(payload.timezone).toBeUndefined();
+  });
 });
 
 describe("createJwtHelper — keyring form", () => {

package/src/api/__tests__/pii-leak-guard.integration.test.ts

@@ -3,12 +3,9 @@
 // rot), Prod → redact + Error-Log, ohne KMS → kein Scan (pass-through).
 
 import { afterAll, afterEach, beforeAll, describe, expect, test } from "bun:test";
+import { resetPiiSubjectKmsForTests } from "@cosmicdrift/kumiko-framework/testing";
 import { z } from "zod";
-import {
-  configurePiiSubjectKms,
-  InMemoryKmsAdapter,
-  resetPiiSubjectKmsForTests,
-} from "../../crypto";
+import { configurePiiSubjectKms, InMemoryKmsAdapter } from "../../crypto";
 import { defineFeature } from "../../engine/define-feature";
 import { defineQueryHandler } from "../../engine/define-handler";
 import { setupTestStack, type TestStack, TestUsers } from "../../stack";

package/src/api/auth-middleware.ts

@@ -307,6 +307,7 @@ export function authMiddleware(jwt: JwtHelper, options: AuthMiddlewareOptions =
       id: payload.sub,
       tenantId: payload.tenantId,
       roles: payload.roles,
+      ...(payload.timezone ? { timezone: payload.timezone } : {}),
       ...(payload.claims ? { claims: payload.claims } : {}),
       ...(payload.jti ? { sid: payload.jti } : {}),
     };

package/src/api/jwt.ts

@@ -10,6 +10,9 @@ export type JwtPayload = {
   sub: string;
   tenantId: TenantId;
   roles: string[];
+  // IANA zone from user.timezone, set at login — see SessionUser.timezone
+  // (fw#1636). Absent → ctx.tz.user falls back to ctx.tz.tenant.
+  timezone?: string;
   // Optional — present when a feature has registered auth claims via the
   // `r.authClaims()` hook system. Absent for stateless-JWT deployments
   // without auth-claims wiring.
@@ -106,6 +109,7 @@ export function createJwtHelper(
         tenantId: user.tenantId,
         roles: [...user.roles],
       };
+      if (user.timezone) body.timezone = user.timezone;
       if (user.claims) body.claims = { ...user.claims };
 
       const header: jose.JWTHeaderParameters = keyring.signKid
@@ -155,6 +159,9 @@ export function createJwtHelper(
         tenantId,
         roles,
       };
+      if (typeof payload["timezone"] === "string") {
+        result.timezone = payload["timezone"];
+      }
       const claims = payload["claims"];
       if (claims && typeof claims === "object") {
         result.claims = claims as DbRow;

package/src/crypto/index.ts

@@ -6,14 +6,12 @@ export {
   configureBlindIndexKey,
   configuredBlindIndexKey,
   decodeBlindIndexKey,
-  resetBlindIndexKeyForTests,
 } from "./blind-index";
 export {
   configuredEventPiiCatalog,
   configureEventPiiCatalog,
   type EventPiiCatalog,
   encryptEventPayloadPii,
-  resetEventPiiCatalogForTests,
 } from "./event-pii";
 export { InMemoryKmsAdapter } from "./in-memory-kms-adapter";
 export {
@@ -64,7 +62,6 @@ export {
   isPiiCiphertext,
   PII_CIPHERTEXT_PREFIX,
   PII_ERASED_SENTINEL,
-  resetPiiSubjectKmsForTests,
 } from "./pii-field-encryption";
 export {
   createRequestKmsCache,

package/src/crypto/kms-adapter.ts

@@ -1,2 +1,27 @@
-// Legacy path — re-exported for callers still importing this module directly.
+import { type SubjectId, subjectIdToKey } from "@cosmicdrift/kumiko-types/kms-adapter-types";
+
 export * from "@cosmicdrift/kumiko-types/kms-adapter-types";
+
+// The KMS error classes live here and not in kumiko-types (#1629): callers
+// branch on them with `instanceof`, which needs a single copy of the class.
+
+export class KeyErasedError extends Error {
+  constructor(public readonly subject: SubjectId) {
+    super(`Subject key erased: ${subjectIdToKey(subject)}`);
+    this.name = "KeyErasedError";
+  }
+}
+
+export class KeyNotFoundError extends Error {
+  constructor(public readonly subject: SubjectId) {
+    super(`Subject key not found: ${subjectIdToKey(subject)}`);
+    this.name = "KeyNotFoundError";
+  }
+}
+
+export class KeyAlreadyExistsError extends Error {
+  constructor(public readonly subject: SubjectId) {
+    super(`Subject key already exists: ${subjectIdToKey(subject)}`);
+    this.name = "KeyAlreadyExistsError";
+  }
+}

package/src/db/__tests__/blind-index.integration.test.ts

@@ -4,6 +4,10 @@
 // dem Ciphertext (erased → NULL), und der Forget-Sweep nullt sofort.
 
 import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import {
+  resetBlindIndexKeyForTests,
+  resetPiiSubjectKmsForTests,
+} from "@cosmicdrift/kumiko-framework/testing";
 import {
   computeBlindIndex,
   configureBlindIndexKey,
@@ -11,8 +15,6 @@ import {
   decodeBlindIndexKey,
   InMemoryKmsAdapter,
   isPiiCiphertext,
-  resetBlindIndexKeyForTests,
-  resetPiiSubjectKmsForTests,
   subjectIdToKey,
 } from "../../crypto";
 import { defineFeature } from "../../engine/define-feature";

package/src/db/__tests__/implicit-projection-equivalence.integration.test.ts

@@ -227,6 +227,10 @@ describe("implicit-projection / Live==Rebuild equivalence", () => {
 // damit auch für sensitive Spalten + Blind-Index. Einzige legitime Divergenz
 // bleibt Crypto-Shredding: DEK erased → bidx NULL, Wert unlesbar.
 
+import {
+  resetBlindIndexKeyForTests,
+  resetPiiSubjectKmsForTests,
+} from "@cosmicdrift/kumiko-framework/testing";
 import {
   computeBlindIndex,
   configureBlindIndexKey,
@@ -235,8 +239,6 @@ import {
   decryptPiiFieldValues,
   InMemoryKmsAdapter,
   isPiiCiphertext,
-  resetBlindIndexKeyForTests,
-  resetPiiSubjectKmsForTests,
 } from "../../crypto";
 import { asRawClient, selectMany } from "../../db/query";
 

package/src/db/index.ts

@@ -48,7 +48,6 @@ export {
   configureEntityFieldEncryption,
   decryptEntityFieldValues,
   encryptEntityFieldValues,
-  resetEntityFieldEncryptionCacheForTests,
 } from "./entity-field-encryption";
 export type {
   BuildEntityTableMetaOptions,

package/src/engine/__tests__/boot-validator-pii-retention.test.ts

@@ -558,6 +558,7 @@ describe("validateBoot — retention", () => {
         createEntity({
           fields: {
             invoiceNumber: createTextField({ allowPlaintext: "is-business-data" }),
+            customerName: createTextField({ pii: true }),
           },
           retention: { keepFor: "10y", strategy: "blockDelete" },
         }),
@@ -570,6 +571,25 @@ describe("validateBoot — retention", () => {
     expect(matchingWarn).toBeDefined();
   });
 
+  test("blockDelete without any subject-annotated field stays silent (#1622)", () => {
+    const feature = defineFeature("test", (r) => {
+      r.entity(
+        "lease",
+        createEntity({
+          fields: {
+            reference: createTextField({ allowPlaintext: "is-business-data" }),
+          },
+          retention: { keepFor: "10y", strategy: "blockDelete" },
+        }),
+      );
+    });
+    validateBoot([feature]);
+    const matchingWarn = warnSpy.mock.calls.find((args: unknown[]) =>
+      String(args[0]).includes('strategy="blockDelete" but no field has an anonymize-function'),
+    );
+    expect(matchingWarn).toBeUndefined();
+  });
+
   test('retention.keepFor with invalid format "30days" warns', () => {
     const feature = defineFeature("test", (r) => {
       r.entity(

package/src/engine/boot-validator/pii-retention.ts

@@ -234,11 +234,17 @@ export function validatePiiAndRetention(feature: FeatureDefinition): void {
       }
 
       if (retention.strategy === "blockDelete") {
+        // blockDelete on an entity with no subject field is the correct
+        // "never auto-delete" choice; User-Forget never reaches those rows (#1622).
+        const hasSubjectField = Object.values(fieldsByName).some((f) => {
+          const a = f as PiiAnnotations; // @cast-boundary schema-walk
+          return Boolean(a.pii || a.userOwned || a.tenantOwned);
+        });
         const hasAnonymize = Object.values(fieldsByName).some((f) => {
           const a = f as PiiAnnotations; // @cast-boundary schema-walk
           return Boolean(a.anonymize);
         });
-        if (!hasAnonymize) {
+        if (hasSubjectField && !hasAnonymize) {
           // biome-ignore lint/suspicious/noConsole: boot-time dev hint, no logger available yet
           console.warn(
             `[kumiko:boot] [Feature ${feature.name}] Entity "${entityName}" retention.strategy="blockDelete" but no field has an anonymize-function. User-Forget cannot anonymize — Forget will return error. Add { anonymize: () => null } or () => "[ANONYMIZED]" to PII fields.`,

package/src/event-store/__tests__/backfill-pii.integration.test.ts

@@ -7,6 +7,10 @@
 // blind-index column, so equality lookups keep working.
 
 import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import {
+  resetBlindIndexKeyForTests,
+  resetPiiSubjectKmsForTests,
+} from "@cosmicdrift/kumiko-framework/testing";
 import { z } from "zod";
 import {
   configureBlindIndexKey,
@@ -14,8 +18,6 @@ import {
   InMemoryKmsAdapter,
   isPiiCiphertext,
   PII_ERASED_SENTINEL,
-  resetBlindIndexKeyForTests,
-  resetPiiSubjectKmsForTests,
 } from "../../crypto";
 import { applyEntityEvent } from "../../db/apply-entity-event";
 import { backfillEventPiiEncryption } from "../../db/queries/backfill-pii";

package/src/event-store/errors.ts

@@ -1,2 +1,58 @@
-// Legacy path — re-exported for callers still importing this module directly.
-export * from "@cosmicdrift/kumiko-types/event-store-errors";
+// Failure modes of the event-store's append() path. Surfaced as typed
+// errors so the executor layer can map them to the framework's
+// WriteResult error contract (version_conflict).
+//
+// These live here and not in kumiko-types (#1629): `instanceof` needs a
+// single copy of the class, which forced kumiko-types to be a peerDependency
+// and made every minor changeset resolve to a major bump.
+
+export class VersionConflictError extends Error {
+  public readonly aggregateId: string;
+  public readonly expectedVersion: number;
+  constructor(aggregateId: string, expectedVersion: number) {
+    super(
+      `Version conflict on aggregate ${aggregateId}: expected predecessor version ${expectedVersion}`,
+    );
+    this.name = "VersionConflictError";
+    this.aggregateId = aggregateId;
+    this.expectedVersion = expectedVersion;
+  }
+}
+
+// Thrown when append() collides on the partial unique index over
+// metadata.idempotencyKey (tenant-scoped). Distinct from VersionConflictError:
+// a version conflict means two writers raced the same predecessor; this
+// means the same idempotency key was used twice, which is a caller-side
+// retry that must have already appended once. Callers that set
+// idempotencyKey should treat this as "already applied" rather than retry.
+export class IdempotentAppendConflictError extends Error {
+  public readonly tenantId: string;
+  public readonly idempotencyKey: string;
+  constructor(tenantId: string, idempotencyKey: string) {
+    super(
+      `Idempotency conflict on tenant ${tenantId}: an event with idempotencyKey "${idempotencyKey}" was already appended.`,
+    );
+    this.name = "IdempotentAppendConflictError";
+    this.tenantId = tenantId;
+    this.idempotencyKey = idempotencyKey;
+  }
+}
+
+// Thrown when ctx.appendEvent targets an archived stream. Archived aggregates
+// are read-only — restoreStream() makes them writable again. The archive
+// state is not carried on the events themselves; it lives on the sparse
+// kumiko_archived_streams table. Handlers that need to branch on archive
+// state should call ctx.isStreamArchived(id) first.
+export class ArchivedStreamError extends Error {
+  public readonly tenantId: string;
+  public readonly aggregateId: string;
+  constructor(tenantId: string, aggregateId: string) {
+    super(
+      `Aggregate ${aggregateId} on tenant ${tenantId} is archived — appendEvent is blocked. ` +
+        `Call restoreStream() to re-open the stream before writing.`,
+    );
+    this.name = "ArchivedStreamError";
+    this.tenantId = tenantId;
+    this.aggregateId = aggregateId;
+  }
+}

package/src/pipeline/dispatch-query.ts

@@ -79,7 +79,7 @@ async function executeQueryInner(
     typeof parsed.data === "object" &&
     parsed.data !== null &&
     (parsed.data as Record<string, unknown>)["includeDeleted"] === true; // @cast-boundary validated-payload
-  const handlerContext = buildHandlerContext(ctx, type, user, tx, undefined, includeDeleted);
+  const handlerContext = await buildHandlerContext(ctx, type, user, tx, undefined, includeDeleted);
   let result = await handler.handler({ type, payload: parsed.data, user }, handlerContext);
 
   // postQuery-Hooks: fire BEFORE field-access-filter so hooks see raw data

package/src/pipeline/dispatch-shared.ts

@@ -146,14 +146,14 @@ async function appendDomainEvent(
   );
 }
 
-export function buildHandlerContext(
+export async function buildHandlerContext(
   ctx: DispatchContext,
   type: string,
   user: SessionUser,
   tx?: DbTx,
   afterCommitHooks?: AfterCommitHook[],
   includeDeleted?: boolean,
-): HandlerContext {
+): Promise<HandlerContext> {
   const { registry, appContext: context, effectiveFeatures, jobRunner } = ctx;
   const isSystem = registry.isHandlerSystemScoped(type);
   // The outer dispatcher receives a DbConnection from the server/stack;
@@ -515,13 +515,19 @@ export function buildHandlerContext(
   // HandlerContext. The spread-then-assign order matters: anything in
   // `context` can be overridden, but we want the authoritative registry
   // from the dispatcher's own closure to win.
-  // ctx.tz ist immer da. Tenant + User-Defaults kommen aus dem
-  // SessionUser sobald die Felder existieren — bis dahin "UTC". Ein
-  // app-injizierter GeoTzProvider (context.geoTzProvider) speist
-  // ctx.tz.fromCoordinates / fromAddress.
-  const tz = createTzContext(
-    context.geoTzProvider !== undefined ? { geoTz: context.geoTzProvider } : {},
-  );
+  // ctx.tz is always present. tenant reads tenant:config:timezone through
+  // the already-built `config` accessor (raw qualified-key — no import of
+  // the tenant feature, framework/pipeline stays bundled-features-free);
+  // falls back to "UTC" when config is missing or the key is unset. user
+  // comes from SessionUser.timezone (set at login), else falls back to
+  // tenant (createTzContext's own default). An app-injected GeoTzProvider
+  // (context.geoTzProvider) feeds ctx.tz.fromCoordinates / fromAddress.
+  const tenantTz = config !== undefined ? await config("tenant:config:timezone") : undefined;
+  const tz = createTzContext({
+    ...(context.geoTzProvider !== undefined ? { geoTz: context.geoTzProvider } : {}),
+    tenant: typeof tenantTz === "string" ? tenantTz : "UTC",
+    ...(user.timezone !== undefined && { user: user.timezone }),
+  });
 
   return {
     ...context,

package/src/pipeline/dispatch-stream.ts

@@ -73,7 +73,7 @@ async function* executeStreamInner(
   // await; close is fire-and-forget instead (#1563).
   let abandonedForInvalidation = false;
   try {
-    const handlerContext = buildHandlerContext(ctx, type, user);
+    const handlerContext = await buildHandlerContext(ctx, type, user);
     const chunks = handler.handler({ type, payload: parsed.data, user }, handlerContext);
     iterator = chunks[Symbol.asyncIterator]();
 

package/src/pipeline/dispatch-write.ts

@@ -348,7 +348,7 @@ async function executeWriteInner(
     }
   }
 
-  const handlerContext = buildHandlerContext(ctx, type, user, tx, afterCommitHooks);
+  const handlerContext = await buildHandlerContext(ctx, type, user, tx, afterCommitHooks);
 
   // Auto transition guard: if entity has transitions and handler doesn't skip it
   if (entityName && !handler.unsafeSkipTransitionGuard) {

package/src/search/__tests__/search-pii-derived-index.integration.test.ts

@@ -2,11 +2,11 @@
 // plaintext in derived search index, purged on subject erase.
 
 import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { resetPiiSubjectKmsForTests } from "@cosmicdrift/kumiko-framework/testing";
 import {
   configurePiiSubjectKms,
   InMemoryKmsAdapter,
   isPiiCiphertext,
-  resetPiiSubjectKmsForTests,
   subjectIdToKey,
 } from "../../crypto";
 import { asRawClient, buildEntityTable, createEventStoreExecutor, createTenantDb } from "../../db";

package/src/secrets/__tests__/leak-guard.test.ts

@@ -89,4 +89,16 @@ describe("assertNoSecretLeak — walks the response tree for branded values", ()
     expect(() => assertNoSecretLeak(undefined)).not.toThrow();
     expect(() => assertNoSecretLeak(null)).not.toThrow();
   });
+
+  // Dual-package hazard: a second resolved copy of @cosmicdrift/kumiko-types
+  // brands with ITS OWN symbol. Constructing the brand from the global registry
+  // here stands in for that copy — with a plain Symbol() the guard walks past
+  // this value and serializes the plaintext (#1438-adjacent).
+  test("catches a Secret branded by another copy of the package", () => {
+    const foreign = {
+      [Symbol.for("kumiko.secret")]: true as const,
+      reveal: () => "plaintext-from-another-copy",
+    };
+    expect(() => assertNoSecretLeak({ payload: foreign })).toThrow(/leaked.*payload/);
+  });
 });

package/src/testing/index.ts

@@ -1,7 +1,16 @@
-// Test-Assertions, Domain-Test-Fixtures und Vitest-spezifische Helpers.
-// Production-Code (dev-server, bin/) darf NICHTS aus diesem Sub-Path importieren —
-// die Stack-Builder leben in `@cosmicdrift/kumiko-framework/stack`, dieses Modul darf
-// vitest-Imports top-level enthalten (siehe expect-error.ts).
+// Test assertions and domain test fixtures. Production code (dev-server, bin/)
+// must import nothing from this subpath — the stack builders live in
+// `@cosmicdrift/kumiko-framework/stack`.
+
+// The four cache/injection resets stay in their own modules (they close over
+// module-private state) and are only re-exported here — they are out of /crypto
+// and /db as of #1631. A production call to resetPiiSubjectKmsForTests() silently
+// switches the PII layer off, and subject-annotated fields are written in
+// plaintext from then on: no error, no log.
+export { resetBlindIndexKeyForTests } from "../crypto/blind-index";
+export { resetEventPiiCatalogForTests } from "../crypto/event-pii";
+export { resetPiiSubjectKmsForTests } from "../crypto/pii-field-encryption";
+export { resetEntityFieldEncryptionCacheForTests } from "../db/entity-field-encryption";
 
 export { rolesOf } from "./access-assertions";
 export { expectError, expectSuccess } from "./assertions";

package/src/time/tz-context.ts

@@ -10,9 +10,10 @@
 // Feature code should no longer call `new Date()` — the lint rule for that
 // lands in a later iteration, once all existing usages are migrated.
 //
-// `tenant` + `user` are the TZ defaults for the current request. Currently
-// both default to "UTC" — once tenant.timezone + user.timezone fields
-// exist, they get read from the request context here.
+// `tenant` + `user` are the TZ defaults for the current request — resolved
+// by buildHandlerContext (tenant:config:timezone, then SessionUser.timezone,
+// falling back to "UTC" at each step) and passed in via TzContextOptions.
+// This factory itself stays a pure default-filler.
 //
 // The pure type contracts (TzContext, TzContextOptions, LocatedTimestampJson)
 // live in @cosmicdrift/kumiko-types/tz-context — only the factories are here.