@sqlbraid/core 0.1.0-rc.0

package/dist/index.d.ts

@@ -0,0 +1,735 @@
+import { StandardSchemaV1, StandardSchemaV1 as StandardSchemaV1$1 } from "@standard-schema/spec";
+//#region src/index.d.ts
+export declare const SQL_FRAGMENT: unique symbol;
+declare const boundParameterBrand: unique symbol;
+export interface SourceRange {
+  readonly start: number;
+  readonly end: number;
+}
+export interface RenderLimits {
+  readonly maxSqlBytes?: number;
+  readonly maxBindCount?: number;
+  readonly maxStructuralItems?: number;
+  readonly maxNestingDepth?: number;
+}
+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 ExactIntegerRange {
+  readonly min?: bigint;
+  readonly max?: bigint;
+}
+export declare class ResultExactnessError extends Error {
+  readonly code = "BRAID_RESULT_EXACTNESS";
+  constructor(message?: string);
+}
+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[];
+}
+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;
+}
+/**
+ * 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
+ * structural tagged-template command.
+ */
+export interface RenderedParameter {
+  readonly value: unknown;
+  readonly interpolation?: number;
+  readonly hint?: ParameterTypeHint;
+  readonly direction?: RoutineParameterDirection;
+  readonly outputName?: string;
+}
+export interface RenderedStatement {
+  readonly segments: readonly string[];
+  readonly parameters: readonly RenderedParameter[];
+  readonly dialectId: string;
+  readonly resultKind: QueryResultKind;
+  readonly routineProcedure?: RoutineProcedure;
+  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;
+}
+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 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";
+export interface StatementBindingContext {
+  readonly dialectId: string;
+  readonly requestedReuse: RequestedReuse;
+  readonly preparedName?: string;
+  readonly transactionScoped?: boolean;
+}
+export interface BindingDescription {
+  readonly index: number;
+  readonly name?: string;
+  readonly interpolation?: number;
+  readonly hint?: ParameterTypeHint;
+  readonly direction?: RoutineParameterDirection;
+  readonly outputName?: string;
+}
+export interface LiteralizeOptions {
+  readonly values?: "inline" | "redacted";
+  readonly maxValueLength?: number;
+  readonly binary?: "summary" | "full";
+  readonly redact?: (parameter: RenderedParameter, index: number) => boolean;
+}
+export interface LiteralizedSqlResult {
+  readonly text: string;
+  /**
+   * True when no diagnostic parameter representation was truncated. Redaction,
+   * unsupported literal markers, and divergence from wire SQL do not make it
+   * incomplete.
+   */
+  readonly complete: boolean;
+  readonly redactedParameters: number;
+  readonly truncatedParameters: number;
+}
+export interface StatementBindingDescription {
+  readonly adapterId: string;
+  readonly dialectId: string;
+  readonly transport: ParameterTransportKind;
+  readonly parameterizedSql?: string;
+  readonly bindings: readonly BindingDescription[];
+  readonly reuse: {
+    readonly requested: RequestedReuse;
+    readonly effective: EffectiveReuse;
+    readonly owner: ReuseOwner;
+    readonly capacity?: number;
+  };
+  /** Diagnostic reconstruction only; never use this text as execution input. */
+  readonly literalizedSql: (options?: LiteralizeOptions) => LiteralizedSqlResult;
+}
+export interface StatementBindingAdapter {
+  readonly id: string;
+  describe(statement: RenderedStatement, context: StatementBindingContext): StatementBindingDescription;
+  describeBulk?(bulk: RenderedBulk, context: StatementBindingContext): BulkBindingDescription;
+}
+export interface StatementBindingDescriptionOptions {
+  readonly adapterId: string;
+  readonly transport: ParameterTransportKind;
+  readonly placeholder?: (index: number) => string;
+  readonly reuse: {
+    readonly effective: EffectiveReuse;
+    readonly owner: ReuseOwner;
+    readonly capacity?: number;
+  };
+  readonly formatLiteral?: (parameter: RenderedParameter, index: number, options: LiteralizeOptions) => string | undefined;
+}
+export interface RenderedBulk {
+  readonly statement: RenderedStatement;
+  readonly parameterSets: readonly (readonly unknown[])[];
+}
+export interface BulkBindingDescription {
+  readonly adapterId: string;
+  readonly dialectId: string;
+  readonly transport: ParameterTransportKind;
+  readonly parameterizedSql?: string;
+  readonly bindings: readonly BindingDescription[];
+  readonly itemCount: number;
+  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 resultKind: QueryResultKind;
+  readonly routineProcedure?: RoutineProcedure;
+  readonly dialectId: string;
+  readonly fingerprint?: string;
+  readonly variantFingerprint?: string;
+}): RenderedStatement;
+export declare function parameterizedSql(statement: RenderedStatement, placeholder: (index: number) => string): string;
+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.
+ */
+export declare function createBulkBindingDescription(bulk: RenderedBulk, context: StatementBindingContext, options: StatementBindingDescriptionOptions): BulkBindingDescription;
+export interface DialectLexicalProfile {
+  readonly lineCommentPrefixes: readonly string[];
+  readonly supportsNestedBlockComments?: boolean;
+  readonly supportsDollarQuotes?: boolean;
+  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;
+}
+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;
+}
+export interface SqlFragment {
+  readonly [SQL_FRAGMENT]: true;
+  readonly ir: TemplateIr;
+  readonly values: readonly unknown[];
+  readonly dialectId: string;
+}
+export interface Query<Row = unknown, Kind extends QueryResultKind = "unknown"> {
+  readonly ir: TemplateIr;
+  readonly values: readonly unknown[];
+  readonly resultKind: Kind;
+  /**
+   * Application result mapper. Never forwarded to a DB driver.
+   */
+  readonly resultSchema?: StandardSchemaV1$1<unknown, Row>;
+  readonly routineContract?: RoutineContract;
+  render(): RenderedStatement;
+  readonly __row?: Row;
+}
+export type RowQuery<Row = unknown> = Query<Row, "rows">;
+export type CommandQuery = Query<CommandResult, "command">;
+export type CallQuery<Result extends RoutineCallResult = RoutineCallResult> = Query<Result, "call">;
+export interface CommandResult {
+  readonly affectedRows?: number;
+  readonly insertId?: string;
+  readonly [key: string]: unknown;
+}
+export interface RowsExecutionResult<Row = unknown> {
+  readonly kind: "rows";
+  readonly rows: readonly Row[];
+  readonly rowCount?: number;
+  readonly command?: never;
+}
+export interface CommandExecutionResult {
+  readonly kind: "command";
+  readonly rows: readonly [];
+  readonly rowCount?: number;
+  readonly command: CommandResult;
+}
+export type QueryExecutionResult<Row = unknown> = RowsExecutionResult<Row> | CommandExecutionResult;
+export interface ExecutionOptions {
+  readonly signal?: AbortSignal;
+}
+export interface RowValidationOptions<Row> extends ExecutionOptions {
+  readonly schema?: StandardSchemaV1$1<unknown, NoInfer<Row>>;
+}
+export interface StreamOptions<Row> extends RowValidationOptions<Row> {}
+export type TransactionIsolation = "read-uncommitted" | "read-committed" | "repeatable-read" | "serializable";
+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);
+}
+export interface RoutineResultSet<Row = unknown> {
+  readonly rows: readonly Row[];
+}
+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;
+}
+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;
+}
+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";
+export declare class RoutineMappingError extends Error {
+  readonly code = "BRAID_CALL_MAP";
+  readonly location: RoutineMappingLocation;
+  constructor(message: string, location: RoutineMappingLocation, options?: {
+    readonly cause?: unknown;
+  });
+}
+export type BulkExecutionMode = "native-bulk" | "pipeline" | "prepared-loop" | "remote-batch";
+export interface BulkExecutionResult {
+  readonly inputCount: number;
+  readonly affectedRows?: number;
+  readonly executionMode: BulkExecutionMode;
+}
+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;
+  query<Row>(rendered: RenderedStatement, binding?: StatementBindingDescription, options?: ExecutionOptions): Promise<QueryExecutionResult<Row>>;
+  stream<Row>(rendered: RenderedStatement, binding?: StatementBindingDescription, options?: ExecutionOptions): AsyncIterable<Row>;
+  call(rendered: RenderedStatement, binding?: StatementBindingDescription, options?: ExecutionOptions): Promise<DriverRoutineResult>;
+  bulk?(bulk: RenderedBulk, binding: BulkBindingDescription, options?: ExecutionOptions): Promise<BulkExecutionResult>;
+  begin?(options?: TransactionOptions): Promise<void>;
+  commit?(): Promise<void>;
+  rollback?(): Promise<void>;
+  savepoint?(name: string): Promise<void>;
+  rollbackTo?(name: string): Promise<void>;
+  releaseSavepoint?(name: string): Promise<void>;
+}
+export interface ConnectionLease extends QueryExecutor {
+  release(options?: {
+    readonly discard?: boolean;
+  }): void | Promise<void>;
+}
+export interface ConnectionProvider {
+  readonly statementBinding: StatementBindingAdapter;
+  readonly environment?: DriverEnvironment;
+  acquire(): Promise<ConnectionLease>;
+}
+export interface QueryExecutionPlan {
+  readonly adapterId: string;
+  readonly dialectId: string;
+  readonly transport: ParameterTransportKind;
+  readonly reuse: StatementBindingDescription["reuse"];
+}
+export interface QueryReadyEvent {
+  readonly type: "query:ready";
+  readonly purpose?: "environment";
+  readonly operationId: string;
+  readonly batchId?: string;
+  readonly sql?: string;
+  readonly values: readonly unknown[];
+  readonly bindingMap?: readonly {
+    readonly placeholder: number;
+    readonly interpolation?: number;
+    readonly direction?: RoutineParameterDirection;
+    readonly outputName?: string;
+  }[];
+  readonly parameterHints?: readonly (ParameterTypeHint | undefined)[];
+  readonly execution: QueryExecutionPlan;
+  readonly literalizedSql: (options?: LiteralizeOptions) => LiteralizedSqlResult;
+  readonly declaredKind: QueryResultKind;
+  readonly fingerprint?: string;
+  readonly variantFingerprint?: string;
+  readonly preparedName?: string;
+  readonly transactionDepth: number;
+  readonly transactionScoped: boolean;
+}
+export interface QueryResultEvent {
+  readonly type: "query:result";
+  readonly purpose?: "environment";
+  readonly operationId: string;
+  readonly preparedName?: string;
+  readonly batchId?: string;
+  readonly durationMs: number;
+  readonly actualKind: "rows" | "command" | "call";
+  readonly rowCount?: number;
+  readonly resultSetCount?: number;
+  readonly outputKeys?: readonly string[];
+  readonly hasReturnValue?: boolean;
+  readonly command?: Readonly<Record<string, unknown>>;
+  readonly transactionDepth: number;
+  readonly transactionScoped: boolean;
+}
+export interface QueryMappedEvent {
+  readonly type: "query:mapped";
+  readonly purpose?: "environment";
+  readonly operationId: string;
+  readonly preparedName?: string;
+  readonly batchId?: string;
+  readonly durationMs: number;
+  readonly rowCount: number;
+  readonly queryMapped: boolean;
+  readonly executionMapped: boolean;
+  readonly transactionDepth: number;
+  readonly transactionScoped: boolean;
+}
+export interface BulkReadyEvent {
+  readonly type: "bulk:ready";
+  readonly operationId: string;
+  readonly itemCount: number;
+  readonly transactionDepth: number;
+  readonly transactionScoped: boolean;
+  readonly sql?: string;
+  readonly valuesAt: (index: number) => readonly unknown[];
+  readonly literalizedSql: (index: number, options?: LiteralizeOptions) => LiteralizedSqlResult;
+}
+export interface BulkResultEvent {
+  readonly type: "bulk:result";
+  readonly operationId: string;
+  readonly itemCount: number;
+  readonly affectedRows?: number;
+  readonly executionMode: BulkExecutionMode;
+  readonly durationMs: number;
+  readonly transactionDepth: number;
+  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";
+export interface QueryErrorEvent {
+  readonly type: "query:error";
+  readonly purpose?: "environment";
+  readonly operationId: string;
+  readonly preparedName?: string;
+  readonly batchId?: string;
+  readonly error: unknown;
+  readonly stage: QueryErrorStage;
+  readonly executionStarted: boolean;
+  readonly executionCompleted: boolean;
+  readonly durationMs?: number;
+  readonly transactionDepth: number;
+  readonly transactionScoped: boolean;
+}
+export interface StreamStartEvent {
+  readonly type: "stream:start";
+  readonly operationId: string;
+  readonly sql?: string;
+  readonly values: readonly unknown[];
+  readonly bindingMap?: readonly {
+    readonly placeholder: number;
+    readonly interpolation?: number;
+    readonly direction?: RoutineParameterDirection;
+    readonly outputName?: string;
+  }[];
+  readonly parameterHints?: readonly (ParameterTypeHint | undefined)[];
+  readonly execution: QueryExecutionPlan;
+  readonly literalizedSql: (options?: LiteralizeOptions) => LiteralizedSqlResult;
+  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>>;
+    };
+  };
+}
+/** 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 interface EnvironmentOptions {
+  readonly targets?: readonly EnvironmentSupportTarget[];
+  /** Re-probe the current lease instead of returning the cached observation. */
+  readonly refresh?: boolean;
+}
+export interface DatabaseOptions {
+  readonly observers?: readonly ExecutionObserver[];
+  readonly reuse?: RequestedReuse;
+}
+export type PreparableQuery = ExecutableQuery | CallQuery;
+export type PreparedArguments<Input, Options> = [Input] extends [never] ? [options?: Options] : [input: Input, options?: Options];
+export type PreparedQuery<Input, Q extends PreparableQuery> = {
+  readonly name: string;
+} & (Q extends CallQuery<infer Result> ? {
+  call(...args: PreparedArguments<Input, ExecutionOptions>): Promise<Result>;
+} : {
+  execute(...args: PreparedArguments<Input, ExecutionOptions>): Promise<ExecutionResultOf<Q>>;
+} & (Q extends RowQuery<infer Row> ? {
+  all(...args: PreparedArguments<Input, RowValidationOptions<Row>>): Promise<readonly Row[]>;
+  one(...args: PreparedArguments<Input, RowValidationOptions<Row>>): Promise<Row>;
+  maybeOne(...args: PreparedArguments<Input, RowValidationOptions<Row>>): Promise<Row | undefined>;
+  stream(...args: PreparedArguments<Input, StreamOptions<Row>>): AsyncIterable<Row>;
+} : {}));
+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;
+export interface Database {
+  environment(options?: EnvironmentOptions): Promise<DatabaseEnvironment>;
+  all<Row>(query: RowQuery<Row>, options?: RowValidationOptions<Row>): Promise<readonly Row[]>;
+  one<Row>(query: RowQuery<Row>, options?: RowValidationOptions<Row>): Promise<Row>;
+  maybeOne<Row>(query: RowQuery<Row>, options?: RowValidationOptions<Row>): Promise<Row | undefined>;
+  execute<Q extends ExecutableQuery>(query: Q, options?: ExecutionOptions): Promise<ExecutionResultOf<Q>>;
+  call<Result extends RoutineCallResult>(query: CallQuery<Result>, options?: ExecutionOptions): Promise<Result>;
+  batch<const Queries extends readonly ExecutableQuery[]>(queries: Queries, options?: ExecutionOptions): Promise<{ readonly [K in keyof Queries]: ExecutionResultOf<Queries[K]>; }>;
+  bulk<Input>(inputs: readonly Input[], factory: (input: Input, index: number) => CommandQuery, options?: ExecutionOptions): Promise<BulkResult>;
+  prepare<Factory extends () => PreparableQuery>(name: string, factory: Factory & (Parameters<Factory> extends [] ? unknown : never)): PreparedQuery<never, ReturnType<Factory>>;
+  prepare<Factory extends (input: never) => PreparableQuery>(name: string, factory: Factory & (Parameters<Factory> extends [unknown] ? unknown : never)): PreparedQuery<Parameters<Factory>[0], ReturnType<Factory>>;
+  stream<Row>(query: RowQuery<Row>, options?: StreamOptions<Row>): AsyncIterable<Row>;
+  session<T>(callback: (database: Database) => Promise<T>): Promise<T>;
+  tx<T>(callback: (database: Database) => Promise<T>): Promise<T>;
+  tx<T>(options: TransactionOptions, callback: (database: Database) => Promise<T>): Promise<T>;
+}
+export interface BulkResult {
+  readonly inputCount: number;
+  readonly affectedRows?: number;
+}
+export type QueryRow<Q> = Q extends Query<infer Row, QueryResultKind> ? Row : never;
+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>>;
+}
+export interface RowsTag {
+  <Input, Output>(schema: StandardSchemaV1$1<Input, Output>): SqlTagLike<"rows", Output>;
+  <Row = unknown>(strings: TemplateStringsArray, ...values: readonly unknown[]): RowQuery<Row>;
+}
+export interface SqlTag extends SqlTagLike<"unknown"> {
+  rows: RowsTag;
+  command: (strings: TemplateStringsArray, ...values: readonly unknown[]) => CommandQuery;
+  call: {
+    <Result extends RoutineCallResult = RoutineCallResult>(strings: TemplateStringsArray, ...values: readonly unknown[]): CallQuery<Result>;
+    <Contract extends RoutineContract>(contract: Contract): RoutineContractTag<Contract>;
+  };
+  bind<Input>(value: NoInfer<Input>, hint: ParameterTypeHint<Input>): BoundParameter<Input>;
+  out(name: string, hint?: ParameterTypeHint): RoutineParameter<null>;
+  inOut<Input>(name: string, value: NoInfer<Input>, hint?: ParameterTypeHint<Input>): RoutineParameter<Input>;
+  fragment: (strings: TemplateStringsArray, ...values: readonly unknown[]) => SqlFragment;
+  empty: SqlFragment;
+  ident: (identifier: string | readonly string[]) => SqlFragment;
+  raw: (text: string) => SqlFragment;
+  join: (items: readonly SqlFragment[], separator?: SqlFragment) => SqlFragment;
+  list: (values: readonly unknown[]) => SqlFragment;
+}
+export declare class SqlRenderError extends Error {
+  readonly code: string;
+  constructor(code: string, message: string);
+}
+//#endregion
+export type { StandardSchemaV1 };
+//# sourceMappingURL=index.d.ts.map