@cosmicdrift/kumiko-types 0.163.3 → 0.165.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-types",
-  "version": "0.163.3",
+  "version": "0.165.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.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",

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/event-store-errors.ts

@@ -15,6 +15,25 @@ export class VersionConflictError extends Error {
   }
 }
 
+// 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

package/src/event-store-types.ts

@@ -12,6 +12,14 @@ export type EventMetadata = {
   // set to event.id when an MSP-apply runs ctx.appendEvent. Together with
   // correlationId forms a causation DAG across aggregate streams.
   readonly causationId?: string;
+  // Opt-in second line of defense against duplicate appends when the
+  // Redis-backed HTTP idempotency guard (pipeline/idempotency.ts) misses a
+  // retry window (Redis unreachable, TTL race). Callers that want a hard
+  // per-event uniqueness guarantee set a stable key derived from the
+  // triggering request; the event-store enforces it via a tenant-scoped
+  // partial unique index and throws IdempotentAppendConflictError on a
+  // repeat. Unset by default — no uniqueness constraint applies.
+  readonly idempotencyKey?: string;
   // Marten-conform free key/value space for app-specific metadata that
   // doesn't deserve its own EventMetadata field. Examples: A/B-test bucket,
   // feature-flag snapshot, geo-region, client SDK version. Persisted into

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