@databricks/appkit 0.71.0 → 0.73.0

package/dist/plugins/database/defaults.js

@@ -13,6 +13,10 @@ const databaseWriteDefaults = {
 * connection past the deadline.
 */
 const STATEMENT_TIMEOUT_MS = 3e4;
+/** Server-side limit for an idle open transaction, independent of JS timers (ms). */
+const IDLE_IN_TRANSACTION_TIMEOUT_MS = 3e4;
+/** Deadline for the transaction callback, not cancellation of arbitrary hook work (ms). */
+const TRANSACTION_TIMEOUT_MS = 3e4;
 /** Max encoded size of a generated read query string. */
 const MAX_QUERY_BYTES = 8 * 1024;
 /** Max nesting depth of `and`/`or` groups in one generated filter. */
@@ -35,5 +39,5 @@ const MAX_SERIALIZED_NODES = 1e4;
 const MAX_RESPONSE_BYTES = 5 * 1024 * 1024;
 
 //#endregion
-export { MAX_GROUP_ITEMS, MAX_MATERIALIZED_NODES, MAX_OFFSET, MAX_ORDER_FIELDS, MAX_QUERY_BYTES, MAX_RESPONSE_BYTES, MAX_SERIALIZED_DEPTH, MAX_SERIALIZED_NODES, MAX_WHERE_CONDITIONS, MAX_WHERE_DEPTH, STATEMENT_TIMEOUT_MS, databaseReadDefaults, databaseWriteDefaults };
+export { IDLE_IN_TRANSACTION_TIMEOUT_MS, MAX_GROUP_ITEMS, MAX_MATERIALIZED_NODES, MAX_OFFSET, MAX_ORDER_FIELDS, MAX_QUERY_BYTES, MAX_RESPONSE_BYTES, MAX_SERIALIZED_DEPTH, MAX_SERIALIZED_NODES, MAX_WHERE_CONDITIONS, MAX_WHERE_DEPTH, STATEMENT_TIMEOUT_MS, TRANSACTION_TIMEOUT_MS, databaseReadDefaults, databaseWriteDefaults };
 //# sourceMappingURL=defaults.js.map

package/dist/plugins/database/defaults.js.map

@@ -1 +1 @@
-{"version":3,"file":"defaults.js","names":[],"sources":["../../../src/plugins/database/defaults.ts"],"sourcesContent":["import type { PluginExecuteConfig } from \"shared\";\n\n/** Default interceptor policy for bounded reads. */\nexport const databaseReadDefaults: PluginExecuteConfig = {\n  retry: { enabled: false },\n};\n\n/** Default interceptor policy for mutations. */\nexport const databaseWriteDefaults: PluginExecuteConfig = {\n  cache: { enabled: false },\n  retry: { enabled: false },\n};\n\n// Connection posture: how long any one statement may hold a pooled connection.\n/**\n * Server-side `statement_timeout` applied to every pooled connection (ms).\n * PostgreSQL cancels the statement itself, so an expensive caller-supplied\n * filter (for example a leading-wildcard `ilike`) cannot hold its pooled\n * connection past the deadline.\n */\nexport const STATEMENT_TIMEOUT_MS = 30_000;\n\n// Generated-read limits. The wire caps a typed caller shares with HTTP live in\n// `database/contract`; these bound only what an untrusted request may ask for.\n\n// Request decoding: rejected before any database work is scheduled.\n/** Max encoded size of a generated read query string. */\nexport const MAX_QUERY_BYTES = 8 * 1024;\n/** Max nesting depth of `and`/`or` groups in one generated filter. */\nexport const MAX_WHERE_DEPTH = 5;\n/** Max column conditions across one generated filter. */\nexport const MAX_WHERE_CONDITIONS = 50;\n/** Max members in one `and`/`or` group. */\nexport const MAX_GROUP_ITEMS = 20;\n/** Max columns one generated `order` may name. */\nexport const MAX_ORDER_FIELDS = 10;\n/** Max accepted generated `offset`. */\nexport const MAX_OFFSET = 10_000;\n/** Max rows one generated read may materialize across its include tree. */\nexport const MAX_MATERIALIZED_NODES = 10_000;\n\n// Response shaping: bounds trusted output on its way to the wire.\n/** Max nesting depth of read-serializer output. */\nexport const MAX_SERIALIZED_DEPTH = 32;\n/** Max node count of read-serializer output. */\nexport const MAX_SERIALIZED_NODES = 10_000;\n/** Max UTF-8 byte length of one generated read response body. */\nexport const MAX_RESPONSE_BYTES = 5 * 1024 * 1024;\n"],"mappings":";;AAGA,MAAa,uBAA4C,EACvD,OAAO,EAAE,SAAS,OAAO,EAC1B;;AAGD,MAAa,wBAA6C;CACxD,OAAO,EAAE,SAAS,OAAO;CACzB,OAAO,EAAE,SAAS,OAAO;CAC1B;;;;;;;AASD,MAAa,uBAAuB;;AAOpC,MAAa,kBAAkB,IAAI;;AAEnC,MAAa,kBAAkB;;AAE/B,MAAa,uBAAuB;;AAEpC,MAAa,kBAAkB;;AAE/B,MAAa,mBAAmB;;AAEhC,MAAa,aAAa;;AAE1B,MAAa,yBAAyB;;AAItC,MAAa,uBAAuB;;AAEpC,MAAa,uBAAuB;;AAEpC,MAAa,qBAAqB,IAAI,OAAO"}
+{"version":3,"file":"defaults.js","names":[],"sources":["../../../src/plugins/database/defaults.ts"],"sourcesContent":["import type { PluginExecuteConfig } from \"shared\";\n\n/** Default interceptor policy for bounded reads. */\nexport const databaseReadDefaults: PluginExecuteConfig = {\n  retry: { enabled: false },\n};\n\n/** Default interceptor policy for mutations. */\nexport const databaseWriteDefaults: PluginExecuteConfig = {\n  cache: { enabled: false },\n  retry: { enabled: false },\n};\n\n// Connection posture: how long any one statement may hold a pooled connection.\n/**\n * Server-side `statement_timeout` applied to every pooled connection (ms).\n * PostgreSQL cancels the statement itself, so an expensive caller-supplied\n * filter (for example a leading-wildcard `ilike`) cannot hold its pooled\n * connection past the deadline.\n */\nexport const STATEMENT_TIMEOUT_MS = 30_000;\n\n/** Server-side limit for an idle open transaction, independent of JS timers (ms). */\nexport const IDLE_IN_TRANSACTION_TIMEOUT_MS = 30_000;\n\n/** Deadline for the transaction callback, not cancellation of arbitrary hook work (ms). */\nexport const TRANSACTION_TIMEOUT_MS = 30_000;\n\n// Generated-read limits. The wire caps a typed caller shares with HTTP live in\n// `database/contract`; these bound only what an untrusted request may ask for.\n\n// Request decoding: rejected before any database work is scheduled.\n/** Max encoded size of a generated read query string. */\nexport const MAX_QUERY_BYTES = 8 * 1024;\n/** Max nesting depth of `and`/`or` groups in one generated filter. */\nexport const MAX_WHERE_DEPTH = 5;\n/** Max column conditions across one generated filter. */\nexport const MAX_WHERE_CONDITIONS = 50;\n/** Max members in one `and`/`or` group. */\nexport const MAX_GROUP_ITEMS = 20;\n/** Max columns one generated `order` may name. */\nexport const MAX_ORDER_FIELDS = 10;\n/** Max accepted generated `offset`. */\nexport const MAX_OFFSET = 10_000;\n/** Max rows one generated read may materialize across its include tree. */\nexport const MAX_MATERIALIZED_NODES = 10_000;\n\n// Response shaping: bounds trusted output on its way to the wire.\n/** Max nesting depth of read-serializer output. */\nexport const MAX_SERIALIZED_DEPTH = 32;\n/** Max node count of read-serializer output. */\nexport const MAX_SERIALIZED_NODES = 10_000;\n/** Max UTF-8 byte length of one generated read response body. */\nexport const MAX_RESPONSE_BYTES = 5 * 1024 * 1024;\n"],"mappings":";;AAGA,MAAa,uBAA4C,EACvD,OAAO,EAAE,SAAS,OAAO,EAC1B;;AAGD,MAAa,wBAA6C;CACxD,OAAO,EAAE,SAAS,OAAO;CACzB,OAAO,EAAE,SAAS,OAAO;CAC1B;;;;;;;AASD,MAAa,uBAAuB;;AAGpC,MAAa,iCAAiC;;AAG9C,MAAa,yBAAyB;;AAOtC,MAAa,kBAAkB,IAAI;;AAEnC,MAAa,kBAAkB;;AAE/B,MAAa,uBAAuB;;AAEpC,MAAa,kBAAkB;;AAE/B,MAAa,mBAAmB;;AAEhC,MAAa,aAAa;;AAE1B,MAAa,yBAAyB;;AAItC,MAAa,uBAAuB;;AAEpC,MAAa,uBAAuB;;AAEpC,MAAa,qBAAqB,IAAI,OAAO"}

package/dist/plugins/database/entity-client.js

@@ -1,8 +1,16 @@
-import { DatabasePluginError, classifyDatabaseError, databaseErrorFromStatus } from "../../database/errors.js";
+import { DatabaseValidationError } from "../../errors/database-validation.js";
+import "../../errors/index.js";
+import { DatabasePluginError, classifyDatabaseError, databaseErrorFromStatus, invalidDatabaseRequest } from "../../database/errors.js";
 import { databaseReadDefaults, databaseWriteDefaults } from "./defaults.js";
 import { andWhere, validateLimit, validateOffset } from "../../database/runtime/data-path.js";
 
 //#region src/plugins/database/entity-client.ts
+/** Internal rollback signal for a hooked keyed mutation that matched no row. */
+var MutationNoMatchError = class extends DatabasePluginError {
+	constructor() {
+		super("NOT_FOUND", "write");
+	}
+};
 /** Clone plain acyclic input so caller mutation cannot change a built query. */
 function snapshotPlain(value, seen = /* @__PURE__ */ new Set()) {
 	if (value === null || typeof value === "string" || typeof value === "boolean" || typeof value === "bigint" || typeof value === "number" && Number.isFinite(value)) return value;
@@ -22,6 +30,10 @@ function validateReadInput(validate) {
 		throw classifyDatabaseError(error, "read");
 	}
 }
+/** A hook replaced the payload only if it returned an object to persist. */
+function isReplacement(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
 /**
 * Plugin-facing client that composes immutable query state. The DataPath remains
 * the schema-aware validation and execution boundary.
@@ -99,27 +111,148 @@ var EntityClient = class EntityClient {
 	count() {
 		return this.run("read", (dataPath) => dataPath.count(this.ctx.table, this.state.where));
 	}
-	create(values) {
-		return this.write("create", values, (dataPath, payload) => dataPath.insert(this.ctx.table, payload));
+	async create(values) {
+		this.assertUnfiltered("create");
+		const hooks = this.ctx.hooks;
+		const insert = (payload, byHook = false) => this.write("create", payload, (dataPath, parsed) => dataPath.insert(this.ctx.table, parsed), byHook);
+		if (this.isDirect("create")) return this.directMutation("create", () => insert(values));
+		return this.mutate("create", (entity) => entity.create(values), async (context) => {
+			const payload = await this.runBefore(() => hooks?.beforeCreate?.(values, context), values);
+			const row = await insert(payload, payload !== values);
+			await this.runHook(() => hooks?.afterCreate?.(row, context));
+			return row;
+		});
 	}
 	update(id, values) {
-		return this.write("update", values, (dataPath, payload) => dataPath.update(this.ctx.table, id, payload));
+		return this.updateWithNoMatch(id, values, new MutationNoMatchError());
+	}
+	async updateWithNoMatch(id, values, noMatch) {
+		const hooks = this.ctx.hooks;
+		const apply = (payload, byHook = false) => this.write("update", payload, (dataPath, parsed) => dataPath.update(this.ctx.table, id, parsed, this.state.where), byHook);
+		if (this.isDirect("update")) return this.directMutation("update", () => apply(values));
+		try {
+			return await this.mutate("update", (entity) => entity.updateWithNoMatch(id, values, noMatch), async (context) => {
+				const payload = await this.runBefore(() => hooks?.beforeUpdate?.(id, values, context), values);
+				const row = await apply(payload, payload !== values);
+				if (row === null) throw noMatch;
+				await this.runHook(() => hooks?.afterUpdate?.(row, context));
+				return row;
+			});
+		} catch (error) {
+			if (error === noMatch && !this.ctx.transactionBound && !this.ctx.scope.activeTransaction()) return null;
+			throw error;
+		}
 	}
-	upsert(values, options) {
+	async upsert(values, options) {
+		this.assertUnfiltered("upsert");
+		const hooks = this.ctx.hooks;
 		const onConflict = options.onConflict;
-		return this.write("create", values, (dataPath, payload) => dataPath.upsert(this.ctx.table, payload, onConflict));
+		const apply = (payload, byHook = false) => this.write("create", payload, (dataPath, parsed) => dataPath.upsert(this.ctx.table, parsed, onConflict), byHook);
+		if (this.isDirect("upsert")) return this.directMutation("upsert", () => apply(values));
+		return this.mutate("upsert", (entity) => entity.upsert(values, { onConflict }), async (context) => {
+			const payload = await this.runBefore(() => hooks?.beforeUpsert?.(values, context), values);
+			const row = await apply(payload, payload !== values);
+			await this.runHook(() => hooks?.afterUpsert?.(row, context));
+			return row;
+		});
 	}
 	delete(id) {
-		return this.run("write", (dataPath) => dataPath.delete(this.ctx.table, id), databaseWriteDefaults);
+		return this.deleteWithNoMatch(id, new MutationNoMatchError());
+	}
+	async deleteWithNoMatch(id, noMatch) {
+		const hooks = this.ctx.hooks;
+		const remove = () => this.run("write", (dataPath) => dataPath.delete(this.ctx.table, id, this.state.where), databaseWriteDefaults);
+		if (this.isDirect("delete")) return this.directMutation("delete", remove);
+		try {
+			return await this.mutate("delete", (entity) => entity.deleteWithNoMatch(id, noMatch), async (context) => {
+				await this.runHook(() => hooks?.beforeDelete?.(id, context));
+				if (!await remove()) throw noMatch;
+				await this.runHook(() => hooks?.afterDelete?.(id, context));
+				return true;
+			});
+		} catch (error) {
+			if (error === noMatch && !this.ctx.transactionBound && !this.ctx.scope.activeTransaction()) return false;
+			throw error;
+		}
+	}
+	/** Count every write that runs on an already bound transaction. */
+	directMutation(operation, run) {
+		if (!this.ctx.transactionBound) return run();
+		return this.ctx.scope.runMutation(this.ctx.table.$name, operation, run);
+	}
+	/** An insert matches no existing row, so a predicate could only be dropped. */
+	assertUnfiltered(operation) {
+		if (this.state.where !== void 0) throw invalidDatabaseRequest(`${operation}() cannot follow where(); it does not select rows to change`);
+	}
+	/**
+	* Go straight to the DataPath only when there is nothing to sequence and no
+	* open transaction to join. A root client that skipped the second check would
+	* commit on the pool while a transaction it cannot see is still open.
+	*/
+	isDirect(operation) {
+		if (this.hasHooks(operation)) return false;
+		return this.ctx.transactionBound || !this.ctx.scope.activeTransaction();
+	}
+	hasHooks(operation) {
+		const hooks = this.ctx.hooks;
+		if (!hooks) return false;
+		switch (operation) {
+			case "create": return Boolean(hooks.beforeCreate ?? hooks.afterCreate);
+			case "update": return Boolean(hooks.beforeUpdate ?? hooks.afterUpdate);
+			case "upsert": return Boolean(hooks.beforeUpsert ?? hooks.afterUpsert);
+			case "delete": return Boolean(hooks.beforeDelete ?? hooks.afterDelete);
+		}
+	}
+	/**
+	* Run one mutation atomically. A top-level call restarts itself on the
+	* transaction-bound client, so hooks, validation, the mutation, and its after
+	* hook commit or roll back together. An unhooked root mutation reaches this
+	* only to join an open transaction; its bound client counts the direct write
+	* without constructing a hook context.
+	*/
+	async mutate(operation, restart, body) {
+		if (this.ctx.transactionBound) return this.ctx.scope.runMutation(this.ctx.table.$name, operation, () => body(this.hookContext()));
+		try {
+			return await this.ctx.runInTransaction((entity) => restart(entity.clone(this.state)));
+		} catch (error) {
+			if (error instanceof DatabaseValidationError || error instanceof MutationNoMatchError) throw error;
+			throw classifyDatabaseError(error, "write");
+		}
+	}
+	/** Resolve the surface at hook time so it cannot outlive its transaction. */
+	hookContext() {
+		const database = this.ctx.scope.activeTransaction();
+		if (!database) throw new DatabasePluginError("INTERNAL", "write");
+		return {
+			entity: this.ctx.table.$name,
+			app: { database }
+		};
+	}
+	/** Substitute the payload a before hook returned, if it returned one. */
+	async runBefore(invoke, values) {
+		const replacement = await this.runHook(invoke);
+		if (replacement === void 0 || replacement === null) return values;
+		if (!isReplacement(replacement)) throw new DatabasePluginError("INTERNAL", "write");
+		return replacement;
+	}
+	/** Keep a deliberate validation signal; collapse every other hook failure. */
+	async runHook(invoke) {
+		try {
+			return await invoke();
+		} catch (error) {
+			if (error instanceof DatabaseValidationError) throw error;
+			throw classifyDatabaseError(error, "write");
+		}
 	}
 	/** Validate caller values against the finalized trusted-write schema. */
-	async write(kind, values, operation) {
-		if (kind === "update" && Object.keys(values).length === 0) throw new DatabasePluginError("INVALID_REQUEST", "write");
+	async write(kind, values, operation, byHook = false) {
+		const rejection = byHook ? "INTERNAL" : "INVALID_REQUEST";
+		if (kind === "update" && Object.keys(values).length === 0) throw new DatabasePluginError(rejection, "write");
 		let parsed;
 		try {
 			parsed = (kind === "create" ? this.ctx.table.$insertSchema : this.ctx.table.$updateSchema).parse(values);
 		} catch {
-			throw new DatabasePluginError("INVALID_REQUEST", "write");
+			throw new DatabasePluginError(rejection, "write");
 		}
 		return this.run("write", (dataPath) => operation(dataPath, parsed), databaseWriteDefaults);
 	}

package/dist/plugins/database/entity-client.js.map

@@ -1 +1 @@
-{"version":3,"file":"entity-client.js","names":[],"sources":["../../../src/plugins/database/entity-client.ts"],"sourcesContent":["import type { PluginExecuteConfig } from \"shared\";\n\nimport {\n  classifyDatabaseError,\n  DatabasePluginError,\n  databaseErrorFromStatus,\n} from \"../../database/errors\";\nimport type {\n  DataPath,\n  IdValue,\n  IncludeSpec,\n  OrderSpec,\n  QuerySpec,\n  Row,\n  WhereClause,\n} from \"../../database/runtime\";\nimport {\n  andWhere,\n  validateLimit,\n  validateOffset,\n} from \"../../database/runtime/data-path\";\nimport type { AppKitTable } from \"../../database/schema-builder\";\nimport type { ExecutionResult } from \"../../plugin/execution-result\";\nimport { databaseReadDefaults, databaseWriteDefaults } from \"./defaults\";\n\n/** Apply AppKit execution policy to an entity operation. */\nexport type EntityExecute = <T>(\n  fn: (signal?: AbortSignal) => Promise<T>,\n  options: { default: PluginExecuteConfig; user?: PluginExecuteConfig },\n) => Promise<ExecutionResult<T>>;\n\n/** Runtime dependencies shared by immutable clients for one table. */\nexport interface EntityClientContext {\n  readonly table: AppKitTable;\n  readonly getDataPath: () => DataPath;\n  readonly execute: EntityExecute;\n  readonly assertActive: () => void;\n}\n\n/** Clone plain acyclic input so caller mutation cannot change a built query. */\nfunction snapshotPlain<T>(value: T, seen = new Set<object>()): T {\n  if (\n    value === null ||\n    typeof value === \"string\" ||\n    typeof value === \"boolean\" ||\n    typeof value === \"bigint\" ||\n    (typeof value === \"number\" && Number.isFinite(value))\n  ) {\n    return value;\n  }\n  if (typeof value !== \"object\") {\n    throw new DatabasePluginError(\"INVALID_REQUEST\", \"read\");\n  }\n  if (seen.has(value)) throw new DatabasePluginError(\"INVALID_REQUEST\", \"read\");\n  if (\n    !Array.isArray(value) &&\n    Object.getPrototypeOf(value) !== Object.prototype\n  )\n    throw new DatabasePluginError(\"INVALID_REQUEST\", \"read\");\n  seen.add(value);\n  const copy = (\n    Array.isArray(value)\n      ? value.map((item) => snapshotPlain(item, seen))\n      : Object.fromEntries(\n          Object.entries(value).map(([key, item]) => [\n            key,\n            snapshotPlain(item, seen),\n          ]),\n        )\n  ) as T;\n  seen.delete(value);\n  return copy;\n}\n\n/** Report eager fluent-input failures through the public read phase. */\nfunction validateReadInput<T>(validate: () => T): T {\n  try {\n    return validate();\n  } catch (error) {\n    throw classifyDatabaseError(error, \"read\");\n  }\n}\n\n/**\n * Plugin-facing client that composes immutable query state. The DataPath remains\n * the schema-aware validation and execution boundary.\n */\nexport class EntityClient {\n  constructor(\n    private readonly ctx: EntityClientContext,\n    private readonly state: QuerySpec = {},\n  ) {}\n\n  private clone(state: QuerySpec): EntityClient {\n    return new EntityClient(this.ctx, state);\n  }\n\n  /** Snapshot and compose predicates; the adapter validates columns/operators. */\n  where(filter: WhereClause): EntityClient {\n    const snapshot = snapshotPlain(filter);\n    return this.clone({\n      ...this.state,\n      where: andWhere(this.state.where, snapshot),\n    });\n  }\n\n  /** Merge ordering, replacing the direction for repeated columns. */\n  order(order: OrderSpec): EntityClient {\n    const snapshot = snapshotPlain(order);\n    return this.clone({\n      ...this.state,\n      order: { ...this.state.order, ...snapshot },\n    });\n  }\n\n  select(columns: readonly string[]): EntityClient {\n    return this.clone({ ...this.state, select: snapshotPlain(columns) });\n  }\n\n  /** Merge relation includes, replacing repeated relation options. */\n  include(include: IncludeSpec): EntityClient {\n    const snapshot = snapshotPlain(include);\n    return this.clone({\n      ...this.state,\n      include: { ...this.state.include, ...snapshot },\n    });\n  }\n\n  limit(limit: number): EntityClient {\n    return validateReadInput(() =>\n      this.clone({ ...this.state, limit: validateLimit(limit) }),\n    );\n  }\n\n  offset(offset: number): EntityClient {\n    return validateReadInput(() =>\n      this.clone({ ...this.state, offset: validateOffset(offset) }),\n    );\n  }\n\n  /** Execute a collection read; DataPath applies the default upper bound. */\n  async toArray(): Promise<Row[]> {\n    return this.run(\"read\", (dataPath) =>\n      dataPath.select(this.ctx.table, this.state),\n    );\n  }\n\n  async first(): Promise<Row | null> {\n    return (await this.limit(1).toArray())[0] ?? null;\n  }\n\n  find(id: IdValue): Promise<Row | null> {\n    return this.run(\"read\", (dataPath) =>\n      dataPath.findOne(this.ctx.table, id, {\n        where: this.state.where,\n        select: this.state.select,\n        include: this.state.include,\n      }),\n    );\n  }\n\n  count(): Promise<number> {\n    return this.run(\"read\", (dataPath) =>\n      dataPath.count(this.ctx.table, this.state.where),\n    );\n  }\n\n  create(values: Row): Promise<Row> {\n    return this.write(\"create\", values, (dataPath, payload) =>\n      dataPath.insert(this.ctx.table, payload),\n    );\n  }\n\n  update(id: IdValue, values: Row): Promise<Row | null> {\n    return this.write(\"update\", values, (dataPath, payload) =>\n      dataPath.update(this.ctx.table, id, payload),\n    );\n  }\n\n  upsert(values: Row, options: { onConflict: string }): Promise<Row> {\n    const onConflict = options.onConflict;\n    return this.write(\"create\", values, (dataPath, payload) =>\n      dataPath.upsert(this.ctx.table, payload, onConflict),\n    );\n  }\n\n  delete(id: IdValue): Promise<boolean> {\n    return this.run(\n      \"write\",\n      (dataPath) => dataPath.delete(this.ctx.table, id),\n      databaseWriteDefaults,\n    );\n  }\n\n  /** Validate caller values against the finalized trusted-write schema. */\n  private async write<T>(\n    kind: \"create\" | \"update\",\n    values: Row,\n    operation: (dataPath: DataPath, values: Row) => Promise<T>,\n  ): Promise<T> {\n    if (kind === \"update\" && Object.keys(values).length === 0) {\n      throw new DatabasePluginError(\"INVALID_REQUEST\", \"write\");\n    }\n    let parsed: Row;\n    try {\n      const validator = (\n        kind === \"create\"\n          ? this.ctx.table.$insertSchema\n          : this.ctx.table.$updateSchema\n      ) as { parse(value: unknown): Row };\n      parsed = validator.parse(values);\n    } catch {\n      throw new DatabasePluginError(\"INVALID_REQUEST\", \"write\");\n    }\n    return this.run(\n      \"write\",\n      (dataPath) => operation(dataPath, parsed),\n      databaseWriteDefaults,\n    );\n  }\n\n  /** Execute through AppKit interceptors and expose only safe failures. */\n  private async run<T>(\n    phase: \"read\" | \"write\",\n    operation: (dataPath: DataPath) => Promise<T>,\n    defaults: PluginExecuteConfig = databaseReadDefaults,\n  ): Promise<T> {\n    try {\n      this.ctx.assertActive();\n    } catch (error) {\n      throw classifyDatabaseError(error, phase);\n    }\n    const result = await this.ctx.execute(\n      async () => {\n        try {\n          this.ctx.assertActive();\n          return await operation(this.ctx.getDataPath());\n        } catch (error) {\n          throw classifyDatabaseError(error, phase);\n        }\n      },\n      { default: defaults },\n    );\n    if (result.ok) return result.data;\n    throw databaseErrorFromStatus(result.status, phase);\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"entity-client.js","names":[],"sources":["../../../src/plugins/database/entity-client.ts"],"sourcesContent":["import type { PluginExecuteConfig } from \"shared\";\n\nimport {\n  classifyDatabaseError,\n  DatabasePluginError,\n  databaseErrorFromStatus,\n  invalidDatabaseRequest,\n} from \"../../database/errors\";\nimport type {\n  DataPath,\n  IdValue,\n  IncludeSpec,\n  OrderSpec,\n  QuerySpec,\n  Row,\n  WhereClause,\n} from \"../../database/runtime\";\nimport {\n  andWhere,\n  validateLimit,\n  validateOffset,\n} from \"../../database/runtime/data-path\";\nimport type { AppKitTable } from \"../../database/schema-builder\";\nimport { DatabaseValidationError } from \"../../errors\";\nimport type { ExecutionResult } from \"../../plugin/execution-result\";\nimport { databaseReadDefaults, databaseWriteDefaults } from \"./defaults\";\nimport type { HookContext, MutationOperation } from \"./hooks\";\nimport type { MutationScope } from \"./scope\";\nimport type { EntityHooks } from \"./types\";\n\n/** Apply AppKit execution policy to an entity operation. */\nexport type EntityExecute = <T>(\n  fn: (signal?: AbortSignal) => Promise<T>,\n  options: { default: PluginExecuteConfig; user?: PluginExecuteConfig },\n) => Promise<ExecutionResult<T>>;\n\n/** Runtime dependencies shared by immutable clients for one table. */\nexport interface EntityClientContext {\n  readonly table: AppKitTable;\n  readonly getDataPath: () => DataPath;\n  readonly execute: EntityExecute;\n  readonly assertActive: () => void;\n  readonly scope: MutationScope;\n  readonly hooks?: EntityHooks;\n  /** True once this client is bound to an already open transaction. */\n  readonly transactionBound: boolean;\n  /** Continue on the same table's client inside a new or reused transaction. */\n  readonly runInTransaction: <T>(\n    run: (entity: EntityClient) => Promise<T>,\n  ) => Promise<T>;\n}\n\n/** Internal rollback signal for a hooked keyed mutation that matched no row. */\nclass MutationNoMatchError extends DatabasePluginError {\n  constructor() {\n    super(\"NOT_FOUND\", \"write\");\n  }\n}\n\n/** Clone plain acyclic input so caller mutation cannot change a built query. */\nfunction snapshotPlain<T>(value: T, seen = new Set<object>()): T {\n  if (\n    value === null ||\n    typeof value === \"string\" ||\n    typeof value === \"boolean\" ||\n    typeof value === \"bigint\" ||\n    (typeof value === \"number\" && Number.isFinite(value))\n  ) {\n    return value;\n  }\n  if (typeof value !== \"object\") {\n    throw new DatabasePluginError(\"INVALID_REQUEST\", \"read\");\n  }\n  if (seen.has(value)) throw new DatabasePluginError(\"INVALID_REQUEST\", \"read\");\n  if (\n    !Array.isArray(value) &&\n    Object.getPrototypeOf(value) !== Object.prototype\n  )\n    throw new DatabasePluginError(\"INVALID_REQUEST\", \"read\");\n  seen.add(value);\n  const copy = (\n    Array.isArray(value)\n      ? value.map((item) => snapshotPlain(item, seen))\n      : Object.fromEntries(\n          Object.entries(value).map(([key, item]) => [\n            key,\n            snapshotPlain(item, seen),\n          ]),\n        )\n  ) as T;\n  seen.delete(value);\n  return copy;\n}\n\n/** Report eager fluent-input failures through the public read phase. */\nfunction validateReadInput<T>(validate: () => T): T {\n  try {\n    return validate();\n  } catch (error) {\n    throw classifyDatabaseError(error, \"read\");\n  }\n}\n\n/** A hook replaced the payload only if it returned an object to persist. */\nfunction isReplacement(value: unknown): value is Row {\n  return typeof value === \"object\" && value !== null && !Array.isArray(value);\n}\n\n/**\n * Plugin-facing client that composes immutable query state. The DataPath remains\n * the schema-aware validation and execution boundary.\n */\nexport class EntityClient {\n  constructor(\n    private readonly ctx: EntityClientContext,\n    private readonly state: QuerySpec = {},\n  ) {}\n\n  private clone(state: QuerySpec): EntityClient {\n    return new EntityClient(this.ctx, state);\n  }\n\n  /** Snapshot and compose predicates; the adapter validates columns/operators. */\n  where(filter: WhereClause): EntityClient {\n    const snapshot = snapshotPlain(filter);\n    return this.clone({\n      ...this.state,\n      where: andWhere(this.state.where, snapshot),\n    });\n  }\n\n  /** Merge ordering, replacing the direction for repeated columns. */\n  order(order: OrderSpec): EntityClient {\n    const snapshot = snapshotPlain(order);\n    return this.clone({\n      ...this.state,\n      order: { ...this.state.order, ...snapshot },\n    });\n  }\n\n  select(columns: readonly string[]): EntityClient {\n    return this.clone({ ...this.state, select: snapshotPlain(columns) });\n  }\n\n  /** Merge relation includes, replacing repeated relation options. */\n  include(include: IncludeSpec): EntityClient {\n    const snapshot = snapshotPlain(include);\n    return this.clone({\n      ...this.state,\n      include: { ...this.state.include, ...snapshot },\n    });\n  }\n\n  limit(limit: number): EntityClient {\n    return validateReadInput(() =>\n      this.clone({ ...this.state, limit: validateLimit(limit) }),\n    );\n  }\n\n  offset(offset: number): EntityClient {\n    return validateReadInput(() =>\n      this.clone({ ...this.state, offset: validateOffset(offset) }),\n    );\n  }\n\n  /** Execute a collection read; DataPath applies the default upper bound. */\n  async toArray(): Promise<Row[]> {\n    return this.run(\"read\", (dataPath) =>\n      dataPath.select(this.ctx.table, this.state),\n    );\n  }\n\n  async first(): Promise<Row | null> {\n    return (await this.limit(1).toArray())[0] ?? null;\n  }\n\n  find(id: IdValue): Promise<Row | null> {\n    return this.run(\"read\", (dataPath) =>\n      dataPath.findOne(this.ctx.table, id, {\n        where: this.state.where,\n        select: this.state.select,\n        include: this.state.include,\n      }),\n    );\n  }\n\n  count(): Promise<number> {\n    return this.run(\"read\", (dataPath) =>\n      dataPath.count(this.ctx.table, this.state.where),\n    );\n  }\n\n  async create(values: Row): Promise<Row> {\n    this.assertUnfiltered(\"create\");\n    const hooks = this.ctx.hooks;\n    const insert = (payload: Row, byHook = false) =>\n      this.write(\n        \"create\",\n        payload,\n        (dataPath, parsed) => dataPath.insert(this.ctx.table, parsed),\n        byHook,\n      );\n    if (this.isDirect(\"create\")) {\n      return this.directMutation(\"create\", () => insert(values));\n    }\n    return this.mutate(\n      \"create\",\n      (entity) => entity.create(values),\n      async (context) => {\n        const payload = await this.runBefore(\n          () => hooks?.beforeCreate?.(values, context),\n          values,\n        );\n        const row = await insert(payload, payload !== values);\n        await this.runHook(() => hooks?.afterCreate?.(row, context));\n        return row;\n      },\n    );\n  }\n\n  update(id: IdValue, values: Row): Promise<Row | null> {\n    return this.updateWithNoMatch(id, values, new MutationNoMatchError());\n  }\n\n  private async updateWithNoMatch(\n    id: IdValue,\n    values: Row,\n    noMatch: MutationNoMatchError,\n  ): Promise<Row | null> {\n    const hooks = this.ctx.hooks;\n    const apply = (payload: Row, byHook = false) =>\n      this.write(\n        \"update\",\n        payload,\n        (dataPath, parsed) =>\n          dataPath.update(this.ctx.table, id, parsed, this.state.where),\n        byHook,\n      );\n    if (this.isDirect(\"update\")) {\n      return this.directMutation(\"update\", () => apply(values));\n    }\n    try {\n      return await this.mutate(\n        \"update\",\n        (entity) => entity.updateWithNoMatch(id, values, noMatch),\n        async (context) => {\n          const payload = await this.runBefore(\n            () => hooks?.beforeUpdate?.(id, values, context),\n            values,\n          );\n          const row = await apply(payload, payload !== values);\n          if (row === null) throw noMatch;\n          await this.runHook(() => hooks?.afterUpdate?.(row, context));\n          return row;\n        },\n      );\n    } catch (error) {\n      if (\n        error === noMatch &&\n        !this.ctx.transactionBound &&\n        !this.ctx.scope.activeTransaction()\n      ) {\n        return null;\n      }\n      throw error;\n    }\n  }\n\n  async upsert(values: Row, options: { onConflict: string }): Promise<Row> {\n    this.assertUnfiltered(\"upsert\");\n    const hooks = this.ctx.hooks;\n    const onConflict = options.onConflict;\n    const apply = (payload: Row, byHook = false) =>\n      this.write(\n        \"create\",\n        payload,\n        (dataPath, parsed) =>\n          dataPath.upsert(this.ctx.table, parsed, onConflict),\n        byHook,\n      );\n    if (this.isDirect(\"upsert\")) {\n      return this.directMutation(\"upsert\", () => apply(values));\n    }\n    return this.mutate(\n      \"upsert\",\n      (entity) => entity.upsert(values, { onConflict }),\n      async (context) => {\n        const payload = await this.runBefore(\n          () => hooks?.beforeUpsert?.(values, context),\n          values,\n        );\n        // Which branch the database took stays invisible to the hook.\n        const row = await apply(payload, payload !== values);\n        await this.runHook(() => hooks?.afterUpsert?.(row, context));\n        return row;\n      },\n    );\n  }\n\n  delete(id: IdValue): Promise<boolean> {\n    return this.deleteWithNoMatch(id, new MutationNoMatchError());\n  }\n\n  private async deleteWithNoMatch(\n    id: IdValue,\n    noMatch: MutationNoMatchError,\n  ): Promise<boolean> {\n    const hooks = this.ctx.hooks;\n    const remove = () =>\n      this.run(\n        \"write\",\n        (dataPath) => dataPath.delete(this.ctx.table, id, this.state.where),\n        databaseWriteDefaults,\n      );\n    if (this.isDirect(\"delete\")) {\n      return this.directMutation(\"delete\", remove);\n    }\n    try {\n      return await this.mutate(\n        \"delete\",\n        (entity) => entity.deleteWithNoMatch(id, noMatch),\n        async (context) => {\n          await this.runHook(() => hooks?.beforeDelete?.(id, context));\n          const deleted = await remove();\n          if (!deleted) throw noMatch;\n          await this.runHook(() => hooks?.afterDelete?.(id, context));\n          return true;\n        },\n      );\n    } catch (error) {\n      if (\n        error === noMatch &&\n        !this.ctx.transactionBound &&\n        !this.ctx.scope.activeTransaction()\n      ) {\n        return false;\n      }\n      throw error;\n    }\n  }\n\n  /** Count every write that runs on an already bound transaction. */\n  private directMutation<T>(\n    operation: MutationOperation,\n    run: () => Promise<T>,\n  ): Promise<T> {\n    if (!this.ctx.transactionBound) return run();\n    return this.ctx.scope.runMutation(this.ctx.table.$name, operation, run);\n  }\n\n  /** An insert matches no existing row, so a predicate could only be dropped. */\n  private assertUnfiltered(operation: \"create\" | \"upsert\"): void {\n    if (this.state.where !== undefined) {\n      throw invalidDatabaseRequest(\n        `${operation}() cannot follow where(); it does not select rows to change`,\n      );\n    }\n  }\n\n  /**\n   * Go straight to the DataPath only when there is nothing to sequence and no\n   * open transaction to join. A root client that skipped the second check would\n   * commit on the pool while a transaction it cannot see is still open.\n   */\n  private isDirect(operation: MutationOperation): boolean {\n    if (this.hasHooks(operation)) return false;\n    return this.ctx.transactionBound || !this.ctx.scope.activeTransaction();\n  }\n\n  private hasHooks(operation: MutationOperation): boolean {\n    const hooks = this.ctx.hooks;\n    if (!hooks) return false;\n    switch (operation) {\n      case \"create\":\n        return Boolean(hooks.beforeCreate ?? hooks.afterCreate);\n      case \"update\":\n        return Boolean(hooks.beforeUpdate ?? hooks.afterUpdate);\n      case \"upsert\":\n        return Boolean(hooks.beforeUpsert ?? hooks.afterUpsert);\n      case \"delete\":\n        return Boolean(hooks.beforeDelete ?? hooks.afterDelete);\n    }\n  }\n\n  /**\n   * Run one mutation atomically. A top-level call restarts itself on the\n   * transaction-bound client, so hooks, validation, the mutation, and its after\n   * hook commit or roll back together. An unhooked root mutation reaches this\n   * only to join an open transaction; its bound client counts the direct write\n   * without constructing a hook context.\n   */\n  private async mutate<T>(\n    operation: MutationOperation,\n    restart: (entity: EntityClient) => Promise<T>,\n    body: (context: HookContext) => Promise<T>,\n  ): Promise<T> {\n    if (this.ctx.transactionBound) {\n      return this.ctx.scope.runMutation(this.ctx.table.$name, operation, () =>\n        body(this.hookContext()),\n      );\n    }\n    try {\n      return await this.ctx.runInTransaction((entity) =>\n        // Change the execution context without losing the caller's query state\n        // or mutating the shared transaction client.\n        restart(entity.clone(this.state)),\n      );\n    } catch (error) {\n      if (\n        error instanceof DatabaseValidationError ||\n        error instanceof MutationNoMatchError\n      ) {\n        throw error;\n      }\n      // BEGIN and COMMIT fail outside the inner classification boundary.\n      throw classifyDatabaseError(error, \"write\");\n    }\n  }\n\n  /** Resolve the surface at hook time so it cannot outlive its transaction. */\n  private hookContext(): HookContext {\n    const database = this.ctx.scope.activeTransaction();\n    if (!database) throw new DatabasePluginError(\"INTERNAL\", \"write\");\n    return { entity: this.ctx.table.$name, app: { database } };\n  }\n\n  /** Substitute the payload a before hook returned, if it returned one. */\n  private async runBefore(invoke: () => unknown, values: Row): Promise<Row> {\n    const replacement = await this.runHook(invoke);\n    if (replacement === undefined || replacement === null) return values;\n    if (!isReplacement(replacement)) {\n      throw new DatabasePluginError(\"INTERNAL\", \"write\");\n    }\n    return replacement;\n  }\n\n  /** Keep a deliberate validation signal; collapse every other hook failure. */\n  private async runHook(invoke: () => unknown): Promise<unknown> {\n    try {\n      return await invoke();\n    } catch (error) {\n      if (error instanceof DatabaseValidationError) throw error;\n      throw classifyDatabaseError(error, \"write\");\n    }\n  }\n\n  /** Validate caller values against the finalized trusted-write schema. */\n  private async write<T>(\n    kind: \"create\" | \"update\",\n    values: Row,\n    operation: (dataPath: DataPath, values: Row) => Promise<T>,\n    // A payload a hook replaced is server-authored, so blaming the caller lies.\n    byHook = false,\n  ): Promise<T> {\n    const rejection = byHook ? \"INTERNAL\" : \"INVALID_REQUEST\";\n    if (kind === \"update\" && Object.keys(values).length === 0) {\n      throw new DatabasePluginError(rejection, \"write\");\n    }\n    let parsed: Row;\n    try {\n      const validator = (\n        kind === \"create\"\n          ? this.ctx.table.$insertSchema\n          : this.ctx.table.$updateSchema\n      ) as { parse(value: unknown): Row };\n      parsed = validator.parse(values);\n    } catch {\n      throw new DatabasePluginError(rejection, \"write\");\n    }\n    return this.run(\n      \"write\",\n      (dataPath) => operation(dataPath, parsed),\n      databaseWriteDefaults,\n    );\n  }\n\n  /** Execute through AppKit interceptors and expose only safe failures. */\n  private async run<T>(\n    phase: \"read\" | \"write\",\n    operation: (dataPath: DataPath) => Promise<T>,\n    defaults: PluginExecuteConfig = databaseReadDefaults,\n  ): Promise<T> {\n    try {\n      this.ctx.assertActive();\n    } catch (error) {\n      throw classifyDatabaseError(error, phase);\n    }\n    const result = await this.ctx.execute(\n      async () => {\n        try {\n          this.ctx.assertActive();\n          return await operation(this.ctx.getDataPath());\n        } catch (error) {\n          throw classifyDatabaseError(error, phase);\n        }\n      },\n      { default: defaults },\n    );\n    if (result.ok) return result.data;\n    throw databaseErrorFromStatus(result.status, phase);\n  }\n}\n"],"mappings":";;;;;;;;AAqDA,IAAM,uBAAN,cAAmC,oBAAoB;CACrD,cAAc;AACZ,QAAM,aAAa,QAAQ;;;;AAK/B,SAAS,cAAiB,OAAU,uBAAO,IAAI,KAAa,EAAK;AAC/D,KACE,UAAU,QACV,OAAO,UAAU,YACjB,OAAO,UAAU,aACjB,OAAO,UAAU,YAChB,OAAO,UAAU,YAAY,OAAO,SAAS,MAAM,CAEpD,QAAO;AAET,KAAI,OAAO,UAAU,SACnB,OAAM,IAAI,oBAAoB,mBAAmB,OAAO;AAE1D,KAAI,KAAK,IAAI,MAAM,CAAE,OAAM,IAAI,oBAAoB,mBAAmB,OAAO;AAC7E,KACE,CAAC,MAAM,QAAQ,MAAM,IACrB,OAAO,eAAe,MAAM,KAAK,OAAO,UAExC,OAAM,IAAI,oBAAoB,mBAAmB,OAAO;AAC1D,MAAK,IAAI,MAAM;CACf,MAAM,OACJ,MAAM,QAAQ,MAAM,GAChB,MAAM,KAAK,SAAS,cAAc,MAAM,KAAK,CAAC,GAC9C,OAAO,YACL,OAAO,QAAQ,MAAM,CAAC,KAAK,CAAC,KAAK,UAAU,CACzC,KACA,cAAc,MAAM,KAAK,CAC1B,CAAC,CACH;AAEP,MAAK,OAAO,MAAM;AAClB,QAAO;;;AAIT,SAAS,kBAAqB,UAAsB;AAClD,KAAI;AACF,SAAO,UAAU;UACV,OAAO;AACd,QAAM,sBAAsB,OAAO,OAAO;;;;AAK9C,SAAS,cAAc,OAA8B;AACnD,QAAO,OAAO,UAAU,YAAY,UAAU,QAAQ,CAAC,MAAM,QAAQ,MAAM;;;;;;AAO7E,IAAa,eAAb,MAAa,aAAa;CACxB,YACE,AAAiB,KACjB,AAAiB,QAAmB,EAAE,EACtC;EAFiB;EACA;;CAGnB,AAAQ,MAAM,OAAgC;AAC5C,SAAO,IAAI,aAAa,KAAK,KAAK,MAAM;;;CAI1C,MAAM,QAAmC;EACvC,MAAM,WAAW,cAAc,OAAO;AACtC,SAAO,KAAK,MAAM;GAChB,GAAG,KAAK;GACR,OAAO,SAAS,KAAK,MAAM,OAAO,SAAS;GAC5C,CAAC;;;CAIJ,MAAM,OAAgC;EACpC,MAAM,WAAW,cAAc,MAAM;AACrC,SAAO,KAAK,MAAM;GAChB,GAAG,KAAK;GACR,OAAO;IAAE,GAAG,KAAK,MAAM;IAAO,GAAG;IAAU;GAC5C,CAAC;;CAGJ,OAAO,SAA0C;AAC/C,SAAO,KAAK,MAAM;GAAE,GAAG,KAAK;GAAO,QAAQ,cAAc,QAAQ;GAAE,CAAC;;;CAItE,QAAQ,SAAoC;EAC1C,MAAM,WAAW,cAAc,QAAQ;AACvC,SAAO,KAAK,MAAM;GAChB,GAAG,KAAK;GACR,SAAS;IAAE,GAAG,KAAK,MAAM;IAAS,GAAG;IAAU;GAChD,CAAC;;CAGJ,MAAM,OAA6B;AACjC,SAAO,wBACL,KAAK,MAAM;GAAE,GAAG,KAAK;GAAO,OAAO,cAAc,MAAM;GAAE,CAAC,CAC3D;;CAGH,OAAO,QAA8B;AACnC,SAAO,wBACL,KAAK,MAAM;GAAE,GAAG,KAAK;GAAO,QAAQ,eAAe,OAAO;GAAE,CAAC,CAC9D;;;CAIH,MAAM,UAA0B;AAC9B,SAAO,KAAK,IAAI,SAAS,aACvB,SAAS,OAAO,KAAK,IAAI,OAAO,KAAK,MAAM,CAC5C;;CAGH,MAAM,QAA6B;AACjC,UAAQ,MAAM,KAAK,MAAM,EAAE,CAAC,SAAS,EAAE,MAAM;;CAG/C,KAAK,IAAkC;AACrC,SAAO,KAAK,IAAI,SAAS,aACvB,SAAS,QAAQ,KAAK,IAAI,OAAO,IAAI;GACnC,OAAO,KAAK,MAAM;GAClB,QAAQ,KAAK,MAAM;GACnB,SAAS,KAAK,MAAM;GACrB,CAAC,CACH;;CAGH,QAAyB;AACvB,SAAO,KAAK,IAAI,SAAS,aACvB,SAAS,MAAM,KAAK,IAAI,OAAO,KAAK,MAAM,MAAM,CACjD;;CAGH,MAAM,OAAO,QAA2B;AACtC,OAAK,iBAAiB,SAAS;EAC/B,MAAM,QAAQ,KAAK,IAAI;EACvB,MAAM,UAAU,SAAc,SAAS,UACrC,KAAK,MACH,UACA,UACC,UAAU,WAAW,SAAS,OAAO,KAAK,IAAI,OAAO,OAAO,EAC7D,OACD;AACH,MAAI,KAAK,SAAS,SAAS,CACzB,QAAO,KAAK,eAAe,gBAAgB,OAAO,OAAO,CAAC;AAE5D,SAAO,KAAK,OACV,WACC,WAAW,OAAO,OAAO,OAAO,EACjC,OAAO,YAAY;GACjB,MAAM,UAAU,MAAM,KAAK,gBACnB,OAAO,eAAe,QAAQ,QAAQ,EAC5C,OACD;GACD,MAAM,MAAM,MAAM,OAAO,SAAS,YAAY,OAAO;AACrD,SAAM,KAAK,cAAc,OAAO,cAAc,KAAK,QAAQ,CAAC;AAC5D,UAAO;IAEV;;CAGH,OAAO,IAAa,QAAkC;AACpD,SAAO,KAAK,kBAAkB,IAAI,QAAQ,IAAI,sBAAsB,CAAC;;CAGvE,MAAc,kBACZ,IACA,QACA,SACqB;EACrB,MAAM,QAAQ,KAAK,IAAI;EACvB,MAAM,SAAS,SAAc,SAAS,UACpC,KAAK,MACH,UACA,UACC,UAAU,WACT,SAAS,OAAO,KAAK,IAAI,OAAO,IAAI,QAAQ,KAAK,MAAM,MAAM,EAC/D,OACD;AACH,MAAI,KAAK,SAAS,SAAS,CACzB,QAAO,KAAK,eAAe,gBAAgB,MAAM,OAAO,CAAC;AAE3D,MAAI;AACF,UAAO,MAAM,KAAK,OAChB,WACC,WAAW,OAAO,kBAAkB,IAAI,QAAQ,QAAQ,EACzD,OAAO,YAAY;IACjB,MAAM,UAAU,MAAM,KAAK,gBACnB,OAAO,eAAe,IAAI,QAAQ,QAAQ,EAChD,OACD;IACD,MAAM,MAAM,MAAM,MAAM,SAAS,YAAY,OAAO;AACpD,QAAI,QAAQ,KAAM,OAAM;AACxB,UAAM,KAAK,cAAc,OAAO,cAAc,KAAK,QAAQ,CAAC;AAC5D,WAAO;KAEV;WACM,OAAO;AACd,OACE,UAAU,WACV,CAAC,KAAK,IAAI,oBACV,CAAC,KAAK,IAAI,MAAM,mBAAmB,CAEnC,QAAO;AAET,SAAM;;;CAIV,MAAM,OAAO,QAAa,SAA+C;AACvE,OAAK,iBAAiB,SAAS;EAC/B,MAAM,QAAQ,KAAK,IAAI;EACvB,MAAM,aAAa,QAAQ;EAC3B,MAAM,SAAS,SAAc,SAAS,UACpC,KAAK,MACH,UACA,UACC,UAAU,WACT,SAAS,OAAO,KAAK,IAAI,OAAO,QAAQ,WAAW,EACrD,OACD;AACH,MAAI,KAAK,SAAS,SAAS,CACzB,QAAO,KAAK,eAAe,gBAAgB,MAAM,OAAO,CAAC;AAE3D,SAAO,KAAK,OACV,WACC,WAAW,OAAO,OAAO,QAAQ,EAAE,YAAY,CAAC,EACjD,OAAO,YAAY;GACjB,MAAM,UAAU,MAAM,KAAK,gBACnB,OAAO,eAAe,QAAQ,QAAQ,EAC5C,OACD;GAED,MAAM,MAAM,MAAM,MAAM,SAAS,YAAY,OAAO;AACpD,SAAM,KAAK,cAAc,OAAO,cAAc,KAAK,QAAQ,CAAC;AAC5D,UAAO;IAEV;;CAGH,OAAO,IAA+B;AACpC,SAAO,KAAK,kBAAkB,IAAI,IAAI,sBAAsB,CAAC;;CAG/D,MAAc,kBACZ,IACA,SACkB;EAClB,MAAM,QAAQ,KAAK,IAAI;EACvB,MAAM,eACJ,KAAK,IACH,UACC,aAAa,SAAS,OAAO,KAAK,IAAI,OAAO,IAAI,KAAK,MAAM,MAAM,EACnE,sBACD;AACH,MAAI,KAAK,SAAS,SAAS,CACzB,QAAO,KAAK,eAAe,UAAU,OAAO;AAE9C,MAAI;AACF,UAAO,MAAM,KAAK,OAChB,WACC,WAAW,OAAO,kBAAkB,IAAI,QAAQ,EACjD,OAAO,YAAY;AACjB,UAAM,KAAK,cAAc,OAAO,eAAe,IAAI,QAAQ,CAAC;AAE5D,QAAI,CADY,MAAM,QAAQ,CAChB,OAAM;AACpB,UAAM,KAAK,cAAc,OAAO,cAAc,IAAI,QAAQ,CAAC;AAC3D,WAAO;KAEV;WACM,OAAO;AACd,OACE,UAAU,WACV,CAAC,KAAK,IAAI,oBACV,CAAC,KAAK,IAAI,MAAM,mBAAmB,CAEnC,QAAO;AAET,SAAM;;;;CAKV,AAAQ,eACN,WACA,KACY;AACZ,MAAI,CAAC,KAAK,IAAI,iBAAkB,QAAO,KAAK;AAC5C,SAAO,KAAK,IAAI,MAAM,YAAY,KAAK,IAAI,MAAM,OAAO,WAAW,IAAI;;;CAIzE,AAAQ,iBAAiB,WAAsC;AAC7D,MAAI,KAAK,MAAM,UAAU,OACvB,OAAM,uBACJ,GAAG,UAAU,6DACd;;;;;;;CASL,AAAQ,SAAS,WAAuC;AACtD,MAAI,KAAK,SAAS,UAAU,CAAE,QAAO;AACrC,SAAO,KAAK,IAAI,oBAAoB,CAAC,KAAK,IAAI,MAAM,mBAAmB;;CAGzE,AAAQ,SAAS,WAAuC;EACtD,MAAM,QAAQ,KAAK,IAAI;AACvB,MAAI,CAAC,MAAO,QAAO;AACnB,UAAQ,WAAR;GACE,KAAK,SACH,QAAO,QAAQ,MAAM,gBAAgB,MAAM,YAAY;GACzD,KAAK,SACH,QAAO,QAAQ,MAAM,gBAAgB,MAAM,YAAY;GACzD,KAAK,SACH,QAAO,QAAQ,MAAM,gBAAgB,MAAM,YAAY;GACzD,KAAK,SACH,QAAO,QAAQ,MAAM,gBAAgB,MAAM,YAAY;;;;;;;;;;CAW7D,MAAc,OACZ,WACA,SACA,MACY;AACZ,MAAI,KAAK,IAAI,iBACX,QAAO,KAAK,IAAI,MAAM,YAAY,KAAK,IAAI,MAAM,OAAO,iBACtD,KAAK,KAAK,aAAa,CAAC,CACzB;AAEH,MAAI;AACF,UAAO,MAAM,KAAK,IAAI,kBAAkB,WAGtC,QAAQ,OAAO,MAAM,KAAK,MAAM,CAAC,CAClC;WACM,OAAO;AACd,OACE,iBAAiB,2BACjB,iBAAiB,qBAEjB,OAAM;AAGR,SAAM,sBAAsB,OAAO,QAAQ;;;;CAK/C,AAAQ,cAA2B;EACjC,MAAM,WAAW,KAAK,IAAI,MAAM,mBAAmB;AACnD,MAAI,CAAC,SAAU,OAAM,IAAI,oBAAoB,YAAY,QAAQ;AACjE,SAAO;GAAE,QAAQ,KAAK,IAAI,MAAM;GAAO,KAAK,EAAE,UAAU;GAAE;;;CAI5D,MAAc,UAAU,QAAuB,QAA2B;EACxE,MAAM,cAAc,MAAM,KAAK,QAAQ,OAAO;AAC9C,MAAI,gBAAgB,UAAa,gBAAgB,KAAM,QAAO;AAC9D,MAAI,CAAC,cAAc,YAAY,CAC7B,OAAM,IAAI,oBAAoB,YAAY,QAAQ;AAEpD,SAAO;;;CAIT,MAAc,QAAQ,QAAyC;AAC7D,MAAI;AACF,UAAO,MAAM,QAAQ;WACd,OAAO;AACd,OAAI,iBAAiB,wBAAyB,OAAM;AACpD,SAAM,sBAAsB,OAAO,QAAQ;;;;CAK/C,MAAc,MACZ,MACA,QACA,WAEA,SAAS,OACG;EACZ,MAAM,YAAY,SAAS,aAAa;AACxC,MAAI,SAAS,YAAY,OAAO,KAAK,OAAO,CAAC,WAAW,EACtD,OAAM,IAAI,oBAAoB,WAAW,QAAQ;EAEnD,IAAI;AACJ,MAAI;AAMF,aAJE,SAAS,WACL,KAAK,IAAI,MAAM,gBACf,KAAK,IAAI,MAAM,eAEF,MAAM,OAAO;UAC1B;AACN,SAAM,IAAI,oBAAoB,WAAW,QAAQ;;AAEnD,SAAO,KAAK,IACV,UACC,aAAa,UAAU,UAAU,OAAO,EACzC,sBACD;;;CAIH,MAAc,IACZ,OACA,WACA,WAAgC,sBACpB;AACZ,MAAI;AACF,QAAK,IAAI,cAAc;WAChB,OAAO;AACd,SAAM,sBAAsB,OAAO,MAAM;;EAE3C,MAAM,SAAS,MAAM,KAAK,IAAI,QAC5B,YAAY;AACV,OAAI;AACF,SAAK,IAAI,cAAc;AACvB,WAAO,MAAM,UAAU,KAAK,IAAI,aAAa,CAAC;YACvC,OAAO;AACd,UAAM,sBAAsB,OAAO,MAAM;;KAG7C,EAAE,SAAS,UAAU,CACtB;AACD,MAAI,OAAO,GAAI,QAAO,OAAO;AAC7B,QAAM,wBAAwB,OAAO,QAAQ,MAAM"}

package/dist/plugins/database/entity-types.d.ts

@@ -81,5 +81,5 @@ type DatabaseExports = TransactionClient & {
   transaction<T>(callback: (tx: TransactionClient) => Promise<T>): Promise<T>;
 };
 //#endregion
-export { DatabaseExports };
+export { DatabaseExports, TransactionClient };
 //# sourceMappingURL=entity-types.d.ts.map

package/dist/plugins/database/hooks.d.ts

@@ -0,0 +1,38 @@
+import { DatabaseRegistry, DatabaseRegistryEntry } from "../../database/contract/registry.js";
+import { IdValue } from "../../database/contract/wire.js";
+import { TransactionClient } from "./entity-types.js";
+import { Row } from "../../database/runtime/data-path.js";
+
+//#region src/plugins/database/hooks.d.ts
+/** The only capability a hook receives: entities bound to its transaction. */
+interface HookApp {
+  readonly database: TransactionClient;
+}
+/** Which entity is being mutated, and the surface a hook may write through. */
+interface HookContext {
+  readonly entity: string;
+  readonly app: HookApp;
+}
+type FacetOf<TTable, TFacet extends "row" | "insert" | "update"> = TTable extends keyof DatabaseRegistry ? DatabaseRegistry[TTable] extends DatabaseRegistryEntry ? DatabaseRegistry[TTable][TFacet] : Row : Row;
+type MaybePromise<T> = T | Promise<T>;
+/**
+ * Mutation lifecycle for one entity. A before hook may return a replacement
+ * payload, which is revalidated against the trusted schema before it is
+ * persisted. Every hook, the mutation, and any write a hook issues through
+ * `ctx.app.database` share one transaction, so a rejection anywhere rolls all
+ * of them back. Throw `DatabaseValidationError` to answer a generated route
+ * with `422`; any other failure stays an opaque server error.
+ */
+interface EntityMutationHooks<TTable extends string = string> {
+  beforeCreate?(values: FacetOf<TTable, "insert">, context: HookContext): MaybePromise<FacetOf<TTable, "insert"> | void>;
+  afterCreate?(row: FacetOf<TTable, "row">, context: HookContext): MaybePromise<void>;
+  beforeUpdate?(id: IdValue, values: FacetOf<TTable, "update">, context: HookContext): MaybePromise<FacetOf<TTable, "update"> | void>;
+  afterUpdate?(row: FacetOf<TTable, "row">, context: HookContext): MaybePromise<void>;
+  beforeUpsert?(values: FacetOf<TTable, "insert">, context: HookContext): MaybePromise<FacetOf<TTable, "insert"> | void>;
+  afterUpsert?(row: FacetOf<TTable, "row">, context: HookContext): MaybePromise<void>;
+  beforeDelete?(id: IdValue, context: HookContext): MaybePromise<void>;
+  afterDelete?(id: IdValue, context: HookContext): MaybePromise<void>;
+}
+//#endregion
+export { EntityMutationHooks, HookApp, HookContext };
+//# sourceMappingURL=hooks.d.ts.map

package/dist/plugins/database/hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.d.ts","names":[],"sources":["../../../src/plugins/database/hooks.ts"],"mappings":";;;;;;;UAWiB,OAAA;EAAA,SACN,QAAA,EAAU,iBAAA;AAAA;;UAIJ,WAAA;EAAA,SACN,MAAA;EAAA,SACA,GAAA,EAAK,OAAA;AAAA;AAAA,KAIX,OAAA,uDAGD,MAAA,eAAqB,gBAAA,GACrB,gBAAA,CAAiB,MAAA,UAAgB,qBAAA,GAC/B,gBAAA,CAAiB,MAAA,EAAQ,MAAA,IACzB,GAAA,GACF,GAAA;AAAA,KAEC,YAAA,MAAkB,CAAA,GAAI,OAAA,CAAQ,CAAA;;;;;;;AAZlC;;UAsBgB,mBAAA;EACf,YAAA,EACE,MAAA,EAAQ,OAAA,CAAQ,MAAA,aAChB,OAAA,EAAS,WAAA,GACR,YAAA,CAAa,OAAA,CAAQ,MAAA;EACxB,WAAA,EACE,GAAA,EAAK,OAAA,CAAQ,MAAA,UACb,OAAA,EAAS,WAAA,GACR,YAAA;EACH,YAAA,EACE,EAAA,EAAI,OAAA,EACJ,MAAA,EAAQ,OAAA,CAAQ,MAAA,aAChB,OAAA,EAAS,WAAA,GACR,YAAA,CAAa,OAAA,CAAQ,MAAA;EACxB,WAAA,EACE,GAAA,EAAK,OAAA,CAAQ,MAAA,UACb,OAAA,EAAS,WAAA,GACR,YAAA;EACH,YAAA,EACE,MAAA,EAAQ,OAAA,CAAQ,MAAA,aAChB,OAAA,EAAS,WAAA,GACR,YAAA,CAAa,OAAA,CAAQ,MAAA;EACxB,WAAA,EACE,GAAA,EAAK,OAAA,CAAQ,MAAA,UACb,OAAA,EAAS,WAAA,GACR,YAAA;EACH,YAAA,EAAc,EAAA,EAAI,OAAA,EAAS,OAAA,EAAS,WAAA,GAAc,YAAA;EAClD,WAAA,EAAa,EAAA,EAAI,OAAA,EAAS,OAAA,EAAS,WAAA,GAAc,YAAA;AAAA"}

package/dist/plugins/database/index.d.ts

@@ -1,3 +1,4 @@
-import { DatabaseExports } from "./entity-types.js";
-import { IDatabaseConfig } from "./types.js";
+import { DatabaseExports, TransactionClient } from "./entity-types.js";
+import { EntityMutationHooks, HookApp, HookContext } from "./hooks.js";
+import { DatabaseApiConfig, DatabaseApiWriteOperation, DatabaseApiWritesConfig, EntityHooks, IDatabaseConfig, ReadSerializer, ReadSerializerContext } from "./types.js";
 import { database } from "./database.js";

package/dist/plugins/database/lifecycle.js

@@ -1,10 +1,13 @@
 import { createLogger } from "../../logging/logger.js";
+import { DatabaseValidationError } from "../../errors/database-validation.js";
+import "../../errors/index.js";
 import { createLakebasePool } from "../../connectors/lakebase/index.js";
 import { assertFinalizedSchema } from "../../database/schema-builder/define-schema.js";
 import { DatabasePluginError, classifyDatabaseError } from "../../database/errors.js";
-import { STATEMENT_TIMEOUT_MS } from "./defaults.js";
+import { IDLE_IN_TRANSACTION_TIMEOUT_MS, STATEMENT_TIMEOUT_MS, TRANSACTION_TIMEOUT_MS } from "./defaults.js";
 import { createDrizzleDataPath, createDrizzleDb } from "../../database/runtime/engine/drizzle-data-path.js";
 import { EntityClient } from "./entity-client.js";
+import { createMutationScope } from "./scope.js";
 
 //#region src/plugins/database/lifecycle.ts
 const logger = createLogger("database");
@@ -13,6 +16,7 @@ function buildSql(context) {
 	return async (strings, ...values) => {
 		try {
 			context.assertActive();
+			if (context.transactionBound) context.scope.consumeTransactionOperation();
 			return await context.getDataPath().raw(strings, ...values);
 		} catch (error) {
 			throw classifyDatabaseError(error, "read");
@@ -26,47 +30,76 @@ function buildTransactionClient(context) {
 		table,
 		getDataPath: context.getDataPath,
 		execute: context.execute,
-		assertActive: context.assertActive
+		assertActive: context.assertActive,
+		scope: context.scope,
+		hooks: context.hooks?.[name],
+		transactionBound: context.transactionBound,
+		runInTransaction: (run) => runTransaction(context, (tx) => run(entityOf(tx, name)))
 	});
 	result.sql = buildSql(context);
 	return result;
 }
+/** Typegen owns the entity keys, so reaching one by table name stays dynamic. */
+function entityOf(tx, name) {
+	return tx[name];
+}
+/** Reject from inside the driver callback so the driver rolls back on expiry. */
+function runWithTransactionDeadline(run) {
+	let timer;
+	const deadline = new Promise((_, reject) => {
+		timer = setTimeout(() => reject(new DatabasePluginError("TRANSIENT", "transaction")), TRANSACTION_TIMEOUT_MS);
+		timer.unref?.();
+	});
+	return Promise.race([Promise.resolve().then(run), deadline]).finally(() => clearTimeout(timer));
+}
+/**
+* Run inside one transaction, joining the active one rather than nesting:
+* PostgreSQL has no nested transaction, and a savepoint would let part of a
+* hooked mutation survive a rollback.
+*/
+function runTransaction(context, callback) {
+	context.assertActive();
+	const active = context.scope.activeTransaction();
+	if (active) return callback(active);
+	return context.getDataPath().transaction(async (txDataPath) => {
+		let open = true;
+		const assertTransactionActive = () => {
+			context.assertActive();
+			if (!open) throw new DatabasePluginError("INTERNAL", "transaction");
+		};
+		const directExecute = async (operation) => ({
+			ok: true,
+			data: await operation()
+		});
+		const tx = buildTransactionClient({
+			...context,
+			getDataPath: () => txDataPath,
+			execute: directExecute,
+			assertActive: assertTransactionActive,
+			transactionBound: true
+		});
+		try {
+			return await runWithTransactionDeadline(() => context.scope.runWithTransaction(tx, () => callback(tx)));
+		} finally {
+			open = false;
+		}
+	});
+}
 /** Add the transaction entry point to the root database surface. */
 function buildDatabaseExports(context) {
 	const result = buildTransactionClient(context);
 	result.transaction = async (callback) => {
 		try {
-			context.assertActive();
-			return await context.getDataPath().transaction(async (txDataPath) => {
-				let active = true;
-				const assertTransactionActive = () => {
-					context.assertActive();
-					if (!active) throw new DatabasePluginError("INTERNAL", "transaction");
-				};
-				const directExecute = async (operation) => ({
-					ok: true,
-					data: await operation()
-				});
-				const tx = buildTransactionClient({
-					...context,
-					getDataPath: () => txDataPath,
-					execute: directExecute,
-					assertActive: assertTransactionActive
-				});
-				try {
-					return await callback(tx);
-				} finally {
-					active = false;
-				}
-			});
+			return await runTransaction(context, callback);
 		} catch (error) {
+			if (error instanceof DatabaseValidationError) throw error;
 			throw classifyDatabaseError(error, "transaction");
 		}
 	};
 	return result;
 }
 /** Validate the schema, create one pool-backed API, and verify connectivity. */
-async function createDatabaseState(schema, execute) {
+async function createDatabaseState(schema, execute, hooks) {
 	try {
 		assertFinalizedSchema(schema);
 	} catch (error) {
@@ -79,13 +112,19 @@ async function createDatabaseState(schema, execute) {
 		if (!active) throw new DatabasePluginError("INTERNAL", "runtime");
 	};
 	try {
-		pool = createLakebasePool({ statement_timeout: STATEMENT_TIMEOUT_MS });
+		pool = createLakebasePool({
+			statement_timeout: STATEMENT_TIMEOUT_MS,
+			idle_in_transaction_session_timeout: IDLE_IN_TRANSACTION_TIMEOUT_MS
+		});
 		const dataPath = createDrizzleDataPath(createDrizzleDb(pool, schema), schema, { columnAccess: "trusted" });
 		const exports = buildDatabaseExports({
 			schema,
 			getDataPath: () => dataPath,
 			execute,
-			assertActive
+			assertActive,
+			scope: createMutationScope(),
+			hooks,
+			transactionBound: false
 		});
 		await dataPath.raw`select 1`;
 		return {

package/dist/plugins/database/lifecycle.js.map

@@ -1 +1 @@
-{"version":3,"file":"lifecycle.js","names":[],"sources":["../../../src/plugins/database/lifecycle.ts"],"sourcesContent":["import { createLakebasePool } from \"../../connectors/lakebase\";\nimport {\n  classifyDatabaseError,\n  DatabasePluginError,\n} from \"../../database/errors\";\nimport type { DataPath } from \"../../database/runtime\";\nimport {\n  createDrizzleDataPath,\n  createDrizzleDb,\n} from \"../../database/runtime/engine/drizzle-data-path\";\nimport type { Schema } from \"../../database/schema-builder\";\nimport { assertFinalizedSchema } from \"../../database/schema-builder/define-schema\";\nimport { createLogger } from \"../../logging/logger\";\nimport { STATEMENT_TIMEOUT_MS } from \"./defaults\";\nimport { EntityClient, type EntityExecute } from \"./entity-client\";\nimport type {\n  DatabaseExports,\n  SqlTag,\n  TransactionClient,\n} from \"./entity-types\";\n\nconst logger = createLogger(\"database\");\n\n/** Resources owned by one successfully initialized plugin instance. */\nexport interface DatabaseState {\n  readonly pool: ReturnType<typeof createLakebasePool>;\n  readonly exports: DatabaseExports;\n  readonly deactivate: () => void;\n}\n\ninterface ExportContext {\n  readonly schema: Schema;\n  readonly getDataPath: () => DataPath;\n  readonly execute: EntityExecute;\n  readonly assertActive: () => void;\n}\n\n/** Execute value-only SQL on the bound DataPath without per-statement retries. */\nfunction buildSql(context: ExportContext): SqlTag {\n  return async <T = Record<string, unknown>>(\n    strings: TemplateStringsArray,\n    ...values: unknown[]\n  ) => {\n    try {\n      context.assertActive();\n      // DataPath accepts value interpolation only and keeps Drizzle private.\n      return await context.getDataPath().raw<T>(strings, ...values);\n    } catch (error) {\n      throw classifyDatabaseError(error, \"read\");\n    }\n  };\n}\n\n/** Build entities and SQL bound to either the root pool or one transaction. */\nfunction buildTransactionClient(context: ExportContext): TransactionClient {\n  const result: Record<string, unknown> = Object.create(null);\n  for (const [name, table] of Object.entries(context.schema.$tables)) {\n    result[name] = new EntityClient({\n      table,\n      getDataPath: context.getDataPath,\n      execute: context.execute,\n      assertActive: context.assertActive,\n    });\n  }\n  result.sql = buildSql(context);\n  return result as TransactionClient;\n}\n\n/** Add the transaction entry point to the root database surface. */\nfunction buildDatabaseExports(context: ExportContext): DatabaseExports {\n  const result = buildTransactionClient(context) as DatabaseExports;\n  result.transaction = async <T>(\n    callback: (tx: TransactionClient) => Promise<T>,\n  ) => {\n    try {\n      context.assertActive();\n      return await context.getDataPath().transaction(async (txDataPath) => {\n        let active = true;\n        const assertTransactionActive = () => {\n          context.assertActive();\n          if (!active) throw new DatabasePluginError(\"INTERNAL\", \"transaction\");\n        };\n        // The outer transaction owns execution; inner clients use its connection.\n        const directExecute: EntityExecute = async (operation) => ({\n          ok: true,\n          data: await operation(),\n        });\n        const tx = buildTransactionClient({\n          ...context,\n          getDataPath: () => txDataPath,\n          execute: directExecute,\n          assertActive: assertTransactionActive,\n        });\n        try {\n          return await callback(tx);\n        } finally {\n          // Captured clients must not outlive the transaction callback.\n          active = false;\n        }\n      });\n    } catch (error) {\n      throw classifyDatabaseError(error, \"transaction\");\n    }\n  };\n  return result;\n}\n\n/** Validate the schema, create one pool-backed API, and verify connectivity. */\nexport async function createDatabaseState<TSchema extends Schema>(\n  schema: TSchema,\n  execute: EntityExecute,\n): Promise<DatabaseState> {\n  try {\n    assertFinalizedSchema(schema);\n  } catch (error) {\n    logger.error(\"Database schema failed validation: %O\", error);\n    throw new DatabasePluginError(\"SETUP_FAILED\", \"setup\");\n  }\n\n  let active = true;\n  let pool: ReturnType<typeof createLakebasePool> | undefined;\n  const assertActive = () => {\n    if (!active) throw new DatabasePluginError(\"INTERNAL\", \"runtime\");\n  };\n  try {\n    pool = createLakebasePool({ statement_timeout: STATEMENT_TIMEOUT_MS });\n    const db = createDrizzleDb(pool, schema);\n    const dataPath = createDrizzleDataPath(db, schema, {\n      columnAccess: \"trusted\",\n    });\n    const exports = buildDatabaseExports({\n      schema,\n      getDataPath: () => dataPath,\n      execute,\n      assertActive,\n    });\n    // Do not publish exports until an authenticated statement succeeds.\n    await dataPath.raw`select 1`;\n    return {\n      pool,\n      exports,\n      deactivate: () => {\n        active = false;\n      },\n    };\n  } catch (error) {\n    logger.error(\"Database setup failed: %O\", error);\n    active = false;\n    await pool?.end().catch(() => undefined);\n    throw new DatabasePluginError(\"SETUP_FAILED\", \"setup\");\n  }\n}\n"],"mappings":";;;;;;;;;AAqBA,MAAM,SAAS,aAAa,WAAW;;AAiBvC,SAAS,SAAS,SAAgC;AAChD,QAAO,OACL,SACA,GAAG,WACA;AACH,MAAI;AACF,WAAQ,cAAc;AAEtB,UAAO,MAAM,QAAQ,aAAa,CAAC,IAAO,SAAS,GAAG,OAAO;WACtD,OAAO;AACd,SAAM,sBAAsB,OAAO,OAAO;;;;;AAMhD,SAAS,uBAAuB,SAA2C;CACzE,MAAM,SAAkC,OAAO,OAAO,KAAK;AAC3D,MAAK,MAAM,CAAC,MAAM,UAAU,OAAO,QAAQ,QAAQ,OAAO,QAAQ,CAChE,QAAO,QAAQ,IAAI,aAAa;EAC9B;EACA,aAAa,QAAQ;EACrB,SAAS,QAAQ;EACjB,cAAc,QAAQ;EACvB,CAAC;AAEJ,QAAO,MAAM,SAAS,QAAQ;AAC9B,QAAO;;;AAIT,SAAS,qBAAqB,SAAyC;CACrE,MAAM,SAAS,uBAAuB,QAAQ;AAC9C,QAAO,cAAc,OACnB,aACG;AACH,MAAI;AACF,WAAQ,cAAc;AACtB,UAAO,MAAM,QAAQ,aAAa,CAAC,YAAY,OAAO,eAAe;IACnE,IAAI,SAAS;IACb,MAAM,gCAAgC;AACpC,aAAQ,cAAc;AACtB,SAAI,CAAC,OAAQ,OAAM,IAAI,oBAAoB,YAAY,cAAc;;IAGvE,MAAM,gBAA+B,OAAO,eAAe;KACzD,IAAI;KACJ,MAAM,MAAM,WAAW;KACxB;IACD,MAAM,KAAK,uBAAuB;KAChC,GAAG;KACH,mBAAmB;KACnB,SAAS;KACT,cAAc;KACf,CAAC;AACF,QAAI;AACF,YAAO,MAAM,SAAS,GAAG;cACjB;AAER,cAAS;;KAEX;WACK,OAAO;AACd,SAAM,sBAAsB,OAAO,cAAc;;;AAGrD,QAAO;;;AAIT,eAAsB,oBACpB,QACA,SACwB;AACxB,KAAI;AACF,wBAAsB,OAAO;UACtB,OAAO;AACd,SAAO,MAAM,yCAAyC,MAAM;AAC5D,QAAM,IAAI,oBAAoB,gBAAgB,QAAQ;;CAGxD,IAAI,SAAS;CACb,IAAI;CACJ,MAAM,qBAAqB;AACzB,MAAI,CAAC,OAAQ,OAAM,IAAI,oBAAoB,YAAY,UAAU;;AAEnE,KAAI;AACF,SAAO,mBAAmB,EAAE,mBAAmB,sBAAsB,CAAC;EAEtE,MAAM,WAAW,sBADN,gBAAgB,MAAM,OAAO,EACG,QAAQ,EACjD,cAAc,WACf,CAAC;EACF,MAAM,UAAU,qBAAqB;GACnC;GACA,mBAAmB;GACnB;GACA;GACD,CAAC;AAEF,QAAM,SAAS,GAAG;AAClB,SAAO;GACL;GACA;GACA,kBAAkB;AAChB,aAAS;;GAEZ;UACM,OAAO;AACd,SAAO,MAAM,6BAA6B,MAAM;AAChD,WAAS;AACT,QAAM,MAAM,KAAK,CAAC,YAAY,OAAU;AACxC,QAAM,IAAI,oBAAoB,gBAAgB,QAAQ"}
+{"version":3,"file":"lifecycle.js","names":[],"sources":["../../../src/plugins/database/lifecycle.ts"],"sourcesContent":["import { createLakebasePool } from \"../../connectors/lakebase\";\nimport {\n  classifyDatabaseError,\n  DatabasePluginError,\n} from \"../../database/errors\";\nimport type { DataPath } from \"../../database/runtime\";\nimport {\n  createDrizzleDataPath,\n  createDrizzleDb,\n} from \"../../database/runtime/engine/drizzle-data-path\";\nimport type { Schema } from \"../../database/schema-builder\";\nimport { assertFinalizedSchema } from \"../../database/schema-builder/define-schema\";\nimport { DatabaseValidationError } from \"../../errors\";\nimport { createLogger } from \"../../logging/logger\";\nimport {\n  IDLE_IN_TRANSACTION_TIMEOUT_MS,\n  STATEMENT_TIMEOUT_MS,\n  TRANSACTION_TIMEOUT_MS,\n} from \"./defaults\";\nimport { EntityClient, type EntityExecute } from \"./entity-client\";\nimport type {\n  DatabaseExports,\n  SqlTag,\n  TransactionClient,\n} from \"./entity-types\";\nimport { createMutationScope, type MutationScope } from \"./scope\";\nimport type { DatabaseHooks } from \"./types\";\n\nconst logger = createLogger(\"database\");\n\n/** Resources owned by one successfully initialized plugin instance. */\nexport interface DatabaseState {\n  readonly pool: ReturnType<typeof createLakebasePool>;\n  readonly exports: DatabaseExports;\n  readonly deactivate: () => void;\n}\n\ninterface ExportContext {\n  readonly schema: Schema;\n  readonly getDataPath: () => DataPath;\n  readonly execute: EntityExecute;\n  readonly assertActive: () => void;\n  readonly scope: MutationScope;\n  readonly hooks?: DatabaseHooks;\n  readonly transactionBound: boolean;\n}\n\n/** Execute value-only SQL on the bound DataPath without per-statement retries. */\nfunction buildSql(context: ExportContext): SqlTag {\n  return async <T = Record<string, unknown>>(\n    strings: TemplateStringsArray,\n    ...values: unknown[]\n  ) => {\n    try {\n      context.assertActive();\n      if (context.transactionBound) {\n        context.scope.consumeTransactionOperation();\n      }\n      // DataPath accepts value interpolation only and keeps Drizzle private.\n      return await context.getDataPath().raw<T>(strings, ...values);\n    } catch (error) {\n      throw classifyDatabaseError(error, \"read\");\n    }\n  };\n}\n\n/** Build entities and SQL bound to either the root pool or one transaction. */\nfunction buildTransactionClient(context: ExportContext): TransactionClient {\n  const result: Record<string, unknown> = Object.create(null);\n  for (const [name, table] of Object.entries(context.schema.$tables)) {\n    result[name] = new EntityClient({\n      table,\n      getDataPath: context.getDataPath,\n      execute: context.execute,\n      assertActive: context.assertActive,\n      scope: context.scope,\n      hooks: context.hooks?.[name],\n      transactionBound: context.transactionBound,\n      runInTransaction: (run) =>\n        runTransaction(context, (tx) => run(entityOf(tx, name))),\n    });\n  }\n  result.sql = buildSql(context);\n  return result as TransactionClient;\n}\n\n/** Typegen owns the entity keys, so reaching one by table name stays dynamic. */\nfunction entityOf(tx: TransactionClient, name: string): EntityClient {\n  return (tx as unknown as Record<string, EntityClient>)[name];\n}\n\n/** Reject from inside the driver callback so the driver rolls back on expiry. */\nfunction runWithTransactionDeadline<T>(run: () => Promise<T>): Promise<T> {\n  let timer: ReturnType<typeof setTimeout>;\n  const deadline = new Promise<never>((_, reject) => {\n    timer = setTimeout(\n      () => reject(new DatabasePluginError(\"TRANSIENT\", \"transaction\")),\n      TRANSACTION_TIMEOUT_MS,\n    );\n    timer.unref?.();\n  });\n  return Promise.race([Promise.resolve().then(run), deadline]).finally(() =>\n    clearTimeout(timer),\n  );\n}\n\n/**\n * Run inside one transaction, joining the active one rather than nesting:\n * PostgreSQL has no nested transaction, and a savepoint would let part of a\n * hooked mutation survive a rollback.\n */\nfunction runTransaction<T>(\n  context: ExportContext,\n  callback: (tx: TransactionClient) => Promise<T>,\n): Promise<T> {\n  context.assertActive();\n  const active = context.scope.activeTransaction();\n  if (active) return callback(active);\n  return context.getDataPath().transaction(async (txDataPath) => {\n    let open = true;\n    const assertTransactionActive = () => {\n      context.assertActive();\n      if (!open) throw new DatabasePluginError(\"INTERNAL\", \"transaction\");\n    };\n    // The outer transaction owns execution; inner clients use its connection.\n    const directExecute: EntityExecute = async (operation) => ({\n      ok: true,\n      data: await operation(),\n    });\n    const tx = buildTransactionClient({\n      ...context,\n      getDataPath: () => txDataPath,\n      execute: directExecute,\n      assertActive: assertTransactionActive,\n      transactionBound: true,\n    });\n    try {\n      return await runWithTransactionDeadline(() =>\n        context.scope.runWithTransaction(tx, () => callback(tx)),\n      );\n    } finally {\n      // Captured clients must not outlive the transaction callback.\n      open = false;\n    }\n  });\n}\n\n/** Add the transaction entry point to the root database surface. */\nfunction buildDatabaseExports(context: ExportContext): DatabaseExports {\n  const result = buildTransactionClient(context) as DatabaseExports;\n  result.transaction = async <T>(\n    callback: (tx: TransactionClient) => Promise<T>,\n  ) => {\n    try {\n      return await runTransaction(context, callback);\n    } catch (error) {\n      if (error instanceof DatabaseValidationError) throw error;\n      throw classifyDatabaseError(error, \"transaction\");\n    }\n  };\n  return result;\n}\n\n/** Validate the schema, create one pool-backed API, and verify connectivity. */\nexport async function createDatabaseState<TSchema extends Schema>(\n  schema: TSchema,\n  execute: EntityExecute,\n  hooks?: DatabaseHooks,\n): Promise<DatabaseState> {\n  try {\n    assertFinalizedSchema(schema);\n  } catch (error) {\n    logger.error(\"Database schema failed validation: %O\", error);\n    throw new DatabasePluginError(\"SETUP_FAILED\", \"setup\");\n  }\n\n  let active = true;\n  let pool: ReturnType<typeof createLakebasePool> | undefined;\n  const assertActive = () => {\n    if (!active) throw new DatabasePluginError(\"INTERNAL\", \"runtime\");\n  };\n  try {\n    pool = createLakebasePool({\n      statement_timeout: STATEMENT_TIMEOUT_MS,\n      idle_in_transaction_session_timeout: IDLE_IN_TRANSACTION_TIMEOUT_MS,\n    });\n    const db = createDrizzleDb(pool, schema);\n    const dataPath = createDrizzleDataPath(db, schema, {\n      columnAccess: \"trusted\",\n    });\n    const exports = buildDatabaseExports({\n      schema,\n      getDataPath: () => dataPath,\n      execute,\n      assertActive,\n      // One scope per state keeps concurrent instances from sharing a transaction.\n      scope: createMutationScope(),\n      hooks,\n      transactionBound: false,\n    });\n    // Do not publish exports until an authenticated statement succeeds.\n    await dataPath.raw`select 1`;\n    return {\n      pool,\n      exports,\n      deactivate: () => {\n        active = false;\n      },\n    };\n  } catch (error) {\n    logger.error(\"Database setup failed: %O\", error);\n    active = false;\n    await pool?.end().catch(() => undefined);\n    throw new DatabasePluginError(\"SETUP_FAILED\", \"setup\");\n  }\n}\n"],"mappings":"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"}

package/dist/plugins/database/scope.js

@@ -0,0 +1,58 @@
+import { DatabasePluginError } from "../../database/errors.js";
+import { AsyncLocalStorage } from "node:async_hooks";
+
+//#region src/plugins/database/scope.ts
+/** How deep hook-issued mutations may nest before the guard rejects. */
+const MAX_MUTATION_DEPTH = 8;
+/** Max database operations admitted by one transaction. */
+const MAX_TRANSACTION_OPERATIONS = 100;
+/** Charge one operation to a transaction-owned shared budget. */
+function consumeBudget(state, phase) {
+	const budget = state?.budget ?? { used: 0 };
+	if (budget.used >= MAX_TRANSACTION_OPERATIONS) throw new DatabasePluginError("INTERNAL", phase);
+	budget.used += 1;
+	return budget;
+}
+/**
+* Async context owned by one plugin instance. It carries the transaction,
+* mutation budget, and frames that bound recursion, so neither two instances
+* nor two concurrent calls can observe each other.
+*/
+function createMutationScope() {
+	const storage = new AsyncLocalStorage();
+	return {
+		activeTransaction() {
+			return storage.getStore()?.transaction;
+		},
+		runWithTransaction(transaction, run) {
+			const current = storage.getStore();
+			return storage.run({
+				transaction,
+				frames: current?.frames ?? [],
+				budget: current?.budget ?? { used: 0 }
+			}, run);
+		},
+		consumeTransactionOperation() {
+			const state = storage.getStore();
+			if (state?.transaction) consumeBudget(state, "transaction");
+		},
+		async runMutation(entity, operation, run) {
+			const state = storage.getStore();
+			const frames = state?.frames ?? [];
+			if (frames.some((frame) => frame.entity === entity && frame.operation === operation) || frames.length >= MAX_MUTATION_DEPTH) throw new DatabasePluginError("INTERNAL", "write");
+			const budget = consumeBudget(state, "write");
+			return storage.run({
+				transaction: state?.transaction,
+				frames: [...frames, {
+					entity,
+					operation
+				}],
+				budget
+			}, run);
+		}
+	};
+}
+
+//#endregion
+export { createMutationScope };
+//# sourceMappingURL=scope.js.map

package/dist/plugins/database/scope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope.js","names":[],"sources":["../../../src/plugins/database/scope.ts"],"sourcesContent":["import { AsyncLocalStorage } from \"node:async_hooks\";\n\nimport { DatabasePluginError } from \"../../database/errors\";\nimport type { TransactionClient } from \"./entity-types\";\nimport type { MutationOperation } from \"./hooks\";\n\n/** How deep hook-issued mutations may nest before the guard rejects. */\nconst MAX_MUTATION_DEPTH = 8;\n/** Max database operations admitted by one transaction. */\nexport const MAX_TRANSACTION_OPERATIONS = 100;\n\ninterface MutationFrame {\n  readonly entity: string;\n  readonly operation: MutationOperation;\n}\n\ninterface MutationBudget {\n  used: number;\n}\n\ninterface ScopeState {\n  readonly transaction?: TransactionClient;\n  readonly frames: readonly MutationFrame[];\n  readonly budget: MutationBudget;\n}\n\n/** Charge one operation to a transaction-owned shared budget. */\nfunction consumeBudget(\n  state: ScopeState | undefined,\n  phase: \"transaction\" | \"write\",\n): MutationBudget {\n  const budget = state?.budget ?? { used: 0 };\n  if (budget.used >= MAX_TRANSACTION_OPERATIONS) {\n    throw new DatabasePluginError(\"INTERNAL\", phase);\n  }\n  budget.used += 1;\n  return budget;\n}\n\n/** Instance-owned async context created by `createMutationScope()`. */\nexport type MutationScope = ReturnType<typeof createMutationScope>;\n\n/**\n * Async context owned by one plugin instance. It carries the transaction,\n * mutation budget, and frames that bound recursion, so neither two instances\n * nor two concurrent calls can observe each other.\n */\nexport function createMutationScope() {\n  const storage = new AsyncLocalStorage<ScopeState>();\n\n  return {\n    /** The transaction a hook must join, or `undefined` outside one. */\n    activeTransaction(): TransactionClient | undefined {\n      return storage.getStore()?.transaction;\n    },\n\n    /** Publish one transaction to everything the callback awaits. */\n    runWithTransaction<T>(\n      transaction: TransactionClient,\n      run: () => Promise<T>,\n    ): Promise<T> {\n      const current = storage.getStore();\n      return storage.run(\n        {\n          transaction,\n          frames: current?.frames ?? [],\n          budget: current?.budget ?? { used: 0 },\n        },\n        run,\n      );\n    },\n\n    /** Charge SQL and other direct work bound to the active transaction. */\n    consumeTransactionOperation(): void {\n      const state = storage.getStore();\n      if (state?.transaction) consumeBudget(state, \"transaction\");\n    },\n\n    /** Open one frame, refusing a repeated entity/operation pair or deep nesting. */\n    async runMutation<T>(\n      entity: string,\n      operation: MutationOperation,\n      run: () => Promise<T>,\n    ): Promise<T> {\n      const state = storage.getStore();\n      const frames = state?.frames ?? [];\n      const repeated = frames.some(\n        (frame) => frame.entity === entity && frame.operation === operation,\n      );\n      if (repeated || frames.length >= MAX_MUTATION_DEPTH) {\n        throw new DatabasePluginError(\"INTERNAL\", \"write\");\n      }\n      const budget = consumeBudget(state, \"write\");\n      return storage.run(\n        {\n          transaction: state?.transaction,\n          frames: [...frames, { entity, operation }],\n          budget,\n        },\n        run,\n      );\n    },\n  };\n}\n"],"mappings":";;;;;AAOA,MAAM,qBAAqB;;AAE3B,MAAa,6BAA6B;;AAkB1C,SAAS,cACP,OACA,OACgB;CAChB,MAAM,SAAS,OAAO,UAAU,EAAE,MAAM,GAAG;AAC3C,KAAI,OAAO,QAAQ,2BACjB,OAAM,IAAI,oBAAoB,YAAY,MAAM;AAElD,QAAO,QAAQ;AACf,QAAO;;;;;;;AAWT,SAAgB,sBAAsB;CACpC,MAAM,UAAU,IAAI,mBAA+B;AAEnD,QAAO;EAEL,oBAAmD;AACjD,UAAO,QAAQ,UAAU,EAAE;;EAI7B,mBACE,aACA,KACY;GACZ,MAAM,UAAU,QAAQ,UAAU;AAClC,UAAO,QAAQ,IACb;IACE;IACA,QAAQ,SAAS,UAAU,EAAE;IAC7B,QAAQ,SAAS,UAAU,EAAE,MAAM,GAAG;IACvC,EACD,IACD;;EAIH,8BAAoC;GAClC,MAAM,QAAQ,QAAQ,UAAU;AAChC,OAAI,OAAO,YAAa,eAAc,OAAO,cAAc;;EAI7D,MAAM,YACJ,QACA,WACA,KACY;GACZ,MAAM,QAAQ,QAAQ,UAAU;GAChC,MAAM,SAAS,OAAO,UAAU,EAAE;AAIlC,OAHiB,OAAO,MACrB,UAAU,MAAM,WAAW,UAAU,MAAM,cAAc,UAC3D,IACe,OAAO,UAAU,mBAC/B,OAAM,IAAI,oBAAoB,YAAY,QAAQ;GAEpD,MAAM,SAAS,cAAc,OAAO,QAAQ;AAC5C,UAAO,QAAQ,IACb;IACE,aAAa,OAAO;IACpB,QAAQ,CAAC,GAAG,QAAQ;KAAE;KAAQ;KAAW,CAAC;IAC1C;IACD,EACD,IACD;;EAEJ"}