@cosmicdrift/kumiko-types 0.305.0 → 0.307.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-types",
-  "version": "0.305.0",
+  "version": "0.307.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>",
@@ -34,6 +34,10 @@
       "types": "./src/event-type-map.ts",
       "default": "./src/event-type-map.ts"
     },
+    "./extension-options-map": {
+      "types": "./src/extension-options-map.ts",
+      "default": "./src/extension-options-map.ts"
+    },
     "./http-route": {
       "types": "./src/http-route.ts",
       "default": "./src/http-route.ts"

package/src/config.ts

@@ -380,8 +380,10 @@ export type JobDefinition = {
   // Enqueue this job once when a runner for its lane starts. Fire-and-forget:
   // the enqueue is awaited, the run is not, so a throwing handler only fails
   // the queue job — the process keeps booting and reports ready.
-  // Deduped on a fixed job id, so it runs at most once per Redis dataset: a
-  // boot job that already ran (or failed) is not retried on a later deploy.
+  // Deduped via a persistent per-queue marker set at enqueue time (not the
+  // fixed job id alone, which BullMQ's bounded retention can evict), so it
+  // runs at most once per Redis dataset: a boot job that already ran (or
+  // failed) is not retried on a later deploy.
   // Never a deploy gate — use `bootGate` for that.
   readonly runOnBoot?: boolean | undefined;
   // Run this job inline while the runner for its lane starts, before cron

package/src/event-store-types.ts

@@ -45,8 +45,23 @@ export type EventMetadata = {
   // every new row carries both, falling back to UNATTRIBUTED_ORIGIN.
   readonly feature?: string;
   readonly handler?: string;
+  // Only set under an anonymous root without public-intake, so event-triggered
+  // jobs keep the personal-data gate.
+  readonly writeOrigin?: WriteOrigin;
 };
 
+export type WriteOrigin = {
+  readonly rootHandler: string;
+  readonly anonymousRoot: boolean;
+  // Only a write-handler root can declare public-intake; a query/stream root never does.
+  readonly publicIntake: boolean;
+  readonly viaJob?: string;
+};
+
+export function isPersonalDataGated(origin: WriteOrigin): boolean {
+  return origin.anonymousRoot && !origin.publicIntake;
+}
+
 // 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.

package/src/extension-options-map.ts

@@ -0,0 +1,21 @@
+// Cross-Feature Compile-Time-Type-Map for `r.useExtension(name, entity, options)`.
+// Augmented per extension point via `declare module "@cosmicdrift/kumiko-framework/engine"`,
+// mirroring event-type-map.ts; names without augmentation stay untyped.
+
+import type { EscapeHatchDeclaration } from "./handlers";
+
+// MUST be `interface` (not `type`): only interfaces support TS declaration-
+// merging. See event-type-map.ts for the same constraint.
+
+// biome-ignore lint/suspicious/noEmptyInterface: declaration-merging marker — augmented per extension point
+export interface KumikoExtensionOptionsMap {}
+
+/** Options shape for an extension name: the augmented hook shape plus `escapeHatch`, or an untyped bag if unaugmented. */
+export type ExtensionOptionsFor<N extends string> = N extends keyof KumikoExtensionOptionsMap
+  ? KumikoExtensionOptionsMap[N] & { readonly escapeHatch?: EscapeHatchDeclaration }
+  : Record<string, unknown>;
+
+/** Rest-tuple for useExtension's positional options arg: required for an augmented name, optional otherwise. */
+export type ExtensionOptionsArgs<N extends string> = N extends keyof KumikoExtensionOptionsMap
+  ? [options: ExtensionOptionsFor<N>]
+  : [options?: Record<string, unknown>];

package/src/feature.ts

@@ -24,6 +24,7 @@ import type {
 } from "./define-handler";
 import type { RegisterEntityCrudOptions } from "./entity-handlers";
 import type { EntityTableMeta } from "./entity-table-meta-types";
+import type { ExtensionOptionsArgs, ExtensionOptionsFor } from "./extension-options-map";
 import type { EntityDefinition } from "./fields";
 import type {
   AccessRule,
@@ -653,9 +654,13 @@ export type FeatureRegistrar<TFeature extends string = string> = {
 
   extendsRegistrar(name: string, def: RegistrarExtensionDef): void;
 
-  useExtension(extensionName: string, entity: NameOrRef, options?: Record<string, unknown>): void;
-  useExtension(
-    definition: { readonly name: string; readonly entity: NameOrRef } & Record<string, unknown>,
+  useExtension<N extends string>(
+    extensionName: N,
+    entity: NameOrRef,
+    ...options: ExtensionOptionsArgs<N>
+  ): void;
+  useExtension<N extends string>(
+    definition: { readonly name: N; readonly entity: NameOrRef } & ExtensionOptionsFor<N>,
   ): void;
 
   /**

package/src/fields.ts

@@ -836,6 +836,38 @@ export type FieldDefinition =
   | FilesFieldDef
   | ImagesFieldDef;
 
+// Exhaustive catalogue of `FieldDefinition["type"]` values, derived from a
+// `Record` so an added/removed union member fails to compile here instead of
+// silently drifting out of sync with the runtime validator that consults
+// this list (feature-ast's pattern-change-schema). Plain array, not a Set —
+// same rationale as NO_WIDGET_FIELD_TYPES (guard-types-class-free.test.ts).
+const FIELD_TYPE_NAME_FLAGS: Record<FieldDefinition["type"], true> = {
+  text: true,
+  longText: true,
+  boolean: true,
+  select: true,
+  multiSelect: true,
+  number: true,
+  bigInt: true,
+  decimal: true,
+  money: true,
+  reference: true,
+  embedded: true,
+  jsonb: true,
+  date: true,
+  timestamp: true,
+  tz: true,
+  locatedTimestamp: true,
+  file: true,
+  image: true,
+  files: true,
+  images: true,
+};
+
+export const FIELD_TYPE_NAMES: readonly FieldDefinition["type"][] = Object.keys(
+  FIELD_TYPE_NAME_FLAGS,
+) as FieldDefinition["type"][];
+
 /** FieldDefinition as an entity-less inline form screen (actionForm,
  *  secretMint) may declare it: a `money` field there has no entity to borrow
  *  `defaultCurrency` from, so it must name its own currency source, or the

package/src/handlers.ts

@@ -4,6 +4,7 @@ import type { ConfigAccessor, ConfigAccessorFactory, ConfigResolver } from "./co
 import type { DbConnection } from "./db-connection";
 import type { DerivativesContext } from "./derivatives-types";
 import type { EntityCache } from "./entity-cache";
+import type { WriteOrigin } from "./event-store-types";
 import type { KumikoEventTypeMap } from "./event-type-map";
 import type { FileContext } from "./file-handle-types";
 import type { FileProviderResolver } from "./file-provider-resolver-types";
@@ -260,8 +261,20 @@ export type JobRunnerRef = {
 // singleton, not bound to one caller's identity. Only write+queryAs — no
 // .query/.stream/.command/.batch/.resolveAuthClaims, that stays Dispatcher-only.
 export type DispatchWriteRef = {
-  readonly write: (user: SessionUser, qn: string, payload: unknown) => Promise<WriteResult>;
-  readonly queryAs: (user: SessionUser, qn: string, payload: unknown) => Promise<unknown>;
+  // A job under a gated anonymous origin passes it, else the target would
+  // reset to the job's own non-anonymous root.
+  readonly write: (
+    user: SessionUser,
+    qn: string,
+    payload: unknown,
+    inheritedOrigin?: WriteOrigin,
+  ) => Promise<WriteResult>;
+  readonly queryAs: (
+    user: SessionUser,
+    qn: string,
+    payload: unknown,
+    inheritedOrigin?: WriteOrigin,
+  ) => Promise<unknown>;
   // Builds a tenant-scoped MemberReader — one per JobContext.queryAsMember
   // caller (job-runner.ts lazily creates one per job run).
   readonly createMemberReader: (tenantId: TenantId) => MemberReader;

package/src/tenant-db-types.ts

@@ -108,7 +108,7 @@ export type UncheckedSystemDb = {
   // durability writes that must survive a rollback of the handler's own
   // transaction. Throws if the dispatch has no outside-transaction source
   // configured (e.g. a hand-built UncheckedSystemDb that only ever passed
-  // the in-tx db to createUncheckedSystemDb).
+  // the in-tx db, as createSystemDbView callers do).
   readonly outsideTransaction: {
     assertTenantMatch(tenantId: TenantId): TenantDb;
     acknowledgeCrossTenant(reason: string): TenantDb;