@cosmicdrift/kumiko-types 0.327.0 → 0.328.1

package/dist/action-icon.d.ts

@@ -0,0 +1,3 @@
+import type { IconKey } from "./nav-icon.js";
+export declare const ACTION_ICON_BY_ID: Readonly<Partial<Record<string, IconKey>>>;
+export declare function resolveActionIcon(id: string, declared?: IconKey): IconKey | undefined;

package/dist/action-icon.js

@@ -0,0 +1,51 @@
+// Part B (fw-ui-defaults): id-derived default icon for actions that never
+// declared one — a screen author still gets a recognizable glyph instead of
+// a bare label. Checked against the actually registered IconKey vocabulary
+// (nav-icon.ts) — no entry for verbs without a matching icon (e.g. "start",
+// "pause").
+export const ACTION_ICON_BY_ID = {
+    delete: "trash",
+    deletion: "trash",
+    edit: "pencil",
+    create: "plus",
+    new: "plus",
+    add: "plus",
+    view: "eye",
+    open: "eye",
+    cancel: "x",
+    reject: "x",
+    complete: "check",
+    resolve: "check",
+    approve: "check",
+    archive: "archive",
+    publish: "upload",
+    duplicate: "copy",
+    copy: "copy",
+    download: "download",
+    refresh: "refresh",
+    retry: "refresh",
+    settings: "settings",
+    share: "share",
+    send: "send",
+};
+// Ids are kebab-case (RowAction.id doc): aggregate-object-verb
+// ("order-ship") or verb-prefix ("add-item").
+function kebabLastSegment(id) {
+    const idx = id.lastIndexOf("-");
+    return idx === -1 ? id : id.slice(idx + 1);
+}
+function kebabFirstSegment(id) {
+    const idx = id.indexOf("-");
+    return idx === -1 ? id : id.slice(0, idx);
+}
+// Resolution order: author-declared `icon` wins, then the id-derived
+// default (full id, then its last kebab segment, then its first kebab
+// segment). `declared` is `undefined` for ToolbarAction, which has no
+// author-facing icon field.
+export function resolveActionIcon(id, declared) {
+    if (declared !== undefined)
+        return declared;
+    return (ACTION_ICON_BY_ID[id] ??
+        ACTION_ICON_BY_ID[kebabLastSegment(id)] ??
+        ACTION_ICON_BY_ID[kebabFirstSegment(id)]);
+}

package/{src/agent-exposure.ts → dist/agent-exposure.d.ts}

@@ -1,22 +1,15 @@
-import type { AgentExposure, AgentHandlerHints } from "./handlers";
-
+import type { AgentExposure, AgentHandlerHints } from "./handlers.js";
 /** Fail-closed: a handler without a `description` stays invisible to the agent
  *  unless it opts in explicitly. `kind` is a parameter because write and query
  *  handler definitions are structurally indistinguishable at runtime. */
-export function resolveAgentExposure(
-  def: { readonly description?: string; readonly agent?: AgentHandlerHints },
-  kind: "query" | "write",
-): AgentExposure {
-  return {
-    expose: def.agent?.expose ?? def.description !== undefined,
-    risk: def.agent?.risk ?? (kind === "query" ? "low" : "mid"),
-  };
-}
-
+export declare function resolveAgentExposure(def: {
+    readonly description?: string;
+    readonly agent?: AgentHandlerHints;
+}, kind: "query" | "write"): AgentExposure;
 /** Screens are the inverse of handlers: the manifest lists every role-visible
  *  screen regardless of `description`, so only an explicit opt-out hides one.
  *  Reusing `resolveAgentExposure`'s fail-closed default here would silently
  *  drop every screen without a description from the agent's view. */
-export function isAgentVisibleScreen(screen: { readonly agent?: AgentHandlerHints }): boolean {
-  return screen.agent?.expose !== false;
-}
+export declare function isAgentVisibleScreen(screen: {
+    readonly agent?: AgentHandlerHints;
+}): boolean;

package/dist/agent-exposure.js

@@ -0,0 +1,16 @@
+/** Fail-closed: a handler without a `description` stays invisible to the agent
+ *  unless it opts in explicitly. `kind` is a parameter because write and query
+ *  handler definitions are structurally indistinguishable at runtime. */
+export function resolveAgentExposure(def, kind) {
+    return {
+        expose: def.agent?.expose ?? def.description !== undefined,
+        risk: def.agent?.risk ?? (kind === "query" ? "low" : "mid"),
+    };
+}
+/** Screens are the inverse of handlers: the manifest lists every role-visible
+ *  screen regardless of `description`, so only an explicit opt-out hides one.
+ *  Reusing `resolveAgentExposure`'s fail-closed default here would silently
+ *  drop every screen without a description from the agent's view. */
+export function isAgentVisibleScreen(screen) {
+    return screen.agent?.expose !== false;
+}

package/dist/concurrency-mode.d.ts

@@ -0,0 +1 @@
+export type ConcurrencyMode = "parallel" | "skip" | "replace" | "sequential" | "debounce";

package/dist/config-scope.d.ts

@@ -0,0 +1 @@
+export type ConfigScope = "system" | "tenant" | "user";

package/dist/config-scope.js

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

package/dist/config.d.ts

@@ -0,0 +1,234 @@
+import type { ZodType } from "zod";
+import type { ConcurrencyMode } from "./concurrency-mode.js";
+import type { ConfigScope } from "./config-scope.js";
+import type { DbConnection } from "./db-connection.js";
+import type { FieldDefinition } from "./fields.js";
+import type { EscapeHatchDeclaration, JobContext } from "./handlers.js";
+import type { PostDeleteHookFn, PostSaveHookFn, PreDeleteHookFn, PreQueryHookFn, PreSaveHookFn } from "./hooks.js";
+import type { TenantId } from "./identifiers.js";
+import type { NavIconKey } from "./nav-icon.js";
+import type { TenantDb } from "./tenant-db-types.js";
+export type ConfigKeyAccess = {
+    readonly read: readonly string[];
+    readonly write: readonly string[];
+};
+export type ConfigKeyType = "text" | "number" | "boolean" | "select";
+export type ConfigValue<T extends ConfigKeyType> = T extends "number" ? number : T extends "boolean" ? boolean : T extends "text" | "select" ? string : never;
+export type ConfigBounds = {
+    readonly min?: number;
+    readonly max?: number;
+};
+export type ConfigComputedContext = {
+    readonly tenantId: TenantId;
+    readonly userId: string;
+    readonly db: DbConnection | TenantDb;
+};
+export type ConfigComputedFn<T extends ConfigKeyType = ConfigKeyType> = (ctx: ConfigComputedContext) => Promise<ConfigValue<T>>;
+export type ConfigBacking = "config" | "secrets";
+export type ConfigSecretsReader = {
+    get(tenantId: TenantId, key: string): Promise<{
+        readonly reveal: () => string;
+    } | undefined>;
+};
+export type ConfigKeyDefinition<T extends ConfigKeyType = ConfigKeyType> = {
+    readonly type: T;
+    readonly default?: ConfigValue<T>;
+    readonly scope: ConfigScope;
+    readonly access: ConfigKeyAccess;
+    readonly encrypted?: boolean;
+    /** User/admin may legitimately see the value — unlike `encrypted`
+     *  (shared master-key cipher), this is the subject-KMS: the value is
+     *  encrypted under the DEK of the scope actually written to (tenant-row
+     *  → tenant subject, user-row → user subject). Only on `type: "text"`,
+     *  `scope !== "system"` (no subject there), and mutually exclusive with
+     *  `encrypted` (kumiko-platform#231/#459). */
+    readonly piiEncrypted?: boolean;
+    readonly options?: readonly string[];
+    readonly bounds?: ConfigBounds;
+    readonly pattern?: {
+        readonly regex: string;
+        readonly flags?: string;
+    };
+    readonly computed?: ConfigComputedFn<T>;
+    readonly allowPerRequest?: boolean;
+    readonly required?: boolean;
+    readonly env?: string;
+    readonly inheritedToTenant?: boolean;
+    readonly backing?: ConfigBacking;
+    readonly mask?: ConfigMask;
+    readonly group?: string;
+};
+export type ConfigMask = {
+    readonly title: string;
+    readonly icon?: NavIconKey;
+    readonly order?: number;
+};
+export type ConfigDefinition = {
+    readonly keys: Readonly<Record<string, ConfigKeyDefinition>>;
+};
+export type ConfigKeyHandle<T extends ConfigKeyType = ConfigKeyType> = {
+    readonly name: string;
+    readonly type: T;
+};
+export type ConfigAccessor = {
+    (qualifiedKey: string): Promise<string | number | boolean | undefined>;
+    <T extends ConfigKeyType>(handle: ConfigKeyHandle<T>): Promise<ConfigValue<T> | undefined>;
+};
+export type ConfigAccessorFactory = (deps: {
+    readonly user: {
+        readonly id: string;
+        readonly tenantId: TenantId;
+    };
+    readonly db: DbConnection | TenantDb;
+    readonly secrets?: ConfigSecretsReader;
+}) => ConfigAccessor;
+export type ConfigStoredRow = {
+    readonly id: string;
+    readonly key: string;
+    readonly value: string | null;
+    readonly tenantId: string;
+    readonly userId: string | null;
+};
+export type ConfigStoredRowWithSource = ConfigStoredRow & {
+    readonly source: ConfigValueSource;
+};
+export type ConfigValueSource = "user-row" | "tenant-row" | "system-row" | "app-override" | "computed" | "default" | "missing";
+export type ConfigValueWithSource = {
+    readonly value: string | number | boolean | undefined;
+    readonly source: ConfigValueSource;
+};
+export type ConfigCascadeLevel = {
+    readonly label: string;
+    readonly value: string | number | boolean | undefined;
+    readonly source: ConfigValueSource;
+    readonly isActive: boolean;
+    readonly hasValue: boolean;
+};
+export type ConfigCascade = {
+    readonly value: string | number | boolean | undefined;
+    readonly source: ConfigValueSource;
+    readonly levels: readonly ConfigCascadeLevel[];
+};
+export type ConfigResolver = {
+    get(qualifiedKey: string, keyDef: ConfigKeyDefinition, tenantId: TenantId, userId: string, db: DbConnection | TenantDb, secretsReader?: ConfigSecretsReader): Promise<string | number | boolean | undefined>;
+    getWithSource(qualifiedKey: string, keyDef: ConfigKeyDefinition, tenantId: TenantId, userId: string, db: DbConnection | TenantDb, secretsReader?: ConfigSecretsReader): Promise<ConfigValueWithSource>;
+    getAll(tenantId: TenantId, userId: string, db: DbConnection | TenantDb): Promise<ReadonlyMap<string, ConfigStoredRow>>;
+    getCascade(qualifiedKey: string, keyDef: ConfigKeyDefinition, tenantId: TenantId, userId: string, db: DbConnection | TenantDb, secretsReader?: ConfigSecretsReader): Promise<ConfigCascade>;
+    getCascadeBatch(keys: readonly string[], keyDefs: ReadonlyMap<string, ConfigKeyDefinition>, tenantId: TenantId, userId: string, db: DbConnection | TenantDb, secretsReader?: ConfigSecretsReader): Promise<ReadonlyMap<string, ConfigCascade>>;
+};
+export type RunIn = "api" | "worker" | "both";
+export type JobRunIn = Exclude<RunIn, "both">;
+export type JobHandlerFn = (payload: Record<string, unknown>, context: JobContext) => Promise<void>;
+export type JobTrigger = {
+    readonly on: import("./handlers.js").NameOrRef | readonly import("./handlers.js").NameOrRef[];
+    readonly where?: Readonly<Record<string, string | number | boolean>>;
+} | {
+    readonly cron: string;
+} | {
+    readonly manual: true;
+};
+export type JobBackoffStrategy = "fixed" | "exponential";
+export type JobBackoff = JobBackoffStrategy | {
+    readonly type: JobBackoffStrategy;
+    readonly delayMs?: number | undefined;
+};
+export type JobDefinition = {
+    readonly name: string;
+    readonly handler: JobHandlerFn;
+    readonly trigger: JobTrigger;
+    readonly concurrency?: ConcurrencyMode | undefined;
+    readonly maxPerTenant?: number | undefined;
+    readonly debounceMs?: number | undefined;
+    readonly retries?: number | undefined;
+    readonly backoff?: JobBackoff | undefined;
+    readonly timeout?: number | undefined;
+    readonly schema?: ZodType | undefined;
+    readonly runOnBoot?: boolean | undefined;
+    readonly bootGate?: boolean | undefined;
+    readonly perTenant?: boolean | undefined;
+    readonly runIn?: JobRunIn | undefined;
+    readonly escapeHatch?: EscapeHatchDeclaration | undefined;
+    readonly tenantVisibleFailure?: {
+        readonly messageKey: string;
+        readonly subjectFields?: readonly string[] | undefined;
+    } | undefined;
+};
+export type NotificationRecipientFn = (result: import("./hooks.js").SaveContext) => string | readonly string[] | {
+    readonly tenant: string;
+} | null;
+export type NotificationDataFn = (result: import("./hooks.js").SaveContext) => Record<string, unknown>;
+export type NotificationTemplateFn = (data: Record<string, unknown>) => Record<string, unknown>;
+export type NotificationDefinition = {
+    readonly name: string;
+    readonly trigger: {
+        readonly on: string;
+    };
+    readonly recipient: NotificationRecipientFn;
+    readonly data: NotificationDataFn;
+    readonly templates: Readonly<Record<string, NotificationTemplateFn>> | undefined;
+};
+export type PluralForms = {
+    readonly zero?: string;
+    readonly one?: string;
+    readonly two?: string;
+    readonly few?: string;
+    readonly many?: string;
+    readonly other: string;
+};
+export type TranslationValue = string | PluralForms;
+export type TranslationEntry = Readonly<Record<string, TranslationValue>>;
+export type TranslationKeys = Readonly<Record<string, TranslationEntry>>;
+export type TranslationsDef = {
+    readonly keys: TranslationKeys;
+};
+export type RegistrarExtensionHooks = {
+    readonly preSave?: PreSaveHookFn;
+    readonly postSave?: PostSaveHookFn;
+    readonly preDelete?: PreDeleteHookFn;
+    readonly postDelete?: PostDeleteHookFn;
+    readonly preQuery?: PreQueryHookFn;
+};
+export type UiExtensionDef = {
+    readonly editSection?: string;
+    readonly listColumns?: string;
+    readonly filters?: string;
+};
+export type RegistrarExtensionDef = {
+    readonly onRegister?: (entityName: string, options?: Record<string, unknown>) => void;
+    readonly extendSchema?: (entityName: string) => Record<string, FieldDefinition>;
+    readonly hooks?: RegistrarExtensionHooks;
+    readonly extendSearch?: (entityName: string) => Record<string, unknown>;
+    readonly uiExtension?: UiExtensionDef;
+};
+export type RegistrarExtensionRegistration = {
+    readonly extensionName: string;
+    readonly entityName: string;
+    readonly options?: Record<string, unknown> | undefined;
+    readonly featureName?: string;
+};
+export type ExtensionSelectorDef = {
+    readonly extensionName: string;
+    readonly qualifiedKey: string;
+};
+export type ReferenceDataDef = {
+    readonly entityName: string;
+    readonly data: readonly Record<string, unknown>[];
+    readonly upsertKey?: string | undefined;
+};
+export type ConfigSeedDef = {
+    readonly key: string;
+    readonly value: string | number | boolean;
+    readonly scope?: ConfigScope;
+    readonly tenantId?: string;
+    readonly userId?: string;
+};
+export type CreateSeedOptions = {
+    readonly value: string | number | boolean;
+};
+export type CreateTenantSeedOptions = {
+    readonly tenantId?: string;
+};
+export type CreateUserSeedOptions = {
+    readonly tenantId: string;
+    readonly userId: string;
+};

package/dist/config.js

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

package/dist/cursor-types.d.ts

@@ -0,0 +1,16 @@
+import type { EntityId, TenantId } from "./identifiers.js";
+export type CursorQueryOptions = {
+    tenantId: TenantId;
+    cursor?: string;
+    limit?: number;
+    filterIds?: readonly EntityId[];
+    sort?: string;
+    sortDirection?: "asc" | "desc";
+};
+export type CursorResult<T> = {
+    rows: T[];
+    nextCursor: string | null;
+    /** Optional total row count — only present when the caller sets
+     *  `totalCount: true` on the query. */
+    total?: number;
+};

package/dist/cursor-types.js

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

package/dist/db-connection.d.ts

@@ -0,0 +1,14 @@
+import type postgres from "postgres";
+export type RawDbClient = {
+    unsafe: (...args: any[]) => any;
+    begin: (...args: any[]) => any;
+    end?: (options?: {
+        timeout?: number;
+    }) => Promise<void>;
+};
+export type DbConnection = ReturnType<typeof postgres> | RawDbClient;
+export type DbTx = postgres.TransactionSql<Record<string, unknown>> | RawDbClient;
+export type DbRunner = DbConnection | DbTx;
+export type DbRow = Record<string, unknown>;
+export type PgClient = ReturnType<typeof postgres>;
+export type PgListenClient = ReturnType<typeof postgres>;

package/dist/db-connection.js

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

package/dist/define-handler.d.ts

@@ -0,0 +1,58 @@
+import type * as z from "zod";
+import type { ZodType } from "zod";
+import type { KumikoEventTypeMap } from "./event-type-map.js";
+import type { AccessRule, AgentHandlerHints, EscapeHatchDeclaration, HandlerContext, QueryEvent, RateLimitDeclaration, WriteEvent, WriteResult } from "./handlers.js";
+import type { PipelineDef } from "./step.js";
+export type WriteHandlerDefinition<TName extends string = string, TSchema extends ZodType = ZodType, TData = unknown, TMap extends object = KumikoEventTypeMap> = {
+    readonly name: TName;
+    readonly schema: TSchema;
+    readonly access: AccessRule;
+    readonly description?: string;
+    readonly agent?: AgentHandlerHints;
+    readonly unsafeSkipTransitionGuard?: boolean;
+    readonly rateLimit?: RateLimitDeclaration;
+    readonly escapeHatch?: EscapeHatchDeclaration;
+    readonly handler: (event: WriteEvent<z.infer<TSchema>>, context: HandlerContext<TMap>) => Promise<WriteResult<TData>>;
+    readonly perform?: PipelineDef<z.infer<TSchema>, TData>;
+};
+export type WriteHandlerInput<TName extends string = string, TSchema extends ZodType = ZodType, TData = unknown, TMap extends object = KumikoEventTypeMap> = {
+    readonly name: TName;
+    readonly schema: TSchema;
+    readonly access: AccessRule;
+    readonly description?: string;
+    readonly agent?: AgentHandlerHints;
+    readonly unsafeSkipTransitionGuard?: boolean;
+    readonly rateLimit?: RateLimitDeclaration;
+    readonly escapeHatch?: EscapeHatchDeclaration;
+} & ({
+    readonly handler: (event: WriteEvent<z.infer<TSchema>>, context: HandlerContext<TMap>) => Promise<WriteResult<TData>>;
+    readonly perform?: never;
+} | {
+    readonly perform: PipelineDef<z.infer<TSchema>, TData>;
+    readonly handler?: never;
+});
+export type QueryHandlerDefinition<TName extends string = string, TSchema extends ZodType = ZodType, TResult = unknown, TMap extends object = KumikoEventTypeMap> = {
+    readonly name: TName;
+    readonly schema: TSchema;
+    readonly access: AccessRule;
+    readonly description?: string;
+    readonly agent?: AgentHandlerHints;
+    readonly rateLimit?: RateLimitDeclaration;
+    readonly escapeHatch?: EscapeHatchDeclaration;
+    readonly handler: (query: QueryEvent<z.infer<TSchema>>, context: HandlerContext<TMap>) => Promise<TResult>;
+    /** Zod schema of `handler`'s actual return value — see QueryHandlerDef's
+     *  doc (handlers.ts) for the boot-validator checks this unlocks. Not
+     *  inferred from `TResult`: TResult is a compile-time-only type param
+     *  (this function never receives a runtime schema for it), so callers
+     *  that want boot-time column checks declare `outputSchema` explicitly,
+     *  same as `schema` for the input side. */
+    readonly outputSchema?: ZodType;
+};
+export type StreamHandlerDefinition<TName extends string = string, TSchema extends ZodType = ZodType, TChunk = unknown, TMap extends object = KumikoEventTypeMap> = {
+    readonly name: TName;
+    readonly schema: TSchema;
+    readonly access: AccessRule;
+    readonly rateLimit?: RateLimitDeclaration;
+    readonly escapeHatch?: EscapeHatchDeclaration;
+    readonly handler: (query: QueryEvent<z.infer<TSchema>>, context: HandlerContext<TMap>) => AsyncGenerator<TChunk>;
+};

package/dist/define-handler.js

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

package/dist/derivatives-types.d.ts

@@ -0,0 +1,53 @@
+export type VariantFit = "cover" | "inside" | "contain";
+export type VariantFormat = "webp" | "avif" | "jpeg";
+export type BlurRegion = {
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+};
+export type OverlayGravity = "north-west" | "north-east" | "south-west" | "south-east" | "center";
+type OverlayPlacement = {
+    readonly widthPct: number;
+    readonly gravity: OverlayGravity;
+    readonly marginPct?: number;
+};
+export type OverlayLayer = ({
+    readonly kind: "qr";
+    readonly dataToken: string;
+} & OverlayPlacement) | ({
+    readonly kind: "image";
+    readonly imageBase64: string;
+} & OverlayPlacement);
+export type ResolvedOverlayLayer = ({
+    readonly kind: "qr";
+    readonly data: string;
+} & OverlayPlacement) | Extract<OverlayLayer, {
+    kind: "image";
+}>;
+export type VariantSpec = {
+    readonly fit?: VariantFit;
+    readonly size?: {
+        readonly width: number;
+        readonly height: number;
+    };
+    readonly maxEdge?: number;
+    readonly format?: VariantFormat;
+    readonly quality?: number;
+    readonly blur?: number;
+    readonly blurRegions?: readonly BlurRegion[];
+    readonly overlays?: readonly OverlayLayer[];
+    readonly resolvedOverlays?: readonly ResolvedOverlayLayer[];
+};
+export type DerivativeRendererPlugin = {
+    readonly render: (input: Uint8Array, spec: VariantSpec, sourceMimeType: string) => Promise<Uint8Array>;
+};
+export type VariantResult = {
+    readonly storageKey: string;
+    readonly mimeType: string;
+    readonly rendered: boolean;
+};
+export type DerivativesContext = {
+    readonly variant: (fileRefId: string, spec: VariantSpec, name: string) => Promise<VariantResult>;
+};
+export {};

package/dist/derivatives-types.js

@@ -0,0 +1,3 @@
+// Derived-file-variants (thumbnails, resized/reformatted images, …) — pure
+// types, no runtime logic. Client-visible package: no `node:*` imports.
+export {};

package/dist/entity-cache.d.ts

@@ -0,0 +1,16 @@
+import type { EntityId, TenantId } from "./identifiers.js";
+export type EntityCache = {
+    /** Get a single cached entity. Returns null on miss. */
+    get(tenantId: TenantId, entityName: string, id: EntityId): Promise<Record<string, unknown> | null>;
+    /** Get multiple cached entities. Returns a Map of id → data (misses are absent). */
+    mget(tenantId: TenantId, entityName: string, ids: readonly EntityId[]): Promise<Map<EntityId, Record<string, unknown>>>;
+    /** Cache a single entity. */
+    set(tenantId: TenantId, entityName: string, id: EntityId, data: Record<string, unknown>): Promise<void>;
+    /** Cache multiple entities at once. */
+    mset(tenantId: TenantId, entityName: string, entries: ReadonlyArray<{
+        id: EntityId;
+        data: Record<string, unknown>;
+    }>): Promise<void>;
+    /** Invalidate a single cached entity. */
+    del(tenantId: TenantId, entityName: string, id: EntityId): Promise<void>;
+};

package/dist/entity-cache.js

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

package/dist/entity-handlers.d.ts

@@ -0,0 +1,54 @@
+import type { EntityDefinition } from "./fields.js";
+import type { AccessRule, AgentHandlerHints, EscapeHatchDeclaration, QueryHandlerDef, WriteHandlerDef } from "./handlers.js";
+export type EntityHandlerOptions = {
+    readonly access: AccessRule;
+    readonly description?: string;
+    readonly agent?: AgentHandlerHints;
+    /** 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. Every use reports an
+     *  `acknowledge-cross-tenant` escape-hatch audit event. On write handlers
+     *  update/delete/restore address the target row's own tenant stream.
+     *  `access` stays the only caller gate. Unlike `escapeHatch` on a
+     *  hand-written handler this does NOT grant `ctx.db.unsafeRaw`,
+     *  `db.global()` writes or identity switches. */
+    readonly escapeHatch?: EscapeHatchDeclaration;
+    /** @deprecated Use `escapeHatch: { reason }` — removed in a future release;
+     *  run `scripts/codemod/migrate-cross-tenant.ts`. */
+    readonly crossTenant?: boolean;
+};
+/** Options for the generic create/update handlers. */
+export type EntityWriteHandlerOptions = EntityHandlerOptions & {
+    /** Fields this handler never writes. They leave the payload schema as
+     *  "must be absent": a payload that still carries one fails validation
+     *  instead of being stripped silently. create rejects a required field
+     *  without default here, since the row could never be created. */
+    readonly excludeFields?: readonly string[];
+};
+export type EntityQueryHandlerOptions = EntityHandlerOptions;
+export type EntityCrudVerb = "create" | "update" | "delete" | "restore" | "list" | "detail";
+export type EntityCrudHandlerDefaults = Omit<EntityHandlerOptions, "access"> & {
+    readonly access?: AccessRule;
+};
+export type RegisterEntityCrudOptions = {
+    readonly write?: EntityCrudHandlerDefaults;
+    readonly read?: EntityCrudHandlerDefaults;
+    readonly verbs?: Partial<Record<EntityCrudVerb, boolean>>;
+    /** Per-verb access override — falls back to `write.access`/`read.access` when unset for a verb. */
+    readonly verbAccess?: Partial<Record<EntityCrudVerb, AccessRule>>;
+    /** 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). Falls back to `write.description`/`read.description`. */
+    readonly descriptions?: Partial<Record<EntityCrudVerb, string>>;
+    /** Per-verb `excludeFields` for the generic create/update handlers — see
+     *  EntityWriteHandlerOptions. */
+    readonly excludeFields?: Partial<Record<"create" | "update", readonly string[]>>;
+    /** Default true. Set false when the entity was already registered (e.g. before r.relation). */
+    readonly registerEntity?: boolean;
+};
+/** Minimal registrar surface — keeps entity-handlers free of define-feature imports. */
+export type EntityCrudRegistrar = {
+    entity(name: string, definition: EntityDefinition): unknown;
+    writeHandler(def: WriteHandlerDef): unknown;
+    queryHandler(def: QueryHandlerDef): unknown;
+};

package/dist/entity-handlers.js

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

package/dist/entity-table-meta-types.d.ts

@@ -0,0 +1,44 @@
+import type { EntityRelations } from "./relations.js";
+import type { EntityTenancy } from "./tenancy-brand.js";
+export type PgType = "uuid" | "text" | "boolean" | "integer" | "double precision" | "bigint" | "serial" | "bigserial" | "jsonb" | "timestamptz" | "timestamptz(3)" | "date" | `numeric(${number},${number})`;
+export type ColumnMeta = {
+    readonly name: string;
+    readonly pgType: PgType;
+    readonly notNull: boolean;
+    readonly defaultSql?: string;
+    readonly primaryKey?: boolean;
+    readonly identity?: boolean;
+    readonly bigintJsMode?: "number" | "bigint";
+};
+export type IndexMeta = {
+    readonly name: string;
+    readonly columns: readonly string[];
+    readonly unique?: boolean;
+    readonly whereSql?: string;
+    readonly needsManualWhere?: boolean;
+};
+export type CompositePrimaryKeyMeta = {
+    readonly name: string;
+    readonly columns: readonly string[];
+};
+export type EntityTableMeta = {
+    readonly tableName: string;
+    readonly columns: readonly ColumnMeta[];
+    readonly indexes: readonly IndexMeta[];
+    readonly compositePrimaryKey?: CompositePrimaryKeyMeta;
+    readonly source: "managed" | "unmanaged";
+    readonly piiSubjectFields?: readonly string[];
+    readonly tenancy?: "global";
+};
+export type BuildEntityTableMetaOptions = {
+    readonly featureName?: string;
+    readonly relations?: EntityRelations;
+    readonly source?: EntityTableMeta["source"];
+};
+export type UnmanagedTableInput = {
+    readonly tableName: string;
+    readonly columns: readonly ColumnMeta[];
+    readonly indexes?: readonly IndexMeta[];
+    readonly compositePrimaryKey?: CompositePrimaryKeyMeta;
+    readonly tenancy?: EntityTenancy;
+};

package/dist/entity-table-meta-types.js

@@ -0,0 +1,6 @@
+// Plain-data types for EntityTableMeta — split from the runtime
+// (deriveEntityTableMeta, resolveTableName, defineUnmanagedTable) in
+// entity-table-meta.ts. Prep step for the types-only package extraction
+// (#1283) — this file must have ONLY `import type`, no value imports
+// (crypto/DB deps).
+export {};

package/dist/envelope-cipher-types.d.ts

@@ -0,0 +1,5 @@
+import type { KeyScope } from "./secrets-types.js";
+export type EnvelopeCipher = {
+    encrypt(plaintext: string, scope?: KeyScope): Promise<string>;
+    decrypt(stored: string, scope?: KeyScope): Promise<string>;
+};

package/dist/envelope-cipher-types.js

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