@cosmicdrift/kumiko-types 0.166.0 → 0.167.1

package/README.md

@@ -7,9 +7,10 @@ Framework type definitions for Kumiko — `FeatureDefinition`, boot-check types,
 and the pure engine types. Lets downstream consumers build against the type
 contracts without importing the whole framework package.
 
-Also contains the identity-sensitive error classes (`event-store-errors.ts`,
-`kms-adapter-types.ts`) as runtime code — `kumiko-framework`/
-`kumiko-bundled-features` declare this package as a `peerDependency`
-(single-copy constraint), not a plain dependency.
+Carries no identity-sensitive runtime values: no classes, and brand symbols use
+`Symbol.for`. Resolving two copies of this package is therefore harmless, so
+`kumiko-framework`/`kumiko-bundled-features` declare it as a plain dependency.
+The error classes callers branch on with `instanceof` live in `kumiko-framework`
+(`/event-store`, `/crypto`), which stays a single copy.
 
 See the [monorepo root README](../../README.md) for the broader pitch.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@cosmicdrift/kumiko-types",
-  "version": "0.166.0",
-  "description": "Framework-Type-Definitions für Kumiko — FeatureDefinition, BootCheck-Types und die reinen Engine-Types. Erlaubt Downstream-Konsumenten, gegen die Type-Contracts zu bauen, ohne das ganze Framework-Package zu importieren. Enthaelt auch die identitaets-sensitiven Error-Klassen (event-store-errors.ts, kms-adapter-types.ts) als Runtime-Code — kumiko-framework/kumiko-bundled-features deklarieren dieses Package deshalb als peerDependency (Single-Copy-Zwang), nicht als plain dependency.",
+  "version": "0.167.1",
+  "description": "Framework-Type-Definitions für Kumiko — FeatureDefinition, BootCheck-Types und die reinen Engine-Types. Erlaubt Downstream-Konsumenten, gegen die Type-Contracts zu bauen, ohne das ganze Framework-Package zu importieren. Enthaelt keine identitaets-sensitiven Runtime-Werte mehr (Error-Klassen leben seit #1629 in kumiko-framework, Brand-Symbole nutzen Symbol.for) und ist deshalb eine plain dependency, keine peerDependency.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
   "repository": {
@@ -206,10 +206,6 @@
       "types": "./src/secrets-types.ts",
       "default": "./src/secrets-types.ts"
     },
-    "./event-store-errors": {
-      "types": "./src/event-store-errors.ts",
-      "default": "./src/event-store-errors.ts"
-    },
     "./kms-adapter-types": {
       "types": "./src/kms-adapter-types.ts",
       "default": "./src/kms-adapter-types.ts"
@@ -228,12 +224,12 @@
     }
   },
   "devDependencies": {
-    "hono": "^4.12.18",
+    "hono": "^4.12.27",
     "postgres": "^3.4.9",
     "temporal-polyfill": "^0.3.2"
   },
   "peerDependencies": {
-    "hono": "^4.12.18",
+    "hono": "^4.12.27",
     "postgres": "^3.4.9",
     "temporal-polyfill": "^0.3.2"
   },

package/src/event-store-types.ts

@@ -1,5 +1,13 @@
 import type { TenantId } from "./identifiers";
 
+// Structural shape of kumiko-framework's VersionConflictError. The class
+// itself cannot live here (#1629) — this package must stay free of
+// identity-sensitive runtime values so it can be a plain dependency.
+export interface VersionConflict extends Error {
+  readonly aggregateId: string;
+  readonly expectedVersion: number;
+}
+
 export type EventMetadata = {
   readonly userId: string;
   readonly requestId?: string;

package/src/handlers.ts

@@ -30,6 +30,10 @@ export type SessionUser = {
   readonly id: string;
   readonly tenantId: TenantId;
   readonly roles: readonly string[];
+  // IANA zone from user.timezone, set at login. Absent → ctx.tz falls back
+  // to tenant.timezone, then "UTC" (buildHandlerContext, fw#1636). Stale
+  // until re-login — same tradeoff as `roles`.
+  readonly timezone?: string;
   // App-specific identity facts baked into the JWT at login time.
   // Populated by `r.authClaims()` hooks (not yet implemented — see the
   // auth-claims design note in docs/plans). Reserved here so the type shape
@@ -479,12 +483,14 @@ export type HandlerContext<TMap extends object = KumikoEventTypeMap> = SharedCon
   readonly metrics: MetricsHandle;
   readonly tracer: Tracer;
 
-  // Time + TZ helper. Feature-Code MUSS hier durch statt `new Date()` —
-  // ctx.tz.now() liefert Temporal.Instant, ctx.tz.parse(wallClock, tz)
-  // produziert ZonedDateTime, ctx.tz.toLocatedJson serialisiert für die
-  // API-Boundary. Lint-Regel gegen `new Date()` kommt sobald alle internen
-  // usages migriert sind. Tenant + User-TZ defaults aktuell "UTC", werden
-  // aus tenant.timezone / user.timezone gelesen sobald die Felder existieren.
+  // Time + TZ helper. Feature code MUST go through this instead of
+  // `new Date()` — ctx.tz.now() returns Temporal.Instant, ctx.tz.parse
+  // (wallClock, tz) produces a ZonedDateTime, ctx.tz.toLocatedJson
+  // serializes for the API boundary. The lint rule against `new Date()`
+  // lands once all internal usages are migrated. tenant reads
+  // tenant:config:timezone (falls back to "UTC" when no config feature is
+  // mounted or the value is unset); user reads SessionUser.timezone (falls
+  // back to tenant).
   readonly tz: TzContext;
 
   // Resolve every registered r.authClaims() hook against `user` and return
@@ -689,7 +695,7 @@ export type UnsafeAppendEventFn = (args: AppendEventArgs) => Promise<void>;
 // entire enclosing transaction.
 export type TryAppendEventResult =
   | { readonly ok: true; readonly event: import("./event-store-types").StoredEvent }
-  | { readonly ok: false; readonly conflict: import("./event-store-errors").VersionConflictError };
+  | { readonly ok: false; readonly conflict: import("./event-store-types").VersionConflict };
 
 export type TryAppendEventFn = (args: AppendEventArgs) => Promise<TryAppendEventResult>;
 

package/src/kms-adapter-types.ts

@@ -95,24 +95,3 @@ export type KmsAdapter = LocalKeyKmsAdapter | RemoteCryptoKmsAdapter;
 export function isLocalKeyKmsAdapter(adapter: KmsAdapter): adapter is LocalKeyKmsAdapter {
   return adapter.capabilities.mode === "local-key";
 }
-
-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/secrets-types.ts

@@ -10,9 +10,14 @@ import type { TenantId } from "./identifiers";
 // 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");
+// Registered symbol, matching KUMIKO_*_SYMBOL in schema-table-types.ts. A
+// plain Symbol() is per-copy: two resolved copies of this package brand with
+// two different symbols, so createSecret() from one and isSecret() from the
+// other disagree — and isSecret() is the ONLY thing assertNoSecretLeak has,
+// so a false there serializes the plaintext into the response. The namespaced
+// key makes accidental user-land collision implausible; a deliberate forge
+// would only over-trigger the guard, which fails safe.
+const SecretBrand: unique symbol = Symbol.for("kumiko.secret");
 
 export type Secret<T = string> = {
   readonly [SecretBrand]: true;

package/src/event-store-errors.ts

@@ -1,54 +0,0 @@
-// 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).
-
-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;
-  }
-}