effect-qb 0.14.0 → 0.15.0

package/src/internal/renderer.ts

@@ -1,6 +1,5 @@
 import * as Query from "./query.js"
 import { type Projection, validateProjections } from "./projections.js"
-import { renderPostgresPlan } from "./postgres-renderer.js"
 
 /** Symbol used to attach rendered-query phantom row metadata. */
 export const TypeId: unique symbol = Symbol.for("effect-qb/Renderer")
@@ -41,12 +40,12 @@ export type RowOf<Value extends RenderedQuery<any, any>> = Value[typeof TypeId][
  */
 export interface Renderer<Dialect extends string = string> {
   readonly dialect: Dialect
-  render<PlanValue extends Query.QueryPlan<any, any, any, any, any, any, any, any, any, any>>(
+  render<PlanValue extends Query.Plan.Any>(
     plan: Query.DialectCompatiblePlan<PlanValue, Dialect>
   ): RenderedQuery<any, Dialect>
 }
 
-type CustomRender<Dialect extends string> = <PlanValue extends Query.QueryPlan<any, any, any, any, any, any, any, any, any, any>>(
+type CustomRender<Dialect extends string> = <PlanValue extends Query.Plan.Any>(
   plan: Query.DialectCompatiblePlan<PlanValue, Dialect>
 ) => {
   readonly sql: string
@@ -55,33 +54,23 @@ type CustomRender<Dialect extends string> = <PlanValue extends Query.QueryPlan<a
 }
 
 /**
- * Constructs a renderer from a dialect and optional implementation callback.
- *
- * When no callback is provided, the library supplies a built-in renderer for
- * `"postgres"` that consumes the query AST directly and produces SQL text plus
- * parameter values.
+ * Constructs a renderer from a dialect and implementation callback.
  */
-export function make(dialect: "postgres"): Renderer<"postgres">
 export function make<Dialect extends string>(
   dialect: Dialect,
   render: CustomRender<Dialect>
 ): Renderer<Dialect>
 export function make<Dialect extends string>(
   dialect: Dialect,
-  render?: CustomRender<Dialect>
+  render: CustomRender<Dialect>
 ): Renderer<Dialect> {
-  const implementation = render ?? ((dialect === "postgres"
-    ? renderPostgresPlan
-    : undefined) as CustomRender<Dialect> | undefined)
-
-  if (!implementation) {
-    throw new Error(`No built-in renderer for dialect: ${dialect}`)
+  if (typeof render !== "function") {
+    throw new Error(`Renderer.make requires an explicit render implementation for dialect: ${dialect}`)
   }
-
   return {
     dialect,
     render(plan) {
-      const rendered = implementation(plan)
+      const rendered = render(plan)
       const projections = rendered.projections ?? []
       validateProjections(projections)
       return {
@@ -97,6 +86,3 @@ export function make<Dialect extends string>(
     }
   } as Renderer<Dialect>
 }
-
-/** Built-in Postgres renderer backed by the current query AST. */
-export const postgres = make("postgres")

package/src/internal/row-set.d.ts

@@ -0,0 +1,53 @@
+import type { Pipeable } from "effect/Pipeable";
+import type { PredicateFormula } from "./predicate/formula.js";
+/** Symbol used to attach logical-plan metadata to runtime values. */
+export declare const TypeId: unique symbol;
+export type TypeId = typeof TypeId;
+/**
+ * Source availability mode within a query scope.
+ *
+ * `required` means the source is guaranteed to produce a row at this point in
+ * the plan. `optional` means the source may be absent, such as the nullable
+ * side of a left join.
+ */
+export type SourceMode = "required" | "optional";
+/** Source made available to a plan. */
+export interface Source<Name extends string = string, Mode extends SourceMode = SourceMode, PresentFormula extends PredicateFormula = PredicateFormula, PresenceWitness extends string = never> {
+    readonly name: Name;
+    readonly mode: Mode;
+    readonly baseName?: string;
+    readonly _presentFormula?: PresentFormula;
+    readonly _presenceWitnesses?: readonly PresenceWitness[];
+}
+export type AnySource = Source<string, SourceMode, PredicateFormula, string>;
+/**
+ * Canonical static metadata stored on a plan.
+ *
+ * `required` tracks sources that the selection references but which are not yet
+ * in scope. `available` tracks sources already in scope for subsequent query
+ * operations.
+ */
+export interface State<Columns, Required, Available extends Record<string, AnySource>, Dialect extends string> {
+    readonly selection: Columns;
+    readonly required: Required;
+    readonly available: Available;
+    readonly dialect: Dialect;
+}
+/**
+ * A composable logical row set.
+ *
+ * Tables implement this interface as already-complete plans. Future query
+ * builders such as `select()` and `from()` should produce and transform values
+ * with this same structure.
+ */
+export interface RowSet<Columns, Required = never, Available extends Record<string, AnySource> = {}, Dialect extends string = never> extends Pipeable {
+    readonly [TypeId]: State<Columns, Required, Available, Dialect>;
+}
+/** Convenience alias for any plan-like value. */
+export type Any = RowSet<any, any, Record<string, AnySource>, string>;
+/** Extracts a row set's columns shape. */
+export type ColumnsOf<Value extends Any> = Value[typeof TypeId]["selection"];
+/** Extracts a plan's selection shape. */
+export type SelectionOf<Value extends Any> = ColumnsOf<Value>;
+/** Extracts a plan's effective dialect. */
+export type DialectOf<Value extends Any> = Value[typeof TypeId]["dialect"];

package/src/internal/{plan.ts → row-set.ts}

@@ -1,5 +1,5 @@
 import type { Pipeable } from "effect/Pipeable"
-import type { PredicateFormula } from "./predicate-formula.js"
+import type { PredicateFormula } from "./predicate/formula.js"
 
 /** Symbol used to attach logical-plan metadata to runtime values. */
 export const TypeId: unique symbol = Symbol.for("effect-qb/Plan")
@@ -39,36 +39,38 @@ export type AnySource = Source<string, SourceMode, PredicateFormula, string>
  * operations.
  */
 export interface State<
-  Selection,
+  Columns,
   Required,
   Available extends Record<string, AnySource>,
   Dialect extends string
 > {
-  readonly selection: Selection
+  readonly selection: Columns
   readonly required: Required
   readonly available: Available
   readonly dialect: Dialect
 }
 
 /**
- * A composable logical query plan.
+ * A composable logical row set.
  *
  * Tables implement this interface as already-complete plans. Future query
  * builders such as `select()` and `from()` should produce and transform values
  * with this same structure.
  */
-export interface Plan<
-  Selection,
+export interface RowSet<
+  Columns,
   Required = never,
   Available extends Record<string, AnySource> = {},
   Dialect extends string = never
 > extends Pipeable {
-  readonly [TypeId]: State<Selection, Required, Available, Dialect>
+  readonly [TypeId]: State<Columns, Required, Available, Dialect>
 }
 
 /** Convenience alias for any plan-like value. */
-export type Any = Plan<any, any, Record<string, AnySource>, string>
+export type Any = RowSet<any, any, Record<string, AnySource>, string>
+/** Extracts a row set's columns shape. */
+export type ColumnsOf<Value extends Any> = Value[typeof TypeId]["selection"]
 /** Extracts a plan's selection shape. */
-export type SelectionOf<Value extends Any> = Value[typeof TypeId]["selection"]
+export type SelectionOf<Value extends Any> = ColumnsOf<Value>
 /** Extracts a plan's effective dialect. */
 export type DialectOf<Value extends Any> = Value[typeof TypeId]["dialect"]

package/src/internal/{runtime-normalize.ts → runtime/normalize.ts}

@@ -1,22 +1,5 @@
-import type * as Expression from "./expression.js"
-import { mysqlDatatypeKinds } from "../mysql/datatypes/spec.js"
-import { postgresDatatypeKinds } from "../postgres/datatypes/spec.js"
-import type { RuntimeTag } from "./datatypes/shape.js"
-
-const stripParameterizedKind = (kind: string): string => {
-  const openParen = kind.indexOf("(")
-  return openParen === -1 ? kind : kind.slice(0, openParen)
-}
-
-const stripArrayKind = (kind: string): string => {
-  let current = kind
-  while (current.endsWith("[]")) {
-    current = current.slice(0, -2)
-  }
-  return current
-}
-
-const baseKind = (kind: string): string => stripArrayKind(stripParameterizedKind(kind))
+import type * as Expression from "../scalar.js"
+import type { RuntimeTag } from "../datatypes/shape.js"
 
 const isRecord = (value: unknown): value is Record<string, unknown> =>
   typeof value === "object" && value !== null && !Array.isArray(value)
@@ -39,17 +22,9 @@ const formatLocalDateTime = (value: Date): string => {
 }
 
 const runtimeTagOfBaseDbType = (
-  dialect: string,
-  kind: string
+  dbType: Expression.DbType.Base<string, string>
 ): RuntimeTag | undefined => {
-  const normalizedKind = baseKind(kind)
-  if (dialect === "postgres") {
-    return postgresDatatypeKinds[normalizedKind as keyof typeof postgresDatatypeKinds]?.runtime
-  }
-  if (dialect === "mysql") {
-    return mysqlDatatypeKinds[normalizedKind as keyof typeof mysqlDatatypeKinds]?.runtime
-  }
-  return undefined
+  return dbType.runtime
 }
 
 const expectString = (value: unknown, label: string): string => {
@@ -225,7 +200,10 @@ const normalizeBytes = (value: unknown): Uint8Array => {
   if (value instanceof Uint8Array) {
     return new Uint8Array(value)
   }
-  if (typeof Buffer !== "undefined" && value instanceof Buffer) {
+  const BufferConstructor = (globalThis as {
+    readonly Buffer?: abstract new (...args: never[]) => Uint8Array
+  }).Buffer
+  if (BufferConstructor !== undefined && value instanceof BufferConstructor) {
     return new Uint8Array(value)
   }
   throw new Error("Expected a byte array value")
@@ -298,7 +276,7 @@ export const normalizeDbValue = (
   if ("variant" in dbType && (dbType.variant === "enum" || dbType.variant === "set")) {
     return expectString(value, "text")
   }
-  switch (runtimeTagOfBaseDbType(dbType.dialect, dbType.kind)) {
+  switch (runtimeTagOfBaseDbType(dbType)) {
     case "string":
       return expectString(value, "text")
     case "number":

package/src/internal/{runtime-schema.ts → runtime/schema.ts}

@@ -1,19 +1,19 @@
 import * as Schema from "effect/Schema"
 import * as SchemaAST from "effect/SchemaAST"
 
-import * as Expression from "./expression.js"
-import * as ExpressionAst from "./expression-ast.js"
-import * as Query from "./query.js"
-import * as JsonPath from "./json/path.js"
-import type { PredicateFormula } from "./predicate-formula.js"
+import * as Expression from "../scalar.js"
+import * as ExpressionAst from "../expression-ast.js"
+import * as Query from "../query.js"
+import * as JsonPath from "../json/path.js"
+import type { PredicateFormula } from "../predicate/formula.js"
 import {
   assumeFormulaFalse,
   assumeFormulaTrue,
   contradictsFormula,
   formulaOfExpression as formulaOfExpressionRuntime,
   impliesFormula
-} from "./predicate-runtime.js"
-import { flattenSelection } from "./projections.js"
+} from "../predicate/runtime.js"
+import { flattenSelection } from "../projections.js"
 import {
   BigIntStringSchema,
   DecimalStringSchema,
@@ -24,10 +24,8 @@ import {
   LocalTimeStringSchema,
   OffsetTimeStringSchema,
   YearStringSchema
-} from "./runtime-value.js"
-import { mysqlDatatypeKinds } from "../mysql/datatypes/spec.js"
-import { postgresDatatypeKinds } from "../postgres/datatypes/spec.js"
-import type { RuntimeTag } from "./datatypes/shape.js"
+} from "./value.js"
+import type { RuntimeTag } from "../datatypes/shape.js"
 
 export type RuntimeSchema = Schema.Schema<any, any, any>
 
@@ -37,21 +35,6 @@ type SchemaContext = {
 
 const schemaCache = new WeakMap<Expression.Any, RuntimeSchema | undefined>()
 
-const stripParameterizedKind = (kind: string): string => {
-  const openParen = kind.indexOf("(")
-  return openParen === -1 ? kind : kind.slice(0, openParen)
-}
-
-const stripArrayKind = (kind: string): string => {
-  let current = kind
-  while (current.endsWith("[]")) {
-    current = current.slice(0, -2)
-  }
-  return current
-}
-
-const baseKind = (kind: string): string => stripArrayKind(stripParameterizedKind(kind))
-
 const isRecord = (value: unknown): value is Record<string, unknown> =>
   typeof value === "object" && value !== null && !Array.isArray(value)
 
@@ -98,17 +81,9 @@ const runtimeSchemaForTag = (tag: RuntimeTag): RuntimeSchema | undefined => {
 }
 
 const runtimeTagOfBaseDbType = (
-  dialect: string,
-  kind: string
+  dbType: Expression.DbType.Base<string, string>
 ): RuntimeTag | undefined => {
-  const normalizedKind = baseKind(kind)
-  if (dialect === "postgres") {
-    return postgresDatatypeKinds[normalizedKind as keyof typeof postgresDatatypeKinds]?.runtime
-  }
-  if (dialect === "mysql") {
-    return mysqlDatatypeKinds[normalizedKind as keyof typeof mysqlDatatypeKinds]?.runtime
-  }
-  return undefined
+  return dbType.runtime
 }
 
 export const runtimeSchemaForDbType = (
@@ -132,7 +107,7 @@ export const runtimeSchemaForDbType = (
   if ("variant" in dbType && (dbType.variant === "enum" || dbType.variant === "set")) {
     return Schema.String
   }
-  const runtimeTag = runtimeTagOfBaseDbType(dbType.dialect, dbType.kind)
+  const runtimeTag = runtimeTagOfBaseDbType(dbType)
   return runtimeTag === undefined ? undefined : runtimeSchemaForTag(runtimeTag)
 }
 
@@ -257,7 +232,7 @@ const unionSchemas = (schemas: ReadonlyArray<RuntimeSchema | undefined>): Runtim
 }
 
 const firstSelectedExpression = (
-  plan: Query.QueryPlan<any, any, any, any, any, any, any, any, any, any>
+  plan: Query.Plan.Any
 ): Expression.Any | undefined => {
   const selection = Query.getAst(plan).select
   return flattenSelection(selection as Record<string, unknown>)[0]?.expression

package/src/internal/runtime/value.d.ts

@@ -0,0 +1,22 @@
+import type * as Brand from "effect/Brand";
+import * as Schema from "effect/Schema";
+import type { JsonPrimitive, JsonValue } from "../json/types.js";
+export type { JsonPrimitive, JsonValue } from "../json/types.js";
+export type LocalDateString = string & Brand.Brand<"LocalDateString">;
+export type LocalTimeString = string & Brand.Brand<"LocalTimeString">;
+export type OffsetTimeString = string & Brand.Brand<"OffsetTimeString">;
+export type LocalDateTimeString = string & Brand.Brand<"LocalDateTimeString">;
+export type InstantString = string & Brand.Brand<"InstantString">;
+export type YearString = string & Brand.Brand<"YearString">;
+export type BigIntString = string & Brand.Brand<"BigIntString">;
+export type DecimalString = string & Brand.Brand<"DecimalString">;
+export declare const LocalDateStringSchema: Schema.Schema<string & Brand.Brand<"LocalDateString">, string & Brand.Brand<"LocalDateString">, never>;
+export declare const LocalTimeStringSchema: Schema.Schema<string & Brand.Brand<"LocalTimeString">, string & Brand.Brand<"LocalTimeString">, never>;
+export declare const OffsetTimeStringSchema: Schema.Schema<string & Brand.Brand<"OffsetTimeString">, string & Brand.Brand<"OffsetTimeString">, never>;
+export declare const LocalDateTimeStringSchema: Schema.Schema<string & Brand.Brand<"LocalDateTimeString">, string & Brand.Brand<"LocalDateTimeString">, never>;
+export declare const InstantStringSchema: Schema.Schema<string & Brand.Brand<"InstantString">, string & Brand.Brand<"InstantString">, never>;
+export declare const YearStringSchema: Schema.Schema<string & Brand.Brand<"YearString">, string & Brand.Brand<"YearString">, never>;
+export declare const BigIntStringSchema: Schema.Schema<string & Brand.Brand<"BigIntString">, string & Brand.Brand<"BigIntString">, never>;
+export declare const DecimalStringSchema: Schema.Schema<string & Brand.Brand<"DecimalString">, string & Brand.Brand<"DecimalString">, never>;
+export declare const JsonValueSchema: Schema.Schema<JsonValue>;
+export declare const JsonPrimitiveSchema: Schema.Schema<JsonPrimitive>;

package/src/internal/{runtime-value.ts → runtime/value.ts}

@@ -1,9 +1,9 @@
 import type * as Brand from "effect/Brand"
 import * as Schema from "effect/Schema"
 
-import type { JsonPrimitive, JsonValue } from "./json/types.js"
+import type { JsonPrimitive, JsonValue } from "../json/types.js"
 
-export type { JsonPrimitive, JsonValue } from "./json/types.js"
+export type { JsonPrimitive, JsonValue } from "../json/types.js"
 
 export type LocalDateString = string & Brand.Brand<"LocalDateString">
 export type LocalTimeString = string & Brand.Brand<"LocalTimeString">

package/src/internal/scalar.d.ts

@@ -0,0 +1,107 @@
+import type { Pipeable } from "effect/Pipeable";
+import type * as Schema from "effect/Schema";
+import type { RuntimeOfDbType as RuntimeOfDbTypeLookup } from "./datatypes/lookup.js";
+import type { DatatypeTraits, RuntimeTag } from "./datatypes/shape.js";
+export type { BigIntString, DecimalString, InstantString, JsonPrimitive, JsonValue, LocalDateString, LocalDateTimeString, LocalTimeString, OffsetTimeString, YearString } from "./runtime/value.js";
+/** Symbol used to attach expression metadata to runtime values. */
+export declare const TypeId: unique symbol;
+export type TypeId = typeof TypeId;
+/** Scope-local binding identifier used for dependency tracking. */
+export type BindingId = string;
+/**
+ * Three-state nullability lattice.
+ *
+ * `"never"` means non-null, `"maybe"` means nullable, and `"always"` means the
+ * expression is known to be `null`.
+ */
+export type Nullability = "never" | "maybe" | "always";
+/**
+ * High-level classification of an expression.
+ *
+ * - `scalar`: regular per-row expression
+ * - `aggregate`: grouped expression such as `count(*)`
+ * - `window`: windowed expression such as `row_number() over (...)`
+ */
+export type ScalarKind = "scalar" | "aggregate" | "window";
+/** Database-type descriptors carried alongside decoded runtime types. */
+export declare namespace DbType {
+    /** Base SQL type descriptor. */
+    interface Base<Dialect extends string, Kind extends string> {
+        readonly dialect: Dialect;
+        readonly kind: Kind;
+        readonly family?: string;
+        readonly runtime?: RuntimeTag;
+        readonly compareGroup?: string;
+        readonly castTargets?: readonly string[];
+        readonly traits?: DatatypeTraits;
+    }
+    /** JSON-like database type. */
+    interface Json<Dialect extends string = string, SchemaName extends string = "json"> extends Base<Dialect, SchemaName> {
+        readonly variant: SchemaName extends "jsonb" ? "jsonb" : "json";
+    }
+    /** Array database type. */
+    interface Array<Dialect extends string = string, Element extends Any = any, Kind extends string = string> extends Base<Dialect, Kind> {
+        readonly element: Element;
+    }
+    /** Range database type. */
+    interface Range<Dialect extends string = string, Subtype extends Any = any, Kind extends string = string> extends Base<Dialect, Kind> {
+        readonly subtype: Subtype;
+    }
+    /** Multirange database type. */
+    interface Multirange<Dialect extends string = string, Subtype extends Any = any, Kind extends string = string> extends Base<Dialect, Kind> {
+        readonly subtype: Subtype;
+    }
+    /** Composite/record database type. */
+    interface Composite<Dialect extends string = string, Fields extends Record<string, Any> = Record<string, any>, Kind extends string = string> extends Base<Dialect, Kind> {
+        readonly fields: Fields;
+    }
+    /** Named domain database type. */
+    interface Domain<Dialect extends string = string, BaseType extends Any = any, Kind extends string = string> extends Base<Dialect, Kind> {
+        readonly base: BaseType;
+    }
+    /** Enumeration database type. */
+    interface Enum<Dialect extends string = string, Kind extends string = string> extends Base<Dialect, Kind> {
+        readonly variant: "enum";
+    }
+    /** Set database type. */
+    interface Set<Dialect extends string = string, Kind extends string = string> extends Base<Dialect, Kind> {
+        readonly variant: "set";
+    }
+    type Any = Json | Base<string, string> | Array<string, any, string> | Range<string, any, string> | Multirange<string, any, string> | Composite<string, Record<string, any>, string> | Domain<string, any, string> | Enum<string, string> | Set<string, string>;
+}
+/** Canonical static metadata stored on an expression. */
+export interface State<Runtime, Db extends DbType.Any, Nullable extends Nullability, Dialect extends string, Kind extends ScalarKind, Deps extends BindingId = never> {
+    readonly runtime: Runtime;
+    readonly dbType: Db;
+    readonly runtimeSchema?: Schema.Schema.Any;
+    readonly nullability: Nullable;
+    readonly dialect: Dialect;
+    readonly kind: Kind;
+    readonly dependencies: Record<string, true>;
+}
+/**
+ * A typed scalar SQL expression.
+ *
+ * `Runtime` is the decoded TypeScript type while `Db` captures the SQL-level
+ * type identity. Both are needed: multiple SQL types may decode to the same
+ * runtime type but still have different comparison/cast semantics.
+ */
+export interface Scalar<Runtime, Db extends DbType.Any, Nullable extends Nullability = "never", Dialect extends string = Db["dialect"], Kind extends ScalarKind = "scalar", Deps extends BindingId = never, GroupKey extends string = string> extends Pipeable {
+    readonly [TypeId]: State<Runtime, Db, Nullable, Dialect, Kind, Deps>;
+}
+/** Convenience alias for any expression-like value. */
+export type Any = Scalar<any, DbType.Any, Nullability, string, ScalarKind, BindingId, string>;
+/** Extracts an expression's decoded runtime type. */
+export type RuntimeOf<Value extends Any> = Value[typeof TypeId]["runtime"];
+/** Extracts an expression's database-type descriptor. */
+export type DbTypeOf<Value extends Any> = Value[typeof TypeId]["dbType"];
+/** Extracts an expression's nullability state. */
+export type NullabilityOf<Value extends Any> = Value[typeof TypeId]["nullability"];
+/** Extracts an expression's kind. */
+export type KindOf<Value extends Any> = Value[typeof TypeId]["kind"];
+/** Extracts an expression's source dependency union. */
+export type DependenciesOf<Value extends Any> = Value extends Scalar<any, any, any, any, any, infer Deps> ? Deps : never;
+/** Extracts an expression's grouping identity. */
+export type GroupKeyOf<Value extends Any> = Value extends Scalar<any, any, any, any, any, any, infer GroupKey> ? GroupKey : never;
+/** Maps a database type descriptor back to its decoded runtime type. */
+export type RuntimeOfDbType<Db extends DbType.Any> = RuntimeOfDbTypeLookup<Db>;

package/src/internal/scalar.ts

@@ -0,0 +1,191 @@
+import type { Pipeable } from "effect/Pipeable"
+import type * as Schema from "effect/Schema"
+import type { RuntimeOfDbType as RuntimeOfDbTypeLookup } from "./datatypes/lookup.js"
+import type { DatatypeTraits, RuntimeTag } from "./datatypes/shape.js"
+
+export type {
+  BigIntString,
+  DecimalString,
+  InstantString,
+  JsonPrimitive,
+  JsonValue,
+  LocalDateString,
+  LocalDateTimeString,
+  LocalTimeString,
+  OffsetTimeString,
+  YearString
+} from "./runtime/value.js"
+
+/** Symbol used to attach expression metadata to runtime values. */
+export const TypeId: unique symbol = Symbol.for("effect-qb/Expression")
+
+export type TypeId = typeof TypeId
+
+/** Scope-local binding identifier used for dependency tracking. */
+export type BindingId = string
+/**
+ * Three-state nullability lattice.
+ *
+ * `"never"` means non-null, `"maybe"` means nullable, and `"always"` means the
+ * expression is known to be `null`.
+ */
+export type Nullability = "never" | "maybe" | "always"
+
+/**
+ * High-level classification of an expression.
+ *
+ * - `scalar`: regular per-row expression
+ * - `aggregate`: grouped expression such as `count(*)`
+ * - `window`: windowed expression such as `row_number() over (...)`
+ */
+export type ScalarKind = "scalar" | "aggregate" | "window"
+
+/** Database-type descriptors carried alongside decoded runtime types. */
+export declare namespace DbType {
+  /** Base SQL type descriptor. */
+  export interface Base<Dialect extends string, Kind extends string> {
+    readonly dialect: Dialect
+    readonly kind: Kind
+    readonly family?: string
+    readonly runtime?: RuntimeTag
+    readonly compareGroup?: string
+    readonly castTargets?: readonly string[]
+    readonly traits?: DatatypeTraits
+  }
+
+  /** JSON-like database type. */
+  export interface Json<
+    Dialect extends string = string,
+    SchemaName extends string = "json"
+  > extends Base<Dialect, SchemaName>
+  {
+    readonly variant: SchemaName extends "jsonb" ? "jsonb" : "json"
+  }
+
+  /** Array database type. */
+  export interface Array<
+    Dialect extends string = string,
+    Element extends Any = any,
+    Kind extends string = string
+  > extends Base<Dialect, Kind> {
+    readonly element: Element
+  }
+
+  /** Range database type. */
+  export interface Range<
+    Dialect extends string = string,
+    Subtype extends Any = any,
+    Kind extends string = string
+  > extends Base<Dialect, Kind> {
+    readonly subtype: Subtype
+  }
+
+  /** Multirange database type. */
+  export interface Multirange<
+    Dialect extends string = string,
+    Subtype extends Any = any,
+    Kind extends string = string
+  > extends Base<Dialect, Kind> {
+    readonly subtype: Subtype
+  }
+
+  /** Composite/record database type. */
+  export interface Composite<
+    Dialect extends string = string,
+    Fields extends Record<string, Any> = Record<string, any>,
+    Kind extends string = string
+  > extends Base<Dialect, Kind> {
+    readonly fields: Fields
+  }
+
+  /** Named domain database type. */
+  export interface Domain<
+    Dialect extends string = string,
+    BaseType extends Any = any,
+    Kind extends string = string
+  > extends Base<Dialect, Kind> {
+    readonly base: BaseType
+  }
+
+  /** Enumeration database type. */
+  export interface Enum<
+    Dialect extends string = string,
+    Kind extends string = string
+  > extends Base<Dialect, Kind> {
+    readonly variant: "enum"
+  }
+
+  /** Set database type. */
+  export interface Set<
+    Dialect extends string = string,
+    Kind extends string = string
+  > extends Base<Dialect, Kind> {
+    readonly variant: "set"
+  }
+
+  export type Any =
+    | Json
+    | Base<string, string>
+    | Array<string, any, string>
+    | Range<string, any, string>
+    | Multirange<string, any, string>
+    | Composite<string, Record<string, any>, string>
+    | Domain<string, any, string>
+    | Enum<string, string>
+    | Set<string, string>
+  }
+
+/** Canonical static metadata stored on an expression. */
+export interface State<
+  Runtime,
+  Db extends DbType.Any,
+  Nullable extends Nullability,
+  Dialect extends string,
+  Kind extends ScalarKind,
+  Deps extends BindingId = never
+> {
+  readonly runtime: Runtime
+  readonly dbType: Db
+  readonly runtimeSchema?: Schema.Schema.Any
+  readonly nullability: Nullable
+  readonly dialect: Dialect
+  readonly kind: Kind
+  readonly dependencies: Record<string, true>
+}
+
+/**
+ * A typed scalar SQL expression.
+ *
+ * `Runtime` is the decoded TypeScript type while `Db` captures the SQL-level
+ * type identity. Both are needed: multiple SQL types may decode to the same
+ * runtime type but still have different comparison/cast semantics.
+ */
+export interface Scalar<
+  Runtime,
+  Db extends DbType.Any,
+  Nullable extends Nullability = "never",
+  Dialect extends string = Db["dialect"],
+  Kind extends ScalarKind = "scalar",
+  Deps extends BindingId = never,
+  GroupKey extends string = string
+> extends Pipeable {
+  readonly [TypeId]: State<Runtime, Db, Nullable, Dialect, Kind, Deps>
+}
+
+/** Convenience alias for any expression-like value. */
+export type Any = Scalar<any, DbType.Any, Nullability, string, ScalarKind, BindingId, string>
+/** Extracts an expression's decoded runtime type. */
+export type RuntimeOf<Value extends Any> = Value[typeof TypeId]["runtime"]
+/** Extracts an expression's database-type descriptor. */
+export type DbTypeOf<Value extends Any> = Value[typeof TypeId]["dbType"]
+/** Extracts an expression's nullability state. */
+export type NullabilityOf<Value extends Any> = Value[typeof TypeId]["nullability"]
+/** Extracts an expression's kind. */
+export type KindOf<Value extends Any> = Value[typeof TypeId]["kind"]
+/** Extracts an expression's source dependency union. */
+export type DependenciesOf<Value extends Any> = Value extends Scalar<any, any, any, any, any, infer Deps> ? Deps : never
+/** Extracts an expression's grouping identity. */
+export type GroupKeyOf<Value extends Any> = Value extends Scalar<any, any, any, any, any, any, infer GroupKey> ? GroupKey : never
+
+/** Maps a database type descriptor back to its decoded runtime type. */
+export type RuntimeOfDbType<Db extends DbType.Any> = RuntimeOfDbTypeLookup<Db>