@cosmicdrift/kumiko-types 0.164.0 → 2.0.0

package/LICENSE

@@ -4,7 +4,7 @@ Parameters
 
 Licensor:             Marc Frost
 
-Licensed Work:        @cosmicdrift/kumiko-framework
+Licensed Work:        @cosmicdrift/kumiko-types
                       The Licensed Work is © 2026 Marc Frost.
 
 Additional Use Grant: 

package/README.md

@@ -0,0 +1,15 @@
+# @cosmicdrift/kumiko-types
+
+[![License: BUSL-1.1](https://img.shields.io/badge/License-BUSL--1.1-blue.svg)](../../LICENSE)
+[![TypeScript](https://img.shields.io/badge/TypeScript-strict-blue.svg)](https://www.typescriptlang.org/)
+
+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.
+
+See the [monorepo root README](../../README.md) for the broader pitch.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@cosmicdrift/kumiko-types",
-  "version": "0.164.0",
-  "description": "Framework-Type-Definitions für Kumiko — FeatureDefinition, BootCheck-Types und die reinen Engine-Types, ohne Runtime-Code. Erlaubt Downstream-Konsumenten, gegen die Type-Contracts zu bauen, ohne das ganze Framework-Package zu importieren.",
+  "version": "2.0.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.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
   "repository": {
@@ -227,9 +227,15 @@
       "default": "./src/snapshot-types.ts"
     }
   },
-  "dependencies": {
+  "devDependencies": {
     "hono": "^4.12.18",
-    "postgres": "^3.4.9"
+    "postgres": "^3.4.9",
+    "temporal-polyfill": "^0.3.2"
+  },
+  "peerDependencies": {
+    "hono": "^4.12.18",
+    "postgres": "^3.4.9",
+    "temporal-polyfill": "^0.3.2"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org",

package/src/concurrency-mode.ts

@@ -1,2 +1,5 @@
-// Keep in sync with ConcurrencyModes in packages/framework/src/engine/constants.ts.
+// Canonical source — packages/framework/src/engine/constants.ts's
+// ConcurrencyModes value object is `satisfies Record<string, ConcurrencyMode>`
+// against this type, so adding a mode only here (or only there) is a compile
+// error instead of silent drift (#1423/#1439).
 export type ConcurrencyMode = "parallel" | "skip" | "replace" | "sequential" | "debounce";

package/src/config-scope.ts

@@ -1,2 +1,5 @@
-// Keep in sync with ConfigScopes in packages/framework/src/engine/constants.ts.
+// Canonical source — packages/framework/src/engine/constants.ts's
+// ConfigScopes value object is `satisfies Record<string, ConfigScope>`
+// against this type, so adding a scope only here (or only there) is a
+// compile error instead of silent drift (#1423/#1439).
 export type ConfigScope = "system" | "tenant" | "user";

package/src/config.ts

@@ -202,8 +202,8 @@ export type ConfigStoredRow = {
   readonly userId: string | null;
 };
 
-// Extended row returned by ConfigResolver.getAllWithSource — includes the
-// resolution source so the UI can display where each value came from.
+// Extended row with resolution source so the UI can display where each
+// value came from.
 export type ConfigStoredRowWithSource = ConfigStoredRow & {
   readonly source: ConfigValueSource;
 };
@@ -280,16 +280,6 @@ export type ConfigResolver = {
     db: DbConnection | TenantDb,
   ): Promise<ReadonlyMap<string, ConfigStoredRow>>;
 
-  // Like getAll() but also reports the resolution source for each key.
-  // Use when the caller needs to display the cascade origin (e.g. the
-  // values.query handler serves the UI's hierarchy badge). Hot-path
-  // callers should prefer getAll() for the narrower return type.
-  getAllWithSource(
-    tenantId: TenantId,
-    userId: string,
-    db: DbConnection | TenantDb,
-  ): Promise<ReadonlyMap<string, ConfigStoredRowWithSource>>;
-
   // Returns ALL cascade levels for a single key — not just the winner.
   // Each level shows its value (or undefined if not set) and whether it
   // is the active/winning level. Levels are ordered by specificity
@@ -354,6 +344,15 @@ export type JobTrigger =
   // maintenance.start) statt N r.job-Calls mit demselben Handler-Body.
   // Im Handler-payload landet `_triggerName: string` damit der Code
   // weiß, welcher Trigger gefeuert hat.
+  //
+  // Two delivery semantics depending on what `on` resolves to (kumiko-
+  // framework#1505): a write/query-handler QN dispatches synchronously
+  // from dispatch-write.ts's afterCommitHooks — effectively once. An
+  // r.defineEvent QN (e.g. one an r.multiStreamProjection appends via
+  // ctx.unsafeAppendEvent) dispatches async via the job-trigger
+  // event-consumer (createJobTriggerEventConsumer, pipeline/system-
+  // hooks.ts) — cursor delivery, at-least-once. Handlers triggered on an
+  // r.defineEvent QN must be idempotent.
   | { readonly on: import("./handlers").NameOrRef | readonly import("./handlers").NameOrRef[] }
   | { readonly cron: string }
   | { readonly manual: true };

package/src/db-connection.ts

@@ -1,9 +1,23 @@
 import type postgres from "postgres";
 
-// biome-ignore lint/suspicious/noExplicitAny: Bun.SQL global type
-export type DbConnection = ReturnType<typeof postgres> | any;
-// biome-ignore lint/suspicious/noExplicitAny: postgres-js namespace lookup
-export type DbTx = postgres.TransactionSql<any> | any;
+// Minimal structural surface both postgres-js and Bun.SQL satisfy for
+// asRawClient() / query helpers. Avoid `| any` — TS unions with `any`
+// collapse to `any` and erase the postgres side entirely.
+export type RawDbClient = {
+  // Signatures are intentionally loose: postgres-js uses (string, values?),
+  // Bun.SQL uses tagged templates / unsafe(string). Call sites go through
+  // asRawClient() which normalizes at runtime.
+  // biome-ignore lint/suspicious/noExplicitAny: cross-provider unsafe arity
+  unsafe: (...args: any[]) => any;
+  // biome-ignore lint/suspicious/noExplicitAny: cross-provider begin arity
+  begin: (...args: any[]) => any;
+  end?: (options?: { timeout?: number }) => Promise<void>;
+};
+
+// Raw SQL client (postgres-js instance or Bun.SQL). Distinct from the
+// framework's structural pool handle (`DbPoolHandle` in db/api.ts).
+export type DbConnection = ReturnType<typeof postgres> | RawDbClient;
+export type DbTx = postgres.TransactionSql<Record<string, unknown>> | RawDbClient;
 export type DbRunner = DbConnection | DbTx;
 export type DbRow = Record<string, unknown>;
 export type PgClient = ReturnType<typeof postgres>;

package/src/entity-table-meta-types.ts

@@ -81,7 +81,7 @@ export type EntityTableMeta = {
 export type BuildEntityTableMetaOptions = {
   readonly featureName?: string;
   readonly relations?: EntityRelations;
-  readonly source?: "managed" | "unmanaged";
+  readonly source?: EntityTableMeta["source"];
 };
 
 export type UnmanagedTableInput = {

package/src/fields.ts

@@ -220,6 +220,8 @@ export type NumberFieldDef = {
   readonly default?: number;
   readonly access?: FieldAccess;
   readonly min?: number;
+  /** Upper bound at the write boundary (Zod `.max`). */
+  readonly max?: number;
   /** `true` → `integer` column + `.int()` Zod validation. Omitted/`false` →
    *  `double precision` column, fractional values allowed. */
   readonly integer?: boolean;

package/src/file-storage-provider-types.ts

@@ -20,6 +20,12 @@ export type WriteStreamOptions = {
 // shuttle bytes. `mimeType` on write() is a hint for providers that need a
 // Content-Type header (S3/R2/…); local filesystems can ignore it.
 //
+// writeStream/readStream are required, not optional: user-data-export jobs
+// need streams for large files, and providers can satisfy the contract with
+// a single-chunk yield if they don't have a native stream API — an optional
+// type here would let a provider skip them and fail silently in production
+// the first time an export job hits it.
+//
 // getSignedUrl is optional — providers without native presigned-URL support
 // (filesystem) leave it undefined; the route then returns 501 and the
 // client falls back to streaming via GET /files/:id. Callers must

package/src/handlers.ts

@@ -272,6 +272,12 @@ type SharedContextFields = {
   // the same process. Returns the Set of feature names effectively
   // enabled for that tenant. Absent = all features on (back-compat).
   readonly effectiveFeatures?: (tenantId: TenantId) => ReadonlySet<string>;
+  // Queue a side-effect to run after the outermost write transaction commits
+  // (same sink as ctx.write / dispatch-write lifecycle afterCommit). Seed
+  // helpers and other mid-tx callers use this instead of firing afterCommit
+  // hooks synchronously (kumiko-framework#1566). Absent outside a write
+  // pipeline — callers fall back to immediate fire (fixture / no-tx paths).
+  readonly scheduleAfterCommit?: (hook: () => Promise<void>) => void;
 };
 
 // All optional — used at pipeline/system boundaries.

package/src/observability/index.ts

@@ -1,5 +1,4 @@
-// Barrel for observability types. Split into span/metric/provider files so
-// each module stays focused; consumers still import from "./types".
+// Barrel for observability types. Split into span/metric/provider so each module stays focused.
 
 export type {
   Counter,

package/src/rate-limit-types.ts

@@ -1,3 +1,5 @@
+import type { Temporal } from "temporal-polyfill";
+
 export type RateLimitDecision = {
   readonly allowed: boolean;
   readonly limit: number;

package/src/relations.ts

@@ -1,5 +1,7 @@
-// Keep in sync with OnDeleteStrategies in packages/framework/src/engine/constants.ts.
-type OnDeleteStrategy = "cascade" | "restrict" | "setNull" | "nothing";
+// Canonical definition — packages/framework/src/engine/constants.ts imports
+// this type and binds its OnDeleteStrategies runtime object to it via
+// `satisfies`, so a drift between the two fails to compile.
+export type OnDeleteStrategy = "cascade" | "restrict" | "setNull" | "nothing";
 
 // --- Relations ---
 

package/src/schema-table-types.ts

@@ -5,6 +5,11 @@ import type { EntityTableMeta, PgType } from "./entity-table-meta-types";
 // exactly the same unique-symbol type as the one used to construct the table.
 export const KUMIKO_NAME_SYMBOL = Symbol.for("kumiko:schema:Name");
 export const KUMIKO_COLUMNS_SYMBOL = Symbol.for("kumiko:schema:Columns");
+// Shadow-proof handle on the canonical EntityTableMeta — SchemaTable also
+// spreads these fields as enumerable string-keyed props, which an entity
+// field named `source`/`columns`/`tableName`/… could shadow; readers that
+// need the canonical meta regardless of shadowing use this symbol instead.
+export const KUMIKO_META_SYMBOL = Symbol.for("kumiko:schema:Meta");
 
 // Column handle exposed on the SchemaTable. The `name` is the SQL column
 // name (snake_case); legacy code accesses `table.fieldName.name` to
@@ -20,5 +25,6 @@ export type ColumnHandle = {
 export type SchemaTable = EntityTableMeta & {
   readonly [KUMIKO_NAME_SYMBOL]: string;
   readonly [KUMIKO_COLUMNS_SYMBOL]: Record<string, ColumnHandle>;
+  readonly [KUMIKO_META_SYMBOL]: EntityTableMeta;
   readonly [field: string]: unknown;
 };

package/src/tz-context.ts

@@ -7,7 +7,7 @@
 import type { GeoAddress, GeoCoordinates, GeoTzProvider } from "./geo-tz";
 
 // JSON form for wall-clock + TZ — see createLocatedTimestampField() in
-// engine/factories.ts. Two fields, foolproof.
+// @cosmicdrift/kumiko-framework, engine/factories.ts. Two fields, foolproof.
 export type LocatedTimestampJson = {
   /** Wall-clock ISO without offset, e.g. "2026-04-03T10:00:00" */
   readonly at: string;

package/src/where-clause-types.ts

@@ -1,5 +1,8 @@
 // WhereValue: primitive for eq, array for IN, null for IS NULL, or an
-// operator-object for range/comparisons.
+// operator-object for range/comparisons. Deliberately NOT `unknown |
+// WhereOperator` — that union collapses to `unknown` and erases the
+// operator form at every call site (a typo like `{ gtee: x }` would
+// type-check, then bind as eq at runtime).
 export type WhereOperator = {
   readonly gt?: unknown;
   readonly gte?: unknown;
@@ -9,8 +12,11 @@ export type WhereOperator = {
   readonly in?: readonly unknown[];
   readonly like?: string;
 };
-export type WhereValue = unknown | WhereOperator;
-export type WhereObject = Record<string, WhereValue>;
+export type WherePrimitive = string | number | boolean | bigint | Date | null | undefined;
+export type WhereValue = WherePrimitive | readonly WherePrimitive[] | WhereOperator;
+// Wider index so dynamic Record<string, unknown> builders still typecheck;
+// annotate literals as WhereValue / satisfies WhereValue to catch typos.
+export type WhereObject = Record<string, WhereValue | unknown>;
 
 export type OrderByClause = {
   readonly col: string;

package/src/write-error-info-types.ts

@@ -12,10 +12,8 @@ export type WriteErrorInfo = {
   readonly details?: unknown;
 };
 
-// The failure half of WriteResult — `{ isSuccess: false } + error`. Named
-// so the write-failure factories in write-error-info.ts and WriteResult
-// share one shape instead of restating it. Not generic: the error carries
-// zero data, so there's nothing for the caller to narrow.
+// The failure half of WriteResult — `{ isSuccess: false } + error`. Not
+// generic: the error carries zero data, so there's nothing to narrow.
 export type WriteFailure = {
   readonly isSuccess: false;
   readonly error: WriteErrorInfo;