@cosmicdrift/kumiko-types 0.327.0 → 0.328.1

package/src/hook-phase.ts

@@ -1,2 +0,0 @@
-// Keep in sync with HookPhases in packages/framework/src/engine/hook-helpers.ts.
-export type HookPhase = "inTransaction" | "afterCommit";

package/src/hooks.ts

@@ -1,170 +0,0 @@
-import type { StoredEvent } from "./event-store-types";
-import type { AppContext } from "./handlers";
-import type { HookPhase } from "./hook-phase";
-import type { EntityId } from "./identifiers";
-
-// --- Validation ---
-
-export type ValidationError = {
-  readonly field: string;
-  readonly error: string;
-};
-
-export type ValidationHookFn = (
-  data: Readonly<Record<string, unknown>>,
-) => readonly ValidationError[] | null;
-
-// --- Save/Delete Context (what hooks receive) ---
-
-export type SaveContext = {
-  readonly kind: "save";
-  readonly id: EntityId;
-  readonly data: Readonly<Record<string, unknown>>;
-  readonly changes: Readonly<Record<string, unknown>>;
-  readonly previous: Readonly<Record<string, unknown>>;
-  readonly isNew: boolean;
-  readonly entityName?: string | undefined;
-  // The event that produced this save. Populated by the event-store-executor;
-  // the pipeline uses it to drive projections inside the same transaction.
-  // Optional because hand-crafted SaveContexts (tests, custom executors) may
-  // not have an event — projections just skip in that case.
-  readonly event?: StoredEvent | undefined;
-};
-
-export type DeleteContext = {
-  readonly kind: "delete";
-  readonly id: EntityId;
-  readonly data: Readonly<Record<string, unknown>>;
-  readonly entityName?: string | undefined;
-  // See SaveContext.event — same semantics.
-  readonly event?: StoredEvent | undefined;
-};
-
-export type LifecycleResult = SaveContext | DeleteContext;
-
-// --- Lifecycle Hooks ---
-
-export type PreSaveHookFn = (
-  changes: Record<string, unknown>,
-  context: AppContext & {
-    readonly previous: Readonly<Record<string, unknown>>;
-    readonly isNew: boolean;
-  },
-) => Promise<Record<string, unknown>>;
-
-export type PostSaveHookFn = (result: SaveContext, context: AppContext) => Promise<void>;
-
-// Batch-variant: called once at the end of a dispatcher batch with every
-// successful SaveContext. The per-save PostSaveHookFn still fires for
-// side-effects that need per-entity semantics (SSE); PostSaveBatch exists
-// for adapters that can amortise work across the whole batch (e.g. search
-// index batch-writes, bulk webhook fanout).
-export type PostSaveBatchHookFn = (
-  results: readonly SaveContext[],
-  context: AppContext,
-) => Promise<void>;
-
-export type PreDeleteHookFn = (payload: DeleteContext, context: AppContext) => Promise<void>;
-
-export type PostDeleteHookFn = (payload: DeleteContext, context: AppContext) => Promise<void>;
-
-export type PostDeleteBatchHookFn = (
-  payloads: readonly DeleteContext[],
-  context: AppContext,
-) => Promise<void>;
-
-export type PreQueryHookFn = (
-  payload: Record<string, unknown>,
-  context: AppContext,
-) => Promise<Record<string, unknown>>;
-
-// postQuery — fires after query-handler-execute, before field-access-read-filter.
-// Hook receives normalized rows + entityName + can mutate rows (e.g., merge
-// custom-fields, add computed-counts, attach related-data). Mutation result
-// replaces original rows. Hook is responsible for its own field-access-logic
-// on added fields (field-access-filter only knows entity's stammfields).
-export type PostQueryHookFn = (
-  result: {
-    // undefined for standalone queries (no-colon handler names like
-    // "ns:dashboard") — those have no backing entity, but handler-keyed
-    // postQuery hooks still fire on them.
-    readonly entityName: string | undefined;
-    readonly rows: ReadonlyArray<Record<string, unknown>>;
-  },
-  context: AppContext,
-) => Promise<{ rows: ReadonlyArray<Record<string, unknown>> }>;
-
-export type LifecycleHookFn =
-  | PreSaveHookFn
-  | PostSaveHookFn
-  | PreDeleteHookFn
-  | PostDeleteHookFn
-  | PreQueryHookFn
-  | PostQueryHookFn;
-
-export type { HookPhase } from "./hook-phase";
-
-// Owner-tag shared across every hook structure. The lifecycle pipeline uses
-// it to skip hooks whose owning feature is globally disabled:
-//   - A concrete feature name like "orders" → subject to the feature-toggle
-//     filter (skipped when "orders" is disabled).
-//   - "*" (star) → invariant plumbing, never filtered. Reserved for
-//     extension-provided hooks and framework-internal hooks that belong to
-//     the pipeline itself, not a feature.
-//   - Omitted (undefined) → treated as "*". Supports tests that hand-build
-//     HookMap objects without caring about ownership.
-export type HookOwner = { readonly featureName?: string };
-
-export type PhasedHook<TFn> = {
-  readonly fn: TFn;
-  readonly phase: HookPhase;
-} & HookOwner;
-
-// Flat (non-phased) hook — preSave, preQuery. Same owner contract, no
-// phase semantics because these hooks run exactly once per handler pass
-// before/around the DB transaction.
-export type OwnedFn<TFn> = {
-  readonly fn: TFn;
-} & HookOwner;
-
-// --- Hook Maps ---
-
-// Slots are optional: defineFeature materializes every slot, but hand-built
-// FeatureDefinitions at system boundaries (test fixtures, partial boots —
-// see registry.test.ts "slot robustness") legitimately omit them, and the
-// registry merge paths tolerate undefined. The type mirrors that contract.
-export type HookMap = {
-  readonly validation?: Readonly<Record<string, ValidationHookFn>>;
-  readonly preSave?: Readonly<Record<string, readonly OwnedFn<PreSaveHookFn>[]>>;
-  readonly postSave?: Readonly<Record<string, readonly PhasedHook<PostSaveHookFn>[]>>;
-  readonly preDelete?: Readonly<Record<string, readonly PhasedHook<PreDeleteHookFn>[]>>;
-  readonly postDelete?: Readonly<Record<string, readonly PhasedHook<PostDeleteHookFn>[]>>;
-  readonly preQuery?: Readonly<Record<string, readonly OwnedFn<PreQueryHookFn>[]>>;
-  readonly postQuery?: Readonly<Record<string, readonly OwnedFn<PostQueryHookFn>[]>>;
-};
-
-export type EntityHookMap = {
-  readonly postSave?: Readonly<Record<string, readonly PhasedHook<PostSaveHookFn>[]>>;
-  readonly preDelete?: Readonly<Record<string, readonly PhasedHook<PreDeleteHookFn>[]>>;
-  readonly postDelete?: Readonly<Record<string, readonly PhasedHook<PostDeleteHookFn>[]>>;
-  readonly postQuery?: Readonly<Record<string, readonly OwnedFn<PostQueryHookFn>[]>>;
-};
-
-// Search-Payload-Extension (F3) — contributor function that adds flat
-// fields to an entity's search-document. Fires synchronously during
-// buildSearchDocument (in `system-hooks.ts`), receives current entity
-// state, returns extra fields to merge into the search-index payload.
-//
-// Use-cases: custom-fields-bundle (merge customFields-jsonb-keys flat
-// into index), tags-bundle (project tags-array as searchable), computed-
-// fields (denormalize related-counts).
-//
-// IMPORTANT: contributor must be deterministic per (entityName, entityId,
-// state). Async-allowed for future-proofing but discouraged — the
-// indexing path runs once per entity-write, sync extension is
-// near-zero-cost.
-export type SearchPayloadContributorFn = (args: {
-  readonly entityName: string;
-  readonly entityId: EntityId;
-  readonly state: Record<string, unknown>;
-}) => Record<string, unknown> | Promise<Record<string, unknown>>;

package/src/http-route.ts

@@ -1,78 +0,0 @@
-// HTTP route definition — feature-declared HTTP endpoints outside
-// the /api/write|query|batch pipeline. Use case: RSS/Atom feeds, OpenAPI
-// specs, OG image generators, webhook receivers — anything where the
-// feature author controls the wire format themselves.
-//
-// Pattern symmetric to r.queryHandler / r.writeHandler: definition as
-// part of the feature (not the app bootstrapping). Phase-3 multi-tenant
-// becomes trivial because tenant context is picked up via host resolution.
-//
-// Escape-hatch stays: runProdApp.extraRoutes (declarative list with
-// `entry` tier) for hand-rolled routes that have nothing to do with a
-// feature (e.g. platform-specific 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>;
-  /** Caller IP resolved via the server's configured, trustedProxyHops-aware
-   *  resolver (same one requestIdMiddleware uses for `/api/*`) — a route
-   *  handler needing the caller's IP (rate limiting, audit) should read
-   *  this instead of parsing X-Forwarded-For itself, which trusts
-   *  whichever hop count the deployment actually has in front of it. */
-  readonly clientIp: string;
-};
-
-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;
-  /** true = public, no session required. false = mounted behind the
-   *  session auth chain (no anonymous fallthrough, PAT rate limit,
-   *  origin + CSRF guards) — a request without a session gets 401. The
-   *  handler reads the caller via getUser(c). */
-  readonly anonymous: boolean;
-  /** Hono-Handler. Bekommt Hono-Context + Framework-Deps; returnt
-   *  Response (sync oder async). */
-  readonly handler: HttpRouteHandler;
-};

package/src/kms-adapter-types.ts

@@ -1,128 +0,0 @@
-import type { TenantId } from "./identifiers";
-
-// The subject a DEK belongs to. User data is shredded on user-forget,
-// tenant data on tenant-destroy, record data on a row-scoped forget —
-// three erase triggers, three subject kinds.
-export type SubjectId =
-  | { readonly kind: "user"; readonly userId: string }
-  | { readonly kind: "tenant"; readonly tenantId: TenantId }
-  | { readonly kind: "record"; readonly entity: string; readonly id: string };
-
-// Compact storage key ("user:<uuid>" / "tenant:<uuid>" / "record:<entity>:<id>")
-// — primary key in adapter backends and cache key in the request-level DEK cache.
-export type SubjectKey = string;
-
-export function subjectKeyForUser(userId: string): SubjectKey {
-  return `user:${userId}`;
-}
-
-export function subjectKeyForTenant(tenantId: TenantId): SubjectKey {
-  return `tenant:${tenantId}`;
-}
-
-// Registry entity names are identifier-shaped; a free-form aggregate_type
-// (events-schema.ts is a plain text column) could otherwise mint a record
-// key that subjectIdSchema (forget-subject.write.ts) later refuses to
-// shred — enforced once here so minting and shredding can never disagree.
-export const RECORD_ENTITY_PATTERN = /^[A-Za-z][A-Za-z0-9_-]*$/;
-
-export function subjectKeyForRecord(entity: string, id: string): SubjectKey {
-  if (!RECORD_ENTITY_PATTERN.test(entity)) {
-    throw new Error(
-      `Invalid record entity for subject key: "${entity}" — must match ${RECORD_ENTITY_PATTERN}`,
-    );
-  }
-  if (id === "") throw new Error("Invalid record id for subject key: empty");
-  return `record:${entity}:${id}`;
-}
-
-export function subjectIdToKey(subject: SubjectId): SubjectKey {
-  switch (subject.kind) {
-    case "user":
-      return subjectKeyForUser(subject.userId);
-    case "tenant":
-      return subjectKeyForTenant(subject.tenantId);
-    case "record":
-      return subjectKeyForRecord(subject.entity, subject.id);
-  }
-}
-
-export function subjectIdFromKey(key: SubjectKey): SubjectId {
-  if (key.startsWith("user:")) return { kind: "user", userId: key.slice("user:".length) };
-  if (key.startsWith("tenant:")) {
-    return { kind: "tenant", tenantId: key.slice("tenant:".length) as TenantId }; // @cast-boundary parse of a key this module minted
-  }
-  if (key.startsWith("record:")) {
-    const rest = key.slice("record:".length);
-    const separatorIndex = rest.indexOf(":");
-    const entity = separatorIndex === -1 ? "" : rest.slice(0, separatorIndex);
-    const id = separatorIndex === -1 ? "" : rest.slice(separatorIndex + 1);
-    if (entity === "" || id === "") throw new Error(`Invalid subject key: ${key}`);
-    return { kind: "record", entity, id };
-  }
-  throw new Error(`Invalid subject key: ${key}`);
-}
-
-export interface KmsContext {
-  readonly tenantId?: TenantId;
-  readonly requestId: string;
-  readonly userId?: string;
-  readonly eraseReason?: string;
-}
-
-export interface KmsHealth {
-  readonly ok: boolean;
-  readonly latencyMs: number;
-  readonly details?: Record<string, unknown>;
-}
-
-// 32-byte AES-256 data-encryption key, unwrapped and ready for local use.
-export type SubjectDek = Buffer;
-
-interface KmsAdapterBase {
-  /**
-   * Creates a fresh subject key. Throws KeyAlreadyExistsError when the
-   * subject already has one — including an erased tombstone: a shredded
-   * subject must never get a new key, or forget could be undone by
-   * re-encrypting under it.
-   */
-  createKey(subject: SubjectId, ctx: KmsContext): Promise<void>;
-
-  /**
-   * Erases the key material immediately; the tombstone row stays for the
-   * audit trail. Idempotent — repeat calls and unknown subjects are no-ops.
-   */
-  eraseKey(subject: SubjectId, ctx: KmsContext): Promise<void>;
-
-  /** Probe for boot + readiness. Throws when the backend is unreachable. */
-  health(): Promise<KmsHealth>;
-}
-
-// Backends that hand out the plaintext DEK (Pg, InMemory). Encrypt/decrypt
-// happens locally; DEKs are cacheable per request.
-export interface LocalKeyKmsAdapter extends KmsAdapterBase {
-  readonly capabilities: { readonly mode: "local-key" };
-
-  /**
-   * Throws KeyErasedError after eraseKey (callers render "[[erased]]"),
-   * KeyNotFoundError when the subject never had a key (typically a bug).
-   */
-  getKey(subject: SubjectId, ctx: KmsContext): Promise<SubjectDek>;
-}
-
-// Backends that never release key material (Vault transit, cloud KMS).
-// Every encrypt/decrypt is a round-trip; nothing is cacheable.
-export interface RemoteCryptoKmsAdapter extends KmsAdapterBase {
-  readonly capabilities: { readonly mode: "remote-crypto" };
-
-  encrypt(subject: SubjectId, plaintext: Uint8Array, ctx: KmsContext): Promise<Uint8Array>;
-
-  /** Same error contract as LocalKeyKmsAdapter.getKey. */
-  decrypt(subject: SubjectId, ciphertext: Uint8Array, ctx: KmsContext): Promise<Uint8Array>;
-}
-
-export type KmsAdapter = LocalKeyKmsAdapter | RemoteCryptoKmsAdapter;
-
-export function isLocalKeyKmsAdapter(adapter: KmsAdapter): adapter is LocalKeyKmsAdapter {
-  return adapter.capabilities.mode === "local-key";
-}

package/src/logger.ts

@@ -1,7 +0,0 @@
-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/multi-stream-apply-context-types.ts

@@ -1,52 +0,0 @@
-import type { DerivativesContext } from "./derivatives-types";
-import type { StoredEvent } from "./event-store-types";
-import type { KumikoEventTypeMap } from "./event-type-map";
-import type { Registry } from "./feature";
-import type { FileContext } from "./file-handle-types";
-import type { AppendEventFn, UnsafeAppendEventFn } from "./handlers";
-import type { SecretsContext } from "./secrets-types";
-
-// Minimal, read+write surface handed to a MultiStreamProjection's apply()
-// when it needs to produce follow-up events (saga / process-manager
-// pattern). Keeps the MSP feature-decoupled: applies don't reach into
-// handler-bridge (no query/write/writeAs), they just read the aggregate
-// stream and append new events — Marten's session scope for projections.
-//
-// TMap propagates the strict event-type-map (see HandlerContext). Default
-// matches the global KumikoEventTypeMap; runtime-pluggable callers route
-// through unsafeAppendEvent.
-export type MultiStreamApplyContext<TMap extends object = KumikoEventTypeMap> = {
-  // Append a domain event onto an aggregate stream in the CURRENT tx.
-  // Schema-validated, archive-guarded, stream-version derived. Metadata
-  // inherits from the triggering event (correlationId) + requestContext
-  // (causationId is already set to the triggering event.id by the
-  // dispatcher wrap). Strict against KumikoEventTypeMap — same contract
-  // as HandlerContext.appendEvent (compile-time-validated payload).
-  readonly appendEvent: AppendEventFn<TMap>;
-  // Escape hatch for runtime-pluggable events without compile-time
-  // augmentation. Same runtime semantics; type-surface is `payload: unknown`.
-  readonly unsafeAppendEvent: UnsafeAppendEventFn;
-  // Read an aggregate stream — useful when a saga needs to inspect the
-  // current state of a different aggregate before deciding what to emit.
-  readonly loadAggregate: (
-    aggregateId: string,
-    options?: { readonly asOf?: Temporal.Instant },
-  ) => Promise<readonly StoredEvent[]>;
-  // The app registry — same instance HandlerContext/JobContext expose. Lets
-  // an apply resolve extension-point usages (registry.getExtensionUsages),
-  // e.g. a provider-routed MSP picking a handler by payload discriminant.
-  readonly registry: Registry;
-  // Binary storage handle factory, mirrors AppContext.files. Present when
-  // the app booted with `files.storageProvider`; undefined otherwise.
-  // Post-processing MSPs (resize, EXIF-strip, virus-scan) read bytes via
-  // `ctx.files.ref(payload.storageKey).read()` and write derivates via
-  // `.derive("thumb").write(...)` — binaries never ride through events.
-  readonly files?: FileContext;
-  // Derive-on-first-use variants, mirrors AppContext.derivatives. Present
-  // exactly when `files` is — same file-foundation-provider precondition.
-  readonly derivatives?: DerivativesContext;
-  // Tenant-scoped secret reads for side-effect MSPs (e.g. step-dispatcher's
-  // webhook auth), audited via the read's own auditCtx. Present when the
-  // app booted with the secrets feature; undefined otherwise.
-  readonly secrets?: SecretsContext;
-};

package/src/nav-icon.ts

@@ -1,105 +0,0 @@
-// Closed vocabulary of nav and button icon keys. NavDefinition.icon,
-// ScreenNavSugar.icon, ConfigMask.icon and ButtonProps.icon/iconEnd are all
-// typed against this union, so an unregistered key is a compile error at the
-// r.nav()/r.screen()/config-mask/button call site instead of a silent
-// missing-icon at runtime.
-//
-// The renderer-web NAV_ICONS map (packages/renderer-web/src/icons.tsx) is
-// checked against this same union via `satisfies`, so the two can't drift —
-// add a key here only together with its lucide-react entry there, and vice
-// versa.
-//
-// Declared as a runtime tuple (not just a type) so callers that sit outside
-// this repo's `tsc --build` project graph (e.g. samples, external consumers
-// resolving from a stale published type) still get a runtime-checkable
-// vocabulary — the boot-validator's validateActionHasIcon checks a declared
-// icon against NAV_ICON_KEYS instead of trusting "not undefined".
-export const NAV_ICON_KEYS = [
-  "dashboard",
-  "layout-grid",
-  "book-open",
-  "clipboard-list",
-  "package",
-  "gauge",
-  "list",
-  "table",
-  "layers",
-  "building",
-  "calculator",
-  "wallet",
-  "coins",
-  "credit-card",
-  "piggy-bank",
-  "receipt",
-  "chart",
-  "bar-chart",
-  "trending",
-  "sparkles",
-  "wand",
-  "calendar",
-  "file",
-  "folder",
-  "folder-open",
-  "home",
-  "bell",
-  "shield",
-  "shield-check",
-  "send",
-  "settings",
-  "users",
-  "user",
-  "search",
-  "tag",
-  "key",
-  "link",
-  "palette",
-  "share",
-  "server",
-  "mail",
-  "lock",
-  "hash",
-  "download",
-  "upload",
-  "rocket",
-  "plus",
-  "languages",
-  "trash",
-  "x",
-  "check",
-  "arrow-left",
-  "arrow-right",
-  "copy",
-  "pencil",
-  "eye",
-  "eye-off",
-  "filter",
-  "refresh",
-  "more-horizontal",
-  "more-vertical",
-  "external-link",
-  "chevron-down",
-  "chevron-right",
-  "save",
-  "undo",
-  "archive",
-  "star",
-  "flag",
-  "clock",
-  "map-pin",
-  "phone",
-  "printer",
-  "alert-triangle",
-  "info",
-  "check-circle",
-  "x-circle",
-  "loader",
-  "mic",
-  "circle-stop",
-  "image",
-] as const;
-
-export type NavIconKey = (typeof NAV_ICON_KEYS)[number];
-
-// Alias kept because the union stopped being nav-only — actions and fields
-// (added on this branch) also key their icons against it.
-export type IconKey = NavIconKey;