@murumets-ee/entity 0.10.0 → 0.12.0

package/dist/admin/index.d.mts

@@ -36,78 +36,6 @@ interface CountCacheLike {
   invalidate(prefix: string): void;
 }
 //#endregion
-//#region src/cursor.d.ts
-/** Cursor input for keyset pagination. */
-interface CursorInput {
-  /** Sort field name (e.g. 'createdAt'). Must be a real column on the entity. */
-  field: string;
-  /** Last seen value of the sort field. */
-  value: string | number;
-  /** Sort direction — must match the ORDER BY direction. */
-  direction: 'asc' | 'desc';
-  /** Tie-breaker: last seen entity ID. Required for non-unique sort fields. */
-  id?: string;
-}
-//#endregion
-//#region src/admin-config.d.ts
-/**
- * Optional admin UI configuration for entities.
- * Controls how entities appear in the admin sidebar, list pages, and forms.
- */
-interface EntityAdminConfig {
-  /** Sidebar section: 'content' | 'structure' | custom string. Default: 'content' */
-  group?: string;
-  /** Plural display name for sidebar + list pages. Default: title-cased pluralized entity name */
-  label?: string;
-  /** Singular label for "New X" button. Default: title-cased entity name */
-  labelSingular?: string;
-  /** Lucide icon name as string, e.g. 'file-text' */
-  icon?: string;
-  /** Description shown on list page */
-  description?: string;
-  /** Form layout. Default: 'single' */
-  layout?: 'single' | 'two-column';
-  /** Fields to hide in the form */
-  hiddenFields?: string[];
-  /** Columns to hide in the list */
-  hiddenColumns?: string[];
-  /** Per-field label/description/placeholder overrides */
-  fieldOverrides?: Record<string, {
-    label?: string;
-    description?: string;
-    placeholder?: string;
-  }>;
-  /** Default list sort field. Default: 'createdAt' */
-  defaultSort?: string;
-  /** Default list sort direction. Default: 'desc' */
-  defaultSortDirection?: 'asc' | 'desc';
-  /** List page size. Default: 20 */
-  pageSize?: number;
-  /** For block editor: fields to show in Puck root config */
-  rootFields?: string[];
-  /** Suppress "New" button in the list page */
-  disableCreate?: boolean;
-  /** Order within sidebar group. Default: 0 */
-  sortOrder?: number;
-  /**
-   * Hide the entity from BOTH dashboard and sidebar.
-   * Use for system entities that should not appear in any UI.
-   * Shorthand for `hideFromMenu: true` + `hideFromDashboard: true`.
-   */
-  hidden?: boolean;
-  /**
-   * Hide from sidebar menu only. Entity remains accessible via dashboard, direct URL,
-   * and the entity API. Use for storage models accessed through specialized UI
-   * (e.g., Ticket entities accessed via the inbox/board, not as a CRUD table).
-   */
-  hideFromMenu?: boolean;
-  /**
-   * Hide from dashboard widget grid only. Entity still appears in sidebar.
-   * Use for entities that don't have meaningful counts/stats to show.
-   */
-  hideFromDashboard?: boolean;
-}
-//#endregion
 //#region src/fields/base.d.ts
 /**
  * Field type definitions
@@ -119,6 +47,23 @@ interface BaseFieldConfig {
   translatable?: boolean;
   indexed?: boolean;
   unique?: boolean;
+  /**
+   * Marks the field as **system-managed**: stored as a real column, populated
+   * by behavior hooks or trusted server-side transitions, but NOT writable
+   * through the public `AdminClient.create/update` surface.
+   *
+   * - Caller-supplied values for internal fields are silently stripped before
+   *   hooks run (so an HTTP PATCH cannot poison a workflow state).
+   * - `beforeCreate` / `beforeUpdate` hooks may still set them (they run after
+   *   the strip), and the values are preserved through validation.
+   * - Trusted server code that needs to write internals directly — e.g.
+   *   workflow transitions invoked from an authorized admin route — must use
+   *   `AdminClient.updateInternal()`, which bypasses the strip.
+   *
+   * Use this flag on any field added by a behavior whose value represents a
+   * controlled state machine (e.g. `_workflowStatus`), not user input.
+   */
+  internal?: boolean;
   access?: {
     view?: string;
     edit?: string;
@@ -199,12 +144,138 @@ interface BlocksField extends BaseFieldConfig {
 }
 type FieldConfig = IdField | TextField | NumberField | BooleanField | DateField | SelectField | ReferenceField | MediaField | RichTextField | SlugField | JsonField | BlocksField;
 //#endregion
+//#region src/types/infer.d.ts
+/**
+ * Recursive JSON-compatible value, for `field.json()` (jsonb column).
+ * Mirrors what Postgres jsonb can store: primitives, arrays, or objects.
+ */
+type JsonValue = string | number | boolean | null | JsonValue[] | {
+  [key: string]: JsonValue;
+};
+/**
+ * Maps a single FieldConfig to its TypeScript output type.
+ * Each branch is a shallow comparison — no recursion.
+ */
+type FieldToTS<F extends FieldConfig> = F extends IdField ? string : F extends TextField ? string : F extends NumberField ? number : F extends BooleanField ? boolean : F extends DateField ? Date | string : F extends SelectField ? F['options'][number] : F extends ReferenceField ? F['cardinality'] extends 'many' ? string[] : string : F extends MediaField ? string : F extends RichTextField ? Record<string, unknown>[] : F extends SlugField ? string : F extends JsonField ? JsonValue : F extends BlocksField ? Array<{
+  _block: string;
+  _id: string;
+  [key: string]: unknown;
+}> : never;
+/**
+ * Maps a full field record to its TypeScript output type.
+ * Required fields are non-nullable; optional fields are `T | null | undefined`.
+ *
+ * The `id` field is always `string` and always present.
+ * The `id` key from Fields is excluded to avoid duplication since
+ * we hardcode `{ id: string }` at the front.
+ */
+type InferEntityDTO<Fields extends Record<string, FieldConfig>> = {
+  id: string;
+} & { [K in keyof Fields as K extends 'id' ? never : Fields[K]['required'] extends true ? K : never]: FieldToTS<Fields[K]> } & { [K in keyof Fields as Fields[K]['required'] extends true ? never : K]?: FieldToTS<Fields[K]> | null };
+/** Fields that are auto-generated and should not appear in create input. */
+type AutoGeneratedFields = 'id' | 'createdAt' | 'updatedAt' | 'createdBy' | 'updatedBy' | '_version';
+/**
+ * The input type for creating an entity.
+ * - Omits auto-generated fields (id, timestamps, version)
+ * - Required fields stay required; optional fields stay optional
+ */
+type InferCreateInput<Fields extends Record<string, FieldConfig>> = Omit<{ [K in keyof Fields as K extends 'id' ? never : Fields[K]['required'] extends true ? K : never]: FieldToTS<Fields[K]> } & { [K in keyof Fields as Fields[K]['required'] extends true ? never : K]?: FieldToTS<Fields[K]> | null }, AutoGeneratedFields>;
+/** Fields that cannot be changed after creation. */
+type ImmutableFields = 'id' | 'createdAt' | 'createdBy';
+type InferUpdateInput<Fields extends Record<string, FieldConfig>> = { [K in keyof Fields as K extends ImmutableFields ? never : K]?: FieldToTS<Fields[K]> | null };
+//#endregion
 //#region src/behaviors/types.d.ts
+/**
+ * Structural shape of a queue `JobDefinition` as seen by behaviors.
+ *
+ * The entity package CANNOT import `@murumets-ee/queue` (would form a
+ * cycle through `@murumets-ee/core`'s registry — see CLAUDE.md
+ * "Package boundaries"). Instead, behaviors receive an `EnqueueOnCommit`
+ * function via `BehaviorContext`, and the queue's `JobDefinition<T>`
+ * is structurally compatible with this minimal shape. The actual
+ * payload validation runs inside the queue when the wrapped resolver
+ * forwards the call.
+ */
+interface JobLike {
+  readonly name: string;
+}
+/**
+ * Resolver shape for `BehaviorContext.enqueueOnCommit`. Synchronous,
+ * fire-and-forget — the resolver writes the row in the background and
+ * logs failures; behaviors do NOT await.
+ *
+ * Intended semantics (PLAN-OUTBOX §4.2): the row INSERT participates
+ * in the AdminClient operation's transaction — commit makes the job
+ * visible to the worker, rollback removes it. As of PR D this is the
+ * actual semantics: AdminClient threads its tx into the
+ * `EnqueueOnCommitFactory` once per call and passes the result through
+ * to behaviors. When the queue plugin is not loaded the field is
+ * `undefined` and behaviors no-op (per §6 Q6).
+ */
+type EnqueueOnCommit = (job: JobLike, payload: unknown) => void;
+/**
+ * Factory that returns an {@link EnqueueOnCommit} resolver bound to an
+ * optional Drizzle transaction handle. AdminClient invokes this once
+ * per CRUD operation, passing the active tx so behaviors firing inside
+ * the operation enqueue rows that commit (or roll back) atomically
+ * with the entity write.
+ *
+ * The `tx` parameter is intentionally typed as `unknown` here — the
+ * entity package CANNOT import `drizzle-orm/postgres-js` types without
+ * pulling in the database stack and breaking its leaf-package contract.
+ * The queue plugin (which writes the slot) and AdminClient (which
+ * supplies the tx) both work with the precise `PostgresJsDatabase`
+ * shape; the interior of the factory casts as needed.
+ *
+ * **Mirror definition** lives in
+ * `packages/queue/src/enqueue-on-commit-slot.ts` with `tx?:
+ * PostgresJsDatabase`. The two are structurally compatible by design;
+ * if you rename or change one, change both. The runtime contract is
+ * the same — only the type-time visibility of the parameter differs.
+ */
+type EnqueueOnCommitFactory = (tx?: unknown) => EnqueueOnCommit;
 /**
  * Context passed to behavior hooks. Resolved once per request by AdminClient
  * from its `contextResolver` and forwarded into every hook so behaviors never
  * have to reach into AsyncLocalStorage themselves — that pattern breaks under
  * bundlers (e.g. Turbopack) that duplicate module instances across boundaries.
+ *
+ * `loadCurrent` returns the *pre-update* entity row. It is eagerly loaded
+ * by AdminClient before any hooks fire on the **update** codepath and
+ * cached for the rest of that call — so calling it from `beforeUpdate`
+ * or `afterUpdate` returns the SAME snapshot regardless of whether a
+ * sibling hook touched it. Returns `null` when no entity matches the id
+ * (rare — usually means the row was deleted concurrently). On `create`
+ * AND `delete` codepaths, `loadCurrent` is undefined: create has no
+ * pre-state, and delete hooks receive the entity id directly via their
+ * first argument so a separate snapshot is unnecessary.
+ *
+ * `afterUpdate` always receives the post-update row as its first argument,
+ * so the (`row`, `loadCurrent()`) pair gives hooks a complete (after, before)
+ * view without per-call Map state. The eager load costs one extra
+ * `findById` per update; updates are not a hot path in this codebase, and
+ * the consistency win — no foot-gun for hook authors — is worth it.
+ *
+ * `viaInternal` is `true` when the hook is running on an `AdminClient.updateInternal`
+ * call (the trusted server-side path; public PATCH always sets it false).
+ * Hooks SHOULD treat this as informational only — the route layer has
+ * authorized the *capability*, but the hook is still responsible for
+ * enforcing structural invariants. Workflowable, for example, validates
+ * the `_workflowStatus` transition table on every update regardless of
+ * `viaInternal` so that even a route-layer bug cannot push the workflow
+ * row into an illegal state. Use `viaInternal` when a hook genuinely
+ * needs to differentiate (e.g. side effects that should only fire when
+ * a real user — not the seed loader — initiates the change).
+ *
+ * `enqueueOnCommit` is the outbox entry point for projection-style hooks
+ * (PR C of PLAN-OUTBOX). When wired (the queue plugin is available in
+ * the running app), behaviors can enqueue side-effect jobs without
+ * importing the queue package directly, keeping entity-as-leaf invariant
+ * intact. Synchronous + fire-and-forget — no await needed in hooks.
+ * Undefined when the AdminClient was constructed without an
+ * `enqueueOnCommit` resolver (e.g. CLI scripts that don't load the
+ * queue plugin); behaviors that depend on it must guard with `if
+ * (ctx.enqueueOnCommit) { ... }` or document the dependency loudly.
  */
 interface BehaviorContext {
   user?: {
@@ -212,6 +283,9 @@ interface BehaviorContext {
     name?: string;
     email?: string;
   };
+  loadCurrent?: () => Promise<Record<string, unknown> | null>;
+  viaInternal?: boolean;
+  enqueueOnCommit?: EnqueueOnCommit;
 }
 interface Behavior<F extends Record<string, FieldConfig> = {}> {
   name: string;
@@ -226,6 +300,78 @@ interface Behavior<F extends Record<string, FieldConfig> = {}> {
   };
 }
 //#endregion
+//#region src/cursor.d.ts
+/** Cursor input for keyset pagination. */
+interface CursorInput {
+  /** Sort field name (e.g. 'createdAt'). Must be a real column on the entity. */
+  field: string;
+  /** Last seen value of the sort field. */
+  value: string | number;
+  /** Sort direction — must match the ORDER BY direction. */
+  direction: 'asc' | 'desc';
+  /** Tie-breaker: last seen entity ID. Required for non-unique sort fields. */
+  id?: string | undefined;
+}
+//#endregion
+//#region src/admin-config.d.ts
+/**
+ * Optional admin UI configuration for entities.
+ * Controls how entities appear in the admin sidebar, list pages, and forms.
+ */
+interface EntityAdminConfig {
+  /** Sidebar section: 'content' | 'structure' | custom string. Default: 'content' */
+  group?: string;
+  /** Plural display name for sidebar + list pages. Default: title-cased pluralized entity name */
+  label?: string;
+  /** Singular label for "New X" button. Default: title-cased entity name */
+  labelSingular?: string;
+  /** Lucide icon name as string, e.g. 'file-text' */
+  icon?: string;
+  /** Description shown on list page */
+  description?: string;
+  /** Form layout. Default: 'single' */
+  layout?: 'single' | 'two-column';
+  /** Fields to hide in the form */
+  hiddenFields?: string[];
+  /** Columns to hide in the list */
+  hiddenColumns?: string[];
+  /** Per-field label/description/placeholder overrides */
+  fieldOverrides?: Record<string, {
+    label?: string;
+    description?: string;
+    placeholder?: string;
+  }>;
+  /** Default list sort field. Default: 'createdAt' */
+  defaultSort?: string;
+  /** Default list sort direction. Default: 'desc' */
+  defaultSortDirection?: 'asc' | 'desc';
+  /** List page size. Default: 20 */
+  pageSize?: number;
+  /** For block editor: fields to show in Puck root config */
+  rootFields?: string[];
+  /** Suppress "New" button in the list page */
+  disableCreate?: boolean;
+  /** Order within sidebar group. Default: 0 */
+  sortOrder?: number;
+  /**
+   * Hide the entity from BOTH dashboard and sidebar.
+   * Use for system entities that should not appear in any UI.
+   * Shorthand for `hideFromMenu: true` + `hideFromDashboard: true`.
+   */
+  hidden?: boolean;
+  /**
+   * Hide from sidebar menu only. Entity remains accessible via dashboard, direct URL,
+   * and the entity API. Use for storage models accessed through specialized UI
+   * (e.g., Ticket entities accessed via the inbox/board, not as a CRUD table).
+   */
+  hideFromMenu?: boolean;
+  /**
+   * Hide from dashboard widget grid only. Entity still appears in sidebar.
+   * Use for entities that don't have meaningful counts/stats to show.
+   */
+  hideFromDashboard?: boolean;
+}
+//#endregion
 //#region src/define-entity.d.ts
 /**
  * A fully resolved entity with merged behavior fields.
@@ -277,46 +423,6 @@ interface SecurityContext {
  */
 type ContextResolver = () => SecurityContext | undefined | Promise<SecurityContext | undefined>;
 //#endregion
-//#region src/types/infer.d.ts
-/**
- * Recursive JSON-compatible value, for `field.json()` (jsonb column).
- * Mirrors what Postgres jsonb can store: primitives, arrays, or objects.
- */
-type JsonValue = string | number | boolean | null | JsonValue[] | {
-  [key: string]: JsonValue;
-};
-/**
- * Maps a single FieldConfig to its TypeScript output type.
- * Each branch is a shallow comparison — no recursion.
- */
-type FieldToTS<F extends FieldConfig> = F extends IdField ? string : F extends TextField ? string : F extends NumberField ? number : F extends BooleanField ? boolean : F extends DateField ? Date | string : F extends SelectField ? F['options'][number] : F extends ReferenceField ? F['cardinality'] extends 'many' ? string[] : string : F extends MediaField ? string : F extends RichTextField ? Record<string, unknown>[] : F extends SlugField ? string : F extends JsonField ? JsonValue : F extends BlocksField ? Array<{
-  _block: string;
-  _id: string;
-  [key: string]: unknown;
-}> : never;
-/**
- * Maps a full field record to its TypeScript output type.
- * Required fields are non-nullable; optional fields are `T | null | undefined`.
- *
- * The `id` field is always `string` and always present.
- * The `id` key from Fields is excluded to avoid duplication since
- * we hardcode `{ id: string }` at the front.
- */
-type InferEntityDTO<Fields extends Record<string, FieldConfig>> = {
-  id: string;
-} & { [K in keyof Fields as K extends 'id' ? never : Fields[K]['required'] extends true ? K : never]: FieldToTS<Fields[K]> } & { [K in keyof Fields as Fields[K]['required'] extends true ? never : K]?: FieldToTS<Fields[K]> | null };
-/** Fields that are auto-generated and should not appear in create input. */
-type AutoGeneratedFields = 'id' | 'createdAt' | 'updatedAt' | 'createdBy' | 'updatedBy' | '_version';
-/**
- * The input type for creating an entity.
- * - Omits auto-generated fields (id, timestamps, version)
- * - Required fields stay required; optional fields stay optional
- */
-type InferCreateInput<Fields extends Record<string, FieldConfig>> = Omit<{ [K in keyof Fields as K extends 'id' ? never : Fields[K]['required'] extends true ? K : never]: FieldToTS<Fields[K]> } & { [K in keyof Fields as Fields[K]['required'] extends true ? never : K]?: FieldToTS<Fields[K]> | null }, AutoGeneratedFields>;
-/** Fields that cannot be changed after creation. */
-type ImmutableFields = 'id' | 'createdAt' | 'createdBy';
-type InferUpdateInput<Fields extends Record<string, FieldConfig>> = { [K in keyof Fields as K extends ImmutableFields ? never : K]?: FieldToTS<Fields[K]> | null };
-//#endregion
 //#region src/types/logger.d.ts
 /**
  * Minimal logger interface compatible with Pino.
@@ -343,32 +449,64 @@ type EntityResolver = () => Map<string, Entity> | undefined;
 interface AdminClientConfig<AllFields extends Record<string, FieldConfig> = Record<string, FieldConfig>> {
   entity: Entity<AllFields>;
   db: PostgresJsDatabase;
-  logger?: Logger;
+  logger?: Logger | undefined;
   /** Optional count cache for COUNT(*) query optimization. */
-  countCache?: CountCacheLike;
+  countCache?: CountCacheLike | undefined;
   /**
    * Resolves the current request's security context (user, role checker, scope).
    * Provided automatically by `createAdminClient()` from @murumets-ee/core/clients.
    * For direct `new AdminClient()` usage, pass your own resolver or use `runAsCli()`.
    */
-  contextResolver?: ContextResolver;
+  contextResolver?: ContextResolver | undefined;
   /**
    * Resolves the running app's entity registry. Used by cascade delete to
    * read each referencing field's `onDelete` strategy. When omitted, all
    * incoming references are treated as `restrict` — a safe default that
    * blocks deletes rather than guessing.
    */
-  entityResolver?: EntityResolver;
+  entityResolver?: EntityResolver | undefined;
+  /**
+   * Outbox entry point exposed on `BehaviorContext.enqueueOnCommit`
+   * (PR C of PLAN-OUTBOX). When provided, projection-style behaviors can
+   * fire side-effect jobs from their hooks without importing the queue
+   * package — the entity package stays a leaf in the dependency graph.
+   *
+   * Used as a fallback when `enqueueOnCommitFactory` is not supplied:
+   * AdminClient passes this resolver verbatim into hook contexts, and
+   * the row INSERT is NOT bound to the operation's transaction. Tests
+   * that need to capture call-site behavior without wiring queue can
+   * pass this directly.
+   *
+   * In production wiring (`createAdminClient` in
+   * `@murumets-ee/core/clients`), prefer `enqueueOnCommitFactory` —
+   * that's the form that delivers PLAN-OUTBOX §4.2's "rollback removes
+   * the job" guarantee.
+   */
+  enqueueOnCommit?: BehaviorContext['enqueueOnCommit'] | undefined;
+  /**
+   * Outbox factory exposed on `BehaviorContext.enqueueOnCommit` (PR D
+   * of PLAN-OUTBOX). When provided, AdminClient invokes the factory
+   * once per CRUD operation with the active Drizzle transaction so the
+   * resulting fire-and-forget resolver routes its INSERT through that
+   * tx. Hook-fired enqueues commit (or roll back) atomically with the
+   * entity write — the canonical PLAN-OUTBOX §4.2 semantics.
+   *
+   * Wired by `createAdminClient()` in `@murumets-ee/core/clients`
+   * against the running app's queue plugin. Takes precedence over the
+   * older `enqueueOnCommit` field when both are set; CLI scripts that
+   * don't load the queue plugin omit both.
+   */
+  enqueueOnCommitFactory?: EnqueueOnCommitFactory | undefined;
 }
 interface FindManyOptions {
   where?: SQL | undefined;
-  limit?: number;
-  offset?: number;
-  orderBy?: SQL | SQL[];
-  locale?: string;
+  limit?: number | undefined;
+  offset?: number | undefined;
+  orderBy?: SQL | SQL[] | undefined;
+  locale?: string | undefined;
   /** Default content locale. For localized blocks, NULL rows (from initial create)
    *  are only returned as fallback when locale matches defaultLocale. */
-  defaultLocale?: string;
+  defaultLocale?: string | undefined;
   /**
    * Cursor-based (keyset) pagination. When provided, replaces OFFSET with a
    * WHERE condition for O(1) page access at any depth. The `offset` option
@@ -376,7 +514,13 @@ interface FindManyOptions {
    *
    * The cursor `field` must be a real column on the entity table.
    */
-  cursor?: CursorInput;
+  cursor?: CursorInput | undefined;
+  /**
+   * Include fields marked `internal: true` (and legacy `_`-prefixed
+   * infrastructure columns) in the returned DTOs. Use only on trusted
+   * server-side reads that need to inspect state-machine fields.
+   */
+  includeInternal?: boolean | undefined;
 }
 interface CountOptions {
   where?: SQL | undefined;
@@ -406,17 +550,84 @@ declare class AdminClient<AllFields extends Record<string, FieldConfig> = Record
   private entity;
   private db;
   private logger?;
+  /** Public-surface create schema — internal fields excluded. */
   private createSchema;
+  /** Public-surface update schema — internal fields excluded. */
   private updateSchema;
+  /** Trusted-surface update schema — internal fields included. Used by `updateInternal()`. */
+  private updateInternalSchema;
+  /** Names of fields marked `internal: true`. Cached for O(1) strip / pick. */
+  private internalFieldNames;
   private table;
   private countCache?;
   private contextResolver?;
   private entityResolver?;
-  /** Shared context for entity-data-ops functions. */
+  private enqueueOnCommit?;
+  private enqueueOnCommitFactory?;
+  /** Shared context for entity-data-ops functions, bound to the default db. */
   private get ctx();
+  /**
+   * Build an {@link EntityContext} bound to a specific Drizzle executor.
+   *
+   * Used by the public CRUD methods so that when the caller threads in
+   * `{ tx }` (PR D of PLAN-OUTBOX) every block-load / translation
+   * merge / scope-condition lookup hits the SAME tx as the entity write.
+   * Without this, a `loadBlocks(this.ctx, ...)` call inside an active tx
+   * would query `this.db` (the AdminClient's owned connection) and miss
+   * the in-flight INSERT — `entity_refs` / blocks rows wouldn't be
+   * visible until commit.
+   *
+   * For callers that don't pass a tx, `exec === this.db` and the ctx
+   * matches today's behaviour exactly.
+   */
+  private ctxFor;
+  /**
+   * Build the `enqueueOnCommit` slot of a {@link BehaviorContext} for
+   * the active tx, ready to spread into `resolveAuthContext`'s options
+   * (PR D of PLAN-OUTBOX).
+   *
+   * - When the queue plugin's factory is wired, invoke it with `tx` so
+   *   the resulting fire-and-forget resolver routes its INSERT through
+   *   the caller's transaction (atomic with the entity write).
+   * - When only the legacy static `enqueueOnCommit` option is set, pass
+   *   it through verbatim — used by tests and callers that wired their
+   *   own resolver directly.
+   * - When neither is configured (CLI scripts, no queue plugin), return
+   *   `{}` so the BehaviorContext's `enqueueOnCommit` field stays
+   *   undefined and behaviors guard accordingly.
+   */
+  private buildAuthOptions;
+  /**
+   * Re-bind `behaviorCtx.enqueueOnCommit` to the supplied executor.
+   *
+   * Used by `delete` / `deleteMany` when they open an internal tx
+   * because no caller tx was supplied: the auth context was resolved
+   * BEFORE the tx existed, so its `enqueueOnCommit` (if a factory is
+   * wired) was bound to `undefined` and would commit the queue row
+   * outside the internal tx. Rebinding here ensures the queue write
+   * rolls back with the cascade if anything in `runDelete` throws.
+   *
+   * Spreads conditionally to satisfy `exactOptionalPropertyTypes` —
+   * never assigns `enqueueOnCommit: undefined` (which would clear an
+   * existing static resolver if the factory wasn't configured).
+   */
+  private rebindEnqueueOnCommit;
   constructor(config: AdminClientConfig<AllFields>);
   /**
-   * Create a new entity
+   * Strip caller-provided values for internal fields from the input.
+   *
+   * Returns a NEW object — does not mutate the caller's input. Hooks run
+   * AFTER this strip, so they can still set internal fields legitimately;
+   * those values are then preserved through validation by `pickInternalFields`.
+   */
+  private stripCallerInternals;
+  /**
+   * Pick the internal-field values that hooks set on `data`.
+   * Used to re-attach them after schema validation strips unknown keys.
+   */
+  private pickInternalFields;
+  /**
+   * Create a new entity.
    *
    * Flow:
    * 1. Validate input with Zod
@@ -425,14 +636,37 @@ declare class AdminClient<AllFields extends Record<string, FieldConfig> = Record
    * 4. Insert into database
    * 5. Execute afterCreate hooks
    * 6. Shape DTO and return
+   *
+   * **Caller transaction (`options.tx`)** — PR D of PLAN-OUTBOX. When
+   * supplied, the row INSERT, blocks save, refs sync, and any hook-fired
+   * `enqueueOnCommit` participate in the caller's transaction:
+   *
+   * ```ts
+   * await db.transaction(async (tx) => {
+   *   const order = await orders.create({ ... }, { tx })
+   *   // afterCreate hooks fired with this tx — enqueueOnCommit's INSERT
+   *   // routes through it. Outer rollback removes both atomically.
+   * })
+   * ```
+   *
+   * When omitted, behaviour matches pre-PR-D exactly: each statement
+   * auto-commits, hooks run after commit, and the static
+   * `enqueueOnCommit` resolver (if any) writes outside the entity tx.
    */
-  create(data: InferCreateInput<AllFields>): Promise<InferEntityDTO<AllFields>>;
+  create(data: InferCreateInput<AllFields>, options?: {
+    tx?: PostgresJsDatabase;
+  }): Promise<InferEntityDTO<AllFields>>;
   /**
-   * Find entity by ID
+   * Find entity by ID.
+   *
+   * Pass `includeInternal: true` from trusted server code (workflow
+   * transitions, behavior implementations) when you need to read fields
+   * marked `internal: true` — by default they are stripped from the DTO.
    */
   findById(id: string, options?: {
     locale?: string;
     defaultLocale?: string;
+    includeInternal?: boolean;
   }): Promise<InferEntityDTO<AllFields> | null>;
   /**
    * Find multiple entities
@@ -455,17 +689,65 @@ declare class AdminClient<AllFields extends Record<string, FieldConfig> = Record
    */
   update(id: string, data: InferUpdateInput<AllFields>, options?: {
     locale?: string;
+    tx?: PostgresJsDatabase;
+  }): Promise<InferEntityDTO<AllFields>>;
+  /**
+   * Update entity by ID, allowing writes to fields marked `internal: true`.
+   *
+   * Use this from trusted server code that has already authorized the
+   * transition out-of-band — typical example: workflow transitions invoked
+   * from an admin route that has already checked the `publish` permission.
+   * The HTTP `PATCH` surface uses the public {@link update} method, which
+   * silently strips internal fields so untrusted callers cannot poison
+   * state-machine values like `_workflowStatus`.
+   *
+   * The validation schema for this method INCLUDES internal fields — values
+   * are still type-checked and constrained (e.g. select-field options).
+   *
+   * **Security**: never call this from a code path that forwards request body
+   * fields directly. The caller must construct the internal-field values
+   * server-side from authorized state transitions.
+   */
+  updateInternal(id: string, data: Record<string, unknown>, options?: {
+    locale?: string;
+    tx?: PostgresJsDatabase;
   }): Promise<InferEntityDTO<AllFields>>;
+  private updateImpl;
+  /**
+   * Internal `findById` variant that issues its SELECT through the
+   * caller-supplied executor. Used by `updateImpl` so the pre-update
+   * snapshot reflects any earlier writes the caller already made
+   * inside the same transaction.
+   *
+   * **Scope is NOT optional** — it must be the same `scopeId` that
+   * `resolveAuthContext` produced for the surrounding `update` call.
+   * The eventual UPDATE is scope-gated via its WHERE clause; if this
+   * pre-load skipped scope, hooks with side effects (audit logs,
+   * system-message creation, outbox enqueues) would observe and
+   * dispatch on cross-tenant rows even when the gated UPDATE matches
+   * nothing. See HIGH finding in pr-review for #247.
+   *
+   * Permission check is skipped because `resolveAuthContext` ran first
+   * in the surrounding `update` call.
+   */
+  private findByIdInternal;
   /**
    * Delete entity by ID.
    *
    * Wraps cascade + delete in a transaction so cascaded deletes are rolled
-   * back if the final entity delete fails (no partial data loss).
+   * back if the final entity delete fails (no partial data loss). When
+   * the caller threads in `{ tx }` (PR D of PLAN-OUTBOX), the same tx
+   * is reused — the inner `db.transaction(...)` call is replaced with a
+   * direct invocation of the body, and any hook-fired `enqueueOnCommit`
+   * INSERT routes through the caller's tx so an outer rollback removes
+   * everything atomically.
    *
    * Checks entity_refs for incoming references first — throws
    * ReferencedEntityError if this entity is still used somewhere.
    */
-  delete(id: string): Promise<void>;
+  delete(id: string, options?: {
+    tx?: PostgresJsDatabase;
+  }): Promise<void>;
   /**
    * Delete multiple entities matching a WHERE condition.
    *
@@ -481,7 +763,9 @@ declare class AdminClient<AllFields extends Record<string, FieldConfig> = Record
    *
    * @returns Number of rows deleted
    */
-  deleteMany(where: SQL): Promise<number>;
+  deleteMany(where: SQL, options?: {
+    tx?: PostgresJsDatabase;
+  }): Promise<number>;
   /** Maximum cascade depth to prevent infinite recursion from circular references. */
   private static readonly MAX_CASCADE_DEPTH;
   /**
@@ -545,6 +829,8 @@ declare class AdminClient<AllFields extends Record<string, FieldConfig> = Record
    */
   updateMany(where: SQL, data: Partial<InferUpdateInput<AllFields>>, options?: {
     expressions?: Record<string, SQL>;
+    allowInternal?: boolean;
+    tx?: PostgresJsDatabase;
   }): Promise<number>;
   /**
    * Run an aggregate query on this entity's table.
@@ -618,30 +904,66 @@ declare class AdminClient<AllFields extends Record<string, FieldConfig> = Record
   /**
    * Save translation for an entity.
    * Each translatable field is a real column on the translation table.
+   *
+   * **Caller transaction (`options.tx`)** — Phase 4b of PLAN-OUTBOX. When
+   * supplied, the upsert participates in the caller's transaction so a
+   * caller wrapping `entity.create + saveTranslation` in a `db.transaction`
+   * gets atomic visibility — outer rollback removes BOTH the entity row
+   * and the translation row, never leaves an orphan translation pointing
+   * at a now-deleted entity. Without it, the translation would auto-commit
+   * regardless of the outer rollback. No hooks fire on this method, so no
+   * factory plumbing is needed — just routing the SQL through `exec`.
    */
-  saveTranslation(entityId: string, locale: string, translations: Record<string, unknown>): Promise<void>;
+  saveTranslation(entityId: string, locale: string, translations: Record<string, unknown>, options?: {
+    tx?: PostgresJsDatabase;
+  }): Promise<void>;
   /**
-   * PHASE 3: Delete translation(s) for an entity
-   * If locale is provided, deletes specific locale; otherwise deletes all translations
+   * Delete translation(s) for an entity. If `locale` is provided, deletes
+   * the specific locale row; otherwise deletes every translation row for
+   * the entity.
+   *
+   * **Caller transaction (`options.tx`)** — Phase 4b of PLAN-OUTBOX. Same
+   * shape as `saveTranslation` — when supplied, the DELETE participates
+   * in the caller's tx.
    */
-  deleteTranslation(entityId: string, locale?: string): Promise<void>;
+  deleteTranslation(entityId: string, locale?: string, options?: {
+    tx?: PostgresJsDatabase;
+  }): Promise<void>;
   /**
    * Save block-level translations for an entity.
    * For each block in each blocks field, extracts translatable field values
    * and upserts them into {entity}_layout_translations.
    *
    * Block _id must match an existing layout row ID.
+   *
+   * **Caller transaction (`options.tx`)** — Phase 4b of PLAN-OUTBOX.
+   * Routes the layout-row lookup AND every layout-translation upsert
+   * through the supplied tx, so a caller doing
+   * `entity.update + saveBlockTranslations` in one tx gets atomic
+   * visibility on rollback.
    */
-  saveBlockTranslations(entityId: string, locale: string, data: Record<string, unknown>): Promise<void>;
+  saveBlockTranslations(entityId: string, locale: string, data: Record<string, unknown>, options?: {
+    tx?: PostgresJsDatabase;
+  }): Promise<void>;
   /**
    * Save per-locale blocks for an entity.
    * Used for entities with `localized: true` on their blocks field — each locale gets
    * its own independent block layout rows in the layout table.
+   *
+   * **Caller transaction (`options.tx`)** — Phase 4b of PLAN-OUTBOX. Threaded
+   * through to `saveBlocks`, which already accepts an executor.
    */
-  saveLocalizedBlocks(entityId: string, locale: string, data: Record<string, unknown>): Promise<void>;
+  saveLocalizedBlocks(entityId: string, locale: string, data: Record<string, unknown>, options?: {
+    tx?: PostgresJsDatabase;
+  }): Promise<void>;
   /**
    * Save blocks for an entity after create/update.
    * For each blocks field, writes rows to {entity}_layout table.
+   *
+   * `exec` is the active Drizzle executor — either a caller-supplied tx
+   * (PR D of PLAN-OUTBOX) or `this.db`. Routing through it keeps the
+   * blocks INSERTs/DELETEs in the same transaction as the parent
+   * entity write.
    */
   private saveBlocks;
   /**
@@ -651,13 +973,27 @@ declare class AdminClient<AllFields extends Record<string, FieldConfig> = Record
    * - 'update': deletes refs for changed ref-bearing fields, then inserts new ones
    *
    * Gracefully skips if entity_refs table is not registered (e.g. before migration).
+   *
+   * `exec` is the active Drizzle executor — caller-supplied tx (PR D of
+   * PLAN-OUTBOX) or `this.db`. Routes the entity_refs UPDATE/INSERT
+   * through the same transaction as the parent entity write.
    */
   private syncRefs;
   /**
    * Invalidate all count cache entries for this entity.
+   *
+   * **Tx-aware** (PR D of PLAN-OUTBOX). When `inCallerTx === true`, we
+   * skip the invalidation: the caller's tx hasn't committed yet, and
+   * eagerly invalidating would have other connections re-compute the
+   * count from the still-pre-tx state and cache that stale value.
+   * The caller is responsible for invalidating after their own commit
+   * (or accepting the cache TTL self-heal). For internally-managed
+   * txs (no-caller-tx path) and no-tx CRUD calls, the invalidation
+   * runs after the inner `db.transaction(...)` resolves — which only
+   * happens post-commit — so the cache reflects the committed state.
    */
   private invalidateCountCache;
 }
 //#endregion
-export { AdminClient, type AdminClientConfig, type CountCacheLike, type CountOptions, type FindManyOptions };
+export { AdminClient, type AdminClientConfig, type CountCacheLike, type CountOptions, type FindManyOptions, type InferCreateInput, type InferEntityDTO, type InferUpdateInput };
 //# sourceMappingURL=index.d.mts.map