@databricks/appkit 0.72.0 → 0.73.0

package/CLAUDE.md

@@ -48,6 +48,7 @@ npx @databricks/appkit docs <query>
 - [Analytics plugin](./docs/plugins/analytics.md): Enables SQL query execution against Databricks SQL Warehouses.
 - [Caching](./docs/plugins/caching.md): AppKit provides both global and plugin-level caching capabilities.
 - [Creating custom plugins](./docs/plugins/custom-plugins.md): If you need custom API routes or background logic, implement an AppKit plugin. The fastest way is to use the CLI:
+- [Database plugin](./docs/plugins/database.md): This plugin is currently beta. APIs may change between minor releases. Import from @databricks/appkit/beta. See Plugin Stability Tiers.
 - [Execution context](./docs/plugins/execution-context.md): AppKit manages Databricks authentication via two contexts:
 - [Files plugin](./docs/plugins/files.md): File operations against Databricks Unity Catalog Volumes. Supports listing, reading, downloading, uploading, deleting, and previewing files with built-in caching, retry, and timeout handling via the execution interceptor pipeline.
 - [Genie plugin](./docs/plugins/genie.md): Integrates Databricks AI/BI Genie spaces into your AppKit application, enabling natural language data queries via a conversational interface.
@@ -68,6 +69,7 @@ npx @databricks/appkit docs <query>
 - [Class: AuthenticationError](./docs/api/appkit/Class.AuthenticationError.md): Error thrown when authentication fails.
 - [Class: ConfigurationError](./docs/api/appkit/Class.ConfigurationError.md): Error thrown when configuration is missing or invalid.
 - [Class: ConnectionError](./docs/api/appkit/Class.ConnectionError.md): Error thrown when a connection or network operation fails.
+- [Class: DatabaseValidationError](./docs/api/appkit/Class.DatabaseValidationError.md): Deliberate validation failure raised by a database mutation hook. Generated
 - [Class: DatabricksAdapter](./docs/api/appkit/Class.DatabricksAdapter.md): Adapter that talks directly to Databricks Model Serving /invocations endpoint.
 - [Class: ExecutionError](./docs/api/appkit/Class.ExecutionError.md): Error thrown when an operation execution fails.
 - [Class: InitializationError](./docs/api/appkit/Class.InitializationError.md): Error thrown when a service or component is not properly initialized.
@@ -138,9 +140,11 @@ npx @databricks/appkit docs <query>
 - [Function: mcpServer()](./docs/api/appkit/Function.mcpServer.md): Factory for declaring a custom MCP server tool.
 - [Function: normalizeHost()](./docs/api/appkit/Function.normalizeHost.md): Ensure the host has a scheme (Databricks env often lacks https://).
 - [Function: parseTextToolCalls()](./docs/api/appkit/Function.parseTextToolCalls.md): Parses text-based tool calls from model output.
+- [Function: readEvalDataset()](./docs/api/appkit/Function.readEvalDataset.md): Read a Databricks managed evaluation dataset (a Unity Catalog table with
 - [Function: reportToMlflow()](./docs/api/appkit/Function.reportToMlflow.md): Write one pass/fail assessment per eval result to the Databricks MLflow REST
 - [Function: resolveDatabricksAuth()](./docs/api/appkit/Function.resolveDatabricksAuth.md): Parameters
 - [Function: resolveHostedTools()](./docs/api/appkit/Function.resolveHostedTools.md): Parameters
+- [Function: resolveWorkspaceClient()](./docs/api/appkit/Function.resolveWorkspaceClient.md): Construct a Databricks WorkspaceClient for the eval runner — the object the
 - [Function: runAgent()](./docs/api/appkit/Function.runAgent.md): Standalone agent execution without createApp. Resolves the adapter, binds
 - [Function: runEval()](./docs/api/appkit/Function.runEval.md): Run a single eval against a driver. Never throws for assertion or agent
 - [Function: runEvalsInDir()](./docs/api/appkit/Function.runEvalsInDir.md): Discover, load, and run every eval under each agent's evals/ dir, driving
@@ -166,10 +170,13 @@ npx @databricks/appkit docs <query>
 - [Interface: CustomJudgeSpec](./docs/api/appkit/Interface.CustomJudgeSpec.md): A custom LLM-judge definition: a prompt template and choice→score mapping.
 - [Interface: DatabaseCredential](./docs/api/appkit/Interface.DatabaseCredential.md): Database credentials with OAuth token for Postgres connection
 - [Interface: DatabaseRegistry](./docs/api/appkit/Interface.DatabaseRegistry.md): CANONICAL augmentation target. Empty by default; the generated database.d.ts
+- [Interface: DatabaseValidationIssue](./docs/api/appkit/Interface.DatabaseValidationIssue.md): One rejected field; path names public columns, never their values.
 - [Interface: DatabricksAuth](./docs/api/appkit/Interface.DatabricksAuth.md): Resolved Databricks host + bearer token for the eval runner's REST calls.
+- [Interface: DatasetRow](./docs/api/appkit/Interface.DatasetRow.md): One row of a managed evaluation dataset. inputs are the kwargs passed to the
 - [Interface: DiscoveredEval](./docs/api/appkit/Interface.DiscoveredEval.md): An eval file found under server/agents//evals/.
 - [Interface: DriveResult](./docs/api/appkit/Interface.DriveResult.md): What a driver returns for a single t.send.
 - [Interface: EndpointConfig](./docs/api/appkit/Interface.EndpointConfig.md): Properties
+- [Interface: EntityMutationHooks<TTable>](./docs/api/appkit/Interface.EntityMutationHooks.md): Mutation lifecycle for one entity. A before hook may return a replacement
 - [Interface: EvalDefinition](./docs/api/appkit/Interface.EvalDefinition.md): A single eval, default-exported from a *.eval.ts file.
 - [Interface: EvalDriver](./docs/api/appkit/Interface.EvalDriver.md): Abstraction over how the agent is driven. The HTTP driver posts to a running
 - [Interface: EvalResult](./docs/api/appkit/Interface.EvalResult.md): The outcome of running one eval.
@@ -180,6 +187,8 @@ npx @databricks/appkit docs <query>
 - [Interface: FunctionTool](./docs/api/appkit/Interface.FunctionTool.md): Properties
 - [Interface: GenerateDatabaseCredentialRequest](./docs/api/appkit/Interface.GenerateDatabaseCredentialRequest.md): Request parameters for generating database OAuth credentials
 - [Interface: GenerationParams](./docs/api/appkit/Interface.GenerationParams.md): Optional generation parameters forwarded to the OpenAI-compatible serving
+- [Interface: HookApp](./docs/api/appkit/Interface.HookApp.md): The only capability a hook receives: entities bound to its transaction.
+- [Interface: HookContext](./docs/api/appkit/Interface.HookContext.md): Which entity is being mutated, and the surface a hook may write through.
 - [Interface: HostedSupervisorTool](./docs/api/appkit/Interface.HostedSupervisorTool.md): Tagged record returned by every supervisorTools factory. The
 - [Interface: HttpDriverOptions](./docs/api/appkit/Interface.HttpDriverOptions.md): Properties
 - [Interface: IAiSearchConfig](./docs/api/appkit/Interface.IAiSearchConfig.md): Base configuration interface for AppKit plugins
@@ -201,6 +210,8 @@ npx @databricks/appkit docs <query>
 - [Interface: PluginToolkitProvider](./docs/api/appkit/Interface.PluginToolkitProvider.md): Minimum shape every entry in the Plugins map must expose. Core
 - [Interface: PostResult](./docs/api/appkit/Interface.PostResult.md): Structured result for a best-effort POST that must not throw.
 - [Interface: PromptContext](./docs/api/appkit/Interface.PromptContext.md): Context passed to baseSystemPrompt callbacks.
+- [Interface: ReadEvalDatasetOptions](./docs/api/appkit/Interface.ReadEvalDatasetOptions.md): Properties
+- [Interface: ReadSerializerContext](./docs/api/appkit/Interface.ReadSerializerContext.md): Which entity and generated operation produced the row being shaped.
 - [Interface: RegisteredAgent](./docs/api/appkit/Interface.RegisteredAgent.md): Properties
 - [Interface: ReportOutcome](./docs/api/appkit/Interface.ReportOutcome.md): Properties
 - [Interface: RequestedClaims](./docs/api/appkit/Interface.RequestedClaims.md): Optional claims for fine-grained Unity Catalog table permissions
@@ -242,7 +253,11 @@ npx @databricks/appkit docs <query>
 - [Type Alias: AgentToolsFn()](./docs/api/appkit/TypeAlias.AgentToolsFn.md): Function form of AgentDefinition.tools. Receives the typed
 - [Type Alias: BaseSystemPromptOption](./docs/api/appkit/TypeAlias.BaseSystemPromptOption.md)
 - [Type Alias: ConfigSchema](./docs/api/appkit/TypeAlias.ConfigSchema.md): Configuration schema definition for plugin config.
+- [Type Alias: DatabaseApiConfig<TSchema>](./docs/api/appkit/TypeAlias.DatabaseApiConfig.md): Full generated CRUD for every declared table by default. Set false to disable
+- [Type Alias: DatabaseApiWriteOperation](./docs/api/appkit/TypeAlias.DatabaseApiWriteOperation.md): Generated HTTP write operations.
+- [Type Alias: DatabaseApiWritesConfig<TSchema>](./docs/api/appkit/TypeAlias.DatabaseApiWritesConfig.md): All writes by default; false keeps reads only, and an object narrows writes.
 - [Type Alias: DatabaseExports](./docs/api/appkit/TypeAlias.DatabaseExports.md): Typed database API published by the plugin.
+- [Type Alias: EntityHooks<TTable>](./docs/api/appkit/TypeAlias.EntityHooks.md): Response shaping and mutation lifecycle declared for one table.
 - [Type Alias: EvalProgress](./docs/api/appkit/TypeAlias.EvalProgress.md)
 - [Type Alias: ExecutionResult<T>](./docs/api/appkit/TypeAlias.ExecutionResult.md): Discriminated union for plugin execution results.
 - [Type Alias: FileAction](./docs/api/appkit/TypeAlias.FileAction.md): Every action the files plugin can perform.
@@ -254,6 +269,7 @@ npx @databricks/appkit docs <query>
 - [Type Alias: Matcher()](./docs/api/appkit/TypeAlias.Matcher.md): A deterministic matcher: inspects a string value and returns a result.
 - [Type Alias: PluginData<T, U, N>](./docs/api/appkit/TypeAlias.PluginData.md): Tuple of plugin class, config, and name. Created by toPlugin() and passed to createApp().
 - [Type Alias: Plugins](./docs/api/appkit/TypeAlias.Plugins.md): Plugin map passed to the function form of AgentDefinition.tools.
+- [Type Alias: ReadSerializer()](./docs/api/appkit/TypeAlias.ReadSerializer.md): Shape one already private-safe row before it reaches the wire. A Promise
 - [Type Alias: ResolvedToolEntry](./docs/api/appkit/TypeAlias.ResolvedToolEntry.md): Internal tool-index entry after a tool record has been resolved to a dispatchable form.
 - [Type Alias: ResourceFieldEntry](./docs/api/appkit/TypeAlias.ResourceFieldEntry.md)
 - [Type Alias: ResourcePermission](./docs/api/appkit/TypeAlias.ResourcePermission.md): Union of all possible permission levels across all resource types.
@@ -263,6 +279,7 @@ npx @databricks/appkit docs <query>
 - [Type Alias: SupervisorTool](./docs/api/appkit/TypeAlias.SupervisorTool.md): Tools supported by the Databricks AI Gateway Responses API. The shapes match
 - [Type Alias: ToolRegistry](./docs/api/appkit/TypeAlias.ToolRegistry.md)
 - [Type Alias: ToPlugin()<T, U, N>](./docs/api/appkit/TypeAlias.ToPlugin.md): Factory function type returned by toPlugin(). Accepts optional config and returns a PluginData tuple.
+- [Type Alias: TransactionClient](./docs/api/appkit/TypeAlias.TransactionClient.md): Entity and SQL capabilities bound to one transaction.
 - [Variable: agents](./docs/api/appkit/Variable.agents.md): Plugin factory for the agents plugin. Discovers agents from
 - [Variable: aiSearch](./docs/api/appkit/Variable.aiSearch.md)
 - [Variable: READ_ACTIONS](./docs/api/appkit/Variable.READ_ACTIONS.md): Actions that only read data.

package/NOTICE.md

@@ -54,6 +54,7 @@ This Software contains code from the following open source projects:
 | [@tanstack/react-table](https://www.npmjs.com/package/@tanstack/react-table) | 8.21.3 | MIT | https://tanstack.com/table |
 | [@types/semver](https://www.npmjs.com/package/@types/semver) | 7.7.1 | MIT | https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/semver |
 | [apache-arrow](https://www.npmjs.com/package/apache-arrow) | 21.1.0 | Apache-2.0 | https://arrow.apache.org/js/ |
+| [autoevals](https://www.npmjs.com/package/autoevals) | 0.3.0 | MIT | https://www.braintrust.dev/docs |
 | [class-variance-authority](https://www.npmjs.com/package/class-variance-authority) | 0.7.1 | Apache-2.0 | https://github.com/joe-bell/cva#readme |
 | [clsx](https://www.npmjs.com/package/clsx) | 2.1.1 | MIT | https://github.com/lukeed/clsx#readme |
 | [cmdk](https://www.npmjs.com/package/cmdk) | 1.1.1 | MIT | https://github.com/pacocoursey/cmdk#readme |

package/dist/appkit/package.js

@@ -1,6 +1,6 @@
 //#region package.json
 var name = "@databricks/appkit";
-var version = "0.72.0";
+var version = "0.73.0";
 
 //#endregion
 export { name, version };

package/dist/beta.d.ts

@@ -15,8 +15,9 @@ import { Schema } from "./database/schema-builder/types.js";
 import { bigid, bigint, boolean, enumColumn, id, integer, jsonb, text, timestamp, uuid, varchar } from "./database/schema-builder/columns.js";
 import { defineSchema } from "./database/schema-builder/define-schema.js";
 import { fk } from "./database/schema-builder/fk.js";
-import { DatabricksAuth, ResolveDatabricksAuthOptions, resolveDatabricksAuth } from "./connectors/mlflow/auth.js";
+import { DatabricksAuth, ResolveDatabricksAuthOptions, resolveDatabricksAuth, resolveWorkspaceClient } from "./connectors/mlflow/auth.js";
 import { MlflowClient, PostResult, normalizeHost } from "./connectors/mlflow/client.js";
+import { DatasetRow, ReadEvalDatasetOptions, readEvalDataset } from "./evals/dataset.js";
 import { AssertionHandle, AssertionResult, CustomJudgeSpec, DriveResult, EvalDefinition, EvalDriver, EvalResult, MatchResult, Matcher, Severity, TestContext } from "./evals/types.js";
 import { defineEval } from "./evals/define-eval.js";
 import { DiscoveredEval, discoverEvalFiles } from "./evals/discover.js";
@@ -27,14 +28,16 @@ import { Assessment, ReportOutcome, buildAssessments, reportToMlflow } from "./e
 import { EvalSummary, evalGlyph, formatEvalDetail, formatEvalHeadline, formatEvalResults, formatSummaryLine, summarize } from "./evals/report.js";
 import { RunEvalOptions, runEval } from "./evals/run-eval.js";
 import { EvalProgress, EvalRunSummary, RunEvalsOptions, runEvalsInDir } from "./evals/run-evals.js";
+import "./evals/index.js";
 import { agentIdFromMarkdownPath, loadAgentFromFile, loadAgentsFromDir } from "./core/agent/load-agents.js";
 import { agents } from "./plugins/agents/agents.js";
 import "./plugins/agents/index.js";
 import { IAiSearchConfig, IndexConfig, RerankerConfig, SearchFilters, SearchRequest, SearchResponse, SearchResult } from "./plugins/ai-search/types.js";
 import { aiSearch } from "./plugins/ai-search/ai-search.js";
-import { DatabaseExports } from "./plugins/database/entity-types.js";
-import { IDatabaseConfig } from "./plugins/database/types.js";
+import { DatabaseExports, TransactionClient } from "./plugins/database/entity-types.js";
+import { EntityMutationHooks, HookApp, HookContext } from "./plugins/database/hooks.js";
+import { DatabaseApiConfig, DatabaseApiWriteOperation, DatabaseApiWritesConfig, EntityHooks, IDatabaseConfig, ReadSerializer, ReadSerializerContext } from "./plugins/database/types.js";
 import { database } from "./plugins/database/database.js";
 import "./plugins/database/index.js";
 import "./plugins/beta-exports.generated.js";
-export { type AgentAdapter, type AgentDefinition, type AgentEvent, type AgentInput, type AgentRunContext, type AgentTool, type AgentToolDefinition, type AgentTools, type AgentToolsFn, type AgentsPluginConfig, AppKitMcpClient, AssertionHandle, AssertionResult, Assessment, type AutoInheritToolsConfig, type BaseSystemPromptOption, CustomJudgeSpec, type DatabaseExports, DatabricksAdapter, DatabricksAuth, DiscoveredEval, DriveResult, EvalDefinition, EvalDriver, EvalProgress, EvalResult, EvalRunSummary, EvalSummary, type FunctionTool, type GenerationParams, type HostedSupervisorTool, type HostedTool, HttpDriverOptions, type IAiSearchConfig, type IDatabaseConfig, type IndexConfig, JudgeConfig, JudgeScore, MatchResult, Matcher, type McpConnectAllResult, type Message, MlflowClient, type PluginToolkitProvider, type Plugins, PostResult, type PromptContext, type RegisteredAgent, ReportOutcome, type RerankerConfig, ResolveDatabricksAuthOptions, type ResolvedToolEntry, type RunAgentInput, type RunAgentResult, RunEvalOptions, RunEvalsOptions, SUPERVISOR_EXTENSION_KEY, type Schema, type SearchFilters, type SearchRequest, type SearchResponse, type SearchResult, Severity, SupervisorApiAdapter, type SupervisorApiAdapterOptions, type SupervisorExtension, type SupervisorTool, TestContext, type Thread, type ThreadStore, type ToolAnnotations, type ToolConfig, type ToolEntry, type ToolProvider, type ToolRegistry, type ToolkitEntry, type ToolkitOptions, type WorkspaceClientLike, agentIdFromMarkdownPath, agents, aiSearch, bigid, bigint, boolean, buildAssessments, configureJudge, createAgent, createHttpDriver, database, defineEval, defineSchema, defineTool, discoverEvalFiles, enumColumn, equals, evalGlyph, executeFromRegistry, fk, formatEvalDetail, formatEvalHeadline, formatEvalResults, formatSummaryLine, fromSupervisorApi, functionToolToDefinition, id, includes, integer, isFunctionTool, isHostedTool, isJudgeConfigured, isSupervisorTool, isToolkitEntry, jsonb, loadAgentFromFile, loadAgentsFromDir, matches, mcpServer, normalizeHost, parseTextToolCalls, reportToMlflow, resolveDatabricksAuth, resolveHostedTools, runAgent, runEval, runEvalsInDir, summarize, supervisorTools, text, timestamp, tool, toolsFromRegistry, uuid, varchar };
+export { type AgentAdapter, type AgentDefinition, type AgentEvent, type AgentInput, type AgentRunContext, type AgentTool, type AgentToolDefinition, type AgentTools, type AgentToolsFn, type AgentsPluginConfig, AppKitMcpClient, AssertionHandle, AssertionResult, Assessment, type AutoInheritToolsConfig, type BaseSystemPromptOption, CustomJudgeSpec, type DatabaseApiConfig, type DatabaseApiWriteOperation, type DatabaseApiWritesConfig, type DatabaseExports, DatabricksAdapter, DatabricksAuth, DatasetRow, DiscoveredEval, DriveResult, type EntityHooks, type EntityMutationHooks, EvalDefinition, EvalDriver, EvalProgress, EvalResult, EvalRunSummary, EvalSummary, type FunctionTool, type GenerationParams, type HookApp, type HookContext, type HostedSupervisorTool, type HostedTool, HttpDriverOptions, type IAiSearchConfig, type IDatabaseConfig, type IndexConfig, JudgeConfig, JudgeScore, MatchResult, Matcher, type McpConnectAllResult, type Message, MlflowClient, type PluginToolkitProvider, type Plugins, PostResult, type PromptContext, ReadEvalDatasetOptions, type ReadSerializer, type ReadSerializerContext, type RegisteredAgent, ReportOutcome, type RerankerConfig, ResolveDatabricksAuthOptions, type ResolvedToolEntry, type RunAgentInput, type RunAgentResult, RunEvalOptions, RunEvalsOptions, SUPERVISOR_EXTENSION_KEY, type Schema, type SearchFilters, type SearchRequest, type SearchResponse, type SearchResult, Severity, SupervisorApiAdapter, type SupervisorApiAdapterOptions, type SupervisorExtension, type SupervisorTool, TestContext, type Thread, type ThreadStore, type ToolAnnotations, type ToolConfig, type ToolEntry, type ToolProvider, type ToolRegistry, type ToolkitEntry, type ToolkitOptions, type TransactionClient, type WorkspaceClientLike, agentIdFromMarkdownPath, agents, aiSearch, bigid, bigint, boolean, buildAssessments, configureJudge, createAgent, createHttpDriver, database, defineEval, defineSchema, defineTool, discoverEvalFiles, enumColumn, equals, evalGlyph, executeFromRegistry, fk, formatEvalDetail, formatEvalHeadline, formatEvalResults, formatSummaryLine, fromSupervisorApi, functionToolToDefinition, id, includes, integer, isFunctionTool, isHostedTool, isJudgeConfigured, isSupervisorTool, isToolkitEntry, jsonb, loadAgentFromFile, loadAgentsFromDir, matches, mcpServer, normalizeHost, parseTextToolCalls, readEvalDataset, reportToMlflow, resolveDatabricksAuth, resolveHostedTools, resolveWorkspaceClient, runAgent, runEval, runEvalsInDir, summarize, supervisorTools, text, timestamp, tool, toolsFromRegistry, uuid, varchar };

package/dist/beta.js

@@ -1,5 +1,5 @@
 import { AppKitMcpClient } from "./connectors/mcp/client.js";
-import { resolveDatabricksAuth } from "./connectors/mlflow/auth.js";
+import { resolveDatabricksAuth, resolveWorkspaceClient } from "./connectors/mlflow/auth.js";
 import { MlflowClient, normalizeHost } from "./connectors/mlflow/client.js";
 import { tool } from "./core/agent/tools/tool.js";
 import { defineTool, executeFromRegistry, toolsFromRegistry } from "./core/agent/tools/define-tool.js";
@@ -15,6 +15,7 @@ import { isToolkitEntry } from "./core/agent/types.js";
 import { runAgent } from "./core/agent/run-agent.js";
 import "./core/agent/tools/index.js";
 import "./database/schema-builder/index.js";
+import { readEvalDataset } from "./evals/dataset.js";
 import { defineEval } from "./evals/define-eval.js";
 import { discoverEvalFiles } from "./evals/discover.js";
 import { createHttpDriver } from "./evals/http-driver.js";
@@ -32,4 +33,4 @@ import { aiSearch } from "./plugins/ai-search/ai-search.js";
 import { database } from "./plugins/database/database.js";
 import "./plugins/beta-exports.generated.js";
 
-export { AppKitMcpClient, DatabricksAdapter, MlflowClient, SUPERVISOR_EXTENSION_KEY, SupervisorApiAdapter, agentIdFromMarkdownPath, agents, aiSearch, bigid, bigint, boolean, buildAssessments, configureJudge, createAgent, createHttpDriver, database, defineEval, defineSchema, defineTool, discoverEvalFiles, enumColumn, equals, evalGlyph, executeFromRegistry, fk, formatEvalDetail, formatEvalHeadline, formatEvalResults, formatSummaryLine, fromSupervisorApi, functionToolToDefinition, id, includes, integer, isFunctionTool, isHostedTool, isJudgeConfigured, isSupervisorTool, isToolkitEntry, jsonb, loadAgentFromFile, loadAgentsFromDir, matches, mcpServer, normalizeHost, parseTextToolCalls, reportToMlflow, resolveDatabricksAuth, resolveHostedTools, runAgent, runEval, runEvalsInDir, summarize, supervisorTools, text, timestamp, tool, toolsFromRegistry, uuid, varchar };
+export { AppKitMcpClient, DatabricksAdapter, MlflowClient, SUPERVISOR_EXTENSION_KEY, SupervisorApiAdapter, agentIdFromMarkdownPath, agents, aiSearch, bigid, bigint, boolean, buildAssessments, configureJudge, createAgent, createHttpDriver, database, defineEval, defineSchema, defineTool, discoverEvalFiles, enumColumn, equals, evalGlyph, executeFromRegistry, fk, formatEvalDetail, formatEvalHeadline, formatEvalResults, formatSummaryLine, fromSupervisorApi, functionToolToDefinition, id, includes, integer, isFunctionTool, isHostedTool, isJudgeConfigured, isSupervisorTool, isToolkitEntry, jsonb, loadAgentFromFile, loadAgentsFromDir, matches, mcpServer, normalizeHost, parseTextToolCalls, readEvalDataset, reportToMlflow, resolveDatabricksAuth, resolveHostedTools, resolveWorkspaceClient, runAgent, runEval, runEvalsInDir, summarize, supervisorTools, text, timestamp, tool, toolsFromRegistry, uuid, varchar };

package/dist/cli/commands/agent/eval.js

@@ -82,6 +82,12 @@ async function runAgentEval(filter, opts) {
 		host: opts.databricksHost ?? process.env.DATABRICKS_HOST,
 		token: opts.databricksToken ?? process.env.DATABRICKS_TOKEN
 	}) ?? {};
+	const warehouseId = opts.warehouseId ?? process.env.DATABRICKS_WAREHOUSE_ID;
+	const workspaceClient = runner.resolveWorkspaceClient({
+		profile: opts.profile ?? process.env.DATABRICKS_CONFIG_PROFILE,
+		host: opts.databricksHost ?? process.env.DATABRICKS_HOST,
+		token: opts.databricksToken ?? process.env.DATABRICKS_TOKEN
+	});
 	let summary;
 	try {
 		summary = await runner.runEvalsInDir({
@@ -93,6 +99,8 @@ async function runAgentEval(filter, opts) {
 			concurrency: opts.concurrency,
 			mlflow: resolveMlflow(opts, auth),
 			judge: resolveJudge(opts, auth),
+			workspaceClient,
+			warehouseId,
 			onEvent: makeProgressReporter(runner, opts.url)
 		});
 	} catch (err) {
@@ -105,7 +113,7 @@ async function runAgentEval(filter, opts) {
 	else console.log("\nMLflow evaluation run skipped — pass --experiment (or set MLFLOW_EXPERIMENT_ID) plus --profile/--databricks-host to create one.");
 	if (!runner.summarize(summary.results).allPassed) process.exitCode = 1;
 }
-const agentEvalCommand = new Command("eval").description("Run agent evals (server/agents/<id>/evals/*.eval.ts) against a running app").argument("[filter]", "Only run evals whose <agent>/<id> contains this substring (or an exact agent id)").option("--url <url>", "Base URL of the running app", "http://localhost:3000").option("--strict", "Fail on soft-assertion misses too", false).option("--concurrency <n>", "Max evals to run concurrently (default 4; keep at or below the app's max concurrent streams per user)", (v) => Number.parseInt(v, 10)).option("--root <dir>", "Project root containing server/agents/ (default: cwd)").option("--header <header...>", "Extra request header as 'Key: value' (repeatable)").option("--profile <name>", "Databricks CLI profile to authenticate with via OAuth (default: DATABRICKS_CONFIG_PROFILE)").option("--databricks-host <host>", "Databricks host for writing MLflow assessments (default: DATABRICKS_HOST)").option("--databricks-token <token>", "Databricks token for writing MLflow assessments (default: DATABRICKS_TOKEN)").option("--experiment <id>", "MLflow experiment id for the evaluation run (default: MLFLOW_EXPERIMENT_ID)").option("--warehouse-id <id>", "SQL warehouse id for writing assessments to UC-backed experiments (default: MLFLOW_TRACING_SQL_WAREHOUSE_ID or DATABRICKS_WAREHOUSE_ID)").option("--judge-model <endpoint>", "Databricks serving endpoint to use as the LLM judge for t.judge.* (default: APPKIT_JUDGE_MODEL)").action(runAgentEval);
+const agentEvalCommand = new Command("eval").description("Run agent evals (server/agents/<id>/evals/*.eval.ts) against a running app").argument("[filter]", "Only run evals whose <agent>/<id> contains this substring (or an exact agent id)").option("--url <url>", "Base URL of the running app", "http://localhost:3000").option("--strict", "Fail on soft-assertion misses too", false).option("--concurrency <n>", "Max evals to run concurrently (default 4; keep at or below the app's max concurrent streams per user)", (v) => Number.parseInt(v, 10)).option("--root <dir>", "Project root containing server/agents/ (default: cwd)").option("--header <header...>", "Extra request header as 'Key: value' (repeatable)").option("--profile <name>", "Databricks CLI profile to authenticate with via OAuth (default: DATABRICKS_CONFIG_PROFILE)").option("--databricks-host <host>", "Databricks host for writing MLflow assessments (default: DATABRICKS_HOST)").option("--databricks-token <token>", "Databricks token for writing MLflow assessments (default: DATABRICKS_TOKEN)").option("--experiment <id>", "MLflow experiment id for the evaluation run (default: MLFLOW_EXPERIMENT_ID)").option("--warehouse-id <id>", "SQL warehouse id for reading managed eval datasets and writing assessments to UC-backed experiments (default: DATABRICKS_WAREHOUSE_ID, or MLFLOW_TRACING_SQL_WAREHOUSE_ID for assessments)").option("--judge-model <endpoint>", "Databricks serving endpoint to use as the LLM judge for t.judge.* (default: APPKIT_JUDGE_MODEL)").action(runAgentEval);
 
 //#endregion
 export { agentEvalCommand };

package/dist/cli/commands/agent/eval.js.map

@@ -1 +1 @@
-{"version":3,"file":"eval.js","names":[],"sources":["../../../../src/cli/commands/agent/eval.ts"],"sourcesContent":["import { Command } from \"commander\";\n\ninterface EvalRunSummary {\n  results: unknown[];\n  mlflow?: {\n    runId: string;\n    report: {\n      written: number;\n      skipped: number;\n      failures: Array<{ traceId: string; status?: number; error?: string }>;\n    };\n    finish: { finished: boolean; metricsError?: string; finishError?: string };\n  };\n}\n\ntype EvalProgress =\n  | { type: \"discovered\"; total: number }\n  | { type: \"run-created\"; runId: string }\n  | { type: \"start\"; id: string; index: number; total: number }\n  | { type: \"result\"; result: unknown; index: number; total: number };\n\n/** Subset of `@databricks/appkit/beta`'s eval runner used by this command. */\ninterface EvalRunner {\n  runEvalsInDir(opts: {\n    rootDir?: string;\n    baseUrl: string;\n    filter?: string;\n    strict?: boolean;\n    headers?: Record<string, string>;\n    concurrency?: number;\n    mlflow?: {\n      host: string;\n      token: string;\n      experimentId: string;\n      sqlWarehouseId?: string;\n    };\n    judge?: { host: string; token: string; model: string };\n    onEvent?: (event: EvalProgress) => void;\n  }): Promise<EvalRunSummary>;\n  resolveDatabricksAuth(opts: {\n    profile?: string;\n    host?: string;\n    token?: string;\n  }): Promise<{ host: string; token: string } | undefined>;\n  formatEvalHeadline(result: unknown): string;\n  formatEvalDetail(result: unknown): string[];\n  formatSummaryLine(results: unknown[]): string;\n  summarize(results: unknown[]): { allPassed: boolean };\n}\n\n/**\n * Loaded at runtime from the consuming project so this command (which ships in\n * `@databricks/shared`) doesn't take a build-time dependency on appkit. The\n * specifier is a variable so the type checker treats it as `any`.\n */\nasync function loadRunner(): Promise<EvalRunner> {\n  const spec = \"@databricks/appkit/beta\";\n  try {\n    return (await import(spec)) as unknown as EvalRunner;\n  } catch (err) {\n    throw new Error(\n      \"Could not load @databricks/appkit. Run `appkit agent eval` from a \" +\n        \"project with @databricks/appkit installed. \" +\n        `Cause: ${err instanceof Error ? err.message : String(err)}`,\n    );\n  }\n}\n\nfunction parseHeaders(values: string[]): Record<string, string> {\n  const headers: Record<string, string> = {};\n  for (const v of values) {\n    const i = v.indexOf(\":\");\n    if (i === -1) continue;\n    headers[v.slice(0, i).trim()] = v.slice(i + 1).trim();\n  }\n  return headers;\n}\n\ninterface EvalOptions {\n  url: string;\n  strict?: boolean;\n  root?: string;\n  header?: string[];\n  profile?: string;\n  databricksHost?: string;\n  databricksToken?: string;\n  experiment?: string;\n  judgeModel?: string;\n  concurrency?: number;\n  warehouseId?: string;\n}\n\n/** Resolved Databricks host + bearer (either field may be absent). */\ntype Auth = { host?: string; token?: string };\n\n/**\n * Native MLflow \"Evaluation run\" config — only when creds + an experiment are\n * all present (traces live in the app; the run + scores are driven from here).\n */\nfunction resolveMlflow(opts: EvalOptions, auth: Auth) {\n  const experimentId = opts.experiment ?? process.env.MLFLOW_EXPERIMENT_ID;\n  if (!(auth.host && auth.token && experimentId)) return undefined;\n  // UC-backed experiments need a SQL warehouse to write assessments to their\n  // V4 traces. Mirror mlflow's env var, and accept the common DATABRICKS one.\n  const sqlWarehouseId =\n    opts.warehouseId ??\n    process.env.MLFLOW_TRACING_SQL_WAREHOUSE_ID ??\n    process.env.DATABRICKS_WAREHOUSE_ID;\n  return {\n    host: auth.host,\n    token: auth.token,\n    experimentId,\n    ...(sqlWarehouseId ? { sqlWarehouseId } : {}),\n  };\n}\n\n/** LLM-as-judge config — reuses the Databricks creds + a judge serving endpoint. */\nfunction resolveJudge(opts: EvalOptions, auth: Auth) {\n  const model = opts.judgeModel ?? process.env.APPKIT_JUDGE_MODEL;\n  return model && auth.host && auth.token\n    ? { host: auth.host, token: auth.token, model }\n    : undefined;\n}\n\n/** Progress reporter: stream each eval as it runs instead of going silent. */\nfunction makeProgressReporter(\n  runner: EvalRunner,\n  url: string,\n): (event: EvalProgress) => void {\n  return (event) => {\n    switch (event.type) {\n      case \"discovered\":\n        console.log(\n          `Running ${event.total} eval${event.total === 1 ? \"\" : \"s\"} against ${url}\\n`,\n        );\n        break;\n      case \"run-created\":\n        console.log(`MLflow evaluation run: ${event.runId}\\n`);\n        break;\n      case \"result\": {\n        // One full line per completion — evals run concurrently, so a split\n        // \"start … glyph\" prefix would interleave into garbage.\n        console.log(\n          `[${event.index + 1}/${event.total}] ${runner.formatEvalHeadline(event.result)}`,\n        );\n        for (const line of runner.formatEvalDetail(event.result)) {\n          console.log(line);\n        }\n        break;\n      }\n    }\n  };\n}\n\nfunction formatFailureLine(f: {\n  traceId: string;\n  status?: number;\n  error?: string;\n}): string {\n  return `  ✗ trace ${f.traceId}: ${f.status ?? \"\"} ${f.error ?? \"\"}`.trim();\n}\n\n/** Print the MLflow assessment/finish outcome after a run that created one. */\nfunction printMlflowOutcome(\n  mlflow: NonNullable<EvalRunSummary[\"mlflow\"]>,\n): void {\n  const { report, finish } = mlflow;\n  console.log(\n    `MLflow: ${report.written} assessment(s) written` +\n      (report.skipped ? `, ${report.skipped} skipped` : \"\") +\n      (report.failures.length ? `, ${report.failures.length} failed` : \"\"),\n  );\n  for (const f of report.failures) {\n    console.error(formatFailureLine(f));\n  }\n  if (finish.metricsError) {\n    console.error(`  ⚠ metrics not logged: ${finish.metricsError}`);\n  }\n  if (!finish.finished) {\n    console.error(\n      `  ✗ run left RUNNING — failed to finish: ${finish.finishError ?? \"unknown\"}`,\n    );\n  }\n}\n\nasync function runAgentEval(\n  filter: string | undefined,\n  opts: EvalOptions,\n): Promise<void> {\n  const runner = await loadRunner();\n\n  // Resolve Databricks host + bearer the AppKit-native way: an explicit\n  // host/token (or DATABRICKS_* env) wins; otherwise the SDK mints an OAuth\n  // token from the CLI profile — so no hand-set PAT is required.\n  const auth: Auth =\n    (await runner.resolveDatabricksAuth({\n      profile: opts.profile ?? process.env.DATABRICKS_CONFIG_PROFILE,\n      host: opts.databricksHost ?? process.env.DATABRICKS_HOST,\n      token: opts.databricksToken ?? process.env.DATABRICKS_TOKEN,\n    })) ?? {};\n\n  let summary: EvalRunSummary;\n  try {\n    summary = await runner.runEvalsInDir({\n      rootDir: opts.root,\n      baseUrl: opts.url,\n      filter,\n      strict: opts.strict,\n      headers: opts.header ? parseHeaders(opts.header) : undefined,\n      concurrency: opts.concurrency,\n      mlflow: resolveMlflow(opts, auth),\n      judge: resolveJudge(opts, auth),\n      onEvent: makeProgressReporter(runner, opts.url),\n    });\n  } catch (err) {\n    // Setup failures (e.g. a bad --experiment for the MLflow run) reject before\n    // any eval runs; surface a clean message + non-zero exit rather than an\n    // unhandled promise rejection with a raw stack.\n    console.error(\n      `\\nEval run failed: ${err instanceof Error ? err.message : String(err)}`,\n    );\n    process.exitCode = 1;\n    return;\n  }\n  console.log(`\\n${runner.formatSummaryLine(summary.results)}`);\n\n  if (summary.mlflow) {\n    printMlflowOutcome(summary.mlflow);\n  } else {\n    console.log(\n      \"\\nMLflow evaluation run skipped — pass --experiment (or set\" +\n        \" MLFLOW_EXPERIMENT_ID) plus --profile/--databricks-host to create one.\",\n    );\n  }\n\n  if (!runner.summarize(summary.results).allPassed) {\n    process.exitCode = 1;\n  }\n}\n\nexport const agentEvalCommand = new Command(\"eval\")\n  .description(\n    \"Run agent evals (server/agents/<id>/evals/*.eval.ts) against a running app\",\n  )\n  .argument(\n    \"[filter]\",\n    \"Only run evals whose <agent>/<id> contains this substring (or an exact agent id)\",\n  )\n  .option(\"--url <url>\", \"Base URL of the running app\", \"http://localhost:3000\")\n  .option(\"--strict\", \"Fail on soft-assertion misses too\", false)\n  .option(\n    \"--concurrency <n>\",\n    \"Max evals to run concurrently (default 4; keep at or below the app's max concurrent streams per user)\",\n    (v) => Number.parseInt(v, 10),\n  )\n  .option(\n    \"--root <dir>\",\n    \"Project root containing server/agents/ (default: cwd)\",\n  )\n  .option(\n    \"--header <header...>\",\n    \"Extra request header as 'Key: value' (repeatable)\",\n  )\n  .option(\n    \"--profile <name>\",\n    \"Databricks CLI profile to authenticate with via OAuth (default: DATABRICKS_CONFIG_PROFILE)\",\n  )\n  .option(\n    \"--databricks-host <host>\",\n    \"Databricks host for writing MLflow assessments (default: DATABRICKS_HOST)\",\n  )\n  .option(\n    \"--databricks-token <token>\",\n    \"Databricks token for writing MLflow assessments (default: DATABRICKS_TOKEN)\",\n  )\n  .option(\n    \"--experiment <id>\",\n    \"MLflow experiment id for the evaluation run (default: MLFLOW_EXPERIMENT_ID)\",\n  )\n  .option(\n    \"--warehouse-id <id>\",\n    \"SQL warehouse id for writing assessments to UC-backed experiments (default: MLFLOW_TRACING_SQL_WAREHOUSE_ID or DATABRICKS_WAREHOUSE_ID)\",\n  )\n  .option(\n    \"--judge-model <endpoint>\",\n    \"Databricks serving endpoint to use as the LLM judge for t.judge.* (default: APPKIT_JUDGE_MODEL)\",\n  )\n  .action(runAgentEval);\n"],"mappings":"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"}
+{"version":3,"file":"eval.js","names":[],"sources":["../../../../src/cli/commands/agent/eval.ts"],"sourcesContent":["import { Command } from \"commander\";\n\ninterface EvalRunSummary {\n  results: unknown[];\n  mlflow?: {\n    runId: string;\n    report: {\n      written: number;\n      skipped: number;\n      failures: Array<{ traceId: string; status?: number; error?: string }>;\n    };\n    finish: { finished: boolean; metricsError?: string; finishError?: string };\n  };\n}\n\ntype EvalProgress =\n  | { type: \"discovered\"; total: number }\n  | { type: \"run-created\"; runId: string }\n  | { type: \"start\"; id: string; index: number; total: number }\n  | { type: \"result\"; result: unknown; index: number; total: number };\n\n/** Subset of `@databricks/appkit/beta`'s eval runner used by this command. */\ninterface EvalRunner {\n  runEvalsInDir(opts: {\n    rootDir?: string;\n    baseUrl: string;\n    filter?: string;\n    strict?: boolean;\n    headers?: Record<string, string>;\n    concurrency?: number;\n    mlflow?: {\n      host: string;\n      token: string;\n      experimentId: string;\n      sqlWarehouseId?: string;\n    };\n    judge?: { host: string; token: string; model: string };\n    workspaceClient?: unknown;\n    warehouseId?: string;\n    onEvent?: (event: EvalProgress) => void;\n  }): Promise<EvalRunSummary>;\n  resolveDatabricksAuth(opts: {\n    profile?: string;\n    host?: string;\n    token?: string;\n  }): Promise<{ host: string; token: string } | undefined>;\n  resolveWorkspaceClient(opts: {\n    profile?: string;\n    host?: string;\n    token?: string;\n  }): unknown;\n  formatEvalHeadline(result: unknown): string;\n  evalGlyph(result: unknown): string;\n  formatEvalDetail(result: unknown): string[];\n  formatSummaryLine(results: unknown[]): string;\n  summarize(results: unknown[]): { allPassed: boolean };\n}\n\n/**\n * Loaded at runtime from the consuming project so this command (which ships in\n * `@databricks/shared`) doesn't take a build-time dependency on appkit. The\n * specifier is a variable so the type checker treats it as `any`.\n */\nasync function loadRunner(): Promise<EvalRunner> {\n  const spec = \"@databricks/appkit/beta\";\n  try {\n    return (await import(spec)) as unknown as EvalRunner;\n  } catch (err) {\n    throw new Error(\n      \"Could not load @databricks/appkit. Run `appkit agent eval` from a \" +\n        \"project with @databricks/appkit installed. \" +\n        `Cause: ${err instanceof Error ? err.message : String(err)}`,\n    );\n  }\n}\n\nfunction parseHeaders(values: string[]): Record<string, string> {\n  const headers: Record<string, string> = {};\n  for (const v of values) {\n    const i = v.indexOf(\":\");\n    if (i === -1) continue;\n    headers[v.slice(0, i).trim()] = v.slice(i + 1).trim();\n  }\n  return headers;\n}\n\ninterface EvalOptions {\n  url: string;\n  strict?: boolean;\n  root?: string;\n  header?: string[];\n  profile?: string;\n  databricksHost?: string;\n  databricksToken?: string;\n  experiment?: string;\n  judgeModel?: string;\n  concurrency?: number;\n  warehouseId?: string;\n}\n\n/** Resolved Databricks host + bearer (either field may be absent). */\ntype Auth = { host?: string; token?: string };\n\n/**\n * Native MLflow \"Evaluation run\" config — only when creds + an experiment are\n * all present (traces live in the app; the run + scores are driven from here).\n */\nfunction resolveMlflow(opts: EvalOptions, auth: Auth) {\n  const experimentId = opts.experiment ?? process.env.MLFLOW_EXPERIMENT_ID;\n  if (!(auth.host && auth.token && experimentId)) return undefined;\n  // UC-backed experiments need a SQL warehouse to write assessments to their\n  // V4 traces. Mirror mlflow's env var, and accept the common DATABRICKS one.\n  const sqlWarehouseId =\n    opts.warehouseId ??\n    process.env.MLFLOW_TRACING_SQL_WAREHOUSE_ID ??\n    process.env.DATABRICKS_WAREHOUSE_ID;\n  return {\n    host: auth.host,\n    token: auth.token,\n    experimentId,\n    ...(sqlWarehouseId ? { sqlWarehouseId } : {}),\n  };\n}\n\n/** LLM-as-judge config — reuses the Databricks creds + a judge serving endpoint. */\nfunction resolveJudge(opts: EvalOptions, auth: Auth) {\n  const model = opts.judgeModel ?? process.env.APPKIT_JUDGE_MODEL;\n  return model && auth.host && auth.token\n    ? { host: auth.host, token: auth.token, model }\n    : undefined;\n}\n\n/** Progress reporter: stream each eval as it runs instead of going silent. */\nfunction makeProgressReporter(\n  runner: EvalRunner,\n  url: string,\n): (event: EvalProgress) => void {\n  return (event) => {\n    switch (event.type) {\n      case \"discovered\":\n        console.log(\n          `Running ${event.total} eval${event.total === 1 ? \"\" : \"s\"} against ${url}\\n`,\n        );\n        break;\n      case \"run-created\":\n        console.log(`MLflow evaluation run: ${event.runId}\\n`);\n        break;\n      case \"result\": {\n        // One full line per completion — evals run concurrently, so a split\n        // \"start … glyph\" prefix would interleave into garbage.\n        console.log(\n          `[${event.index + 1}/${event.total}] ${runner.formatEvalHeadline(event.result)}`,\n        );\n        for (const line of runner.formatEvalDetail(event.result)) {\n          console.log(line);\n        }\n        break;\n      }\n    }\n  };\n}\n\nfunction formatFailureLine(f: {\n  traceId: string;\n  status?: number;\n  error?: string;\n}): string {\n  return `  ✗ trace ${f.traceId}: ${f.status ?? \"\"} ${f.error ?? \"\"}`.trim();\n}\n\n/** Print the MLflow assessment/finish outcome after a run that created one. */\nfunction printMlflowOutcome(\n  mlflow: NonNullable<EvalRunSummary[\"mlflow\"]>,\n): void {\n  const { report, finish } = mlflow;\n  console.log(\n    `MLflow: ${report.written} assessment(s) written` +\n      (report.skipped ? `, ${report.skipped} skipped` : \"\") +\n      (report.failures.length ? `, ${report.failures.length} failed` : \"\"),\n  );\n  for (const f of report.failures) {\n    console.error(formatFailureLine(f));\n  }\n  if (finish.metricsError) {\n    console.error(`  ⚠ metrics not logged: ${finish.metricsError}`);\n  }\n  if (!finish.finished) {\n    console.error(\n      `  ✗ run left RUNNING — failed to finish: ${finish.finishError ?? \"unknown\"}`,\n    );\n  }\n}\n\nasync function runAgentEval(\n  filter: string | undefined,\n  opts: EvalOptions,\n): Promise<void> {\n  const runner = await loadRunner();\n\n  // Resolve Databricks host + bearer the AppKit-native way: an explicit\n  // host/token (or DATABRICKS_* env) wins; otherwise the SDK mints an OAuth\n  // token from the CLI profile — so no hand-set PAT is required.\n  const auth: Auth =\n    (await runner.resolveDatabricksAuth({\n      profile: opts.profile ?? process.env.DATABRICKS_CONFIG_PROFILE,\n      host: opts.databricksHost ?? process.env.DATABRICKS_HOST,\n      token: opts.databricksToken ?? process.env.DATABRICKS_TOKEN,\n    })) ?? {};\n\n  // Managed-dataset reads: a workspace client (same profile/host/token) + a SQL\n  // warehouse. Only needed by evals that declare `dataset`.\n  const warehouseId = opts.warehouseId ?? process.env.DATABRICKS_WAREHOUSE_ID;\n  const workspaceClient = runner.resolveWorkspaceClient({\n    profile: opts.profile ?? process.env.DATABRICKS_CONFIG_PROFILE,\n    host: opts.databricksHost ?? process.env.DATABRICKS_HOST,\n    token: opts.databricksToken ?? process.env.DATABRICKS_TOKEN,\n  });\n\n  let summary: EvalRunSummary;\n  try {\n    summary = await runner.runEvalsInDir({\n      rootDir: opts.root,\n      baseUrl: opts.url,\n      filter,\n      strict: opts.strict,\n      headers: opts.header ? parseHeaders(opts.header) : undefined,\n      concurrency: opts.concurrency,\n      mlflow: resolveMlflow(opts, auth),\n      judge: resolveJudge(opts, auth),\n      workspaceClient,\n      warehouseId,\n      onEvent: makeProgressReporter(runner, opts.url),\n    });\n  } catch (err) {\n    // Setup failures (e.g. a bad --experiment for the MLflow run) reject before\n    // any eval runs; surface a clean message + non-zero exit rather than an\n    // unhandled promise rejection with a raw stack.\n    console.error(\n      `\\nEval run failed: ${err instanceof Error ? err.message : String(err)}`,\n    );\n    process.exitCode = 1;\n    return;\n  }\n  console.log(`\\n${runner.formatSummaryLine(summary.results)}`);\n\n  if (summary.mlflow) {\n    printMlflowOutcome(summary.mlflow);\n  } else {\n    console.log(\n      \"\\nMLflow evaluation run skipped — pass --experiment (or set\" +\n        \" MLFLOW_EXPERIMENT_ID) plus --profile/--databricks-host to create one.\",\n    );\n  }\n\n  if (!runner.summarize(summary.results).allPassed) {\n    process.exitCode = 1;\n  }\n}\n\nexport const agentEvalCommand = new Command(\"eval\")\n  .description(\n    \"Run agent evals (server/agents/<id>/evals/*.eval.ts) against a running app\",\n  )\n  .argument(\n    \"[filter]\",\n    \"Only run evals whose <agent>/<id> contains this substring (or an exact agent id)\",\n  )\n  .option(\"--url <url>\", \"Base URL of the running app\", \"http://localhost:3000\")\n  .option(\"--strict\", \"Fail on soft-assertion misses too\", false)\n  .option(\n    \"--concurrency <n>\",\n    \"Max evals to run concurrently (default 4; keep at or below the app's max concurrent streams per user)\",\n    (v) => Number.parseInt(v, 10),\n  )\n  .option(\n    \"--root <dir>\",\n    \"Project root containing server/agents/ (default: cwd)\",\n  )\n  .option(\n    \"--header <header...>\",\n    \"Extra request header as 'Key: value' (repeatable)\",\n  )\n  .option(\n    \"--profile <name>\",\n    \"Databricks CLI profile to authenticate with via OAuth (default: DATABRICKS_CONFIG_PROFILE)\",\n  )\n  .option(\n    \"--databricks-host <host>\",\n    \"Databricks host for writing MLflow assessments (default: DATABRICKS_HOST)\",\n  )\n  .option(\n    \"--databricks-token <token>\",\n    \"Databricks token for writing MLflow assessments (default: DATABRICKS_TOKEN)\",\n  )\n  .option(\n    \"--experiment <id>\",\n    \"MLflow experiment id for the evaluation run (default: MLFLOW_EXPERIMENT_ID)\",\n  )\n  .option(\n    \"--warehouse-id <id>\",\n    \"SQL warehouse id for reading managed eval datasets and writing assessments to UC-backed experiments (default: DATABRICKS_WAREHOUSE_ID, or MLFLOW_TRACING_SQL_WAREHOUSE_ID for assessments)\",\n  )\n  .option(\n    \"--judge-model <endpoint>\",\n    \"Databricks serving endpoint to use as the LLM judge for t.judge.* (default: APPKIT_JUDGE_MODEL)\",\n  )\n  .action(runAgentEval);\n"],"mappings":"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"}

package/dist/connectors/index.js

@@ -13,7 +13,7 @@ import "./jobs/index.js";
 import { buildMcpHostPolicy } from "./mcp/host-policy.js";
 import { AppKitMcpClient } from "./mcp/client.js";
 import "./mcp/index.js";
-import { resolveDatabricksAuth } from "./mlflow/auth.js";
+import { resolveDatabricksAuth, resolveWorkspaceClient } from "./mlflow/auth.js";
 import { MlflowClient, normalizeHost } from "./mlflow/client.js";
 import { DEFAULT_WAREHOUSE_STARTUP_TIMEOUT_MS, SQLWarehouseConnector } from "./sql-warehouse/client.js";
 import "./sql-warehouse/index.js";

package/dist/connectors/mlflow/auth.d.ts

@@ -1,3 +1,5 @@
+import { WorkspaceClient } from "../../workspace-client/index.js";
+
 //#region src/connectors/mlflow/auth.d.ts
 /** Resolved Databricks host + bearer token for the eval runner's REST calls. */
 interface DatabricksAuth {
@@ -13,6 +15,14 @@ interface ResolveDatabricksAuthOptions {
   token?: string;
 }
 declare function resolveDatabricksAuth(options?: ResolveDatabricksAuthOptions): Promise<DatabricksAuth | undefined>;
+/**
+ * Construct a Databricks `WorkspaceClient` for the eval runner — the object the
+ * SDK-backed connectors (e.g. `SQLWarehouseConnector`) take. An explicit
+ * host+token builds a PAT client; otherwise the profile (or ambient config) is
+ * used and the SDK resolves credentials, minting OAuth as needed. Returns
+ * `undefined` if construction throws (missing/invalid config).
+ */
+declare function resolveWorkspaceClient(options?: ResolveDatabricksAuthOptions): WorkspaceClient | undefined;
 //#endregion
-export { DatabricksAuth, ResolveDatabricksAuthOptions, resolveDatabricksAuth };
+export { DatabricksAuth, ResolveDatabricksAuthOptions, resolveDatabricksAuth, resolveWorkspaceClient };
 //# sourceMappingURL=auth.d.ts.map

package/dist/connectors/mlflow/auth.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auth.d.ts","names":[],"sources":["../../../src/connectors/mlflow/auth.ts"],"mappings":";;UAGiB,cAAA;EACf,IAAA;EACA,KAAA;AAAA;AAAA,UAGe,4BAAA;EAAA;EAEf,OAAA;;EAEA,IAAA;EAFA;EAIA,KAAA;AAAA;AAAA,iBA+CoB,qBAAA,CACpB,OAAA,GAAS,4BAAA,GACR,OAAA,CAAQ,cAAA"}
+{"version":3,"file":"auth.d.ts","names":[],"sources":["../../../src/connectors/mlflow/auth.ts"],"mappings":";;;;UAMiB,cAAA;EACf,IAAA;EACA,KAAA;AAAA;AAAA,UAGe,4BAAA;EAHV;EAKL,OAAA;EAF2C;EAI3C,IAAA;EAJ2C;EAM3C,KAAA;AAAA;AAAA,iBA8CoB,qBAAA,CACpB,OAAA,GAAS,4BAAA,GACR,OAAA,CAAQ,cAAA;;;AAFX;;;;;iBAiBgB,sBAAA,CACd,OAAA,GAAS,4BAAA,GACR,eAAA"}

package/dist/connectors/mlflow/auth.js

@@ -23,7 +23,8 @@ function extractBearer(headers) {
 */
 async function resolveViaSdk(options) {
 	try {
-		const client = createWorkspaceClient(options.profile ? { profile: options.profile } : {});
+		const client = resolveWorkspaceClient(options);
+		if (!client) return void 0;
 		const headers = new Headers();
 		await client.config.authenticate(headers);
 		const token = options.token ?? extractBearer(headers);
@@ -44,7 +45,26 @@ async function resolveDatabricksAuth(options = {}) {
 	};
 	return resolveViaSdk(options);
 }
+/**
+* Construct a Databricks `WorkspaceClient` for the eval runner — the object the
+* SDK-backed connectors (e.g. `SQLWarehouseConnector`) take. An explicit
+* host+token builds a PAT client; otherwise the profile (or ambient config) is
+* used and the SDK resolves credentials, minting OAuth as needed. Returns
+* `undefined` if construction throws (missing/invalid config).
+*/
+function resolveWorkspaceClient(options = {}) {
+	try {
+		if (options.host && options.token) return createWorkspaceClient({
+			host: options.host,
+			token: options.token,
+			authType: "pat"
+		});
+		return createWorkspaceClient(options.profile ? { profile: options.profile } : {});
+	} catch {
+		return;
+	}
+}
 
 //#endregion
-export { resolveDatabricksAuth };
+export { resolveDatabricksAuth, resolveWorkspaceClient };
 //# sourceMappingURL=auth.js.map

package/dist/connectors/mlflow/auth.js.map

@@ -1 +1 @@
-{"version":3,"file":"auth.js","names":[],"sources":["../../../src/connectors/mlflow/auth.ts"],"sourcesContent":["import { createWorkspaceClient } from \"../../workspace-client\";\n\n/** Resolved Databricks host + bearer token for the eval runner's REST calls. */\nexport interface DatabricksAuth {\n  host: string;\n  token: string;\n}\n\nexport interface ResolveDatabricksAuthOptions {\n  /** `~/.databrickscfg` profile to authenticate with (e.g. `dogfood`). */\n  profile?: string;\n  /** Explicit host; wins over the profile/SDK-resolved host when set. */\n  host?: string;\n  /** Explicit bearer token; when set, no OAuth is minted (PAT/CI path). */\n  token?: string;\n}\n\n/**\n * Resolve `{host, token}` for the eval runner the same way the rest of AppKit\n * authenticates: construct a Databricks `WorkspaceClient` and let its config\n * mint (and later refresh) an OAuth bearer from the CLI profile — no hand-set\n * PAT required. An explicit host/token still wins (PAT or CI env), so the SDK\n * is only consulted for whatever isn't supplied.\n *\n * Returns `undefined` when neither an explicit token nor a resolvable profile\n * yields a bearer, so the caller can treat auth as simply unavailable.\n */\n/** Pull the bearer out of an `Authorization: Bearer <token>` header. */\nfunction extractBearer(headers: Headers): string | undefined {\n  return headers.get(\"authorization\")?.replace(/^Bearer\\s+/i, \"\");\n}\n\n/**\n * Resolve `{host, token}` via the SDK: construct a `WorkspaceClient`, let it\n * mint/refresh an OAuth bearer from the profile (or reuse a PAT), and fall back\n * to any explicit host/token the caller supplied. Returns `undefined` when\n * either is missing or the SDK can't resolve credentials.\n */\nasync function resolveViaSdk(\n  options: ResolveDatabricksAuthOptions,\n): Promise<DatabricksAuth | undefined> {\n  try {\n    const client = createWorkspaceClient(\n      options.profile ? { profile: options.profile } : {},\n    );\n    const headers = new Headers();\n    // Mints the OAuth access token (or reuses a PAT from the profile) and adds\n    // an `Authorization: Bearer <token>` header — the same call the connectors\n    // use before each request.\n    await client.config.authenticate(headers);\n    const token = options.token ?? extractBearer(headers);\n    const host =\n      options.host ??\n      (await client.config.getHost()).toString().replace(/\\/+$/, \"\");\n    if (!token || !host) return undefined;\n    return { host, token };\n  } catch {\n    return undefined;\n  }\n}\n\nexport async function resolveDatabricksAuth(\n  options: ResolveDatabricksAuthOptions = {},\n): Promise<DatabricksAuth | undefined> {\n  // Fully explicit — no need to touch the SDK.\n  if (options.host && options.token) {\n    return { host: options.host, token: options.token };\n  }\n  return resolveViaSdk(options);\n}\n"],"mappings":";;;;;;;;;;;;;;AA4BA,SAAS,cAAc,SAAsC;AAC3D,QAAO,QAAQ,IAAI,gBAAgB,EAAE,QAAQ,eAAe,GAAG;;;;;;;;AASjE,eAAe,cACb,SACqC;AACrC,KAAI;EACF,MAAM,SAAS,sBACb,QAAQ,UAAU,EAAE,SAAS,QAAQ,SAAS,GAAG,EAAE,CACpD;EACD,MAAM,UAAU,IAAI,SAAS;AAI7B,QAAM,OAAO,OAAO,aAAa,QAAQ;EACzC,MAAM,QAAQ,QAAQ,SAAS,cAAc,QAAQ;EACrD,MAAM,OACJ,QAAQ,SACP,MAAM,OAAO,OAAO,SAAS,EAAE,UAAU,CAAC,QAAQ,QAAQ,GAAG;AAChE,MAAI,CAAC,SAAS,CAAC,KAAM,QAAO;AAC5B,SAAO;GAAE;GAAM;GAAO;SAChB;AACN;;;AAIJ,eAAsB,sBACpB,UAAwC,EAAE,EACL;AAErC,KAAI,QAAQ,QAAQ,QAAQ,MAC1B,QAAO;EAAE,MAAM,QAAQ;EAAM,OAAO,QAAQ;EAAO;AAErD,QAAO,cAAc,QAAQ"}
+{"version":3,"file":"auth.js","names":[],"sources":["../../../src/connectors/mlflow/auth.ts"],"sourcesContent":["import {\n  createWorkspaceClient,\n  type WorkspaceClient,\n} from \"../../workspace-client\";\n\n/** Resolved Databricks host + bearer token for the eval runner's REST calls. */\nexport interface DatabricksAuth {\n  host: string;\n  token: string;\n}\n\nexport interface ResolveDatabricksAuthOptions {\n  /** `~/.databrickscfg` profile to authenticate with (e.g. `dogfood`). */\n  profile?: string;\n  /** Explicit host; wins over the profile/SDK-resolved host when set. */\n  host?: string;\n  /** Explicit bearer token; when set, no OAuth is minted (PAT/CI path). */\n  token?: string;\n}\n\n/**\n * Resolve `{host, token}` for the eval runner the same way the rest of AppKit\n * authenticates: construct a Databricks `WorkspaceClient` and let its config\n * mint (and later refresh) an OAuth bearer from the CLI profile — no hand-set\n * PAT required. An explicit host/token still wins (PAT or CI env), so the SDK\n * is only consulted for whatever isn't supplied.\n *\n * Returns `undefined` when neither an explicit token nor a resolvable profile\n * yields a bearer, so the caller can treat auth as simply unavailable.\n */\n/** Pull the bearer out of an `Authorization: Bearer <token>` header. */\nfunction extractBearer(headers: Headers): string | undefined {\n  return headers.get(\"authorization\")?.replace(/^Bearer\\s+/i, \"\");\n}\n\n/**\n * Resolve `{host, token}` via the SDK: construct a `WorkspaceClient`, let it\n * mint/refresh an OAuth bearer from the profile (or reuse a PAT), and fall back\n * to any explicit host/token the caller supplied. Returns `undefined` when\n * either is missing or the SDK can't resolve credentials.\n */\nasync function resolveViaSdk(\n  options: ResolveDatabricksAuthOptions,\n): Promise<DatabricksAuth | undefined> {\n  try {\n    const client = resolveWorkspaceClient(options);\n    if (!client) return undefined;\n    const headers = new Headers();\n    // Mints the OAuth access token (or reuses a PAT from the profile) and adds\n    // an `Authorization: Bearer <token>` header — the same call the connectors\n    // use before each request.\n    await client.config.authenticate(headers);\n    const token = options.token ?? extractBearer(headers);\n    const host =\n      options.host ??\n      (await client.config.getHost()).toString().replace(/\\/+$/, \"\");\n    if (!token || !host) return undefined;\n    return { host, token };\n  } catch {\n    return undefined;\n  }\n}\n\nexport async function resolveDatabricksAuth(\n  options: ResolveDatabricksAuthOptions = {},\n): Promise<DatabricksAuth | undefined> {\n  // Fully explicit — no need to touch the SDK.\n  if (options.host && options.token) {\n    return { host: options.host, token: options.token };\n  }\n  return resolveViaSdk(options);\n}\n\n/**\n * Construct a Databricks `WorkspaceClient` for the eval runner — the object the\n * SDK-backed connectors (e.g. `SQLWarehouseConnector`) take. An explicit\n * host+token builds a PAT client; otherwise the profile (or ambient config) is\n * used and the SDK resolves credentials, minting OAuth as needed. Returns\n * `undefined` if construction throws (missing/invalid config).\n */\nexport function resolveWorkspaceClient(\n  options: ResolveDatabricksAuthOptions = {},\n): WorkspaceClient | undefined {\n  try {\n    if (options.host && options.token) {\n      return createWorkspaceClient({\n        host: options.host,\n        token: options.token,\n        authType: \"pat\",\n      });\n    }\n    return createWorkspaceClient(\n      options.profile ? { profile: options.profile } : {},\n    );\n  } catch {\n    return undefined;\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;AA+BA,SAAS,cAAc,SAAsC;AAC3D,QAAO,QAAQ,IAAI,gBAAgB,EAAE,QAAQ,eAAe,GAAG;;;;;;;;AASjE,eAAe,cACb,SACqC;AACrC,KAAI;EACF,MAAM,SAAS,uBAAuB,QAAQ;AAC9C,MAAI,CAAC,OAAQ,QAAO;EACpB,MAAM,UAAU,IAAI,SAAS;AAI7B,QAAM,OAAO,OAAO,aAAa,QAAQ;EACzC,MAAM,QAAQ,QAAQ,SAAS,cAAc,QAAQ;EACrD,MAAM,OACJ,QAAQ,SACP,MAAM,OAAO,OAAO,SAAS,EAAE,UAAU,CAAC,QAAQ,QAAQ,GAAG;AAChE,MAAI,CAAC,SAAS,CAAC,KAAM,QAAO;AAC5B,SAAO;GAAE;GAAM;GAAO;SAChB;AACN;;;AAIJ,eAAsB,sBACpB,UAAwC,EAAE,EACL;AAErC,KAAI,QAAQ,QAAQ,QAAQ,MAC1B,QAAO;EAAE,MAAM,QAAQ;EAAM,OAAO,QAAQ;EAAO;AAErD,QAAO,cAAc,QAAQ;;;;;;;;;AAU/B,SAAgB,uBACd,UAAwC,EAAE,EACb;AAC7B,KAAI;AACF,MAAI,QAAQ,QAAQ,QAAQ,MAC1B,QAAO,sBAAsB;GAC3B,MAAM,QAAQ;GACd,OAAO,QAAQ;GACf,UAAU;GACX,CAAC;AAEJ,SAAO,sBACL,QAAQ,UAAU,EAAE,SAAS,QAAQ,SAAS,GAAG,EAAE,CACpD;SACK;AACN"}

package/dist/connectors/mlflow/index.d.ts

@@ -0,0 +1,2 @@
+import { DatabricksAuth, ResolveDatabricksAuthOptions, resolveDatabricksAuth, resolveWorkspaceClient } from "./auth.js";
+import { MlflowClient, PostResult, normalizeHost } from "./client.js";

package/dist/database/errors.js

@@ -9,6 +9,10 @@ const definitions = {
 		message: "Invalid database request",
 		statusCode: 400
 	},
+	VALIDATION_FAILED: {
+		message: "Database request failed validation",
+		statusCode: 422
+	},
 	NOT_FOUND: {
 		message: "Database record not found",
 		statusCode: 404
@@ -25,6 +29,10 @@ const definitions = {
 		message: "Database operation temporarily unavailable",
 		statusCode: 503
 	},
+	UNSUPPORTED_MEDIA_TYPE: {
+		message: "Database request body must be JSON",
+		statusCode: 415
+	},
 	PAYLOAD_TOO_LARGE: {
 		message: "Database response is too large",
 		statusCode: 413
@@ -44,6 +52,8 @@ const categoryByStatus = {
 	404: "NOT_FOUND",
 	409: "CONFLICT",
 	413: "PAYLOAD_TOO_LARGE",
+	415: "UNSUPPORTED_MEDIA_TYPE",
+	422: "VALIDATION_FAILED",
 	503: "TRANSIENT"
 };
 /** AppKit-facing database failure with stable metadata and no driver details. */
@@ -51,9 +61,9 @@ var DatabasePluginError = class extends AppKitError {
 	code = "DATABASE_PLUGIN_ERROR";
 	isRetryable;
 	statusCode;
-	constructor(category, phase, runtimeMessage, details) {
+	constructor(category, phase, diagnosticMessage, details) {
 		const definition = definitions[category];
-		super(phase === "runtime" && runtimeMessage ? runtimeMessage : definition.message, { clientMessage: definition.message });
+		super((phase === "runtime" || phase === "setup") && diagnosticMessage ? diagnosticMessage : definition.message, { clientMessage: definition.message });
 		this.category = category;
 		this.phase = phase;
 		this.details = details;
@@ -67,8 +77,8 @@ function invalidDatabaseRequest(runtimeMessage) {
 	return new DatabasePluginError("INVALID_REQUEST", "runtime", runtimeMessage);
 }
 /** Refuse to publish a plugin whose configuration cannot be honored. */
-function databaseSetupFailed() {
-	return new DatabasePluginError("SETUP_FAILED", "setup");
+function databaseSetupFailed(reason) {
+	return new DatabasePluginError("SETUP_FAILED", "setup", reason ? `Database setup failed: ${reason}` : void 0);
 }
 /** Reject untrusted request input, naming the field but never its value. */
 function invalidDatabaseInput(path, message) {
@@ -93,7 +103,7 @@ function describeUnclassifiedError(error) {
 }
 /** Add operation context without retaining an unknown error's details. */
 function classifyDatabaseError(error, phase) {
-	if (error instanceof DatabasePluginError) return error.phase === phase ? error : new DatabasePluginError(error.category, phase);
+	if (error instanceof DatabasePluginError) return error.phase === phase ? error : new DatabasePluginError(error.category, phase, void 0, error.details);
 	logger.error("Unclassified database error during %s (%s)", phase, describeUnclassifiedError(error));
 	return new DatabasePluginError("INTERNAL", phase);
 }

package/dist/database/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","names":[],"sources":["../../src/database/errors.ts"],"sourcesContent":["import { AppKitError } from \"../errors\";\nimport { createLogger } from \"../logging/logger\";\n\nconst logger = createLogger(\"database\");\n\nexport type DatabaseErrorCategory =\n  | \"INVALID_REQUEST\"\n  | \"NOT_FOUND\"\n  | \"CONFLICT\"\n  | \"FORBIDDEN\"\n  | \"TRANSIENT\"\n  | \"PAYLOAD_TOO_LARGE\"\n  | \"INTERNAL\"\n  | \"SETUP_FAILED\";\n\n/** Which request field a rejection concerns; it never carries caller values. */\nexport interface DatabaseErrorDetail {\n  readonly path: readonly string[];\n  readonly message: string;\n}\n\ntype DatabaseErrorPhase =\n  | \"setup\"\n  | \"shutdown\"\n  | \"read\"\n  | \"write\"\n  | \"transaction\"\n  | \"runtime\";\n\nconst definitions: Record<\n  DatabaseErrorCategory,\n  { readonly message: string; readonly statusCode: number }\n> = {\n  INVALID_REQUEST: { message: \"Invalid database request\", statusCode: 400 },\n  NOT_FOUND: { message: \"Database record not found\", statusCode: 404 },\n  CONFLICT: { message: \"Database conflict\", statusCode: 409 },\n  FORBIDDEN: { message: \"Database operation forbidden\", statusCode: 403 },\n  TRANSIENT: {\n    message: \"Database operation temporarily unavailable\",\n    statusCode: 503,\n  },\n  PAYLOAD_TOO_LARGE: {\n    message: \"Database response is too large\",\n    statusCode: 413,\n  },\n  INTERNAL: { message: \"Database operation failed\", statusCode: 500 },\n  SETUP_FAILED: { message: \"Database setup failed\", statusCode: 500 },\n};\n\nconst categoryByStatus: Readonly<Record<number, DatabaseErrorCategory>> = {\n  400: \"INVALID_REQUEST\",\n  403: \"FORBIDDEN\",\n  404: \"NOT_FOUND\",\n  409: \"CONFLICT\",\n  413: \"PAYLOAD_TOO_LARGE\",\n  503: \"TRANSIENT\",\n};\n\n/** AppKit-facing database failure with stable metadata and no driver details. */\nexport class DatabasePluginError extends AppKitError {\n  readonly code = \"DATABASE_PLUGIN_ERROR\";\n  readonly isRetryable: boolean;\n  readonly statusCode: number;\n\n  constructor(\n    readonly category: DatabaseErrorCategory,\n    readonly phase: DatabaseErrorPhase,\n    runtimeMessage?: string,\n    readonly details?: readonly DatabaseErrorDetail[],\n  ) {\n    const definition = definitions[category];\n    // Plugin boundaries replace runtime diagnostics with the stable message.\n    super(\n      phase === \"runtime\" && runtimeMessage\n        ? runtimeMessage\n        : definition.message,\n      {\n        clientMessage: definition.message,\n      },\n    );\n    this.statusCode = definition.statusCode;\n    this.isRetryable = category === \"TRANSIENT\";\n    this.name = \"DatabasePluginError\";\n  }\n}\n\n/** Keep runtime diagnostics internal until a plugin boundary classifies them. */\nexport function invalidDatabaseRequest(\n  runtimeMessage?: string,\n): DatabasePluginError {\n  return new DatabasePluginError(\"INVALID_REQUEST\", \"runtime\", runtimeMessage);\n}\n\n/** Refuse to publish a plugin whose configuration cannot be honored. */\nexport function databaseSetupFailed(): DatabasePluginError {\n  return new DatabasePluginError(\"SETUP_FAILED\", \"setup\");\n}\n\n/** Reject untrusted request input, naming the field but never its value. */\nexport function invalidDatabaseInput(\n  path: readonly string[],\n  message: string,\n): DatabasePluginError {\n  return new DatabasePluginError(\"INVALID_REQUEST\", \"read\", undefined, [\n    { path, message },\n  ]);\n}\n\n/**\n * Name an unknown failure without its payload. A driver error carries the SQL\n * text and its bound row values (for example a `DrizzleQueryError` retains\n * `query` and `params`), so only constructor names walk into the log.\n */\nfunction describeUnclassifiedError(error: unknown): string {\n  const names: string[] = [];\n  let current: unknown = error;\n  for (let depth = 0; depth < 5 && current instanceof Error; depth++) {\n    names.push(current.name);\n    current = current.cause;\n  }\n  return names.length > 0 ? names.join(\" <- \") : typeof error;\n}\n\n/** Add operation context without retaining an unknown error's details. */\nexport function classifyDatabaseError(\n  error: unknown,\n  phase: DatabaseErrorPhase,\n): DatabasePluginError {\n  if (error instanceof DatabasePluginError) {\n    return error.phase === phase\n      ? error\n      : new DatabasePluginError(error.category, phase);\n  }\n  logger.error(\n    \"Unclassified database error during %s (%s)\",\n    phase,\n    describeUnclassifiedError(error),\n  );\n  return new DatabasePluginError(\"INTERNAL\", phase);\n}\n\n/** Restore the safe database category carried through `Plugin.execute()`. */\nexport function databaseErrorFromStatus(\n  status: number,\n  phase: DatabaseErrorPhase,\n): DatabasePluginError {\n  const category = categoryByStatus[status] ?? \"INTERNAL\";\n  return new DatabasePluginError(category, phase);\n}\n"],"mappings":";;;;;AAGA,MAAM,SAAS,aAAa,WAAW;AA0BvC,MAAM,cAGF;CACF,iBAAiB;EAAE,SAAS;EAA4B,YAAY;EAAK;CACzE,WAAW;EAAE,SAAS;EAA6B,YAAY;EAAK;CACpE,UAAU;EAAE,SAAS;EAAqB,YAAY;EAAK;CAC3D,WAAW;EAAE,SAAS;EAAgC,YAAY;EAAK;CACvE,WAAW;EACT,SAAS;EACT,YAAY;EACb;CACD,mBAAmB;EACjB,SAAS;EACT,YAAY;EACb;CACD,UAAU;EAAE,SAAS;EAA6B,YAAY;EAAK;CACnE,cAAc;EAAE,SAAS;EAAyB,YAAY;EAAK;CACpE;AAED,MAAM,mBAAoE;CACxE,KAAK;CACL,KAAK;CACL,KAAK;CACL,KAAK;CACL,KAAK;CACL,KAAK;CACN;;AAGD,IAAa,sBAAb,cAAyC,YAAY;CACnD,AAAS,OAAO;CAChB,AAAS;CACT,AAAS;CAET,YACE,AAAS,UACT,AAAS,OACT,gBACA,AAAS,SACT;EACA,MAAM,aAAa,YAAY;AAE/B,QACE,UAAU,aAAa,iBACnB,iBACA,WAAW,SACf,EACE,eAAe,WAAW,SAC3B,CACF;EAdQ;EACA;EAEA;AAYT,OAAK,aAAa,WAAW;AAC7B,OAAK,cAAc,aAAa;AAChC,OAAK,OAAO;;;;AAKhB,SAAgB,uBACd,gBACqB;AACrB,QAAO,IAAI,oBAAoB,mBAAmB,WAAW,eAAe;;;AAI9E,SAAgB,sBAA2C;AACzD,QAAO,IAAI,oBAAoB,gBAAgB,QAAQ;;;AAIzD,SAAgB,qBACd,MACA,SACqB;AACrB,QAAO,IAAI,oBAAoB,mBAAmB,QAAQ,QAAW,CACnE;EAAE;EAAM;EAAS,CAClB,CAAC;;;;;;;AAQJ,SAAS,0BAA0B,OAAwB;CACzD,MAAM,QAAkB,EAAE;CAC1B,IAAI,UAAmB;AACvB,MAAK,IAAI,QAAQ,GAAG,QAAQ,KAAK,mBAAmB,OAAO,SAAS;AAClE,QAAM,KAAK,QAAQ,KAAK;AACxB,YAAU,QAAQ;;AAEpB,QAAO,MAAM,SAAS,IAAI,MAAM,KAAK,OAAO,GAAG,OAAO;;;AAIxD,SAAgB,sBACd,OACA,OACqB;AACrB,KAAI,iBAAiB,oBACnB,QAAO,MAAM,UAAU,QACnB,QACA,IAAI,oBAAoB,MAAM,UAAU,MAAM;AAEpD,QAAO,MACL,8CACA,OACA,0BAA0B,MAAM,CACjC;AACD,QAAO,IAAI,oBAAoB,YAAY,MAAM;;;AAInD,SAAgB,wBACd,QACA,OACqB;AAErB,QAAO,IAAI,oBADM,iBAAiB,WAAW,YACJ,MAAM"}
+{"version":3,"file":"errors.js","names":[],"sources":["../../src/database/errors.ts"],"sourcesContent":["import { AppKitError } from \"../errors\";\nimport { createLogger } from \"../logging/logger\";\n\nconst logger = createLogger(\"database\");\n\nexport type DatabaseErrorCategory =\n  | \"INVALID_REQUEST\"\n  | \"VALIDATION_FAILED\"\n  | \"NOT_FOUND\"\n  | \"CONFLICT\"\n  | \"FORBIDDEN\"\n  | \"TRANSIENT\"\n  | \"UNSUPPORTED_MEDIA_TYPE\"\n  | \"PAYLOAD_TOO_LARGE\"\n  | \"INTERNAL\"\n  | \"SETUP_FAILED\";\n\n/** Which request field a rejection concerns; it never carries caller values. */\nexport interface DatabaseErrorDetail {\n  readonly path: readonly string[];\n  readonly message: string;\n}\n\ntype DatabaseErrorPhase =\n  | \"setup\"\n  | \"shutdown\"\n  | \"read\"\n  | \"write\"\n  | \"transaction\"\n  | \"runtime\";\n\nconst definitions: Record<\n  DatabaseErrorCategory,\n  { readonly message: string; readonly statusCode: number }\n> = {\n  INVALID_REQUEST: { message: \"Invalid database request\", statusCode: 400 },\n  VALIDATION_FAILED: {\n    message: \"Database request failed validation\",\n    statusCode: 422,\n  },\n  NOT_FOUND: { message: \"Database record not found\", statusCode: 404 },\n  CONFLICT: { message: \"Database conflict\", statusCode: 409 },\n  FORBIDDEN: { message: \"Database operation forbidden\", statusCode: 403 },\n  TRANSIENT: {\n    message: \"Database operation temporarily unavailable\",\n    statusCode: 503,\n  },\n  UNSUPPORTED_MEDIA_TYPE: {\n    message: \"Database request body must be JSON\",\n    statusCode: 415,\n  },\n  PAYLOAD_TOO_LARGE: {\n    message: \"Database response is too large\",\n    statusCode: 413,\n  },\n  INTERNAL: { message: \"Database operation failed\", statusCode: 500 },\n  SETUP_FAILED: { message: \"Database setup failed\", statusCode: 500 },\n};\n\nconst categoryByStatus: Readonly<Record<number, DatabaseErrorCategory>> = {\n  400: \"INVALID_REQUEST\",\n  403: \"FORBIDDEN\",\n  404: \"NOT_FOUND\",\n  409: \"CONFLICT\",\n  413: \"PAYLOAD_TOO_LARGE\",\n  415: \"UNSUPPORTED_MEDIA_TYPE\",\n  422: \"VALIDATION_FAILED\",\n  503: \"TRANSIENT\",\n};\n\n/** AppKit-facing database failure with stable metadata and no driver details. */\nexport class DatabasePluginError extends AppKitError {\n  readonly code = \"DATABASE_PLUGIN_ERROR\";\n  readonly isRetryable: boolean;\n  readonly statusCode: number;\n\n  constructor(\n    readonly category: DatabaseErrorCategory,\n    readonly phase: DatabaseErrorPhase,\n    diagnosticMessage?: string,\n    readonly details?: readonly DatabaseErrorDetail[],\n  ) {\n    const definition = definitions[category];\n    // Setup and runtime diagnostics stay server-side. Request boundaries and\n    // clientMessage always use the stable message.\n    super(\n      (phase === \"runtime\" || phase === \"setup\") && diagnosticMessage\n        ? diagnosticMessage\n        : definition.message,\n      {\n        clientMessage: definition.message,\n      },\n    );\n    this.statusCode = definition.statusCode;\n    this.isRetryable = category === \"TRANSIENT\";\n    this.name = \"DatabasePluginError\";\n  }\n}\n\n/** Keep runtime diagnostics internal until a plugin boundary classifies them. */\nexport function invalidDatabaseRequest(\n  runtimeMessage?: string,\n): DatabasePluginError {\n  return new DatabasePluginError(\"INVALID_REQUEST\", \"runtime\", runtimeMessage);\n}\n\n/** Refuse to publish a plugin whose configuration cannot be honored. */\nexport function databaseSetupFailed(reason?: string): DatabasePluginError {\n  return new DatabasePluginError(\n    \"SETUP_FAILED\",\n    \"setup\",\n    reason ? `Database setup failed: ${reason}` : undefined,\n  );\n}\n\n/** Reject untrusted request input, naming the field but never its value. */\nexport function invalidDatabaseInput(\n  path: readonly string[],\n  message: string,\n): DatabasePluginError {\n  return new DatabasePluginError(\"INVALID_REQUEST\", \"read\", undefined, [\n    { path, message },\n  ]);\n}\n\n/**\n * Name an unknown failure without its payload. A driver error carries the SQL\n * text and its bound row values (for example a `DrizzleQueryError` retains\n * `query` and `params`), so only constructor names walk into the log.\n */\nfunction describeUnclassifiedError(error: unknown): string {\n  const names: string[] = [];\n  let current: unknown = error;\n  for (let depth = 0; depth < 5 && current instanceof Error; depth++) {\n    names.push(current.name);\n    current = current.cause;\n  }\n  return names.length > 0 ? names.join(\" <- \") : typeof error;\n}\n\n/** Add operation context without retaining an unknown error's details. */\nexport function classifyDatabaseError(\n  error: unknown,\n  phase: DatabaseErrorPhase,\n): DatabasePluginError {\n  if (error instanceof DatabasePluginError) {\n    // Details name request fields only, so they survive a change of phase.\n    return error.phase === phase\n      ? error\n      : new DatabasePluginError(\n          error.category,\n          phase,\n          undefined,\n          error.details,\n        );\n  }\n  logger.error(\n    \"Unclassified database error during %s (%s)\",\n    phase,\n    describeUnclassifiedError(error),\n  );\n  return new DatabasePluginError(\"INTERNAL\", phase);\n}\n\n/** Restore the safe database category carried through `Plugin.execute()`. */\nexport function databaseErrorFromStatus(\n  status: number,\n  phase: DatabaseErrorPhase,\n): DatabasePluginError {\n  const category = categoryByStatus[status] ?? \"INTERNAL\";\n  return new DatabasePluginError(category, phase);\n}\n"],"mappings":";;;;;AAGA,MAAM,SAAS,aAAa,WAAW;AA4BvC,MAAM,cAGF;CACF,iBAAiB;EAAE,SAAS;EAA4B,YAAY;EAAK;CACzE,mBAAmB;EACjB,SAAS;EACT,YAAY;EACb;CACD,WAAW;EAAE,SAAS;EAA6B,YAAY;EAAK;CACpE,UAAU;EAAE,SAAS;EAAqB,YAAY;EAAK;CAC3D,WAAW;EAAE,SAAS;EAAgC,YAAY;EAAK;CACvE,WAAW;EACT,SAAS;EACT,YAAY;EACb;CACD,wBAAwB;EACtB,SAAS;EACT,YAAY;EACb;CACD,mBAAmB;EACjB,SAAS;EACT,YAAY;EACb;CACD,UAAU;EAAE,SAAS;EAA6B,YAAY;EAAK;CACnE,cAAc;EAAE,SAAS;EAAyB,YAAY;EAAK;CACpE;AAED,MAAM,mBAAoE;CACxE,KAAK;CACL,KAAK;CACL,KAAK;CACL,KAAK;CACL,KAAK;CACL,KAAK;CACL,KAAK;CACL,KAAK;CACN;;AAGD,IAAa,sBAAb,cAAyC,YAAY;CACnD,AAAS,OAAO;CAChB,AAAS;CACT,AAAS;CAET,YACE,AAAS,UACT,AAAS,OACT,mBACA,AAAS,SACT;EACA,MAAM,aAAa,YAAY;AAG/B,SACG,UAAU,aAAa,UAAU,YAAY,oBAC1C,oBACA,WAAW,SACf,EACE,eAAe,WAAW,SAC3B,CACF;EAfQ;EACA;EAEA;AAaT,OAAK,aAAa,WAAW;AAC7B,OAAK,cAAc,aAAa;AAChC,OAAK,OAAO;;;;AAKhB,SAAgB,uBACd,gBACqB;AACrB,QAAO,IAAI,oBAAoB,mBAAmB,WAAW,eAAe;;;AAI9E,SAAgB,oBAAoB,QAAsC;AACxE,QAAO,IAAI,oBACT,gBACA,SACA,SAAS,0BAA0B,WAAW,OAC/C;;;AAIH,SAAgB,qBACd,MACA,SACqB;AACrB,QAAO,IAAI,oBAAoB,mBAAmB,QAAQ,QAAW,CACnE;EAAE;EAAM;EAAS,CAClB,CAAC;;;;;;;AAQJ,SAAS,0BAA0B,OAAwB;CACzD,MAAM,QAAkB,EAAE;CAC1B,IAAI,UAAmB;AACvB,MAAK,IAAI,QAAQ,GAAG,QAAQ,KAAK,mBAAmB,OAAO,SAAS;AAClE,QAAM,KAAK,QAAQ,KAAK;AACxB,YAAU,QAAQ;;AAEpB,QAAO,MAAM,SAAS,IAAI,MAAM,KAAK,OAAO,GAAG,OAAO;;;AAIxD,SAAgB,sBACd,OACA,OACqB;AACrB,KAAI,iBAAiB,oBAEnB,QAAO,MAAM,UAAU,QACnB,QACA,IAAI,oBACF,MAAM,UACN,OACA,QACA,MAAM,QACP;AAEP,QAAO,MACL,8CACA,OACA,0BAA0B,MAAM,CACjC;AACD,QAAO,IAAI,oBAAoB,YAAY,MAAM;;;AAInD,SAAgB,wBACd,QACA,OACqB;AAErB,QAAO,IAAI,oBADM,iBAAiB,WAAW,YACJ,MAAM"}

package/dist/database/runtime/data-path.d.ts

@@ -0,0 +1,7 @@
+import { IdValue, OrderDirection } from "../contract/wire.js";
+
+//#region src/database/runtime/data-path.d.ts
+type Row = Record<string, unknown>;
+//#endregion
+export { Row };
+//# sourceMappingURL=data-path.d.ts.map

package/dist/database/runtime/data-path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-path.d.ts","names":[],"sources":["../../../src/database/runtime/data-path.ts"],"mappings":";;;KA8CY,GAAA,GAAM,MAAA"}

package/dist/database/runtime/data-path.js.map

@@ -1 +1 @@
-{"version":3,"file":"data-path.js","names":[],"sources":["../../../src/database/runtime/data-path.ts"],"sourcesContent":["import {\n  DEFAULT_LIMIT,\n  type FilterOperator,\n  type IdValue,\n  MAX_LIMIT,\n  MAX_OFFSET,\n  type OrderDirection,\n} from \"../contract\";\nimport { invalidDatabaseRequest } from \"../errors\";\nimport type { AppKitTable, ColumnMeta } from \"../schema-builder\";\n\nexport type { IdValue, OrderDirection };\nexport type ScalarValue = string | number | bigint | boolean | null;\n/** Operators for one column; array operands are reserved for `in`. */\nexport type FilterOps = Partial<\n  Record<FilterOperator, ScalarValue | readonly ScalarValue[]>\n>;\nexport type WhereValue = ScalarValue | readonly ScalarValue[] | FilterOps;\n/** Direct-column predicates with explicit `and` and `or` predicate groups. */\nexport type WhereClause = Readonly<\n  Record<string, WhereValue | readonly WhereClause[]>\n>;\n\nexport type OrderSpec = Readonly<Record<string, OrderDirection>>;\n\nexport interface IncludeOptions {\n  readonly select?: readonly string[];\n  readonly where?: WhereClause;\n  readonly order?: OrderSpec;\n  readonly limit?: number;\n  readonly include?: IncludeSpec;\n}\n\n/** Selection and bounds for one declared relation edge. */\nexport type IncludeSpec = Readonly<Record<string, boolean | IncludeOptions>>;\n\n/** A bounded root read; adapters apply defaults and validate explicit bounds. */\nexport interface QuerySpec {\n  readonly where?: WhereClause;\n  readonly order?: OrderSpec;\n  readonly select?: readonly string[];\n  readonly include?: IncludeSpec;\n  readonly limit?: number;\n  readonly offset?: number;\n}\n\nexport type Row = Record<string, unknown>;\n\n/** Combine predicates without making callers understand the wire shape. */\nexport function andWhere(\n  existing: WhereClause | undefined,\n  next: WhereClause,\n): WhereClause {\n  return existing === undefined ? next : { and: [existing, next] };\n}\n\n/** Internal AppKit execution port; field names are schema-owned identifiers. */\nexport interface DataPath {\n  /** Read a bounded collection from one finalized table. */\n  select(table: AppKitTable, spec: QuerySpec): Promise<Row[]>;\n  /** Read by the sole primary key while preserving supported query state. */\n  findOne(\n    table: AppKitTable,\n    id: IdValue,\n    spec?: Pick<QuerySpec, \"where\" | \"select\" | \"include\">,\n  ): Promise<Row | null>;\n  count(table: AppKitTable, where?: WhereClause): Promise<number>;\n  /** Return exactly one inserted row; zero or many is an invariant failure. */\n  insert(table: AppKitTable, values: Row): Promise<Row>;\n  /** Return null for zero updated rows and reject more than one. */\n  update(table: AppKitTable, id: IdValue, values: Row): Promise<Row | null>;\n  /** Return exactly one row for a validated primary-key or unique conflict. */\n  upsert(table: AppKitTable, values: Row, onConflict: string): Promise<Row>;\n  /** Return false for zero deleted rows, true for one, and reject many. */\n  delete(table: AppKitTable, id: IdValue): Promise<boolean>;\n  /** Execute tagged SQL whose interpolations are parameter values, not SQL. */\n  raw<T = Row>(\n    strings: TemplateStringsArray,\n    ...values: unknown[]\n  ): Promise<T[]>;\n  /** Run the callback with one transaction-bound DataPath. */\n  transaction<T>(callback: (tx: DataPath) => Promise<T>): Promise<T>;\n}\n\n/** Validate an explicit root or relation row limit. */\nexport function validateLimit(limit: number): number {\n  if (!Number.isInteger(limit) || limit < 0 || limit > MAX_LIMIT) {\n    throw invalidDatabaseRequest(\n      `limit must be an integer between 0 and ${MAX_LIMIT}`,\n    );\n  }\n  return limit;\n}\n\n/** Apply the conservative collection default when no limit is supplied. */\nexport function limitOrDefault(limit?: number): number {\n  return limit === undefined ? DEFAULT_LIMIT : validateLimit(limit);\n}\n\n/** Validate an explicit root or relation row offset. */\nexport function validateOffset(offset: number): number {\n  if (!Number.isSafeInteger(offset) || offset < 0 || offset > MAX_OFFSET) {\n    throw invalidDatabaseRequest(\n      `offset must be an integer between 0 and ${MAX_OFFSET}`,\n    );\n  }\n  return offset;\n}\n\n/** Resolve the sole primary key required by keyed operations. */\nexport function primaryKeyMeta(table: AppKitTable): ColumnMeta {\n  const primaryKeys = Object.values(table.$columns).filter(\n    (column) => column.primaryKey,\n  );\n  if (primaryKeys.length !== 1) {\n    throw invalidDatabaseRequest(`Table \"${table.$name}\" has no primary key`);\n  }\n  return primaryKeys[0];\n}\n\n/** Resolve an upsert target that PostgreSQL can use for conflict detection. */\nexport function conflictTargetMeta(\n  table: AppKitTable,\n  columnName: string,\n): ColumnMeta {\n  const column = table.$columns[columnName];\n  if (!column || (!column.primaryKey && !column.unique)) {\n    throw invalidDatabaseRequest(\n      `Column \"${table.$name}.${columnName}\" is not a conflict target`,\n    );\n  }\n  return column;\n}\n"],"mappings":";;;;;;AAiDA,SAAgB,SACd,UACA,MACa;AACb,QAAO,aAAa,SAAY,OAAO,EAAE,KAAK,CAAC,UAAU,KAAK,EAAE;;;AAgClE,SAAgB,cAAc,OAAuB;AACnD,KAAI,CAAC,OAAO,UAAU,MAAM,IAAI,QAAQ,KAAK,QAAQ,UACnD,OAAM,uBACJ,0CAA0C,YAC3C;AAEH,QAAO;;;AAIT,SAAgB,eAAe,OAAwB;AACrD,QAAO,UAAU,SAAY,gBAAgB,cAAc,MAAM;;;AAInE,SAAgB,eAAe,QAAwB;AACrD,KAAI,CAAC,OAAO,cAAc,OAAO,IAAI,SAAS,KAAK,SAAS,WAC1D,OAAM,uBACJ,2CAA2C,aAC5C;AAEH,QAAO;;;AAIT,SAAgB,eAAe,OAAgC;CAC7D,MAAM,cAAc,OAAO,OAAO,MAAM,SAAS,CAAC,QAC/C,WAAW,OAAO,WACpB;AACD,KAAI,YAAY,WAAW,EACzB,OAAM,uBAAuB,UAAU,MAAM,MAAM,sBAAsB;AAE3E,QAAO,YAAY;;;AAIrB,SAAgB,mBACd,OACA,YACY;CACZ,MAAM,SAAS,MAAM,SAAS;AAC9B,KAAI,CAAC,UAAW,CAAC,OAAO,cAAc,CAAC,OAAO,OAC5C,OAAM,uBACJ,WAAW,MAAM,MAAM,GAAG,WAAW,4BACtC;AAEH,QAAO"}
+{"version":3,"file":"data-path.js","names":[],"sources":["../../../src/database/runtime/data-path.ts"],"sourcesContent":["import {\n  DEFAULT_LIMIT,\n  type FilterOperator,\n  type IdValue,\n  MAX_LIMIT,\n  MAX_OFFSET,\n  type OrderDirection,\n} from \"../contract\";\nimport { invalidDatabaseRequest } from \"../errors\";\nimport type { AppKitTable, ColumnMeta } from \"../schema-builder\";\n\nexport type { IdValue, OrderDirection };\nexport type ScalarValue = string | number | bigint | boolean | null;\n/** Operators for one column; array operands are reserved for `in`. */\nexport type FilterOps = Partial<\n  Record<FilterOperator, ScalarValue | readonly ScalarValue[]>\n>;\nexport type WhereValue = ScalarValue | readonly ScalarValue[] | FilterOps;\n/** Direct-column predicates with explicit `and` and `or` predicate groups. */\nexport type WhereClause = Readonly<\n  Record<string, WhereValue | readonly WhereClause[]>\n>;\n\nexport type OrderSpec = Readonly<Record<string, OrderDirection>>;\n\nexport interface IncludeOptions {\n  readonly select?: readonly string[];\n  readonly where?: WhereClause;\n  readonly order?: OrderSpec;\n  readonly limit?: number;\n  readonly include?: IncludeSpec;\n}\n\n/** Selection and bounds for one declared relation edge. */\nexport type IncludeSpec = Readonly<Record<string, boolean | IncludeOptions>>;\n\n/** A bounded root read; adapters apply defaults and validate explicit bounds. */\nexport interface QuerySpec {\n  readonly where?: WhereClause;\n  readonly order?: OrderSpec;\n  readonly select?: readonly string[];\n  readonly include?: IncludeSpec;\n  readonly limit?: number;\n  readonly offset?: number;\n}\n\nexport type Row = Record<string, unknown>;\n\n/** Combine predicates without making callers understand the wire shape. */\nexport function andWhere(\n  existing: WhereClause | undefined,\n  next: WhereClause,\n): WhereClause {\n  return existing === undefined ? next : { and: [existing, next] };\n}\n\n/** Internal AppKit execution port; field names are schema-owned identifiers. */\nexport interface DataPath {\n  /** Read a bounded collection from one finalized table. */\n  select(table: AppKitTable, spec: QuerySpec): Promise<Row[]>;\n  /** Read by the sole primary key while preserving supported query state. */\n  findOne(\n    table: AppKitTable,\n    id: IdValue,\n    spec?: Pick<QuerySpec, \"where\" | \"select\" | \"include\">,\n  ): Promise<Row | null>;\n  count(table: AppKitTable, where?: WhereClause): Promise<number>;\n  /** Return exactly one inserted row; zero or many is an invariant failure. */\n  insert(table: AppKitTable, values: Row): Promise<Row>;\n  /** Return null for zero updated rows and reject more than one. */\n  update(\n    table: AppKitTable,\n    id: IdValue,\n    values: Row,\n    where?: WhereClause,\n  ): Promise<Row | null>;\n  /** Return exactly one row for a validated primary-key or unique conflict. */\n  upsert(table: AppKitTable, values: Row, onConflict: string): Promise<Row>;\n  /** Return false for zero deleted rows, true for one, and reject many. */\n  delete(\n    table: AppKitTable,\n    id: IdValue,\n    where?: WhereClause,\n  ): Promise<boolean>;\n  /** Execute tagged SQL whose interpolations are parameter values, not SQL. */\n  raw<T = Row>(\n    strings: TemplateStringsArray,\n    ...values: unknown[]\n  ): Promise<T[]>;\n  /** Run the callback with one transaction-bound DataPath. */\n  transaction<T>(callback: (tx: DataPath) => Promise<T>): Promise<T>;\n}\n\n/** Validate an explicit root or relation row limit. */\nexport function validateLimit(limit: number): number {\n  if (!Number.isInteger(limit) || limit < 0 || limit > MAX_LIMIT) {\n    throw invalidDatabaseRequest(\n      `limit must be an integer between 0 and ${MAX_LIMIT}`,\n    );\n  }\n  return limit;\n}\n\n/** Apply the conservative collection default when no limit is supplied. */\nexport function limitOrDefault(limit?: number): number {\n  return limit === undefined ? DEFAULT_LIMIT : validateLimit(limit);\n}\n\n/** Validate an explicit root or relation row offset. */\nexport function validateOffset(offset: number): number {\n  if (!Number.isSafeInteger(offset) || offset < 0 || offset > MAX_OFFSET) {\n    throw invalidDatabaseRequest(\n      `offset must be an integer between 0 and ${MAX_OFFSET}`,\n    );\n  }\n  return offset;\n}\n\n/** Resolve the sole primary key required by keyed operations. */\nexport function primaryKeyMeta(table: AppKitTable): ColumnMeta {\n  const primaryKeys = Object.values(table.$columns).filter(\n    (column) => column.primaryKey,\n  );\n  if (primaryKeys.length !== 1) {\n    throw invalidDatabaseRequest(`Table \"${table.$name}\" has no primary key`);\n  }\n  return primaryKeys[0];\n}\n\n/** Resolve an upsert target that PostgreSQL can use for conflict detection. */\nexport function conflictTargetMeta(\n  table: AppKitTable,\n  columnName: string,\n): ColumnMeta {\n  const column = table.$columns[columnName];\n  if (!column || (!column.primaryKey && !column.unique)) {\n    throw invalidDatabaseRequest(\n      `Column \"${table.$name}.${columnName}\" is not a conflict target`,\n    );\n  }\n  return column;\n}\n"],"mappings":";;;;;;AAiDA,SAAgB,SACd,UACA,MACa;AACb,QAAO,aAAa,SAAY,OAAO,EAAE,KAAK,CAAC,UAAU,KAAK,EAAE;;;AAyClE,SAAgB,cAAc,OAAuB;AACnD,KAAI,CAAC,OAAO,UAAU,MAAM,IAAI,QAAQ,KAAK,QAAQ,UACnD,OAAM,uBACJ,0CAA0C,YAC3C;AAEH,QAAO;;;AAIT,SAAgB,eAAe,OAAwB;AACrD,QAAO,UAAU,SAAY,gBAAgB,cAAc,MAAM;;;AAInE,SAAgB,eAAe,QAAwB;AACrD,KAAI,CAAC,OAAO,cAAc,OAAO,IAAI,SAAS,KAAK,SAAS,WAC1D,OAAM,uBACJ,2CAA2C,aAC5C;AAEH,QAAO;;;AAIT,SAAgB,eAAe,OAAgC;CAC7D,MAAM,cAAc,OAAO,OAAO,MAAM,SAAS,CAAC,QAC/C,WAAW,OAAO,WACpB;AACD,KAAI,YAAY,WAAW,EACzB,OAAM,uBAAuB,UAAU,MAAM,MAAM,sBAAsB;AAE3E,QAAO,YAAY;;;AAIrB,SAAgB,mBACd,OACA,YACY;CACZ,MAAM,SAAS,MAAM,SAAS;AAC9B,KAAI,CAAC,UAAW,CAAC,OAAO,cAAc,CAAC,OAAO,OAC5C,OAAM,uBACJ,WAAW,MAAM,MAAM,GAAG,WAAW,4BACtC;AAEH,QAAO"}

package/dist/database/runtime/engine/drizzle-data-path.js

@@ -2,7 +2,7 @@ import { createLogger } from "../../../logging/logger.js";
 import { columnValueSchema } from "../../schema-builder/validators.js";
 import { DatabasePluginError, invalidDatabaseRequest } from "../../errors.js";
 import { buildEngineRelations } from "../../schema-builder/engine/relations.js";
-import { conflictTargetMeta, limitOrDefault, primaryKeyMeta, validateOffset } from "../data-path.js";
+import { andWhere, conflictTargetMeta, limitOrDefault, primaryKeyMeta, validateOffset } from "../data-path.js";
 import { columnOf, defaultColumns, publicColumnNames, returningColumns, selectToColumns, translateInclude, translateOrder, translateWhere } from "./translate.js";
 import { and, eq, isSQLWrapper, sql } from "drizzle-orm";
 import { drizzle } from "drizzle-orm/node-postgres";
@@ -113,6 +113,8 @@ function createDrizzleDataPath(db, schema, options = {}) {
 		return table.$engine;
 	};
 	const whereSql = (table, where) => where === void 0 ? void 0 : translateWhere(table, where, columnAccess);
+	/** Narrow by the primary key while preserving an accumulated predicate. */
+	const keyedWhere = (table, primaryKey, id, where) => where === void 0 ? eq(columnOf(table, primaryKey.columnName), id) : translateWhere(table, andWhere({ [primaryKey.columnName]: { eq: id } }, where), columnAccess);
 	return {
 		async select(table, spec) {
 			return runDatabaseOperation(() => relationalQueryBuilder(db, schema, table).findMany({
@@ -142,11 +144,11 @@ function createDrizzleDataPath(db, schema, options = {}) {
 			const parameters = mutationValues(table, values, "insert");
 			return expectExactlyOne(mutationRows(table, await runDatabaseOperation(() => db.insert(engineTable).values(parameters).returning(returningColumns(table, columnAccess))), columnAccess));
 		},
-		async update(table, id, values) {
+		async update(table, id, values, where) {
 			const engineTable = pgTable(table);
 			const parameters = mutationValues(table, values, "update");
 			const { meta: primaryKey, value: validatedId } = validatedPrimaryKey(table, id);
-			return expectZeroOrOne(mutationRows(table, await runDatabaseOperation(() => db.update(engineTable).set(parameters).where(eq(columnOf(table, primaryKey.columnName), validatedId)).returning(returningColumns(table, columnAccess))), columnAccess));
+			return expectZeroOrOne(mutationRows(table, await runDatabaseOperation(() => db.update(engineTable).set(parameters).where(keyedWhere(table, primaryKey, validatedId, where)).returning(returningColumns(table, columnAccess))), columnAccess));
 		},
 		async upsert(table, values, onConflict) {
 			const engineTable = pgTable(table);
@@ -158,9 +160,9 @@ function createDrizzleDataPath(db, schema, options = {}) {
 				set: updates
 			}).returning(returningColumns(table, columnAccess))), columnAccess));
 		},
-		async delete(table, id) {
+		async delete(table, id, where) {
 			const { meta: primaryKey, value: validatedId } = validatedPrimaryKey(table, id);
-			return expectZeroOrOne(await runDatabaseOperation(() => db.delete(pgTable(table)).where(eq(columnOf(table, primaryKey.columnName), validatedId)).returning({ id: columnOf(table, primaryKey.columnName) }))) !== null;
+			return expectZeroOrOne(await runDatabaseOperation(() => db.delete(pgTable(table)).where(keyedWhere(table, primaryKey, validatedId, where)).returning({ id: columnOf(table, primaryKey.columnName) }))) !== null;
 		},
 		async raw(strings, ...values) {
 			if (values.some((value) => isSQLWrapper(value))) throw invalidDatabaseRequest("Tagged SQL interpolations must be parameter values");