@cosmicdrift/kumiko-types 0.326.1 → 0.328.0

package/src/tenant-db-types.ts

@@ -1,116 +0,0 @@
-import type { DbRunner } from "./db-connection";
-import type { EntityTableMeta } from "./entity-table-meta-types";
-import type { ExecutorOnly, NotExecutorOnly } from "./executor-brand";
-import type { TenantId } from "./identifiers";
-import type { SchemaTable } from "./schema-table-types";
-import type { TenancyBrand } from "./tenancy-brand";
-import type { SelectOptions, WhereObject } from "./where-clause-types";
-
-// Method-form writes reject the executor-only brand exactly like the free-function
-// helpers (#742): a managed EntityTable is a rebuildable projection, so writing it
-// directly — free-function OR method-form — drifts the row past its event stream and
-// a rebuild wipes it. The permissive base stays (raw pgTables AND unmanaged entity
-// metas are not projections → writable); `& NotExecutorOnly` strips only branded
-// EntityTables (its `[EXECUTOR_ONLY]: true` violates the optional-never). Reads keep
-// the plain `SchemaTable` param.
-type WritableTable = (SchemaTable | EntityTableMeta) & NotExecutorOnly;
-
-// db.global(table)'s surface: reads are unrestricted; writes require the managed
-// EntityTable's executor-only brand to be absent (mirrors WritableTable above).
-type GlobalReads = {
-  selectMany<T = Record<string, unknown>>(
-    where?: WhereObject,
-    options?: SelectOptions,
-  ): Promise<readonly T[]>;
-  fetchOne<T = Record<string, unknown>>(where: WhereObject): Promise<T | undefined>;
-};
-type GlobalWrites = {
-  insertOne<T = Record<string, unknown>>(values: Record<string, unknown>): Promise<T | undefined>;
-  updateMany<T = Record<string, unknown>>(
-    set: Record<string, unknown>,
-    where: WhereObject,
-  ): Promise<readonly T[]>;
-  deleteMany(where: WhereObject): Promise<void>;
-};
-// Checks `extends ExecutorOnly`, not `NotExecutorOnly` — the latter's optional-never
-// property is a TS "weak type" that would silently collapse every TTable to GlobalReads.
-export type GlobalTableDb<TTable> = GlobalReads &
-  (TTable extends ExecutorOnly ? unknown : GlobalWrites);
-
-/**
- * TenantDb scope modes:
- *
- * - "tenant" (default): SELECT/UPDATE/DELETE filtered by tenantId + reference data (tenantId=SYSTEM_TENANT_ID).
- *   INSERT forces tenantId — handler cannot override.
- *
- * - "system" (r.systemScope()): No tenant filter on reads/updates/deletes.
- *   INSERT uses tenantId as default but handler can override.
- *
- * Tables without a tenantId column are always unfiltered regardless of mode.
- */
-export type TenantDbMode = "tenant" | "system";
-
-export type TenantDb = {
-  readonly tenantId: TenantId;
-  readonly mode: TenantDbMode;
-  /**
-   * Unfiltered DbRunner escape hatch for handlers/hooks that declare `escapeHatch: { reason }`.
-   * Throws `AccessDeniedError` when ungranted, or `Error` when `reason` is empty.
-   */
-  unsafeRaw(reason: string): DbRunner;
-  /**
-   * Reach a "global" table with the tenant filter lifted — reads always work; writes
-   * reject unless the write handler declared `escapeHatch: { reason }`. "tenant"-tenancy is a compile error here.
-   */
-  global<TTable extends (SchemaTable | EntityTableMeta) & TenancyBrand<"global">>(
-    table: TTable,
-  ): GlobalTableDb<TTable>;
-  selectMany<T = Record<string, unknown>>(
-    table: SchemaTable | EntityTableMeta,
-    where?: WhereObject,
-    options?: SelectOptions,
-  ): Promise<readonly T[]>;
-  fetchOne<T = Record<string, unknown>>(
-    table: SchemaTable | EntityTableMeta,
-    where: WhereObject,
-  ): Promise<T | undefined>;
-  count(table: SchemaTable | EntityTableMeta, where?: WhereObject): Promise<number>;
-  insertOne<T = Record<string, unknown>>(
-    table: WritableTable,
-    values: Record<string, unknown>,
-  ): Promise<T | undefined>;
-  updateMany<T = Record<string, unknown>>(
-    table: WritableTable,
-    set: Record<string, unknown>,
-    where: WhereObject,
-  ): 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;
-  /**
-   * Raw unfiltered DbRunner, gated behind a mandatory non-empty `reason` for auditability.
-   * Throws on an empty (or whitespace-only) reason.
-   */
-  unsafeRaw(reason: string): DbRunner;
-  // Same self-check pair as above, but hands back the caller's
-  // ctx.dbOutsideTransaction TenantDb instead of the in-tx one — for
-  // 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, as createSystemDbView callers do).
-  readonly outsideTransaction: {
-    assertTenantMatch(tenantId: TenantId): TenantDb;
-    acknowledgeCrossTenant(reason: string): TenantDb;
-  };
-};

package/src/tree-node.ts

@@ -1,134 +0,0 @@
-// 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;
-  // Qualified screen name ("<feature>:screen:<id>") — renders as a route
-  // link. Exactly one of `screen`/`target` must be set; an action with
-  // neither is a Hover-Icon that does nothing, the boot validator rejects
-  // it.
-  readonly screen?: string;
-  // EditorPanel dispatch target — renders as a click-dispatch button.
-  // Exactly one of `screen`/`target` must be set.
-  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-declared "+ create" action for nodes with `state: "empty"`.
-  // The tree component automatically shows a "+" icon; click navigates to
-  // `createAction.screen` or dispatches `createAction.target` — the
-  // provider knows what "create empty" means for it (e.g. "new page slug"
-  // vs. "new entity row"), convention couldn't guess that. Consistent with
-  // `state` (also provider-explicit). See 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;
-};

package/src/tz-context.ts

@@ -1,63 +0,0 @@
-// TzContext — the type contract for ctx.tz (pure types; the factory lives in
-// @cosmicdrift/kumiko-framework, time/tz-context.ts).
-//
-// `Temporal` here is the ambient global from TypeScript's lib
-// (lib.esnext.temporal) — at runtime the framework installs the polyfill.
-
-import type { GeoAddress, GeoCoordinates, GeoTzProvider } from "./geo-tz";
-
-// JSON form for wall-clock + TZ — see createLocatedTimestampField() in
-// @cosmicdrift/kumiko-framework, engine/factories.ts. Two fields, foolproof.
-export type LocatedTimestampJson = {
-  /** Wall-clock ISO without offset, e.g. "2026-04-03T10:00:00" */
-  readonly at: string;
-  /** IANA zone, e.g. "Europe/Lisbon" */
-  readonly tz: string;
-};
-
-export type TzContext = {
-  /** Default TZ of the tenant (from tenant.timezone, default "UTC"). */
-  readonly tenant: string;
-  /** Display TZ of the current user (profile override, fallback tenant). */
-  readonly user: string;
-
-  /** Current moment as UTC instant. */
-  now(): Temporal.Instant;
-  /** Current moment as ZonedDateTime in the requested zone. */
-  nowIn(tz: string): Temporal.ZonedDateTime;
-
-  /** Today's calendar date in the requested zone. */
-  today(tz: string): Temporal.PlainDate;
-  /** Day boundaries (00:00 to 24:00 next day) as UTC instants — for DB range queries. */
-  todayRange(tz: string): { readonly start: Temporal.Instant; readonly end: Temporal.Instant };
-
-  /** Wall-clock string + IANA zone → ZonedDateTime. */
-  parse(wallClock: string, tz: string): Temporal.ZonedDateTime;
-
-  /** ZonedDateTime → UTC instant. */
-  toInstant(zdt: Temporal.ZonedDateTime): Temporal.Instant;
-
-  /** ZonedDateTime → JSON pair { at, tz } (API boundary). */
-  toLocatedJson(zdt: Temporal.ZonedDateTime): LocatedTimestampJson;
-
-  /** JSON pair { at, tz } → ZonedDateTime (wall-clock + IANA). */
-  fromLocatedJson(obj: LocatedTimestampJson): Temporal.ZonedDateTime;
-
-  /** Geo coordinates → IANA zone via the configured GeoTzProvider.
-   *  Throws when no provider is configured (v1 default). */
-  fromCoordinates(coords: GeoCoordinates): Promise<string>;
-  /** Postal address → IANA zone via GeoTzProvider. Throws when no provider is
-   *  configured OR the provider does not support fromAddress (the offline
-   *  lat/lng provider does not). */
-  fromAddress(address: GeoAddress): Promise<string>;
-};
-
-export type TzContextOptions = {
-  /** Tenant default TZ. Default "UTC" when unset. */
-  readonly tenant?: string;
-  /** User override. Default = tenant. */
-  readonly user?: string;
-  /** Optional geo→zone adapter for ctx.tz.fromCoordinates / fromAddress.
-   *  Without a provider those methods throw. */
-  readonly geoTz?: GeoTzProvider;
-};

package/src/where-clause-types.ts

@@ -1,31 +0,0 @@
-// WhereValue: primitive for eq, array for IN, null for IS NULL, or an
-// operator-object for range/comparisons. Deliberately NOT `unknown |
-// WhereOperator` — that union collapses to `unknown` and erases the
-// operator form at every call site (a typo like `{ gtee: x }` would
-// type-check, then bind as eq at runtime).
-export type WhereOperator = {
-  readonly gt?: unknown;
-  readonly gte?: unknown;
-  readonly lt?: unknown;
-  readonly lte?: unknown;
-  readonly ne?: unknown;
-  readonly in?: readonly unknown[];
-  readonly like?: string;
-};
-export type WherePrimitive = string | number | boolean | bigint | Date | null | undefined;
-export type WhereValue = WherePrimitive | readonly WherePrimitive[] | WhereOperator;
-// Wider index so dynamic Record<string, unknown> builders still typecheck;
-// annotate literals as WhereValue / satisfies WhereValue to catch typos.
-export type WhereObject = Record<string, WhereValue | unknown>;
-
-export type OrderByClause = {
-  readonly col: string;
-  readonly direction?: "asc" | "desc";
-};
-
-export type SelectOptions = {
-  readonly limit?: number;
-  // Single column or array for multi-column tie-breaks (e.g.
-  // [{col: "createdAt"}, {col: "id"}] for chronological-with-stable-id).
-  readonly orderBy?: OrderByClause | readonly OrderByClause[];
-};

package/src/workspace.ts

@@ -1,42 +0,0 @@
-import type { AccessRule } from "./handlers";
-
-// Workspace declaration. A workspace is a persona-/role-scoped UI surface:
-// pure UI composition with no backend, DB or auth impact. The engine stores
-// these verbatim and the active web shell (shellWorkspaces) renders the
-// switcher and filters the nav tree by membership + access.
-//
-// Membership is computed from two sources, merged at boot:
-//   1. r.workspace({ nav: [...] }) — explicit list of nav QNs
-//   2. r.nav({ workspaces: [...] }) — nav entry self-assigns to workspaces
-// A nav entry that appears in neither source belongs to no workspace and
-// only shows up when no workspace is active (legacy / non-workspace apps).
-//
-// Cross-feature references are allowed: `nav` may point at any registered
-// nav QN. The boot validator checks references exist and that workspace
-// IDs referenced from r.nav are real.
-export type WorkspaceDefinition = {
-  // Feature author writes the short id ("disposition"); the registry
-  // overwrites `id` with the qualified name ("bmc:workspace:disposition")
-  // in its stored copy. Same pattern as NavDefinition / ScreenDefinition.
-  readonly id: string;
-  // 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 (mirrors NavDefinition.icon).
-  readonly icon?: string;
-  // Sort weight in the workspace switcher (lower = earlier). Ties broken
-  // by registration order — features registered later appear lower.
-  readonly order?: number;
-  // Role / openToAll gate. Only users matching this rule see the workspace
-  // in their switcher. Mirrors NavDefinition.access — same semantics across
-  // the UI surface, so a default-deny app can do `{ roles: [] }`.
-  readonly access?: AccessRule;
-  // Explicit nav QNs that belong to this workspace. Merged with any nav
-  // entries that self-assign via r.nav({ workspaces: [...] }).
-  readonly nav?: readonly string[];
-  // Default workspace at login when the user has access to multiple. Boot
-  // validator rejects more than one default per app.
-  readonly default?: boolean;
-};

package/src/write-error-info-types.ts

@@ -1,20 +0,0 @@
-// Plain, JSON-serializable snapshot of a KumikoError for use on the write-path
-// (WriteResult.error, BatchResult.error). The dispatcher stores results under
-// an idempotency key — a KumikoError instance wouldn't round-trip through
-// JSON, so we keep structural data only and rebuild the instance on demand
-// via reraiseAsKumikoError when we need to throw upstream again.
-export type WriteErrorInfo = {
-  readonly code: string;
-  readonly httpStatus: number;
-  readonly i18nKey: string;
-  readonly i18nParams?: Readonly<Record<string, unknown>>;
-  readonly message: string;
-  readonly details?: unknown;
-};
-
-// The failure half of WriteResult — `{ isSuccess: false } + error`. Not
-// generic: the error carries zero data, so there's nothing to narrow.
-export type WriteFailure = {
-  readonly isSuccess: false;
-  readonly error: WriteErrorInfo;
-};