@cosmicdrift/kumiko-types 0.197.1 → 0.199.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-types",
-  "version": "0.197.1",
+  "version": "0.199.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>",
@@ -162,6 +162,10 @@
       "types": "./src/nav.ts",
       "default": "./src/nav.ts"
     },
+    "./nav-icon": {
+      "types": "./src/nav-icon.ts",
+      "default": "./src/nav-icon.ts"
+    },
     "./ownership": {
       "types": "./src/ownership.ts",
       "default": "./src/ownership.ts"

package/src/config.ts

@@ -3,7 +3,7 @@ import type { ConcurrencyMode } from "./concurrency-mode";
 import type { ConfigScope } from "./config-scope";
 import type { DbConnection } from "./db-connection";
 import type { FieldDefinition } from "./fields";
-import type { AppContext } from "./handlers";
+import type { JobContext } from "./handlers";
 import type {
   PostDeleteHookFn,
   PostSaveHookFn,
@@ -12,6 +12,7 @@ import type {
   PreSaveHookFn,
 } from "./hooks";
 import type { TenantId } from "./identifiers";
+import type { NavIconKey } from "./nav-icon";
 import type { TenantDb } from "./tenant-db-types";
 
 // --- Config ---
@@ -154,12 +155,12 @@ export type ConfigKeyDefinition<T extends ConfigKeyType = ConfigKeyType> = {
   readonly group?: string;
 };
 
-// Label-Träger für den Settings-Hub. `title` ist ein i18n-Key (kein Literal —
-// Guard), `icon` ein Icon-Registry-Key für den Nav-Eintrag, `order` die
-// Sortier-Gewichtung innerhalb seiner Audience-Gruppe.
+// Label carrier for the settings hub. `title` is an i18n key (no literal —
+// guarded), `icon` a NavIconKey for the nav entry, `order` the sort weight
+// within its audience group.
 export type ConfigMask = {
   readonly title: string;
-  readonly icon?: string;
+  readonly icon?: NavIconKey;
   readonly order?: number;
 };
 
@@ -335,7 +336,7 @@ export type JobRunIn = Exclude<RunIn, "both">;
 
 // --- Jobs ---
 
-export type JobHandlerFn = (payload: Record<string, unknown>, context: AppContext) => Promise<void>;
+export type JobHandlerFn = (payload: Record<string, unknown>, context: JobContext) => Promise<void>;
 
 export type JobTrigger =
   // `on` akzeptiert ein einzelnes Handler-Ref ODER eine Liste. Multi-

package/src/feature.ts

@@ -932,6 +932,10 @@ export type Registry = {
   ): readonly SearchPayloadContributorFn[];
   getHandlerEntity(qualifiedHandler: string): string | undefined;
   isHandlerSystemScoped(qualifiedHandler: string): boolean;
+  // Job counterpart to isHandlerSystemScoped — a job's owning feature is
+  // tracked separately (jobFeatureMap) since jobs aren't write/query/stream
+  // handlers and don't populate handlerFeatureMap.
+  isJobSystemScoped(qualifiedJobName: string): boolean;
   getHandlerFeature(qualifiedHandler: string): string | undefined;
   // True iff at least one registered handler declares a `rateLimit`
   // option. Pre-computed at registry-build so the boot path can skip

package/src/handlers.ts

@@ -177,6 +177,7 @@ export type WriteResult<TData = unknown> =
 // Forward import: Registry is in feature.ts (circular type import — fine in TS)
 import type { Registry } from "./feature";
 import type { TenantId } from "./identifiers";
+import type { UncheckedSystemDb } from "./tenant-db-types";
 
 // Minimal interface for job event triggers (framework-owned, concrete type in jobs/)
 export type JobRunnerRef = {
@@ -187,6 +188,17 @@ export type JobRunnerRef = {
   ): Promise<void>;
 };
 
+// Minimal interface a JobRunner attaches via attachDispatcher() to reach the
+// write pipeline — framework-owned, concrete type wraps the dispatcher's
+// executeWrite/executeQuery. Unlike HandlerContext.write (identity implicit
+// via closure), both take an explicit user: a JobRunner is a boot-time
+// 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>;
+};
+
 // Priority levels for notifications
 export type NotifyPriority = "critical" | "normal" | "low";
 
@@ -347,6 +359,9 @@ export type HandlerContext<TMap extends object = KumikoEventTypeMap> = SharedCon
   // outside the DB. `undefined` when the pipeline has no outside-tx source
   // for this dispatch (see dispatch-shared.ts) — callers must check before use.
   readonly dbOutsideTransaction: TenantDb | undefined;
+  // Only present for r.systemScope() handlers, bound to the same `db` as above.
+  // Non-system handlers never receive this — reach for `db` instead.
+  readonly systemDb?: UncheckedSystemDb;
   readonly registry: Registry;
   /** Aktiver SessionUser des Handler-Aufrufs — Convenience-Alias zu
    *  `event.user`. Existiert weil Handler intuitiv `ctx.user.tenantId`
@@ -544,13 +559,43 @@ export type HandlerContext<TMap extends object = KumikoEventTypeMap> = SharedCon
   readonly resolveAuthClaims: (user: SessionUser) => Promise<Record<string, unknown>>;
 };
 
-// Job execution: db + registry + systemUser + logging guaranteed
+// Job execution: db + registry + systemUser + logging guaranteed, plus a
+// write path into the same dispatcher pipeline write-handlers use.
+//
+// write/queryAs throw until JobRunner.attachDispatcher() has run — a call
+// this early is a framework boot bug, not a job-author mistake.
+//
+// Identity is implicit: write runs as the job's own systemUser, tenant-
+// scoped via the job's _tenantId (falls back to SYSTEM_TENANT_ID for jobs
+// with no tenant context, e.g. plain cron jobs). A job that writes without
+// fanning out per-tenant (`_perTenant:` trigger) silently writes into the
+// system tenant instead of each tenant it may have meant to reach — no
+// guard against this, only this warning.
 export type JobContext = SharedContextFields & {
   readonly db: DbConnection;
   readonly registry: Registry;
   readonly systemUser: SessionUser;
   readonly log: Logger;
   readonly triggeredBy: { readonly id: string; readonly tenantId: TenantId } | null;
+  // Only present for jobs whose owning feature declares r.systemScope(),
+  // mirroring HandlerContext.systemDb (dispatch-shared.ts buildHandlerContext).
+  // assertTenantMatch()/acknowledgeCrossTenant() return a TenantDb, not the
+  // raw DbConnection above — job code that needs a DbRunner for a helper
+  // like reindexEntity() reaches through `.raw` on that TenantDb. `.raw`
+  // bypasses tenant filtering entirely, so it's only safe to hand to a
+  // helper that filters by tenantId itself (as reindexEntity does) — never
+  // pass it to code that trusts the connection to already be scoped.
+  readonly systemDb?: UncheckedSystemDb;
+  readonly write: (qn: string, payload: unknown) => Promise<WriteResult>;
+  readonly queryAs: (user: SessionUser, qn: string, payload: unknown) => Promise<unknown>;
+  // Multi-trigger jobs (`on: [...]`) use this to tell which trigger fired —
+  // undefined for cron/manual jobs. Mirrors AppContext.triggerName.
+  readonly triggerName?: string;
+  // Fallback tenant/user when systemUser doesn't carry it (tenant-less cron
+  // jobs). Mirrors AppContext._tenantId/_userId — see the tenant-scoping
+  // footgun above.
+  readonly _tenantId?: TenantId;
+  readonly _userId?: string | undefined;
 };
 
 // --- Handler Functions ---

package/src/identifiers.ts

@@ -15,6 +15,14 @@ export type TenantId = string;
 // the system boundary.
 const TENANT_ID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
 
+// Shared shape check for any UUID-formatted identifier crossing an
+// untrusted boundary (fileRefId, entity ids, ...) — same loose,
+// version-agnostic regex as TENANT_ID_REGEX (v4/v7/nil all match), kept as
+// one predicate so call sites don't grow their own copy of the shape.
+export function isUuid(value: unknown): value is string {
+  return typeof value === "string" && TENANT_ID_REGEX.test(value);
+}
+
 // Validates a candidate string against the tenantId format and returns it
 // as a TenantId, or `null` when it doesn't match. Use at every system
 // boundary that admits untrusted input (HTTP headers, cookies, query
@@ -22,9 +30,7 @@ const TENANT_ID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-
 // of the rejection shape — middleware returns 400, batch jobs may filter
 // + log, and unit tests don't need a try/catch.
 export function parseTenantId(value: unknown): TenantId | null {
-  if (typeof value !== "string") return null;
-  if (!TENANT_ID_REGEX.test(value)) return null;
-  return value;
+  return isUuid(value) ? value : null;
 }
 
 // "System-scope" tenant marker: handlers carry this tenantId when the event

package/src/nav-icon.ts

@@ -0,0 +1,56 @@
+// Closed vocabulary of nav icon keys. NavDefinition.icon, ScreenNavSugar.icon
+// and ConfigMask.icon are all typed against this union, so an unregistered
+// key is a compile error at the r.nav()/r.screen()/config-mask call site
+// instead of a silent missing-icon at runtime.
+//
+// The renderer-web NAV_ICONS map (packages/renderer-web/src/layout/
+// nav-tree.tsx) is checked against this same union via `satisfies`, so the
+// two can't drift — add a key here only together with its lucide-react entry
+// there, and vice versa.
+export type NavIconKey =
+  | "dashboard"
+  | "layout-grid"
+  | "book-open"
+  | "clipboard-list"
+  | "package"
+  | "gauge"
+  | "list"
+  | "table"
+  | "layers"
+  | "building"
+  | "calculator"
+  | "wallet"
+  | "coins"
+  | "credit-card"
+  | "piggy-bank"
+  | "receipt"
+  | "chart"
+  | "bar-chart"
+  | "trending"
+  | "sparkles"
+  | "wand"
+  | "calendar"
+  | "file"
+  | "folder"
+  | "folder-open"
+  | "home"
+  | "bell"
+  | "shield"
+  | "settings"
+  | "users"
+  | "user"
+  | "search"
+  | "tag"
+  | "key"
+  | "link"
+  | "palette"
+  | "share"
+  | "server"
+  | "mail"
+  | "lock"
+  | "hash"
+  | "download"
+  | "upload"
+  | "rocket"
+  | "plus"
+  | "languages";

package/src/nav.ts

@@ -1,7 +1,10 @@
 import type { AccessRule } from "./handlers";
+import type { NavIconKey } from "./nav-icon";
 import type { TargetRef } from "./target-ref";
 import type { TreeAction } from "./tree-node";
 
+export type { NavIconKey } from "./nav-icon";
+
 // Nav entry declaration. Every feature that wants to appear in the app's
 // navigation tree registers one or more entries via r.nav(). The engine
 // keeps the list flat — ui-core's resolveNavigation assembles the parent/
@@ -22,10 +25,10 @@ export type NavDefinition = {
   // i18n translation key. Resolved at render time by the renderer's
   // useTranslation hook; engine keeps it opaque.
   readonly label: string;
-  // Icon key — whatever the icon registry of the active renderer understands.
-  // Engine doesn't validate; unknown icons surface as a missing icon on screen,
-  // not a boot failure.
-  readonly icon?: string;
+  // Icon key from the closed NavIconKey vocabulary (see nav-icon.ts). Every
+  // renderer's icon map is checked against the same union, so a typo'd key
+  // is a compile error here rather than a missing icon at runtime.
+  readonly icon?: NavIconKey;
   // Qualified name of a parent nav entry ("<feature>:nav:<id>"). Omit for
   // top-level entries. Boot-validator rejects cycles + dangling refs.
   readonly parent?: string;
@@ -113,7 +116,7 @@ export type ContentCollectionDefinition = {
   readonly variableSchema?: Readonly<Record<string, string>>;
   readonly nav: {
     readonly label: string;
-    readonly icon?: string;
+    readonly icon?: NavIconKey;
     readonly parent?: string;
     readonly order?: number;
     // Visibility of the nav node. Leave unset — it then follows the

package/src/screen.ts

@@ -1,5 +1,6 @@
 import type { FieldDefinition } from "./fields";
 import type { AccessRule } from "./handlers";
+import type { NavIconKey } from "./nav-icon";
 
 // Screen definitions describe how a feature surfaces data to the user.
 // Pure data — the engine stores these verbatim and ui-core / the renderer
@@ -704,6 +705,16 @@ export type CustomScreenDefinition = {
   /** Parent list screen for breadcrumb when this detail is not in nav. */
   readonly listScreenId?: string;
   readonly access?: AccessRule;
+  /** This screen is registered without a self-owned `r.nav()` entry by
+   *  design — an app opts in by navving it explicitly (e.g. a settings-area
+   *  self-service screen). `createKumikoApp`'s boot diagnostic
+   *  (kumiko-framework#2025) skips dormant screens instead of flagging
+   *  every consumer that doesn't mount the client plugin as a false
+   *  positive (kumiko-framework#2034). Only set this on screens the
+   *  feature itself never navs — a screen the feature DOES nav still needs
+   *  its client plugin mounted by every consumer, and should keep
+   *  triggering the diagnostic if it's missing. */
+  readonly dormant?: boolean;
 };
 
 // --- configEdit ---
@@ -790,7 +801,7 @@ export type ScreenSlots = {
 // declare a standalone `r.nav()` entry instead.
 export type ScreenNavSugar = {
   readonly label: string;
-  readonly icon?: string;
+  readonly icon?: NavIconKey;
   readonly parent?: string;
   readonly order?: number;
 };

package/src/tenant-db-types.ts

@@ -56,3 +56,16 @@ export type TenantDb = {
   ): Promise<readonly T[]>;
   deleteMany(table: WritableTable, where: WhereObject): Promise<void>;
 };
+
+// Symbol.for (global registry) so the brand identity matches even if kumiko-types
+// resolves to two independent copies (workspace symlink vs. published npm) — a plain
+// `Symbol()` per copy would make each resolution's `UncheckedSystemDb` structurally
+// incompatible with the other, per the kumiko.secret precedent in secrets-types.ts.
+export const SYSTEM_SCOPE_CHECK_BRAND: unique symbol = Symbol.for("kumiko.system-scope-check");
+
+export type UncheckedSystemDb = {
+  readonly [SYSTEM_SCOPE_CHECK_BRAND]: true;
+  assertTenantMatch(tenantId: TenantId): TenantDb;
+  assertRowsTenant<T>(rows: readonly T[], tenantField: keyof T): readonly T[];
+  acknowledgeCrossTenant(reason: string): TenantDb;
+};