@cosmicdrift/kumiko-types 0.288.0 → 0.290.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-types",
-  "version": "0.288.0",
+  "version": "0.290.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 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>",

package/src/changes.json

@@ -0,0 +1,14 @@
+[
+  {
+    "version": "0.290.0",
+    "type": "improvement",
+    "title": "EventMetadata: feature + handler + UNATTRIBUTED_ORIGIN",
+    "detail": "EventMetadata traegt zwei neue optionale Felder (feature, handler) und exportiert die Sentinel-Konstante UNATTRIBUTED_ORIGIN fuer Appends ausserhalb eines attribuierten Ausfuehrungsscopes. Additiv, bestehende Zeilen bleiben ohne Backfill lesbar."
+  },
+  {
+    "version": "0.289.0",
+    "type": "improvement",
+    "title": "EntityDefinition gains an optional transferable flag",
+    "detail": "Declares that an entity's rows can move to a different tenant via the tenant-handover bundled feature (kumiko-framework#3035): the root entity, or any parentRef-linked entity, that is NOT declared transferable makes a claim attempt fail with a named error instead of silently leaving its rows behind. Additive — every existing entity is unaffected (transferable defaults to unset/false)."
+  }
+]

package/src/event-store-executor-types.ts

@@ -37,7 +37,26 @@ export type EventStoreExecutor = {
     payload: { id: EntityId; version?: number | undefined; changes: Record<string, unknown> },
     user: SessionUser,
     db: TenantDb,
-    options?: { skipOptimisticLock?: boolean; skipUnchanged?: boolean; preSave?: PreSaveRunner },
+    options?: {
+      skipOptimisticLock?: boolean;
+      skipUnchanged?: boolean;
+      preSave?: PreSaveRunner;
+      // Declarative precondition for a "genau einmal"-transition (kumiko-
+      // framework#3024): field/value pairs the row must still hold at write
+      // time — a `null` expected value matches a null field. Re-read fresh,
+      // atomically with the write's stream version (not the payload's stale
+      // `previous`), so a concurrent writer that already moved the row on is
+      // caught even when it doesn't collide with the stream-version check.
+      // Mismatch fails the whole update with PreconditionFailedError instead
+      // of applying it.
+      // Scalars only (string/number/boolean/null) — the check is `!==`, so an
+      // object/Date/Instant value would compare by reference and silently
+      // never match; a timestamp precondition needs its own scalar mirror
+      // field to check against, not the compound value itself. Also plain
+      // columns only: the check reads raw column values (no decrypt pass),
+      // so a pii/encrypted field can't be used here.
+      expect?: Readonly<Record<string, string | number | boolean | null>>;
+    },
   ) => Promise<WriteResult<SaveContext>>;
 
   delete: (

package/src/event-store-types.ts

@@ -37,8 +37,21 @@ export type EventMetadata = {
   // app reads them when filtering/auditing. Keep values JSON-primitive
   // (string|number|boolean) so JSON serialization stays bulletproof.
   readonly headers?: Readonly<Record<string, string | number | boolean>>;
+  // Feature that owned the execution scope which wrote this event, and the
+  // qualified name of the handler/consumer/job inside it. Derived in
+  // event-store.append() from the ambient request scope, never passed in by
+  // the writer — attribution handed over can lie, attribution derived cannot.
+  // Optional so rows written before #3043 stay readable without a backfill;
+  // every new row carries both, falling back to UNATTRIBUTED_ORIGIN.
+  readonly feature?: string;
+  readonly handler?: string;
 };
 
+// Stamped when an append runs outside any attributed scope (seed scripts,
+// tests, direct event-store use). A distinct value, not an omission —
+// omitted would be indistinguishable from a pre-#3043 row.
+export const UNATTRIBUTED_ORIGIN = "unknown";
+
 // Generic over the payload shape. Default = Record<string, unknown> keeps
 // all existing consumers backwards-compatible; annotate `StoredEvent<MyEventPayload>`
 // where a typed payload read is needed.

package/src/fields.ts

@@ -1012,4 +1012,14 @@ export type EntityDefinition<
   readonly derivedFields?: DerivedFieldsMap;
   /** Optional free-text semantics for the AI agent manifest — see TextFieldDef.description. */
   readonly description?: string;
+  /**
+   * Opts this entity's rows into the `tenant-handover` bundled feature
+   * (kumiko-framework#3035): a row-bound-grant-legitimated ownership change
+   * from an anonymous/public tenant to a freshly signed-up account's tenant.
+   * An entity reachable from a transfer's root — the root itself, or any
+   * entity whose `parentRef` names the root's type — that is NOT declared
+   * `transferable: true` makes the whole transfer fail with a named error
+   * instead of silently leaving that entity's rows behind.
+   */
+  readonly transferable?: boolean;
 };