@cosmicdrift/kumiko-types 0.327.0 → 0.328.1

package/dist/screen.js

@@ -0,0 +1,3 @@
+export function metricField(metric) {
+    return typeof metric === "string" ? metric : metric.field;
+}

package/dist/search-adapter.d.ts

@@ -0,0 +1,32 @@
+import type { EntityId, TenantId } from "./identifiers.js";
+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>;
+    setDefaultConfig?(config: SearchAdapterConfig): 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>;
+    indexBatch?(tenantId: TenantId, docs: readonly SearchDocument[]): Promise<void>;
+    removeBatch?(tenantId: TenantId, items: readonly {
+        entityType: string;
+        entityId: EntityId;
+    }[]): Promise<void>;
+    dropAllIndexes?(): Promise<number>;
+};

package/dist/search-adapter.js

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

package/dist/secrets-types.d.ts

@@ -0,0 +1,52 @@
+import type { TenantId } from "./identifiers.js";
+declare const SecretBrand: unique symbol;
+export type Secret<T = string> = {
+    readonly [SecretBrand]: true;
+    readonly reveal: () => T;
+};
+export declare function createSecret<T>(value: T): Secret<T>;
+export declare function isSecret(v: unknown): v is Secret<unknown>;
+type Primitive = string | number | boolean | bigint | symbol | null | undefined;
+type SafeLeaf = Date | RegExp | Temporal.Instant | Temporal.ZonedDateTime | Temporal.PlainDate | Temporal.PlainDateTime | Temporal.PlainTime | Temporal.PlainYearMonth | Temporal.PlainMonthDay | Temporal.Duration | Map<unknown, unknown> | Set<unknown>;
+export type ContainsSecret<T> = [T] extends [never] ? false : unknown extends T ? false : T extends Secret<unknown> ? true : T extends Primitive ? false : T extends SafeLeaf ? false : T extends readonly (infer U)[] ? ContainsSecret<U> : T extends object ? true extends {
+    [K in keyof T]-?: ContainsSecret<T[K]>;
+}[keyof T] ? true : false : false;
+export type SecretAuditContext = {
+    readonly userId: string;
+    readonly handlerName: string;
+};
+export type SecretKeyRef = string | {
+    readonly name: string;
+};
+export interface SecretsContext {
+    get(tenantId: TenantId, key: SecretKeyRef, auditCtx?: SecretAuditContext): Promise<Secret<string> | undefined>;
+    has(tenantId: TenantId, key: SecretKeyRef): Promise<boolean>;
+    set(tenantId: TenantId, key: SecretKeyRef, value: string, opts?: {
+        redact?: (plaintext: string) => string;
+        hint?: string;
+        updatedBy?: string;
+    }): Promise<void>;
+    delete(tenantId: TenantId, key: SecretKeyRef, opts?: {
+        deletedBy?: string;
+    }): Promise<boolean>;
+}
+export type Envelope = {
+    readonly ciphertext: Buffer;
+    readonly iv: Buffer;
+    readonly authTag: Buffer;
+    readonly encryptedDek: Buffer;
+    readonly kekVersion: number;
+};
+export type KeyScope = {
+    readonly tenantId?: TenantId;
+};
+export interface MasterKeyProvider {
+    wrapDek(dek: Buffer, scope?: KeyScope): Promise<{
+        encryptedDek: Buffer;
+        kekVersion: number;
+    }>;
+    unwrapDek(encryptedDek: Buffer, kekVersion: number, scope?: KeyScope): Promise<Buffer>;
+    currentVersion(): number;
+    isAvailable(): Promise<boolean>;
+}
+export {};

package/dist/secrets-types.js

@@ -0,0 +1,30 @@
+// Envelope Encryption types. Separating DEK (per-value) from KEK (central)
+// is what makes key rotation cheap: on rotation we only re-wrap the small
+// encryptedDek, never touch the ciphertext.
+// Plaintext-secret wrapper (branded). Carries the actual string internally
+// but the nominal typing stops it from landing in an HTTP response by
+// accident — a response-serializer guard + the reveal() cost make the leak
+// intentional. Framework code that sees `Secret<string>` knows the caller
+// has already gone through the audited ctx.secrets.get path.
+//
+// Registered symbol, matching KUMIKO_*_SYMBOL in schema-table-types.ts. A
+// plain Symbol() is per-copy: two resolved copies of this package brand with
+// two different symbols, so createSecret() from one and isSecret() from the
+// other disagree — and isSecret() is the ONLY thing assertNoSecretLeak has,
+// so a false there serializes the plaintext into the response. The namespaced
+// key makes accidental user-land collision implausible; a deliberate forge
+// would only over-trigger the guard, which fails safe.
+const SecretBrand = Symbol.for("kumiko.secret");
+// Implementation helper — bundled-features uses this to wrap a plaintext after
+// decryption. Kept in the framework so both sides share one canonical brand.
+export function createSecret(value) {
+    return {
+        [SecretBrand]: true,
+        reveal: () => value,
+    };
+}
+// True for any object carrying the Secret brand. Used by the response guard
+// to reject leaks before serialization.
+export function isSecret(v) {
+    return typeof v === "object" && v !== null && SecretBrand in v;
+}

package/dist/snapshot-types.d.ts

@@ -0,0 +1,13 @@
+import type { StoredEvent } from "./event-store-types.js";
+export type SnapshotReducer<TState extends Record<string, unknown>> = (state: TState, event: StoredEvent) => TState;
+export type LoadAggregateWithSnapshotResult<TState extends Record<string, unknown>> = {
+    readonly state: TState;
+    readonly version: number;
+    readonly snapshotHit: boolean;
+};
+export type LoadAggregateWithSnapshotOptions = {
+    readonly includeArchived?: boolean;
+    readonly upcastEvent?: (event: StoredEvent) => Promise<StoredEvent>;
+    readonly snapshotEvery?: number;
+    readonly snapshotVersion?: number;
+};

package/dist/snapshot-types.js

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

package/dist/step.d.ts

@@ -0,0 +1,304 @@
+import type { EventStoreExecutor } from "./event-store-executor-types.js";
+import type { KumikoEventTypeMap } from "./event-type-map.js";
+import type { HandlerContext, WriteEvent, WriteResult } from "./handlers.js";
+import type { SaveContext } from "./hooks.js";
+import type { EntityId } from "./identifiers.js";
+import type { WhereObject } from "./where-clause-types.js";
+/**
+ * The kind discriminator for a step instance — matches the step's
+ * registration name in the step-registry (e.g. "return", "compute",
+ * "aggregate.create"). Steps register themselves at module-load time
+ * via defineStep().
+ */
+export type StepKind = string;
+/**
+ * Pipeline-side context handed to step argument resolvers.
+ *
+ * Contains the full HandlerContext (no per-step subset in M.1) plus
+ * the accumulated `steps` map of prior step results, and a `scope`
+ * record for forEach/branch-local bindings.
+ *
+ * `scope` is `Record<string, unknown>` — sub-step builders (forEach,
+ * branch) populate it once they land in later M.1 slices. M.1.1 ships
+ * with `r.step.return` only, which reads `event` and ignores both
+ * `steps` and `scope`.
+ */
+export type PipelineCtx<TPayload = unknown, TMap extends object = KumikoEventTypeMap> = HandlerContext<TMap> & {
+    readonly event: WriteEvent<TPayload>;
+    readonly steps: Readonly<Record<string, unknown>>;
+    readonly scope: Readonly<Record<string, unknown>>;
+    readonly workflow?: {
+        readonly runId: string;
+        readonly workflowName: string;
+        /** Current step index in the pipeline — set by the executor before each step. */
+        readonly stepIndex: number;
+        /**
+         * Retry attempt counter for the current workflow.retry step.
+         * Set by the workflow-engine resume-loop on re-entry; starts at 1.
+         * Absent (undefined) means first attempt.
+         */
+        readonly retryAttempt?: number;
+        /**
+         * Q7 Snapshot-at-Start fingerprint of the workflow definition that
+         * started this run. Propagated into every suspension event payload so
+         * the resume-loop can detect library-upgrades that changed the closure
+         * source and surface them as a typed failure instead of running a
+         * stale-vs-new mix of steps. Optional only for legacy callers; the
+         * workflow-runner sets it on every newly-started run.
+         */
+        readonly definitionFingerprint?: string;
+    };
+};
+/**
+ * A resolver is either a static value or a function that derives the
+ * value from the pipeline-context. M.1 keeps the resolver signature
+ * uniform — every step accepts both forms via a normalise helper.
+ */
+export type StepResolver<T, TPayload = unknown> = T | ((ctx: PipelineCtx<TPayload>) => T);
+export type AwaitedEventType = string & {
+    readonly __awaitedEvent: unique symbol;
+};
+export type EventMatchValue = string | number | boolean | null;
+export type EventMatchOp = {
+    readonly kind: "eq";
+    readonly value: EventMatchValue;
+} | {
+    readonly kind: "ne";
+    readonly value: EventMatchValue;
+} | {
+    readonly kind: "in";
+    readonly values: readonly EventMatchValue[];
+} | {
+    readonly kind: "gt";
+    readonly value: number | string;
+} | {
+    readonly kind: "gte";
+    readonly value: number | string;
+} | {
+    readonly kind: "lt";
+    readonly value: number | string;
+} | {
+    readonly kind: "lte";
+    readonly value: number | string;
+};
+export type EventMatchExpr = {
+    readonly kind: "and";
+    readonly nodes: readonly EventMatchExpr[];
+} | {
+    readonly kind: "or";
+    readonly nodes: readonly EventMatchExpr[];
+} | {
+    readonly kind: "atom";
+    readonly path: readonly string[];
+    readonly op: EventMatchOp;
+};
+export type EventMatch = {
+    readonly version: 1;
+    readonly expr: EventMatchExpr;
+};
+/**
+ * Per-step error strategy. M.1.1 only supports "throw" — the type is
+ * deliberately narrowed so callers cannot pass an unsupported strategy
+ * past the type-checker. The doc lists "return" / "skip" / fallback as
+ * future strategies; each lands together with its own runtime support
+ * + integration test in a later slice (no untested type expansion).
+ */
+export type StepFailureStrategy = "throw";
+export type StepDef<TArgs = unknown, TResult = unknown> = {
+    readonly kind: StepKind;
+    readonly defaultFailureStrategy: StepFailureStrategy;
+    readonly resultKey?: (args: TArgs) => string | undefined;
+    readonly subPaths?: readonly string[];
+    readonly tier?: 1 | 2 | 3;
+    readonly run: (args: TArgs, ctx: PipelineCtx) => Promise<TResult> | TResult;
+};
+/**
+ * An instance of a step in a pipeline — what users build via the
+ * step-builder (`r.step.compute(...)`). Carries the kind + resolved-or-
+ * resolver args + the user-chosen onFailure override.
+ *
+ * `args` is `unknown` at this layer — the registered StepDef knows the
+ * concrete shape and casts at run() time. Cross-step type-safety lives
+ * in the per-step builder factories, not in this central type.
+ */
+export type StepInstance = {
+    readonly kind: StepKind;
+    readonly args: unknown;
+    readonly onFailure?: StepFailureStrategy;
+};
+/**
+ * What `stepsPipeline(closure)` returns. Carries the closure (instead of an
+ * eagerly-built array) so each handler-call sees a fresh event ref and
+ * the `r` step-builder is resolved at runtime, not at module-load time.
+ *
+ * `__kind: "pipeline"` lets defineWriteHandler distinguish a pipeline-
+ * form `perform` from accidental other shapes.
+ *
+ * `_TData` is a phantom type-parameter — held in constraint position
+ * only, never referenced in the type body. defineWriteHandler binds it
+ * via `def.perform: PipelineDef<…, TData>` (the call-site uses TData
+ * without underscore — phantom-prefix is purely a Biome
+ * `noUnusedVariables` marker, not user-facing). _TData is NOT inferred
+ * from the closure body (r.step.return has its own per-call TData), so
+ * callers must spell it explicitly:
+ *   `stepsPipeline<{ greeting: string }, { echoed: string }>(...)`
+ * Better DX is a known follow-up — see step-vocabulary.md M.1-Followups.
+ */
+export type PipelineDef<TPayload = unknown, _TData = unknown, TAwaits extends Record<string, AwaitedEventType> = Record<string, AwaitedEventType>> = {
+    readonly __kind: "pipeline";
+    readonly awaits?: Readonly<Record<string, string>>;
+    readonly build: (ctx: PipelineBuildCtx<TPayload, TAwaits>) => readonly StepInstance[];
+};
+/**
+ * Argument bundle passed to the closure inside `stepsPipeline(closure)`.
+ * Build-time only — no `steps`, no `scope`, no `db`: at build time no
+ * step has run yet.
+ *
+ * The closure is invoked ONCE per handler-call and returns the immutable
+ * list of step instances. Values inside the closure that depend on prior
+ * step results MUST go through resolvers (functions) — those receive the
+ * resolver-side PipelineCtx which carries `steps` + `scope`.
+ *
+ * **Closure-body contract:** the closure must produce a deterministic
+ * step-list that doesn't depend on `event.payload` — branching on payload
+ * fields belongs inside resolvers (where they fire per-call), not in the
+ * outer closure body. Boot-validation runs the closure once with a dummy
+ * empty payload to scan unsafeProjection-* step targets; a closure that
+ * conditionally builds different step-lists per payload would silently
+ * skip validation. See validate-projection-allowlist.ts for the
+ * boot-side mechanics.
+ */
+export type PipelineBuildCtx<TPayload = unknown, TAwaits extends Record<string, AwaitedEventType> = Record<string, AwaitedEventType>> = {
+    readonly event: WriteEvent<TPayload>;
+    readonly r: StepBuilder;
+    readonly awaits: TAwaits;
+};
+/**
+ * Step-builder namespace handed to the pipeline closure. The fields
+ * grow as M.1 adds more steps. Each is a thin factory that returns a
+ * StepInstance — the runtime resolution happens later in run().
+ *
+ * Why nested under `step`: matches the doc-API surface and leaves room
+ * for future sibling namespaces (`r.trigger`, `r.transform`) without
+ * crowding the top-level r.
+ */
+export type StepBuilder = {
+    readonly step: StepNamespace;
+};
+/**
+ * The collection of step factory functions. Grown incrementally —
+ * landed: return (M.1.1), compute (M.1.2), unsafeProjectionUpsert
+ * (M.1.3), aggregate.create (M.1.4). Pending: branch, forEach,
+ * read.*, aggregate.update, aggregate.appendEvent,
+ * unsafeProjectionDelete.
+ */
+export type StepNamespace = {
+    readonly return: <TData>(resolver: StepResolver<WriteResult<TData>>) => StepInstance;
+    readonly compute: <TResult>(name: string, fn: (ctx: PipelineCtx) => TResult) => StepInstance;
+    readonly unsafeProjectionUpsert: (args: {
+        readonly table: unknown;
+        readonly on: readonly string[];
+        readonly row: StepResolver<Record<string, unknown>>;
+    }) => StepInstance;
+    readonly unsafeProjectionDelete: (args: {
+        readonly table: unknown;
+        readonly where: StepResolver<WhereObject>;
+    }) => StepInstance;
+    readonly read: {
+        readonly findOne: (name: string, opts: {
+            readonly table: unknown;
+            readonly where: StepResolver<WhereObject | undefined>;
+            readonly unsafeAllTenants?: {
+                readonly reason: string;
+            };
+        }) => StepInstance;
+        readonly findMany: (name: string, opts: {
+            readonly table: unknown;
+            readonly where?: StepResolver<WhereObject | undefined>;
+            readonly limit?: number;
+            readonly unsafeAllTenants?: {
+                readonly reason: string;
+            };
+        }) => StepInstance;
+    };
+    readonly aggregate: {
+        readonly create: (name: string, opts: {
+            readonly executor: EventStoreExecutor;
+            readonly data: StepResolver<Record<string, unknown>>;
+        }) => StepInstance;
+        readonly update: (name: string, opts: {
+            readonly executor: EventStoreExecutor;
+            readonly id: StepResolver<EntityId>;
+            readonly changes: StepResolver<Record<string, unknown>>;
+            readonly version?: StepResolver<number | undefined>;
+            readonly skipOptimisticLock?: boolean;
+        }) => StepInstance;
+        readonly appendEvent: (args: {
+            readonly aggregateId: StepResolver<string>;
+            readonly aggregateType: string;
+            readonly type: string;
+            readonly payload: StepResolver<unknown>;
+            readonly headers?: StepResolver<Readonly<Record<string, string | number | boolean>>>;
+        }) => StepInstance;
+    };
+    readonly branch: (args: {
+        readonly if: StepResolver<boolean>;
+        readonly onTrue: readonly StepInstance[];
+        readonly onFalse?: readonly StepInstance[];
+    }) => StepInstance;
+    readonly forEach: <TItem = unknown>(args: {
+        readonly over: StepResolver<readonly TItem[]>;
+        readonly as: string;
+        readonly do: readonly StepInstance[];
+        readonly concurrency?: 1;
+    }) => StepInstance;
+    readonly webhook: {
+        readonly send: (args: {
+            readonly url: StepResolver<string>;
+            readonly method?: "POST" | "PUT" | "PATCH";
+            readonly headers?: StepResolver<Readonly<Record<string, string>>>;
+            readonly body?: StepResolver<unknown>;
+            readonly auth?: {
+                readonly kind: "bearer";
+                readonly secret: string;
+            } | {
+                readonly kind: "header";
+                readonly name: string;
+                readonly secret: string;
+            };
+            readonly mode: "deferred";
+            readonly retry?: {
+                readonly times: number;
+                readonly backoff: "exponential" | "linear";
+            };
+        }) => StepInstance;
+    };
+    readonly mail: {
+        readonly send: (args: {
+            readonly to: StepResolver<string | readonly string[]>;
+            readonly subject: StepResolver<string>;
+            readonly body: StepResolver<string>;
+            readonly from?: StepResolver<string>;
+            readonly mode: "deferred";
+        }) => StepInstance;
+    };
+    readonly callFeature: (name: string, opts: {
+        readonly handler: string;
+        readonly payload: StepResolver<unknown>;
+        readonly as?: import("./handlers.js").SessionUser;
+    }) => StepInstance;
+    readonly wait: (args: {
+        readonly for: StepResolver<string>;
+    }) => StepInstance;
+    readonly waitForEvent: (args: {
+        readonly event: AwaitedEventType;
+        readonly match?: StepResolver<EventMatch>;
+        readonly timeout: StepResolver<string>;
+    }) => StepInstance;
+    readonly retry: (args: {
+        readonly times: number;
+        readonly backoff: "exponential" | "linear";
+        readonly do: readonly StepInstance[];
+    }) => StepInstance;
+};
+export type AggregateStepResult = SaveContext;

package/dist/step.js

@@ -0,0 +1,11 @@
+// Step-Vocabulary Types — see docs/plans/architecture/intern/step-vocabulary.md
+//
+// M.1 minimal scope:
+//   - Steps execute against the existing HandlerContext (no per-step subset).
+//   - steps-accumulator is Record<string, unknown> (no tuple-reduce typing).
+//   - Resolvers receive the full PipelineCtx as one argument.
+//
+// Strict typing on appendEvent inside steps is deferred to a later pass
+// (see TS-typing notes in the design doc). M.1 uses unsafeAppendEvent
+// semantics under the hood for r.step.aggregate.appendEvent.
+export {};

package/dist/target-ref.d.ts

@@ -0,0 +1,5 @@
+export type TargetRef = {
+    readonly featureId: string;
+    readonly action: string;
+    readonly args?: Readonly<Record<string, unknown>>;
+};

package/{src/target-ref.ts → dist/target-ref.js}

@@ -13,9 +13,4 @@
 // 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>>;
-};
+export {};

package/dist/tenancy-brand.d.ts

@@ -0,0 +1,6 @@
+export type EntityTenancy = "global" | "tenant";
+declare const TENANCY: unique symbol;
+export interface TenancyBrand<T extends EntityTenancy> {
+    readonly [TENANCY]: T;
+}
+export {};

package/dist/tenancy-brand.js

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

package/dist/tenant-db-types.d.ts

@@ -0,0 +1,67 @@
+import type { DbRunner } from "./db-connection.js";
+import type { EntityTableMeta } from "./entity-table-meta-types.js";
+import type { ExecutorOnly, NotExecutorOnly } from "./executor-brand.js";
+import type { TenantId } from "./identifiers.js";
+import type { SchemaTable } from "./schema-table-types.js";
+import type { TenancyBrand } from "./tenancy-brand.js";
+import type { SelectOptions, WhereObject } from "./where-clause-types.js";
+type WritableTable = (SchemaTable | EntityTableMeta) & NotExecutorOnly;
+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>;
+};
+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>;
+};
+export declare const SYSTEM_SCOPE_CHECK_BRAND: unique symbol;
+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;
+    readonly outsideTransaction: {
+        assertTenantMatch(tenantId: TenantId): TenantDb;
+        acknowledgeCrossTenant(reason: string): TenantDb;
+    };
+};
+export {};

package/dist/tenant-db-types.js

@@ -0,0 +1,5 @@
+// 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 = Symbol.for("kumiko.system-scope-check");

package/dist/tree-node.d.ts

@@ -0,0 +1,26 @@
+import type { TargetRef } from "./target-ref.js";
+export type TreeNodeState = "filled" | "stub" | "empty" | "loading" | "error";
+export type TreeAction = {
+    readonly icon: string;
+    readonly label: string;
+    readonly screen?: string;
+    readonly target?: TargetRef;
+};
+export type TreeNode = {
+    readonly label: string;
+    readonly icon?: string;
+    readonly state?: TreeNodeState;
+    readonly target?: TargetRef;
+    readonly actions?: readonly TreeAction[];
+    readonly children?: readonly TreeNode[] | TreeChildrenSubscribe;
+    readonly createAction?: TreeAction;
+};
+export type Subscribe<T> = (emit: (value: T) => void, emitError?: (error: Error) => void) => () => void;
+export type TreeChildrenSubscribe = () => Subscribe<readonly TreeNode[]>;
+export type TreeActionDef<TArgs = Record<string, unknown>> = {
+    readonly args?: TArgs;
+};
+export type TreeActionsHandle<TFeature extends string, TActions extends Record<string, TreeActionDef>> = {
+    readonly id: TFeature;
+    readonly treeActions: TActions;
+};

package/dist/tree-node.js

@@ -0,0 +1,22 @@
+// 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.
+export {};

package/dist/tz-context.d.ts

@@ -0,0 +1,48 @@
+import type { GeoAddress, GeoCoordinates, GeoTzProvider } from "./geo-tz.js";
+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;
+};