@typed-sql/core 1.0.0 → 2.0.0-rc.1

package/CHANGELOG.md

@@ -1,5 +1,55 @@
 # @typed-sql/core
 
+## 2.0.0-rc.1
+
+### Patch Changes
+
+- Publish the coherent 2.0.0-rc.1 release-candidate train.
+
+## 2.0.0-rc.0
+
+### Major Changes
+
+- 29afc3d: Add conservative semantic primary/replica routing over application-owned databases, scoped
+  read-after-write pinning, explicit role requirements, stable unsafe-route errors, dialect runtime
+  semantic resolvers, and bounded abortable transaction retry policies with native PostgreSQL and
+  MySQL error classifiers. Parse and classify dialect locking reads so uncertain or affine work
+  always fails closed to primary.
+- 3f063f6: Add deterministic, secret-free query manifests with bounded structural variants, inferred result
+  and parameter descriptions, semantic evidence, runtime-correlatable fingerprints, unresolved
+  entries, compatible parsing, canonical serialization, incremental per-file reuse, tsconfig project
+  discovery, and a dedicated CLI command.
+- 6a7ae58: Add opt-in live query verification through grammar-owned PostgreSQL PREPARE and MySQL
+  COM_STMT_PREPARE adapters, bounded neutral comparison, deterministic secret-free proof artifacts,
+  offline cache validation, explicit unsupported classifications, CLI workflows, real database E2E,
+  and performance budgets.
+- b06fd0a: Add grammar-neutral optional adapter capability discovery, typed PostgreSQL COPY import and export
+  through application-owned `pg-copy-streams`, and typed MySQL LOAD DATA import through mysql2's
+  application-owned infile stream. Bulk transfers preserve ordinary `INSERT` parameter evidence,
+  enforce structural row stability, apply bounded backpressure, support cancellation and progress,
+  and integrate with transaction ownership and conservative connection cleanup.
+- 3050209: Add the dialect contract v4 semantic query evidence foundation. PostgreSQL and MySQL now report operation, dependencies, cardinality, volatility, locking, connection affinity, and required capabilities; compiler results add deterministic query and structural-variant fingerprints and conservatively merged source-mapped semantics. Schema snapshots can record function volatility, and the AST package exposes a neutral statement walker for grammar implementations.
+- 1b054b6: Add an adapter-neutral, redacted database observation lifecycle for queries, cardinality contracts,
+  batches, PostgreSQL pipelines, streams, cancellation, and nested transactions. Runtime fingerprints
+  correlate with compiler structural variants while SQL, parameter values, connection configuration,
+  and driver causes remain excluded by default. Publish the optional OpenTelemetry bridge with current
+  database semantic conventions and explicit high-cardinality or exception-capture opt-ins.
+- b4f1b6e: Add deterministic migration compatibility analysis across before/after schema snapshots and query
+  manifests. Reports classify both rolling-deployment directions, retain exact source and dependency
+  evidence, fail closed for unknown semantics, redact defaults and paths, and support configurable CI
+  severity through `typed-sql compat`.
+- 87189c3: Add grammar-neutral `all`, `one`, and `maybeOne` execution with exact row types, stable cardinality
+  and cancellation errors, explicit adapter capabilities, AbortSignal support, and absolute deadlines.
+  The pg and mysql2 adapters conservatively discard interrupted connections, including transaction
+  leases, while the existing uncontrolled `execute` path remains unchanged.
+- e654fae: Add opt-in Standard Schema V1 result validation with compile-time output compatibility, immutable
+  query attachment, sync and async validators, redacted fingerprinted errors, and consistent decoded-row
+  handling across buffered cardinality methods, batches, PostgreSQL pipelines, streams, and transactions.
+- b2ec119: Add opt-in, grammar-neutral query-plan governance with PostgreSQL and MySQL structured EXPLAIN
+  adapters, transient application-owned samples, redacted fingerprint-keyed artifacts, absolute and
+  comparable regression budgets, explicit uncertainty, CLI capture and review, documentation, and
+  performance coverage.
+
 ## 1.0.0
 
 ### Major Changes

package/README.md

@@ -26,13 +26,36 @@ type Account = QueryRow<typeof query>;
 type Parameters = QueryParameters<typeof query>;
 ```
 
+Runtime adapters share grammar-neutral result and control contracts: `all`, `one`, and `maybeOne`
+preserve the inferred row, accept optional signals or absolute deadlines, and expose stable
+cardinality and cancellation errors. Adapter capabilities are explicit; unsupported controls are
+never silently ignored.
+
+Optional adapter services use namespaced capability tokens rather than widening the common
+`Database` interface. `getAdapterCapability` and `requireAdapterCapability` preserve the service
+type without adding a protocol or driver dependency to core.
+
+`DatabaseObserver` provides redacted query, batch, pipeline, stream, cancellation, and nested
+transaction lifecycles. It is disabled by default and does not add a telemetry dependency to core.
+
+`sql.validateResult(query, schema)` optionally validates decoded rows through the structural
+Standard Schema V1 interface. Validator output must agree with the inferred row; core does not
+install Zod, Valibot, or another validator package.
+
+`createRoutedDatabase` provides conservative, grammar-neutral primary/replica selection and bounded
+explicit-transaction retries from semantic evidence. Dialect packages supply the semantic resolver;
+applications continue owning every database adapter and topology decision.
+
 Grammar and adapter authors can use `DialectPlugin`, `DIALECT_CONTRACT_VERSION`,
-`assertDialectPlugin`, `createDatabase`, `renderQuery`, the prepared-query skeleton helpers, and
-the neutral resolver primitives from the package root. The package has no parser, grammar,
+`assertDialectPlugin`, `defineQuerySemantics`, `mergeQuerySemantics`, `createDatabase`, `renderQuery`,
+the prepared-query skeleton helpers, and the neutral resolver primitives from the package root. The package has no parser, grammar,
 database driver, TypeScript compiler, or editor dependency.
 
 Read the [query API](https://github.com/Lojhan/typed-sql/blob/main/docs/reference/api.md),
-[architecture](https://github.com/Lojhan/typed-sql/blob/main/docs/concepts/architecture.md), and
+[architecture](https://github.com/Lojhan/typed-sql/blob/main/docs/concepts/architecture.md),
+[routing and retry guide](https://github.com/Lojhan/typed-sql/blob/main/docs/guides/routing-and-retries.md),
+[bulk data guide](https://github.com/Lojhan/typed-sql/blob/main/docs/guides/bulk-data.md),
+[result validation guide](https://github.com/Lojhan/typed-sql/blob/main/docs/guides/result-validation.md), and
 [custom grammar guide](https://github.com/Lojhan/typed-sql/blob/main/docs/extending/custom-grammars.md).
 
 MIT © typed-sql contributors

package/dist/packages/core/src/adapter-capabilities.d.ts

@@ -0,0 +1,30 @@
+declare const adapterCapabilityBrand: unique symbol;
+/** A namespaced token describing one optional service exposed by a database adapter. */
+export interface AdapterCapability<Service> {
+    readonly id: string;
+    readonly key: symbol;
+    readonly [adapterCapabilityBrand]: () => Service;
+}
+export type AdapterCapabilityService<Capability> = Capability extends AdapterCapability<infer Service> ? Service : never;
+export type AdapterCapabilityResolver = (key: symbol) => unknown;
+export declare const adapterCapabilities: unique symbol;
+/** Structural host contract implemented by adapters that provide optional services. */
+export interface AdapterCapabilityHost {
+    readonly [adapterCapabilities]?: AdapterCapabilityResolver;
+}
+export declare class UnsupportedAdapterCapabilityError extends Error {
+    readonly code = "TSQL_UNSUPPORTED_ADAPTER_CAPABILITY";
+    readonly capability: string;
+    constructor(capability: string);
+}
+/** Defines a globally stable, namespaced adapter capability token. */
+export declare function defineAdapterCapability<Service>(id: string): AdapterCapability<Service>;
+/** Creates the immutable resolver installed on one adapter or transaction scope. */
+export declare function createAdapterCapabilityResolver(entries: readonly (readonly [AdapterCapability<unknown>, unknown])[]): AdapterCapabilityResolver;
+/** Returns an optional adapter service without importing its driver or protocol package. */
+export declare function getAdapterCapability<Service>(host: unknown, capability: AdapterCapability<Service>): Service | undefined;
+export declare function hasAdapterCapability<Service>(host: unknown, capability: AdapterCapability<Service>): boolean;
+/** Resolves an adapter service or throws a stable fail-closed error. */
+export declare function requireAdapterCapability<Service>(host: unknown, capability: AdapterCapability<Service>): Service;
+export {};
+//# sourceMappingURL=adapter-capabilities.d.ts.map

package/dist/packages/core/src/adapter-capabilities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter-capabilities.d.ts","sourceRoot":"","sources":["../../../../src/adapter-capabilities.ts"],"names":[],"mappings":"AAAA,QAAA,MAAM,sBAAsB,EAAE,OAAO,MAA8D,CAAC;AAEpG,wFAAwF;AACxF,MAAM,WAAW,iBAAiB,CAAC,OAAO;IACxC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,CAAC,sBAAsB,CAAC,EAAE,MAAM,OAAO,CAAC;CAClD;AAED,MAAM,MAAM,wBAAwB,CAAC,UAAU,IAC7C,UAAU,SAAS,iBAAiB,CAAC,MAAM,OAAO,CAAC,GAAG,OAAO,GAAG,KAAK,CAAC;AAExE,MAAM,MAAM,yBAAyB,GAAG,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;AAEjE,eAAO,MAAM,mBAAmB,EAAE,OAAO,MAAoE,CAAC;AAE9G,uFAAuF;AACvF,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,CAAC,mBAAmB,CAAC,CAAC,EAAE,yBAAyB,CAAC;CAC5D;AAED,qBAAa,iCAAkC,SAAQ,KAAK;IAC1D,QAAQ,CAAC,IAAI,yCAAyC;IACtD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAE5B,YAAY,UAAU,EAAE,MAAM,EAI7B;CACF;AAED,sEAAsE;AACtE,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,EAAE,EAAE,MAAM,GAAG,iBAAiB,CAAC,OAAO,CAAC,CAWvF;AAED,oFAAoF;AACpF,wBAAgB,+BAA+B,CAC7C,OAAO,EAAE,SAAS,CAAC,SAAS,CAAC,iBAAiB,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,CAAC,EAAE,GACnE,yBAAyB,CAO3B;AAED,4FAA4F;AAC5F,wBAAgB,oBAAoB,CAAC,OAAO,EAC1C,IAAI,EAAE,OAAO,EACb,UAAU,EAAE,iBAAiB,CAAC,OAAO,CAAC,GACrC,OAAO,GAAG,SAAS,CAIrB;AAED,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,UAAU,EAAE,iBAAiB,CAAC,OAAO,CAAC,GAAG,OAAO,CAE5G;AAED,wEAAwE;AACxE,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,UAAU,EAAE,iBAAiB,CAAC,OAAO,CAAC,GAAG,OAAO,CAIhH"}

package/dist/packages/core/src/adapter-capabilities.js

@@ -0,0 +1,52 @@
+const adapterCapabilityBrand = Symbol("@typed-sql/core.adapter-capability");
+export const adapterCapabilities = Symbol.for("@typed-sql/core.adapter-capabilities");
+export class UnsupportedAdapterCapabilityError extends Error {
+    code = "TSQL_UNSUPPORTED_ADAPTER_CAPABILITY";
+    capability;
+    constructor(capability) {
+        super(`This database adapter does not provide the ${capability} capability`);
+        this.name = "UnsupportedAdapterCapabilityError";
+        this.capability = capability;
+    }
+}
+/** Defines a globally stable, namespaced adapter capability token. */
+export function defineAdapterCapability(id) {
+    if (id.length === 0 || !id.includes(".")) {
+        throw new TypeError("Adapter capability ids must be non-empty and namespaced, for example vendor.feature");
+    }
+    return Object.freeze({
+        id,
+        key: Symbol.for(`@typed-sql/adapter-capability/${id}`),
+        [adapterCapabilityBrand]: () => {
+            throw new TypeError("Adapter capability type brands are not callable");
+        },
+    });
+}
+/** Creates the immutable resolver installed on one adapter or transaction scope. */
+export function createAdapterCapabilityResolver(entries) {
+    const services = new Map();
+    for (const [capability, service] of entries) {
+        if (services.has(capability.key))
+            throw new TypeError(`Duplicate adapter capability: ${capability.id}`);
+        services.set(capability.key, service);
+    }
+    return (key) => services.get(key);
+}
+/** Returns an optional adapter service without importing its driver or protocol package. */
+export function getAdapterCapability(host, capability) {
+    if ((typeof host !== "object" && typeof host !== "function") || host === null)
+        return undefined;
+    const resolver = host[adapterCapabilities];
+    return resolver?.(capability.key);
+}
+export function hasAdapterCapability(host, capability) {
+    return getAdapterCapability(host, capability) !== undefined;
+}
+/** Resolves an adapter service or throws a stable fail-closed error. */
+export function requireAdapterCapability(host, capability) {
+    const service = getAdapterCapability(host, capability);
+    if (service === undefined)
+        throw new UnsupportedAdapterCapabilityError(capability.id);
+    return service;
+}
+//# sourceMappingURL=adapter-capabilities.js.map

package/dist/packages/core/src/adapter-capabilities.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter-capabilities.js","sourceRoot":"","sources":["../../../../src/adapter-capabilities.ts"],"names":[],"mappings":"AAAA,MAAM,sBAAsB,GAAkB,MAAM,CAAC,oCAAoC,CAAU,CAAC;AAcpG,MAAM,CAAC,MAAM,mBAAmB,GAAkB,MAAM,CAAC,GAAG,CAAC,sCAAsC,CAAU,CAAC;AAO9G,MAAM,OAAO,iCAAkC,SAAQ,KAAK;IACjD,IAAI,GAAG,qCAAqC,CAAC;IAC7C,UAAU,CAAS;IAE5B,YAAY,UAAkB;QAC5B,KAAK,CAAC,8CAA8C,UAAU,aAAa,CAAC,CAAC;QAC7E,IAAI,CAAC,IAAI,GAAG,mCAAmC,CAAC;QAChD,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;IAC/B,CAAC;CACF;AAED,sEAAsE;AACtE,MAAM,UAAU,uBAAuB,CAAU,EAAU;IACzD,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;QACzC,MAAM,IAAI,SAAS,CAAC,qFAAqF,CAAC,CAAC;IAC7G,CAAC;IACD,OAAO,MAAM,CAAC,MAAM,CAAC;QACnB,EAAE;QACF,GAAG,EAAE,MAAM,CAAC,GAAG,CAAC,iCAAiC,EAAE,EAAE,CAAC;QACtD,CAAC,sBAAsB,CAAC,EAAE,GAAY,EAAE;YACtC,MAAM,IAAI,SAAS,CAAC,iDAAiD,CAAC,CAAC;QACzE,CAAC;KACF,CAAC,CAAC;AACL,CAAC;AAED,oFAAoF;AACpF,MAAM,UAAU,+BAA+B,CAC7C,OAAoE;IAEpE,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAmB,CAAC;IAC5C,KAAK,MAAM,CAAC,UAAU,EAAE,OAAO,CAAC,IAAI,OAAO,EAAE,CAAC;QAC5C,IAAI,QAAQ,CAAC,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC;YAAE,MAAM,IAAI,SAAS,CAAC,iCAAiC,UAAU,CAAC,EAAE,EAAE,CAAC,CAAC;QACxG,QAAQ,CAAC,GAAG,CAAC,UAAU,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;IACxC,CAAC;IACD,OAAO,CAAC,GAAW,EAAW,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AACrD,CAAC;AAED,4FAA4F;AAC5F,MAAM,UAAU,oBAAoB,CAClC,IAAa,EACb,UAAsC;IAEtC,IAAI,CAAC,OAAO,IAAI,KAAK,QAAQ,IAAI,OAAO,IAAI,KAAK,UAAU,CAAC,IAAI,IAAI,KAAK,IAAI;QAAE,OAAO,SAAS,CAAC;IAChG,MAAM,QAAQ,GAAI,IAA8B,CAAC,mBAAmB,CAAC,CAAC;IACtE,OAAO,QAAQ,EAAE,CAAC,UAAU,CAAC,GAAG,CAAwB,CAAC;AAC3D,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAU,IAAa,EAAE,UAAsC;IACjG,OAAO,oBAAoB,CAAC,IAAI,EAAE,UAAU,CAAC,KAAK,SAAS,CAAC;AAC9D,CAAC;AAED,wEAAwE;AACxE,MAAM,UAAU,wBAAwB,CAAU,IAAa,EAAE,UAAsC;IACrG,MAAM,OAAO,GAAG,oBAAoB,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;IACvD,IAAI,OAAO,KAAK,SAAS;QAAE,MAAM,IAAI,iCAAiC,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC;IACtF,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/packages/core/src/diagnostics.d.ts

@@ -15,6 +15,10 @@ export declare const diagnosticRegistry: Readonly<{
         readonly category: "contract";
         readonly summary: "Structural SQL requires an explicitly trusted fragment.";
     };
+    readonly TSQ005: {
+        readonly category: "support";
+        readonly summary: "Runtime SQL cannot be analyzed statically.";
+    };
     readonly TSQ007: {
         readonly category: "contract";
         readonly summary: "The schema snapshot and dialect do not match.";
@@ -111,6 +115,18 @@ export declare const diagnosticRegistry: Readonly<{
         readonly category: "support";
         readonly summary: "The dialect surface is intentionally unsupported.";
     };
+    readonly TSQ500: {
+        readonly category: "verification";
+        readonly summary: "Live database metadata differs from compiler evidence.";
+    };
+    readonly TSQ501: {
+        readonly category: "verification";
+        readonly summary: "A query could not be verified safely or statically.";
+    };
+    readonly TSQ502: {
+        readonly category: "verification";
+        readonly summary: "Native live verification failed without persisting driver details.";
+    };
 }>;
 export type TypedSqlDiagnosticCode = keyof typeof diagnosticRegistry;
 export declare function isTypedSqlDiagnosticCode(value: string): value is TypedSqlDiagnosticCode;

package/dist/packages/core/src/diagnostics.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"diagnostics.d.ts","sourceRoot":"","sources":["../../../../src/diagnostics.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,kBAAkB;;iBACnB,QAAQ,EAAE,QAAQ;iBAAE,OAAO,EAAE,iCAAiC;;;iBAC9D,QAAQ,EAAE,UAAU;iBAAE,OAAO,EAAE,uCAAuC;;;iBACtE,QAAQ,EAAE,UAAU;iBAAE,OAAO,EAAE,wDAAwD;;;iBACvF,QAAQ,EAAE,UAAU;iBAAE,OAAO,EAAE,yDAAyD;;;iBACxF,QAAQ,EAAE,UAAU;iBAAE,OAAO,EAAE,+CAA+C;;;iBAC9E,QAAQ,EAAE,QAAQ;iBAAE,OAAO,EAAE,oCAAoC;;;iBACjE,QAAQ,EAAE,QAAQ;iBAAE,OAAO,EAAE,qCAAqC;;;iBAClE,QAAQ,EAAE,QAAQ;iBAAE,OAAO,EAAE,kCAAkC;;;iBAC/D,QAAQ,EAAE,QAAQ;iBAAE,OAAO,EAAE,kDAAkD;;;iBAC/E,QAAQ,EAAE,QAAQ;iBAAE,OAAO,EAAE,oDAAoD;;;iBACjF,QAAQ,EAAE,QAAQ;iBAAE,OAAO,EAAE,oDAAoD;;;iBACjF,QAAQ,EAAE,MAAM;iBAAE,OAAO,EAAE,sCAAsC;;;iBACjE,QAAQ,EAAE,QAAQ;iBAAE,OAAO,EAAE,yCAAyC;;;iBACtE,QAAQ,EAAE,QAAQ;iBAAE,OAAO,EAAE,iCAAiC;;;iBAC9D,QAAQ,EAAE,MAAM;iBAAE,OAAO,EAAE,wBAAwB;;;iBACnD,QAAQ,EAAE,MAAM;iBAAE,OAAO,EAAE,wCAAwC;;;iBACnE,QAAQ,EAAE,MAAM;iBAAE,OAAO,EAAE,mCAAmC;;;iBAC9D,QAAQ,EAAE,MAAM;iBAAE,OAAO,EAAE,4DAA4D;;;iBACvF,QAAQ,EAAE,SAAS;iBAAE,OAAO,EAAE,kDAAkD;;;iBAChF,QAAQ,EAAE,QAAQ;iBAAE,OAAO,EAAE,2BAA2B;;;iBACxD,QAAQ,EAAE,QAAQ;iBAAE,OAAO,EAAE,6BAA6B;;;iBAC1D,QAAQ,EAAE,QAAQ;iBAAE,OAAO,EAAE,wCAAwC;;;iBACrE,QAAQ,EAAE,QAAQ;iBAAE,OAAO,EAAE,0CAA0C;;;iBACvE,QAAQ,EAAE,QAAQ;iBAAE,OAAO,EAAE,kDAAkD;;;iBAC/E,QAAQ,EAAE,QAAQ;iBAAE,OAAO,EAAE,uDAAuD;;;iBACpF,QAAQ,EAAE,QAAQ;iBAAE,OAAO,EAAE,oDAAoD;;;iBACjF,QAAQ,EAAE,OAAO;iBAAE,OAAO,EAAE,qEAAqE;;;iBACjG,QAAQ,EAAE,SAAS;iBAAE,OAAO,EAAE,mDAAmD;;EAClF,CAAC;AAEZ,MAAM,MAAM,sBAAsB,GAAG,MAAM,OAAO,kBAAkB,CAAC;AAErE,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,sBAAsB,CAEvF"}
+{"version":3,"file":"diagnostics.d.ts","sourceRoot":"","sources":["../../../../src/diagnostics.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,kBAAkB;;iBACnB,QAAQ,EAAE,QAAQ;iBAAE,OAAO,EAAE,iCAAiC;;;iBAC9D,QAAQ,EAAE,UAAU;iBAAE,OAAO,EAAE,uCAAuC;;;iBACtE,QAAQ,EAAE,UAAU;iBAAE,OAAO,EAAE,wDAAwD;;;iBACvF,QAAQ,EAAE,UAAU;iBAAE,OAAO,EAAE,yDAAyD;;;iBACxF,QAAQ,EAAE,SAAS;iBAAE,OAAO,EAAE,4CAA4C;;;iBAC1E,QAAQ,EAAE,UAAU;iBAAE,OAAO,EAAE,+CAA+C;;;iBAC9E,QAAQ,EAAE,QAAQ;iBAAE,OAAO,EAAE,oCAAoC;;;iBACjE,QAAQ,EAAE,QAAQ;iBAAE,OAAO,EAAE,qCAAqC;;;iBAClE,QAAQ,EAAE,QAAQ;iBAAE,OAAO,EAAE,kCAAkC;;;iBAC/D,QAAQ,EAAE,QAAQ;iBAAE,OAAO,EAAE,kDAAkD;;;iBAC/E,QAAQ,EAAE,QAAQ;iBAAE,OAAO,EAAE,oDAAoD;;;iBACjF,QAAQ,EAAE,QAAQ;iBAAE,OAAO,EAAE,oDAAoD;;;iBACjF,QAAQ,EAAE,MAAM;iBAAE,OAAO,EAAE,sCAAsC;;;iBACjE,QAAQ,EAAE,QAAQ;iBAAE,OAAO,EAAE,yCAAyC;;;iBACtE,QAAQ,EAAE,QAAQ;iBAAE,OAAO,EAAE,iCAAiC;;;iBAC9D,QAAQ,EAAE,MAAM;iBAAE,OAAO,EAAE,wBAAwB;;;iBACnD,QAAQ,EAAE,MAAM;iBAAE,OAAO,EAAE,wCAAwC;;;iBACnE,QAAQ,EAAE,MAAM;iBAAE,OAAO,EAAE,mCAAmC;;;iBAC9D,QAAQ,EAAE,MAAM;iBAAE,OAAO,EAAE,4DAA4D;;;iBACvF,QAAQ,EAAE,SAAS;iBAAE,OAAO,EAAE,kDAAkD;;;iBAChF,QAAQ,EAAE,QAAQ;iBAAE,OAAO,EAAE,2BAA2B;;;iBACxD,QAAQ,EAAE,QAAQ;iBAAE,OAAO,EAAE,6BAA6B;;;iBAC1D,QAAQ,EAAE,QAAQ;iBAAE,OAAO,EAAE,wCAAwC;;;iBACrE,QAAQ,EAAE,QAAQ;iBAAE,OAAO,EAAE,0CAA0C;;;iBACvE,QAAQ,EAAE,QAAQ;iBAAE,OAAO,EAAE,kDAAkD;;;iBAC/E,QAAQ,EAAE,QAAQ;iBAAE,OAAO,EAAE,uDAAuD;;;iBACpF,QAAQ,EAAE,QAAQ;iBAAE,OAAO,EAAE,oDAAoD;;;iBACjF,QAAQ,EAAE,OAAO;iBAAE,OAAO,EAAE,qEAAqE;;;iBACjG,QAAQ,EAAE,SAAS;iBAAE,OAAO,EAAE,mDAAmD;;;iBACjF,QAAQ,EAAE,cAAc;iBAAE,OAAO,EAAE,wDAAwD;;;iBAC3F,QAAQ,EAAE,cAAc;iBAAE,OAAO,EAAE,qDAAqD;;;iBACxF,QAAQ,EAAE,cAAc;iBAAE,OAAO,EAAE,oEAAoE;;EACxG,CAAC;AAEZ,MAAM,MAAM,sBAAsB,GAAG,MAAM,OAAO,kBAAkB,CAAC;AAErE,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,sBAAsB,CAEvF"}

package/dist/packages/core/src/diagnostics.js

@@ -3,6 +3,7 @@ export const diagnosticRegistry = Object.freeze({
     TSQ002: { category: "resource", summary: "SQL exceeded a parser resource limit." },
     TSQ003: { category: "resource", summary: "Conditional SQL exceeded the structural variant limit." },
     TSQ004: { category: "contract", summary: "Structural SQL requires an explicitly trusted fragment." },
+    TSQ005: { category: "support", summary: "Runtime SQL cannot be analyzed statically." },
     TSQ007: { category: "contract", summary: "The schema snapshot and dialect do not match." },
     TSQ100: { category: "schema", summary: "A referenced table does not exist." },
     TSQ101: { category: "schema", summary: "A referenced column does not exist." },
@@ -27,6 +28,9 @@ export const diagnosticRegistry = Object.freeze({
     TSQ217: { category: "result", summary: "An IN subquery does not return exactly one column." },
     TSQ301: { category: "drift", summary: "The live schema or type policy differs from the generated snapshot." },
     TSQ401: { category: "support", summary: "The dialect surface is intentionally unsupported." },
+    TSQ500: { category: "verification", summary: "Live database metadata differs from compiler evidence." },
+    TSQ501: { category: "verification", summary: "A query could not be verified safely or statically." },
+    TSQ502: { category: "verification", summary: "Native live verification failed without persisting driver details." },
 });
 export function isTypedSqlDiagnosticCode(value) {
     return Object.hasOwn(diagnosticRegistry, value);

package/dist/packages/core/src/diagnostics.js.map

@@ -1 +1 @@
-{"version":3,"file":"diagnostics.js","sourceRoot":"","sources":["../../../../src/diagnostics.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,kBAAkB,GAAG,MAAM,CAAC,MAAM,CAAC;IAC9C,MAAM,EAAE,EAAE,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAE,iCAAiC,EAAE;IAC1E,MAAM,EAAE,EAAE,QAAQ,EAAE,UAAU,EAAE,OAAO,EAAE,uCAAuC,EAAE;IAClF,MAAM,EAAE,EAAE,QAAQ,EAAE,UAAU,EAAE,OAAO,EAAE,wDAAwD,EAAE;IACnG,MAAM,EAAE,EAAE,QAAQ,EAAE,UAAU,EAAE,OAAO,EAAE,yDAAyD,EAAE;IACpG,MAAM,EAAE,EAAE,QAAQ,EAAE,UAAU,EAAE,OAAO,EAAE,+CAA+C,EAAE;IAC1F,MAAM,EAAE,EAAE,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAE,oCAAoC,EAAE;IAC7E,MAAM,EAAE,EAAE,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAE,qCAAqC,EAAE;IAC9E,MAAM,EAAE,EAAE,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAE,kCAAkC,EAAE;IAC3E,MAAM,EAAE,EAAE,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAE,kDAAkD,EAAE;IAC3F,MAAM,EAAE,EAAE,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAE,oDAAoD,EAAE;IAC7F,MAAM,EAAE,EAAE,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAE,oDAAoD,EAAE;IAC7F,MAAM,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,sCAAsC,EAAE;IAC7E,MAAM,EAAE,EAAE,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAE,yCAAyC,EAAE;IAClF,MAAM,EAAE,EAAE,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAE,iCAAiC,EAAE;IAC1E,MAAM,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,wBAAwB,EAAE;IAC/D,MAAM,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,wCAAwC,EAAE;IAC/E,MAAM,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,mCAAmC,EAAE;IAC1E,MAAM,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,4DAA4D,EAAE;IACnG,MAAM,EAAE,EAAE,QAAQ,EAAE,SAAS,EAAE,OAAO,EAAE,kDAAkD,EAAE;IAC5F,MAAM,EAAE,EAAE,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAE,2BAA2B,EAAE;IACpE,MAAM,EAAE,EAAE,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAE,6BAA6B,EAAE;IACtE,MAAM,EAAE,EAAE,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAE,wCAAwC,EAAE;IACjF,MAAM,EAAE,EAAE,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAE,0CAA0C,EAAE;IACnF,MAAM,EAAE,EAAE,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAE,kDAAkD,EAAE;IAC3F,MAAM,EAAE,EAAE,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAE,uDAAuD,EAAE;IAChG,MAAM,EAAE,EAAE,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAE,oDAAoD,EAAE;IAC7F,MAAM,EAAE,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,EAAE,qEAAqE,EAAE;IAC7G,MAAM,EAAE,EAAE,QAAQ,EAAE,SAAS,EAAE,OAAO,EAAE,mDAAmD,EAAE;CACrF,CAAC,CAAC;AAIZ,MAAM,UAAU,wBAAwB,CAAC,KAAa;IACpD,OAAO,MAAM,CAAC,MAAM,CAAC,kBAAkB,EAAE,KAAK,CAAC,CAAC;AAClD,CAAC"}
+{"version":3,"file":"diagnostics.js","sourceRoot":"","sources":["../../../../src/diagnostics.ts"],"names":[],"mappings":"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"}

package/dist/packages/core/src/execution.d.ts

@@ -1,4 +1,36 @@
 import type { Query } from "./query.js";
+export type QueryCardinalityExpectation = "one" | "maybeOne";
+export type QueryCancellationReason = "signal" | "deadline";
+export type ExecutionCapability = "cancellation" | "deadlines";
+export interface ExecutionOptions {
+    readonly signal?: AbortSignal;
+    /** Absolute Unix time in milliseconds, or a Date representing that instant. */
+    readonly deadline?: number | Date;
+}
+export interface ExecutionCapabilities {
+    readonly cancellation: boolean;
+    readonly deadlines: boolean;
+}
+export declare class QueryCardinalityError extends Error {
+    readonly code = "TSQL_CARDINALITY";
+    readonly expected: QueryCardinalityExpectation;
+    readonly actual: number;
+    constructor(expected: QueryCardinalityExpectation, actual: number);
+}
+export declare class QueryCancelledError extends Error {
+    readonly code = "TSQL_CANCELLED";
+    readonly reason: QueryCancellationReason;
+    constructor(reason: QueryCancellationReason, options?: ErrorOptions);
+}
+export declare class UnsupportedExecutionCapabilityError extends Error {
+    readonly code = "TSQL_UNSUPPORTED_EXECUTION_CAPABILITY";
+    readonly capability: ExecutionCapability;
+    constructor(capability: ExecutionCapability);
+}
+export declare function executionDeadline(options: ExecutionOptions): number | undefined;
+export declare function assertExecutionCapabilities(capabilities: ExecutionCapabilities, options: ExecutionOptions): void;
+/** Runs one dispatched operation and invokes adapter cleanup exactly once when its controls fire. */
+export declare function runControlledExecution<Value>(options: ExecutionOptions, operation: () => Promise<Value>, cancel: (error: QueryCancelledError) => void): Promise<Value>;
 /** The buffered rows produced by executing one typed query. */
 export type QueryResult<Value> = Value extends Query<infer Row, infer _Params> ? readonly Row[] : never;
 /**

package/dist/packages/core/src/execution.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"execution.d.ts","sourceRoot":"","sources":["../../../../src/execution.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAExC,+DAA+D;AAC/D,MAAM,MAAM,WAAW,CAAC,KAAK,IAAI,KAAK,SAAS,KAAK,CAAC,MAAM,GAAG,EAAE,MAAM,OAAO,CAAC,GAAG,SAAS,GAAG,EAAE,GAAG,KAAK,CAAC;AAExG;;;;GAIG;AACH,MAAM,MAAM,YAAY,CAAC,OAAO,SAAS,SAAS,OAAO,EAAE,IAAI;IAC7D,QAAQ,EAAE,KAAK,IAAI,MAAM,OAAO,GAAG,WAAW,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;CAC/D,CAAC;AAEF,qFAAqF;AACrF,MAAM,MAAM,UAAU,CAAC,OAAO,SAAS,SAAS,OAAO,EAAE,IAAI,OAAO,GAAG;IACrE,QAAQ,EAAE,KAAK,IAAI,MAAM,OAAO,GAAG,OAAO,CAAC,KAAK,CAAC,SAAS,KAAK,CAAC,MAAM,GAAG,EAAE,MAAM,MAAM,CAAC,GAAG,KAAK,CAAC,GAAG,EAAE,MAAM,CAAC,GAAG,KAAK;CACtH,CAAC;AAEF,oDAAoD;AACpD,MAAM,WAAW,aAAa;IAC5B;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,+DAA+D;AAC/D,MAAM,WAAW,WAAW,CAAC,GAAG,CAAE,SAAQ,qBAAqB,CAAC,GAAG,CAAC,EAAE,eAAe;IACnF,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB"}
+{"version":3,"file":"execution.d.ts","sourceRoot":"","sources":["../../../../src/execution.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAExC,MAAM,MAAM,2BAA2B,GAAG,KAAK,GAAG,UAAU,CAAC;AAC7D,MAAM,MAAM,uBAAuB,GAAG,QAAQ,GAAG,UAAU,CAAC;AAC5D,MAAM,MAAM,mBAAmB,GAAG,cAAc,GAAG,WAAW,CAAC;AAE/D,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAC9B,+EAA+E;IAC/E,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACnC;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAC/B,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B;AAED,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,QAAQ,CAAC,IAAI,sBAAsB;IACnC,QAAQ,CAAC,QAAQ,EAAE,2BAA2B,CAAC;IAC/C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAExB,YAAY,QAAQ,EAAE,2BAA2B,EAAE,MAAM,EAAE,MAAM,EAShE;CACF;AAED,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,QAAQ,CAAC,IAAI,oBAAoB;IACjC,QAAQ,CAAC,MAAM,EAAE,uBAAuB,CAAC;IAEzC,YAAY,MAAM,EAAE,uBAAuB,EAAE,OAAO,GAAE,YAAiB,EAItE;CACF;AAED,qBAAa,mCAAoC,SAAQ,KAAK;IAC5D,QAAQ,CAAC,IAAI,2CAA2C;IACxD,QAAQ,CAAC,UAAU,EAAE,mBAAmB,CAAC;IAEzC,YAAY,UAAU,EAAE,mBAAmB,EAI1C;CACF;AAED,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,gBAAgB,GAAG,MAAM,GAAG,SAAS,CAK/E;AAED,wBAAgB,2BAA2B,CAAC,YAAY,EAAE,qBAAqB,EAAE,OAAO,EAAE,gBAAgB,GAAG,IAAI,CAQhH;AAID,qGAAqG;AACrG,wBAAsB,sBAAsB,CAAC,KAAK,EAChD,OAAO,EAAE,gBAAgB,EACzB,SAAS,EAAE,MAAM,OAAO,CAAC,KAAK,CAAC,EAC/B,MAAM,EAAE,CAAC,KAAK,EAAE,mBAAmB,KAAK,IAAI,GAC3C,OAAO,CAAC,KAAK,CAAC,CA2DhB;AAED,+DAA+D;AAC/D,MAAM,MAAM,WAAW,CAAC,KAAK,IAAI,KAAK,SAAS,KAAK,CAAC,MAAM,GAAG,EAAE,MAAM,OAAO,CAAC,GAAG,SAAS,GAAG,EAAE,GAAG,KAAK,CAAC;AAExG;;;;GAIG;AACH,MAAM,MAAM,YAAY,CAAC,OAAO,SAAS,SAAS,OAAO,EAAE,IAAI;IAC7D,QAAQ,EAAE,KAAK,IAAI,MAAM,OAAO,GAAG,WAAW,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;CAC/D,CAAC;AAEF,qFAAqF;AACrF,MAAM,MAAM,UAAU,CAAC,OAAO,SAAS,SAAS,OAAO,EAAE,IAAI,OAAO,GAAG;IACrE,QAAQ,EAAE,KAAK,IAAI,MAAM,OAAO,GAAG,OAAO,CAAC,KAAK,CAAC,SAAS,KAAK,CAAC,MAAM,GAAG,EAAE,MAAM,MAAM,CAAC,GAAG,KAAK,CAAC,GAAG,EAAE,MAAM,CAAC,GAAG,KAAK;CACtH,CAAC;AAEF,oDAAoD;AACpD,MAAM,WAAW,aAAa;IAC5B;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,+DAA+D;AAC/D,MAAM,WAAW,WAAW,CAAC,GAAG,CAAE,SAAQ,qBAAqB,CAAC,GAAG,CAAC,EAAE,eAAe;IACnF,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB"}

package/dist/packages/core/src/execution.js

@@ -1,2 +1,118 @@
-export {};
+export class QueryCardinalityError extends Error {
+    code = "TSQL_CARDINALITY";
+    expected;
+    actual;
+    constructor(expected, actual) {
+        super(expected === "one"
+            ? `Expected exactly one row, received ${actual}`
+            : `Expected at most one row, received ${actual}`);
+        this.name = "QueryCardinalityError";
+        this.expected = expected;
+        this.actual = actual;
+    }
+}
+export class QueryCancelledError extends Error {
+    code = "TSQL_CANCELLED";
+    reason;
+    constructor(reason, options = {}) {
+        super(reason === "deadline" ? "Query deadline expired" : "Query execution was cancelled", options);
+        this.name = "QueryCancelledError";
+        this.reason = reason;
+    }
+}
+export class UnsupportedExecutionCapabilityError extends Error {
+    code = "TSQL_UNSUPPORTED_EXECUTION_CAPABILITY";
+    capability;
+    constructor(capability) {
+        super(`This database adapter does not support ${capability}`);
+        this.name = "UnsupportedExecutionCapabilityError";
+        this.capability = capability;
+    }
+}
+export function executionDeadline(options) {
+    if (options.deadline === undefined)
+        return undefined;
+    const deadline = options.deadline instanceof Date ? options.deadline.getTime() : options.deadline;
+    if (!Number.isFinite(deadline))
+        throw new RangeError("Execution deadline must be a finite Unix time in milliseconds");
+    return deadline;
+}
+export function assertExecutionCapabilities(capabilities, options) {
+    executionDeadline(options);
+    if (options.signal !== undefined && !capabilities.cancellation) {
+        throw new UnsupportedExecutionCapabilityError("cancellation");
+    }
+    if (options.deadline !== undefined && !capabilities.deadlines) {
+        throw new UnsupportedExecutionCapabilityError("deadlines");
+    }
+}
+const maximumTimerDelay = 2_147_483_647;
+/** Runs one dispatched operation and invokes adapter cleanup exactly once when its controls fire. */
+export async function runControlledExecution(options, operation, cancel) {
+    const deadline = executionDeadline(options);
+    if (options.signal?.aborted)
+        throw new QueryCancelledError("signal", { cause: options.signal.reason });
+    if (deadline !== undefined && deadline <= Date.now())
+        throw new QueryCancelledError("deadline");
+    let cancellationError;
+    let rejectCancellation;
+    const cancellation = new Promise((_resolve, reject) => {
+        rejectCancellation = reject;
+    });
+    // A deadline may expire before the operation is dispatched. Keep that rejected
+    // branch observed even when the function exits before constructing Promise.race.
+    void cancellation.catch(() => undefined);
+    const requestCancellation = (reason) => {
+        if (cancellationError !== undefined)
+            return;
+        cancellationError = new QueryCancelledError(reason, {
+            ...(reason === "signal" ? { cause: options.signal?.reason } : {}),
+        });
+        try {
+            cancel(cancellationError);
+        }
+        catch {
+            // Cancellation is authoritative. Adapter cleanup failures must not escape
+            // an AbortSignal listener or replace the stable cancellation error.
+        }
+        finally {
+            rejectCancellation(cancellationError);
+        }
+    };
+    const onAbort = () => requestCancellation("signal");
+    options.signal?.addEventListener("abort", onAbort, { once: true });
+    let deadlineTimer;
+    const armDeadline = () => {
+        if (deadline === undefined)
+            return;
+        const remaining = deadline - Date.now();
+        if (remaining <= 0)
+            requestCancellation("deadline");
+        else
+            deadlineTimer = setTimeout(remaining > maximumTimerDelay ? armDeadline : () => requestCancellation("deadline"), Math.min(remaining, maximumTimerDelay));
+    };
+    armDeadline();
+    try {
+        if (cancellationError !== undefined)
+            throw cancellationError;
+        const running = operation();
+        try {
+            const value = await Promise.race([running, cancellation]);
+            if (cancellationError !== undefined)
+                throw cancellationError;
+            return value;
+        }
+        catch (error) {
+            if (cancellationError === undefined)
+                throw error;
+            await running.catch(() => undefined);
+            throw cancellationError;
+        }
+    }
+    finally {
+        options.signal?.removeEventListener("abort", onAbort);
+        if (deadlineTimer !== undefined)
+            clearTimeout(deadlineTimer);
+    }
+}
 //# sourceMappingURL=execution.js.map

package/dist/packages/core/src/execution.js.map

@@ -1 +1 @@
-{"version":3,"file":"execution.js","sourceRoot":"","sources":["../../../../src/execution.ts"],"names":[],"mappings":""}
+{"version":3,"file":"execution.js","sourceRoot":"","sources":["../../../../src/execution.ts"],"names":[],"mappings":"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"}

package/dist/packages/core/src/index.d.ts

@@ -1,10 +1,21 @@
+export type { AdapterCapability, AdapterCapabilityHost, AdapterCapabilityResolver, AdapterCapabilityService, } from "./adapter-capabilities.js";
+export { adapterCapabilities, createAdapterCapabilityResolver, defineAdapterCapability, getAdapterCapability, hasAdapterCapability, requireAdapterCapability, UnsupportedAdapterCapabilityError, } from "./adapter-capabilities.js";
 export type { TypedSqlDiagnosticCode } from "./diagnostics.js";
 export { diagnosticRegistry, isTypedSqlDiagnosticCode } from "./diagnostics.js";
-export type { QueryBatch, QueryResult, QueryResults, QueryStream, StreamOptions } from "./execution.js";
-export type { Database, OptionalSqlFragment, Query, QueryExecutor, QueryParameters, QueryRenderSkeleton, QueryRow, RenderedQuery, SqlFragment, SqlRenderer, SqlSegment, SqlTag, TransactionDatabase, TransactionRunner, } from "./query.js";
+export type { ExecutionCapabilities, ExecutionCapability, ExecutionOptions, QueryBatch, QueryCancellationReason, QueryCardinalityExpectation, QueryResult, QueryResults, QueryStream, StreamOptions, } from "./execution.js";
+export { assertExecutionCapabilities, executionDeadline, QueryCancelledError, QueryCardinalityError, runControlledExecution, UnsupportedExecutionCapabilityError, } from "./execution.js";
+export type { ActiveDatabaseObservation, BatchOperationStart, DatabaseObservation, DatabaseObservationStatus, DatabaseObserver, DatabaseOperationCompletion, DatabaseOperationEnd, DatabaseOperationStart, QueryObservationCardinality, QueryOperationStart, StreamOperationStart, TransactionOperationStart, } from "./observation.js";
+export { databaseErrorCompletion, observeQueryStream, startDatabaseObservation } from "./observation.js";
+export type { ControlledQueryExecutor, Database, OptionalSqlFragment, Query, QueryExecutor, QueryParameters, QueryRenderSkeleton, QueryRow, RenderedQuery, SqlFragment, SqlRenderer, SqlSegment, SqlTag, TransactionDatabase, TransactionRunner, } from "./query.js";
 export { bindQueryRenderSkeleton, compileQueryRenderSkeleton, createDatabase, renderQuery, sql, } from "./query.js";
 export type { ResolverType } from "./resolver.js";
 export { closestName, ParameterCollector, ResolverSchemaIndex, unionTypeLiterals } from "./resolver.js";
-export type { ColumnSnapshot, DialectAnalysis, DialectCapabilities, DialectPlugin, DomainSnapshot, FunctionSnapshot, GeneratedSchemaMetadata, GeneratedSchemaSnapshot, ResolvedColumn, ResolvedParameter, SchemaProvider, SchemaSnapshot, SourceRange, SqlDiagnostic, SqlDiagnosticFix, TableSnapshot, TypedSqlConfig, } from "./types.js";
+export type { CompatibleResultSchema, QueryResultValidationFailure, QueryResultValidationIssue, QueryResultValidationOptions, StandardSchemaV1, StandardTypedV1, } from "./result-validation.js";
+export { hasQueryResultValidator, QueryResultValidationError, queryResultValidationSource, validateQueryResultRows, validateQueryResultStream, } from "./result-validation.js";
+export type { QueryRoute, QueryRoutePreference, QueryRouteSelection, QueryRoutingObserver, QuerySemanticResolver, ReplicaSelectionContext, ReplicaSelector, RoutedDatabase, RoutedDatabaseOptions, RoutedTransactionOptions, TransactionRetryContext, TransactionRetryEvent, TransactionRetryPolicy, } from "./routing.js";
+export { createRoutedDatabase, queryRoute, UnsafeReplicaRoutingError } from "./routing.js";
+export type { QueryCardinality, QueryConnectionAffinity, QueryDependency, QueryDependencyAccess, QueryDependencyKind, QueryLocking, QueryOperation, QuerySemantics, QueryVolatility, SemanticEvidence, SemanticFact, } from "./semantics.js";
+export { defineQuerySemantics, mapQuerySemanticRanges, mergeQuerySemantics, QUERY_SEMANTICS_VERSION, unknownQuerySemantics, } from "./semantics.js";
+export type { ColumnSnapshot, DialectAnalysis, DialectCapabilities, DialectPlugin, DomainSnapshot, FunctionSnapshot, GeneratedSchemaMetadata, GeneratedSchemaSnapshot, LiveQueryVerificationEvidence, LiveQueryVerificationField, LiveQueryVerificationRequest, LiveQueryVerificationServer, LiveQueryVerifier, QueryPlanBudget, QueryPlanBudgetPolicy, QueryPlanCaptureRequest, QueryPlanEnvironment, QueryPlanEvidence, QueryPlanInspector, QueryPlanNode, QueryPlanSample, QueryPlanSampleProvider, QueryPlanSampleRequest, ResolvedColumn, ResolvedParameter, SchemaProvider, SchemaSnapshot, SourceRange, SqlDiagnostic, SqlDiagnosticFix, TableSnapshot, TypedSqlConfig, } from "./types.js";
 export { assertDialectPlugin, DIALECT_CONTRACT_VERSION, defineConfig, parameterTypeLiteral, rowTypeLiteral, } from "./types.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/packages/core/src/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAC/D,OAAO,EAAE,kBAAkB,EAAE,wBAAwB,EAAE,MAAM,kBAAkB,CAAC;AAChF,YAAY,EAAE,UAAU,EAAE,WAAW,EAAE,YAAY,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AACxG,YAAY,EACV,QAAQ,EACR,mBAAmB,EACnB,KAAK,EACL,aAAa,EACb,eAAe,EACf,mBAAmB,EACnB,QAAQ,EACR,aAAa,EACb,WAAW,EACX,WAAW,EACX,UAAU,EACV,MAAM,EACN,mBAAmB,EACnB,iBAAiB,GAClB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,uBAAuB,EACvB,0BAA0B,EAC1B,cAAc,EACd,WAAW,EACX,GAAG,GACJ,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,EAAE,WAAW,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AACxG,YAAY,EACV,cAAc,EACd,eAAe,EACf,mBAAmB,EACnB,aAAa,EACb,cAAc,EACd,gBAAgB,EAChB,uBAAuB,EACvB,uBAAuB,EACvB,cAAc,EACd,iBAAiB,EACjB,cAAc,EACd,cAAc,EACd,WAAW,EACX,aAAa,EACb,gBAAgB,EAChB,aAAa,EACb,cAAc,GACf,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,mBAAmB,EACnB,wBAAwB,EACxB,YAAY,EACZ,oBAAoB,EACpB,cAAc,GACf,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,iBAAiB,EACjB,qBAAqB,EACrB,yBAAyB,EACzB,wBAAwB,GACzB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EACL,mBAAmB,EACnB,+BAA+B,EAC/B,uBAAuB,EACvB,oBAAoB,EACpB,oBAAoB,EACpB,wBAAwB,EACxB,iCAAiC,GAClC,MAAM,2BAA2B,CAAC;AACnC,YAAY,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAC/D,OAAO,EAAE,kBAAkB,EAAE,wBAAwB,EAAE,MAAM,kBAAkB,CAAC;AAChF,YAAY,EACV,qBAAqB,EACrB,mBAAmB,EACnB,gBAAgB,EAChB,UAAU,EACV,uBAAuB,EACvB,2BAA2B,EAC3B,WAAW,EACX,YAAY,EACZ,WAAW,EACX,aAAa,GACd,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,2BAA2B,EAC3B,iBAAiB,EACjB,mBAAmB,EACnB,qBAAqB,EACrB,sBAAsB,EACtB,mCAAmC,GACpC,MAAM,gBAAgB,CAAC;AACxB,YAAY,EACV,yBAAyB,EACzB,mBAAmB,EACnB,mBAAmB,EACnB,yBAAyB,EACzB,gBAAgB,EAChB,2BAA2B,EAC3B,oBAAoB,EACpB,sBAAsB,EACtB,2BAA2B,EAC3B,mBAAmB,EACnB,oBAAoB,EACpB,yBAAyB,GAC1B,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,uBAAuB,EAAE,kBAAkB,EAAE,wBAAwB,EAAE,MAAM,kBAAkB,CAAC;AACzG,YAAY,EACV,uBAAuB,EACvB,QAAQ,EACR,mBAAmB,EACnB,KAAK,EACL,aAAa,EACb,eAAe,EACf,mBAAmB,EACnB,QAAQ,EACR,aAAa,EACb,WAAW,EACX,WAAW,EACX,UAAU,EACV,MAAM,EACN,mBAAmB,EACnB,iBAAiB,GAClB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,uBAAuB,EACvB,0BAA0B,EAC1B,cAAc,EACd,WAAW,EACX,GAAG,GACJ,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,EAAE,WAAW,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AACxG,YAAY,EACV,sBAAsB,EACtB,4BAA4B,EAC5B,0BAA0B,EAC1B,4BAA4B,EAC5B,gBAAgB,EAChB,eAAe,GAChB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,uBAAuB,EACvB,0BAA0B,EAC1B,2BAA2B,EAC3B,uBAAuB,EACvB,yBAAyB,GAC1B,MAAM,wBAAwB,CAAC;AAChC,YAAY,EACV,UAAU,EACV,oBAAoB,EACpB,mBAAmB,EACnB,oBAAoB,EACpB,qBAAqB,EACrB,uBAAuB,EACvB,eAAe,EACf,cAAc,EACd,qBAAqB,EACrB,wBAAwB,EACxB,uBAAuB,EACvB,qBAAqB,EACrB,sBAAsB,GACvB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,oBAAoB,EAAE,UAAU,EAAE,yBAAyB,EAAE,MAAM,cAAc,CAAC;AAC3F,YAAY,EACV,gBAAgB,EAChB,uBAAuB,EACvB,eAAe,EACf,qBAAqB,EACrB,mBAAmB,EACnB,YAAY,EACZ,cAAc,EACd,cAAc,EACd,eAAe,EACf,gBAAgB,EAChB,YAAY,GACb,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,oBAAoB,EACpB,sBAAsB,EACtB,mBAAmB,EACnB,uBAAuB,EACvB,qBAAqB,GACtB,MAAM,gBAAgB,CAAC;AACxB,YAAY,EACV,cAAc,EACd,eAAe,EACf,mBAAmB,EACnB,aAAa,EACb,cAAc,EACd,gBAAgB,EAChB,uBAAuB,EACvB,uBAAuB,EACvB,6BAA6B,EAC7B,0BAA0B,EAC1B,4BAA4B,EAC5B,2BAA2B,EAC3B,iBAAiB,EACjB,eAAe,EACf,qBAAqB,EACrB,uBAAuB,EACvB,oBAAoB,EACpB,iBAAiB,EACjB,kBAAkB,EAClB,aAAa,EACb,eAAe,EACf,uBAAuB,EACvB,sBAAsB,EACtB,cAAc,EACd,iBAAiB,EACjB,cAAc,EACd,cAAc,EACd,WAAW,EACX,aAAa,EACb,gBAAgB,EAChB,aAAa,EACb,cAAc,GACf,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,mBAAmB,EACnB,wBAAwB,EACxB,YAAY,EACZ,oBAAoB,EACpB,cAAc,GACf,MAAM,YAAY,CAAC"}

package/dist/packages/core/src/index.js

@@ -1,5 +1,11 @@
+export { adapterCapabilities, createAdapterCapabilityResolver, defineAdapterCapability, getAdapterCapability, hasAdapterCapability, requireAdapterCapability, UnsupportedAdapterCapabilityError, } from "./adapter-capabilities.js";
 export { diagnosticRegistry, isTypedSqlDiagnosticCode } from "./diagnostics.js";
+export { assertExecutionCapabilities, executionDeadline, QueryCancelledError, QueryCardinalityError, runControlledExecution, UnsupportedExecutionCapabilityError, } from "./execution.js";
+export { databaseErrorCompletion, observeQueryStream, startDatabaseObservation } from "./observation.js";
 export { bindQueryRenderSkeleton, compileQueryRenderSkeleton, createDatabase, renderQuery, sql, } from "./query.js";
 export { closestName, ParameterCollector, ResolverSchemaIndex, unionTypeLiterals } from "./resolver.js";
+export { hasQueryResultValidator, QueryResultValidationError, queryResultValidationSource, validateQueryResultRows, validateQueryResultStream, } from "./result-validation.js";
+export { createRoutedDatabase, queryRoute, UnsafeReplicaRoutingError } from "./routing.js";
+export { defineQuerySemantics, mapQuerySemanticRanges, mergeQuerySemantics, QUERY_SEMANTICS_VERSION, unknownQuerySemantics, } from "./semantics.js";
 export { assertDialectPlugin, DIALECT_CONTRACT_VERSION, defineConfig, parameterTypeLiteral, rowTypeLiteral, } from "./types.js";
 //# sourceMappingURL=index.js.map

package/dist/packages/core/src/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,kBAAkB,EAAE,wBAAwB,EAAE,MAAM,kBAAkB,CAAC;AAkBhF,OAAO,EACL,uBAAuB,EACvB,0BAA0B,EAC1B,cAAc,EACd,WAAW,EACX,GAAG,GACJ,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,WAAW,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAoBxG,OAAO,EACL,mBAAmB,EACnB,wBAAwB,EACxB,YAAY,EACZ,oBAAoB,EACpB,cAAc,GACf,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/index.ts"],"names":[],"mappings":"AAMA,OAAO,EACL,mBAAmB,EACnB,+BAA+B,EAC/B,uBAAuB,EACvB,oBAAoB,EACpB,oBAAoB,EACpB,wBAAwB,EACxB,iCAAiC,GAClC,MAAM,2BAA2B,CAAC;AAEnC,OAAO,EAAE,kBAAkB,EAAE,wBAAwB,EAAE,MAAM,kBAAkB,CAAC;AAahF,OAAO,EACL,2BAA2B,EAC3B,iBAAiB,EACjB,mBAAmB,EACnB,qBAAqB,EACrB,sBAAsB,EACtB,mCAAmC,GACpC,MAAM,gBAAgB,CAAC;AAexB,OAAO,EAAE,uBAAuB,EAAE,kBAAkB,EAAE,wBAAwB,EAAE,MAAM,kBAAkB,CAAC;AAkBzG,OAAO,EACL,uBAAuB,EACvB,0BAA0B,EAC1B,cAAc,EACd,WAAW,EACX,GAAG,GACJ,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,WAAW,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AASxG,OAAO,EACL,uBAAuB,EACvB,0BAA0B,EAC1B,2BAA2B,EAC3B,uBAAuB,EACvB,yBAAyB,GAC1B,MAAM,wBAAwB,CAAC;AAgBhC,OAAO,EAAE,oBAAoB,EAAE,UAAU,EAAE,yBAAyB,EAAE,MAAM,cAAc,CAAC;AAc3F,OAAO,EACL,oBAAoB,EACpB,sBAAsB,EACtB,mBAAmB,EACnB,uBAAuB,EACvB,qBAAqB,GACtB,MAAM,gBAAgB,CAAC;AAmCxB,OAAO,EACL,mBAAmB,EACnB,wBAAwB,EACxB,YAAY,EACZ,oBAAoB,EACpB,cAAc,GACf,MAAM,YAAY,CAAC"}

package/dist/packages/core/src/observation.d.ts

@@ -0,0 +1,60 @@
+import type { QueryCancellationReason, QueryCardinalityExpectation, QueryStream } from "./execution.js";
+export type QueryObservationCardinality = QueryCardinalityExpectation | "many";
+export type DatabaseObservationStatus = "success" | "error" | "cancelled";
+interface DatabaseOperationCommon {
+    readonly dialect: string;
+    readonly grammarVersion: string;
+    readonly transactionDepth: number;
+}
+export interface QueryOperationStart extends DatabaseOperationCommon {
+    readonly kind: "query";
+    readonly fingerprint: string;
+    readonly cardinality: QueryObservationCardinality;
+    readonly prepared: boolean;
+}
+export interface BatchOperationStart extends DatabaseOperationCommon {
+    readonly kind: "batch" | "pipeline";
+    readonly fingerprints: readonly string[];
+    readonly size: number;
+}
+export interface StreamOperationStart extends DatabaseOperationCommon {
+    readonly kind: "stream";
+    readonly fingerprint: string;
+    readonly prepared: boolean;
+}
+export interface TransactionOperationStart extends DatabaseOperationCommon {
+    readonly kind: "transaction";
+}
+export type DatabaseOperationStart = QueryOperationStart | BatchOperationStart | StreamOperationStart | TransactionOperationStart;
+export interface DatabaseOperationCompletion {
+    readonly status: DatabaseObservationStatus;
+    readonly rowCount?: number;
+    readonly errorType?: string;
+    readonly cancellationReason?: QueryCancellationReason;
+}
+export interface DatabaseOperationEnd extends DatabaseOperationCompletion {
+    readonly durationMilliseconds: number;
+    /** Present only when the observer explicitly enables error-cause capture. */
+    readonly cause?: unknown;
+}
+export interface DatabaseObservation {
+    /** Runs dispatch in observer-owned context, such as an OpenTelemetry span context. */
+    run?<Value>(operation: () => Value): Value;
+    end(completion: DatabaseOperationEnd): void;
+}
+export interface DatabaseObserver {
+    /** Error objects may include sensitive driver text and are excluded by default. */
+    readonly captureErrorCause?: boolean;
+    start(operation: DatabaseOperationStart): DatabaseObservation | undefined;
+}
+export interface ActiveDatabaseObservation {
+    run<Value>(operation: () => Value): Value;
+    end(completion: DatabaseOperationCompletion, cause?: unknown): void;
+}
+/** Starts one redacted operation lifecycle. Observer start/end failures never replace database results. */
+export declare function startDatabaseObservation(observer: DatabaseObserver | undefined, operation: DatabaseOperationStart): ActiveDatabaseObservation | undefined;
+export declare function databaseErrorCompletion(error: unknown): DatabaseOperationCompletion;
+/** Adds a lazy, exactly-once observation lifecycle to an adapter-owned query stream. */
+export declare function observeQueryStream<Row>(stream: QueryStream<Row>, observer: DatabaseObserver | undefined, operation: StreamOperationStart): QueryStream<Row>;
+export {};
+//# sourceMappingURL=observation.d.ts.map

package/dist/packages/core/src/observation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observation.d.ts","sourceRoot":"","sources":["../../../../src/observation.ts"],"names":[],"mappings":"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"}