@cosmicdrift/kumiko-framework 0.166.0 → 0.167.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.166.0",
+  "version": "0.167.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>",
@@ -182,9 +182,10 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
+    "@cosmicdrift/kumiko-types": "0.167.0",
     "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.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

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/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/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/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";