@sqlbraid/core 1.0.0 → 1.0.3

package/dist/index.d.ts

@@ -1,277 +1,302 @@
 import { StandardSchemaV1, StandardSchemaV1 as StandardSchemaV1$1 } from "@standard-schema/spec";
-//#region src/authoring-modules.d.ts
-/** Data-only authoring identity shared by compiler, tooling, and editor consumers. */
-type AuthoringModuleCatalogEntry = {
-  readonly moduleSpecifier: string;
-  readonly dialectId?: "postgres" | "mysql" | "mariadb" | "sqlite" | "oracle" | "mssql";
-  readonly helperFamily: "template" | "facade";
-};
-export declare const AUTHORING_MODULE_CATALOG: readonly AuthoringModuleCatalogEntry[];
+//#region src/errors.d.ts
+/** Thrown when a driver value cannot be represented without losing database information. */
+export declare class ResultExactnessError extends Error {
+  static readonly code: "BRAID_RESULT_EXACTNESS";
+  readonly code: "BRAID_RESULT_EXACTNESS";
+  constructor(message?: string);
+}
+export type PublicErrorCategory = "runtime" | "adapter" | "compiler";
+/** One deliberately public SQLBraid error code; an arbitrary `BRAID_` message is not automatically public. */
+export interface PublicErrorDefinition {
+  readonly code: string;
+  readonly category: PublicErrorCategory;
+  readonly owner: string;
+  /**
+   * UnsupportedFeatureError only: features for which this code is a public
+   * contract. Other public errors intentionally omit this metadata.
+   */
+  readonly features?: readonly string[];
+}
+/**
+ * The intentionally small compatibility boundary for SQLBraid-owned errors.
+ *
+ * Keep this registry explicit.  In particular, a BRAID_ token in a driver
+ * message or an internal compiler fallback is not public merely because it
+ * happens to use the project prefix.
+ */
+export declare const PUBLIC_ERROR_DEFINITIONS: readonly PublicErrorDefinition[];
+/** Public adapter capability failure. Unsupported features reject explicitly rather than being buffered or simulated. */
+export declare class UnsupportedFeatureError extends Error {
+  readonly feature: string;
+  readonly code: `BRAID_${string}`;
+  constructor(feature: string, code: `BRAID_${string}`, message: string, options?: ErrorOptions);
+}
+/** Return true only for a registered, semantically valid feature/code pair. */
+export declare function isPublicUnsupportedFeatureError(error: unknown): error is UnsupportedFeatureError;
+/** An adapter-owned input/transport failure that retains TypeError semantics. */
+export declare class AdapterError extends TypeError {
+  readonly code: `BRAID_${string}`;
+  constructor(code: `BRAID_${string}`, message: string, options?: ErrorOptions);
+}
+/** Rendering/authoring failure with a stable diagnostic code, raised before driver execution. */
+export declare class SqlRenderError extends Error {
+  readonly code: string;
+  constructor(code: string, message: string);
+}
 //#endregion
-//#region src/capabilities.d.ts
+//#region src/numeric.d.ts
+export type NumericSemantics = "exact-integer" | "exact-decimal" | "approximate-binary";
+export type NumericRepresentation = "string" | "number";
+export type TransportFidelity = "lossless" | "guarded" | "lossy" | "unsupported";
+/** Database type semantics, JavaScript representation, and transport-fidelity claim for one mapping. */
+export interface NumericTypeContract {
+  readonly semantics: NumericSemantics;
+  readonly representation: NumericRepresentation;
+  readonly fidelity: TransportFidelity;
+  readonly binaryPrecision?: 32 | 64;
+}
+export interface ExactIntegerRange {
+  readonly min?: bigint;
+  readonly max?: bigint;
+}
 /**
- * The machine-readable capability vocabulary shared by adapters, support data,
- * and documentation. A capability's family describes what its status proves;
- * representation and metadata evidence are not execution support aliases.
+ * Decode an exact integer from driver output, optionally enforcing bigint bounds.
+ *
+ * @throws {ResultExactnessError} When the value is not an exact integer or violates the requested range.
  */
-type CapabilityFamily = "support" | "representation" | "metadata";
-interface WellKnownCapability {
-  readonly id: string;
-  readonly family: CapabilityFamily;
+export declare function decodeExactInteger(value: unknown, range?: ExactIntegerRange): bigint;
+/**
+ * Normalize an exact integer at the raw SQLBraid boundary without changing
+ * its textual spelling. This is intentionally not a bigint decoder: callers
+ * that need arithmetic may opt in to decodeExactInteger().
+ */
+export declare function normalizeExactInteger(value: unknown): string;
+/**
+ * Convert a database-reported count to a safe operational Number. Counts are
+ * not application values, so unlike exact SQL numerics they remain numbers,
+ * but narrowing an unsafe value is never implicit.
+ */
+export declare function safeDatabaseCount(value: unknown): number;
+/**
+ * Preserve an exact decimal as text; numeric JavaScript values are rejected because they may already be rounded.
+ *
+ * @throws {ResultExactnessError} When the value cannot prove exact decimal fidelity.
+ */
+export declare function decodeExactDecimal(value: unknown, options?: {
+  readonly allowBigInt?: boolean;
+}): string;
+//#endregion
+//#region src/parameter.d.ts
+declare const boundParameterBrand: unique symbol;
+export type RoutineParameterDirection = "in" | "out" | "inout";
+/** Explicit database-type metadata for one bound value; this is not application validation or an input codec. */
+export interface ParameterTypeHint<Input = unknown> {
+  readonly databaseType: string;
+  readonly length?: number | "max";
+  readonly precision?: number;
+  readonly scale?: number;
+  readonly __input?: Input;
 }
-declare const definitions: readonly [{
-  readonly id: "sql.native-transparency";
-  readonly family: "support";
-}, {
-  readonly id: "sql.generated-structure";
-  readonly family: "support";
-}, {
-  readonly id: "result.rows";
-  readonly family: "support";
-}, {
-  readonly id: "result.command";
-  readonly family: "support";
-}, {
-  readonly id: "result.multiple-sets";
-  readonly family: "support";
-}, {
-  readonly id: "result.standard-schema";
-  readonly family: "support";
-}, {
-  readonly id: "numeric.exact-integer";
-  readonly family: "representation";
-}, {
-  readonly id: "numeric.exact-decimal";
-  readonly family: "representation";
-}, {
-  readonly id: "numeric.approximate-float";
-  readonly family: "representation";
-}, {
-  readonly id: "numeric.approximate-special";
-  readonly family: "representation";
-}, {
-  readonly id: "numeric.bind-exact";
-  readonly family: "representation";
-}, {
-  readonly id: "numeric.aggregate";
-  readonly family: "representation";
-}, {
-  readonly id: "numeric.command-metadata";
-  readonly family: "representation";
-}, {
-  readonly id: "numeric.special-values";
-  readonly family: "representation";
-}, {
-  readonly id: "numeric.scale-greater-than-precision";
-  readonly family: "representation";
-}, {
-  readonly id: "numeric.negative-scale";
-  readonly family: "representation";
-}, {
-  readonly id: "data.json-parsed";
-  readonly family: "representation";
-}, {
-  readonly id: "data.json-lossless-text";
-  readonly family: "representation";
-}, {
-  readonly id: "data.sql-variant";
-  readonly family: "representation";
-}, {
-  readonly id: "data.oracle-object";
-  readonly family: "representation";
-}, {
-  readonly id: "data.oracle-collection";
-  readonly family: "representation";
-}, {
-  readonly id: "data.vector";
-  readonly family: "representation";
-}, {
-  readonly id: "data.binary";
-  readonly family: "representation";
-}, {
-  readonly id: "data.uuid";
-  readonly family: "representation";
-}, {
-  readonly id: "data.temporal-native";
-  readonly family: "representation";
-}, {
-  readonly id: "data.temporal-lossless";
-  readonly family: "representation";
-}, {
-  readonly id: "data.timezone";
-  readonly family: "representation";
-}, {
-  readonly id: "metadata.command-safe";
-  readonly family: "metadata";
-}, {
-  readonly id: "dml.insert-returning";
-  readonly family: "support";
-}, {
-  readonly id: "dml.update-returning";
-  readonly family: "support";
-}, {
-  readonly id: "dml.delete-returning";
-  readonly family: "support";
-}, {
-  readonly id: "dml.merge-returning";
-  readonly family: "support";
-}, {
-  readonly id: "dml.upsert-returning";
-  readonly family: "support";
-}, {
-  readonly id: "session.pinned";
-  readonly family: "support";
-}, {
-  readonly id: "statement.prepare";
-  readonly family: "support";
-}, {
-  readonly id: "statement.cancel";
-  readonly family: "support";
-}, {
-  readonly id: "statement.stream";
-  readonly family: "support";
-}, {
-  readonly id: "statement.bulk";
-  readonly family: "support";
-}, {
-  readonly id: "execution.bulk-fidelity";
-  readonly family: "support";
-}, {
-  readonly id: "transaction";
-  readonly family: "support";
-}, {
-  readonly id: "transaction.savepoint";
-  readonly family: "support";
-}, {
-  readonly id: "transaction.read-only";
-  readonly family: "support";
-}, {
-  readonly id: "transaction.isolation.read-uncommitted";
-  readonly family: "support";
-}, {
-  readonly id: "transaction.isolation.read-committed";
-  readonly family: "support";
-}, {
-  readonly id: "transaction.isolation.repeatable-read";
-  readonly family: "support";
-}, {
-  readonly id: "transaction.isolation.serializable";
-  readonly family: "support";
-}, {
-  readonly id: "routine.call";
-  readonly family: "support";
-}, {
-  readonly id: "routine.out";
-  readonly family: "support";
-}, {
-  readonly id: "routine.inout";
-  readonly family: "support";
-}, {
-  readonly id: "routine.result-sets";
-  readonly family: "support";
-}, {
-  readonly id: "routine.out-cursor";
-  readonly family: "support";
-}, {
-  readonly id: "routine.return-value";
-  readonly family: "support";
-}, {
-  readonly id: "metadata.identity";
-  readonly family: "metadata";
-}, {
-  readonly id: "metadata.generated";
-  readonly family: "metadata";
-}, {
-  readonly id: "metadata.routines";
-  readonly family: "metadata";
-}, {
-  readonly id: "metadata.types";
-  readonly family: "metadata";
-}];
-export declare const WELL_KNOWN_CAPABILITIES: readonly WellKnownCapability[];
-type WellKnownCapabilityId = (typeof definitions)[number]["id"];
-export declare const WELL_KNOWN_CAPABILITY_IDS: readonly WellKnownCapabilityId[];
-export declare function isWellKnownCapabilityId(value: string): value is WellKnownCapabilityId;
+/** Value plus an explicit database type hint, created by `sql.bind()`. */
+export interface BoundParameter<Input = unknown> {
+  readonly value: Input;
+  readonly hint: ParameterTypeHint<Input>;
+  readonly [boundParameterBrand]: true;
+}
+/** Value-only routine OUT/INOUT marker; the direction and output name are interpreted by the adapter. */
+export interface RoutineParameter<Input = unknown> {
+  readonly value: Input;
+  readonly hint?: ParameterTypeHint;
+  readonly direction: Exclude<RoutineParameterDirection, "in">;
+  readonly outputName: string;
+}
+/** Validate and freeze an explicit database parameter-type hint. */
+export declare function createParameterTypeHint<Input = unknown>(hint: ParameterTypeHint<Input>): ParameterTypeHint<Input>;
+/** Create the value-only marker consumed by adapter binding for an explicitly typed input. */
+export declare function createBoundParameter<Input>(value: NoInfer<Input>, hint: ParameterTypeHint<Input>): BoundParameter<Input>;
+/** Recognize only bound-parameter objects created by SQLBraid's own constructor. */
+export declare function isBoundParameter(value: unknown): value is BoundParameter;
+/** Create a value-only OUT parameter descriptor; the adapter supplies the native carrier. */
+export declare function createRoutineOutParameter(name: string, hint?: ParameterTypeHint): RoutineParameter<null>;
+/** Create a value-only INOUT parameter descriptor; input value and output channel stay distinct. */
+export declare function createRoutineInOutParameter<Input>(name: string, value: NoInfer<Input>, hint?: ParameterTypeHint<Input>): RoutineParameter<Input>;
+/** Recognize only routine OUT/INOUT descriptors created by SQLBraid's own constructor. */
+export declare function isRoutineParameter(value: unknown): value is RoutineParameter;
 //#endregion
-//#region src/index.d.ts
+//#region src/routine.d.ts
+/** Optional routine identity metadata used by procedure-aware adapters and prepared-shape checks. */
+export interface RoutineProcedure {
+  readonly name: string;
+  readonly parameterNames: readonly string[];
+}
+export type RoutineSchema = StandardSchemaV1$1<any, any>;
+/**
+ * Application mapping contracts for routine OUT values, result sets, and return values.
+ * Each channel is independent; an OUT cursor is represented as a result set, not as scalar output.
+ */
+export interface RoutineContract<Output extends Readonly<Record<string, unknown>> = Readonly<Record<string, unknown>>, Sets extends readonly RoutineSchema[] = readonly RoutineSchema[], ReturnValue = unknown> {
+  readonly output?: StandardSchemaV1$1<any, Output>;
+  readonly resultSets?: Sets;
+  readonly returnValue?: StandardSchemaV1$1<any, ReturnValue>;
+  readonly procedure?: RoutineProcedure;
+}
+/** One materialized routine result set, kept separate from scalar OUT and return-value channels. */
+export interface RoutineResultSet<Row = unknown> {
+  readonly rows: readonly Row[];
+}
+export type RoutineResultSetTuple<Sets extends readonly unknown[]> = { readonly [K in keyof Sets]: RoutineResultSet<Sets[K]>; };
+/** Application-facing routine result with independent output, result-set, and return-value channels. */
+export interface RoutineCallResult<Output extends Readonly<Record<string, unknown>> = Readonly<Record<string, unknown>>, Sets extends readonly unknown[] = readonly unknown[], ReturnValue = unknown> {
+  readonly output: Output;
+  readonly resultSets: RoutineResultSetTuple<Sets>;
+  readonly returnValue?: ReturnValue;
+}
+export type RoutineSchemaOutput<Schema> = Schema extends StandardSchemaV1$1<any, infer Output> ? Output : never;
+type RoutineRowsFromSchemas<Schemas extends readonly RoutineSchema[]> = { readonly [K in keyof Schemas]: RoutineSchemaOutput<Schemas[K]>; };
+export type RoutineResultFromContract<Contract extends RoutineContract> = RoutineCallResult<Contract["output"] extends RoutineSchema ? RoutineSchemaOutput<Contract["output"]> extends Readonly<Record<string, unknown>> ? RoutineSchemaOutput<Contract["output"]> : Readonly<Record<string, unknown>> : Readonly<Record<string, unknown>>, Contract["resultSets"] extends (infer Schemas extends readonly RoutineSchema[]) ? RoutineRowsFromSchemas<Schemas> : readonly unknown[], Contract["returnValue"] extends RoutineSchema ? RoutineSchemaOutput<Contract["returnValue"]> : unknown> & (Contract extends {
+  readonly returnValue: RoutineSchema;
+} ? {
+  readonly returnValue: RoutineSchemaOutput<Contract["returnValue"]>;
+} : {});
+export type RoutineResultSource = {
+  readonly kind: "out-cursor";
+  readonly name?: string;
+  readonly parameterIndex?: number;
+} | {
+  readonly kind: "implicit";
+  readonly index: number;
+} | {
+  readonly kind: "emitted";
+  readonly index: number;
+};
+/** Driver result-set payload with provenance for OUT cursors and emitted/implicit sets. */
+export interface DriverRoutineResultSet {
+  readonly rows: readonly unknown[];
+  readonly source: RoutineResultSource;
+}
+/** Fully materialized routine result; native cursors, requests, and LOB handles must not escape this boundary. */
+export interface DriverRoutineResult {
+  readonly output: Readonly<Record<string, unknown>>;
+  readonly returnValue?: unknown;
+  readonly resultSets: readonly DriverRoutineResultSet[];
+}
+export type RoutineMappingLocation = {
+  readonly kind: "output";
+} | {
+  readonly kind: "return-value";
+} | {
+  readonly kind: "result-set";
+  readonly resultSetIndex: number;
+  readonly rowIndex: number;
+};
+export type DriverCapabilityErrorCode = "BRAID_STREAM_UNSUPPORTED" | "BRAID_CALL_UNSUPPORTED" | "BRAID_CALL_RESULT_SETS" | "BRAID_CALL_CURSOR_TX_REQUIRED" | "BRAID_CALL_OUT_UNSUPPORTED" | "BRAID_CALL_RETURN_UNSUPPORTED" | "BRAID_CALL_CURSOR_UNSUPPORTED" | "BRAID_RESOURCE_CLEANUP";
+/** Identifies which routine channel or row failed during Standard Schema mapping. */
+export declare class RoutineMappingError extends Error {
+  static readonly code: "BRAID_CALL_MAP";
+  readonly code: "BRAID_CALL_MAP";
+  readonly location: RoutineMappingLocation;
+  constructor(message: string, location: RoutineMappingLocation, options?: {
+    readonly cause?: unknown;
+  });
+}
+//#endregion
+//#region src/template-ir.d.ts
 export declare const SQL_FRAGMENT: unique symbol;
-declare const boundParameterBrand: unique symbol;
+/** Half-open source range in the cooked template text, used for diagnostics and source mapping. */
 export interface SourceRange {
   readonly start: number;
   readonly end: number;
 }
-export interface RenderLimits {
-  readonly maxSqlBytes?: number;
-  readonly maxBindCount?: number;
-  readonly maxStructuralItems?: number;
-  readonly maxNestingDepth?: number;
+/** Safety bounds applied while parsing and rendering dynamic SQL. */
+export interface RenderLimits {
+  readonly maxSqlBytes?: number;
+  readonly maxBindCount?: number;
+  readonly maxStructuralItems?: number;
+  readonly maxNestingDepth?: number;
+}
+/** Declared logical result channel; runtime checks the driver's actual result kind against it. */
+export type QueryResultKind = "rows" | "command" | "call" | "unknown";
+export interface TextNode {
+  readonly kind: "text";
+  readonly text: string;
+  readonly range: SourceRange;
+}
+export interface BindNode {
+  readonly kind: "bind";
+  readonly interpolation: number;
+  readonly range: SourceRange;
+}
+export interface FragmentNode {
+  readonly kind: "fragment";
+  readonly fragment: SqlFragment;
+  readonly range: SourceRange;
+}
+export interface IdentifierNode {
+  readonly kind: "identifier";
+  readonly value: string | readonly string[];
+  readonly range: SourceRange;
+}
+export interface RawNode {
+  readonly kind: "raw";
+  readonly text: string;
+  readonly range: SourceRange;
 }
-export type QueryResultKind = "rows" | "command" | "call" | "unknown";
-export type NumericSemantics = "exact-integer" | "exact-decimal" | "approximate-binary";
-export type NumericRepresentation = "string" | "number";
-export type TransportFidelity = "lossless" | "guarded" | "lossy" | "unsupported";
-export interface NumericTypeContract {
-  readonly semantics: NumericSemantics;
-  readonly representation: NumericRepresentation;
-  readonly fidelity: TransportFidelity;
-  readonly binaryPrecision?: 32 | 64;
+export interface ListNode {
+  readonly kind: "list";
+  readonly values: readonly unknown[];
+  readonly range: SourceRange;
 }
-export interface ExactIntegerRange {
-  readonly min?: bigint;
-  readonly max?: bigint;
+export interface IfNode {
+  readonly kind: "if";
+  readonly condition: number;
+  readonly children: readonly TemplateNode[];
+  readonly range: SourceRange;
 }
-export declare class ResultExactnessError extends Error {
-  static readonly code: "BRAID_RESULT_EXACTNESS";
-  readonly code: "BRAID_RESULT_EXACTNESS";
-  constructor(message?: string);
+export interface ChooseWhen {
+  readonly condition: number;
+  readonly children: readonly TemplateNode[];
+  readonly range: SourceRange;
 }
-export type PublicErrorCategory = "runtime" | "adapter" | "compiler";
-export interface PublicErrorDefinition {
-  readonly code: string;
-  readonly category: PublicErrorCategory;
-  readonly owner: string;
+export interface ChooseNode {
+  readonly kind: "choose";
+  readonly whens: readonly ChooseWhen[];
+  readonly otherwise?: readonly TemplateNode[];
+  readonly range: SourceRange;
+}
+export interface TrimAttributes {
+  readonly prefix: string;
+  readonly prefixOverrides: readonly string[];
+  readonly suffix: string;
+  readonly suffixOverrides: readonly string[];
+}
+export interface TrimNode {
+  readonly kind: "trim";
+  readonly attributes: TrimAttributes;
+  readonly children: readonly TemplateNode[];
+  readonly range: SourceRange;
+}
+export type TemplateNode = TextNode | BindNode | FragmentNode | IdentifierNode | RawNode | ListNode | IfNode | ChooseNode | TrimNode;
+/** Frozen template intermediate representation with source ranges and optional raw-text parallel nodes. */
+export interface TemplateIr {
+  readonly version: 1;
+  readonly nodes: readonly TemplateNode[];
+  readonly sourceLength: number;
   /**
-   * UnsupportedFeatureError only: features for which this code is a public
-   * contract. Other public errors intentionally omit this metadata.
+   * Optional parallel node tree preserving raw JavaScript template text for
+   * native tagged-template transports. The logical node tree remains cooked.
    */
-  readonly features?: readonly string[];
-}
-/**
- * The intentionally small compatibility boundary for SQLBraid-owned errors.
- *
- * Keep this registry explicit.  In particular, a BRAID_ token in a driver
- * message or an internal compiler fallback is not public merely because it
- * happens to use the project prefix.
- */
-export declare const PUBLIC_ERROR_DEFINITIONS: readonly PublicErrorDefinition[];
-export declare function decodeExactInteger(value: unknown, range?: ExactIntegerRange): bigint;
-/**
- * Normalize an exact integer at the raw SQLBraid boundary without changing
- * its textual spelling. This is intentionally not a bigint decoder: callers
- * that need arithmetic may opt in to decodeExactInteger().
- */
-export declare function normalizeExactInteger(value: unknown): string;
-/**
- * Convert a database-reported count to a safe operational Number. Counts are
- * not application values, so unlike exact SQL numerics they remain numbers,
- * but narrowing an unsafe value is never implicit.
- */
-export declare function safeDatabaseCount(value: unknown): number;
-export declare function decodeExactDecimal(value: unknown, options?: {
-  readonly allowBigInt?: boolean;
-}): string;
-export type RoutineParameterDirection = "in" | "out" | "inout";
-export interface RoutineProcedure {
-  readonly name: string;
-  readonly parameterNames: readonly string[];
+  readonly rawNodes?: readonly TemplateNode[];
 }
-export type RoutineSchema = StandardSchemaV1$1<any, any>;
-export interface RoutineContract<Output extends Readonly<Record<string, unknown>> = Readonly<Record<string, unknown>>, Sets extends readonly RoutineSchema[] = readonly RoutineSchema[], ReturnValue = unknown> {
-  readonly output?: StandardSchemaV1$1<any, Output>;
-  readonly resultSets?: Sets;
-  readonly returnValue?: StandardSchemaV1$1<any, ReturnValue>;
-  readonly procedure?: RoutineProcedure;
+/** Explicit structural SQL fragment. Ordinary interpolations are values; fragments opt into SQL structure. */
+export interface SqlFragment {
+  readonly [SQL_FRAGMENT]: true;
+  readonly ir: TemplateIr;
+  readonly values: readonly unknown[];
+  readonly dialectId: string;
 }
+//#endregion
+//#region src/statement.d.ts
 /**
  * A rendered parameter is always a value. Adapters MUST NOT interpret it as
  * raw SQL, an identifier, a nested query, a driver-specific fragment, or a
@@ -284,6 +309,10 @@ export interface RenderedParameter {
   readonly direction?: RoutineParameterDirection;
   readonly outputName?: string;
 }
+/**
+ * Immutable logical statement before driver materialization.
+ * `segments.length` is always `parameters.length + 1`; structural SQL lives in segments and parameters remain values.
+ */
 export interface RenderedStatement {
   readonly segments: readonly string[];
   readonly parameters: readonly RenderedParameter[];
@@ -299,34 +328,31 @@ export interface RenderedStatement {
   readonly fingerprint?: string;
   readonly variantFingerprint?: string;
 }
-export interface ParameterTypeHint<Input = unknown> {
-  readonly databaseType: string;
-  readonly length?: number | "max";
-  readonly precision?: number;
-  readonly scale?: number;
-  readonly __input?: Input;
-}
-export interface BoundParameter<Input = unknown> {
-  readonly value: Input;
-  readonly hint: ParameterTypeHint<Input>;
-  readonly [boundParameterBrand]: true;
-}
-export interface RoutineParameter<Input = unknown> {
-  readonly value: Input;
-  readonly hint?: ParameterTypeHint;
-  readonly direction: Exclude<RoutineParameterDirection, "in">;
-  readonly outputName: string;
+/** One logical command shape plus its value matrix; all rows must remain homogeneous. */
+export interface RenderedBulk {
+  readonly statement: RenderedStatement;
+  readonly parameterSets: readonly (readonly unknown[])[];
 }
-export declare function createParameterTypeHint<Input = unknown>(hint: ParameterTypeHint<Input>): ParameterTypeHint<Input>;
-export declare function createBoundParameter<Input>(value: NoInfer<Input>, hint: ParameterTypeHint<Input>): BoundParameter<Input>;
-export declare function isBoundParameter(value: unknown): value is BoundParameter;
-export declare function createRoutineOutParameter(name: string, hint?: ParameterTypeHint): RoutineParameter<null>;
-export declare function createRoutineInOutParameter<Input>(name: string, value: NoInfer<Input>, hint?: ParameterTypeHint<Input>): RoutineParameter<Input>;
-export declare function isRoutineParameter(value: unknown): value is RoutineParameter;
+export declare function createRenderedBulk(bulk: RenderedBulk): RenderedBulk;
+/** Validate and freeze one logical statement without creating a second mutable SQL/value source of truth. */
+/** @throws {TypeError|SqlRenderError} For broken segment/parameter invariants or unsupported bind values. */
+export declare function createRenderedStatement(statement: {
+  readonly segments: readonly string[];
+  readonly parameters: readonly RenderedParameter[];
+  readonly nativeTemplate?: TemplateStringsArray;
+  readonly resultKind: QueryResultKind;
+  readonly routineProcedure?: RoutineProcedure;
+  readonly dialectId: string;
+  readonly fingerprint?: string;
+  readonly variantFingerprint?: string;
+}): RenderedStatement;
+//#endregion
+//#region src/binding.d.ts
 export type ParameterTransportKind = "native-value-template" | "text-positional" | "text-named" | "typed-request";
 export type RequestedReuse = "auto" | "simple" | "reuse";
 export type EffectiveReuse = "simple" | "reuse";
 export type ReuseOwner = "sqlbraid" | "driver" | "server";
+/** Inputs to pure binding description. Placeholder syntax and prepared reuse remain adapter-owned. */
 export interface StatementBindingContext {
   readonly dialectId: string;
   readonly requestedReuse: RequestedReuse;
@@ -341,12 +367,14 @@ export interface BindingDescription {
   readonly direction?: RoutineParameterDirection;
   readonly outputName?: string;
 }
+/** Diagnostic-only literalization controls; the result must never be sent to a database. */
 export interface LiteralizeOptions {
   readonly values?: "inline" | "redacted";
   readonly maxValueLength?: number;
   readonly binary?: "summary" | "full";
   readonly redact?: (parameter: RenderedParameter, index: number) => boolean;
 }
+/** Diagnostic SQL reconstruction with explicit redaction/truncation evidence. */
 export interface LiteralizedSqlResult {
   readonly text: string;
   /**
@@ -358,6 +386,10 @@ export interface LiteralizedSqlResult {
   readonly redactedParameters: number;
   readonly truncatedParameters: number;
 }
+/**
+ * Immutable transport description derived from one logical statement.
+ * `literalizedSql()` reconstructs diagnostics from segments and values; it is never execution input.
+ */
 export interface StatementBindingDescription {
   readonly adapterId: string;
   readonly dialectId: string;
@@ -373,6 +405,10 @@ export interface StatementBindingDescription {
   /** Diagnostic reconstruction only; never use this text as execution input. */
   readonly literalizedSql: (options?: LiteralizeOptions) => LiteralizedSqlResult;
 }
+/**
+ * Driver-owned binding policy. Implementations choose transport, placeholders, type encoding, and reuse ownership.
+ * `describe` must be pure and safe to run before connection acquisition.
+ */
 export interface StatementBindingAdapter {
   readonly id: string;
   describe(statement: RenderedStatement, context: StatementBindingContext): StatementBindingDescription;
@@ -389,10 +425,7 @@ export interface StatementBindingDescriptionOptions {
   };
   readonly formatLiteral?: (parameter: RenderedParameter, index: number, options: LiteralizeOptions) => string | undefined;
 }
-export interface RenderedBulk {
-  readonly statement: RenderedStatement;
-  readonly parameterSets: readonly (readonly unknown[])[];
-}
+/** Binding metadata for a homogeneous bulk operation; values are fetched by item index. */
 export interface BulkBindingDescription {
   readonly adapterId: string;
   readonly dialectId: string;
@@ -403,29 +436,18 @@ export interface BulkBindingDescription {
   valuesAt(index: number): readonly unknown[];
   literalizedSql(index: number, options?: LiteralizeOptions): LiteralizedSqlResult;
 }
-/**
- * Normalize and snapshot a homogeneous bulk's logical statement and value
- * matrix. Values themselves are application-owned and are not cloned.
- */
-export declare function createRenderedBulk(bulk: RenderedBulk): RenderedBulk;
-export declare function createRenderedStatement(statement: {
-  readonly segments: readonly string[];
-  readonly parameters: readonly RenderedParameter[];
-  readonly nativeTemplate?: TemplateStringsArray;
-  readonly resultKind: QueryResultKind;
-  readonly routineProcedure?: RoutineProcedure;
-  readonly dialectId: string;
-  readonly fingerprint?: string;
-  readonly variantFingerprint?: string;
-}): RenderedStatement;
+/** Materialize placeholder text as a derived view; this helper does not own reuse or driver transport policy. */
 export declare function parameterizedSql(statement: RenderedStatement, placeholder: (index: number) => string): string;
+/** Build an immutable binding description before I/O, including adapter reuse policy and diagnostic literalization. */
 export declare function createStatementBindingDescription(statement: RenderedStatement, context: StatementBindingContext, options: StatementBindingDescriptionOptions): StatementBindingDescription;
 /**
- * Build one binding description for a logical bulk statement. The statement
- * metadata is shared by every parameter set; values and diagnostics are
- * addressed only when requested for a particular item.
+ * Build one binding description for a homogeneous bulk statement without cloning application-owned values.
+ * Statement metadata is shared by every parameter set; values and diagnostics are addressed by item index.
  */
 export declare function createBulkBindingDescription(bulk: RenderedBulk, context: StatementBindingContext, options: StatementBindingDescriptionOptions): BulkBindingDescription;
+//#endregion
+//#region src/dialect.d.ts
+/** Lexical features the template parser must know to avoid treating SQL text inside comments/quotes as directives. */
 export interface DialectLexicalProfile {
   readonly lineCommentPrefixes: readonly string[];
   /** Require whitespace/control after -- (MySQL/MariaDB). Defaults to false. */
@@ -437,103 +459,36 @@ export interface DialectLexicalProfile {
   readonly supportsBacktickIdentifiers?: boolean;
   readonly supportsBracketIdentifiers?: boolean;
   readonly supportsOracleQQuotes?: boolean;
-  readonly backslashEscapes?: boolean;
-}
-export interface Dialect {
-  readonly id: string;
-  quoteIdentifier(identifier: string): string;
-  readonly lexicalProfile?: DialectLexicalProfile;
-}
-export interface TypeMapping {
-  readonly databaseType: string;
-  readonly inputType: string;
-  readonly outputType: string;
-  readonly nullable: boolean;
-  readonly numeric?: NumericTypeContract;
-}
-export interface TypePolicy {
-  readonly id: string;
-  readonly hash: string;
-  readonly mappings: readonly TypeMapping[];
-  decode(databaseType: string, value: unknown): unknown;
-  encode(databaseType: string, value: unknown): unknown;
-}
-export interface TextNode {
-  readonly kind: "text";
-  readonly text: string;
-  readonly range: SourceRange;
-}
-export interface BindNode {
-  readonly kind: "bind";
-  readonly interpolation: number;
-  readonly range: SourceRange;
-}
-export interface FragmentNode {
-  readonly kind: "fragment";
-  readonly fragment: SqlFragment;
-  readonly range: SourceRange;
-}
-export interface IdentifierNode {
-  readonly kind: "identifier";
-  readonly value: string | readonly string[];
-  readonly range: SourceRange;
-}
-export interface RawNode {
-  readonly kind: "raw";
-  readonly text: string;
-  readonly range: SourceRange;
-}
-export interface ListNode {
-  readonly kind: "list";
-  readonly values: readonly unknown[];
-  readonly range: SourceRange;
-}
-export interface IfNode {
-  readonly kind: "if";
-  readonly condition: number;
-  readonly children: readonly TemplateNode[];
-  readonly range: SourceRange;
-}
-export interface ChooseWhen {
-  readonly condition: number;
-  readonly children: readonly TemplateNode[];
-  readonly range: SourceRange;
-}
-export interface ChooseNode {
-  readonly kind: "choose";
-  readonly whens: readonly ChooseWhen[];
-  readonly otherwise?: readonly TemplateNode[];
-  readonly range: SourceRange;
-}
-export interface TrimAttributes {
-  readonly prefix: string;
-  readonly prefixOverrides: readonly string[];
-  readonly suffix: string;
-  readonly suffixOverrides: readonly string[];
-}
-export interface TrimNode {
-  readonly kind: "trim";
-  readonly attributes: TrimAttributes;
-  readonly children: readonly TemplateNode[];
-  readonly range: SourceRange;
+  readonly backslashEscapes?: boolean;
 }
-export type TemplateNode = TextNode | BindNode | FragmentNode | IdentifierNode | RawNode | ListNode | IfNode | ChooseNode | TrimNode;
-export interface TemplateIr {
-  readonly version: 1;
-  readonly nodes: readonly TemplateNode[];
-  readonly sourceLength: number;
-  /**
-   * Optional parallel node tree preserving raw JavaScript template text for
-   * native tagged-template transports. The logical node tree remains cooked.
-   */
-  readonly rawNodes?: readonly TemplateNode[];
+/** SQL dialect boundary: identifier quoting plus lexical behavior used by template parsing and trimming. */
+export interface Dialect {
+  readonly id: string;
+  quoteIdentifier(identifier: string): string;
+  readonly lexicalProfile?: DialectLexicalProfile;
 }
-export interface SqlFragment {
-  readonly [SQL_FRAGMENT]: true;
-  readonly ir: TemplateIr;
-  readonly values: readonly unknown[];
-  readonly dialectId: string;
+/** One database type's input/output representation and numeric fidelity claim. */
+export interface TypeMapping {
+  readonly databaseType: string;
+  readonly inputType: string;
+  readonly outputType: string;
+  readonly nullable: boolean;
+  readonly numeric?: NumericTypeContract;
+}
+/** Adapter type policy; it normalizes driver values and encodes inputs without becoming a schema validator. */
+export interface TypePolicy {
+  readonly id: string;
+  readonly hash: string;
+  readonly mappings: readonly TypeMapping[];
+  decode(databaseType: string, value: unknown): unknown;
+  encode(databaseType: string, value: unknown): unknown;
 }
+//#endregion
+//#region src/query.d.ts
+/**
+ * SQLBraid query value. It retains template IR and application mapping metadata until runtime rendering.
+ * `resultSchema` is applied after driver materialization and is never forwarded to the driver.
+ */
 export interface Query<Row = unknown, Kind extends QueryResultKind = "unknown"> {
   readonly ir: TemplateIr;
   readonly values: readonly unknown[];
@@ -549,17 +504,20 @@ export interface Query<Row = unknown, Kind extends QueryResultKind = "unknown">
 export type RowQuery<Row = unknown> = Query<Row, "rows">;
 export type CommandQuery = Query<CommandResult, "command">;
 export type CallQuery<Result extends RoutineCallResult = RoutineCallResult> = Query<Result, "call">;
+/** Driver-normalized command metadata; adapters may expose additional native fields without changing the kind. */
 export interface CommandResult {
   readonly affectedRows?: number;
   readonly insertId?: string;
   readonly [key: string]: unknown;
 }
+/** Materialized row result. Runtime validates that it matches a rows query declaration. */
 export interface RowsExecutionResult<Row = unknown> {
   readonly kind: "rows";
   readonly rows: readonly Row[];
   readonly rowCount?: number;
   readonly command?: never;
 }
+/** Materialized command result. Command executions intentionally expose no row payload. */
 export interface CommandExecutionResult {
   readonly kind: "command";
   readonly rows: readonly [];
@@ -567,125 +525,175 @@ export interface CommandExecutionResult {
   readonly command: CommandResult;
 }
 export type QueryExecutionResult<Row = unknown> = RowsExecutionResult<Row> | CommandExecutionResult;
+/** Execution controls shared by materialized, routine, batch, and stream operations. */
 export interface ExecutionOptions {
   readonly signal?: AbortSignal;
+  /** Override the database reuse preference for this operation; adapters select the effective strategy. */
+  readonly reuse?: RequestedReuse;
 }
+/** Physical SPI may complete synchronously; the public database surface remains asynchronous. */
 export type Awaitable<T> = T | PromiseLike<T>;
+/** Optional Standard Schema mapping applied after query-bound mapping and driver materialization. */
 export interface RowValidationOptions<Row> extends ExecutionOptions {
   readonly schema?: StandardSchemaV1$1<unknown, NoInfer<Row>>;
 }
 export interface StreamOptions<Row> extends RowValidationOptions<Row> {}
+/** Portable transaction isolation vocabulary; adapters reject levels they cannot provide. */
 export type TransactionIsolation = "read-uncommitted" | "read-committed" | "repeatable-read" | "serializable";
+/** Options for the outer physical transaction. Nested `db.tx()` calls are savepoints and accept no second option set. */
 export interface TransactionOptions {
   readonly isolation?: TransactionIsolation;
   readonly readOnly?: boolean;
 }
-export declare class UnsupportedFeatureError extends Error {
-  readonly feature: string;
-  readonly code: `BRAID_${string}`;
-  constructor(feature: string, code: `BRAID_${string}`, message: string, options?: ErrorOptions);
-}
-/** Return true only for a registered, semantically valid feature/code pair. */
-export declare function isPublicUnsupportedFeatureError(error: unknown): error is UnsupportedFeatureError;
-/** An adapter-owned input/transport failure that retains TypeError semantics. */
-export declare class AdapterError extends TypeError {
-  readonly code: `BRAID_${string}`;
-  constructor(code: `BRAID_${string}`, message: string, options?: ErrorOptions);
-}
-export interface RoutineResultSet<Row = unknown> {
-  readonly rows: readonly Row[];
+//#endregion
+//#region src/environment.d.ts
+export interface EnvironmentCapability {
+  readonly status: "guaranteed" | "guarded" | "unsupported";
+  readonly canonical?: "string" | "number" | "Uint8Array";
+  readonly rawRepresentations?: readonly string[];
+  readonly conditionCode?: string;
 }
-export type RoutineResultSetTuple<Sets extends readonly unknown[]> = { readonly [K in keyof Sets]: RoutineResultSet<Sets[K]>; };
-export interface RoutineCallResult<Output extends Readonly<Record<string, unknown>> = Readonly<Record<string, unknown>>, Sets extends readonly unknown[] = readonly unknown[], ReturnValue = unknown> {
-  readonly output: Output;
-  readonly resultSets: RoutineResultSetTuple<Sets>;
-  readonly returnValue?: ReturnValue;
+/** Observed database/driver/runtime evidence plus exact support-target matching. */
+export interface DatabaseEnvironment {
+  readonly database: {
+    readonly product: string;
+    readonly version?: string;
+    readonly edition?: string;
+  };
+  readonly driver: {
+    readonly id: string;
+    readonly version?: string;
+    readonly profile?: string;
+  };
+  readonly runtime: {
+    readonly id: string;
+    readonly version?: string;
+  };
+  readonly typePolicy?: {
+    readonly id: string;
+    readonly hash: string;
+  };
+  readonly capabilities: Readonly<Record<string, EnvironmentCapability>>;
+  readonly supportMatch: {
+    readonly status: "official" | "conditional" | "compatible";
+    readonly targetId?: string;
+    readonly reason?: string;
+  };
 }
-export type RoutineSchemaOutput<Schema> = Schema extends StandardSchemaV1$1<any, infer Output> ? Output : never;
-type RoutineRowsFromSchemas<Schemas extends readonly RoutineSchema[]> = { readonly [K in keyof Schemas]: RoutineSchemaOutput<Schemas[K]>; };
-export type RoutineResultFromContract<Contract extends RoutineContract> = RoutineCallResult<Contract["output"] extends RoutineSchema ? RoutineSchemaOutput<Contract["output"]> extends Readonly<Record<string, unknown>> ? RoutineSchemaOutput<Contract["output"]> : Readonly<Record<string, unknown>> : Readonly<Record<string, unknown>>, Contract["resultSets"] extends (infer Schemas extends readonly RoutineSchema[]) ? RoutineRowsFromSchemas<Schemas> : readonly unknown[], Contract["returnValue"] extends RoutineSchema ? RoutineSchemaOutput<Contract["returnValue"]> : unknown> & (Contract extends {
-  readonly returnValue: RoutineSchema;
-} ? {
-  readonly returnValue: RoutineSchemaOutput<Contract["returnValue"]>;
-} : {});
-export type RoutineResultSource = {
-  readonly kind: "out-cursor";
-  readonly name?: string;
-  readonly parameterIndex?: number;
-} | {
-  readonly kind: "implicit";
-  readonly index: number;
-} | {
-  readonly kind: "emitted";
-  readonly index: number;
-};
-export interface DriverRoutineResultSet {
-  readonly rows: readonly unknown[];
-  readonly source: RoutineResultSource;
+/** Adapter evidence only. Probes run through the ordinary observed, leased query path. */
+export interface DriverEnvironment {
+  readonly database: DatabaseEnvironment["database"];
+  readonly driver: DatabaseEnvironment["driver"];
+  readonly typePolicy?: {
+    readonly id: string;
+    readonly hash: string;
+  };
+  readonly capabilities: DatabaseEnvironment["capabilities"];
+  readonly probe?: {
+    readonly statement: RenderedStatement;
+    readonly read: (rows: readonly unknown[]) => {
+      readonly version?: string;
+      readonly edition?: string;
+      readonly capabilities?: Readonly<Record<string, EnvironmentCapability>>;
+    };
+  };
 }
-export interface DriverRoutineResult {
-  readonly output: Readonly<Record<string, unknown>>;
-  readonly returnValue?: unknown;
-  readonly resultSets: readonly DriverRoutineResultSet[];
+/** Structural subset of a support manifest; importing support tooling is unnecessary. */
+export interface EnvironmentSupportTarget {
+  readonly id: string;
+  readonly status: string;
+  readonly database: {
+    readonly product: string;
+    readonly version: string;
+    readonly edition: string;
+  };
+  readonly driver: {
+    readonly id: string;
+    readonly version: string;
+    readonly profile: string;
+  };
+  readonly runtime: {
+    readonly id: string;
+    readonly version: string;
+  };
+  readonly typePolicy: {
+    readonly id: string;
+    readonly hash: string;
+  };
+  readonly evidence: {
+    readonly status: string;
+  };
 }
-export type RoutineMappingLocation = {
-  readonly kind: "output";
-} | {
-  readonly kind: "return-value";
-} | {
-  readonly kind: "result-set";
-  readonly resultSetIndex: number;
-  readonly rowIndex: number;
-};
-export type DriverCapabilityErrorCode = "BRAID_STREAM_UNSUPPORTED" | "BRAID_CALL_UNSUPPORTED" | "BRAID_CALL_RESULT_SETS" | "BRAID_CALL_CURSOR_TX_REQUIRED" | "BRAID_CALL_OUT_UNSUPPORTED" | "BRAID_CALL_RETURN_UNSUPPORTED" | "BRAID_CALL_CURSOR_UNSUPPORTED" | "BRAID_RESOURCE_CLEANUP";
-export declare class RoutineMappingError extends Error {
-  static readonly code: "BRAID_CALL_MAP";
-  readonly code: "BRAID_CALL_MAP";
-  readonly location: RoutineMappingLocation;
-  constructor(message: string, location: RoutineMappingLocation, options?: {
-    readonly cause?: unknown;
-  });
+export interface EnvironmentOptions {
+  readonly targets?: readonly EnvironmentSupportTarget[];
+  /** Re-probe the current lease instead of returning the cached observation. */
+  readonly refresh?: boolean;
 }
+//#endregion
+//#region src/executor.d.ts
+/** Native or adapter execution strategy reported for a bulk operation; the label does not imply atomicity. */
 export type BulkExecutionMode = "native-bulk" | "pipeline" | "prepared-loop" | "remote-batch";
+/** Driver bulk result normalized for runtime accounting and observer events. */
 export interface BulkExecutionResult {
   readonly inputCount: number;
   readonly affectedRows?: number;
   readonly executionMode: BulkExecutionMode;
 }
+/**
+ * Physical execution SPI for one serialized resource.
+ * Query/call/control methods may be synchronous at this boundary; streams remain async iterables and retain ownership until closed.
+ */
 export interface QueryExecutor {
   /** Stable identity for the physical execution resource shared by wrappers; pools must use a leased resource. */
   readonly ownershipKey?: object;
   readonly statementBinding: StatementBindingAdapter;
   readonly environment?: DriverEnvironment;
+  /** Execute one materialized statement on this physical resource. */
   query<Row>(rendered: RenderedStatement, binding?: StatementBindingDescription, options?: ExecutionOptions): Awaitable<QueryExecutionResult<Row>>;
+  /** Open a true driver stream; the physical resource remains owned until iteration closes. */
   stream<Row>(rendered: RenderedStatement, binding?: StatementBindingDescription, options?: ExecutionOptions): AsyncIterable<Row>;
+  /** Execute a routine call and return normalized scalar/result-set channels. */
   call(rendered: RenderedStatement, binding?: StatementBindingDescription, options?: ExecutionOptions): Awaitable<DriverRoutineResult>;
+  /** Optional homogeneous bulk protocol. The reported execution mode does not imply atomicity. */
   bulk?(bulk: RenderedBulk, binding: BulkBindingDescription, options?: ExecutionOptions): Awaitable<BulkExecutionResult>;
+  /** Pure pre-acquire validation for adapter-specific transaction option support. */
   validateTransactionOptions?(options: TransactionOptions): void;
+  /** Begin the outer transaction on this physical resource. */
   begin?(options?: TransactionOptions): Awaitable<void>;
+  /** Commit the outer transaction on this physical resource. */
   commit?(): Awaitable<void>;
+  /** Roll back the outer transaction on this physical resource. */
   rollback?(): Awaitable<void>;
+  /** Create a nested transaction boundary on the current resource. */
   savepoint?(name: string): Awaitable<void>;
+  /** Roll back the current resource to a previously created savepoint. */
   rollbackTo?(name: string): Awaitable<void>;
+  /** End the logical savepoint boundary; adapters may implement this as a no-op when the database releases implicitly. */
   releaseSavepoint?(name: string): Awaitable<void>;
 }
+/** Acquired physical resource. The lease owns release/discard, while runtime owns operation serialization. */
 export interface ConnectionLease extends QueryExecutor {
   release(options?: {
     readonly discard?: boolean;
   }): void | Promise<void>;
 }
+/** Lease factory for pools; acquiring one lease is the boundary that establishes physical connection ownership. */
 export interface ConnectionProvider {
   readonly statementBinding: StatementBindingAdapter;
   readonly environment?: DriverEnvironment;
   validateTransactionOptions?(options: TransactionOptions): void;
   acquire(): Promise<ConnectionLease>;
 }
+//#endregion
+//#region src/observers.d.ts
+/** Immutable observer projection of adapter transport and reuse decisions. */
 export interface QueryExecutionPlan {
   readonly adapterId: string;
   readonly dialectId: string;
   readonly transport: ParameterTransportKind;
   readonly reuse: StatementBindingDescription["reuse"];
 }
+/** Observer event emitted after rendering and binding, before physical execution. */
 export interface QueryReadyEvent {
   readonly type: "query:ready";
   readonly purpose?: "environment";
@@ -709,6 +717,7 @@ export interface QueryReadyEvent {
   readonly transactionDepth: number;
   readonly transactionScoped: boolean;
 }
+/** Observer event emitted after driver materialization and result-kind validation, before mapping. */
 export interface QueryResultEvent {
   readonly type: "query:result";
   readonly purpose?: "environment";
@@ -725,6 +734,7 @@ export interface QueryResultEvent {
   readonly transactionDepth: number;
   readonly transactionScoped: boolean;
 }
+/** Observer event emitted after query-bound and execution-level mapping completes. */
 export interface QueryMappedEvent {
   readonly type: "query:mapped";
   readonly purpose?: "environment";
@@ -738,6 +748,7 @@ export interface QueryMappedEvent {
   readonly transactionDepth: number;
   readonly transactionScoped: boolean;
 }
+/** Observer event emitted after the complete homogeneous bulk is prepared, before physical execution. */
 export interface BulkReadyEvent {
   readonly type: "bulk:ready";
   readonly operationId: string;
@@ -748,6 +759,7 @@ export interface BulkReadyEvent {
   readonly valuesAt: (index: number) => readonly unknown[];
   readonly literalizedSql: (index: number, options?: LiteralizeOptions) => LiteralizedSqlResult;
 }
+/** Observer event emitted after bulk execution and result normalization. */
 export interface BulkResultEvent {
   readonly type: "bulk:result";
   readonly operationId: string;
@@ -759,6 +771,7 @@ export interface BulkResultEvent {
   readonly transactionScoped: boolean;
 }
 export type QueryErrorStage = "render" | "prepared" | "observer-before" | "materialize" | "acquire" | "driver" | "result-kind" | "cardinality" | "query-map" | "execution-map" | "observer-after" | "release" | "stream" | "transaction";
+/** Observer event describing the stage and truthful execution flags for a failed operation. */
 export interface QueryErrorEvent {
   readonly type: "query:error";
   readonly purpose?: "environment";
@@ -773,6 +786,7 @@ export interface QueryErrorEvent {
   readonly transactionDepth: number;
   readonly transactionScoped: boolean;
 }
+/** Observer event emitted when a stream is admitted and its lease is about to be retained. */
 export interface StreamStartEvent {
   readonly type: "stream:start";
   readonly operationId: string;
@@ -790,115 +804,40 @@ export interface StreamStartEvent {
   readonly declaredKind: "rows";
   readonly variantFingerprint?: string;
   readonly preparedName?: string;
-  readonly transactionDepth: number;
-  readonly transactionScoped: boolean;
-}
-export interface StreamEndEvent {
-  readonly type: "stream:end";
-  readonly operationId: string;
-  readonly status: "completed" | "error";
-  readonly durationMs: number;
-  readonly rowCount: number;
-  readonly error?: unknown;
-  readonly transactionDepth: number;
-  readonly transactionScoped: boolean;
-}
-export type TransactionEventPhase = "begin" | "commit" | "rollback" | "savepoint" | "rollback-to-savepoint" | "release-savepoint";
-export interface TransactionEvent {
-  readonly type: "transaction";
-  readonly transactionId: string;
-  readonly phase: TransactionEventPhase;
-  readonly status: "requested" | "completed" | "failed";
-  readonly depth: number;
-  readonly savepointName?: string;
-  readonly durationMs?: number;
-  readonly error?: unknown;
-}
-export type ExecutionEvent = QueryReadyEvent | QueryResultEvent | QueryMappedEvent | BulkReadyEvent | BulkResultEvent | QueryErrorEvent | StreamStartEvent | StreamEndEvent | TransactionEvent;
-export interface ExecutionObserver {
-  onEvent(event: ExecutionEvent): void | Promise<void>;
-}
-export interface EnvironmentCapability {
-  readonly status: "guaranteed" | "guarded" | "unsupported";
-  readonly canonical?: "string" | "number" | "Uint8Array";
-  readonly rawRepresentations?: readonly string[];
-  readonly conditionCode?: string;
-}
-export interface DatabaseEnvironment {
-  readonly database: {
-    readonly product: string;
-    readonly version?: string;
-    readonly edition?: string;
-  };
-  readonly driver: {
-    readonly id: string;
-    readonly version?: string;
-    readonly profile?: string;
-  };
-  readonly runtime: {
-    readonly id: string;
-    readonly version?: string;
-  };
-  readonly typePolicy?: {
-    readonly id: string;
-    readonly hash: string;
-  };
-  readonly capabilities: Readonly<Record<string, EnvironmentCapability>>;
-  readonly supportMatch: {
-    readonly status: "official" | "conditional" | "compatible";
-    readonly targetId?: string;
-    readonly reason?: string;
-  };
-}
-/** Adapter evidence only. Probes run through the ordinary observed, leased query path. */
-export interface DriverEnvironment {
-  readonly database: DatabaseEnvironment["database"];
-  readonly driver: DatabaseEnvironment["driver"];
-  readonly typePolicy?: {
-    readonly id: string;
-    readonly hash: string;
-  };
-  readonly capabilities: DatabaseEnvironment["capabilities"];
-  readonly probe?: {
-    readonly statement: RenderedStatement;
-    readonly read: (rows: readonly unknown[]) => {
-      readonly version?: string;
-      readonly edition?: string;
-      readonly capabilities?: Readonly<Record<string, EnvironmentCapability>>;
-    };
-  };
+  readonly transactionDepth: number;
+  readonly transactionScoped: boolean;
 }
-/** Structural subset of a support manifest; importing support tooling is unnecessary. */
-export interface EnvironmentSupportTarget {
-  readonly id: string;
-  readonly status: string;
-  readonly database: {
-    readonly product: string;
-    readonly version: string;
-    readonly edition: string;
-  };
-  readonly driver: {
-    readonly id: string;
-    readonly version: string;
-    readonly profile: string;
-  };
-  readonly runtime: {
-    readonly id: string;
-    readonly version: string;
-  };
-  readonly typePolicy: {
-    readonly id: string;
-    readonly hash: string;
-  };
-  readonly evidence: {
-    readonly status: string;
-  };
+/** Terminal stream event; delivery is attempted for every observer even if one observer fails. */
+export interface StreamEndEvent {
+  readonly type: "stream:end";
+  readonly operationId: string;
+  readonly status: "completed" | "error";
+  readonly durationMs: number;
+  readonly rowCount: number;
+  readonly error?: unknown;
+  readonly transactionDepth: number;
+  readonly transactionScoped: boolean;
 }
-export interface EnvironmentOptions {
-  readonly targets?: readonly EnvironmentSupportTarget[];
-  /** Re-probe the current lease instead of returning the cached observation. */
-  readonly refresh?: boolean;
+export type TransactionEventPhase = "begin" | "commit" | "rollback" | "savepoint" | "rollback-to-savepoint" | "release-savepoint";
+/** Transaction-control lifecycle event for outer transactions and nested savepoints. */
+export interface TransactionEvent {
+  readonly type: "transaction";
+  readonly transactionId: string;
+  readonly phase: TransactionEventPhase;
+  readonly status: "requested" | "completed" | "failed";
+  readonly depth: number;
+  readonly savepointName?: string;
+  readonly durationMs?: number;
+  readonly error?: unknown;
+}
+export type ExecutionEvent = QueryReadyEvent | QueryResultEvent | QueryMappedEvent | BulkReadyEvent | BulkResultEvent | QueryErrorEvent | StreamStartEvent | StreamEndEvent | TransactionEvent;
+/** Readonly observer hook. Observers may fail execution, but cannot rewrite SQL, binds, routing, or results. */
+export interface ExecutionObserver {
+  onEvent(event: ExecutionEvent): void | Promise<void>;
 }
+//#endregion
+//#region src/database.d.ts
+/** Root database behavior: observers and default prepared-reuse preference. */
 export interface DatabaseOptions {
   readonly observers?: readonly ExecutionObserver[];
   readonly reuse?: RequestedReuse;
@@ -910,6 +849,7 @@ export type PreparedFactoryOptions = {
   readonly input: "required";
 };
 export type PreparedArguments<Input, Options> = [Input] extends [never] ? [options?: Options] : [input: Input, options?: Options];
+/** Prepared handle whose input arity and result helpers are fixed by the factory's query kind. */
 export type PreparedQuery<Input, Q extends PreparableQuery> = {
   readonly name: string;
 } & (Q extends CallQuery<infer Result> ? {
@@ -924,15 +864,29 @@ export type PreparedQuery<Input, Q extends PreparableQuery> = {
 } : {}));
 export type ExecutableQuery = RowQuery<unknown> | Query<unknown, "command"> | Query<unknown, "unknown">;
 export type ExecutionResultOf<Q> = Q extends RowQuery<infer Row> ? RowsExecutionResult<Row> : Q extends Query<unknown, "command"> ? CommandExecutionResult : Q extends Query<infer Row, "unknown"> ? QueryExecutionResult<Row> : never;
+/**
+ * Async application database surface.
+ * Root pooled operations acquire/release per operation; `session()` and `tx()` callbacks pin a scoped resource.
+ * Scoped handles expire when their callback returns, and streams must close before a scope can finish.
+ */
 export interface Database {
+  /** Observe database/driver/runtime evidence and optionally match it against exact support targets. */
   environment(options?: EnvironmentOptions): Promise<DatabaseEnvironment>;
+  /** Materialize every row and apply query/execution mapping after the root lease is released. */
   all<Row>(query: RowQuery<Row>, options?: RowValidationOptions<Row>): Promise<readonly Row[]>;
+  /** Require exactly one row; cardinality is checked before application mapping. */
   one<Row>(query: RowQuery<Row>, options?: RowValidationOptions<Row>): Promise<Row>;
+  /** Return `undefined` for zero rows and reject when more than one row is returned. */
   maybeOne<Row>(query: RowQuery<Row>, options?: RowValidationOptions<Row>): Promise<Row | undefined>;
+  /** Execute a row, command, or unknown query and preserve its normalized result kind. */
   execute<Q extends ExecutableQuery>(query: Q, options?: ExecutionOptions): Promise<ExecutionResultOf<Q>>;
+  /** Execute a routine query and materialize all normalized routine channels before mapping. */
   call<Result extends RoutineCallResult>(query: CallQuery<Result>, options?: ExecutionOptions): Promise<Result>;
+  /** Execute different queries sequentially on one physical use/lease. This is not an implicit transaction. */
   batch<const Queries extends readonly ExecutableQuery[]>(queries: Queries, options?: ExecutionOptions): Promise<{ readonly [K in keyof Queries]: ExecutionResultOf<Queries[K]>; }>;
+  /** Execute one homogeneous command shape for many inputs using the adapter's bulk strategy. */
   bulk<Input>(inputs: readonly Input[], factory: (input: Input, index: number) => CommandQuery, options?: ExecutionOptions): Promise<BulkResult>;
+  /** Create a prepared handle whose first successful execution locks the logical SQLBraid shape. */
   prepare<Factory extends () => PreparableQuery>(name: string, factory: Factory & (Parameters<Factory> extends [] ? unknown : never), options: {
     readonly input: "none";
   }): PreparedQuery<never, ReturnType<Factory>>;
@@ -940,47 +894,260 @@ export interface Database {
   prepare<Factory extends (input: never) => PreparableQuery>(name: string, factory: Factory & (number extends Parameters<Factory>["length"] ? unknown : Parameters<Factory>["length"] extends 0 | 1 ? unknown : never), options: {
     readonly input: "required";
   }): PreparedQuery<Parameters<Factory>[0], ReturnType<Factory>>;
+  /** Stream rows without full buffering; the physical resource remains pinned until iteration closes. */
   stream<Row>(query: RowQuery<Row>, options?: StreamOptions<Row>): AsyncIterable<Row>;
+  /** Pin one physical resource for the callback without implicitly starting a transaction. */
   session<T>(callback: (database: Database) => Promise<T>): Promise<T>;
+  /** Run the callback in one physical transaction; nested calls use savepoints on the same resource. */
   tx<T>(callback: (database: Database) => Promise<T>): Promise<T>;
   tx<T>(options: TransactionOptions, callback: (database: Database) => Promise<T>): Promise<T>;
 }
+/** Normalized bulk accounting; root bulk is not implicitly transactional. */
 export interface BulkResult {
   readonly inputCount: number;
   readonly affectedRows?: number;
 }
 export type QueryRow<Q> = Q extends Query<infer Row, QueryResultKind> ? Row : never;
+//#endregion
+//#region src/authoring.d.ts
+/** Generic SQL tag shape used by configured dialect/query-kind specializations. */
 export interface SqlTagLike<Kind extends QueryResultKind = QueryResultKind, Row = unknown> {
   (strings: TemplateStringsArray, ...values: readonly unknown[]): Query<Row, Kind>;
 }
 export interface RoutineContractTag<Contract extends RoutineContract> {
   (strings: TemplateStringsArray, ...values: readonly unknown[]): CallQuery<RoutineResultFromContract<Contract>>;
 }
+/** Row-specialized tag supporting either a TypeScript row type or a Standard Schema mapper. */
 export interface RowsTag {
   <Input, Output>(schema: StandardSchemaV1$1<Input, Output>): SqlTagLike<"rows", Output>;
   <Row = unknown>(strings: TemplateStringsArray, ...values: readonly unknown[]): RowQuery<Row>;
 }
+/**
+ * SQL authoring surface. Values are bound by default; `ident`, `fragment`, `list`, `join`, and `raw` are explicit structure.
+ */
 export interface SqlTag extends SqlTagLike<"unknown"> {
+  /** Declare a row-producing query, optionally with query-bound Standard Schema mapping. */
   rows: RowsTag;
+  /** Declare a command query that must normalize to command metadata. */
   command: (strings: TemplateStringsArray, ...values: readonly unknown[]) => CommandQuery;
+  /** Declare a routine query, optionally with explicit output/result-set/return mapping contracts. */
   call: {
     <Result extends RoutineCallResult = RoutineCallResult>(strings: TemplateStringsArray, ...values: readonly unknown[]): CallQuery<Result>;
     <Contract extends RoutineContract>(contract: Contract): RoutineContractTag<Contract>;
   };
+  /** Attach explicit database parameter metadata without turning the value into SQL structure. */
   bind<Input>(value: NoInfer<Input>, hint: ParameterTypeHint<Input>): BoundParameter<Input>;
+  /** Declare a routine OUT parameter owned by the adapter. */
   out(name: string, hint?: ParameterTypeHint): RoutineParameter<null>;
+  /** Declare a routine INOUT parameter owned by the adapter. */
   inOut<Input>(name: string, value: NoInfer<Input>, hint?: ParameterTypeHint<Input>): RoutineParameter<Input>;
+  /** Create explicit SQL structure while preserving ordinary interpolations as values. */
   fragment: (strings: TemplateStringsArray, ...values: readonly unknown[]) => SqlFragment;
+  /** Empty structural fragment for conditional composition. */
   empty: SqlFragment;
+  /** Create a dialect-quoted identifier or qualified identifier path. */
   ident: (identifier: string | readonly string[]) => SqlFragment;
+  /** Insert verbatim SQL structure. Never pass user-controlled or otherwise untrusted text. */
   raw: (text: string) => SqlFragment;
+  /** Join already-structural fragments with a structural separator. */
   join: (items: readonly SqlFragment[], separator?: SqlFragment) => SqlFragment;
+  /** Expand an array as a structural comma-separated list of value binds. */
   list: (values: readonly unknown[]) => SqlFragment;
 }
-export declare class SqlRenderError extends Error {
-  readonly code: string;
-  constructor(code: string, message: string);
+//#endregion
+//#region src/authoring-modules.d.ts
+/** Data-only authoring identity shared by compiler, tooling, and editor consumers. */
+type AuthoringModuleCatalogEntry = {
+  readonly moduleSpecifier: string;
+  readonly dialectId?: "postgres" | "mysql" | "mariadb" | "sqlite" | "oracle" | "mssql";
+  readonly helperFamily: "template" | "facade";
+};
+export declare const AUTHORING_MODULE_CATALOG: readonly AuthoringModuleCatalogEntry[];
+//#endregion
+//#region src/capabilities.d.ts
+/**
+ * The machine-readable capability vocabulary shared by adapters, support data,
+ * and documentation. A capability's family describes what its status proves;
+ * representation and metadata evidence are not execution support aliases.
+ */
+type CapabilityFamily = "support" | "representation" | "metadata";
+interface WellKnownCapability {
+  readonly id: string;
+  readonly family: CapabilityFamily;
 }
+declare const definitions: readonly [{
+  readonly id: "sql.native-transparency";
+  readonly family: "support";
+}, {
+  readonly id: "sql.generated-structure";
+  readonly family: "support";
+}, {
+  readonly id: "result.rows";
+  readonly family: "support";
+}, {
+  readonly id: "result.command";
+  readonly family: "support";
+}, {
+  readonly id: "result.multiple-sets";
+  readonly family: "support";
+}, {
+  readonly id: "result.standard-schema";
+  readonly family: "support";
+}, {
+  readonly id: "numeric.exact-integer";
+  readonly family: "representation";
+}, {
+  readonly id: "numeric.exact-decimal";
+  readonly family: "representation";
+}, {
+  readonly id: "numeric.approximate-float";
+  readonly family: "representation";
+}, {
+  readonly id: "numeric.approximate-special";
+  readonly family: "representation";
+}, {
+  readonly id: "numeric.bind-exact";
+  readonly family: "representation";
+}, {
+  readonly id: "numeric.aggregate";
+  readonly family: "representation";
+}, {
+  readonly id: "numeric.command-metadata";
+  readonly family: "representation";
+}, {
+  readonly id: "numeric.special-values";
+  readonly family: "representation";
+}, {
+  readonly id: "numeric.scale-greater-than-precision";
+  readonly family: "representation";
+}, {
+  readonly id: "numeric.negative-scale";
+  readonly family: "representation";
+}, {
+  readonly id: "data.json-parsed";
+  readonly family: "representation";
+}, {
+  readonly id: "data.json-lossless-text";
+  readonly family: "representation";
+}, {
+  readonly id: "data.sql-variant";
+  readonly family: "representation";
+}, {
+  readonly id: "data.oracle-object";
+  readonly family: "representation";
+}, {
+  readonly id: "data.oracle-collection";
+  readonly family: "representation";
+}, {
+  readonly id: "data.vector";
+  readonly family: "representation";
+}, {
+  readonly id: "data.binary";
+  readonly family: "representation";
+}, {
+  readonly id: "data.uuid";
+  readonly family: "representation";
+}, {
+  readonly id: "data.temporal-native";
+  readonly family: "representation";
+}, {
+  readonly id: "data.temporal-lossless";
+  readonly family: "representation";
+}, {
+  readonly id: "data.timezone";
+  readonly family: "representation";
+}, {
+  readonly id: "metadata.command-safe";
+  readonly family: "metadata";
+}, {
+  readonly id: "dml.insert-returning";
+  readonly family: "support";
+}, {
+  readonly id: "dml.update-returning";
+  readonly family: "support";
+}, {
+  readonly id: "dml.delete-returning";
+  readonly family: "support";
+}, {
+  readonly id: "dml.merge-returning";
+  readonly family: "support";
+}, {
+  readonly id: "dml.upsert-returning";
+  readonly family: "support";
+}, {
+  readonly id: "session.pinned";
+  readonly family: "support";
+}, {
+  readonly id: "statement.prepare";
+  readonly family: "support";
+}, {
+  readonly id: "statement.cancel";
+  readonly family: "support";
+}, {
+  readonly id: "statement.stream";
+  readonly family: "support";
+}, {
+  readonly id: "statement.bulk";
+  readonly family: "support";
+}, {
+  readonly id: "execution.bulk-fidelity";
+  readonly family: "support";
+}, {
+  readonly id: "transaction";
+  readonly family: "support";
+}, {
+  readonly id: "transaction.savepoint";
+  readonly family: "support";
+}, {
+  readonly id: "transaction.read-only";
+  readonly family: "support";
+}, {
+  readonly id: "transaction.isolation.read-uncommitted";
+  readonly family: "support";
+}, {
+  readonly id: "transaction.isolation.read-committed";
+  readonly family: "support";
+}, {
+  readonly id: "transaction.isolation.repeatable-read";
+  readonly family: "support";
+}, {
+  readonly id: "transaction.isolation.serializable";
+  readonly family: "support";
+}, {
+  readonly id: "routine.call";
+  readonly family: "support";
+}, {
+  readonly id: "routine.out";
+  readonly family: "support";
+}, {
+  readonly id: "routine.inout";
+  readonly family: "support";
+}, {
+  readonly id: "routine.result-sets";
+  readonly family: "support";
+}, {
+  readonly id: "routine.out-cursor";
+  readonly family: "support";
+}, {
+  readonly id: "routine.return-value";
+  readonly family: "support";
+}, {
+  readonly id: "metadata.identity";
+  readonly family: "metadata";
+}, {
+  readonly id: "metadata.generated";
+  readonly family: "metadata";
+}, {
+  readonly id: "metadata.routines";
+  readonly family: "metadata";
+}, {
+  readonly id: "metadata.types";
+  readonly family: "metadata";
+}];
+export declare const WELL_KNOWN_CAPABILITIES: readonly WellKnownCapability[];
+type WellKnownCapabilityId = (typeof definitions)[number]["id"];
+export declare const WELL_KNOWN_CAPABILITY_IDS: readonly WellKnownCapabilityId[];
+export declare function isWellKnownCapabilityId(value: string): value is WellKnownCapabilityId;
 //#endregion
 export type { AuthoringModuleCatalogEntry, CapabilityFamily, StandardSchemaV1, WellKnownCapability, WellKnownCapabilityId };
 //# sourceMappingURL=index.d.ts.map