@cosmicdrift/kumiko-types 0.159.0

package/LICENSE

@@ -0,0 +1,57 @@
+Business Source License 1.1
+
+Parameters
+
+Licensor:             Marc Frost
+
+Licensed Work:        @cosmicdrift/kumiko-framework
+                      The Licensed Work is © 2026 Marc Frost.
+
+Additional Use Grant: 
+You may use the Licensed Work in production for any purpose, including 
+commercially, EXCEPT for the Restricted Use. 
+
+"Restricted Use" is defined as using the Licensed Work to provide a platform 
+or service to third parties that allows them to host, deploy, or run their 
+own applications built with the Licensed Work. This includes, but is not 
+limited to: managed hosting services, software-as-a-service (SaaS) platforms, 
+platform-as-a-service (PaaS), developer platforms, or any multi-tenant 
+managed offering of the Licensed Work.
+
+This restriction does not apply to the Licensor, any entity controlled by, 
+controlling, or under common control with the Licensor ("Affiliates"), or 
+contractors acting on their behalf. The Licensor remains free to use the 
+Licensed Work for any purpose, including for the operation of kumiko.rocks.
+
+Change Date:          2030-05-05
+Change License:       Apache License, Version 2.0
+
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative works, 
+redistribute, and make non-production use of the Licensed Work. The Licensor may 
+make an Additional Use Grant, above, permitting limited production use.
+
+Effective on the Change Date, or the fourth anniversary of the first publicly 
+available distribution of the Licensed Work under this License, whichever comes 
+first, this License will convert to the Change License.
+
+This Business Source License governs use of the Licensed Work in all cases, except 
+as to any use that is explicitly granted in the Additional Use Grant above or 
+under the Change License after the Change Date.
+
+If your use of the Licensed Work does not comply with the requirements of this 
+License, you must cease use of the Licensed Work immediately.
+
+All copies of the Licensed Work, and all derivative works thereof, must include 
+this License.
+
+This License does not grant you any right, title, or interest in any trademark, 
+logo, or branding of the Licensor, except as required to comply with this License.
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON AN 
+“AS IS” BASIS. LICENSOR DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 
+WITHOUT LIMITATION WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, 
+TITLE, AND NON-INFRINGEMENT. IN NO EVENT WILL LICENSOR BE LIABLE FOR ANY DAMAGES 
+ARISING OUT OF OR RELATED TO THIS LICENSE OR THE USE OF THE LICENSED WORK.

package/package.json

@@ -0,0 +1,95 @@
+{
+  "name": "@cosmicdrift/kumiko-types",
+  "version": "0.159.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>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/CosmicDriftGameStudio/kumiko-framework.git",
+    "directory": "packages/types"
+  },
+  "bugs": {
+    "url": "https://github.com/CosmicDriftGameStudio/kumiko-framework/issues"
+  },
+  "homepage": "https://kumiko.rocks",
+  "type": "module",
+  "kumiko": {
+    "runtime": "client"
+  },
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    },
+    "./identifiers": {
+      "types": "./src/identifiers.ts",
+      "default": "./src/identifiers.ts"
+    },
+    "./target-ref": {
+      "types": "./src/target-ref.ts",
+      "default": "./src/target-ref.ts"
+    },
+    "./event-type-map": {
+      "types": "./src/event-type-map.ts",
+      "default": "./src/event-type-map.ts"
+    },
+    "./http-route": {
+      "types": "./src/http-route.ts",
+      "default": "./src/http-route.ts"
+    },
+    "./relations": {
+      "types": "./src/relations.ts",
+      "default": "./src/relations.ts"
+    },
+    "./tree-node": {
+      "types": "./src/tree-node.ts",
+      "default": "./src/tree-node.ts"
+    },
+    "./logger": {
+      "types": "./src/logger.ts",
+      "default": "./src/logger.ts"
+    },
+    "./search-adapter": {
+      "types": "./src/search-adapter.ts",
+      "default": "./src/search-adapter.ts"
+    },
+    "./geo-tz": {
+      "types": "./src/geo-tz.ts",
+      "default": "./src/geo-tz.ts"
+    },
+    "./observability": {
+      "types": "./src/observability/index.ts",
+      "default": "./src/observability/index.ts"
+    },
+    "./observability/metric": {
+      "types": "./src/observability/metric.ts",
+      "default": "./src/observability/metric.ts"
+    },
+    "./observability/provider": {
+      "types": "./src/observability/provider.ts",
+      "default": "./src/observability/provider.ts"
+    },
+    "./observability/span": {
+      "types": "./src/observability/span.ts",
+      "default": "./src/observability/span.ts"
+    },
+    "./db-connection": {
+      "types": "./src/db-connection.ts",
+      "default": "./src/db-connection.ts"
+    }
+  },
+  "dependencies": {
+    "hono": "^4.12.18",
+    "postgres": "^3.4.9"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ]
+}

package/src/db-connection.ts

@@ -0,0 +1,11 @@
+import type postgres from "postgres";
+
+// biome-ignore lint/suspicious/noExplicitAny: Bun.SQL global type
+export type DbConnection = ReturnType<typeof postgres> | any;
+// biome-ignore lint/suspicious/noExplicitAny: postgres-js namespace lookup
+export type DbTx = postgres.TransactionSql<any> | any;
+export type DbRunner = DbConnection | DbTx;
+export type DbRow = Record<string, unknown>;
+export type PgClient = ReturnType<typeof postgres>;
+
+export type PgListenClient = ReturnType<typeof postgres>;

package/src/event-type-map.ts

@@ -0,0 +1,37 @@
+// Cross-Feature Compile-Time-Type-Map.
+//
+// Zweck: ctx.appendEvent / ctx.queryProjection / dispatcher.write gegen ein
+// statisch bekanntes Schema-Bild prüfen, statt erst zur Boot- oder Runtime
+// (zod-validate) zu scheitern. Designer/AI-Layer profitiert dadurch sofort:
+// Autocomplete kennt alle Event-Typen aller geladenen Features, payload-
+// Shape-Mismatches werden im Editor angezeigt, nicht erst beim Boot.
+//
+// Befüllung erfolgt per Feature über `declare module "@cosmicdrift/kumiko-framework/engine"`
+// — entweder hand-geschrieben (für stabile Frameworks-Internals) oder vom
+// Codegen-Skript erzeugt (für apps/bundled-features). Empty defaults sind
+// kein Bug: ein Feature ohne Augmentation ist runtime-pluggable und nutzt
+// die Fallback-Overload mit `unknown` payload.
+//
+// Pattern für hand-geschriebene Augmentation am File-Top:
+//
+//   declare module "@cosmicdrift/kumiko-framework/engine" {
+//     interface KumikoEventTypeMap {
+//       "users:user.created": z.infer<typeof userCreatedSchema>;
+//     }
+//   }
+
+// MUST be `interface` (not `type`): only interfaces support TS declaration-
+// merging. Apps/features extend these via `declare module "@cosmicdrift/kumiko-framework/engine"`
+// blocks. A `type X = {}` alias would silently break that augmentation channel.
+
+// biome-ignore lint/suspicious/noEmptyInterface: declaration-merging marker — augmented per feature
+export interface KumikoEventTypeMap {}
+
+// biome-ignore lint/suspicious/noEmptyInterface: declaration-merging marker
+export interface KumikoEntityTypeMap {}
+
+// biome-ignore lint/suspicious/noEmptyInterface: declaration-merging marker
+export interface KumikoHandlerPayloadMap {}
+
+// biome-ignore lint/suspicious/noEmptyInterface: declaration-merging marker
+export interface KumikoHandlerResultMap {}

package/src/geo-tz.ts

@@ -0,0 +1,32 @@
+// GeoTzProvider — optional adapter for geo-position → IANA zone. The framework
+// defines ONLY the interface + injection seam (ctx.tz.fromCoordinates /
+// fromAddress); a concrete implementation ships in a separate package
+// (e.g. a geo-tz-based offline package). v1 default: no provider — the
+// fromCoordinates/fromAddress methods throw clearly instead of silently guessing.
+//
+// `fromCoordinates` is the PRIMARY method: offline geo-tz libs resolve
+// lat/lng → zone (exact, offline, free) — they don't know postal addresses.
+// `fromAddress` is optional, for providers backed by a geocoding API (address →
+// zone, online). This split keeps the interface compatible with both
+// provider classes instead of forcing an address shape the offline case
+// can't serve at all.
+
+export type GeoCoordinates = {
+  readonly latitude: number;
+  readonly longitude: number;
+};
+
+export type GeoAddress = {
+  readonly street?: string;
+  readonly city?: string;
+  readonly region?: string;
+  readonly postalCode?: string;
+  readonly country?: string;
+};
+
+export type GeoTzProvider = {
+  /** Geo-coordinates → IANA zone (offline lat/lng → tz). */
+  readonly fromCoordinates: (coords: GeoCoordinates) => string | Promise<string>;
+  /** Optional: postal address → IANA zone (geocoding API provider). */
+  readonly fromAddress?: (address: GeoAddress) => string | Promise<string>;
+};

package/src/http-route.ts

@@ -0,0 +1,72 @@
+// HTTP-Route-Definition — feature-deklarierte HTTP-Endpoints außerhalb
+// der /api/write|query|batch-Pipeline. Use-Case: RSS/Atom-Feeds, OpenAPI-
+// Specs, OG-Image-Generators, Webhook-Receiver — alles wo der Feature-
+// Author das Wire-Format selbst kontrolliert.
+//
+// Pattern symmetrisch zu r.queryHandler / r.writeHandler: Definition als
+// Teil des Features (nicht des App-Bootstrapping). Phase-3 Multi-Tenant
+// wird trivial weil tenant-context via host-resolution greift.
+//
+// Escape-hatch bleibt: runProdApp.extraRoutes für hand-rolled Routes die
+// nichts mit einem Feature zu tun haben (z.B. plattform-spezifische
+// Static-Serving-Logic).
+
+import type { Context } from "hono";
+
+/** Subset von HTTP-Methoden den wir aktiv unterstützen. Hono spricht
+ *  alle, aber das hier sind die einzigen die ein Feature-Author
+ *  realistisch deklariert. */
+export type HttpRouteMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS";
+
+/** Dependencies die der Handler vom Framework bekommt. App-Author kann
+ *  die App selbst aufrufen (`deps.app.fetch(...)` für intern-call) oder
+ *  direkt per dispatcher Daten ziehen. Db/Redis sind die rohen Connections
+ *  — wer Tenant-Scope braucht muss durch dispatcher.query gehen.
+ *
+ *  Hono-typing: `Context<any, any>` weil das Hono-Type-Param-Setup nur
+ *  intern relevant ist. Concrete Hono-app wird im Boot-Path zugewiesen. */
+export type HttpRouteHandlerDeps = {
+  /** Die Hono-app — Handler kann via app.fetch(...) interne Routes
+   *  ansprechen (z.B. /api/query mit der vollen Auth-/Anonymous-Chain). */
+  // biome-ignore lint/suspicious/noExplicitAny: Hono's generic-Param ist im Framework-Boundary unsichtbar
+  readonly app: import("hono").Hono<any, any>;
+  /** Run a query handler in-process, forcing a SPECIFIC tenant — WITHOUT
+   *  going through the public /api/query HTTP layer (no header parsing, no
+   *  anonymousAccess tenant resolution). The synthesized caller carries
+   *  anonymous-level access ONLY (same role a real anonymous request would
+   *  have, no more) — the primitive forces the tenant, not the privilege
+   *  level, so it stays safe to call from any `anonymous: true` route
+   *  without risking a field-level disclosure a real anonymous caller
+   *  couldn't already get. Use this whenever the route needs a tenant
+   *  other than the one the request resolves to (e.g. always
+   *  SYSTEM_TENANT_ID regardless of the visited host) — spoofing that via
+   *  an internal X-Tenant header on `app.fetch(...)` is indistinguishable
+   *  from an external client and gets rejected by resolverTrust:
+   *  "authoritative" anonymousAccess configs (see auth-middleware.ts). */
+  readonly systemQuery: (
+    type: string,
+    payload: unknown,
+    tenantId: import("./identifiers").TenantId,
+  ) => Promise<unknown>;
+};
+
+export type HttpRouteHandler = (
+  // biome-ignore lint/suspicious/noExplicitAny: Hono Context-Generics sind im Framework-Boundary unsichtbar
+  c: Context<any, any>,
+  deps: HttpRouteHandlerDeps,
+) => Response | Promise<Response>;
+
+export type HttpRouteDefinition = {
+  /** HTTP-Methode — bei Hono-Mount via app.{get,post,...}(path). */
+  readonly method: HttpRouteMethod;
+  /** URL-Pfad (Hono-Pattern, z.B. "/feed.xml" oder "/og/:tenantId.png"). */
+  readonly path: string;
+  /** Wenn true, bypasses die /api/*-Auth-Middleware. Default false —
+   *  Routes liegen außerhalb /api/* und sehen die Auth-Middleware
+   *  ohnehin nicht; das Flag ist semantisch (= "diese Route ist
+   *  bewusst öffentlich") für Boot-Validator + Doku. */
+  readonly anonymous?: boolean;
+  /** Hono-Handler. Bekommt Hono-Context + Framework-Deps; returnt
+   *  Response (sync oder async). */
+  readonly handler: HttpRouteHandler;
+};

package/src/identifiers.ts

@@ -0,0 +1,47 @@
+// Domain-identifier type aliases. Used everywhere a tenantId/userId/aggregateId
+// travels through the framework. One declaration per concept so future
+// representation changes (branded types, UUID validation, opaque wrappers)
+// land in a single place.
+
+// Tenant identifier — UUID string today. May become branded/opaque later
+// without touching call sites.
+export type TenantId = string;
+
+// Lowercase UUID (any RFC-4122 variant). Strict enough to keep client-
+// supplied junk (e.g. SQL fragments, path-traversal probes) out of the
+// pipeline; loose enough that v4 / v7 / nil all match. Any caller that
+// already holds a TenantId from a trusted source (JWT payload, server
+// config) skips this — the helper is for **untrusted input** crossing
+// 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}$/;
+
+// 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
+// params). Returning null instead of throwing keeps the caller in charge
+// 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;
+}
+
+// "System-scope" tenant marker: handlers carry this tenantId when the event
+// doesn't belong to any particular tenant (reference data, cross-tenant
+// jobs, global config). The concrete UUID is a valid v4 (not all-zeroes —
+// Postgres' UUID type rejects invalid variants), chosen to be easy to
+// eyeball in logs. Central constant so call sites don't re-type the string
+// and the isSystemTenant() check stays in sync.
+export const SYSTEM_TENANT_ID: TenantId = "00000000-0000-4000-8000-000000000000";
+
+export function isSystemTenant(tenantId: TenantId | null | undefined): boolean {
+  return !tenantId || tenantId === SYSTEM_TENANT_ID;
+}
+
+// Primary-key identifier for any entity row. Two shapes coexist because of
+// the entity-def `idType` switch: classic CRUD entities keep `serial` (number),
+// while tenant + ES aggregates run on `uuid` (string). Call sites that pass
+// the id through to the DB layer stay agnostic; only code that formats ids
+// for URLs, logs, or cache keys needs `String(id)` — JS coerces both safely.
+export type EntityId = number | string;

package/src/index.ts

@@ -0,0 +1 @@
+export {};

package/src/logger.ts

@@ -0,0 +1,7 @@
+export type Logger = {
+  info(msg: string, data?: Record<string, unknown>): void;
+  warn(msg: string, data?: Record<string, unknown>): void;
+  error(msg: string, data?: Record<string, unknown>): void;
+  debug(msg: string, data?: Record<string, unknown>): void;
+  child(context: Record<string, unknown>): Logger;
+};

package/src/observability/index.ts

@@ -0,0 +1,29 @@
+// Barrel for observability types. Split into span/metric/provider files so
+// each module stays focused; consumers still import from "./types".
+
+export type {
+  Counter,
+  Gauge,
+  Histogram,
+  Meter,
+  MetricDefinition,
+  MetricLabels,
+  MetricsHandle,
+  MetricType,
+} from "./metric";
+export type {
+  ObservabilityOptions,
+  ObservabilityProvider,
+  SamplingConfig,
+  SensitiveFilterConfig,
+} from "./provider";
+export type {
+  SerializedTraceContext,
+  Span,
+  SpanAttributes,
+  SpanAttributeValue,
+  SpanKind,
+  SpanStatus,
+  StartSpanOptions,
+  Tracer,
+} from "./span";

package/src/observability/metric.ts

@@ -0,0 +1,56 @@
+// Metric + Meter contract. Feature code interacts through ctx.metrics
+// (MetricsHandle); the framework wires Counter/Histogram/Gauge behind that.
+
+export type MetricLabels = Record<string, string | number | boolean>;
+
+export type MetricType = "counter" | "histogram" | "gauge";
+
+export type MetricDefinition = {
+  // Fully-qualified name (with kumiko_<feature>_ prefix already applied).
+  readonly name: string;
+  readonly type: MetricType;
+  readonly description?: string;
+  // Declared label keys. Inc/observe calls with unknown label keys throw.
+  readonly labels?: readonly string[];
+  // Buckets only for histogram. If omitted, provider-default is used.
+  readonly buckets?: readonly number[];
+  readonly unit?: string;
+  // If true, the framework auto-injects tenant_id from the active ctx.
+  // Default false — adding tenant_id multiplies cardinality by tenant count.
+  readonly tenantLabel?: boolean;
+};
+
+export interface Counter {
+  inc(value?: number, labels?: MetricLabels): void;
+}
+
+export interface Histogram {
+  observe(value: number, labels?: MetricLabels): void;
+}
+
+export interface Gauge {
+  set(value: number, labels?: MetricLabels): void;
+  inc(value?: number, labels?: MetricLabels): void;
+  dec(value?: number, labels?: MetricLabels): void;
+}
+
+export interface Meter {
+  // Called once per metric during boot. Duplicate names throw.
+  registerMetric(def: MetricDefinition): void;
+  // Lookup by fully-qualified name. Unknown names throw — typed access only.
+  counter(name: string): Counter;
+  histogram(name: string): Histogram;
+  gauge(name: string): Gauge;
+  // List of registered definitions — used by ctx.metrics to validate labels.
+  definitions(): ReadonlyMap<string, MetricDefinition>;
+}
+
+// Public handle for feature code — ctx.metrics.
+// Name resolution uses the fully-qualified name (kumiko_<feature>_<short>).
+// The registrar resolves the short name from the calling feature context
+// at boot time; at handler time the map is ready.
+export interface MetricsHandle {
+  inc(name: string, labels?: MetricLabels, value?: number): void;
+  observe(name: string, value: number, labels?: MetricLabels): void;
+  set(name: string, value: number, labels?: MetricLabels): void;
+}

package/src/observability/provider.ts

@@ -0,0 +1,32 @@
+// Observability provider contract — the "plug" that implementations (noop,
+// console, otlp, prometheus) fulfil. Configuration types that consumers
+// (buildServer, setupTestStack) hand in also live here.
+
+import type { Meter } from "./metric";
+import type { Tracer } from "./span";
+
+export type SamplingConfig = {
+  // Base sampling rate 0..1. Default 1 in v1 (sample everything).
+  readonly tracing?: number;
+  readonly alwaysOnError?: boolean;
+  readonly alwaysOnSlow?: { readonly thresholdMs: number };
+};
+
+export type SensitiveFilterConfig = {
+  readonly redactedHeaders: readonly string[];
+  readonly redactedQueryParams: readonly string[];
+  readonly redactedAttributeKeyPatterns: readonly RegExp[];
+};
+
+export type ObservabilityOptions = {
+  readonly sampling?: SamplingConfig;
+  readonly sensitiveFilter?: Partial<SensitiveFilterConfig>;
+};
+
+export interface ObservabilityProvider {
+  readonly name: string;
+  readonly tracer: Tracer;
+  readonly meter: Meter;
+  // Graceful flush. Called from framework lifecycle shutdown.
+  shutdown(): Promise<void>;
+}

package/src/observability/span.ts

@@ -0,0 +1,58 @@
+// Span + Tracer contract. Provider implementations (noop, recording → console/otlp)
+// all speak this — everything else (middleware, dispatcher, db, redis, jobs)
+// is provider-agnostic.
+
+export type SpanAttributeValue = string | number | boolean;
+export type SpanAttributes = Record<string, SpanAttributeValue>;
+
+export type SpanStatus = "unset" | "ok" | "error";
+
+export type SpanKind = "internal" | "server" | "client" | "producer" | "consumer";
+
+// Serialized form of a trace context — what we pass across process boundaries
+// (outbox row, BullMQ job payload). Matches W3C trace-context spec loosely,
+// but staying minimal — a full W3C parser is v2.
+export type SerializedTraceContext = {
+  readonly traceId: string;
+  readonly spanId: string;
+  readonly baggage?: Readonly<Record<string, string>>;
+};
+
+export type StartSpanOptions = {
+  // Either a live Span (normal in-process parent) or a serialized trace
+  // context (cross-process — outbox row, job payload). Both carry traceId
+  // and spanId, so the tracer reads them uniformly. Omitted → fall back to
+  // the AsyncLocalStorage active span.
+  readonly parent?: Span | SerializedTraceContext;
+  readonly attributes?: SpanAttributes;
+  readonly kind?: SpanKind;
+  readonly startTime?: number;
+};
+
+export interface Span {
+  readonly traceId: string;
+  readonly spanId: string;
+  readonly parentSpanId: string | undefined;
+  readonly name: string;
+  setAttribute(key: string, value: SpanAttributeValue): void;
+  setAttributes(attrs: SpanAttributes): void;
+  setStatus(status: SpanStatus, message?: string): void;
+  recordException(error: Error): void;
+  end(endTime?: number): void;
+  // Whether end() has been called. Idempotency guard for auto-wrappers.
+  readonly ended: boolean;
+}
+
+export interface Tracer {
+  startSpan(name: string, options?: StartSpanOptions): Span;
+  // Runs fn inside the span context (AsyncLocalStorage), ends the span
+  // automatically — including on thrown errors, where the error is recorded
+  // and status set to "error" before re-throwing.
+  withSpan<T>(
+    name: string,
+    optionsOrFn: StartSpanOptions | ((span: Span) => Promise<T>),
+    fn?: (span: Span) => Promise<T>,
+  ): Promise<T>;
+  // Current active span from AsyncLocalStorage, or undefined.
+  getActiveSpan(): Span | undefined;
+}

package/src/relations.ts

@@ -0,0 +1,52 @@
+// Keep in sync with OnDeleteStrategies in packages/framework/src/engine/constants.ts.
+type OnDeleteStrategy = "cascade" | "restrict" | "setNull" | "nothing";
+
+// --- Relations ---
+
+export type BelongsToRelation = {
+  readonly type: "belongsTo";
+  readonly target: string;
+  readonly foreignKey: string;
+  readonly searchInclude?: readonly string[];
+  // onDelete is declared on the parent-side (hasMany / manyToMany) because
+  // that's where the "what happens to my children?" decision lives. A
+  // belongsTo node just points at a parent — the parent's onDelete drives
+  // the cleanup.
+};
+
+export type HasManyRelation = {
+  readonly type: "hasMany";
+  readonly target: string;
+  readonly foreignKey: string;
+  readonly onDelete?: OnDeleteStrategy;
+  // When true, a nested payload under this relation's key (e.g.
+  // `{ tasks: [{ ... }] }` on a `project:create` write) is auto-expanded
+  // into child writes: parent first, then one child-write per entry with
+  // the foreign key set to the parent's new id — all in the same TX.
+  // Opt-in (default false) so legacy hasMany relations that were declared
+  // purely for cascade-delete or UI-nav semantics don't silently gain a
+  // client-writable path. Children are never inferred from payload-shape
+  // alone; only relations with this flag unlock nested-write.
+  //
+  // Scope v1: depth=1, create-only, hasMany-only. Update-nested,
+  // delete-nested, and belongsTo/m2m auto-expansion are explicit future
+  // work — when they arrive, they'll take the same flag so the opt-in
+  // stays a single, consistent surface.
+  readonly nestedWrite?: boolean;
+};
+
+export type ManyToManyRelation = {
+  readonly type: "manyToMany";
+  readonly target: string;
+  readonly through: {
+    readonly table: string;
+    readonly sourceKey: string;
+    readonly targetKey: string;
+  };
+  readonly searchInclude?: readonly string[];
+  readonly onDelete?: OnDeleteStrategy;
+};
+
+export type RelationDefinition = BelongsToRelation | HasManyRelation | ManyToManyRelation;
+
+export type EntityRelations = Readonly<Record<string, RelationDefinition>>;

package/src/search-adapter.ts

@@ -0,0 +1,39 @@
+import type { EntityId, TenantId } from "./identifiers";
+
+export type SearchAdapterConfig = {
+  searchableFields: readonly string[];
+  rankingFields?: readonly string[];
+};
+
+export type SearchDocument = {
+  entityType: string;
+  entityId: EntityId;
+  weight: number;
+  fields: Record<string, unknown>;
+};
+
+export type SearchResult = {
+  entityType: string;
+  entityId: EntityId;
+};
+
+export type SearchOptions = {
+  limit?: number;
+  filterType?: string;
+};
+
+export type SearchAdapter = {
+  configure(tenantId: TenantId, config: SearchAdapterConfig): Promise<void>;
+  index(tenantId: TenantId, doc: SearchDocument): Promise<void>;
+  search(tenantId: TenantId, query: string, options?: SearchOptions): Promise<SearchResult[]>;
+  remove(tenantId: TenantId, entityType: string, entityId: EntityId): Promise<void>;
+  // Bulk variants. Default implementations loop over the single-doc methods —
+  // adapters should override when the backend supports a real batch call
+  // (Meilisearch, Elasticsearch, Typesense all do). Cuts a batch-write from
+  // N sequential HTTP + waitTask round-trips to one.
+  indexBatch?(tenantId: TenantId, docs: readonly SearchDocument[]): Promise<void>;
+  removeBatch?(
+    tenantId: TenantId,
+    items: readonly { entityType: string; entityId: EntityId }[],
+  ): Promise<void>;
+};

package/src/target-ref.ts

@@ -0,0 +1,21 @@
+// TargetRef — runtime-Repräsentation eines typed buildTarget-Outputs.
+// Wird vom Visual-Tree-Component (renderer-web) an einen Target-Resolver
+// dispatcht; der Resolver findet die Editor-Maske via featureId.
+//
+// **Compile-time-Safety:** TargetRef wird niemals hand-getippt. Stattdessen
+// erzeugt der typed buildTarget-Builder (engine/build-target.ts) einen
+// TargetRef, dessen action + args gegen die treeActions-Map des Ziel-
+// Features validiert sind.
+//
+// **Runtime:** args sind hier untyped (Record<string, unknown>), weil
+// TargetRef die erased-runtime-Version ist. Der Resolver kennt das
+// Ziel-Feature und kann args entsprechend casten — ähnlich wie Event-
+// Payloads im Event-Store.
+//
+// Siehe docs/plans/architecture/visual-tree.md A5.
+
+export type TargetRef = {
+  readonly featureId: string;
+  readonly action: string;
+  readonly args?: Readonly<Record<string, unknown>>;
+};

package/src/tree-node.ts

@@ -0,0 +1,129 @@
+// TreeNode — single Knoten im Client-navProvider-Tree. Provider liefern
+// entweder statische readonly TreeNode[] oder dynamische TreeChildrenSubscribe.
+//
+// **Mental-Modell** (VS-Code-Explorer):
+//   [icon] [label] [...hover-actions]
+// optional ein target zum Klicken (öffnet Editor-Maske via
+// Target-Resolver) und optional children als nested tree.
+//
+// **State** markiert Visual-Modus für Skeleton-Pattern:
+//   - "filled" (default) — schwarz, Knoten hat Inhalt
+//   - "stub" — hellgrau, existing aber leer (Designer-Stub-File)
+//   - "empty" — Platzhalter für "+ create"-Affordance
+//   - "loading" — Children werden gerade aufgelöst
+//   - "error" — Provider hat Fehler emittiert
+// Provider die kein Skeleton-Pattern brauchen müssen state nicht setzen.
+//
+// **Subscribe-Form** für dynamic Children: Provider erhält emit(),
+// gibt unsubscribe() zurück. Initial-Emit synchron oder async, weitere
+// Emits beliebig oft (z.B. wenn Entity-Row neu erscheint via SSE).
+// Spielt natürlich mit existing SSE-Frame: ein Provider kann intern
+// auf Entity-Update-Events abonnieren und bei Änderung emit() aufrufen.
+
+import type { TargetRef } from "./target-ref";
+
+export type TreeNodeState = "filled" | "stub" | "empty" | "loading" | "error";
+
+export type TreeAction = {
+  // Icon-Key — vom Renderer-Icon-Registry interpretiert. Konvention
+  // matched NavDefinition.icon: unbekannte Icons surface als missing-icon
+  // im UI, nicht als Boot-Failure.
+  readonly icon: string;
+  // i18n-Translation-Key oder roher String. Vom Renderer aufgelöst, Engine
+  // behandelt opak (mirrors NavDefinition.label, WorkspaceDefinition.label).
+  readonly label: string;
+  // Klick-Ziel der Action. Pflicht — Action ohne target ist semantisch
+  // sinnlos (Hover-Icon das nichts tut).
+  readonly target: TargetRef;
+};
+
+export type TreeNode = {
+  // i18n-Translation-Key oder roher String. Vom Renderer beim Rendern
+  // aufgelöst (siehe TreeAction.label).
+  readonly label: string;
+  // Optional. Icon links neben dem Label. Selbe Konvention wie
+  // TreeAction.icon — Renderer-Icon-Registry-Lookup.
+  readonly icon?: string;
+  // Visueller State für Skeleton-Pattern. Default "filled" (kein Eintrag
+  // ⇒ schwarz/normal). Wert-Semantik im Header-Comment dieser Datei.
+  readonly state?: TreeNodeState;
+  // Optional Klick-Ziel. Fehlt → reiner Container-Knoten (nur ausklappbar,
+  // nicht klickbar). Vorhanden → Klick öffnet die Editor-Maske via
+  // Target-Resolver in renderer-web.
+  readonly target?: TargetRef;
+  // Hover-Actions rechts (Add/Refresh/Delete/etc.). Werden in der
+  // Sidebar-Row erst bei Hover sichtbar — VS-Code-Pattern. Engine
+  // ordnet die Actions in der Reihenfolge an, in der sie hier stehen.
+  readonly actions?: readonly TreeAction[];
+  // Statische Children oder dynamic Subscribe-Function. Subscribe wird
+  // erst beim Ausklappen aufgerufen (lazy); die Function-Form erlaubt
+  // SSE-gefütterte Live-Updates wenn neue Entity-Rows reinkommen.
+  readonly children?: readonly TreeNode[] | TreeChildrenSubscribe;
+  // Provider-deklarierte „+ create"-Action für Knoten mit `state: "empty"`.
+  // Tree-Component zeigt automatisch ein „+"-Icon und dispatcht
+  // `createAction.target` bei Klick — Provider weiß was „leer befüllen"
+  // für ihn bedeutet (z.B. „neuer Page-Slug" vs „neue Entity-Row"),
+  // Convention könnte das nicht raten. Konsistent zu `state` (auch
+  // Provider-explizit). Siehe visual-tree.md V.1.1-Decision D3.
+  readonly createAction?: TreeAction;
+};
+
+// Subscribe<T> — Provider implementiert: emit(initial); ...emit(updated);
+// und gibt unsubscribe-Function zurück. Caller (Tree-Component) ruft
+// unsubscribe auf wenn Knoten unmounted/eingeklappt wird.
+//
+// **V.1.4 emitError**: optional callback für async-error-Pfade (fetch-
+// fail, SSE-disconnect). Provider die explizit Errors signalisieren
+// wollen rufen `emitError(e)` statt empty-emit; VisualTree zeigt
+// Error-Banner mit Retry-Button. Sync-Throws im Provider-Body werden
+// vom useEffect-try/catch abgefangen — emitError ist nur für async.
+export type Subscribe<T> = (
+  emit: (value: T) => void,
+  emitError?: (error: Error) => void,
+) => () => void;
+
+// TreeChildrenSubscribe — Lazy-Variante für dynamic Children. Wird
+// erst aufgerufen wenn der Knoten im UI ausgeklappt wird. Kein ctx-
+// Argument: Provider sind session-bound; Backend liest tenantId aus
+// session bei jedem fetch/dispatch. V.1.1 hatte ein ctx mit tenantId,
+// das aber im Browser nie echten Tenant trug (war auf SYSTEM_TENANT_ID
+// gepinnt) und vom einzigen V.1.2-Consumer (text-content) ignoriert
+// wurde. SR2-Rip 2026-05-18: Dead-API entfernt; wenn später ein
+// Provider tenant-aware-rendern muss (z.B. cross-tenant-Dashboards
+// für SystemAdmin), wird ctx mit echtem Tenant-Source aus dem Auth-
+// Layer re-introduziert. YAGNI bis dahin.
+export type TreeChildrenSubscribe = () => Subscribe<readonly TreeNode[]>;
+
+// TreeActionDef — Schema-Eintrag pro Action in der treeActions-Map
+// eines Features. Phase 0: Args sind ein optionales Type-Sample
+// (kein Validator zur Laufzeit — Validation passiert compile-time
+// via buildTarget-Generic, runtime via Editor-Panel-Schema).
+//
+// Lebt hier (nicht in build-target.ts) weil es konzeptuell zur
+// Visual-Tree-Domäne gehört, nicht zum Builder. build-target.ts
+// importiert den Type von hier.
+export type TreeActionDef<TArgs = Record<string, unknown>> = {
+  readonly args?: TArgs;
+};
+
+// TreeActionsHandle<T> — Return-Type von r.treeActions(...). Trägt
+// den literal-typed Action-Map durch das Feature-Export-System
+// (siehe FeatureDefinition.exports + Memory `[EventDef-Exports-
+// Pattern]`). Das ist die compile-time Bridge zu buildTarget:
+//
+//   const handle = r.treeActions({ edit: { args: { slug: "" as string } } });
+//   // handle.id        → TFeature (literal feature name)
+//   // handle.treeActions → { edit: { args: { slug: string } } } (literal-typed)
+//   buildTarget({ target: handle, action: "edit", args: { slug: "x" } });
+//   //                                ^^^^^^^^^^^^^^         ^^^^^^^^
+//   //                                literal-validated      typed-validated
+//
+// Runtime-Lookup geht über FeatureDefinition.treeActions (erased Map),
+// Compile-Time-Validation über diesen Handle.
+export type TreeActionsHandle<
+  TFeature extends string,
+  TActions extends Record<string, TreeActionDef>,
+> = {
+  readonly id: TFeature;
+  readonly treeActions: TActions;
+};