@cosmicdrift/kumiko-framework 0.397.0 → 0.399.0

package/agents/api/types.md

@@ -0,0 +1,4962 @@
+<!-- Generated by `bun run gen:agent-docs` from the API entry points. Do not edit. -->
+
+# Referenced types
+
+Types that appear in the signatures of the entry points but are not exported by any of them. Use them to read option shapes; import only what an entry point exports.
+
+## packages/dev-server/src/setup-test-stack-from-features.ts
+
+```ts
+type SetupTestStackFromFeaturesOptions = Omit<TestStackOptions, "features"> & {
+  includeBundled?: boolean;
+  authOptions?: ComposeFeaturesOptions["authOptions"];
+  bundledLists?: ComposeFeaturesOptions["bundledLists"];
+  presets?: TestStackPreset[];
+};
+type TestStackPreset = "config" | "template-resolver";
+```
+
+## packages/framework/src/api/auth-middleware.ts
+
+```ts
+type AuthSessionCheckResult =
+  | AuthSessionStatus
+  | {
+    status: "live";
+    roles: string[];
+  }
+;
+type AuthSessionChecker = (sid: string, expectedUserId: string) => Promise<AuthSessionCheckResult>;
+type AuthSessionStatus = "live" | "revoked" | "expired" | "missing" | "blocked";
+type TokenVerifier = (rawToken: string) => Promise<SessionUser | null>;
+```
+
+## packages/framework/src/api/auth-routes-types.ts
+
+```ts
+type AccountUnlockConfig = {
+  requestHandler: string;
+  confirmHandler: string;
+};
+type AuthRoutesConfig = {
+  membershipQuery: string;
+  userQuery?: string;
+  loginHandler?: string;
+  loginErrorStatusMap?: Readonly<Record<string, number>>;
+  loginRateLimit?: LoginRateLimiter | null;
+  mfaVerifyHandler?: string;
+  switchTenantMfaGateHandler?: string;
+  mfaVerifyErrorStatusMap?: Readonly<Record<string, number>>;
+  mfaVerifyRateLimit?: LoginRateLimiter | null;
+  mfaPreauthEnableStartHandler?: string;
+  mfaPreauthEnableStartErrorStatusMap?: Readonly<Record<string, number>>;
+  mfaPreauthEnableStartRateLimit?: LoginRateLimiter | null;
+  mfaPreauthConfirmHandler?: string;
+  mfaPreauthConfirmErrorStatusMap?: Readonly<Record<string, number>>;
+  mfaPreauthConfirmRateLimit?: LoginRateLimiter | null;
+  sessionCreator?: SessionCreator;
+  sessionRevoker?: SessionRevoker;
+  sessionChecker?: SessionChecker;
+  tokenVerifier?: TokenVerifier;
+  patRateLimiter?: LoginRateLimiter;
+  resolveTenantLifecycleStatus?: TenantLifecycleStatusResolver;
+  passwordReset?: PasswordResetConfig;
+  emailVerification?: EmailVerificationConfig;
+  accountUnlock?: AccountUnlockConfig;
+  signup?: SignupConfig;
+  invite?: InviteConfig;
+  cookieSameSite?: "lax" | "strict";
+  cookieDomain?: string;
+  secureCookies?: boolean;
+  retiredCookieDomains?: string[];
+  allowedOrigins?: string[];
+  publicOrigin?: string;
+  unsafeSkipOriginCheck?: boolean;
+  trustedProxyHops?: number;
+  postAuthLanding?: PostAuthLandingResolver;
+  resolver?: ClientIpResolver;
+};
+type EmailVerificationConfig = {
+  requestHandler: string;
+  confirmHandler: string;
+};
+type InviteConfig = {
+  acceptHandler: string;
+  acceptWithLoginHandler: string;
+  signupCompleteHandler: string;
+  infoHandler?: string;
+};
+type LoginRateLimiter = {
+  check(key: string): Promise<boolean>;
+  reset(key: string): Promise<void>;
+};
+type PasswordResetConfig = {
+  requestHandler: string;
+  confirmHandler: string;
+};
+type SessionChecker = AuthSessionChecker;
+type SessionCreator = (user: SessionUser, meta: SessionMetadata) => Promise<string>;
+type SessionMetadata = {
+  ip: string;
+  userAgent: string;
+};
+type SessionRevoker = (sid: string) => Promise<void>;
+type SignupConfig = {
+  requestHandler: string;
+  confirmHandler: string;
+};
+```
+
+## packages/framework/src/api/client-ip.ts
+
+```ts
+type ClientIpHeaderSource = {
+  header: (name: string) => string | undefined;
+  socketAddress?: string;
+};
+type ClientIpResolver = {
+  resolve: (source: ClientIpHeaderSource) => string;
+};
+```
+
+## packages/framework/src/api/extra-route.ts
+
+```ts
+type AnonymousExtraRoute = {
+  method: HttpRouteMethod;
+  path: string;
+  entry: "anonymous";
+  handler: (c: Context<any, any>, deps: AnonymousExtraRouteDeps) => Response | Promise<Response>;
+};
+type AnonymousExtraRouteDeps = {
+  app: Hono<any, any>;
+  registry: Registry;
+  systemQuery: (type: string, payload: unknown, tenantId: TenantId) => Promise<unknown>;
+  write: (type: string, payload: unknown) => Promise<WriteResult>; // Runs as the session the /api chain resolved for this request — anonymous when no token is sent, the authenticated user otherwise.
+  clientIp: string; // Resolved by the server's single trustedProxyHops-aware resolver — never read X-Forwarded-For yourself.
+};
+type ExtraRouteDefinition = AnonymousExtraRoute | UserExtraRoute | SignatureExtraRoute<unknown>;
+type RoleDispatchArgs = SystemDispatchArgs & {
+  roles: string[];
+};
+type SignatureExtraRoute<TVerified> = {
+  method: HttpRouteMethod;
+  path: string;
+  entry: "signature";
+  verify: (request: SignatureExtraRouteVerifyRequest, deps: SignatureExtraRouteVerifyDeps) => Promise<TVerified>;
+  handler: (c: Context<any, any>, verified: TVerified, deps: SignatureExtraRouteDeps) => Response | Promise<Response>;
+};
+type SignatureExtraRouteDeps = {
+  app: Hono<any, any>;
+  registry: Registry;
+  secrets?: SecretsContext;
+  systemQuery: (type: string, payload: unknown, tenantId: TenantId) => Promise<unknown>;
+  dispatchSystemWrite: (args: SystemDispatchArgs) => Promise<WriteResult>; // Privilege scope: SystemAdmin of the target tenant, WITHOUT the route's access check — only reachable because verify() has already proven the caller's authenticity (signature, HMAC state, etc.).
+  dispatchSystemQuery: (args: SystemDispatchArgs) => Promise<unknown>;
+  dispatchWriteAs: (args: RoleDispatchArgs) => Promise<WriteResult>; // Same trust as dispatchSystemWrite, but runs as the tenant's system user with the "system" role plus exactly `roles` (no SystemAdmin), so the write passes app-role access checks.
+};
+type SignatureExtraRouteVerifyDeps = {
+  registry: Registry;
+  secrets?: SecretsContext;
+};
+type SignatureExtraRouteVerifyRequest = {
+  rawBody: string;
+  headers: Readonly<Record<string, string>>; // Lowercase header names — Hono/undici normalize incoming headers to lowercase, verify() must not have to re-normalize per provider.
+  params: Readonly<Record<string, string>>;
+  query: Readonly<Record<string, string>>;
+};
+type SystemDispatchArgs = {
+  handlerQn: string;
+  payload: unknown;
+  tenantId: TenantId;
+};
+type UserExtraRoute = {
+  method: HttpRouteMethod;
+  path: string;
+  entry: "user";
+  handler: (c: Context<any, any>, deps: UserExtraRouteDeps) => Response | Promise<Response>;
+};
+type UserExtraRouteDeps = {
+  app: Hono<any, any>;
+  registry: Registry;
+  user: SessionUser;
+  query: (type: string, payload: unknown) => Promise<unknown>;
+  write: (type: string, payload: unknown) => Promise<WriteResult>;
+};
+```
+
+## packages/framework/src/api/jwt.ts
+
+```ts
+type JwtHelper = {
+  sign(user: SessionUser): Promise<string>;
+  verify(token: string): Promise<JwtPayload>;
+  ttlSeconds: number;
+};
+type JwtPayload = {
+  sub: string;
+  tenantId: TenantId;
+  roles: string[];
+  timezone?: string;
+  locale?: string;
+  claims?: Record<string, unknown>;
+  jti?: string;
+  exp?: number;
+};
+```
+
+## packages/framework/src/api/post-auth-landing.ts
+
+```ts
+type PostAuthLandingArgs = {
+  flow: PostAuthLandingFlow;
+  roles: string[];
+  tenantId: string;
+  tenantKey?: string;
+  handover?: {
+    entityType: string;
+    id: string;
+  };
+};
+type PostAuthLandingFlow = "login" | "signup" | "invite";
+type PostAuthLandingResolver = (args: PostAuthLandingArgs) => string | undefined;
+```
+
+## packages/framework/src/api/sse-broker.ts
+
+```ts
+type AccessInvalidationCredential = {
+  sid?: string;
+  patTokenId?: string;
+};
+type AccessInvalidationScope =
+  | {
+    kind: "user";
+  }
+  | {
+    kind: "all-except-session";
+    keptSessionId: string;
+  }
+  | {
+    kind: "sessions";
+    sessionIds: string[];
+  }
+  | {
+    kind: "pat-tokens";
+    tokenIds: string[];
+  }
+;
+type SseBroker = {
+  addClient(channel: string, send: (event: SseEvent) => void, close: () => void): string;
+  removeClient(channel: string, clientId: string): void;
+  pushToChannel(channel: string, event: SseEvent): void | Promise<void>;
+  getClientCount(channel: string): number;
+  getTotalClientCount(): number;
+  subscribeAccessInvalidation(userId: string, onInvalidate: () => void, credential?: AccessInvalidationCredential): () => void;
+  publishAccessInvalidation(userId: string, scope?: AccessInvalidationScope): void | Promise<void>;
+};
+type SseEvent = {
+  type: string;
+  data: Record<string, unknown>;
+};
+```
+
+## packages/framework/src/db/apply-entity-event.ts
+
+```ts
+type ApplyResult =
+  | {
+    kind: "applied";
+    verb: AutoVerb;
+    row: DbRow | null;
+  }
+  | {
+    kind: "skipped";
+  }
+;
+type AutoVerb = "created" | "updated" | "deleted" | "restored" | "forgotten";
+type Table = TableColumns;
+```
+
+## packages/framework/src/db/connection.ts
+
+```ts
+type BunSqlOptions = Bun.SQL.PostgresOrMySQLOptions;
+type CreateDbConnectionOptions = DbConnectionOptions & {
+  url: string;
+  rowLevelSecurity?: RowLevelSecurityMode;
+};
+type DbConnectionHandle = {
+  db: DbConnection;
+  client: PgClient;
+  listenClient: PgListenClient;
+  close: () => Promise<void>;
+};
+type DbConnectionOptions = {
+  maxConnections?: number;
+  idleTimeoutSeconds?: number;
+  connectTimeoutSeconds?: number;
+  closeTimeoutSeconds?: number;
+  ssl?: BunSqlOptions["tls"];
+  statementTimeoutMs?: number;
+  idleInTransactionSessionTimeoutMs?: number;
+  lockTimeoutMs?: number;
+};
+```
+
+## packages/framework/src/db/cursor.ts
+
+```ts
+type DecodedKeysetCursor = {
+  id: string;
+  sortValue: string | null | undefined;
+};
+```
+
+## packages/framework/src/db/dialect.ts
+
+```ts
+type ColumnBuilder<TValue = unknown> = {
+  __column: true;
+  finalise: () => ColumnFinal;
+  notNull(): ColumnBuilder<TValue>;
+  primaryKey(): ColumnBuilder<TValue>;
+  default(value: TValue | SqlExpression | unknown[] | number | string | boolean | null): ColumnBuilder<TValue>;
+  defaultRandom(): ColumnBuilder<TValue>;
+  defaultNow(): ColumnBuilder<TValue>;
+  generatedAlwaysAsIdentity(): ColumnBuilder<TValue>;
+  unique(name?: string): ColumnBuilder<TValue>;
+  $type<T>(): ColumnBuilder<T>;
+  $onUpdate(fn: () => unknown): ColumnBuilder<TValue>;
+};
+type ColumnFinal = {
+  sqlName: string;
+  pgType: PgType;
+  notNull: boolean;
+  primaryKey: boolean;
+  unique: boolean;
+  identity: boolean;
+  defaultSql?: string;
+  bigintJsMode?: "number" | "bigint";
+};
+type ColumnMap = Record<string, ColumnBuilder<unknown>>;
+type IndexBuilder = {
+  __index: true;
+  on(...cols: ColumnHandle[]): IndexBuilderWithCols;
+};
+type IndexBuilderWithCols = {
+  __index: true;
+  name: string;
+  unique: boolean;
+  columns: string[];
+  where(expr: SqlExpression): IndexBuilderWithCols;
+  whereSql?: string;
+};
+type IndexOrPk = IndexBuilderWithCols | PrimaryKeyDescriptor;
+type PrimaryKeyDescriptor = {
+  __pk: true;
+  columns: string[];
+  name?: string;
+};
+type SqlExpression = {
+  kind: "sql-expr";
+  text: string;
+  params: unknown[];
+  [SQL_EXPR_BRAND]: true;
+};
+type TableColumns<_T = unknown> = SchemaTable;
+```
+
+## packages/framework/src/db/eagerload.ts
+
+```ts
+type EagerLoadEntityResolver = (entityName: string) => EntityDefinition | undefined;
+type EagerLoadViewer = {
+  user: SessionUser;
+  parentVisibility: ParentVisibilityOption;
+};
+```
+
+## packages/framework/src/db/event-store-executor-context.ts
+
+```ts
+type EntityLifecycleVerb = "created" | "updated" | "deleted" | "restored" | "forgotten";
+type Table = TableColumns;
+```
+
+## packages/framework/src/db/event-store-executor.ts
+
+```ts
+type EventStoreExecutorOptions = {
+  searchAdapter?: SearchAdapter;
+  entityName: string;
+  entityCache?: EntityCache;
+  encryption?: EnvelopeCipher; // Override the boot-injected cipher for fields marked `encrypted: true`.
+  kms?: LocalKeyKmsAdapter; // Override the boot-injected subject KMS for pii-annotated fields.
+};
+```
+
+## packages/framework/src/db/feature-table-sources.ts
+
+```ts
+type FeatureTableSource = {
+  table: unknown;
+  origin: string;
+};
+```
+
+## packages/framework/src/db/list-aggregate-labels.ts
+
+```ts
+type AggregateRequest = Parameters<EventStoreExecutor["aggregate"]>[0];
+type LabelDeps = {
+  entity: EntityDefinition;
+  resolveEntity: EagerLoadEntityResolver;
+  viewer: EagerLoadViewer;
+};
+```
+
+## packages/framework/src/db/located-timestamp.ts
+
+```ts
+type LocatedTimestampRead = { // Shape of a single rehydrated locatedTimestamp field.
+  at: string;
+  tz: string;
+  utc: string;
+};
+```
+
+## packages/framework/src/db/migrate-change-render.ts
+
+```ts
+type ColumnChange = {
+  name: string;
+  nullabilityChanged?: {
+    from: boolean;
+    to: boolean;
+  };
+  defaultChanged?: {
+    from: string | undefined;
+    to: string | undefined;
+  };
+  typeChanged?: {
+    from: string;
+    to: string;
+  };
+};
+type IndexChange = {
+  name: string;
+  columnsChanged?: {
+    from: string[];
+    to: string[];
+  };
+  uniqueChanged?: {
+    from: boolean;
+    to: boolean;
+  };
+  whereSqlChanged?: {
+    from: string | undefined;
+    to: string | undefined;
+  };
+  needsManualWhereChanged?: {
+    from: boolean;
+    to: boolean;
+  };
+};
+```
+
+## packages/framework/src/db/migrate-generator.ts
+
+```ts
+type GenerateMigrationInput = {
+  metas: EntityTableMeta[];
+  prevSnapshot: Snapshot | null;
+  name: string;
+  sequenceNumber: number;
+  priorMigrationsSql?: string[]; // Raw SQL of all earlier migrations, in order — lets the generator decide whether a retired framework table still needs its executable drop.
+  rowLevelSecurity?: RowLevelSecurityMode;
+};
+type GenerateMigrationOutput = {
+  filename: string;
+  sqlContent: string;
+  snapshot: Snapshot;
+  diff: SchemaDiff;
+  retiredDrops: RetiredFrameworkTable[];
+  rowLevelSecurityChanges: RowLevelSecurityChange[];
+};
+type SchemaDiff = {
+  newTables: EntityTableMeta[];
+  droppedTables: string[];
+  changedTables: TableDiff[];
+};
+type Snapshot = {
+  version: typeof SNAPSHOT_VERSION;
+  generatedAt?: string;
+  tables: EntityTableMeta[];
+  rowLevelSecurity?: Readonly<Record<string, TableRowLevelSecurity>>;
+};
+type TableDiff = {
+  tableName: string;
+  newColumns: ColumnMeta[];
+  droppedColumns: string[];
+  changedColumns: ColumnChange[];
+  newIndexes: IndexMeta[];
+  droppedIndexes: string[];
+  changedIndexes: IndexChange[];
+  primaryKeyChanged?: PrimaryKeyChange;
+  nextMeta: EntityTableMeta;
+};
+```
+
+## packages/framework/src/db/migrate-primary-key.ts
+
+```ts
+type PrimaryKey = {
+  columns: string[];
+  constraintName: string;
+};
+type PrimaryKeyChange = {
+  from: PrimaryKey;
+  to: PrimaryKey;
+};
+```
+
+## packages/framework/src/db/migrate-rls-diff.ts
+
+```ts
+type RowLevelSecurityChange =
+  | {
+    kind: "enable";
+    tableName: string;
+    next: TableRowLevelSecurity;
+    previous?: TableRowLevelSecurity;
+  }
+  | {
+    kind: "disable";
+    tableName: string;
+    previous: TableRowLevelSecurity;
+  }
+;
+```
+
+## packages/framework/src/db/migrate-runner.ts
+
+```ts
+type ApplyResult = {
+  applied: string[];
+  skipped: string[];
+};
+```
+
+## packages/framework/src/db/pg-error.ts
+
+```ts
+type PgErrorInfo = {
+  code: string | undefined;
+  constraint_name: string | undefined;
+};
+```
+
+## packages/framework/src/db/queries/backfill-pii.ts
+
+```ts
+type PiiBackfillBatchOptions = PiiBackfillOptions & {
+  afterEventId?: bigint | string;
+  eventIds?: string[];
+  scanCache?: PiiBackfillScanCache;
+};
+type PiiBackfillBatchResult = PiiBackfillResult & {
+  lastEventId: string | null;
+  scannedAll: boolean;
+  firstFailedEventId: string | null;
+  touchedAggregateTypes: string[];
+  touchedEventTypes: string[];
+};
+type PiiBackfillFailure = {
+  eventId: string;
+  reason: string;
+};
+type PiiBackfillOptions = {
+  batchSize?: number;
+  dryRun?: boolean;
+  resolveOwnerFromProjection?: boolean;
+  eraseUnresolvableSubjects?: boolean;
+  rekeyTenantKeyedOwnerFields?: boolean;
+};
+type PiiBackfillResult = {
+  scannedEvents: number;
+  updatedEvents: number;
+  encryptedFields: number;
+  erasedFields: number;
+  rekeyedFields: number;
+  ownerFromProjection: number;
+  erasedUnresolvable: number;
+  deletedSnapshots: number;
+  failures: PiiBackfillFailure[];
+};
+type PiiBackfillScanCache = {
+  forgottenAggregates?: ReadonlySet<string>;
+  destroyedTenants?: ReadonlySet<string>;
+};
+```
+
+## packages/framework/src/db/queries/event-store-orphan-rows.ts
+
+```ts
+type DeleteRowsWithoutReplayableStreamArgs = {
+  table: unknown;
+  ids: string[];
+  tenantId?: TenantId;
+};
+```
+
+## packages/framework/src/db/queries/postgres-array-literal.ts
+
+```ts
+type PostgresArrayElement = string | number | bigint | null;
+```
+
+## packages/framework/src/db/query.ts
+
+```ts
+type AnyDb = DbRunner | unknown;
+type AnyRow = any;
+type DeleteManyBatchedOptions = {
+  limit: number;
+  maxBatches?: number;
+  idColumn?: string; // Row id field for the LIMIT subquery.
+};
+type DeleteManyBatchedResult = {
+  deleted: number;
+  batches: number;
+};
+type IncrementCounterOptions = {
+  conflictKeys?: string[];
+  set?: Record<string, unknown>; // Extra SET clauses on conflict (e.g. lastUpdatedAt: sql\`NOW()\`).
+};
+type InnerJoinRow<TLeft, TRight> = {
+  left: TLeft;
+  right: TRight;
+};
+type InnerJoinSpec = {
+  left: TableLike;
+  right: TableLike;
+  on: [ JoinColumnPair, ...JoinColumnPair[] ];
+  leftWhere?: WhereObject;
+  rightWhere?: WhereObject;
+  leftFields?: string[]; // Fields to return per side; default: all columns of `left`, none of `right`.
+  rightFields?: string[];
+  limit?: number;
+};
+type InsertOnConflictDoNothingOptions = {
+  conflictKeys?: string[];
+};
+type JoinColumnPair = {
+  left: string;
+  right: string;
+};
+type RawClient = {
+  unsafe: <TRow = unknown>(sql: string, params?: unknown[]) => Promise<TRow[]>;
+  begin?: <T>(fn: (tx: DbTx) => Promise<T>) => Promise<T>;
+  savepoint?: <T>(fn: (sp: unknown) => Promise<T>) => Promise<T>;
+  release?: unknown;
+  reserve?: () => Promise<ReservedClient>;
+};
+type ReservedClient = {
+  unsafe: RawClient["unsafe"];
+  release: () => unknown;
+};
+type TableLike = EntityTableMeta | any;
+type UpsertOnConflictOptions = {
+  conflictKeys: string[];
+  update?: Record<string, unknown>; // Columns to set on conflict.
+};
+```
+
+## packages/framework/src/db/render-ddl.ts
+
+```ts
+type RenderDdlOptions = {
+  rowLevelSecurity?: RowLevelSecurityMode;
+};
+```
+
+## packages/framework/src/db/render-rls-ddl.ts
+
+```ts
+type RowLevelSecurityPolicy = {
+  name: string;
+  command: (typeof POLICY_COMMANDS)[number];
+  kind: (typeof POLICY_KINDS)[number];
+  rolesSql: string;
+  using?: string;
+  withCheck?: string;
+};
+type TableRowLevelSecurity = {
+  policies: RowLevelSecurityPolicy[];
+};
+```
+
+## packages/framework/src/db/retired-framework-tables.ts
+
+```ts
+type RetiredFrameworkTable = {
+  tableName: string;
+  sinceVersion: string;
+  explanation: string;
+};
+```
+
+## packages/framework/src/db/row-level-security-boot-check.ts
+
+```ts
+type RowLevelSecurityCheckScope = "database" | "declared tables";
+```
+
+## packages/framework/src/db/table-builder.ts
+
+```ts
+type BaseColumnsType<E extends EntityDefinition> = {
+  id: E extends { idType: "serial"; } ? Col<number> : Col<string>;
+  tenantId: Col<string>;
+  version: Col<number>;
+  insertedAt: Col<Temporal.Instant>;
+  modifiedAt: NullCol<Temporal.Instant>;
+  insertedById: NullCol<string>;
+  modifiedById: NullCol<string>;
+};
+type BlindIndexColumnForField<K extends string, F extends FieldDefinition> = F extends { type: "text"; lookupable: true; } ? { [P in `${K}Bidx`]: NullCol<string>; } : unknown;
+type BuildEntityTableOptions = {
+  featureName?: string;
+  relations?: EntityRelations;
+};
+type Col<T> = ColumnHandle & {
+  __notNull: true;
+  __value?: T;
+};
+type ColumnValue<C> = C extends { __notNull: true; __value?: infer T; } ? T : C extends { __notNull: false; __value?: infer T; } ? T | null : unknown;
+type ColumnsForEntity<F extends FieldsMap> = UnionToIntersection<{ [K in keyof F & string]: ColumnsForField<K, F[K]>; }[keyof F & string]>;
+type ColumnsForField<K extends string, F extends FieldDefinition> = ValueColumnsForField<K, F> & BlindIndexColumnForField<K, F>;
+type CompoundRowField<K extends string, V, F> = F extends { required: true; } ? { [P in K]: V; } : { [P in K]?: V; };
+type EntityRow<E extends EntityDefinition = EntityDefinition> = string extends keyof E["fields"] ? Record<string, unknown> : Flatten<RowOfColumns<BaseColumnsType<E>> & SoftDeleteRow<E> & RowForFields<E["fields"]>>; // The row `executor.list()` / `executor.detail()` return for entity `E`.
+type EntityTableTenancy<E extends EntityDefinition> = [ NonNullable<E["tenancy"]> ] extends [ never ] ? "tenant" : [ NonNullable<E["tenancy"]> ] extends [ "global" ] ? "global" : "tenant";
+type Flatten<T> = { [K in keyof T]: T[K]; } & {
+};
+type NullCol<T> = ColumnHandle & {
+  __notNull: false;
+  __value?: T;
+};
+type RowForField<K extends string, F extends FieldDefinition> = F extends { type: "money"; } ? CompoundRowField<K, MoneyRead, F> : F extends { type: "locatedTimestamp"; } ? CompoundRowField<K, LocatedTimestampRead, F> : [ ValueColumnsForField<K, F> ] extends [ never ] ? { [P in K]: unknown; } : RowOfColumns<ValueColumnsForField<K, F>>;
+type RowForFields<F extends FieldsMap> = UnionToIntersection<{ [K in keyof F & string]: RowForField<K, F[K]>; }[keyof F & string]>;
+type RowOfColumns<C> = { [K in keyof C]: ColumnValue<C[K]>; };
+type SoftDeleteColumnsType = {
+  isDeleted: Col<boolean>;
+  deletedAt: NullCol<Temporal.Instant>;
+  deletedById: NullCol<string>;
+};
+type SoftDeleteRow<E extends EntityDefinition> = E["softDelete"] extends true ? RowOfColumns<SoftDeleteColumnsType> : [ E["softDelete"] ] extends [ false | undefined ] ? unknown : Partial<RowOfColumns<SoftDeleteColumnsType>>;
+type UnionToIntersection<U> = (U extends unknown ? (k: U) => void : never) extends (k: infer I) => void ? I : never;
+type ValueColumnsForField<K extends string, F extends FieldDefinition> = F extends { type: "text" | "longText" | "select" | "tz"; } ? F extends { required: true; } ? { [P in K]: Col<string>; } : { [P in K]: NullCol<string>; } : F extends { type: "boolean"; } ? F extends { default: boolean; } | { required: true; } ? { [P in K]: Col<boolean>; } : { [P in K]: NullCol<boolean>; } : F extends { type: "multiSelect"; } ? { [P in K]: Col<string[]>; } : F extends { type: "number"; } ? F extends { required: true; } ? { [P in K]: Col<number>; } : { [P in K]…;
+```
+
+## packages/framework/src/db/tenant-db.ts
+
+```ts
+type CreateTenantDbOptions = ({ mode?: "tenant"; reason?: undefined; } | { mode: "system"; reason: string; }) & {
+  db: DbRunner;
+  tenantId: TenantId;
+  tracer?: Tracer;
+  meter?: Meter;
+  signal?: AbortSignal;
+  grants?: TenantDbGrants;
+};
+type PersonalDataGate = (tableName: string, keys: string[], entity?: EntityDefinition) => void;
+type TenantDbGrants = {
+  globalWrites?: EscapeHatchDeclaration;
+  unsafeRaw?: EscapeHatchDeclaration;
+  report?: EscapeHatchReporter;
+  memberReadOnly?: boolean;
+  personalDataGate?: PersonalDataGate;
+  projectionRegistry?: Registry;
+  writesDeniedReason?: string;
+};
+```
+
+## packages/framework/src/derivatives/derivatives-context.ts
+
+```ts
+type OverlayResolverArgs = {
+  entityId: string;
+  tenantId: TenantId;
+  fieldName: string;
+  dataToken: string;
+};
+type OverlayResolverPlugin = {
+  resolve: (args: OverlayResolverArgs) => string | Promise<string>;
+};
+```
+
+## packages/framework/src/engine/boot-validator/card-meta-overflow.ts
+
+```ts
+type CardMetaOverflow = {
+  feature: string;
+  screen: string;
+  location?: string;
+  count: number;
+  fields: string[];
+};
+```
+
+## packages/framework/src/engine/build-app-schema.ts
+
+```ts
+type BuildAppSchemaOptions = {
+  authoringWarnings?: boolean; // Dev-server authoring hints (Settings-Hub placement).
+  searchAdapterMissing?: boolean; // Forwarded onto every FeatureSchema.searchAdapterMissing.
+};
+```
+
+## packages/framework/src/engine/build-config-feature-schema.ts
+
+```ts
+type ConfigFeatureSchema = {
+  screens: ScreenDefinition[];
+  navs: NavDefinition[];
+  workspace?: WorkspaceSchema;
+  translations?: TranslationKeys;
+};
+```
+
+## packages/framework/src/engine/config-helpers.ts
+
+```ts
+type ConfigKeyOptions<T extends ConfigKeyType> = {
+  write?: string[];
+  read?: string[];
+  default?: ConfigValue<T>;
+  encrypted?: boolean;
+  piiEncrypted?: T extends "text" ? boolean : never;
+  options?: string[];
+  optionsQuery?: T extends "select" ? string : never;
+  optionsQueryPayload?: T extends "select" ? OptionsQueryPayload : never;
+  bounds?: T extends "number" ? ConfigBounds : never;
+  pattern?: T extends "text" ? { regex: string; flags?: string; } : never;
+  computed?: ConfigComputedFn<T>;
+  validate?: ConfigValidateFn<T>;
+  allowPerRequest?: T extends "text" ? never : boolean;
+  required?: boolean;
+  env?: string;
+  inheritedToTenant?: boolean;
+  backing?: ConfigBacking;
+  mask?: ConfigMask;
+  group?: string;
+};
+```
+
+## packages/framework/src/engine/define-feature.ts
+
+```ts
+type DefineFeatureSettings = {
+  dedupeOptions?: Readonly<Record<string, unknown>>;
+};
+```
+
+## packages/framework/src/engine/define-roles.ts
+
+```ts
+type RoleMap<T extends string[]> = { [K in T[number]]: K; };
+```
+
+## packages/framework/src/engine/define-workflow.ts
+
+```ts
+type WorkflowInput<TPayload = unknown, TData = unknown, TAwaits extends Record<string, string> = Record<string, string>> = { // Input shape for defineWorkflow() — the user-facing API.
+  name: string;
+  trigger: WorkflowTrigger;
+  awaits?: TAwaits;
+  steps: PipelineDef<TPayload, TData, { [K in keyof TAwaits]: AwaitedEventType; }>;
+  idempotencyKey?: string | ((event: WriteEvent<TPayload>) => string);
+  onError?: PipelineDef<unknown>;
+};
+type WorkflowTrigger = // Trigger configuration for a workflow.
+  | {
+    kind: "event";
+    eventType: string;
+    filter?: (event: WriteEvent) => boolean;
+  }
+  | {
+    kind: "cron";
+    schedule: string;
+  }
+  | {
+    kind: "webhook";
+    path: string;
+  }
+;
+```
+
+## packages/framework/src/engine/event-helpers.ts
+
+```ts
+type EmitCtx = {
+  events: Pick<HandlerContext["events"], "unsafeAppend">;
+};
+```
+
+## packages/framework/src/engine/extension-names.ts
+
+```ts
+interface KumikoExtensionOptionsMap {
+  [EXT_TENANT_DATA]: TenantDataExtensionHooks;
+  [EXT_USER_DATA]: UserDataExtensionOptions;
+  [EXT_FILE_PROVIDER]: FileProviderPlugin;
+  [EXT_DERIVATIVE_RENDERER]: DerivativeRendererPlugin;
+  [EXT_DERIVATIVE_OVERLAY_RESOLVER]: OverlayResolverPlugin;
+  [EXT_PRINCIPAL_STATUS]: PrincipalStatusPlugin;
+  [EXT_TENANT_LIFECYCLE_STATUS]: TenantLifecycleStatusPlugin;
+  [EXT_ASSIGNABLE_ROLE]: {
+    assignableFrom?: AssignableFromRole;
+  };
+  [EXT_STORAGE_PROVIDER]: TenantResourceExtensionHooks;
+  [EXT_SEARCH_ADAPTER]: TenantResourceExtensionHooks;
+  [EXT_EXTERNAL_RESOURCE]: TenantResourceExtensionHooks;
+  [EXT_INFRA_RESOURCE]: TenantResourceExtensionHooks;
+  [TENANT_TIER_RESOLVER_EXT]: TierResolverPlugin;
+}
+```
+
+## packages/framework/src/engine/extensions/tenant-data.ts
+
+```ts
+interface TenantDataExtensionHooks {
+  destroy: TenantDataDestroyHook;
+}
+```
+
+## packages/framework/src/engine/extensions/tenant-resource.ts
+
+```ts
+interface TenantResourceExtensionHooks {
+  destroyTenant: TenantResourceDestroyHook;
+}
+```
+
+## packages/framework/src/engine/extensions/user-data.ts
+
+```ts
+type UserDataDeleteHookResult = // Forget hook: deletes or anonymizes entity rows belonging to a user.
+  | void
+  | {
+    status: "ok";
+  }
+  | {
+    status: "incomplete";
+    reason: string;
+  }
+;
+type UserDataExtensionOptions = ({ export: UserDataExportHook; delete?: UserDataDeleteHook; } | { export?: UserDataExportHook; delete: UserDataDeleteHook; }) & {
+  order?: number;
+};
+type UserId = string;
+```
+
+## packages/framework/src/engine/feature-changelog.ts
+
+```ts
+type ChangelogType = (typeof CHANGELOG_TYPES)[number];
+type FeatureChangelog = {
+  feature: string;
+  entries: ChangelogEntry[];
+};
+```
+
+## packages/framework/src/engine/feature-manifest.ts
+
+```ts
+type BuildManifestOptions = {
+  source: string; // Description of the manifest's origin, included unchanged in the JSON.
+  featureNames?: ReadonlySet<string>; // Emit only these features (e.g. the 16 enterprise features from a Registry that also mounted their bundled requirements).
+  tier?: string; // Tags each feature and the top-level manifest (e.g. "enterprise").
+};
+```
+
+## packages/framework/src/engine/handler-field-references.ts
+
+```ts
+type HandlerFieldReference = {
+  entity: string;
+  by: string | undefined;
+  multiple: boolean;
+};
+```
+
+## packages/framework/src/engine/paged-list.ts
+
+```ts
+type PagedListRequest<TSortField extends string> = {
+  limit: number;
+  offset?: number | undefined;
+  search?: string | undefined;
+  sort?: TSortField | undefined;
+  sortDirection?: "asc" | "desc" | undefined;
+  totalCount?: boolean | undefined;
+};
+type PagedListRowValue = string | number | boolean | null;
+```
+
+## packages/framework/src/engine/qualified-name.ts
+
+```ts
+type ParsedQn = {
+  scope: string;
+  type: string;
+  name: string;
+};
+type QnType = string;
+```
+
+## packages/framework/src/engine/role-assignment.ts
+
+```ts
+type AssignableFromRole = (typeof ASSIGNABLE_FROM_ROLE_LIST)[number];
+```
+
+## packages/framework/src/engine/run-pipeline.ts
+
+```ts
+type StepListOutcome =
+  | {
+    kind: "return";
+    result: WriteResult<unknown>;
+  }
+  | {
+    kind: "suspended";
+    stepIndex: number;
+  }
+  | {
+    kind: "exhausted";
+  }
+;
+```
+
+## packages/framework/src/engine/screen-helpers.ts
+
+```ts
+type FieldsOrGroupsSection = { // Structural reader contract for every section that can carry `fields` and/or `groups`: the `EditFieldsSection` union members and `EditWriteFormSection` all assign without narrowing.
+  fields?: EditFieldSpec[];
+  groups?: { title: string; fields: EditFieldSpec[]; }[];
+};
+type SelectOptionRules = Pick<SelectFieldDef, "options" | "conditionalOptions">;
+type UnavailableSelectOption = {
+  field: string;
+  value: string;
+  allowed: string[];
+};
+```
+
+## packages/framework/src/errors/classes.ts
+
+```ts
+type RateLimitDetails = {
+  bucket: string;
+  limit: number;
+  windowSeconds: number;
+  remaining: number;
+  retryAfterSeconds: number;
+  resetAt: string;
+};
+type UnconfiguredDetails = {
+  feature: string;
+  key: string;
+  hint?: string;
+};
+type UniqueViolationDetails = {
+  entityName: string;
+  constraintName?: string;
+};
+type UnprocessableOpts = Pick<ErrorOpts, "i18nKey" | "i18nParams" | "cause" | "message"> & {
+  details?: Readonly<Record<string, unknown>> & { reason?: never; };
+};
+type ValidationDetails = {
+  fields: FieldIssue[];
+};
+type VersionConflictDetails = {
+  entityId: number | string;
+  expectedVersion: number;
+  currentVersion: number;
+};
+```
+
+## packages/framework/src/errors/kumiko-error.ts
+
+```ts
+type ErrorCtorInput = {
+  message: string;
+  i18nKey: string;
+  i18nParams?: Readonly<Record<string, unknown>>;
+  details?: unknown;
+  cause?: Error;
+  retryAfterSeconds?: number;
+};
+type ErrorOpts = {
+  message?: string;
+  i18nKey?: string;
+  i18nParams?: Readonly<Record<string, unknown>>;
+  details?: unknown;
+  cause?: Error;
+};
+```
+
+## packages/framework/src/event-store/archive.ts
+
+```ts
+type ArchiveStreamArgs = {
+  tenantId: TenantId;
+  aggregateId: string;
+  aggregateType: string;
+  archivedBy: string;
+  reason?: string;
+};
+```
+
+## packages/framework/src/event-store/event-store.ts
+
+```ts
+type EventToAppend = {
+  aggregateId: string;
+  aggregateType: string;
+  tenantId: TenantId;
+  expectedVersion: number;
+  type: string;
+  eventVersion?: number;
+  payload: Record<string, unknown>;
+  metadata: EventMetadata;
+};
+```
+
+## packages/framework/src/event-store/provenance-append.ts
+
+```ts
+type ProvenanceEventInput = {
+  aggregateId: string;
+  aggregateType: string;
+  tenantId: TenantId;
+  expectedVersion: number | "current";
+  type: string;
+  payload: Record<string, unknown>;
+  metadata: EventMetadata;
+};
+```
+
+## packages/framework/src/event-store/tenant-db-append.ts
+
+```ts
+type AppendEventInTenantDbOptions = {
+  registry?: Registry;
+};
+```
+
+## packages/framework/src/event-store/transfer.ts
+
+```ts
+type TransferAggregateStreamsArgs = {
+  sourceTenantId: TenantId;
+  destinationTenantId: TenantId;
+  aggregateType: string;
+  aggregateIds: string[];
+  transferredBy: string;
+};
+```
+
+## packages/framework/src/event-store/upcaster.ts
+
+```ts
+type EventUpcasters = ReadonlyMap<string, { currentVersion: number; chain: ReadonlyMap<number, EventUpcastFn>; }>;
+```
+
+## packages/framework/src/files/provider-resolver.ts
+
+```ts
+type FileProviderContext = { // Narrow surface type for provider plugins.
+  config?: ConfigAccessor;
+  registry?: Registry;
+  secrets: SecretsContext | undefined;
+  auditUserId?: string | undefined;
+};
+type FileProviderPlugin = { // File-Storage-Plugin contract.
+  build: (ctx: FileProviderContext, tenantId: string) => Promise<FileStorageProvider>;
+};
+```
+
+## packages/framework/src/jobs/job-runner-types.ts
+
+```ts
+type JobDroppedMeta = {
+  tenantId: string;
+};
+type JobLogEntry = {
+  level: "info" | "warn" | "error";
+  message: string;
+  timestamp: Temporal.Instant;
+};
+type JobMeta = {
+  triggeredById?: string | undefined;
+  payload?: string | undefined;
+  attempt?: number | undefined;
+  priority?: number | undefined;
+  jobId?: string | undefined;
+  tenantVisibleRun?: { tenantId: string; subject: string | null; } | undefined;
+};
+type JobOutcomeMeta = {
+  tenantId: string;
+  finalAttempt: boolean;
+  tenantVisible?: { subject: string | null; messageKey: string | null; } | undefined;
+  tenantVisibleRun?: { subject: string | null; } | undefined;
+};
+type JobQueuedMeta = {
+  tenantId: string;
+  subject: string | null;
+  jobCreatedAtMs: number;
+};
+type JobRunner = {
+  start(): Promise<void>;
+  stop(): Promise<void>;
+  dispatch(jobName: string, payload?: Record<string, unknown>, meta?: JobMeta): Promise<string>;
+  handleEvent(eventName: string, payload: Record<string, unknown>, user?: SessionUser, triggerEvent?: JobTriggerEvent): Promise<void>;
+  handleCatchUpEvent(jobName: string, eventName: string, payload: Record<string, unknown>, user: SessionUser, triggerEvent: JobTriggerEvent): Promise<void>;
+  attachDispatcher(ref: DispatchWriteRef): void;
+  countPendingJobs(): Promise<number>;
+};
+type JobRunnerOptions = {
+  registry: Registry;
+  context: AppContext;
+  redisUrl: string;
+  consumerLane?: JobRunIn | undefined;
+  queueNamePrefix?: string | undefined;
+  bootRedisTimeoutMs?: number | undefined;
+  schedulerSeenRefreshMs?: number | undefined;
+  jobRetention?: { completedAgeSec?: number | undefined; failedAgeSec?: number | undefined; } | undefined;
+  getActiveTenantIds?: () => Promise<TenantId[]>;
+  onJobStart?: (jobName: string, jobId: string, meta: JobMeta) => void;
+  onJobComplete?: (jobName: string, jobId: string, duration: number, logs: JobLogEntry[], outcome?: JobOutcomeMeta) => void;
+  onJobFailed?: (jobName: string, jobId: string, error: string, logs: JobLogEntry[], outcome?: JobOutcomeMeta) => void;
+  onJobDeferred?: (jobName: string, jobId: string, meta: JobMeta) => void;
+  onJobQueued?: (jobName: string, jobId: string, meta: JobQueuedMeta) => void;
+  onJobDropped?: (jobName: string, jobId: string, meta: JobDroppedMeta) => void;
+};
+```
+
+## packages/framework/src/lifecycle/lifecycle.ts
+
+```ts
+interface Lifecycle {
+  state(): LifecycleState;
+  uptimeSec(): number;
+  markReady(): void;
+  onStateChange(cb: StateChangeListener): () => void;
+  registerShutdownHook(name: string, fn: ShutdownHookFn): void;
+  hookNames(): string[];
+  drain(opts?: { signal?: string; timeoutMs?: number; }): Promise<void>;
+}
+type LifecycleState = "starting" | "ready" | "draining" | "stopped";
+type ShutdownHookFn = (signal: string) => Promise<void>;
+type StateChangeListener = (from: LifecycleState, to: LifecycleState) => void;
+```
+
+## packages/framework/src/observability/recording-meter.ts
+
+```ts
+type MetricEvent =
+  | {
+    type: "counter.inc";
+    name: string;
+    value: number;
+    labels: MetricLabels | undefined;
+  }
+  | {
+    type: "histogram.observe";
+    name: string;
+    value: number;
+    labels: MetricLabels | undefined;
+  }
+  | {
+    type: "gauge.set" | "gauge.inc" | "gauge.dec";
+    name: string;
+    value: number;
+    labels: MetricLabels | undefined;
+  }
+;
+```
+
+## packages/framework/src/observability/recording-tracer.ts
+
+```ts
+type RecordedSpan = {
+  traceId: string;
+  spanId: string;
+  parentSpanId: string | undefined;
+  name: string;
+  kind: SpanKind;
+  startTime: number;
+  endTime: number | undefined;
+  attributes: Record<string, SpanAttributeValue>;
+  status: SpanStatus;
+  statusMessage: string | undefined;
+  exception: { name: string; message: string; } | undefined;
+};
+```
+
+## packages/framework/src/pipeline/dispatch-shared.ts
+
+```ts
+type BatchCommand = {
+  type: string;
+  payload: unknown;
+};
+type BatchResult =
+  | {
+    isSuccess: true;
+    results: WriteResult[];
+  }
+  | {
+    isSuccess: false;
+    error: WriteErrorInfo;
+    failedIndex: number;
+    results: WriteResult[];
+  }
+;
+```
+
+## packages/framework/src/pipeline/dispatch-stream.ts
+
+```ts
+type StreamOptions = {
+  tokenExpiresAtSec?: number | undefined; // JWT exp (epoch seconds) the stream was opened with; the stream ends when it passes.
+};
+```
+
+## packages/framework/src/pipeline/dispatcher-utils.ts
+
+```ts
+type HandlerType = string | HandlerRef;
+```
+
+## packages/framework/src/pipeline/dispatcher.ts
+
+```ts
+type Dispatcher = {
+  write(type: HandlerType, payload: unknown, user: SessionUser, requestId?: string): Promise<WriteResult>;
+  query(type: HandlerType, payload: unknown, user: SessionUser): Promise<unknown>;
+  stream(type: HandlerType, payload: unknown, user: SessionUser, options?: StreamOptions): AsyncGenerator<unknown>;
+  command(type: HandlerType, payload: unknown, user: SessionUser): Promise<void>;
+  batch(commands: BatchCommand[], user: SessionUser, requestId?: string): Promise<BatchResult>;
+  resolveAuthClaims(user: SessionUser): Promise<Record<string, unknown>>;
+  resolveActiveMembership(userId: string, tenantId: TenantId): Promise<ActiveMembershipResult>;
+  createMemberReader(tenantId: TenantId): MemberReader;
+};
+```
+
+## packages/framework/src/pipeline/event-dispatcher.ts
+
+```ts
+type DispatcherPassResult = {
+  processed: number;
+  failed: number;
+  byConsumer: Record<string, { processed: number; failed: number; }>;
+};
+type EventConsumer = {
+  name: string;
+  handler: EventConsumerHandler;
+  batchHandler?: EventConsumerBatchHandler;
+  errorPolicy?: EventConsumerErrorPolicy;
+  featureName?: string;
+  delivery?: "shared" | "per-instance";
+  startFrom?: "beginning" | "now";
+};
+type EventConsumerBatchHandler = (events: StoredEvent[], ctx: AppContext) => Promise<void>;
+type EventConsumerErrorPolicy = {
+  skipApplyErrors?: boolean;
+  maxAttempts?: number;
+  isTransientError?: (error: unknown) => boolean;
+};
+type EventConsumerHandler = (event: StoredEvent, ctx: AppContext) => Promise<void>;
+type EventDispatcher = {
+  start(): Promise<void>;
+  stop(): Promise<void>;
+  runOnce(): Promise<DispatcherPassResult>;
+  ensureRegistered(): Promise<void>;
+  drain(): Promise<void>;
+  withBackgroundPassesPaused<T>(fn: () => Promise<T>): Promise<T>;
+  consumers: EventConsumer[];
+};
+```
+
+## packages/framework/src/pipeline/lifecycle-pipeline.ts
+
+```ts
+type SystemHookDef<TFn> = {
+  name: string;
+  priority: number;
+  fn: TFn;
+  phase?: HookPhase;
+};
+type SystemHooks = {
+  preSave?: SystemHookDef<PreSaveHookFn>[];
+  postSave?: SystemHookDef<PostSaveHookFn>[];
+  postSaveBatch?: SystemHookDef<PostSaveBatchHookFn>[];
+  preDelete?: SystemHookDef<PreDeleteHookFn>[];
+  postDelete?: SystemHookDef<PostDeleteHookFn>[];
+  postDeleteBatch?: SystemHookDef<PostDeleteBatchHookFn>[];
+};
+```
+
+## packages/framework/src/secrets/dek-cache.ts
+
+```ts
+type DekCache = {
+  unwrapDek(encryptedDek: Buffer, kekVersion: number, provider: MasterKeyProvider, scope?: KeyScope): Promise<Buffer>;
+  clear(): void;
+  size(): number;
+};
+```
+
+## packages/framework/src/secrets/envelope-cipher.ts
+
+```ts
+type EnvelopeCipherOptions = {
+  dekCache?: DekCache;
+};
+```
+
+## packages/framework/src/seeding/entity-seed.ts
+
+```ts
+type EventStoreSeedExisting<TId extends string | number = string> = {
+  id: TId;
+  version: number;
+};
+type RunEventStoreSeedOptions<TId extends string | number = string, TExisting extends EventStoreSeedExisting<TId> = EventStoreSeedExisting<TId>> = {
+  existing: TExisting | null | undefined;
+  ifExists?: SeedIfExists;
+  create: () => Promise<{ id: TId; }>;
+  update: (existing: TExisting) => Promise<{ id: TId; }>;
+};
+```
+
+## packages/framework/src/ui-types/card-column-roles.ts
+
+```ts
+type CardColumnRoles<C extends CardRoleColumn> = {
+  image: C | undefined;
+  title: C | undefined;
+  status: C | undefined;
+  meta: C[];
+};
+type CardRoleColumn = {
+  field: string;
+  highlighted?: boolean;
+  type?: string;
+  renderer?: unknown;
+  hideOnNarrow?: boolean;
+  fileDisplay?: {
+    kind: string;
+  };
+};
+```
+
+## packages/framework/src/ui-types/list-row-meta.ts
+
+```ts
+type ListRowMetaColumnType = "text" | "number" | "timestamp";
+type ListRowMetaReference = {
+  refFeature: string;
+  refEntity: string;
+  refLabelField: string;
+};
+type ReferenceLookupSource = {
+  queryQn: string;
+  labelKey: string;
+};
+type SystemReferenceLabel = {
+  id: string;
+  aliases?: string[]; // Further literals that mean the same system identity (e.g. the "system" createdBy literal).
+  labelKey: string;
+};
+```
+
+## packages/renderer/src/app/client-actions.tsx
+
+```ts
+type ClientActionHandler = (payload: Readonly<Record<string, unknown>>) => Promise<ClientActionOutcome>;
+type ClientActionOutcome =
+  | {
+    ok: true;
+  }
+  | {
+    ok: false;
+    message: string;
+  }
+;
+```
+
+## packages/renderer/src/app/column-renderers.tsx
+
+```ts
+type ColumnRendererComponent = ComponentType<ColumnRendererProps>;
+type ColumnRendererProps = {
+  value: unknown;
+  row: Readonly<Record<string, unknown>>;
+  column: {
+    field: string;
+  };
+  onChange?: (value: unknown) => void; // Set only when the caller (DataTable's `onCellChange`) wired an editable path for this cell — undefined means read-only.
+};
+```
+
+## packages/renderer/src/app/content-editors.tsx
+
+```ts
+type ContentEditorComponent = ComponentType<ContentEditorProps>;
+type ContentEditorProps = {
+  id: string; // DOM id every registered editor must render onto its own focusable root element.
+  value: string;
+  onChange: (value: string) => void;
+  variables: string[]; // Variable names insertable as chips (from the collection's variableSchema).
+  readOnly: boolean;
+};
+```
+
+## packages/renderer/src/app/extension-sections.tsx
+
+```ts
+type ExtensionSectionComponent = ComponentType<ExtensionSectionProps>;
+type ExtensionSectionProps = {
+  entityName: string;
+  entityId: string | null;
+  initialValues?: Readonly<Record<string, unknown>>; // Previously saved extension values for the entity (passed through from the loaded detail row).
+  screenId?: string; // Set only in the list-header slot (`entityId` is null): the list's `screen.id`, so a header control can access the per-screen URL filter state (`useListUrlState`) — for example, a tag filter that narrows the list to a set of IDs.
+  filterParams?: Readonly<Record<string, unknown>>; // Set only in a Dashboard-`custom` panel: the currently selected value of the screen filter (see DashboardFilterDefinition), merged as with any other panel query.
+  values?: Readonly<Record<string, unknown>>; // Current form values of the host RenderEdit (controlled mode) — same snapshot reference as `RenderEditChangeState.values`.
+  patch?: (partial: Readonly<Record<string, unknown>>) => void; // Sets host RenderEdit form values from outside (e.g. a VIN-decode roundtrip that fills other fields) — same function as `RenderEditControls.patch`, merges only the given keys.
+  validate?: () => boolean; // Validates the host form without writing — same function as `RenderEditControls.validate`; field errors land in `snapshot.errors` on the field instead of a collective message.
+  markSaved?: (fields?: string[]) => void; // Marks host form values as saved after the section wrote them itself, so a following navigation does not ask to discard.
+  hasUnsavedChanges?: boolean; // Whether the host form has unsaved changes.
+  wizardStep?: {
+    index: number;
+    isLast: boolean;
+  }; // Current wizard step, only set for `layout.mode === "wizard"` forms.
+  reportStepComplete?: (complete: boolean) => void; // Only set for extension steps of a `layout.mode: "wizard"` entityEdit editing an existing record (update mode); undefined everywhere else.
+};
+```
+
+## packages/renderer/src/app/nav.tsx
+
+```ts
+type NavigateOptions = {
+  searchParams?: Readonly<Record<string, string>>; // Search params of the target route, set in the same history entry as the path.
+};
+type ObjectTarget = {
+  workspaceId?: string;
+  entity: string;
+  id: string;
+};
+type ScreenTarget = {
+  workspaceId?: string;
+  screenId: string;
+  entityId?: string;
+};
+```
+
+## packages/renderer/src/components/list-empty-state.tsx
+
+```ts
+type ListEmptyStateContent = {
+  title: string;
+  description?: string;
+  action?: RenderEditAction;
+};
+```
+
+## packages/renderer/src/components/render-edit-types.ts
+
+```ts
+type RenderEditAction = {
+  id: string;
+  label: string;
+  onPress: () => void | Promise<void>;
+  style?: "primary" | "secondary" | "danger";
+  confirm?: string;
+  confirmLabel?: string;
+  confirmRequired?: boolean; // Overrides the default "danger implies a confirm dialog" rule.
+  icon?: IconKey; // Resolved icon (author `RowAction.icon` or the id-derived default) — drives both the icon-left-of-text render and the icon-only collapse rule (see `shouldRenderActionsIconOnly`).
+};
+```
+
+## packages/renderer/src/components/render-list-toolbar-action.tsx
+
+```ts
+type ToolbarActionButton = {
+  id: string;
+  label: string;
+  style?: "primary" | "secondary" | "danger";
+  confirm?: string;
+  confirmLabel?: string;
+  confirmRequired?: boolean; // Overrides the default "danger implies a confirm dialog" rule.
+  onTrigger: () => Promise<void> | void;
+  icon?: IconKey; // Id-derived default icon (ACTION_ICON_BY_ID in kumiko-screen.tsx) — ToolbarAction has no author-declared icon field, unlike RowAction.
+};
+```
+
+## packages/renderer/src/context/draft-storage-context.tsx
+
+```ts
+type DraftStorage = {
+  getDraftId: (screenId: string) => string | null;
+  setDraftId: (screenId: string, draftId: string) => void;
+  clearDraftId: (screenId: string) => void;
+};
+```
+
+## packages/renderer/src/data-table-aggregate-types.ts
+
+```ts
+type DataTableListNotice = "truncated" | "searchTruncated"; // `truncated`: more groups than the server answers.
+type DataTableMeasure = { // One server-computed measure; a money measure holds one minor-unit value per currency.
+  field: string;
+  kind: ListAggregateMeasureKind;
+  value: ListAggregateValue;
+};
+type DataTableRangeBound = "min" | "max";
+type DataTableRangeFacet = { // "From/to" inputs on a number field.
+  field: string;
+  label: string;
+  min: string;
+  max: string;
+  unit?: string; // Shown after the inputs, e.g. the money field's currency.
+};
+type DataTableServerGroup = {
+  key: string; // `relatedListGroupKey` of the group value; stable across reloads.
+  value: AggregateKey; // Raw group value, rendered through the group column when `label` is absent.
+  label?: string;
+  count: number; // Rows of the whole group on the server, not the loaded ones.
+  measures: DataTableMeasure[];
+  collapsed: boolean;
+  rowCount: number; // How many of the table's `rows` belong to this group; rows arrive in group order.
+  hasMore: boolean;
+  loading: boolean;
+};
+type DataTableServerGroups = { // Server-side grouping: groups are the load unit, each loads its own rows.
+  field: string;
+  groups: DataTableServerGroup[];
+  totalCount: number;
+  onToggle: (key: string) => void;
+  onLoadMore: (key: string) => void;
+  onHeaderVisible: (key: string) => void;
+};
+type DataTableTotals = {
+  measures: DataTableMeasure[];
+};
+```
+
+## packages/renderer/src/data-table-bulk-types.ts
+
+```ts
+type BulkRowOutcome =
+  | {
+    kind: "succeeded";
+  }
+  | {
+    kind: "failed";
+    message: string;
+  }
+;
+type DataTableBulk = {
+  actions: DataTableBulkAction[];
+  reload: () => Promise<void>; // Reloads the list once after a run.
+};
+type DataTableBulkAction = {
+  id: string;
+  label: string; // Translated label of the underlying row action.
+  style?: "primary" | "secondary" | "danger";
+  icon?: IconKey;
+  confirmText?: (count: number) => string; // Present: one confirm dialog for the whole selection, with this text for `count` rows.
+  confirmLabel?: string;
+  appliesTo: (row: ListRowViewModel) => boolean; // False: the row action's `visible` hides it for this row; the run skips the row.
+  writeRow: (row: ListRowViewModel) => Promise<BulkRowOutcome>; // Exactly one server write for one row.
+};
+```
+
+## packages/renderer/src/data-table-facet-types.ts
+
+```ts
+type DataTableDateRangeFacet = {
+  field: string; // The facet's namespace (its date field) — a key, not a filter value.
+  label: string; // Translated label ("When").
+  from: string;
+  to: string;
+};
+type DataTableFacet = {
+  field: string; // Entity-Feldname (= URL-State-Key + payload.filters[].field).
+  label: string; // Translated Button-Label ("Status", "Active").
+  options: { value: string; label: string; }[]; // Selectable values with display labels.
+  chips?: DataTableFacetChip[]; // Present: render the facet as a row of single-choice toggle chips instead of a dropdown.
+  showCounts?: boolean; // Chips only: show each chip's `count` next to its label.
+  hideEmpty?: boolean; // Chips only: hide chips whose `count` is 0 (unless pressed).
+  onSearchChange?: (query: string) => void; // Present: the options come from a server-side search (reference facets), so the dropdown shows a search field and reports the typed term instead of filtering `options` itself.
+  searching?: boolean; // The search is loading; the option list may still show the previous term's rows.
+};
+type DataTableFacetChip = {
+  id: string;
+  label: string; // Translated chip label.
+  values: string[]; // Selection a click sets; `[]` clears the facet.
+  count?: number; // Matching row count, undefined while unknown.
+};
+```
+
+## packages/renderer/src/data-table-view-types.ts
+
+```ts
+type DataTableColumnPin = ListColumnPin;
+type DataTableColumnPins = Readonly<Record<string, DataTableColumnPin>>;
+type DataTableColumnWidths = Readonly<Record<string, number>>;
+type DataTableDensity = ListTableDensity;
+type DataTableExport = { // What the export button sends to POST /api/export/xlsx (xlsx is the only format).
+  screen: string; // Screen QN `<feature>:screen:<id>`.
+  screenShortId: string;
+  payload: Readonly<Record<string, unknown>>; // The list payload without paging keys; the server reads the whole filtered list.
+  columns: string[]; // Visible column ids in display order.
+};
+type DataTableGroupByChoice = {
+  value: string; // Active group field, "" = not grouped.
+  fields: string[];
+  onChange: (next: string) => void;
+};
+type DataTableResetAll = {
+  active: boolean; // True while something deviates from the screen default.
+  onReset: () => void;
+};
+type DataTableTableBlock = { // The DataTable props a screen's `table` block feeds.
+  view?: DataTableViewOptions; // View menu (column picker, density); absent = no menu.
+  resetAll?: DataTableResetAll; // Replaces the facet reset with one that also covers sort, search and page size.
+  exportList?: DataTableExport; // Present: the toolbar has an export button (web only).
+  serverGroups?: DataTableServerGroups; // Present: the rows are grouped on the server; replaces pager and infinite scroll.
+  totals?: DataTableTotals; // Present: a footer row with the server-computed totals of the filtered list.
+  notice?: DataTableListNotice; // Present: the toolbar says the answer is incomplete and asks to narrow the list.
+  rangeFacets?: DataTableRangeFacet[];
+  onRangeChange?: (field: string, bound: DataTableRangeBound, value: string) => void;
+};
+type DataTableViewColumn = { // One column in the view menu.
+  field: string;
+  visible: boolean;
+};
+type DataTableViewOptions = {
+  columns?: DataTableViewColumn[]; // Present: the view menu has a column section (visibility + order).
+  onColumnsChange?: (next: DataTableViewColumn[]) => void;
+  density: DataTableDensity;
+  onDensityChange?: (next: DataTableDensity) => void; // Present: the view menu has a density section.
+  pins?: DataTableColumnPins; // Present: pinning is on and the view menu has a pin section.
+  onPinsChange?: (next: DataTableColumnPins) => void;
+  widths?: DataTableColumnWidths; // Present: resizing is on.
+  minWidths?: DataTableColumnWidths; // Present together with `widths`; every column has an entry (px).
+  onWidthChange?: (field: string, width: number, others?: DataTableColumnWidths) => void; // `others` holds the displayed widths of the columns that had no entry yet, so they keep their size once the layout turns fixed.
+  keyboardNavigation?: boolean;
+  groupBy?: DataTableGroupByChoice; // Present: the view menu has a "group by" section.
+  viewIsDefault: boolean; // False once columns, order or density differ from the screen default.
+  onViewReset: () => void;
+};
+```
+
+## packages/renderer/src/headless/contracts/locale.ts
+
+```ts
+type LocaleResolver = {
+  translate(key: string, params?: Readonly<Record<string, unknown>>): string;
+  locale(): string;
+  timeZone(): string;
+  subscribe(listener: () => void): () => void;
+  setLocale?(locale: string): void;
+};
+```
+
+## packages/renderer/src/headless/dispatcher/types.ts
+
+```ts
+type BatchResult =
+  | {
+    isSuccess: true;
+    results: WriteResult[];
+  }
+  | {
+    isSuccess: false;
+    error: DispatcherError;
+    failedIndex: number;
+    results: WriteResult[];
+  }
+;
+type Command = {
+  type: string;
+  payload: unknown;
+};
+type Dispatcher = {
+  write<TData = unknown>(type: string, payload: unknown, opts?: WriteOpts): Promise<WriteResult<TData>>;
+  query<TData = unknown>(type: string, payload: unknown, opts?: QueryOpts): Promise<QueryResult<TData>>;
+  batch(commands: Command[], opts?: WriteOpts): Promise<BatchResult>;
+  stream<TChunk = unknown>(type: string, payload: unknown, opts?: StreamOpts): AsyncGenerator<TChunk, void, undefined>;
+  statusStore: Store<DispatcherStatus>;
+  pendingWrites(): PendingWrite[];
+  pendingFiles(): PendingFile[];
+};
+type DispatcherError = {
+  code: string;
+  httpStatus: number;
+  i18nKey: string;
+  i18nParams?: Readonly<Record<string, unknown>>;
+  message: string;
+  details?: { fields?: FieldIssue[]; } & Record<string, unknown>;
+  docsUrl?: string;
+  requestId?: string;
+};
+type DispatcherStatus = "online" | "offline" | "syncing";
+type PendingFile = {
+  id: string;
+  fileName: string;
+  sizeBytes: number;
+  queuedAt: string;
+  attempts: number;
+  progress?: number;
+  lastError?: DispatcherError;
+};
+type PendingWrite = {
+  id: string;
+  type: string;
+  payload: unknown;
+  queuedAt: string;
+  attempts: number;
+  lastError?: DispatcherError;
+};
+type QueryOpts = {
+  signal?: AbortSignal;
+};
+type QueryResult<TData = unknown> =
+  | {
+    isSuccess: true;
+    data: TData;
+  }
+  | {
+    isSuccess: false;
+    error: DispatcherError;
+  }
+;
+type StreamOpts = {
+  signal?: AbortSignal;
+};
+type WriteOpts = {
+  requestId?: string;
+  signal?: AbortSignal;
+};
+type WriteResult<TData = unknown> =
+  | {
+    isSuccess: true;
+    data: TData;
+  }
+  | {
+    isSuccess: false;
+    error: DispatcherError;
+  }
+;
+```
+
+## packages/renderer/src/headless/form/types.ts
+
+```ts
+type FieldConditionPredicate<TValues extends FormValues, TCtx> = (values: TValues, ctx: TCtx) => boolean;
+type FieldConditionValue<TValues extends FormValues, TCtx> = boolean | FieldConditionPredicate<TValues, TCtx>;
+type FieldConditions<TValues extends FormValues, TCtx = unknown> = {
+  visible?: FieldConditionValue<TValues, TCtx>;
+  readonly?: FieldConditionValue<TValues, TCtx>;
+  required?: FieldConditionValue<TValues, TCtx>;
+};
+type FieldState = {
+  visible: boolean;
+  readonly: boolean;
+  required: boolean;
+};
+type FormController<TValues extends FormValues> = {
+  getSnapshot(): FormSnapshot<TValues>;
+  subscribe(listener: () => void): () => void;
+  setField<K extends keyof TValues>(key: K, value: TValues[K]): void;
+  setValues(partial: Partial<TValues>): void;
+  clearErrors(path?: string): void;
+  setErrors(errors: Readonly<Record<string, FieldIssue[]>>): void;
+  validate(scope?: FormScopeKey<TValues>[]): boolean;
+  reset(): void;
+  rebase(): void;
+  rebaseFields(fields: string[]): void;
+  seedField(field: string, value: unknown): void;
+  setCtx(ctx: unknown): void;
+  submit<TData = unknown>(): Promise<SubmitResult<TData>>;
+};
+type FormControllerOptions<TValues extends FormValues, TCtx = unknown> = {
+  initial: TValues;
+  schema?: ZodType;
+  fields?: Readonly<Record<string, FieldConditions<TValues, TCtx>>>;
+  ctx?: TCtx;
+  submit?: SubmitConfig<TValues>;
+};
+type FormScopeKey<TValues extends FormValues> = (keyof TValues & string) | `${keyof TValues & string}.${string}`;
+type FormSnapshot<TValues extends FormValues> = {
+  values: TValues;
+  initial: TValues;
+  changes: Partial<TValues>;
+  isDirty: boolean;
+  isUnchanged: boolean;
+  errors: Readonly<Record<string, FieldIssue[]>>;
+  fields: Readonly<Record<string, FieldState>>;
+};
+type FormValues = Record<string, unknown>;
+type SubmitConfig<TValues extends FormValues = FormValues> = {
+  dispatcher?: Dispatcher;
+  type: string;
+  payloadMode?: SubmitPayloadMode;
+  stripEmptySeeds?: boolean; // Only applies to payloadMode "values".
+  omitFields?: string[]; // Top-level payload keys removed right before dispatch, for fields that are shown or validated but must not reach the write handler.
+  buildPayload?: (snapshot: FormSnapshot<TValues>) => unknown;
+  serverFieldPathPrefix?: string;
+  validateScope?: string[]; // Restricts submit()'s internal validate() call to these field names — same contract as validate()'s `scope` param.
+};
+type SubmitPayloadMode = "values" | "changes";
+type SubmitResult<TData = unknown> =
+  | ({ validationBlocked: false; isNoOp?: boolean; } & WriteResult<TData>)
+  | {
+    validationBlocked: true;
+    isSuccess: false;
+  }
+;
+```
+
+## packages/renderer/src/headless/nav/types.ts
+
+```ts
+type NavRegistrySlice = {
+  topLevel: NavDefinition[];
+  byParent: (parentQualifiedName: string) => NavDefinition[];
+};
+```
+
+## packages/renderer/src/headless/store/types.ts
+
+```ts
+type Store<T> = {
+  getSnapshot(): T;
+  subscribe(listener: () => void): () => void;
+};
+```
+
+## packages/renderer/src/headless/view-model/types.ts
+
+```ts
+type CellLink = { // Where a cell's text links to.
+  href: string;
+  onPress: () => void;
+};
+type CellLinkItem = { // One entry of a multi-reference cell: its label, linked when the target is readable.
+  id: string;
+  label: string;
+  link?: CellLink;
+};
+type EditFieldViewModel = {
+  field: string;
+  label: string;
+  type: string;
+  value: unknown;
+  visible: boolean;
+  readOnly: boolean;
+  required: boolean;
+  span?: number;
+  renderer?: FieldRenderer;
+  options?: string[]; // Set for `type: "select"` and `type: "multiSelect"` — the allowed values.
+  optionLabels?: Readonly<Record<string, string>>; // Set for `type: "select"` and `type: "multiSelect"` — translated labels per option, keyed by raw value.
+  selectOptionsQuery?: {
+    query: string;
+    payload: OptionsQueryPayload;
+  }; // Set for `type: "select"` when SelectFieldDef.optionsQuery is set: the renderer loads the options from this query (`{ rows: { value, label, description?, group?
+  selectOptionsAvailabilityQuery?: {
+    query: string;
+    payload: OptionsQueryPayload;
+  }; // Set for `type: "select"` / `"multiSelect"` when optionsAvailabilityQuery is set: the renderer loads `{ rows: { value, disabled?, hint?
+  display?: "checkboxes" | "dropdown" | "radio"; // Set for `type: "multiSelect"` when MultiSelectFieldDef.display is "checkboxes" — the renderer shows a checkbox grid with a select-all toggle instead of the default combobox dropdown.
+  columns?: 1 | 2 | 3 | 4; // Set for `type: "multiSelect"` when MultiSelectFieldDef.columns is defined — column count for the checkbox grid at the widest breakpoint.
+  maxRows?: number; // Set for `type: "multiSelect"` when MultiSelectFieldDef.maxRows is defined — grid rows visible before the checkbox grid becomes scrollable.
+  multiline?: boolean | { rows?: number; }; // For `type: "text"`, set when TextFieldDef.multiline is true — the renderer then renders a textarea instead of a single-line input.
+  format?: "email" | "url" | "phone" | "password" | "month" | "iban"; // From TextFieldDef.format — `password` makes the renderer mask the input.
+  autoComplete?: string; // From TextFieldDef.autoComplete — HTML autocomplete token for the text input.
+  writeOnly?: true; // From TextFieldDef.writeOnly — value is `true` (set) / `null` (empty), never plaintext.
+  sensitive?: true; // From the field's `sensitive: true` — the value must not leave the form (drafts, URL prefill).
+  wallClock?: boolean; // Only set for `type: "timestamp"` when TimestampFieldDef.locatedBy exists — wall-clock time without offset.
+  min?: string; // Only for `type: "date" | "timestamp"` — date bounds (ISO) and format/locale override from the FieldDefinition.
+  max?: string;
+  dateLocale?: string;
+  grouping?: boolean; // Only for `type: "number"` — mirrors `NumberFieldDef.grouping` (default `true`).
+  refEntity?: string; // Only set for `type: "reference"`.
+  refFeature?: string; // Only set for `type: "reference"` — name of the feature the referenced entity lives in.
+  refLabelField?: string; // Only set for `type: "reference"` — which field of the referenced entity appears as the display label in the dropdown.
+  refOptionsQuery?: string; // Only for `type: "reference"` — query handler QN the picker sources its options from, replacing the referenced entity's list handler.
+  refMultiple?: boolean; // Only for `type: "reference"` — multi mode: the value is a UUID array, the renderer mounts a multi-combobox with tags.
+  accept?: string[]; // Only for `type: "file" | "image"` — allowed extensions/MIME (e.g. ["jpg","png"]) + max size ("5mb").
+  maxSize?: string;
+  maxCount?: number; // Only for `type: "files" | "images"` — upper bound on list length.
+  entityType?: string; // Only for `type: "file" | "image"` — entity name + field name for the upload POST (`/api/files`), so the endpoint can check maxSize/accept against the right field def.
+  uploadActionForm?: string; // Only for file fields of an actionForm — the screen QN the upload POST names as `actionForm` instead of `entityType`; the server resolves the field through that screen.
+  fieldName?: string;
+  fileDisplay?: "list" | "dropzone"; // Only for `type: "files" | "images"` — how the field is shown.
+  entityId?: string; // Record being edited (update mode only).
+  imageVariant?: string; // Only for `type: "image"` and `"images"` — the variant name the preview requests (`/api/files/:id/variant/:name`) instead of the original.
+  capture?: "environment" | "user"; // Only for `type: "image"` — forwarded to the file input's `capture` attribute so a phone opens the camera instead of the file picker.
+  icon?: FieldIconKey; // Closed FieldIconKey from EditFieldSpec.icon (FIELD_ICONS registry).
+  placeholder?: string; // From EditFieldSpec.placeholder, already translated — hint shown while the input is empty.
+  prefix?: FieldAffix; // From EditFieldSpec.prefix / suffix.
+  suffix?: FieldAffix;
+  fillAction?: FieldFillAction; // From EditFieldSpec.fillAction, `label` already translated.
+  embeddedListCells?: EmbeddedListCellViewModel[]; // Only set for an embedded-LIST field (`multiple: true`) — the per-cell metadata the renderer needs to draw each column/cell.
+  embeddedListMinItems?: number; // Minimum row count for the embedded list.
+  embeddedListMaxItems?: number; // Maximum row count for the embedded list.
+  embeddedListDerived?: Readonly<Record<string, { op: "multiply" | "sum" | "subtract" | "percent"; from: string[]; }>>; // Sub-field name → how to compute its cell from other sub-fields of the same row.
+  embeddedListTotals?: (string | { label: string; from: string[]; })[]; // Footer totals: a sub-field name, or a labelled sum of several.
+  embeddedListFixedRows?: boolean; // No add, remove, duplicate or move; cells stay editable.
+  embeddedListCurrency?: string; // Currency for the whole embedded list's money cells and totals row — currency lives on the head aggregate (EntityDefinition.defaultCurrency), not per row.
+  currency?: string; // Only set for a plain (non-list, non-embedded) `type: "money"` field — same source as embeddedListCurrency (EntityDefinition.defaultCurrency, falls back to "EUR").
+  unit?: string | { field: string; }; // Only set for `type: "number"` when NumberFieldDef.unit is set — a static suffix string, or a sibling-field reference the renderer resolves against the live row values.
+};
+type EmbeddedListCellViewModel = {
+  field: string;
+  label: string;
+  type: "text" | "number" | "boolean" | "date" | "money" | "decimal" | "select" | "reference" | "timestamp";
+  required: boolean;
+  options?: string[]; // Only for `type: "select"`.
+  optionLabels?: Readonly<Record<string, string>>;
+  display?: "radio" | "dropdown"; // Only for `type: "select"`; `"radio"` renders segmented buttons instead of a dropdown.
+  readOnly?: boolean; // Cell is shown but not editable (`EditFieldSpec.embeddedList.readOnlyCells`).
+  refEntity?: string; // Only for `type: "reference"`.
+  refFeature?: string;
+  refLabelField?: string;
+  refOptionsQuery?: string;
+  scale?: number; // Only for `type: "decimal"`.
+};
+type ListColumnFileDisplay = // How a list cell shows a FileRef value (id or id array).
+  | {
+    kind: "image";
+    variant?: string;
+  }
+  | {
+    kind: "file";
+  }
+;
+type ListColumnViewModel = {
+  field: string;
+  label: string;
+  type: string;
+  renderer?: FieldRenderer | RuntimeRenderer;
+  linkFor?: RuntimeCellLink;
+  linkItemsFor?: RuntimeCellLinkItems;
+  sortable: boolean;
+  optionLabels?: Readonly<Record<string, string>>; // Only for `type: "select"` or `type: "multiSelect"` — translated option labels keyed by raw value.
+  optionTones?: Readonly<Partial<Record<string, SelectOptionTone>>>; // Only for `type: "select"` — declared tone per raw option value.
+  refEntity?: string; // Only for `type: "reference"` — referenced entity name for the bulk lookup in the renderer (`<refFeature>:query:<refEntity>:list`).
+  refFeature?: string; // Only for `type: "reference"` — name of the feature the referenced entity lives in.
+  refLabelField?: string; // Only for `type: "reference"` — which field of the referenced entity appears as the display value in the cell (default "id").
+  highlighted?: boolean; // Set by the caller at runtime (not schema-derived) to emphasize one column — e.g. the currently selected base-year column in a multi-year statement grid.
+  hideOnNarrow?: boolean; // Mirrors `ListColumnSpec.hideOnNarrow`: card layout skips the column.
+  grouping?: boolean; // Only for `type: "number"` — mirrors `NumberFieldDef.grouping` (default `true`).
+  fileDisplay?: ListColumnFileDisplay; // Set for file/image columns: from the entity field type, or from a `{ format: "image" | "file" }` renderer.
+};
+type ListRowViewModel = {
+  id: string;
+  values: Readonly<Record<string, unknown>>;
+};
+type RuntimeCellLink = (value: unknown, row?: Readonly<Record<string, unknown>>) => CellLink | undefined; // Runtime-only like RuntimeRenderer; undefined means the cell stays plain text.
+type RuntimeCellLinkItems = (value: unknown, row?: Readonly<Record<string, unknown>>) => CellLinkItem[] | undefined; // Runtime-only like RuntimeCellLink; undefined means the cell uses its single renderer.
+type RuntimeRenderer = (value: unknown, row?: Readonly<Record<string, unknown>>) => string;
+type Translate = (key: string, params?: Readonly<Record<string, unknown>>) => string;
+```
+
+## packages/renderer/src/hooks/use-list-url-state.ts
+
+```ts
+type ListSort = DataTableSort;
+```
+
+## packages/renderer/src/metric-types.ts
+
+```ts
+type MetricBandProps = { // Band above the tabs of a record detail: optional subtitle line plus the metrics as a definition list.
+  lead?: ReactNode; // Free-form block rendered unstyled as the first full-width row of the band.
+  subtitle?: ReactNode;
+  children: ReactNode;
+  tiles?: boolean; // The children are KPI tiles, laid out as a tile grid instead of a definition list.
+  testId?: string;
+};
+type MetricProps = { // Compact label/value tile (record-detail metrics band).
+  label: string;
+  value: string;
+  testId?: string;
+  onPress?: () => void; // Click handler — set when the metric declares a `navigate` target (see `MetricSpec`).
+  tile?: boolean; // Draw as a KPI tile (the dashboard StatCard) instead of a band entry.
+  tone?: DashboardStatTone;
+  icon?: NavIconKey;
+};
+```
+
+## packages/renderer/src/primitives.tsx
+
+```ts
+type ActionMenuItemSpec = { // One item in an `ActionOverflowMenu` (header/row actions beyond the primary one collapse into this menu instead of a wall of buttons).
+  id: string;
+  label: string;
+  icon?: IconKey; // Icon name, resolved by the implementation (same names as row actions).
+  disabled?: boolean;
+  variant?: "default" | "danger";
+  testId?: string;
+  onSelect: () => void;
+};
+type ActionOverflowMenuProps = {
+  items: ActionMenuItemSpec[];
+  label: string; // aria-label for the three-dots trigger.
+  testId?: string;
+};
+type ButtonBaseProps = {
+  type?: "button" | "submit";
+  onClick?: () => void | Promise<void>;
+  disabled?: boolean;
+  loading?: boolean; // Render a spinner instead of the children.
+  variant?: "primary" | "secondary" | "danger" | "link" | "danger-ghost" | "ghost"; // Semantic class — default="primary".
+  size?: "sm" | "md" | "icon"; // Size—default="md".
+  ariaLabel?: string; // Accessible label—required for icon-only buttons (when children contain only an icon or character), otherwise the button has no accessible name.
+  title?: string; // Tooltip — rendered as the `title` attribute.
+  pressed?: boolean; // Toggle state for toggle buttons — web sets `aria-pressed`; leave unset for plain buttons.
+  expanded?: boolean; // Disclosure state for buttons that open a menu or panel — web sets `aria-expanded`.
+  width?: "full" | "auto"; // Width—default="auto" (content width).
+  testId?: string;
+  className?: string; // Layout extras, merged via cn().
+  ref?: Ref<HTMLButtonElement>; // DOM ref on the button — escape hatch for cases that need more than a click (e.g. binding a drop-target handler).
+  icon?: NavIconKey; // Icon before the label.
+  iconEnd?: NavIconKey; // Icon after the label (e.g. "Continue →").
+  dataAttributes?: DataAttributes;
+};
+type CardOptions = { // Card-Options — Verhalten/Optik, ebenfalls additiv erweiterbar.
+  padded?: boolean; // Body-Padding (px-6 py-6).
+  radius?: "lg" | "xl"; // Eckenradius.
+  footerBordered?: boolean; // Separates the footer with `border-t` and `bg-muted/30`.
+  footerInset?: boolean; // Footer horizontal padding.
+  fillHeight?: boolean; // Joins the ancestor fillHeight flex chain — a tabs-mode relatedList table sizing to the panel instead of the page — instead of normal document-flow height.
+  framed?: boolean; // false drops border, background, shadow and radius but keeps padding and header slots — a panel inside a host surface such as a tab panel.
+  screenBody?: boolean; // The card is the whole screen body (secretMint reveal and done phase): no frame, the shared screen insets and width of form screens, children stacked with a gap.
+};
+type CardSlots = { // Card slots are named content regions, all optional.
+  header?: ReactNode;
+  title?: ReactNode;
+  subtitle?: ReactNode;
+  headerContent?: ReactNode; // Free-form block content in its own full-width row below the title/subtitle/`headerActions` row, within the same header block — for a host-supplied header (projectionDetail `slots.header`).
+  headerActions?: ReactNode; // Right-aligned header slot, for example a range switcher, filter, or badge.
+  footer?: ReactNode; // Footer content, separated by a top border; aligned to the right by default.
+};
+type ConfigCascadeViewProps = { // Cascade view for a config-edit field: one origin line ("Set for this tenant", "Uses the default", …), a reset action for an own value, and a disclosure listing every level.
+  cascade: ConfigCascade;
+  screenScope: ConfigScope;
+  onReset?: (key: string, scope: ConfigScope) => void;
+  qualifiedKey?: string;
+  required?: boolean; // The key declares `required: true` — a missing value reads "Not set.
+  renderValue?: (value: string | number | boolean) => ReactNode; // Display form of a level value (e.g. a select's label instead of its raw value).
+};
+type ConfigSourceBadgeProps = { // Source-badge for one cascade step (User / Tenant / System / …).
+  source: ConfigValueSource;
+  screenScope?: ConfigScope; // Scope of the hosting screen.
+};
+type CopyButtonProps = { // Copies `text` to the clipboard; the label flips to `copiedLabel` once the platform confirmed the write.
+  text: string;
+  label: string;
+  copiedLabel: string;
+  variant?: "primary" | "secondary";
+  className?: string; // Layout extras, merged via cn().
+  testId?: string;
+};
+type DataAttributes = Readonly<Record<`data-${string}`, string>>; // Escape hatch for `data-*` test hooks (e.g. an E2E selector) that don't warrant a dedicated typed prop.
+type DataTableRowAction = {
+  id: string; // Stable ID for aria-labels and data-testids.
+  label: string; // Translated Label.
+  style?: "primary" | "secondary" | "danger"; // Visual style — "danger" renders the red variant in the default primitive.
+  confirm?: string; // Translated confirmation prompt (dialog description).
+  confirmLabel?: string; // Translated confirm-button label in the dialog.
+  confirmRequired?: boolean; // Overrides the default "danger implies a confirm dialog" rule.
+  onTrigger: (row: ListRowViewModel) => Promise<void> | void; // Called with the clicked row's `ListRowViewModel`.
+  isVisible?: (row: ListRowViewModel) => boolean; // Controls per-row visibility (e.g. show "Start" only when `status==="scheduled"`).
+  rowClick?: boolean; // This action is what a click on the row does.
+  icon?: IconKey; // Resolved icon (author `RowAction.icon` or the id-derived default) — drives both the icon-left-of-text render and the icon-only collapse rule (see `shouldRenderActionsIconOnly`).
+  display?: RowActionDisplay; // Author-chosen inline form (`RowAction.display`).
+};
+type DataTableRowActionMode = "adaptive" | "inline";
+type DataTableSort = {
+  field: string;
+  dir: DataTableSortDir;
+};
+type DataTableSortDir = "asc" | "desc";
+type DataTableTableBlockProps = Pick<DataTableProps, keyof DataTableTableBlock>;
+type DialogProps = { // Modal dialog for confirmations or compact sub-forms.
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  title: string;
+  description?: string; // Optional description, typically a sentence explaining the consequence ("This action cannot be undone.").
+  confirmLabel?: string; // Confirm-button label.
+  cancelLabel?: string; // Cancel-Button-Label.
+  variant?: "default" | "danger"; // `default` = Confirm primary, `danger` = Confirm danger.
+  initialFocus?: "confirm" | "cancel"; // Which button takes focus on open.
+  onConfirm: () => void | Promise<void>; // Called when the user confirms.
+  children?: ReactNode; // Optional additional content between the description and buttons, such as an input when the dialog also collects data.
+  testId?: string;
+};
+type DrawerProps = { // Side panel for hosting an existing self-contained form/widget (own submit/cancel buttons) without leaving the underlying screen — e.g. a toolbar action's `kind: "drawer"` mounts an actionForm here instead of navigating to a full page.
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  title?: string;
+  subtitle?: string; // Muted line under the title.
+  children: ReactNode;
+  testId?: string;
+};
+type EmbeddedListCellType = "text" | "number" | "boolean" | "date" | "money" | "decimal" | "select" | "reference" | "timestamp"; // Cell type for one column of an embedded-list field.
+type EmbeddedListColumn = { // One column of an embedded-list table (one entry per key of the source EmbeddedFieldDef's `schema`).
+  field: string;
+  label: string;
+  type: EmbeddedListCellType;
+  required: boolean;
+  derived: boolean; // Read-only, value supplied by the caller (already computed from sibling cells) — not directly user-editable.
+  readOnly?: boolean; // Shown but not editable by the user; unlike `derived` it is not computed.
+  options?: string[]; // Only for `type: "select"`.
+  optionLabels?: Readonly<Record<string, string>>;
+  display?: "radio" | "dropdown"; // Only for `type: "select"`; `"radio"` renders segmented buttons, the default is a dropdown.
+  referenceOptions?: { value: string; label: string; }[]; // Only for `type: "reference"` — pre-fetched by the caller, ONE query per column shared across every row (not one query per cell).
+  referenceLoading?: boolean;
+};
+type EmbeddedListInputProps = { // Row-array + totals table for a `createEmbeddedListField` (invoice- positions-style) field — structurally too different from `Input`'s value/onChange union to fit there, so it's its own primitive, same as `DataTable`.
+  id: string;
+  columns: EmbeddedListColumn[];
+  rows: Readonly<Record<string, unknown>>[];
+  totals?: EmbeddedListTotal[];
+  currency?: string; // Currency for money cells and the totals row — one value for the whole list (currency lives on the head aggregate, not the row).
+  disabled?: boolean; // Whole-list read-only (e.g. a released invoice) — hides row-mutation affordances and disables every cell.
+  fixedRows?: boolean; // Rows are fixed: no add, remove, duplicate or move; cells stay editable.
+  minItems?: number;
+  maxItems?: number;
+  listIssues?: FieldIssue[]; // Shown under the whole list (e.g. under the totals row).
+  rowIssues?: Readonly<Record<number, FieldIssue[]>>; // Keyed by row index.
+  cellIssues?: Readonly<Record<string, FieldIssue[]>>; // Keyed `${rowIndex}.${field}`.
+  onCellChange: (rowIndex: number, field: string, value: unknown) => void;
+  onAddRow: () => void;
+  onRemoveRow: (rowIndex: number) => void;
+  onDuplicateRow: (rowIndex: number) => void;
+  onMoveRow: (fromIndex: number, toIndex: number) => void;
+  onPasteCells?: (rowIndex: number, columnIndex: number, grid: (string[])[]) => void; // Tab/newline-delimited clipboard paste starting at (rowIndex, columnIndex) — parsed to a 2D string grid by the Web impl (paste events are a browser-only concept); undefined caller = no paste handling wired up.
+  addLabel: string;
+  actionsLabel: string; // Accessible name of the (otherwise headerless) row-actions column.
+  removeLabel: string;
+  duplicateLabel: string;
+  moveUpLabel: string;
+  moveDownLabel: string;
+  emptyLabel: string;
+  emptyCtaLabel: string;
+  testId?: string;
+};
+type EmbeddedListTotal = { // One entry of an embedded-list totals row (e.g. an invoice's total amount, summed across all rows by the caller).
+  field: string;
+  label: string;
+  value: number;
+  money?: boolean; // Set for labelled multi-column totals, which have no single column to read the money type from.
+};
+type FieldCellWidth = "text" | "number" | "money" | "date" | "timestamp" | "select" | "full" | "toggle"; // Width class of a field cell inside a `flow` grid: sized by what the field holds.
+type FileValueListProps = { // Read-only list of stored files (FileRef ids): name, download link and, for PDFs, an inline preview.
+  fileIds: string[];
+  previewOpenByDefault?: boolean; // Starts the inline PDF preview of the newest file open; uploads append, so that is the last id.
+  testId?: string;
+};
+type FillContainerProps = { // Chromeless flex-fill layout host — no title, no card frame, no padding, just a container that sizes to its content and, once the ancestor chain is height-constrained, shrinks so one scrolling child can scroll internally instead of the page growing.
+  children: ReactNode;
+  testId?: string;
+  grow?: boolean; // Claims the remaining height of the flex chain (`flex-1`) instead of sizing to its content, so a footer inside the child sits at the bottom edge even with few rows.
+};
+type FormSectionNavItem = { // One entry of a form's "on this page" navigation: `id` matches the `SectionProps.id` of the section it scrolls to.
+  id: string;
+  title: string;
+};
+type InputFillAction = { // Button beside a single-line text/number input that fills it with a suggestion.
+  label: string;
+  onPress: () => void;
+  busy?: boolean; // A suggestion is being fetched: the button shows a spinner and is inert.
+  disabled?: boolean; // The surrounding form is locked as a whole.
+  testId?: string;
+};
+type JsonViewProps = { // Structured JSON display (audit payload/metadata, job logs, unsupported jsonb/embedded field fallback).
+  value: unknown;
+  indent?: number;
+  testId?: string;
+};
+type LightboxBaseProps = {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  testId?: string;
+  actions?: ReactNode; // Controls for the shown image, e.g. a download button.
+  showPosition?: boolean; // `false` hides the `{current} / {total}` counter of a set, for images that carry their own.
+};
+type LightboxImage = {
+  src: string;
+  alt: string;
+};
+type LightboxProps = LightboxBaseProps & ({ src: string; alt: string; } | { images: LightboxImage[]; index: number; onIndexChange: (index: number) => void; }); // Image lightbox — full-size preview on click.
+type LinkProps = { // Navigation link.
+  href: string;
+  variant?: "default" | "button" | "muted";
+  target?: "_blank" | "_self" | "_parent" | "_top"; // `_blank` makes the web impl set `rel="noopener noreferrer"` unless `rel` is set explicitly.
+  rel?: string;
+  onPress?: () => void; // Plain left-click handler (SPA navigation); `href` stays set for modifier/middle clicks, which the browser handles itself.
+  className?: string; // Layout extras (self-center, text-xs), merged via cn().
+  children: ReactNode;
+  testId?: string;
+  dataAttributes?: DataAttributes;
+};
+type ModalProps = { // Bare content shell for hosting an existing self-contained form/widget (own submit/cancel buttons) inside a modal overlay — unlike `Dialog`, it renders no footer buttons of its own.
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  title: string; // Screen-reader-only accessible title (required by the underlying dialog primitive) — not shown visually since the hosted content is expected to render its own heading.
+  children: ReactNode;
+  testId?: string;
+};
+type PageHeaderProps = { // Page title area rendered by the app shell's header instead of inside the screen: `title` replaces the last breadcrumb, `status` sits right after it, `actions` at the right edge.
+  title?: string;
+  recordTitle?: string; // Name of the loaded record; shown as an extra breadcrumb before the last one.
+  status?: ReactNode;
+  actions?: ReactNode;
+  overflowItems?: ActionMenuItemSpec[]; // Land in the shell header's overflow menu at phone width.
+  hideBreadcrumb?: boolean; // Hide the shell header's breadcrumb while mounted, for a screen that stands in for the one the route names (a locked screen's fallback).
+  breadcrumbScreenId?: string; // Label the breadcrumb with this screen (id as in the route) instead of the one the route names, for a locked screen's fallback.
+};
+type PickedFile = { // Platform-neutral view of a picked file; the DOM `File` satisfies it.
+  name: string;
+  size: number;
+  type: string;
+  webkitRelativePath: string;
+  arrayBuffer: () => Promise<ArrayBuffer>;
+};
+type ProgressProps = {
+  value: number;
+  tone?: ProgressTone;
+  ariaLabel?: string;
+  testId?: string;
+};
+type ProgressTone = "default" | "success" | "warn" | "danger"; // Determinate progress bar (e.g. wizard step progress).
+type PromoPanelAction =
+  | {
+    label: string;
+    href: string;
+    testId?: string;
+  }
+  | {
+    label: string;
+    onClick: () => void;
+    testId?: string;
+  }
+;
+type PromoPanelProps = { // Offer surface for upsells (e.g. "create an account"): its own tinted panel with eyebrow, headline, benefit content and one call to action, so an offer never reads like an info or error banner.
+  title: string;
+  eyebrow?: string;
+  children?: ReactNode;
+  action?: PromoPanelAction;
+  testId?: string;
+};
+type SecretRevealProps = { // One-time secret reveal — mint-form confirm phase.
+  values: SecretRevealValue[];
+  copyLabel: string;
+  copiedLabel: string;
+  testId?: string;
+};
+type SecretRevealValue = { // One revealed value on a `secretMint` screen's confirm phase.
+  label: string;
+  value: string;
+  copyable: boolean;
+  multiline: boolean;
+  qr?: boolean; // Render `value` as a scannable QR code instead of monospaced text — for an otpauth://-style enrollment URI.
+};
+type ShareButtonProps = ({ target: "whatsapp"; phone?: string; } | { target: "system"; title?: string; url?: string; }) & { // Hands `text` to another app.
+  text: string;
+  label: string;
+  variant?: "primary" | "secondary";
+  className?: string; // Layout extras, merged via cn().
+  testId?: string;
+};
+type StatusBadgeOptionTone = StatusTone | "accent"; // Tones a select option can request: the status tones plus the brand `accent`.
+type StatusBadgeProps = { // Status pill.
+  value: string;
+  tone?: StatusBadgeOptionTone;
+  testId?: string;
+};
+type StatusTone = "ok" | "warn" | "bad" | "critical" | "muted";
+type StepBarProps = { // Wizard step overview — numbered chips, one per step label, with the active step highlighted.
+  steps: string[];
+  currentIndex: number;
+  compactLabel: string;
+  onStepSelect?: (index: number) => void;
+  doneSteps?: boolean[]; // Explicit done state per step index.
+  selectableSteps?: "done" | "all"; // "done" (default): only done steps are jump targets.
+  narrowLayout?: "label" | "steps"; // "label" (default) swaps the step row for `compactLabel` on narrow viewports; "steps" keeps the row there too — for short wizards whose labels fit a phone and whose done steps must stay tappable.
+  orientation?: "horizontal" | "vertical"; // "vertical" renders a step rail (from `lg`, with `compactLabel` as the single line below it) instead of the chip row.
+  heading?: string; // Vertical only: rail heading ("Step 4 of 6") and optional description.
+  description?: string;
+  subtitles?: (string | undefined)[]; // Vertical only: line under each step label, same order as `steps`.
+  upNext?: {
+    heading: string;
+    title: string;
+    subtitle?: string;
+  }; // Vertical only: box under the rail announcing the next step.
+  testId?: string;
+  compactTestId?: string;
+};
+type StickyActionBarProps = { // Thumb-reach action row for custom screens: pinned to the bottom edge on narrow viewports (above the device's safe-area inset), inline otherwise.
+  children: ReactNode;
+  back?: {
+    onBack: () => void;
+    label: string;
+  };
+  testId?: string;
+};
+type TabsProps = { // Tab strip for a projectionDetail `layout.mode: "tabs"`.
+  items: { id: string; label: string; count?: number; }[];
+  activeId: string;
+  onSelect: (id: string) => void;
+  testId?: string;
+};
+type TrailingInputAction = {
+  icon: "clear" | "undo";
+  label: string;
+  onPress: () => void;
+  testId?: string;
+};
+type WizardStepGroupProps = { // Wraps a single wizard step so it stays mounted but inert while off- screen — `hidden` visually hides it, and implementations that have a native constraint-validation concept (web: `<fieldset disabled>`, spec- guaranteed to also bar descendants from participating) must bar it too, or a `type="submit"` step-advance button triggers the browser's full-form check against fields on unvisited, unfocusable steps.
+  hidden: boolean;
+  inset?: boolean; // Pads the step content (tab panels sit full-bleed under the tab strip).
+  children: ReactNode;
+};
+```
+
+## packages/renderer/src/web/app/client-plugin.tsx
+
+```ts
+type CollectionNavProviders = { // What a `navProvidersFromCollections` factory returns: the providers plus the entities whose live events should re-fire them.
+  providers: Readonly<Record<string, TreeChildrenSubscribe>>;
+  entities?: Readonly<Record<string, string[]>>;
+};
+```
+
+## packages/renderer/src/web/app/create-app.tsx
+
+```ts
+type BoundaryErrorContext = {
+  errorId: string;
+  screen?: string; // Qualified name of the screen whose boundary caught the error; absent for the root boundary.
+};
+type BoundaryErrorHandler = (error: Error, info: ErrorInfo, context: BoundaryErrorContext) => void;
+```
+
+## packages/renderer/src/web/app/resolvers-context.tsx
+
+```ts
+type ResolverComponent = ComponentType<{ target: TargetRef; onClose: () => void; }>;
+```
+
+## packages/renderer/src/web/layout/default-app-shell.tsx
+
+```ts
+type DefaultAppShellUser = {
+  id: string;
+  roles: string[];
+};
+```
+
+## packages/renderer/src/web/layout/sidebar-panel.tsx
+
+```ts
+type SidebarPanelProps = {
+  children: ReactNode;
+  defaultWidth?: number; // Initial width in px.
+  minWidth?: number;
+  maxWidth?: number;
+  storageKey?: string; // localStorage key for the dragged width.
+  className?: string;
+  tone?: "nav" | "surface"; // "nav" (default) matches the shell's own sidebar chrome.
+};
+```
+
+## packages/renderer/src/web/lib/file-upload-form-data.ts
+
+```ts
+type FileUploadFormDataInput = {
+  file: Blob;
+  entityType?: string | undefined;
+  entityId?: string | undefined;
+  fieldName?: string | undefined;
+  actionForm?: string | undefined; // Screen QN of an actionForm: the upload is pending for that form's field, not for an entity.
+};
+```
+
+## packages/renderer/src/web/primitives/form.tsx
+
+```ts
+type FormScreenShellWidth = FormWidth;
+```
+
+## packages/renderer/src/web/primitives/layout.tsx
+
+```ts
+type PageSectionProps = {
+  className?: string;
+  children?: ReactNode;
+  testId?: string;
+  maxWidth?: ScreenWidth;
+};
+type ScreenWidth = FormWidth;
+type StackGap = keyof typeof STACK_GAP;
+type StackProps = {
+  gap?: StackGap;
+  className?: string;
+  children?: ReactNode;
+  testId?: string;
+};
+```
+
+## packages/renderer/src/web/primitives/toast.tsx
+
+```ts
+type ToastApi = {
+  toast: (opts: ToastOptions) => void;
+};
+```
+
+## packages/renderer/src/web/sse/live-events.ts
+
+```ts
+type LiveEventTimers = {
+  set: (callback: () => void, delayMs: number) => () => void; // Schedules the callback and returns a function that cancels it.
+};
+```
+
+## packages/renderer/src/web/widgets/ai-text-field.tsx
+
+```ts
+type AiTextAction = "correct" | "translate" | "rewrite";
+interface AiTextFieldBaseProps {
+  label: string;
+  id: string;
+  name: string;
+  value: string;
+  onChange: (v: string) => void;
+  required?: boolean;
+  disabled?: boolean;
+  placeholder?: string;
+  testId?: string;
+  hideLabel?: boolean;
+  completion?: boolean; // Ghost-text completion on/off.
+  completionDebounceMs?: number; // Debounce for ghost-text requests, ms.
+  actions?: AiTextAction[]; // Toolbar actions to expose.
+  translateLanguages?: string[]; // Target languages the translate action offers.
+}
+```
+
+## packages/renderer/src/web/widgets/chart-data.ts
+
+```ts
+type ChartMarker = {
+  atMs: number;
+  label: string;
+  color?: string; // Colors the pin and, on StackedAreaChart, draws a dashed guide line in the plot.
+  legendLabel?: string; // Translated by the caller.
+};
+```
+
+## packages/renderer/src/web/widgets/form-fields.tsx
+
+```ts
+interface FieldBase {
+  label: string;
+  id: string;
+  name: string;
+  required?: boolean;
+  disabled?: boolean;
+  hideLabel?: boolean;
+  testId?: string;
+}
+```
+
+## packages/renderer/src/web/widgets/public-shell.tsx
+
+```ts
+type PublicShellCommonProps = {
+  brand: ReactNode;
+  headerActions?: ReactNode;
+  footer?: ReactNode;
+  children: ReactNode;
+  testId?: string;
+};
+```
+
+## packages/renderer/src/web/widgets/result-panel.tsx
+
+```ts
+interface ResultTableFooterRow {
+  label: string;
+  value: ReactNode;
+  emphasize?: boolean;
+}
+```
+
+## packages/testing/src/bundled-injection.ts
+
+```ts
+type InboxMessage = {
+  to: string;
+  subject: string;
+  html: string;
+  text?: string;
+  from?: string;
+  fromName?: string;
+  replyTo?: string;
+  headers?: Readonly<Record<string, string>>;
+};
+```
+
+## packages/testing/src/e2e/seed-route.ts
+
+```ts
+type E2eExtraSeeder = (ctx: E2eSeederContext, tenantId: TenantId, body: unknown) => Promise<unknown>;
+type E2eSeedRoutesOptions = {
+  extraRoles?: string[];
+  extraSeeders?: Readonly<Record<string, E2eExtraSeeder>>;
+  mailOutbox?: {
+    sent: InboxMessage[];
+  };
+};
+type E2eSeederContext = {
+  write: (handlerQn: string, payload: unknown) => Promise<unknown>;
+  query: (handlerQn: string, payload: unknown) => Promise<unknown>;
+  writeAs: (roles: string[], handlerQn: string, payload: unknown) => Promise<unknown>;
+};
+```
+
+## packages/testing/src/helpers/access-assertions.ts
+
+```ts
+type CheckedHandlerCounts = {
+  checkedWriteHandlers: number;
+  checkedQueryHandlers: number;
+};
+```
+
+## packages/testing/src/helpers/closed-connection-error.ts
+
+```ts
+type AdminClient = {
+  unsafe(sql: string, params?: unknown[]): Promise<unknown>;
+};
+```
+
+## packages/testing/src/helpers/event-store-writes.ts
+
+```ts
+type ExecutorArgs = Parameters<typeof createEventStoreExecutor>;
+```
+
+## packages/testing/src/helpers/manual-clock.ts
+
+```ts
+type ClockStep = {
+  hours?: number;
+  minutes?: number;
+  seconds?: number;
+  milliseconds?: number;
+};
+```
+
+## packages/testing/src/helpers/seed.ts
+
+```ts
+type SeedTable = EntityTable | EntityTableMeta;
+```
+
+## packages/testing/src/helpers/sse-frames.ts
+
+```ts
+type ReadSseFramesOptions = {
+  until: (frame: SseFrame, all: SseFrame[]) => boolean;
+  skipPings?: boolean;
+  timeoutMs?: number;
+};
+```
+
+## packages/testing/src/seed-tenant.ts
+
+```ts
+type InProcessSeededTenant = SeededTenant & {
+  unsubscribeSse: () => void;
+};
+type PersistedTenant = {
+  id: TenantId;
+  key: string;
+  name: string;
+  admin: SeededCredentials;
+  members: SeededCredentials[];
+};
+type SavedRow = {
+  id: string;
+  data: {
+    version: number;
+  };
+};
+type SeedWriter = (handlerQn: string, payload: unknown, tenantId: TenantId) => Promise<SavedRow>;
+```
+
+## packages/testing/src/seed-types.ts
+
+```ts
+type BoundApi = {
+  writeOk: <T = Record<string, unknown>>(type: string, payload: unknown, requestId?: string) => Promise<T>;
+  writeErr: (type: string, payload: unknown) => Promise<WriteErrorInfo>;
+  queryOk: <T = unknown>(type: string, payload: unknown) => Promise<T>;
+  queryErr: (type: string, payload: unknown) => Promise<WriteErrorInfo>;
+};
+type SeedAdminIdentity = {
+  displayName?: string;
+  email?: string;
+};
+type SeedPart = (ctx: { tenant: SeededTenant; }) => Promise<void>;
+type SeedTenantOptions = {
+  name?: string;
+  users?: number;
+  with?: SeedPart[];
+  persist?: boolean;
+  admin?: SeedAdminIdentity;
+};
+type SeededCredentials = {
+  id: string;
+  email: string;
+  password: string;
+};
+type SeededTenant = {
+  id: TenantId;
+  key: string;
+  name: string;
+  admin: SeededUser;
+  members: SeededUser[];
+  addUser: (roles?: string[], identity?: SeedAdminIdentity) => Promise<SeededUser>;
+  api: BoundApi;
+  apiAs: (user: SeededUser) => BoundApi;
+};
+type SeededUser = SeededCredentials & {
+  session: SessionUser;
+  mfaTotpSecret?: string;
+};
+```
+
+## packages/testing/src/stack/push-entity-projection-tables.ts
+
+```ts
+type DbHolder = {
+  db: DbConnection;
+  unscopedDb?: DbConnection;
+};
+```
+
+## packages/testing/src/stack/redis.ts
+
+```ts
+type CreateTestRedisOptions = {
+  borrowKeyPrefix?: string; // Reuse another stack's keyPrefix on a fresh connection.
+};
+```
+
+## packages/testing/src/stack/request-helper.ts
+
+```ts
+type BatchCommand = {
+  type: string;
+  payload: unknown;
+};
+type RequestHelperOptions = {
+  sessionCreator?: SessionCreator;
+};
+```
+
+## packages/types/src/aggregate-types.ts
+
+```ts
+type AggregateDimension =
+  | {
+    field: string;
+  }
+  | {
+    field: string;
+    bucket: AggregateTimeBucket;
+    timeZone: string;
+  }
+;
+type AggregateKey = string | number | boolean | null;
+type AggregateMeasure =
+  | {
+    fn: "count";
+  }
+  | {
+    fn: "countDistinct" | "sum" | "avg";
+    field: string;
+  }
+;
+type AggregateRow = {
+  keys: AggregateKey[];
+  value: number | null;
+};
+type AggregateSpec = {
+  measure: AggregateMeasure;
+  groupBy?: AggregateDimension[];
+  orderByValue?: "asc" | "desc";
+  orderByKeys?: "asc" | "desc"; // Direction of the group-key ordering (default asc).
+  limit?: number;
+};
+type AggregateTimeBucket = "hour" | "day";
+```
+
+## packages/types/src/cache-sync-types.ts
+
+```ts
+type CacheSyncBus = {
+  publish(topic: string, message: unknown, options?: CacheSyncPublishOptions): void;
+  subscribe(topic: string, listener: (message: unknown) => void): () => void;
+  onResync(listener: () => void): () => void;
+};
+type CacheSyncPublishOptions = {
+  remoteOnly?: boolean;
+};
+type ClosableCacheSyncBus = CacheSyncBus & {
+  close(): Promise<void>;
+};
+```
+
+## packages/types/src/concurrency-mode.ts
+
+```ts
+type ConcurrencyMode = "parallel" | "skip" | "replace" | "sequential" | "debounce";
+```
+
+## packages/types/src/config.ts
+
+```ts
+type ConfigBacking = "config" | "secrets";
+type ConfigBounds = {
+  min?: number;
+  max?: number;
+};
+type ConfigComputedContext = {
+  tenantId: TenantId;
+  userId: string;
+  db: DbConnection | TenantDb;
+};
+type ConfigComputedFn<T extends ConfigKeyType = ConfigKeyType> = (ctx: ConfigComputedContext) => Promise<ConfigValue<T>>;
+type ConfigKeyAccess = {
+  read: string[];
+  write: string[];
+};
+type ConfigMask = {
+  title: string;
+  description?: string; // i18n key for help text shown under the field label.
+  icon?: NavIconKey;
+  order?: number;
+};
+type ConfigSeedDef = {
+  key: string;
+  value: string | number | boolean;
+  scope?: ConfigScope;
+  tenantId?: string;
+  userId?: string;
+};
+type ConfigStoredRow = {
+  id: string;
+  key: string;
+  value: string | null;
+  tenantId: string;
+  userId: string | null;
+};
+type ConfigValidateContext = {
+  key: string;
+  scope: ConfigScope;
+  tenantId: TenantId;
+  userId: string | null;
+  db: TenantDb;
+  readCascade: (qualifiedKey: string) => Promise<ConfigCascade>;
+};
+type CreateSeedOptions = {
+  value: string | number | boolean;
+};
+type CreateTenantSeedOptions = {
+  tenantId?: string;
+};
+type ExtensionSelectorDef = {
+  extensionName: string;
+  qualifiedKey: string;
+  panels?: ExtensionSelectorPanel[];
+};
+type ExtensionSelectorPanel = DashboardCustomPanel | Omit<DashboardScreenPanel, "label">;
+type JobBackoff =
+  | JobBackoffStrategy
+  | {
+    type: JobBackoffStrategy;
+    delayMs?: number | undefined;
+  }
+;
+type JobBackoffStrategy = "fixed" | "exponential";
+type JobRunIn = Exclude<RunIn, "both">;
+type MaxPerTenantOptions = {
+  limit: number;
+  onLimit: "skip" | "defer";
+  deferMs?: number | undefined;
+};
+type NotificationDataFn = (result: SaveContext) => Record<string, unknown>;
+type NotificationRecipientFn = (result: SaveContext) => string | string[] | { tenant: string; } | null;
+type NotificationTemplateFn = (data: Record<string, unknown>) => Record<string, unknown>;
+type PluralForms = {
+  zero?: string;
+  one?: string;
+  two?: string;
+  few?: string;
+  many?: string;
+  other: string;
+};
+type RegistrarExtensionDef = {
+  onRegister?: (entityName: string, options?: Record<string, unknown>) => void;
+  extendSchema?: (entityName: string) => Record<string, EntityFieldDefinition>;
+  hooks?: RegistrarExtensionHooks;
+  extendSearch?: (entityName: string) => Record<string, unknown>;
+  uiExtension?: UiExtensionDef;
+};
+type RegistrarExtensionHooks = {
+  preSave?: PreSaveHookFn;
+  postSave?: PostSaveHookFn;
+  preDelete?: PreDeleteHookFn;
+  postDelete?: PostDeleteHookFn;
+};
+type RegistrarExtensionRegistration = {
+  extensionName: string;
+  entityName: string;
+  options?: Record<string, unknown> | undefined;
+  featureName?: string;
+};
+type RunIn = "api" | "worker" | "both";
+type TemplateImagesVariableDef = TemplateVariableCommon & {
+  type: "images";
+};
+type TemplateVariableCommon = {
+  label?: string;
+  required?: boolean;
+};
+type TranslationsDef = {
+  keys: TranslationKeys;
+};
+type UiExtensionDef = {
+  editSection?: string;
+  listColumns?: string;
+  filters?: string;
+};
+```
+
+## packages/types/src/cursor-types.ts
+
+```ts
+type CursorResult<T> = {
+  rows: T[];
+  nextCursor: string | null;
+  total?: number; // Optional total row count — only present when the caller sets `totalCount: true` on the query.
+  searchTruncated?: true; // Set when the search backend returned as many candidates as it can in one response, so matches beyond that may be missing from `rows`.
+};
+```
+
+## packages/types/src/db-connection.ts
+
+```ts
+type PgClient = SQL;
+type PgListenClient = {
+  listen(channel: string, onnotify: (payload: string) => void, onlisten?: () => void): Promise<PgListenSubscription>;
+};
+type PgListenSubscription = {
+  unlisten(): Promise<void>;
+};
+type RawDbClient = {
+  unsafe: (sql: string, params?: unknown[]) => PromiseLike<unknown[]>;
+  begin: <T>(fn: (tx: DbTx) => Promise<T>) => Promise<T>;
+  end?: (options?: { timeout?: number; }) => Promise<void>;
+};
+```
+
+## packages/types/src/define-handler.ts
+
+```ts
+type StreamHandlerDefinition<TName extends string = string, TSchema extends ZodType = ZodType, TChunk = unknown, TMap extends object = KumikoEventTypeMap> = {
+  name: TName;
+  schema: TSchema;
+  access: AccessRule;
+  rateLimit?: RateLimitDeclaration;
+  escapeHatch?: EscapeHatchDeclaration;
+  handler: (query: QueryEvent<z.infer<TSchema>>, context: HandlerContext<TMap>) => AsyncGenerator<TChunk>;
+};
+```
+
+## packages/types/src/derivatives-types.ts
+
+```ts
+type BlurRegion = {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+};
+type DerivativeRendererPlugin = {
+  render: (input: Uint8Array, spec: VariantSpec, sourceMimeType: string) => Promise<Uint8Array>;
+};
+type DerivativesContext = {
+  variant: (fileRefId: string, spec: VariantSpec, name: string) => Promise<VariantResult>;
+};
+type OverlayGravity = "north-west" | "north-east" | "south-west" | "south-east" | "center";
+type OverlayLayer = ({ kind: "qr"; dataToken: string; } & OverlayPlacement) | ({ kind: "image"; imageBase64: string; } & OverlayPlacement);
+type OverlayPlacement = {
+  widthPct: number;
+  gravity: OverlayGravity;
+  marginPct?: number;
+};
+type ResolvedOverlayLayer = ({ kind: "qr"; data: string; } & OverlayPlacement) | Extract<OverlayLayer, { kind: "image"; }>;
+type VariantFit = "cover" | "inside" | "contain";
+type VariantFormat = "webp" | "avif" | "jpeg";
+type VariantResult = {
+  storageKey: string;
+  mimeType: string;
+  rendered: boolean;
+};
+type VariantSpec = {
+  fit?: VariantFit;
+  size?: {
+    width: number;
+    height: number;
+  };
+  maxEdge?: number;
+  format?: VariantFormat;
+  quality?: number;
+  blur?: number;
+  blurRegions?: BlurRegion[];
+  overlays?: OverlayLayer[];
+  resolvedOverlays?: ResolvedOverlayLayer[];
+};
+```
+
+## packages/types/src/entity-cache.ts
+
+```ts
+type EntityCache = {
+  get(tenantId: TenantId, entityName: string, id: EntityId): Promise<Record<string, unknown> | null>; // Get a single cached entity.
+  mget(tenantId: TenantId, entityName: string, ids: EntityId[]): Promise<Map<EntityId, Record<string, unknown>>>; // Get multiple cached entities.
+  set(tenantId: TenantId, entityName: string, id: EntityId, data: Record<string, unknown>): Promise<void>; // Cache a single entity.
+  mset(tenantId: TenantId, entityName: string, entries: ReadonlyArray<{ id: EntityId; data: Record<string, unknown>; }>): Promise<void>; // Cache multiple entities at once.
+  del(tenantId: TenantId, entityName: string, id: EntityId): Promise<void>; // Invalidate a single cached entity.
+};
+```
+
+## packages/types/src/entity-handlers.ts
+
+```ts
+type EntityCrudHandlerDefaults = Omit<EntityHandlerOptions, "access"> & {
+  access?: AccessRule;
+};
+type EntityCrudVerb = "create" | "update" | "delete" | "restore" | "list" | "detail";
+type EntityHandlerOptions = {
+  access: AccessRule;
+  description?: string;
+  agent?: AgentHandlerHints;
+  escapeHatch?: EscapeHatchDeclaration; // Lifts row filtering for this ONE handler across every tenant instead of the caller's own — for a SystemAdmin-only operator handler over an otherwise tenant-scoped entity.
+};
+type EntityQueryHandlerOptions = EntityHandlerOptions;
+type EntityWriteHandlerOptions = EntityHandlerOptions & { // Options for the generic create/update handlers.
+  excludeFields?: string[]; // Fields this handler never writes.
+};
+type RegisterEntityCrudOptions = {
+  write?: EntityCrudHandlerDefaults;
+  read?: EntityCrudHandlerDefaults;
+  verbs?: Partial<Record<EntityCrudVerb, boolean>>;
+  verbAccess?: Partial<Record<EntityCrudVerb, AccessRule>>; // Per-verb access override — falls back to `write.access`/`read.access` when unset for a verb.
+  descriptions?: Partial<Record<EntityCrudVerb, string>>; // Per-verb `description` — the author writes one sentence per verb; the AI-agent manifest exposes only the verbs described here (fail-closed, same rule as hand-written handlers).
+  agents?: Partial<Record<EntityCrudVerb, AgentHandlerHints>>; // Per-verb agent hints; win over `write.agent`/`read.agent`, so one irreversible verb (e.g. a hard delete) can be `risk: "high"` without raising create/update.
+  excludeFields?: Partial<Record<"create" | "update", string[]>>; // Per-verb `excludeFields` for the generic create/update handlers — see EntityWriteHandlerOptions.
+  registerEntity?: boolean; // Default true.
+};
+```
+
+## packages/types/src/entity-table-meta-types.ts
+
+```ts
+type BuildEntityTableMetaOptions = {
+  featureName?: string;
+  relations?: EntityRelations;
+  source?: EntityTableMeta["source"];
+};
+type CompositePrimaryKeyMeta = {
+  name: string;
+  columns: string[];
+};
+type IndexMeta = {
+  name: string;
+  columns: string[];
+  unique?: boolean;
+  whereSql?: string;
+  needsManualWhere?: boolean;
+};
+type PgType = "uuid" | "text" | "boolean" | "integer" | "double precision" | "bigint" | "serial" | "bigserial" | "jsonb" | "timestamptz" | "timestamptz(3)" | "date" | `numeric(${number},${number})`;
+type UnmanagedTableInput = {
+  tableName: string;
+  columns: ColumnMeta[];
+  indexes?: IndexMeta[];
+  compositePrimaryKey?: CompositePrimaryKeyMeta;
+  tenancy?: EntityTenancy;
+};
+```
+
+## packages/types/src/envelope-cipher-types.ts
+
+```ts
+type EnvelopeCipher = {
+  encrypt(plaintext: string, scope?: KeyScope): Promise<string>;
+  decrypt(stored: string, scope?: KeyScope): Promise<string>;
+};
+```
+
+## packages/types/src/event-store-executor-types.ts
+
+```ts
+type ListAggregateRequest = {
+  search?: string | undefined;
+  filter?: ListFilterOption | undefined;
+  filters?: ListFilterOption[] | undefined;
+  aggregate: ListAggregatePayload;
+};
+type ListFilterOption = {
+  field: string;
+  op: "eq" | "ne" | "lt" | "gt" | "lte" | "gte" | "in";
+  value: unknown;
+};
+type ListRuntimeOptions = {
+  searchAdapter?: SearchAdapter;
+  includeDeleted?: boolean;
+  referenceSearch?: {
+    fields: ReadonlyArray<{ fieldName: string; targetEntityName: string; labelField: string; }>;
+    resolveEntity: (entityName: string) => EntityDefinition | undefined;
+  };
+  referenceSort?: {
+    fields: ReadonlyArray<{ fieldName: string; targetEntityName: string; labelField: string; }>;
+    resolveEntity: (entityName: string) => EntityDefinition | undefined;
+  };
+  parentVisibility?: ParentVisibilityOption;
+};
+type LockGuardOption = {
+  unsafeSkipLockGuard?: boolean;
+  writePurpose?: WritePurpose;
+};
+type ParentVisibilityGateOption = {
+  parentVisibility?: ParentVisibilityOption;
+};
+type ParentVisibilityOption = {
+  entities: ReadonlyMap<string, EntityDefinition>;
+};
+type PreSaveRunner = (changes: Record<string, unknown>, previous: Readonly<Record<string, unknown>>, isNew: boolean) => Promise<Record<string, unknown>>;
+type StreamTenantOption = {
+  streamTenantId?: TenantId | undefined;
+};
+```
+
+## packages/types/src/event-store-types.ts
+
+```ts
+type WriteOrigin = {
+  rootHandler: string;
+  anonymousRoot: boolean;
+  publicIntake: boolean;
+  viaJob?: string;
+};
+```
+
+## packages/types/src/executor-brand.ts
+
+```ts
+interface ExecutorManagedWriteCapability {
+  [EXECUTOR_MANAGED_WRITE]: true;
+}
+interface Writable {
+  [WRITABLE]: true;
+}
+```
+
+## packages/types/src/feature-registrar.ts
+
+```ts
+type EntityObjectDefinition = EntityDefinition & {
+  name: string;
+  backingTable?: unknown;
+};
+type HookDefinition =
+  | {
+    type: "validation";
+    target: RefOrRefs;
+    handler: ValidationHookFn;
+    escapeHatch?: never;
+    phase?: never;
+  }
+  | ({ type: "preSave"; target: RefOrRefs; handler: PreSaveHookFn; phase?: never; } & HookEscapeHatch)
+  | ({ type: "postSave"; target: HookTarget; handler: PostSaveHookFn; } & HookEscapeHatch & HookPhaseOption)
+  | ({ type: "preDelete"; target: HookTarget; handler: PreDeleteHookFn; phase?: never; } & HookEscapeHatch)
+  | ({ type: "postDelete"; target: HookTarget; handler: PostDeleteHookFn; } & HookEscapeHatch & HookPhaseOption)
+  | ({ type: "postQuery"; target: HookTarget; handler: PostQueryHookFn; phase?: never; } & HookEscapeHatch)
+;
+type HookEscapeHatch = {
+  escapeHatch?: EscapeHatchDeclaration;
+};
+type HookPhaseOption = {
+  phase?: HookPhase;
+};
+type HookTarget =
+  | RefOrRefs
+  | {
+    allOf: NameOrRef;
+  }
+;
+type RefOrRefs = NameOrRef | NameOrRef[];
+type RequiresApi = ((options: { features: string[]; }) => void) & { // `r.requires({ features })` declares the features this one depends on; the `.projection` extension declares read-side projection tables that this feature's pipeline steps are allowed to write via `r.step.unsafeProjectionUpsert` (hard-required for any unsafeProjection-* step usage, see Q10).
+  projection: (tableName: string) => void;
+  step: (stepKind: string) => void;
+};
+```
+
+## packages/types/src/feature.ts
+
+```ts
+type BootCheckContext = {
+  features: FeatureDefinition[];
+};
+type BootCheckFn = (ctx: BootCheckContext) => void;
+type FeatureMetricDef = {
+  shortName: string;
+  type: FeatureMetricType;
+  description?: string;
+  labels?: string[];
+  buckets?: number[];
+  unit?: string;
+  tenantLabel?: boolean;
+};
+type FeatureMetricType = "counter" | "histogram" | "gauge";
+type MetricOptions = Omit<FeatureMetricDef, "shortName">;
+type SecretOptions = Omit<SecretKeyDefinition, "shortName" | "qualifiedName">;
+type StackBootRequirement = {
+  stack: string;
+  options: BootOptionName[];
+  severity?: "error" | "warn"; // `"warn"`: a missing option logs a boot warning instead of aborting.
+};
+type StoreTableDef = StoreTableEntry & { // Registry-aggregated store-table — the per-feature `StoreTableEntry` plus the owning feature name.
+  featureName: string;
+};
+type StoreTableEntry = { // Per-feature store-table registration.
+  name: string;
+  meta: EntityTableMeta;
+  reason: string;
+  piiEncryptedOnWrite?: true;
+};
+type StoreTableOptions = { // Options accepted by `r.storeTable()`.
+  reason: string; // Why this table needs to bypass the event-sourcing system.
+  piiEncryptedOnWrite?: true; // Direct-write stores skip the executor, so the executor's PII encryption never runs for them — a feature whose meta carries piiSubjectFields must encrypt those fields itself before every insert/update and declare that here, or boot fails.
+};
+type UiHintOption = {
+  key: string;
+  label: string;
+  type: "boolean";
+  default: boolean;
+};
+type UiHints = {
+  displayLabel?: string;
+  category?: string;
+  recommended?: boolean;
+  configurableOptions?: UiHintOption[];
+};
+```
+
+## packages/types/src/fields-derived.ts
+
+```ts
+type DerivedFieldDef = {
+  valueType: DerivedValueType;
+  derive: (row: Readonly<Record<string, unknown>>, ctx: DeriveContext) => unknown; // Pure function of the stored row + clock.
+};
+type DerivedFieldsMap = Readonly<Record<string, DerivedFieldDef>>;
+type DerivedValueType = "text" | "number" | "decimal" | "boolean" | "date" | "timestamp"; // Display type a derived value formats as — drives the column's renderer choice in the view-model, parallel to FieldDefinition["type"].
+```
+
+## packages/types/src/fields.ts
+
+```ts
+type BigIntFieldDef = ResolvedPiiFlags & { // 64-bit integer field for audit counters, byte sizes, event IDs, and other values that can exceed 2^31 (~2.1 billion).
+  type: "bigInt";
+  description?: string;
+  required?: boolean;
+  sortable?: boolean;
+  sortNulls?: SortNulls;
+  filterable?: boolean;
+  sensitive?: boolean;
+  default?: number;
+  access?: FieldAccess;
+};
+type BooleanFieldDef = {
+  type: "boolean";
+  description?: string;
+  required?: boolean;
+  sortable?: boolean;
+  sortNulls?: SortNulls;
+  filterable?: boolean;
+  sensitive?: boolean;
+  default?: boolean;
+  access?: FieldAccess;
+};
+type DateFieldDef = ResolvedPiiFlags & {
+  type: "date";
+  description?: string;
+  required?: boolean;
+  sortable?: boolean;
+  sortNulls?: SortNulls;
+  filterable?: boolean;
+  sensitive?: boolean;
+  access?: FieldAccess;
+  min?: string; // Permitted date bounds as ISO `yyyy-mm-dd` (for example, a birth date cannot be in the future when `max` is today).
+  max?: string;
+  locale?: string; // Format/locale override for display and input parsing (for example, "de-DE").
+};
+type DecimalFieldDef = ResolvedPiiFlags & { // Exact decimal — Postgres `numeric(precision, scale)`.
+  type: "decimal";
+  description?: string;
+  precision: number;
+  scale: number;
+  required?: boolean;
+  sortable?: boolean;
+  sortNulls?: SortNulls;
+  filterable?: boolean;
+  sensitive?: boolean;
+  default?: number;
+  access?: FieldAccess;
+};
+type EmbeddedFieldDef = ResolvedPiiFlags & {
+  type: "embedded";
+  description?: string;
+  required?: boolean;
+  sensitive?: boolean;
+  schema: Readonly<Record<string, EmbeddedSubFieldDef>>;
+  access?: FieldAccess;
+  multiple?: boolean; // A list of like-shaped objects instead of exactly one: the value is an array and every element is validated against `schema`.
+  minItems?: number; // Minimum row count for an embedded list.
+  maxItems?: number; // Maximum row count for an embedded list.
+  derived?: Readonly<Record<string, EmbeddedDerivedCellDef>>; // Renderer metadata: sub-field name → how to compute its cell from other sub-fields of the same row, rounded to that sub-field's declared precision.
+  totals?: EmbeddedTotalDef[]; // Renderer metadata: footer totals.
+  totalsMatch?: Readonly<Record<string, string>>; // Maps an embedded-list subfield name to a sibling top-level money field name — the sum of that subfield across all rows must equal the sibling field's amount.
+};
+type EmbeddedSubFieldBase = {
+  required?: boolean;
+  searchable?: boolean;
+  access?: FieldAccess;
+};
+type EmbeddedSubFieldDef = (EmbeddedSubFieldBase & { type: "text" | "number" | "boolean" | "date" | "money" | "timestamp"; }) | (EmbeddedSubFieldBase & { type: "decimal"; scale: number; }) | (EmbeddedSubFieldBase & { type: "select"; options: string[]; display?: "radio" | "dropdown"; }) | (EmbeddedSubFieldBase & { type: "reference"; entity: string; labelField?: string; optionsQuery?: string; }); // `money` is a signed integer amount in minor units (cents); which currency it means is defined by the owning aggregate (a head-level field or tenant config), not per row.
+type EmbeddedTotalDef =
+  | string
+  | {
+    label: string;
+    from: string[];
+  }
+;
+type EntityEventMigration = {
+  fromVersion: number;
+  toVersion: number;
+  transform: (fields: Readonly<Record<string, unknown>>, ctx: EventUpcastCtx) => Record<string, unknown> | Promise<Record<string, unknown>>;
+};
+type EntityFieldDefinition = Exclude<FieldDefinition, TextFieldDef | LongTextFieldDef> | EntityTextFieldDef | EntityLongTextFieldDef;
+type EntityIndexDef = { // Composite index on an entity.
+  columns: [ string, ...string[] ];
+  unique?: boolean;
+  name?: string;
+  where?: unknown; // Optional SQL fragment for a partial index — `CREATE [UNIQUE] INDEX ...
+};
+type EntityLongTextFieldDef = LongTextFieldDef & ResolvedPiiStance;
+type EntityPiiAbsentSubject = "tenant" | "self";
+type EntityTextFieldDef = TextFieldDef & ResolvedPiiStance;
+type FieldAccess = {
+  read?: OwnershipMap | string[];
+  write?: OwnershipMap | string[];
+};
+type FieldsMap = Readonly<Record<string, EntityFieldDefinition>>;
+type FileFieldDef = ResolvedPiiFlags & {
+  type: "file";
+  description?: string;
+  required?: boolean;
+  maxSize?: string;
+  anonymousUpload?: boolean; // Anonymous visitors may upload into this field as a pending upload (no entityId); the app binds the file itself.
+  accept?: string[];
+  access?: FieldAccess;
+};
+type FilesFieldDef = ResolvedPiiFlags & {
+  type: "files";
+  description?: string;
+  maxSize?: string;
+  anonymousUpload?: boolean; // Anonymous visitors may upload into this field as a pending upload (no entityId); the app binds the file itself.
+  accept?: string[];
+  maxCount?: number;
+  display?: "list" | "dropzone"; // `"list"` (default) shows the picked files as a list with a file picker; `"dropzone"` shows a drag-and-drop zone with one status row per file, a remove action per file and the field's `maxCount`/`accept`/`maxSize` as hints.
+  access?: FieldAccess;
+};
+type Findability = "exact" | "fuzzy" | "none" | "secret";
+type FormFieldDefinition = Exclude<FieldDefinition, MoneyFieldDef> | (MoneyFieldDef & { currency: MoneyCurrencySource; }); // FieldDefinition as an entity-less inline form screen (actionForm, secretMint) may declare it: a `money` field there has no entity to borrow `defaultCurrency` from, so it must name its own currency source, or the form seeds a bare `0` that the handler's zod schema then rejects .
+type ImageFieldDef = ResolvedPiiFlags & {
+  type: "image";
+  description?: string;
+  required?: boolean;
+  maxSize?: string;
+  anonymousUpload?: boolean; // Anonymous visitors may upload into this field as a pending upload (no entityId); the app binds the file itself.
+  accept?: string[];
+  variants?: Readonly<Record<string, VariantSpec>>; // Named derived versions of the uploaded image.
+  capture?: "environment" | "user"; // Forwarded to the file input's `capture` attribute so a phone opens the camera instead of the file picker.
+  access?: FieldAccess;
+};
+type ImagesFieldDef = ResolvedPiiFlags & {
+  type: "images";
+  description?: string;
+  maxSize?: string;
+  anonymousUpload?: boolean; // Anonymous visitors may upload into this field as a pending upload (no entityId); the app binds the file itself.
+  accept?: string[];
+  maxCount?: number;
+  display?: "list" | "dropzone"; // `"list"` (default) shows the picked files as a list with a file picker; `"dropzone"` shows a drag-and-drop zone with one status row per file, a remove action per file and the field's `maxCount`/`accept`/`maxSize` as hints.
+  variants?: Readonly<Record<string, VariantSpec>>;
+  capture?: "environment" | "user"; // Forwarded to the file input's `capture` attribute so a phone opens the camera instead of the file picker.
+  access?: FieldAccess;
+};
+type JsonbEmptyValue = "object" | "array";
+type LocatedTimestampFieldDef = ResolvedPiiFlags & {
+  type: "locatedTimestamp";
+  description?: string;
+  required?: boolean;
+  sortable?: boolean;
+  sortNulls?: SortNulls;
+  filterable?: boolean;
+  sensitive?: boolean;
+  access?: FieldAccess;
+  min?: string; // Permitted bounds as ISO datetime values (wall-clock time).
+  max?: string;
+  locale?: string; // Format/locale override for display and input parsing.
+};
+type LongTextFieldDef = ResolvedPiiFlags & { // Long-form text content — source code, markdown, blog posts, email templates, and anything that can be megabytes large.
+  type: "longText";
+  description?: string;
+  maxLength?: number; // Optional soft cap.
+  required?: boolean;
+  encrypted?: boolean;
+  sensitive?: boolean;
+  readAsInstruction?: boolean; // A later run reads this field's value as an instruction — prompt, rule, template.
+  default?: string;
+  access?: FieldAccess;
+  multiline?: boolean | { rows?: number; };
+};
+type LongTextFindability = "none" | "secret";
+type MoneyCurrencySource = // Where a money field's currency comes from.
+  | {
+    kind: "tenant";
+  }
+  | {
+    kind: "literal";
+    code: string;
+  }
+;
+type MoneyFieldDef = {
+  type: "money";
+  description?: string;
+  required?: boolean;
+  sortable?: boolean;
+  sortNulls?: SortNulls;
+  filterable?: boolean;
+  sensitive?: boolean;
+  access?: FieldAccess;
+  currency?: MoneyCurrencySource; // Declares where this field's currency comes from for a currently-empty value in an entityEdit form.
+};
+type MultiSelectFieldDef<TOptions extends string[] = string[]> = ResolvedPiiFlags & {
+  type: "multiSelect";
+  description?: string;
+  options: TOptions;
+  required?: boolean;
+  filterable?: boolean;
+  sensitive?: boolean;
+  default?: TOptions[number][]; // Default selection.
+  access?: FieldAccess;
+  display?: "checkboxes" | "dropdown"; // Renderer metadata: `"checkboxes"` renders every option as a visible checkbox with a select-all toggle.
+  columns?: 1 | 2 | 3 | 4; // Renderer metadata: column count for the `"checkboxes"` grid at the widest breakpoint; narrow viewports always collapse to one column.
+  maxRows?: number; // Renderer metadata: how many grid rows stay visible before the `"checkboxes"` grid becomes scrollable.
+  optionsAvailabilityQuery?: string; // Query returning `{ rows: { value, disabled?, hint?
+};
+type NoPersonalAnnotation = {
+  personal?: never;
+  find?: never;
+  reason?: never;
+  anonymize?: never;
+};
+type NumberFieldDef = ResolvedPiiFlags & { // Storage: `integer` flag decides the Postgres column type, not just Zod validation.
+  type: "number";
+  description?: string;
+  required?: boolean;
+  sortable?: boolean;
+  sortNulls?: SortNulls;
+  filterable?: boolean;
+  sensitive?: boolean;
+  default?: number;
+  access?: FieldAccess;
+  min?: number;
+  max?: number; // Upper bound at the write boundary (Zod `.max`).
+  integer?: boolean; // `true` → `integer` column + `.int()` Zod validation.
+  unit?: string | { field: string; }; // Display-only suffix: a static string, or a sibling field name whose value supplies it.
+  grouping?: boolean; // Thousands-grouping in the rendered display (Intl `useGrouping`).
+};
+type OptionsQueryPayloadValue = // One `optionsQueryPayload` entry: a literal, or `{ field }` = the current value of a sibling field of the same form (config keys: another key of the owner feature).
+  | string
+  | number
+  | boolean
+  | {
+    field: string;
+  }
+;
+type ParentRefDef = {
+  entityTypeField: string; // Field holding the name of the host entity this row hangs off.
+  entityIdField: string; // Field holding the host row's id.
+  allowedTypes?: string[]; // Narrow which registered entities may act as host.
+};
+type PersonalAnnotations =
+  | {
+    personal: PersonalSubject;
+    find: Findability;
+    anonymize?: () => unknown | Promise<unknown>;
+  }
+  | {
+    personal: "ref";
+  }
+  | {
+    personal: false;
+    reason: string;
+    anonymize?: () => unknown | Promise<unknown>;
+  }
+;
+type PersonalAnnotationsLongText =
+  | {
+    personal: PersonalSubject;
+    find: LongTextFindability;
+    anonymize?: () => unknown | Promise<unknown>;
+  }
+  | {
+    personal: "ref";
+  }
+  | {
+    personal: false;
+    reason: string;
+    anonymize?: () => unknown | Promise<unknown>;
+  }
+;
+type PersonalAnnotationsNoFind =
+  | {
+    personal: PersonalSubject;
+    anonymize?: () => unknown | Promise<unknown>;
+  }
+  | {
+    personal: "ref";
+  }
+  | {
+    personal: false;
+    reason: string;
+    anonymize?: () => unknown | Promise<unknown>;
+  }
+  | NoPersonalAnnotation
+;
+type PersonalSubject =
+  | "self"
+  | {
+    of: string;
+    whenAbsent?: EntityPiiAbsentSubject;
+  }
+  | "tenant"
+;
+type ReferenceFieldDef = ResolvedPiiFlags & {
+  type: "reference";
+  description?: string;
+  entity: string;
+  required?: boolean;
+  filterable?: boolean;
+  sensitive?: boolean;
+  access?: FieldAccess;
+  labelField?: string; // Field of the referenced entity displayed as the Select dropdown label.
+  multiple?: boolean; // Multi-reference: the value is an array of UUIDs rather than a single UUID.
+  searchable?: true; // Include a row in this entity's result set on a text-search hit against the referenced entity's `labelField`, instead of only matching the UUID column itself.
+  sortable?: true; // Order a list by the referenced entity's `labelField` instead of by the raw UUID column.
+  sortNulls?: SortNulls;
+  optionsQuery?: string; // Fill the picker from this query handler instead of the referenced entity's own list handler — for targets whose identity is composed from joined rows, where no single column of the referenced entity is a readable label.
+  handover?: "stay"; // tenant-handover opt-out: rows of THIS entity that point at a handed-over row through this field stay in the source tenant instead of travelling with it (or failing the claim with `entity_not_transferable`).
+};
+type ResolvedPiiStance =
+  | {
+    pii: true;
+  }
+  | {
+    userOwned: NonNullable<ResolvedPiiFlags["userOwned"]>;
+  }
+  | {
+    tenantOwned: true;
+  }
+  | {
+    recordOwned: true;
+  }
+  | {
+    allowPlaintext: string;
+  }
+  | {
+    subjectRef: true;
+  }
+;
+type SelectConditionalOptions<TOption extends string = string> = { // Options of a select field that are only available while `when` holds for the row values.
+  options: TOption[];
+  when: Exclude<FieldCondition, boolean>;
+};
+type SelectFieldDef<TOptions extends string[] = string[]> = ResolvedPiiFlags & {
+  type: "select";
+  description?: string;
+  options: TOptions;
+  required?: boolean;
+  sortable?: boolean;
+  sortNulls?: SortNulls;
+  filterable?: boolean;
+  sensitive?: boolean;
+  default?: TOptions[number];
+  access?: FieldAccess;
+  display?: "radio" | "dropdown"; // Renderer metadata: `"radio"` always renders the option set as a visible radio group, `"dropdown"` always renders the combobox.
+  optionTones?: { [K in TOptions[number]]?: SelectOptionTone; }; // Status tone per option, shown as a toned badge with dot in lists and detail bands.
+  optionsQuery?: string; // Loads the options from this query (QN), labels shown verbatim: `{ rows: { value, label, description?, group?, default?
+  optionsQueryPayload?: OptionsQueryPayload; // Payload sent with every `optionsQuery` call.
+  optionsAvailabilityQuery?: string; // Marks static options as unavailable per tenant (e.g. by tier).
+  conditionalOptions?: SelectConditionalOptions<TOptions[number]>[]; // Options that are only available while `when` holds for the row values; options in no rule are always available.
+};
+type SortNulls = "first" | "last"; // Where rows without a value sort in a list, in both directions.
+type TimestampFieldDef = ResolvedPiiFlags & {
+  type: "timestamp";
+  description?: string;
+  required?: boolean;
+  sortable?: boolean;
+  sortNulls?: SortNulls;
+  filterable?: boolean;
+  sensitive?: boolean;
+  access?: FieldAccess;
+  locatedBy?: string; // Marker: this timestamp field represents wall-clock time at a location.
+  min?: string; // Permitted bounds as ISO datetime values.
+  max?: string;
+  locale?: string; // Format/locale override for display and input parsing.
+};
+type TransitionMap = Readonly<Record<string, string[]>>;
+type TzFieldDef = ResolvedPiiFlags & {
+  type: "tz";
+  description?: string;
+  required?: boolean;
+  sensitive?: boolean;
+  access?: FieldAccess;
+};
+```
+
+## packages/types/src/file-handle-types.ts
+
+```ts
+type FileContext = {
+  ref(key: string): FileHandle;
+  refFromFileRef(row: { storageKey: string; }): FileHandle;
+  listFromFileRef(row: { storageKey: string; }): Promise<string[]>;
+  list(prefix: string): Promise<string[]>;
+  writeUploadBytes(key: string, data: Uint8Array, mimeType: string): Promise<void>;
+  forgetUploadBytes(key: string): Promise<void>;
+};
+type FileHandle = {
+  key: string;
+  read(): Promise<Uint8Array>;
+  write(data: Uint8Array, mimeType?: string): Promise<void>;
+  delete(): Promise<void>;
+  exists(): Promise<boolean>;
+  derive(suffix: string): FileHandle;
+};
+```
+
+## packages/types/src/file-provider-resolver-types.ts
+
+```ts
+type FileProviderResolver = ((tenantId: TenantId) => Promise<FileStorageProvider>) & {
+  uploadLedgerFor?: (tenantId: TenantId) => FileUploadLedger;
+};
+type FileUploadLedger = {
+  record(storageKey: string): Promise<void>;
+  forget(storageKey: string): Promise<void>;
+};
+```
+
+## packages/types/src/file-storage-provider-types.ts
+
+```ts
+type FileStorageProvider = {
+  write(key: string, data: Uint8Array, mimeType?: string): Promise<void>;
+  writeStream(key: string, source: AsyncIterable<Uint8Array>, options?: WriteStreamOptions): Promise<void>;
+  read(key: string): Promise<Uint8Array>;
+  readStream(key: string): AsyncIterable<Uint8Array>;
+  delete(key: string): Promise<void>;
+  exists(key: string): Promise<boolean>;
+  list(prefix: string): Promise<string[]>;
+  getSignedUrl?(key: string, expiresInSeconds: number, options?: SignedUrlOptions): Promise<string>;
+};
+type SignedUrlOptions = {
+  contentDisposition?: string;
+};
+type WriteStreamOptions = {
+  mimeType?: string;
+  contentLength?: number;
+};
+```
+
+## packages/types/src/geo-tz.ts
+
+```ts
+type GeoAddress = {
+  street?: string;
+  city?: string;
+  region?: string;
+  postalCode?: string;
+  country?: string;
+};
+type GeoCoordinates = {
+  latitude: number;
+  longitude: number;
+};
+type GeoTzProvider = {
+  fromCoordinates: (coords: GeoCoordinates) => string | Promise<string>; // Geo-coordinates → IANA zone (offline lat/lng → tz).
+  fromAddress?: (address: GeoAddress) => string | Promise<string>; // Optional: postal address → IANA zone (geocoding API provider).
+};
+```
+
+## packages/types/src/handler-context-facets.ts
+
+```ts
+type PhaseWithoutTransaction = "events" | "notify" | "dispatch" | "lifecycle";
+```
+
+## packages/types/src/handler-context-services.ts
+
+```ts
+type ContextServices = { // Infrastructure the app wired at boot, as the handler or job sees it.
+  redis?: Redis;
+  cacheSync?: CacheSyncBus;
+  jobRunner?: JobRunnerRef;
+  searchAdapter?: SearchAdapter;
+  entityCache?: EntityCache;
+  secrets?: SecretsContext;
+  kms?: KmsAdapter;
+  files?: FileContext;
+  derivatives?: DerivativesContext;
+  configResolver?: ConfigResolver;
+  configEncryption?: EnvelopeCipher;
+  rateLimit?: RateLimitResolver;
+  effectiveFeatures?: (tenantId: TenantId) => ReadonlySet<string>;
+  masterKeyProvider?: MasterKeyProvider;
+  _fileProviderResolver?: FileProviderResolver;
+  _notifyFactory?: NotifyFactory;
+  _notifyInTransactionFactory?: (user: SessionUser, tenantId: TenantId) => NotifyFn;
+  _notifyAfterCommitFactory?: (user: SessionUser, tenantId: TenantId) => NotifyFn;
+  _escapeHatchAuditSink?: EscapeHatchAuditSink;
+  extensions: Readonly<Record<string, unknown>>;
+};
+type HandlerLifecycle = {
+  runPreSave?: (handlerName: string, changes: Record<string, unknown>, previous: Readonly<Record<string, unknown>>, isNew: boolean) => Promise<Record<string, unknown>>; // Runs the registered `preSave` hooks (and system preSave hooks) for `handlerName` and returns the hook-transformed `changes`.
+  afterCommit?: (hook: () => Promise<void>) => void; // Queues a side-effect to run after the outermost write transaction commits (same sink as ctx.dispatch.write).
+  afterRollback?: (hook: () => Promise<void>) => void; // Runs when the handler transaction (or enclosing savepoint) does not commit, also after a failed COMMIT of unknown outcome, so write it idempotent and outcome-safe.
+  signal?: AbortSignal; // Cancellation.
+};
+type HandlerTenants = {
+  config?: (tenantId: TenantId) => ConfigAccessor; // Config accessor resolved for ANOTHER tenant, identity = that tenant's system user.
+  writeTarget?: (tenantId: TenantId) => TenantWriteTarget; // Write target for ANOTHER tenant: a tenant-mode db bound to it plus the `streamTenantId` to hand the executor, so the event actor stays the operator.
+};
+type JobLifecycle = Pick<HandlerLifecycle, "signal">;
+```
+
+## packages/types/src/handlers.ts
+
+```ts
+type ActiveMembership = {
+  tenantId: TenantId;
+  roles: string[];
+  tenantName?: string;
+  tenantKey?: string;
+};
+type ActiveMembershipRejection = "not_a_member" | "principal_blocked" | "tenant_teardown";
+type ActiveMembershipResult =
+  | {
+    kind: "active";
+    membership: ActiveMembership;
+  }
+  | {
+    kind: "rejected";
+    reason: ActiveMembershipRejection;
+  }
+;
+type AgentExposure = {
+  expose: boolean;
+  risk: AgentRisk;
+};
+type AgentScreenHints = Pick<AgentHandlerHints, "expose">; // Screens only read `expose`; `risk` ranks handler tool calls, so it is not offered here.
+type AggregateStreamHandle = {
+  events: StoredEvent[];
+  version: number;
+  appendOne: (args: { type: string; payload: unknown; }) => Promise<void>;
+  hasEvent: (type: string) => boolean;
+};
+type AppendEventArgs = {
+  aggregateId: string;
+  aggregateType: string;
+  type: string;
+  payload: unknown;
+  headers?: Readonly<Record<string, string | number | boolean>>;
+};
+type AppendEventFn<TMap extends object = KumikoEventTypeMap> = <K extends keyof TMap>(args: TypedAppendEventArgs<TMap, K>) => Promise<void>;
+type AuthClaimsFn = (user: SessionUser, ctx: AuthClaimsContext) => Promise<Record<string, unknown>>;
+type AuthClaimsHookDef = {
+  featureName: string;
+  fn: AuthClaimsFn;
+  declaredKeys?: ReadonlySet<string>;
+};
+type BeforeTransactionPhase<TPayload = unknown, TPrepared = unknown> = (event: WriteEvent<TPayload>, ctx: BeforeTransactionContext) => Promise<BeforeTransactionResult<TPrepared>>;
+type BeforeTransactionWhenNested = "skip"; // `skip`: run as a nested write without the `beforeTransaction` phase.
+type CamelToKebab<S extends string> = CamelToKebabImpl<S, "start", "">; // Compile-time mirror of `engine/qualified-name.ts:toKebab` for camelCase → kebab-case.
+type CamelToKebabImpl<S extends string, Prev extends "start" | "upper" | "post-letter", Acc extends string> = S extends `${infer C}${infer Rest}` ? CharKind<C> extends "upper" ? Prev extends "start" ? CamelToKebabImpl<Rest, "upper", `${Acc}${Lowercase<C>}`> : Prev extends "post-letter" ? CamelToKebabImpl<Rest, "upper", `${Acc}-${Lowercase<C>}`> : Rest extends `${infer Next}${string}` ? CharKind<Next> extends "lower" ? CamelToKebabImpl<Rest, "upper", `${Acc}-${Lowercase<C>}`> : CamelToKebabImpl<Rest, "upper", `${Acc}${Lowercase<C>}`> : `${Acc}${Lowercase<C>}` : CharKind<C> extends "l…;
+type CharKind<C extends string> = C extends Lowercase<C> ? (C extends Uppercase<C> ? "non-letter" : "lower") : "upper"; // Three-way classification used by `CamelToKebab`: - "lower" — a lowercase letter (a-z and Unicode lowercase) - "upper" — an uppercase letter (A-Z and Unicode uppercase) - "non-letter" — digit, dot, dash, etc.
+type ClaimKeyDefinition = {
+  shortName: string;
+  qualifiedName: string;
+  type: ClaimKeyType;
+};
+type ClaimKeyHandle<T extends ClaimKeyType = ClaimKeyType> = {
+  name: string;
+  type: T;
+};
+type ClaimKeyJsType<T extends ClaimKeyType> = T extends "string" ? string : T extends "number" ? number : T extends "boolean" ? boolean : T extends "string[]" ? string[] : T extends "object" ? Readonly<Record<string, unknown>> : never;
+type DeclarativeEventMigration = {
+  rename?: Readonly<Record<string, string>>;
+  default?: Readonly<Record<string, unknown>>;
+  map?: Readonly<Record<string, (value: unknown) => unknown>>;
+};
+type DispatchWriteRef = {
+  write: (user: SessionUser, qn: string, payload: unknown, inheritedOrigin?: WriteOrigin) => Promise<WriteResult>;
+  queryAs: (user: SessionUser, qn: string, payload: unknown, inheritedOrigin?: WriteOrigin) => Promise<unknown>;
+  createMemberReader: (tenantId: TenantId) => MemberReader;
+};
+type EntityRef = {
+  name: string;
+  table: string;
+};
+type EscapeHatchGrant = (typeof ESCAPE_HATCH_GRANTS)[number];
+type EscapeHatchReporter = (kind: EscapeHatchKind, reason: string, target?: EscapeHatchTarget) => void;
+type EscapeHatchTarget = {
+  id: string;
+  tenantId: TenantId;
+};
+type EventMigrationDef = {
+  eventName: string;
+  fromVersion: number;
+  toVersion: number;
+  transform: EventUpcastFn;
+};
+type EventPiiAbsentSubject = "plaintext" | "tenant" | "self";
+type EventPiiFields = Readonly<Record<string, EventPiiSubject>>;
+type EventPiiStance = EventPiiFields | "none";
+type EventPiiSubject =
+  | {
+    personal: {
+      of: string;
+      whenAbsent?: EventPiiAbsentSubject;
+    };
+  }
+  | {
+    personal: "tenant";
+  }
+  | {
+    personal: "self";
+  }
+  | {
+    subjectField: string;
+  }
+;
+type EventUpcastCtx = {
+  db: DbRunner;
+  tenantId: TenantId;
+};
+type EventUpcastFn = (payload: unknown, ctx: EventUpcastCtx) => unknown | Promise<unknown>;
+type FetchForWritingArgs = {
+  aggregateId: string;
+  aggregateType: string;
+  expectedVersion?: number;
+};
+type HandlerRef = {
+  name: string;
+};
+type JobRunnerRef = {
+  handleEvent(eventName: string, payload: Record<string, unknown>, user?: SessionUser, triggerEvent?: JobTriggerEvent): Promise<void>;
+  handleCatchUpEvent?(jobName: string, eventName: string, payload: Record<string, unknown>, user: SessionUser, triggerEvent: JobTriggerEvent): Promise<void>;
+  dispatch?(jobName: string, payload: Record<string, unknown>, meta?: { priority?: number; jobId?: string; }): Promise<unknown>;
+};
+type JobTriggerEvent = {
+  id: string;
+  headers: NonNullable<EventMetadata["headers"]>;
+};
+type MemberReader = (userId: string, qn: string, payload: unknown) => Promise<unknown>;
+type NameOrRef =
+  | string
+  | {
+    name: string;
+  }
+;
+type NotifyDeferred = {
+  kind: "deferred";
+};
+type OpenToAllAccessRule = {
+  openToAll: OpenToAllDeclaration;
+};
+type OpenToAllDeclaration = {
+  reason: string;
+  personalData?: OpenToAllPersonalData;
+};
+type OpenToAllPersonalData = "tenant-members";
+type PayloadBucketNormalization = "email";
+type PayloadRateLimitOption = {
+  per: RateLimitPayloadBucket;
+  limit: number;
+  windowSeconds: number;
+  cost?: number;
+  normalize?: PayloadBucketNormalization;
+};
+type PreTransactionReservation = (event: WriteEvent, ctx: ReservationContext) => Promise<ReservationRelease | ReservationHandle | undefined>; // Runs in the dispatcher after every pre-handler gate (feature, rate limit, access, schema, validation, field roles) passed but before the handler transaction opens, so it must commit its own short write instead of holding a second connection while the transaction is open.
+type PreparedOrSkipped<TPrepared, TWhenNested> = [ TWhenNested ] extends [ BeforeTransactionWhenNested ] ? TPrepared | undefined : TPrepared; // The `prepared` type a handler sees: with `beforeTransactionWhenNested: "skip"` a nested run leaves it undefined.
+type PreparedWriteEvent<TPayload = unknown, TPrepared = unknown> = WriteEvent<TPayload> & ([ TPrepared ] extends [ undefined ] ? { prepared?: undefined; } : { prepared: TPrepared; }); // What a handler sees when its `beforeTransaction` phase ran: the phase's `data` as `prepared`; absent for handlers without the phase.
+type QualifiedEventName<TFeature extends string, TInner extends string> = `${CamelToKebab<TFeature>}:event:${CamelToKebab<TInner>}`; // Builds the qualified event-name from feature + inner-name in the same shape the runtime emits via `qn(toKebab(feature), "event", toKebab(inner))`.
+type QueryHandlerFn<TPayload = unknown, TResult = unknown> = (query: QueryEvent<TPayload>, context: HandlerContext) => Promise<TResult>;
+type RateLimitDeclaration = RateLimitOption | RateLimitOptions | RateLimitDisabled;
+type RateLimitDisabled = {
+  disabled: true;
+  reason: string;
+};
+type RateLimitOption = {
+  per: RateLimitPer;
+  limit: number;
+  windowSeconds: number;
+  cost?: number;
+};
+type RateLimitOptions = [ RateLimitOption, ...RateLimitOption[] ];
+type RateLimitPayloadBucket = {
+  payloadField: string;
+};
+type ReservationConfirmContext = { // The dispatcher's own open handler transaction: a reservation must settle on it, not on HandlerContext, whose db is fail-closed for r.systemScope() handlers.
+  tx: DbTx;
+  tenantId: TenantId;
+};
+type ReservationHandle = { // A reservation that also settles inside the handler transaction.
+  release: ReservationRelease;
+  confirmInTransaction: (confirm: ReservationConfirmContext) => Promise<void>;
+};
+type ReservationRelease = () => Promise<void>; // Undoes a reservation made before the handler transaction.
+type SessionUserOrigin = "member-resolution";
+type SharedContextFields = {
+  redis?: Redis;
+  cacheSync?: CacheSyncBus;
+  jobRunner?: JobRunnerRef;
+  configResolver?: ConfigResolver;
+  config?: ConfigAccessor;
+  configFor?: (tenantId: TenantId) => ConfigAccessor; // Becomes `ctx.tenants.config`.
+  forTenant?: (tenantId: TenantId) => TenantWriteTarget; // Becomes `ctx.tenants.writeTarget`.
+  configAccessorFactory?: ConfigAccessorFactory; // Mints the per-request `ctx.config`; set by the boot (`addConfigAccessorFactory`) from the effective `configResolver`, overriding an app-supplied value.
+  configEncryption?: EnvelopeCipher;
+  rateLimit?: RateLimitResolver;
+  _rateLimitPayloadDigest?: (value: string) => string;
+  searchAdapter?: SearchAdapter;
+  files?: FileContext;
+  derivatives?: DerivativesContext;
+  _fileProviderResolver?: FileProviderResolver;
+  entityCache?: EntityCache;
+  notify?: NotifyFn;
+  _notifyFactory?: NotifyFactory;
+  _notifyInTransactionFactory?: (user: SessionUser, tenantId: TenantId) => NotifyFn;
+  _notifyAfterCommitFactory?: (user: SessionUser, tenantId: TenantId) => NotifyFn;
+  _escapeHatchAuditSink?: EscapeHatchAuditSink;
+  secrets?: SecretsContext;
+  masterKeyProvider?: MasterKeyProvider;
+  kms?: KmsAdapter;
+  tracer?: Tracer;
+  meter?: Meter;
+  signal?: AbortSignal;
+  effectiveFeatures?: (tenantId: TenantId) => ReadonlySet<string>;
+  scheduleAfterCommit?: (hook: () => Promise<void>) => void; // Becomes `ctx.lifecycle.afterCommit`.
+  scheduleAfterRollback?: (hook: () => Promise<void>) => void; // Becomes `ctx.lifecycle.afterRollback`.
+};
+type StreamHandlerFn<TPayload = unknown, TChunk = unknown> = (query: QueryEvent<TPayload>, context: HandlerContext) => AsyncGenerator<TChunk>;
+type TryAppendEventFn = (args: AppendEventArgs) => Promise<TryAppendEventResult>;
+type TryAppendEventResult =
+  | {
+    ok: true;
+    event: StoredEvent;
+  }
+  | {
+    ok: false;
+    conflict: VersionConflict;
+  }
+;
+type TypedAppendEventArgs<TMap extends object, K extends keyof TMap> = {
+  aggregateId: string;
+  aggregateType: string;
+  type: K;
+  payload: TMap[K];
+  headers?: Readonly<Record<string, string | number | boolean>>;
+};
+type UnsafeAppendEventFn = (args: AppendEventArgs) => Promise<void>;
+type WriteHandlerTransactionMode = "perCommand"; // `perCommand`: the handler runs without a transaction of its own.
+```
+
+## packages/types/src/hook-phase.ts
+
+```ts
+type HookPhase = "inTransaction" | "afterCommit";
+```
+
+## packages/types/src/hooks.ts
+
+```ts
+type EntityHookMap = {
+  postSave?: Readonly<Record<string, PhasedHook<PostSaveHookFn>[]>>;
+  preDelete?: Readonly<Record<string, PhasedHook<PreDeleteHookFn>[]>>;
+  postDelete?: Readonly<Record<string, PhasedHook<PostDeleteHookFn>[]>>;
+  postQuery?: Readonly<Record<string, OwnedFn<PostQueryHookFn>[]>>;
+};
+type HookMap = {
+  validation?: Readonly<Record<string, ValidationHookFn>>;
+  preSave?: Readonly<Record<string, OwnedFn<PreSaveHookFn>[]>>;
+  postSave?: Readonly<Record<string, PhasedHook<PostSaveHookFn>[]>>;
+  preDelete?: Readonly<Record<string, PhasedHook<PreDeleteHookFn>[]>>;
+  postDelete?: Readonly<Record<string, PhasedHook<PostDeleteHookFn>[]>>;
+  postQuery?: Readonly<Record<string, OwnedFn<PostQueryHookFn>[]>>;
+};
+type HookOwner = {
+  featureName?: string;
+};
+type OwnedFn<TFn> = HookOwner & {
+  fn: TFn;
+};
+type PhasedHook<TFn> = HookOwner & {
+  fn: TFn;
+  phase: HookPhase;
+};
+type PostDeleteBatchHookFn = (payloads: DeleteContext[], context: HandlerContext) => Promise<void>;
+type PostQueryHookFn = (result: { entityName: string | undefined; rows: ReadonlyArray<Record<string, unknown>>; }, context: HandlerContext) => Promise<{ rows: ReadonlyArray<Record<string, unknown>>; }>;
+type PostSaveBatchHookFn = (results: SaveContext[], context: HandlerContext) => Promise<void>;
+type SearchPayloadContributorFn = (args: { entityName: string; entityId: EntityId; state: Record<string, unknown>; }) => Record<string, unknown> | Promise<Record<string, unknown>>;
+```
+
+## packages/types/src/http-route.ts
+
+```ts
+type HttpRouteDefinition = {
+  method: HttpRouteMethod; // HTTP method — mounted in Hono via app.{get,post,...}(path).
+  path: string; // URL path (Hono pattern, e.g. "/feed.xml" or "/og/:tenantId.png").
+  anonymous: boolean; // true = public, no session required.
+  handler: HttpRouteHandler; // Hono handler.
+  rateLimit?: HttpRouteRateLimit; // Enforced before the route's guards through the server's rate-limit resolver (fail-open like the global L1 limiter: a limiter outage lets the request through, counted and logged).
+};
+type HttpRouteHandler = (c: Context<any, any>, deps: HttpRouteHandlerDeps) => Response | Promise<Response>;
+type HttpRouteHandlerDeps = { // Dependencies provided to the handler by the framework.
+  app: Hono<any, any>; // The Hono app — the handler can use app.fetch(...) to call internal routes (e.g. /api/query with the full auth/anonymous chain).
+  systemQuery: (type: string, payload: unknown, tenantId: TenantId) => Promise<unknown>; // 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).
+  clientIp: string; // 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.
+};
+type HttpRouteMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS"; // Subset of HTTP methods actively supported.
+type HttpRouteRateLimit = Omit<RateLimitOption, "per"> & { // Same shape as a handler's `rateLimit`, restricted to the IP-keyed buckets: a route has no dispatcher identity to key on.
+  per: "ip" | "ip+handler";
+};
+```
+
+## packages/types/src/kms-adapter-types.ts
+
+```ts
+type KmsAdapter = LocalKeyKmsAdapter | RemoteCryptoKmsAdapter;
+interface KmsAdapterBase {
+  createKey(subject: SubjectId, ctx: KmsContext): Promise<void>; // Creates a fresh subject key.
+  eraseKey(subject: SubjectId, ctx: KmsContext): Promise<void>; // Erases the key material immediately; the tombstone row stays for the audit trail.
+  health(): Promise<KmsHealth>; // Probe for boot + readiness.
+}
+interface KmsContext {
+  tenantId?: TenantId;
+  requestId: string;
+  userId?: string;
+  eraseReason?: string;
+}
+interface KmsHealth {
+  ok: boolean;
+  latencyMs: number;
+  details?: Record<string, unknown>;
+}
+interface LocalKeyKmsAdapter extends KmsAdapterBase {
+  capabilities: {
+    mode: "local-key";
+  };
+  getKey(subject: SubjectId, ctx: KmsContext): Promise<SubjectDek>; // Throws KeyErasedError after eraseKey (callers render "[[erased]]"), KeyNotFoundError when the subject never had a key (typically a bug).
+}
+interface RemoteCryptoKmsAdapter extends KmsAdapterBase {
+  capabilities: {
+    mode: "remote-crypto";
+  };
+  encrypt(subject: SubjectId, plaintext: Uint8Array, ctx: KmsContext): Promise<Uint8Array>;
+  decrypt(subject: SubjectId, ciphertext: Uint8Array, ctx: KmsContext): Promise<Uint8Array>; // Same error contract as LocalKeyKmsAdapter.getKey.
+}
+type SubjectDek = Buffer;
+type SubjectId =
+  | {
+    kind: "user";
+    userId: string;
+  }
+  | {
+    kind: "tenant";
+    tenantId: TenantId;
+  }
+  | {
+    kind: "record";
+    entity: string;
+    id: string;
+  }
+;
+```
+
+## packages/types/src/list-aggregate-types.ts
+
+```ts
+type ListAggregateCurrencyAmount = {
+  currency: string;
+  value: number;
+};
+type ListAggregateGroup = {
+  key: AggregateKey;
+  label?: string | null;
+  count: number;
+  measures: ListAggregateValue[];
+};
+type ListAggregateMeasureKind = (typeof LIST_AGGREGATE_MEASURE_KINDS)[number];
+type ListAggregatePayload = {
+  groupBy?: string | undefined;
+  measures: { field: string; kind: ListAggregateMeasureKind; }[];
+};
+type ListAggregateResult = {
+  groups: ListAggregateGroup[];
+  truncated?: true;
+  searchTruncated?: true;
+};
+type ListAggregateValue = number | string | null | ListAggregateCurrencyAmount[];
+```
+
+## packages/types/src/logger.ts
+
+```ts
+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;
+};
+```
+
+## packages/types/src/multi-stream-apply-context-types.ts
+
+```ts
+type MultiStreamApplyContext<TMap extends object = KumikoEventTypeMap> = {
+  appendEvent: AppendEventFn<TMap>;
+  unsafeAppendEvent: UnsafeAppendEventFn;
+  loadAggregate: (aggregateId: string, options?: { asOf?: Temporal.Instant; }) => Promise<StoredEvent[]>;
+  registry: Registry;
+  files?: FileContext;
+  derivatives?: DerivativesContext;
+  secrets?: SecretsContext;
+  jobs?: {
+    dispatch(jobName: string, payload: Record<string, unknown>, options?: { jobId?: string; }): Promise<void>;
+  };
+};
+```
+
+## packages/types/src/nav.ts
+
+```ts
+type ContentEditorFormat = "plain" | "document"; // Client editor format for r.contentCollection() — not template body storage formats.
+```
+
+## packages/types/src/observability/metric.ts
+
+```ts
+interface Counter {
+  inc(value?: number, labels?: MetricLabels): void;
+}
+interface Gauge {
+  set(value: number, labels?: MetricLabels): void;
+  inc(value?: number, labels?: MetricLabels): void;
+  dec(value?: number, labels?: MetricLabels): void;
+}
+interface Histogram {
+  observe(value: number, labels?: MetricLabels): void;
+}
+interface Meter {
+  registerMetric(def: MetricDefinition): void;
+  counter(name: string): Counter;
+  histogram(name: string): Histogram;
+  gauge(name: string): Gauge;
+  definitions(): ReadonlyMap<string, MetricDefinition>;
+}
+type MetricDefinition = {
+  name: string;
+  type: MetricType;
+  description?: string;
+  labels?: string[];
+  buckets?: number[];
+  unit?: string;
+  tenantLabel?: boolean;
+};
+type MetricLabels = Record<string, string | number | boolean>;
+type MetricType = "counter" | "histogram" | "gauge";
+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;
+}
+```
+
+## packages/types/src/observability/provider.ts
+
+```ts
+type ObservabilityOptions = {
+  sampling?: SamplingConfig;
+  sensitiveFilter?: Partial<SensitiveFilterConfig>;
+};
+interface ObservabilityProvider {
+  name: string;
+  tracer: Tracer;
+  meter: Meter;
+  shutdown(): Promise<void>;
+}
+type SamplingConfig = {
+  tracing?: number;
+  alwaysOnError?: boolean;
+  alwaysOnSlow?: {
+    thresholdMs: number;
+  };
+};
+type SensitiveFilterConfig = {
+  redactedHeaders: string[];
+  redactedQueryParams: string[];
+  redactedAttributeKeyPatterns: RegExp[];
+};
+```
+
+## packages/types/src/observability/span.ts
+
+```ts
+type SerializedTraceContext = {
+  traceId: string;
+  spanId: string;
+  baggage?: Readonly<Record<string, string>>;
+};
+interface Span {
+  traceId: string;
+  spanId: string;
+  parentSpanId: string | undefined;
+  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;
+  ended: boolean;
+}
+type SpanAttributeValue = string | number | boolean;
+type SpanAttributes = Record<string, SpanAttributeValue>;
+type SpanKind = "internal" | "server" | "client" | "producer" | "consumer";
+type SpanStatus = "unset" | "ok" | "error";
+type StartSpanOptions = {
+  parent?: Span | SerializedTraceContext;
+  attributes?: SpanAttributes;
+  kind?: SpanKind;
+  startTime?: number;
+};
+interface Tracer {
+  startSpan(name: string, options?: StartSpanOptions): Span;
+  withSpan<T>(name: string, optionsOrFn: StartSpanOptions | ((span: Span) => Promise<T>), fn?: (span: Span) => Promise<T>): Promise<T>;
+  getActiveSpan(): Span | undefined;
+}
+```
+
+## packages/types/src/ownership.ts
+
+```ts
+type FromRule = {
+  kind: "from";
+  refKind: FromRuleKind;
+  refPath: string;
+  column: string;
+};
+type FromRuleKind = "user" | "claim";
+type OwnershipRef = string;
+type OwnershipRule = "all" | FromRule | WhereRule;
+type SqlFragment = {
+  sqlText: string;
+  params: unknown[];
+};
+type WhereRule<TTable = unknown> = {
+  kind: "where";
+  where: (user: SessionUser, ctx: WhereRuleContext<TTable>) => SqlFragment;
+};
+type WhereRuleContext<TTable = unknown> = {
+  table: TTable;
+  tableName: string;
+  paramStart: number;
+};
+```
+
+## packages/types/src/projection.ts
+
+```ts
+type EntityProjectionExtension = {
+  sources?: string[];
+  rowIdOf?: ProjectionRowIdOf;
+  apply: Readonly<Record<string, SingleStreamApplyFn>>;
+};
+type MspErrorPolicy = {
+  skipApplyErrors?: boolean;
+};
+type ProjectionRowIdOf = (source: Pick<StoredEvent, "tenantId" | "aggregateId">) => string;
+type ProjectionTable = SchemaTable;
+type SingleStreamApplyFn<TPayload = Record<string, unknown>> = (event: StoredEvent<TPayload>, tx: ExecutorManagedRunner, table: ProjectionTable) => Promise<void>;
+```
+
+## packages/types/src/rate-limit-types.ts
+
+```ts
+type RateLimitBucketRequest = {
+  bucket: string;
+  config: RateLimitConfig;
+};
+type RateLimitConfig = {
+  limit: number;
+  windowSeconds: number;
+  cost?: number;
+};
+type RateLimitDecision = {
+  allowed: boolean;
+  limit: number;
+  remaining: number;
+  retryAfterSeconds: number;
+  windowSeconds: number;
+  resetAt: Temporal.Instant;
+};
+type RateLimitResolver = {
+  check(bucket: string, config: RateLimitConfig): Promise<RateLimitDecision>;
+  enforce(bucket: string, config: RateLimitConfig): Promise<RateLimitDecision>;
+  enforceAll(requests: RateLimitBucketRequest[]): Promise<RateLimitDecision[]>;
+  peek(bucket: string, config: Omit<RateLimitConfig, "cost">): Promise<RateLimitDecision>;
+};
+```
+
+## packages/types/src/relations.ts
+
+```ts
+type BelongsToRelation = {
+  type: "belongsTo";
+  target: string;
+  foreignKey: string;
+};
+type EntityRelations = Readonly<Record<string, RelationDefinition>>;
+type HasManyRelation = {
+  type: "hasMany";
+  target: string;
+  foreignKey: string;
+  onDelete?: OnDeleteStrategy;
+  nestedWrite?: boolean;
+};
+type ManyToManyRelation = {
+  type: "manyToMany";
+  target: string;
+  through: {
+    table: string;
+    sourceKey: string;
+    targetKey: string;
+  };
+  onDelete?: OnDeleteStrategy;
+};
+type OnDeleteStrategy = "cascade" | "restrict" | "setNull" | "nothing";
+```
+
+## packages/types/src/schema-table-types.ts
+
+```ts
+type ColumnHandle = {
+  name: string;
+  pgType: PgType;
+  getSQLType: () => string;
+};
+```
+
+## packages/types/src/screen-action-form.ts
+
+```ts
+type FormFieldDerivation = // A form field computed from other fields of the same form.
+  | {
+    op: "sum" | "subtract" | "multiply" | "percent";
+    from: string[];
+  }
+  | {
+    op: "listSum";
+    list: string;
+    cell: string;
+    whenEmpty?: FormFieldDerivationWithoutList;
+  }
+;
+type FormFieldDerivationWithoutList = Extract<FormFieldDerivation, { from: unknown; }>;
+type SecretReveal = {
+  fields: SecretRevealField[];
+  title?: string; // i18n key.
+  warning?: string; // i18n key for the "this is the only time you see it" warning.
+  confirmLabel?: string; // i18n key for the acknowledge button.
+  acknowledge?: string; // i18n key for a checkbox on the reveal card ("I have saved my recovery codes").
+};
+type SecretRevealField = { // Author-declared field shown once after a mint-form submit — API token, recovery codes, similar one-time secrets.
+  field: string; // Flat field name in the handler's success payload.
+  label: string; // i18n key for this value's label.
+  display?: "code" | "list" | "qr"; // "code" (default) renders one monospaced value; "list" renders a string-array payload one value per line (recovery codes); "qr" renders the value as a scannable QR code (otpauth://-style enrollment URI) — platforms without a QR-capable SecretReveal primitive fall back to the monospaced text display.
+  copyable?: boolean; // Default true — offer a copy-to-clipboard control next to the value.
+};
+```
+
+## packages/types/src/screen-custom-config.ts
+
+```ts
+type CustomScreenRoute = {
+  path: string;
+  component: PlatformComponent;
+};
+type SecretsEditSection = {
+  title?: string;
+  fields: string[];
+};
+```
+
+## packages/types/src/screen-dashboard.ts
+
+```ts
+type DashboardChartKind = "timeseries" | "stacked-bars" | "segment-bars" | "stacked-area";
+type DashboardChartRangeOption = { // One option of a stacked-area range switch.
+  value: string;
+  label: string;
+  months?: number;
+};
+type DashboardChartRanges = {
+  options: DashboardChartRangeOption[];
+  default: string;
+};
+type DashboardChartTone = "positive" | "negative" | "active" | "neutral";
+type DashboardPanelGate = {
+  visibleWhen?: DashboardPanelVisibility;
+};
+type DashboardRecordBinding = {
+  param: string; // URL search param carrying the record id.
+  payloadKey?: string; // Key of the id in each panel query payload.
+  query?: string; // Optional query for the record row (QN).
+  titleField?: string; // Field of the record row shown as the page title.
+};
+type DashboardRelativeTimeFormat = { // The stat value is an epoch ms timestamp, shown relative to now and kept current.
+  kind: "relativeTime";
+};
+type DashboardStatTone = (typeof DASHBOARD_STAT_TONES)[number];
+type DashboardValueFormat = DashboardCurrencyFormat | DashboardRelativeTimeFormat; // Stat panels take both formats; chart panels only the currency one.
+```
+
+## packages/types/src/screen-entity-edit.ts
+
+```ts
+type EditFieldGroup = {
+  title: string;
+  fields: EditFieldSpec[];
+  columns?: number; // Default 2.
+};
+type EditFieldPrefill =
+  | {
+    kind: "today";
+  }
+  | {
+    kind: "currentUser";
+    property: "displayName" | "email" | "id";
+  }
+;
+type EditFieldsSectionBase = {
+  id?: string; // Kebab-case tab id, used as the `?tab=` value.
+  kind?: "fields";
+  title?: string; // Optional.
+  description?: string; // Optional help text under the block heading (i18n key or raw string, like `title`) — makes a form usable without training instead of falling back to custom JSX for help text.
+  columns?: number;
+  icon?: IconKey; // Rendered left of the section title, `text-muted-foreground` — closed IconKey vocabulary into the ICONS registry (renderer/web), analogous to EditFieldSpec.icon.
+  countField?: string; // Record field rendered as a count badge in the tab label when the enclosing `EditLayout.mode` is "tabs" (e.g. an open-items counter).
+  subtitle?: string; // Short line (i18n key) under this step's title in the wizard step rail and in the "up next" box.
+  actions?: RowAction[]; // Rendered top-right in the section's Card title row — same navigate/drawer/writeHandler dispatch as `ProjectionDetailScreenDefinition.actions`, evaluated against the same record.
+};
+type EntityEditActionPlacement = "inline" | "menu";
+type EntityWriteExcludedFields = {
+  create?: string[];
+  update?: string[];
+};
+```
+
+## packages/types/src/screen-entity-list.ts
+
+```ts
+type EntityListFacetExtraOption = { // An extra choice on a facet next to the field's own options: a named bundle of values ("Running" = several statuses) or "no filter" (`values: []`, e.g. "All").
+  id: string;
+  label: string; // i18n key.
+  values: string[]; // Option values this choice selects; `[]` selects nothing, i.e. no filter.
+  position?: "start" | "end"; // Where the chip sits relative to the field's own options.
+};
+type ListColumnDisplay = "bar" | "badge" | "datetime";
+type ListPaginationMode = "pages" | "infinite" | false;
+type ListSortDir = "asc" | "desc";
+type RowActionNavigateBase = {
+  kind: "navigate";
+  id: string;
+  label: string;
+  entityId?: string; // Field name whose value is embedded as entityId in the URL path (`/<workspace>/<screen>/<entityId>`).
+  params?: RowFieldExtractor; // Declarative URL search params extracted from the clicked row.
+  tab?: string; // Section id of the tab to activate on the target projectionDetail (layout.mode "tabs"); merged into the navigate search params next to returnTo.
+  visible?: FieldCondition; // Conditional visibility per row.
+  style?: "primary" | "secondary" | "danger"; // Visual style only — unlike the writeHandler variants, "danger" does not force a confirm dialog here: the target form is the confirmation.
+  rowClick?: boolean; // When true, a click on the whole row (not just the action menu) triggers this navigate action.
+  icon?: IconKey; // Overrides the id-based default icon (see ACTION_ICON_BY_ID in kumiko-renderer) — closed IconKey vocabulary into the ICONS registry (renderer/web), analogous to EditFieldSpec.icon.
+  display?: RowActionDisplay; // Inline render form in the row-action column — see `RowActionDisplay`.
+};
+type ScreenFilter = {
+  field: string;
+  op: ScreenFilterOp;
+  value: unknown;
+};
+type ScreenFilterOp = "eq" | "ne" | "lt" | "gt" | "lte" | "gte" | "in";
+```
+
+## packages/types/src/screen-expandable-row.ts
+
+```ts
+type EntityListExpandableRow = Omit<EditRelatedListSection, "id" | "countField" | "table" | "bulkActions"> & { // Expandable area of an `entityList` row: a relatedList of the row's record.
+  table?: {
+    grouping?: ExpandableRowGrouping;
+  };
+};
+type ExpandableRowGrouping = Omit<ListTableGrouping, "field" | "userChoice" | "fields"> & { // Server-side grouping of an expandable row's sub-list: a fixed `field`, no "Group by" choice.
+  field: string;
+};
+```
+
+## packages/types/src/screen-list-table.ts
+
+```ts
+type ListColumnPin = (typeof LIST_COLUMN_PINS)[number];
+type ListTableDensity = (typeof LIST_TABLE_DENSITIES)[number];
+type ListTableExportOptions = {
+  xlsx: true;
+  maxRows?: number; // Export is refused above this many rows.
+};
+type ListTableGrouping = {
+  field?: string; // Start grouping.
+  collapsedWhen?: string | number | boolean | null; // Groups whose key equals this start collapsed and load no rows until opened.
+  label?: string; // i18n key of the group header.
+  labels?: Readonly<Record<string, string>>; // Header i18n key per group key (as string), overriding `label`.
+  userChoice?: boolean; // Shows "Group by" in the view menu (needs `fields` or `field`) and remembers the choice per session.
+  fields?: string[]; // Fields offered under "Group by"; `field` is always offered.
+};
+type ListTableTotal = {
+  field: string;
+  kind: ListAggregateMeasureKind; // sum and avg on number, decimal, money and bigInt; min and max also on date and timestamp.
+};
+```
+
+## packages/types/src/screen-projection.ts
+
+```ts
+type MetricSpec = {
+  field: string;
+  label: string;
+  navigate?: MetricNavigate;
+  tone?: DashboardStatTone; // Tile color as on dashboard stat panels; not applied while the value is 0.
+  icon?: NavIconKey; // Icon chip of the tile; only drawn with `metricsStyle: "tiles"`.
+};
+type RecordHeaderSpec = {
+  title: string;
+  subtitle?: string | RecordHeaderSubtitlePart[]; // Field name, or several parts (field name or `{ field, navigate }`) joined by a separator; parts with an empty value are dropped.
+  status?: string;
+  statusFormat?: FormatSpec; // Formats the badge text (typically `enumOption` with a `keyPrefix`); tones still resolve on the raw value.
+  subtitleHref?: string; // Record field holding an absolute http(s) URL.
+  statusToneField?: string; // Record field whose value selects the `statusTones` entry, for a badge text that carries more than the state (e.g. "Terminated on 31.03.2027").
+  statusTones?: {
+    [statusValue: string]: SelectOptionTone;
+  }; // Badge tone per `statusToneField` value (default: the `status` value); unlisted values fall back to the value heuristic.
+};
+```
+
+## packages/types/src/screen.ts
+
+```ts
+type FormatSpec = { [K in keyof FieldFormatRegistry]: { format: K; } & FieldFormatRegistry[K]; }[keyof FieldFormatRegistry];
+type NumberFormatOptions = {
+  locale?: string;
+  grouping?: boolean;
+  minimumFractionDigits?: number; // Intl `minimumFractionDigits` / `maximumFractionDigits` (integers 0..20, min <= max).
+  maximumFractionDigits?: number;
+};
+type ScreenNavSugar = {
+  label: string;
+  icon?: NavIconKey;
+  parent?: string;
+  order?: number;
+};
+```
+
+## packages/types/src/search-adapter.ts
+
+```ts
+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: SearchDocument[]): Promise<void>;
+  removeBatch?(tenantId: TenantId, items: { entityType: string; entityId: EntityId; }[]): Promise<void>;
+  dropAllIndexes?(): Promise<number>;
+};
+type SearchAdapterConfig = {
+  searchableFields: string[];
+  rankingFields?: string[];
+};
+type SearchDocument = {
+  entityType: string;
+  entityId: EntityId;
+  weight: number;
+  fields: Record<string, unknown>;
+};
+type SearchOptions = {
+  limit?: number;
+  filterType?: string;
+};
+type SearchResult = {
+  entityType: string;
+  entityId: EntityId;
+};
+```
+
+## packages/types/src/secrets-types.ts
+
+```ts
+type ContainsSecret<T, Depth extends unknown[] = [ ]> = [ T ] extends [ never ] ? false : unknown extends T ? false : Depth["length"] extends MaxSecretDepth ? false : T extends Secret<unknown> ? true : T extends Primitive ? false : T extends SafeLeaf ? false : T extends (infer U)[] ? ContainsSecret<U, [ ...Depth, unknown ]> : T extends object ? true extends { [K in keyof T]-?: ContainsSecret<T[K], [ ...Depth, unknown ]>; }[keyof T] ? true : false : false;
+type KeyScope = {
+  tenantId?: TenantId;
+};
+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>;
+}
+type MaxSecretDepth = 8;
+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>;
+type Secret<T = string> = {
+  [SecretBrand]: true;
+  reveal: () => T;
+};
+type SecretAuditContext = {
+  userId: string;
+  handlerName: string;
+};
+type SecretKeyRef =
+  | string
+  | {
+    name: string;
+  }
+;
+interface SecretsContext {
+  withRunner(runner: DbRunner): 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>;
+}
+```
+
+## packages/types/src/step.ts
+
+```ts
+type EventMatch = {
+  version: 1;
+  expr: EventMatchExpr;
+};
+type EventMatchExpr =
+  | {
+    kind: "and";
+    nodes: EventMatchExpr[];
+  }
+  | {
+    kind: "or";
+    nodes: EventMatchExpr[];
+  }
+  | {
+    kind: "atom";
+    path: string[];
+    op: EventMatchOp;
+  }
+;
+type EventMatchOp =
+  | {
+    kind: "eq";
+    value: EventMatchValue;
+  }
+  | {
+    kind: "ne";
+    value: EventMatchValue;
+  }
+  | {
+    kind: "in";
+    values: EventMatchValue[];
+  }
+  | {
+    kind: "gt";
+    value: number | string;
+  }
+  | {
+    kind: "gte";
+    value: number | string;
+  }
+  | {
+    kind: "lt";
+    value: number | string;
+  }
+  | {
+    kind: "lte";
+    value: number | string;
+  }
+;
+type EventMatchValue = string | number | boolean | null;
+type PipelineBuildCtx<TPayload = unknown, TAwaits extends Record<string, AwaitedEventType> = Record<string, AwaitedEventType>> = { // Argument bundle passed to the closure inside `stepsPipeline(closure)`.
+  event: WriteEvent<TPayload>;
+  r: StepBuilder;
+  awaits: TAwaits;
+};
+type PipelineDef<TPayload = unknown, _TData = unknown, TAwaits extends Record<string, AwaitedEventType> = Record<string, AwaitedEventType>> = { // What `stepsPipeline(closure)` returns.
+  __kind: "pipeline";
+  awaits?: Readonly<Record<string, string>>;
+  build: (ctx: PipelineBuildCtx<TPayload, TAwaits>) => StepInstance[];
+};
+type StepBuilder = { // Step-builder namespace handed to the pipeline closure.
+  step: StepNamespace;
+};
+type StepDef<TArgs = unknown, TResult = unknown> = {
+  kind: StepKind;
+  defaultFailureStrategy: StepFailureStrategy;
+  resultKey?: (args: TArgs) => string | undefined;
+  subPaths?: string[];
+  tier?: 1 | 2 | 3;
+  run: (args: TArgs, ctx: PipelineCtx) => Promise<TResult> | TResult;
+};
+type StepFailureStrategy = "throw"; // Per-step error strategy.
+type StepKind = string; // The kind discriminator for a step instance — matches the step's registration name in the step-registry (e.g. "return", "compute", "aggregate.create").
+type StepNamespace = { // The collection of step factory functions.
+  return: <TData>(resolver: StepResolver<WriteResult<TData>>) => StepInstance;
+  compute: <TResult>(name: string, fn: (ctx: PipelineCtx) => TResult) => StepInstance;
+  unsafeProjectionUpsert: (args: { table: unknown; on: string[]; row: StepResolver<Record<string, unknown>>; }) => StepInstance;
+  unsafeProjectionDelete: (args: { table: unknown; where: StepResolver<WhereObject>; }) => StepInstance;
+  read: {
+    findOne: (name: string, opts: { table: unknown; where: StepResolver<WhereObject | undefined>; unsafeAllTenants?: { reason: string; }; }) => StepInstance;
+    findMany: (name: string, opts: { table: unknown; where?: StepResolver<WhereObject | undefined>; limit?: number; unsafeAllTenants?: { reason: string; }; }) => StepInstance;
+  };
+  aggregate: {
+    create: (name: string, opts: { executor: EventStoreExecutor; data: StepResolver<Record<string, unknown>>; }) => StepInstance;
+    update: (name: string, opts: { executor: EventStoreExecutor; id: StepResolver<EntityId>; changes: StepResolver<Record<string, unknown>>; version?: StepResolver<number | undefined>; skipOptimisticLock?: boolean; }) => StepInstance;
+    appendEvent: (args: { aggregateId: StepResolver<string>; aggregateType: string; type: string; payload: StepResolver<unknown>; headers?: StepResolver<Readonly<Record<string, string | number | boolean>>>; }) => StepInstance;
+  };
+  branch: (args: { if: StepResolver<boolean>; onTrue: StepInstance[]; onFalse?: StepInstance[]; }) => StepInstance;
+  forEach: <TItem = unknown>(args: { over: StepResolver<TItem[]>; as: string; do: StepInstance[]; concurrency?: 1; }) => StepInstance;
+  webhook: {
+    send: (args: { url: StepResolver<string>; method?: "POST" | "PUT" | "PATCH"; headers?: StepResolver<Readonly<Record<string, string>>>; body?: StepResolver<unknown>; auth?: { kind: "bearer"; secret: string; } | { kind: "header"; name: string; sec…;
+  };
+  mail: {
+    send: (args: { to: StepResolver<string | string[]>; subject: StepResolver<string>; body: StepResolver<string>; from?: StepResolver<string>; mode: "deferred"; }) => StepInstance;
+  };
+  callFeature: (name: string, opts: { handler: string; payload: StepResolver<unknown>; as?: SessionUser; }) => StepInstance;
+  wait: (args: { for: StepResolver<string>; }) => StepInstance;
+  waitForEvent: (args: { event: AwaitedEventType; match?: StepResolver<EventMatch>; timeout: StepResolver<string>; }) => StepInstance;
+  retry: (args: { times: number; backoff: "exponential" | "linear"; do: StepInstance[]; }) => StepInstance;
+};
+```
+
+## packages/types/src/temporal.ts
+
+```ts
+type Instant = globalThis.Temporal.Instant;
+```
+
+## packages/types/src/tenancy-brand.ts
+
+```ts
+type EntityTenancy = "global" | "tenant";
+interface TenancyBrand<T extends EntityTenancy> {
+  [TENANCY]: T;
+}
+```
+
+## packages/types/src/tenant-db-types.ts
+
+```ts
+type CrossTenantReads = Pick<TenantDb, "selectMany" | "fetchOne" | "count">;
+type GlobalReads = {
+  selectMany<T = Record<string, unknown>>(where?: WhereObject, options?: SelectOptions): Promise<T[]>;
+  fetchOne<T = Record<string, unknown>>(where: WhereObject): Promise<T | undefined>;
+};
+type GlobalTableDb<TTable> = GlobalReads & (TTable extends Writable ? GlobalWrites : unknown);
+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<T[]>;
+  deleteMany(where: WhereObject): Promise<void>;
+};
+type TenantDbMode = "tenant" | "system"; // TenantDb scope modes: - "tenant" (default): SELECT/UPDATE/DELETE filtered by tenantId + reference data (tenantId=SYSTEM_TENANT_ID).
+type TenantDbNonWrites = {
+  tenantId: TenantId;
+  mode: TenantDbMode;
+  unsafeRaw(): DbRunner; // Unfiltered DbRunner escape hatch for handlers/hooks that declare `escapeHatch: { reason }`.
+  global<TTable extends (SchemaTable | EntityTableMeta) & TenancyBrand<"global">>(table: TTable): GlobalTableDb<TTable>; // Reach a "global" table with the tenant filter lifted — reads always work; writes reject unless the write handler declared `escapeHatch: { reason }`.
+  selectMany<T = Record<string, unknown>>(table: SchemaTable | EntityTableMeta, where?: WhereObject, options?: SelectOptions): Promise<T[]>;
+  fetchOne<T = Record<string, unknown>>(table: SchemaTable | EntityTableMeta, where: WhereObject): Promise<T | undefined>;
+  count(table: SchemaTable | EntityTableMeta, where?: WhereObject): Promise<number>;
+  advisoryXactLock(namespace: number, key: string): Promise<void>; // Transaction-scoped advisory lock keyed on (namespace, this handle's tenantId + key); released at commit or rollback.
+  databaseNow(): Promise<Date>; // Postgres `now()`; inside a transaction this is the transaction start.
+  aggregate(table: SchemaTable | EntityTableMeta, spec: AggregateSpec, where?: WhereObject): Promise<AggregateRow[]>;
+  upsert<T = Record<string, unknown>>(table: WritableTable, values: Record<string, unknown>, options: TenantDbUpsertOptions): Promise<T | undefined>;
+};
+type TenantDbUpsertOptions = {
+  conflictTarget: string[];
+  update?: Record<string, unknown>;
+};
+type TenantDbWrites<TTable> = {
+  insertOne<T = Record<string, unknown>>(table: TTable, values: Record<string, unknown>): Promise<T | undefined>;
+  updateMany<T = Record<string, unknown>>(table: TTable, set: Record<string, unknown>, where: WhereObject): Promise<T[]>;
+  deleteMany(table: TTable, where: WhereObject): Promise<number>;
+};
+```
+
+## packages/types/src/tree-node.ts
+
+```ts
+type Subscribe<T> = (emit: (value: T) => void, emitError?: (error: Error) => void) => () => void;
+type TreeActionBase = {
+  icon: string;
+  label: string;
+};
+type TreeActionsHandle<TFeature extends string, TActions extends Record<string, TreeActionDef>> = {
+  id: TFeature;
+  treeActions: TActions;
+};
+type TreeNodeState = "filled" | "stub" | "empty" | "loading" | "error";
+```
+
+## packages/types/src/tz-context.ts
+
+```ts
+type Clock = { // Source of "now" for ctx.tz; tests inject a fixed or advancing one.
+  now: () => Temporal.Instant;
+};
+type LocatedTimestampJson = {
+  at: string; // Wall-clock ISO without offset, e.g. "2026-04-03T10:00:00"
+  tz: string; // IANA zone, e.g. "Europe/Lisbon"
+};
+type TzContext = {
+  tenant: string; // Default TZ of the tenant (from tenant.timezone, default "UTC").
+  user: string; // Display TZ of the current user (profile override, fallback tenant).
+  now(): Temporal.Instant; // Current moment as UTC instant.
+  nowIn(tz: string): Temporal.ZonedDateTime; // Current moment as ZonedDateTime in the requested zone.
+  today(tz: string): Temporal.PlainDate; // Today's calendar date in the requested zone.
+  todayRange(tz: string): { start: Temporal.Instant; end: Temporal.Instant; }; // Day boundaries (00:00 to 24:00 next day) as UTC instants — for DB range queries.
+  parse(wallClock: string, tz: string): Temporal.ZonedDateTime; // Wall-clock string + IANA zone → ZonedDateTime.
+  toInstant(zdt: Temporal.ZonedDateTime): Temporal.Instant; // ZonedDateTime → UTC instant.
+  toLocatedJson(zdt: Temporal.ZonedDateTime): LocatedTimestampJson; // ZonedDateTime → JSON pair { at, tz } (API boundary).
+  fromLocatedJson(obj: LocatedTimestampJson): Temporal.ZonedDateTime; // JSON pair { at, tz } → ZonedDateTime (wall-clock + IANA).
+  fromCoordinates(coords: GeoCoordinates): Promise<string>; // Geo coordinates → IANA zone via the configured GeoTzProvider.
+  fromAddress(address: GeoAddress): Promise<string>; // Postal address → IANA zone via GeoTzProvider.
+};
+```
+
+## packages/types/src/websocket-route.ts
+
+```ts
+type WebSocketConnection = {
+  send: (data: WebSocketMessageData) => void;
+  close: (code?: number, reason?: string) => void;
+  signal: AbortSignal; // Aborts when the socket closes.
+};
+type WebSocketMessageData = string | Uint8Array;
+type WebSocketRouteConnectDeps = {
+  user: SessionUser;
+  query: (type: string, payload: unknown) => Promise<unknown>;
+  write: (type: string, payload: unknown) => Promise<WriteResult>;
+  clientIp: string; // Resolved via the server's trustedProxyHops-aware resolver, like HttpRouteHandlerDeps.clientIp.
+};
+type WebSocketRouteDefinition = {
+  path: string; // Must start with "/api/ws/"; `:param` segments allowed, no "*".
+  maxMessageBytes?: number; // Per-message cap; oversized messages close the socket with 1009.
+  maxConnectionsPerUser?: number; // Concurrent sockets per user and tenant on this route (per server process).
+  connect: (c: Context<any, any>, deps: WebSocketRouteConnectDeps) => WebSocketSessionHandlers | Response | Promise<WebSocketSessionHandlers | Response>; // Runs after auth + origin checks, before the upgrade.
+};
+type WebSocketSessionHandlers = {
+  onOpen?: (connection: WebSocketConnection) => void | Promise<void>; // May still be awaiting when onClose runs; see `WebSocketConnection.signal`.
+  onMessage?: (data: WebSocketMessageData, connection: WebSocketConnection) => void | Promise<void>;
+  onClose?: (code: number, reason: string, connection: WebSocketConnection) => void | Promise<void>; // Runs immediately on close, not queued behind a slow onMessage; pending messages never start after it.
+};
+```
+
+## packages/types/src/where-clause-types.ts
+
+```ts
+type OrderByClause = {
+  col: string;
+  direction?: "asc" | "desc";
+};
+type WhereOperator = {
+  gt?: unknown;
+  gte?: unknown;
+  lt?: unknown;
+  lte?: unknown;
+  ne?: unknown;
+  in?: unknown[];
+  notIn?: unknown[]; // Not for jsonb columns; an empty list matches every row.
+  like?: string;
+  jsonText?: JsonTextMatch | JsonTextMatch[]; // jsonb columns only; cannot be combined with other operators in the same object.
+};
+type WherePrimitive = string | number | boolean | bigint | Date | null | undefined;
+type WhereValue = WherePrimitive | WherePrimitive[] | WhereOperator;
+```