@cosmicdrift/kumiko-framework 0.1.0

package/src/engine/resolve-config-or-param.ts

@@ -0,0 +1,153 @@
+import type { Registry } from "./types";
+import type {
+  ConfigAccessor,
+  ConfigBounds,
+  ConfigKeyHandle,
+  ConfigKeyType,
+  ConfigValue,
+} from "./types/config";
+
+// Per-Request Config-Resolver für Routes.
+//
+// Use-case (aus configuration-layers.md, Ebene 7): der Caller will pro
+// Request einen Wert setzen, den Tenant-Admin aber den Max-Bound festlegen.
+// Beispiel: `GET /files/:id/download-url?expiresSeconds=3600` — Client
+// wählt 3600s, aber wenn Tenant-Admin Max=1800 gesetzt hat, clampt der
+// Helper auf 1800.
+//
+// Clamp-Regel: hard-clamp für number mit bounds. Silent — im Gegensatz zu
+// tenant-admin-SET (dort ist reject richtig). Caller hat oft keine Kontrolle
+// über den genauen Wert (voreingestellt im Client-SDK), und ein 422 pro
+// Download-Klick wäre UX-Gift.
+//
+// Fallback-Cascade:
+//   1. paramValue valide → clamp + return
+//   2. paramValue fehlt / nicht parseable → ctx.config(handle)
+//
+// Bei select: nur valide Options werden akzeptiert, sonst Fallback.
+// Bei boolean: "true"/"1" → true, sonst false.
+//
+// ### text-Keys sind gesperrt
+//
+// Per-Request-Overrides für `type="text"` werden HART ABGELEHNT. Grund:
+// Query-Param-Strings können XSS/SQL/Command-Fragmente enthalten, und
+// dieser Helper ist ein *Parser*, kein *Sanitizer*. Ein silent-pass-through
+// wäre ein Footgun — App-Dev würde denken "param ist aktiv" und der
+// unsanitized Wert landet in HTML/SQL/Shell-Kontext.
+//
+// Die Sperre gilt nur beim tatsächlichen Override-Versuch (paramValue
+// gesetzt). Wenn paramValue undefined/null/"" ist, gibt der Helper den
+// Config-Wert zurück — dann liefert die Funktion für text-Keys einfach
+// denselben Wert wie `ctx.config(handle)`.
+//
+// Wer für text pro Request tatsächlich einen Wert akzeptieren will, baut
+// das explizit in der Route mit eigener Escape-Strategie für den Consumer
+// (HTML-Encoder, SQL-Parameter-Binding, Shell-Quoter).
+
+type ResolveCtx = {
+  readonly config: ConfigAccessor;
+  readonly registry: Registry;
+};
+
+// Fires for every number-case clamp with the before/after values. Consumers
+// typically wire this into a structured logger or a metric counter:
+//   resolveConfigOrParam(ctx, handle, raw, {
+//     onClamp: ({ key, original, clamped, max }) =>
+//       ctx.logger?.warn("config.clamp", { key, original, clamped, max }),
+//   });
+// Without this hook a clamp is invisible — the caller just sees 1000 instead
+// of the 9999 they sent, and debugging becomes guesswork.
+export type ClampInfo = {
+  readonly key: string;
+  readonly original: number;
+  readonly clamped: number;
+  readonly min?: number;
+  readonly max?: number;
+};
+
+export type ResolveOptions = {
+  readonly onClamp?: (info: ClampInfo) => void;
+};
+
+export async function resolveConfigOrParam<T extends ConfigKeyType>(
+  ctx: ResolveCtx,
+  handle: ConfigKeyHandle<T>,
+  paramValue: unknown,
+  options?: ResolveOptions,
+): Promise<ConfigValue<T> | undefined> {
+  if (paramValue === undefined || paramValue === null || paramValue === "") {
+    return ctx.config(handle);
+  }
+
+  const keyDef = ctx.registry.getConfigKey(handle.name);
+  // skip: key isn't in the registry — unlikely because the caller holds a
+  // typed handle, but defence-in-depth for hand-built handles.
+  if (!keyDef) return ctx.config(handle);
+
+  // Explicit opt-in required. A config key without `allowPerRequest: true`
+  // on its declaration cannot be overridden via a query-param, even if the
+  // route-handler forwards one. This is a deny-by-default policy: without
+  // it, a future feature-dev could accidentally route a sensitive key
+  // (rate-limits, quotas) through a public query-param without noticing.
+  if (!keyDef.allowPerRequest) {
+    throw new Error(
+      `resolveConfigOrParam: per-request override not enabled for config key "${handle.name}". Set allowPerRequest: true on the declaration to opt in — or drop the paramValue if the route-handler forwards it by mistake.`,
+    );
+  }
+
+  switch (keyDef.type) {
+    case "number": {
+      const parsed = typeof paramValue === "number" ? paramValue : Number(paramValue);
+      if (Number.isNaN(parsed) || !Number.isFinite(parsed)) {
+        return ctx.config(handle);
+      }
+      const clamped = clampToBounds(parsed, keyDef.bounds);
+      // Fire onClamp only when the value actually moved. No bounds + within
+      // bounds = silent; crossing a bound = audit event.
+      if (clamped !== parsed && options?.onClamp) {
+        const info: ClampInfo = {
+          key: handle.name,
+          original: parsed,
+          clamped,
+          ...(keyDef.bounds?.min !== undefined && { min: keyDef.bounds.min }),
+          ...(keyDef.bounds?.max !== undefined && { max: keyDef.bounds.max }),
+        };
+        options.onClamp(info);
+      }
+      return clamped as ConfigValue<T>; // @cast-boundary engine-bridge
+    }
+
+    case "boolean": {
+      if (typeof paramValue === "boolean") return paramValue as ConfigValue<T>; // @cast-boundary engine-bridge
+      const str = String(paramValue).toLowerCase();
+      return (str === "true" || str === "1") as ConfigValue<T>; // @cast-boundary engine-bridge
+    }
+
+    case "text": {
+      // Hard-reject any attempt to override a text key via query-param.
+      // See the module-level comment for why this is strict. App-devs
+      // that see this error should either (a) remove the paramValue from
+      // their route — the config value still flows through ctx.config —
+      // or (b) build their own sanitised parser outside this helper.
+      throw new Error(
+        `resolveConfigOrParam: per-request override is not allowed for type="text" config key "${handle.name}" — query-params would bypass sanitisation. Remove the paramValue or build a feature-specific sanitiser.`,
+      );
+    }
+
+    case "select": {
+      const str = String(paramValue);
+      if (keyDef.options?.includes(str)) return str as ConfigValue<T>; // @cast-boundary engine-bridge
+      // Invalid option → fall back to the configured value rather than 400.
+      // The caller is signalling intent; we honour the constraint instead.
+      return ctx.config(handle);
+    }
+  }
+}
+
+function clampToBounds(value: number, bounds: ConfigBounds | undefined): number {
+  if (!bounds) return value;
+  let v = value;
+  if (bounds.min !== undefined && v < bounds.min) v = bounds.min;
+  if (bounds.max !== undefined && v > bounds.max) v = bounds.max;
+  return v;
+}

package/src/engine/run-in.ts

@@ -0,0 +1,29 @@
+// runIn lane-routing helpers. Tiny module on purpose: both buildServer
+// (MSP-consumer filter) and the boot-validator (Welle 2.6.c coverage
+// check) need the same resolution rule, and duplicating it in two places
+// invites drift — when the default changes, one site gets updated and
+// the other silently doesn't.
+//
+// Resolution rule:
+//   - `runIn: undefined` resolves to "worker" — that's the prod default
+//     for async work (API instances stay request-focused, heavy async
+//     work lives on the worker fleet).
+//   - `runIn: "both"` means "eligible on any lane" — SKIP LOCKED on the
+//     consumer cursor handles the race between processes that want the
+//     same event. Used for cross-lane load-balancing and for MSPs that
+//     have no reason to pin to a specific process shape.
+//   - `runIn: "api"` / `runIn: "worker"` pin to one lane.
+//
+// processLane describes the CURRENT process's role:
+//   - "api" / "worker" — single-role deploy, filter strictly.
+//   - "both"           — all-in-one, no filtering (one process does it all).
+
+import type { RunIn } from "./types";
+
+// Does a consumer with `runIn` want to run on a process of the given lane?
+export function runsInLane(runIn: RunIn | undefined, processLane: RunIn): boolean {
+  if (processLane === "both") return true;
+  const resolved = runIn ?? "worker";
+  if (resolved === "both") return true;
+  return resolved === processLane;
+}

package/src/engine/schema-builder.ts

@@ -0,0 +1,175 @@
+import { z } from "zod";
+import { assertUnreachable } from "../utils";
+import type { EmbeddedSubFieldDef, EntityDefinition, FieldDefinition } from "./types";
+import { DEFAULT_CURRENCIES } from "./types";
+
+function embeddedSubFieldToZod(subField: EmbeddedSubFieldDef): z.ZodTypeAny {
+  switch (subField.type) {
+    case "text":
+      return subField.required ? z.string().min(1) : z.string();
+    case "number":
+      return z.number();
+    case "boolean":
+      return z.boolean();
+    case "date":
+      return z.string().date();
+    default:
+      assertUnreachable(subField.type, "embedded sub-field type");
+  }
+}
+
+function fieldToZod(field: FieldDefinition, currencies: readonly string[]): z.ZodTypeAny {
+  switch (field.type) {
+    case "text": {
+      let schema = z.string();
+      if (field.maxLength) schema = schema.max(field.maxLength);
+      if (field.format === "email") schema = schema.email();
+      if (field.format === "url") schema = schema.url();
+      if (field.required) schema = schema.min(1);
+      return field.default !== undefined ? schema.default(field.default) : schema;
+    }
+    case "longText": {
+      // longText hat keine `format`-Variante (per type-design). Nur
+      // optional maxLength + required, sonst ein offener z.string().
+      let schema = z.string();
+      if (field.maxLength) schema = schema.max(field.maxLength);
+      if (field.required) schema = schema.min(1);
+      return field.default !== undefined ? schema.default(field.default) : schema;
+    }
+    case "boolean": {
+      const schema = z.boolean();
+      return field.default !== undefined ? schema.default(field.default) : schema;
+    }
+    case "select": {
+      const [first, ...rest] = field.options;
+      if (!first) return z.string();
+      const schema = z.enum([first, ...rest]);
+      return field.default !== undefined ? schema.default(field.default) : schema;
+    }
+    case "multiSelect": {
+      const [first, ...rest] = field.options;
+      if (!first) return z.array(z.string());
+      // `required: true` heißt non-empty — Analogie zu `text`-Field.
+      // Leeres Array wird rejected; das globale `.optional()`-Wrapping
+      // in buildInsertSchema kümmert sich um „darf fehlen".
+      let schema = z.array(z.enum([first, ...rest]));
+      if (field.required) schema = schema.min(1);
+      return field.default !== undefined ? schema.default([...field.default]) : schema;
+    }
+    case "number": {
+      const schema = z.number();
+      return field.default !== undefined ? schema.default(field.default) : schema;
+    }
+    case "money": {
+      const [first, ...rest] = currencies;
+      if (!first) throw new Error("No currencies configured");
+      return z.object({
+        amount: z.number(),
+        currency: z.enum([first, ...rest]),
+      });
+    }
+    case "embedded": {
+      const shape: Record<string, z.ZodTypeAny> = {};
+      for (const [subName, subField] of Object.entries(field.schema)) {
+        const zodSub = embeddedSubFieldToZod(subField);
+        shape[subName] = subField.required ? zodSub : zodSub.optional();
+      }
+      return z.object(shape);
+    }
+    case "date": {
+      return z.string().date();
+    }
+    case "timestamp": {
+      // Wenn locatedBy gesetzt: Wall-Clock OHNE Offset (ISO-Datetime ohne `Z`).
+      // Sonst: ISO-UTC-Datetime (mit `Z`). Beide werden über z.iso.datetime
+      // gegen das ISO-8601-Schema validiert; die Präzision (mit/ohne Offset)
+      // hängt von locatedBy ab.
+      return field.locatedBy !== undefined ? z.iso.datetime({ local: true }) : z.iso.datetime();
+    }
+    case "tz": {
+      // IANA-Zonenname. Validierung gegen Intl.supportedValuesOf("timeZone")
+      // ist genau aber teuer (~600 Strings) — wir akzeptieren den freien
+      // String und prüfen via try/catch im Boot-Validator (kommt in
+      // späterer Iteration).
+      return z.string().min(1);
+    }
+    case "locatedTimestamp": {
+      // Combined Wall-Clock+TZ Object. Beim Write akzeptieren wir entweder
+      // { at, tz } (typisch UI-Form, utc wird berechnet) oder { utc, tz }
+      // (typisch Server-zu-Server, at wird berechnet). Beim Read liefert
+      // der Read-Wrapper alle drei Felder (siehe Phase D in MIGRATION.md).
+      //
+      // Hier nur die Schema-Garantie: mindestens tz + (at ODER utc).
+      const at = z.iso.datetime({ local: true });
+      const tz = z.string().min(1);
+      const utc = z.iso.datetime();
+      return z.union([
+        z.object({ at, tz, utc: utc.optional() }),
+        z.object({ utc, tz, at: at.optional() }),
+      ]);
+    }
+    case "file":
+    case "image": {
+      // Single file: stores a fileRef UUID — must match fileRefsTable.id
+      // (uuid column). Pre-fix this was z.number() from an era when the
+      // column was (wrongly) integer; the table-builder fix to uuid needs
+      // a matching validation-layer fix here or the CRUD pipeline rejects
+      // every valid UUID with "expected number".
+      return z.uuid();
+    }
+    case "files":
+    case "images": {
+      // Multi file: array of fileRef UUIDs. Same story as the singular
+      // variant — the element type has to match the UUID column on
+      // fileRefsTable.id.
+      return z.array(z.uuid());
+    }
+    case "reference":
+      // Tier 2.7e-3: Validiert UUID-shape. Existenz-Check der Reference
+      // (Row im referenced Table existiert + Tenant-Scope) ist Server-
+      // side-Verantwortung im Handler / Foreign-Key-Constraint, nicht
+      // im Schema-Validator (würde sonst Round-trip zur DB beim Parse).
+      // Multi-Mode (Tier 2.7e-Multi): Array von UUIDs.
+      return field.multiple === true ? z.array(z.uuid()) : z.uuid();
+    default:
+      assertUnreachable(field, "field type");
+  }
+}
+
+export function buildInsertSchema(
+  entity: EntityDefinition,
+  currencies: readonly string[] = [...DEFAULT_CURRENCIES],
+): z.ZodObject<Record<string, z.ZodTypeAny>> {
+  const shape: Record<string, z.ZodTypeAny> = {};
+
+  for (const [name, field] of Object.entries(entity.fields)) {
+    const zodField = fieldToZod(field, currencies);
+    const hasDefault = "default" in field && field.default !== undefined;
+    const isRequired = "required" in field && field.required === true;
+    shape[name] = isRequired || hasDefault ? zodField : zodField.optional();
+  }
+
+  return z.object(shape);
+}
+
+export function buildUpdateSchema(
+  entity: EntityDefinition,
+  currencies: readonly string[] = [...DEFAULT_CURRENCIES],
+): z.ZodObject<Record<string, z.ZodTypeAny>> {
+  const shape: Record<string, z.ZodTypeAny> = {};
+
+  for (const [name, field] of Object.entries(entity.fields)) {
+    // Update schemas never apply defaults — a user that sends only
+    // `{ title }` means "only change title"; zod defaults would silently
+    // inject default values for every omitted field and clobber existing
+    // data via the event-store-executor's `changes` payload.
+    // Cast widens the discriminated union so destructure works for variants
+    // without a `default` field; remainder is structurally a FieldDefinition.
+    const { default: _default, ...stripped } = field as FieldDefinition & {
+      default?: unknown;
+    };
+    shape[name] = fieldToZod(stripped as FieldDefinition, currencies).optional();
+  }
+
+  return z.object(shape);
+}

package/src/engine/screen-filter-ops.ts

@@ -0,0 +1,51 @@
+// Screen-Filter (Tier 2.7c) — Op-vs-Field-Type-Compatibility.
+//
+// Wer darf was filtern?
+//   - text/select/multiSelect: nur equality-Ops (eq, ne, in). lt/gt
+//     auf Strings ist semantisch fast immer Tippfehler (lexicographic
+//     compare nutzt der Author selten bewusst); Author kann den
+//     Filter dann einfach nicht setzen.
+//   - boolean: eq, ne (in/lt/gt sinnlos für 2-Werte-Type).
+//   - number/money/date/timestamp/locatedTimestamp: alle 5 Ops —
+//     die Felder sind natürlich vergleichbar.
+//
+// Boot-Validator nutzt diese Map um Author-Fehler früh zu fangen
+// ("filter mit op:lt auf einem text-Feld" → Boot-Fail). Erweitert sich
+// transparent: neuer Field-Type → hier eintragen + sortable/filterable-
+// Flag im Type-Def, sonst lehnt der Validator das Field generell ab.
+
+import type { FieldDefinition, ScreenFilterOp } from "./types";
+
+const EQUALITY_ONLY = ["eq", "ne", "in"] as const satisfies readonly ScreenFilterOp[];
+const COMPARABLE = ["eq", "ne", "lt", "gt", "in"] as const satisfies readonly ScreenFilterOp[];
+const BOOL_OPS = ["eq", "ne"] as const satisfies readonly ScreenFilterOp[];
+
+export function getAllowedFilterOps(field: FieldDefinition): readonly ScreenFilterOp[] {
+  switch (field.type) {
+    case "text":
+    case "select":
+    case "multiSelect":
+      return EQUALITY_ONLY;
+    case "boolean":
+      return BOOL_OPS;
+    case "number":
+    case "money":
+    case "date":
+    case "timestamp":
+    case "locatedTimestamp":
+      return COMPARABLE;
+    // tz/embedded/file/image/files/images: nicht filterbar — Author
+    // kann das Feld nicht als filterable: true markieren (Boot-
+    // Validator weist `filterable: true` auf den Types ohnehin schon
+    // ab, weil das Flag dort gar nicht im Type-Def steht).
+    default:
+      return [];
+  }
+}
+
+// Author hat das Feld als filterable markiert? Tz/Embedded/File-Types
+// haben das Flag gar nicht im Type-Def, also fangen wir das per
+// `"filterable" in field`-Narrow ab.
+export function isFieldFilterable(field: FieldDefinition): boolean {
+  return "filterable" in field && field.filterable === true;
+}

package/src/engine/state-machine.ts

@@ -0,0 +1,70 @@
+import { buildInvalidTransitionDetails, FrameworkReasons, UnprocessableError } from "../errors";
+
+/**
+ * Type-safe transition graph. Wraps the underlying Map so callers don't
+ * accidentally fall into the `transitions[from]?.includes(to)` footgun
+ * (Object-Index-Access auf einer Map returnt undefined und der ganze
+ * Check kollabiert silently). Stattdessen forciert die API explizite
+ * Methoden — kein Map-shape mehr extern sichtbar.
+ *
+ * - `canTransition(from, to)` → boolean
+ * - `allowedFrom(from)` → readonly string[] (leer wenn `from` unbekannt
+ *   oder terminaler Zustand)
+ * - `assertTransition(from, to)` → wirft UnprocessableError(invalid_transition)
+ */
+export type TransitionGraph<TStates extends string = string> = {
+  readonly canTransition: (from: TStates, to: TStates) => boolean;
+  readonly allowedFrom: (from: TStates) => readonly TStates[];
+  readonly assertTransition: (from: TStates, to: TStates) => void;
+};
+
+/**
+ * Defines allowed state transitions. Returns a typed graph (see
+ * TransitionGraph) — nicht eine Map. Damit ist `transitions[x]`-Zugriff
+ * type-error statt silent undefined.
+ */
+export function defineTransitions<const TMap extends Record<string, readonly string[]>>(
+  map: TMap,
+): TransitionGraph<keyof TMap & string> {
+  type TStates = keyof TMap & string;
+  const internal = new Map<string, ReadonlySet<string>>();
+  for (const [from, targets] of Object.entries(map)) {
+    internal.set(from, new Set(targets));
+  }
+
+  return {
+    canTransition: (from, to) => internal.get(from)?.has(to) === true,
+    allowedFrom: (from) => {
+      const set = internal.get(from);
+      return set ? ([...set] as TStates[]) : [];
+    },
+    assertTransition: (from, to) => {
+      const set = internal.get(from);
+      // skip: erlaubter Übergang — kein Throw, fall through.
+      if (set?.has(to) === true) return;
+      const allowed = set ? [...set] : [];
+      throw new UnprocessableError(FrameworkReasons.invalidTransition, {
+        i18nKey: "errors.invalidTransition",
+        details: buildInvalidTransitionDetails(from, to, allowed),
+      });
+    },
+  };
+}
+
+/**
+ * Asserts a state transition is allowed. Throws UnprocessableError with
+ * reason="invalid_transition" if not — the 422 status lets the client
+ * distinguish a logical rejection from a validation or auth failure.
+ *
+ * Convenience-Wrapper um `transitions.assertTransition(from, to)` —
+ * existiert weil bestehende Aufrufer `guardTransition(graph, ...)`-Form
+ * nutzen. Beides ist erlaubt; die Method-Form auf dem Graph ist die
+ * idiomatische API für neuen Code.
+ */
+export function guardTransition<TStates extends string>(
+  transitions: TransitionGraph<TStates>,
+  from: TStates,
+  to: TStates,
+): void {
+  transitions.assertTransition(from, to);
+}

package/src/engine/system-user.ts

@@ -0,0 +1,32 @@
+import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import type { SessionUser } from "./types";
+
+// Stringified so it round-trips through SessionUser.id (string UUID-shape).
+// Not a real UUID — SYSTEM acts as an alias for "no human caller" and event-
+// store createdBy is text, so the literal suffices.
+export const SYSTEM_USER_ID = "00000000-0000-0000-0000-000000000000";
+export const SYSTEM_ROLE = "system" as const;
+
+export function createSystemUser(tenantId: TenantId): SessionUser {
+  return {
+    id: SYSTEM_USER_ID,
+    tenantId,
+    roles: [SYSTEM_ROLE],
+  };
+}
+
+// Anonymous = unauthenticated caller on a public endpoint. id is a stable
+// literal (not a UUID) so audit-trails and event-store rows stay readable —
+// `actor: "anonymous"` is more useful than a random UUID-bucket. Reserved
+// like SYSTEM_ROLE: the boot-validator rejects apps that declare these as
+// custom roles.
+export const ANONYMOUS_USER_ID = "anonymous";
+export const ANONYMOUS_ROLE = "anonymous" as const;
+
+export function createAnonymousUser(tenantId: TenantId): SessionUser {
+  return {
+    id: ANONYMOUS_USER_ID,
+    tenantId,
+    roles: [ANONYMOUS_ROLE],
+  };
+}