@biref/scanner 0.0.1

package/dist/index.js

@@ -0,0 +1,2248 @@
+// src/adapters/postgres/pgEnums.ts
+var PgTypeCategory = {
+  Array: "A"};
+var PgTypeKind = {
+  Enum: "e"};
+var PgConstraintKind = {
+  Check: "c",
+  Unique: "u",
+  Exclusion: "x"
+};
+var PgReferentialAction = {
+  NoAction: "a",
+  Restrict: "r",
+  Cascade: "c",
+  SetNull: "n",
+  SetDefault: "d"
+};
+var PgIndexMethod = {
+  BTree: "btree",
+  Hash: "hash",
+  Gin: "gin",
+  Gist: "gist",
+  Brin: "brin",
+  SpGist: "spgist"
+};
+
+// src/adapters/postgres/mapping/ConstraintMapper.ts
+var ConstraintMapper = class _ConstraintMapper {
+  static toConstraint(raw) {
+    return {
+      name: raw.name,
+      kind: _ConstraintMapper.toKind(raw.kind_code),
+      fields: raw.columns,
+      expression: raw.definition
+    };
+  }
+  static toKind(code) {
+    switch (code) {
+      case PgConstraintKind.Check: {
+        return "check";
+      }
+      case PgConstraintKind.Unique: {
+        return "unique";
+      }
+      case PgConstraintKind.Exclusion: {
+        return "exclusion";
+      }
+      default: {
+        return "custom";
+      }
+    }
+  }
+};
+
+// src/adapters/postgres/mapping/FieldMapper.ts
+var FieldMapper = class _FieldMapper {
+  static toField(col, isIdentifier) {
+    return {
+      name: col.name,
+      type: _FieldMapper.toType(col),
+      nullable: col.nullable,
+      isIdentifier,
+      defaultValue: col.default_value,
+      description: col.description
+    };
+  }
+  static toType(col) {
+    if (col.type_category === PgTypeCategory.Array) {
+      return {
+        category: "array",
+        nativeType: col.native_type,
+        elementType: _FieldMapper.toElementType(col)
+      };
+    }
+    if (col.type_kind === PgTypeKind.Enum) {
+      return {
+        category: "enum",
+        nativeType: col.native_type,
+        enumValues: col.enum_values ?? []
+      };
+    }
+    return {
+      category: _FieldMapper.categorize(col.udt_name),
+      nativeType: col.native_type
+    };
+  }
+  static toElementType(col) {
+    const elementUdt = col.element_udt_name ?? (col.udt_name.startsWith("_") ? col.udt_name.slice(1) : col.udt_name);
+    if (col.element_type_kind === PgTypeKind.Enum) {
+      return {
+        category: "enum",
+        nativeType: elementUdt,
+        enumValues: col.element_enum_values ?? []
+      };
+    }
+    return {
+      category: _FieldMapper.categorize(elementUdt),
+      nativeType: elementUdt
+    };
+  }
+  static categorize(udt) {
+    switch (udt.toLowerCase()) {
+      case "varchar":
+      case "bpchar":
+      case "char":
+      case "text":
+      case "name":
+      case "citext": {
+        return "string";
+      }
+      case "int2":
+      case "int4":
+      case "int8":
+      case "smallint":
+      case "integer":
+      case "bigint": {
+        return "integer";
+      }
+      case "numeric":
+      case "decimal":
+      case "float4":
+      case "float8":
+      case "real":
+      case "money": {
+        return "decimal";
+      }
+      case "bool":
+      case "boolean": {
+        return "boolean";
+      }
+      case "date": {
+        return "date";
+      }
+      case "timestamp":
+      case "timestamptz": {
+        return "timestamp";
+      }
+      case "time":
+      case "timetz": {
+        return "time";
+      }
+      case "json":
+      case "jsonb": {
+        return "json";
+      }
+      case "uuid": {
+        return "uuid";
+      }
+      case "bytea": {
+        return "binary";
+      }
+      default: {
+        return "unknown";
+      }
+    }
+  }
+};
+
+// src/adapters/postgres/mapping/IndexMapper.ts
+var IndexMapper = class _IndexMapper {
+  static toIndex(raw) {
+    return {
+      name: raw.name,
+      fields: raw.columns,
+      unique: raw.unique,
+      kind: _IndexMapper.toKind(raw.method),
+      partial: raw.partial,
+      definition: raw.definition
+    };
+  }
+  static toKind(method) {
+    switch (method.toLowerCase()) {
+      case PgIndexMethod.BTree: {
+        return "btree";
+      }
+      case PgIndexMethod.Hash: {
+        return "hash";
+      }
+      case PgIndexMethod.Gin: {
+        return "gin";
+      }
+      case PgIndexMethod.Gist: {
+        return "gist";
+      }
+      case PgIndexMethod.Brin: {
+        return "brin";
+      }
+      case PgIndexMethod.SpGist: {
+        return "spgist";
+      }
+      default: {
+        return "unknown";
+      }
+    }
+  }
+};
+
+// src/adapters/postgres/mapping/ReferenceMapper.ts
+var ReferenceMapper = class _ReferenceMapper {
+  static toReference(fk) {
+    return {
+      name: fk.name,
+      fromEntity: { namespace: fk.from_namespace, name: fk.from_table },
+      fromFields: fk.from_columns,
+      toEntity: { namespace: fk.to_namespace, name: fk.to_table },
+      toFields: fk.to_columns,
+      confidence: 1,
+      onUpdate: _ReferenceMapper.toAction(fk.update_action_code),
+      onDelete: _ReferenceMapper.toAction(fk.delete_action_code)
+    };
+  }
+  static toAction(code) {
+    switch (code) {
+      case PgReferentialAction.NoAction: {
+        return "no-action";
+      }
+      case PgReferentialAction.Restrict: {
+        return "restrict";
+      }
+      case PgReferentialAction.Cascade: {
+        return "cascade";
+      }
+      case PgReferentialAction.SetNull: {
+        return "set-null";
+      }
+      case PgReferentialAction.SetDefault: {
+        return "set-default";
+      }
+      default: {
+        return "no-action";
+      }
+    }
+  }
+};
+
+// src/adapters/postgres/mapping/EntityAssembler.ts
+var EntityAssembler = class _EntityAssembler {
+  static assemble(inputs) {
+    const tableKeys = new Set(
+      inputs.tables.map((t) => _EntityAssembler.qualified(t.namespace, t.name))
+    );
+    const pkByEntity = _EntityAssembler.indexPrimaryKeys(inputs.primaryKeys);
+    const colsByEntity = _EntityAssembler.indexColumns(inputs.columns);
+    const relsByEntity = _EntityAssembler.buildRelationships(
+      inputs.foreignKeys,
+      tableKeys
+    );
+    const indexesByEntity = _EntityAssembler.buildIndexes(
+      inputs.indexes,
+      tableKeys
+    );
+    const constraintsByEntity = _EntityAssembler.buildConstraints(
+      inputs.constraints,
+      tableKeys
+    );
+    return inputs.tables.map((table) => {
+      const key = _EntityAssembler.qualified(table.namespace, table.name);
+      const pkColumns = pkByEntity.get(key) ?? [];
+      const pkSet = new Set(pkColumns);
+      const rawCols = colsByEntity.get(key) ?? [];
+      const fields = rawCols.map(
+        (col) => FieldMapper.toField(col, pkSet.has(col.name))
+      );
+      return {
+        namespace: table.namespace,
+        name: table.name,
+        fields,
+        identifier: pkColumns,
+        relationships: relsByEntity.get(key) ?? [],
+        constraints: constraintsByEntity.get(key) ?? [],
+        indexes: indexesByEntity.get(key) ?? [],
+        description: table.description
+      };
+    });
+  }
+  static indexPrimaryKeys(primaryKeys) {
+    const map = /* @__PURE__ */ new Map();
+    for (const pk of primaryKeys) {
+      map.set(
+        _EntityAssembler.qualified(pk.namespace, pk.table_name),
+        pk.columns
+      );
+    }
+    return map;
+  }
+  static indexColumns(columns) {
+    const map = /* @__PURE__ */ new Map();
+    for (const col of columns) {
+      const key = _EntityAssembler.qualified(col.namespace, col.table_name);
+      const list = map.get(key);
+      if (list) {
+        list.push(col);
+      } else {
+        map.set(key, [col]);
+      }
+    }
+    return map;
+  }
+  static buildRelationships(foreignKeys, tableKeys) {
+    const map = /* @__PURE__ */ new Map();
+    for (const fk of foreignKeys) {
+      const reference = ReferenceMapper.toReference(fk);
+      const fromKey = _EntityAssembler.qualified(
+        fk.from_namespace,
+        fk.from_table
+      );
+      const toKey = _EntityAssembler.qualified(fk.to_namespace, fk.to_table);
+      if (tableKeys.has(fromKey)) {
+        _EntityAssembler.push(map, fromKey, {
+          direction: "outbound",
+          reference
+        });
+      }
+      if (tableKeys.has(toKey)) {
+        _EntityAssembler.push(map, toKey, {
+          direction: "inbound",
+          reference
+        });
+      }
+    }
+    return map;
+  }
+  static buildIndexes(indexes, tableKeys) {
+    const map = /* @__PURE__ */ new Map();
+    for (const idx of indexes) {
+      const key = _EntityAssembler.qualified(idx.namespace, idx.table_name);
+      if (!tableKeys.has(key)) {
+        continue;
+      }
+      _EntityAssembler.push(map, key, IndexMapper.toIndex(idx));
+    }
+    return map;
+  }
+  static buildConstraints(constraints, tableKeys) {
+    const map = /* @__PURE__ */ new Map();
+    for (const cn of constraints) {
+      const key = _EntityAssembler.qualified(cn.namespace, cn.table_name);
+      if (!tableKeys.has(key)) {
+        continue;
+      }
+      _EntityAssembler.push(map, key, ConstraintMapper.toConstraint(cn));
+    }
+    return map;
+  }
+  static push(map, key, value) {
+    const list = map.get(key);
+    if (list) {
+      list.push(value);
+    } else {
+      map.set(key, [value]);
+    }
+  }
+  static qualified(namespace, name) {
+    return `${namespace}.${name}`;
+  }
+};
+
+// src/adapters/postgres/PostgresMeta.ts
+var POSTGRES_ADAPTER_NAME = "postgres";
+var POSTGRES_URL_SCHEMES = [
+  "postgres",
+  "postgresql"
+];
+
+// src/adapters/postgres/queries/ColumnsQuery.ts
+var ColumnsQuery = class _ColumnsQuery {
+  static SQL = `
+SELECT
+  n.nspname AS namespace,
+  c.relname AS table_name,
+  a.attname AS name,
+  format_type(a.atttypid, a.atttypmod) AS native_type,
+  t.typname AS udt_name,
+  t.typcategory AS type_category,
+  t.typtype AS type_kind,
+  NOT a.attnotnull AS nullable,
+  pg_get_expr(d.adbin, d.adrelid) AS default_value,
+  col_description(c.oid, a.attnum) AS description,
+  CASE
+    WHEN t.typtype = 'e' THEN (
+      SELECT array_agg(enumlabel ORDER BY enumsortorder)::text[]
+      FROM pg_enum
+      WHERE enumtypid = a.atttypid
+    )
+    ELSE NULL
+  END AS enum_values,
+  et.typname AS element_udt_name,
+  et.typcategory AS element_type_category,
+  et.typtype AS element_type_kind,
+  CASE
+    WHEN et.typtype = 'e' THEN (
+      SELECT array_agg(enumlabel ORDER BY enumsortorder)::text[]
+      FROM pg_enum
+      WHERE enumtypid = et.oid
+    )
+    ELSE NULL
+  END AS element_enum_values
+FROM pg_attribute a
+JOIN pg_class c ON c.oid = a.attrelid
+JOIN pg_namespace n ON n.oid = c.relnamespace
+JOIN pg_type t ON t.oid = a.atttypid
+LEFT JOIN pg_type et ON et.oid = t.typelem AND t.typcategory = 'A'
+LEFT JOIN pg_attrdef d ON d.adrelid = c.oid AND d.adnum = a.attnum
+WHERE c.relkind IN ('r', 'p')
+  AND a.attnum > 0
+  AND NOT a.attisdropped
+  AND n.nspname = ANY($1)
+ORDER BY n.nspname, c.relname, a.attnum
+`;
+  static async fetch(client, namespaces) {
+    const result = await client.query(_ColumnsQuery.SQL, [
+      namespaces
+    ]);
+    return result.rows;
+  }
+};
+
+// src/adapters/postgres/queries/ConstraintsQuery.ts
+var ConstraintsQuery = class _ConstraintsQuery {
+  static SQL = `
+SELECT
+  n.nspname AS namespace,
+  cls.relname AS table_name,
+  c.conname AS name,
+  c.contype AS kind_code,
+  pg_get_constraintdef(c.oid) AS definition,
+  CASE
+    WHEN array_length(c.conkey, 1) > 0 THEN
+      (SELECT array_agg(att.attname ORDER BY u.ord)::text[]
+       FROM unnest(c.conkey) WITH ORDINALITY AS u(attnum, ord)
+       JOIN pg_attribute att
+         ON att.attrelid = c.conrelid AND att.attnum = u.attnum)
+    ELSE ARRAY[]::text[]
+  END AS columns
+FROM pg_constraint c
+JOIN pg_class cls ON cls.oid = c.conrelid
+JOIN pg_namespace n ON n.oid = cls.relnamespace
+WHERE c.contype IN ('c', 'u', 'x')
+  AND n.nspname = ANY($1)
+ORDER BY n.nspname, cls.relname, c.conname
+`;
+  static async fetch(client, namespaces) {
+    const result = await client.query(_ConstraintsQuery.SQL, [
+      namespaces
+    ]);
+    return result.rows;
+  }
+};
+
+// src/adapters/postgres/queries/ForeignKeysQuery.ts
+var ForeignKeysQuery = class _ForeignKeysQuery {
+  static SQL = `
+SELECT
+  c.conname AS name,
+  fn.nspname AS from_namespace,
+  fc.relname AS from_table,
+  (SELECT array_agg(att.attname ORDER BY u.ord)::text[]
+   FROM unnest(c.conkey) WITH ORDINALITY AS u(attnum, ord)
+   JOIN pg_attribute att
+     ON att.attrelid = c.conrelid AND att.attnum = u.attnum
+  ) AS from_columns,
+  tn.nspname AS to_namespace,
+  tc.relname AS to_table,
+  (SELECT array_agg(att.attname ORDER BY u.ord)::text[]
+   FROM unnest(c.confkey) WITH ORDINALITY AS u(attnum, ord)
+   JOIN pg_attribute att
+     ON att.attrelid = c.confrelid AND att.attnum = u.attnum
+  ) AS to_columns,
+  c.confupdtype AS update_action_code,
+  c.confdeltype AS delete_action_code
+FROM pg_constraint c
+JOIN pg_class fc ON fc.oid = c.conrelid
+JOIN pg_namespace fn ON fn.oid = fc.relnamespace
+JOIN pg_class tc ON tc.oid = c.confrelid
+JOIN pg_namespace tn ON tn.oid = tc.relnamespace
+WHERE c.contype = 'f'
+  AND fn.nspname = ANY($1)
+`;
+  static async fetch(client, namespaces) {
+    const result = await client.query(_ForeignKeysQuery.SQL, [
+      namespaces
+    ]);
+    return result.rows;
+  }
+};
+
+// src/adapters/postgres/queries/IndexesQuery.ts
+var IndexesQuery = class _IndexesQuery {
+  static SQL = `
+SELECT
+  n.nspname AS namespace,
+  t.relname AS table_name,
+  i.relname AS name,
+  am.amname AS method,
+  ix.indisunique AS unique,
+  (ix.indpred IS NOT NULL) AS partial,
+  pg_get_indexdef(ix.indexrelid) AS definition,
+  ARRAY(
+    SELECT a.attname
+    FROM unnest(ix.indkey::int[]) WITH ORDINALITY AS k(attnum, ord)
+    JOIN pg_attribute a
+      ON a.attrelid = t.oid AND a.attnum = k.attnum
+    ORDER BY k.ord
+  )::text[] AS columns
+FROM pg_index ix
+JOIN pg_class i ON i.oid = ix.indexrelid
+JOIN pg_class t ON t.oid = ix.indrelid
+JOIN pg_namespace n ON n.oid = t.relnamespace
+JOIN pg_am am ON am.oid = i.relam
+WHERE NOT ix.indisprimary
+  AND n.nspname = ANY($1)
+ORDER BY n.nspname, t.relname, i.relname
+`;
+  static async fetch(client, namespaces) {
+    const result = await client.query(_IndexesQuery.SQL, [namespaces]);
+    return result.rows;
+  }
+};
+
+// src/adapters/postgres/queries/PrimaryKeysQuery.ts
+var PrimaryKeysQuery = class _PrimaryKeysQuery {
+  static SQL = `
+SELECT
+  n.nspname AS namespace,
+  cls.relname AS table_name,
+  (SELECT array_agg(att.attname ORDER BY u.ord)::text[]
+   FROM unnest(c.conkey) WITH ORDINALITY AS u(attnum, ord)
+   JOIN pg_attribute att
+     ON att.attrelid = c.conrelid AND att.attnum = u.attnum
+  ) AS columns
+FROM pg_constraint c
+JOIN pg_class cls ON cls.oid = c.conrelid
+JOIN pg_namespace n ON n.oid = cls.relnamespace
+WHERE c.contype = 'p'
+  AND n.nspname = ANY($1)
+`;
+  static async fetch(client, namespaces) {
+    const result = await client.query(_PrimaryKeysQuery.SQL, [
+      namespaces
+    ]);
+    return result.rows;
+  }
+};
+
+// src/adapters/postgres/queries/TablesQuery.ts
+var TablesQuery = class _TablesQuery {
+  static SQL = `
+SELECT
+  n.nspname AS namespace,
+  c.relname AS name,
+  obj_description(c.oid, 'pg_class') AS description
+FROM pg_class c
+JOIN pg_namespace n ON n.oid = c.relnamespace
+WHERE c.relkind IN ('r', 'p')
+  AND n.nspname = ANY($1)
+ORDER BY n.nspname, c.relname
+`;
+  static async fetch(client, namespaces) {
+    const result = await client.query(_TablesQuery.SQL, [namespaces]);
+    return result.rows;
+  }
+};
+
+// src/domain/model/DataModel.ts
+var DataModel = class _DataModel {
+  constructor(kind, entities) {
+    this.kind = kind;
+    this.entities = entities;
+    this.index = new Map(
+      entities.map((e) => [_DataModel.qualifiedName(e.namespace, e.name), e])
+    );
+  }
+  kind;
+  entities;
+  index;
+  /**
+   * Build the lookup key for an entity. Exposed as a static helper so
+   * consumers can compute keys consistently when building their own
+   * indexes on top of a `DataModel`.
+   */
+  static qualifiedName(namespace, name) {
+    return `${namespace}.${name}`;
+  }
+  getEntity(namespace, name) {
+    return this.index.get(_DataModel.qualifiedName(namespace, name));
+  }
+  hasEntity(namespace, name) {
+    return this.index.has(_DataModel.qualifiedName(namespace, name));
+  }
+  /**
+   * All relationships an entity participates in, in both directions.
+   * Returns an empty array if the entity is unknown.
+   */
+  relationshipsOf(namespace, name) {
+    return this.getEntity(namespace, name)?.relationships ?? [];
+  }
+  /**
+   * Outbound relationships: this entity holds the reference.
+   * In a relational store these correspond to FOREIGN KEY constraints
+   * declared by the entity itself.
+   */
+  outboundRelationshipsOf(namespace, name) {
+    return this.relationshipsOf(namespace, name).filter(
+      (r) => r.direction === "outbound"
+    );
+  }
+  /**
+   * Inbound relationships: other entities hold references pointing here.
+   *
+   * This is the differentiating feature of the SDK. Most introspection
+   * tools only surface outbound relationships, requiring consumers to
+   * know which other entities reference theirs ahead of time.
+   */
+  inboundRelationshipsOf(namespace, name) {
+    return this.relationshipsOf(namespace, name).filter(
+      (r) => r.direction === "inbound"
+    );
+  }
+};
+
+// src/adapters/postgres/PostgresIntrospector.ts
+var DEFAULT_NAMESPACES = ["public"];
+var PostgresIntrospector = class _PostgresIntrospector {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  name = POSTGRES_ADAPTER_NAME;
+  kind = "relational";
+  async introspect(options = {}) {
+    const namespaces = await this.resolveNamespaces(options.namespaces);
+    const [tables, columns, primaryKeys, foreignKeys, indexes, constraints] = await Promise.all([
+      TablesQuery.fetch(this.client, namespaces),
+      ColumnsQuery.fetch(this.client, namespaces),
+      PrimaryKeysQuery.fetch(this.client, namespaces),
+      ForeignKeysQuery.fetch(this.client, namespaces),
+      IndexesQuery.fetch(this.client, namespaces),
+      ConstraintsQuery.fetch(this.client, namespaces)
+    ]);
+    const filteredTables = _PostgresIntrospector.applyEntityFilters(
+      tables,
+      options
+    );
+    const entities = EntityAssembler.assemble({
+      tables: filteredTables,
+      columns,
+      primaryKeys,
+      foreignKeys,
+      indexes,
+      constraints
+    });
+    return new DataModel("relational", entities);
+  }
+  async resolveNamespaces(raw) {
+    if (raw === void 0) {
+      return DEFAULT_NAMESPACES;
+    }
+    if (raw === "all") {
+      const result = await this.client.query(
+        _PostgresIntrospector.ALL_NAMESPACES_SQL
+      );
+      return result.rows.map((row) => row.nspname);
+    }
+    return raw;
+  }
+  static ALL_NAMESPACES_SQL = `
+SELECT n.nspname
+FROM pg_namespace n
+WHERE n.nspname NOT IN ('pg_catalog', 'information_schema')
+  AND n.nspname NOT LIKE 'pg_toast%'
+  AND n.nspname NOT LIKE 'pg_temp_%'
+ORDER BY n.nspname
+`;
+  static applyEntityFilters(tables, options) {
+    const { includeEntities: allow, excludeEntities: deny } = options;
+    if (!allow && !deny) {
+      return tables;
+    }
+    return tables.filter((t) => {
+      if (allow && !allow.includes(t.name)) {
+        return false;
+      }
+      if (deny?.includes(t.name)) {
+        return false;
+      }
+      return true;
+    });
+  }
+};
+
+// src/adapters/postgres/query/SqlIdentifier.ts
+var SqlIdentifier = class _SqlIdentifier {
+  static quote(id) {
+    return `"${id.replace(/"/g, '""')}"`;
+  }
+  static qualified(namespace, name) {
+    return `${_SqlIdentifier.quote(namespace)}.${_SqlIdentifier.quote(name)}`;
+  }
+};
+
+// src/adapters/postgres/query/FilterBuilder.ts
+var FilterBuilder = class {
+  constructor(params) {
+    this.params = params;
+  }
+  params;
+  build(filter) {
+    const col = SqlIdentifier.quote(filter.field);
+    switch (filter.operator) {
+      case "eq": {
+        return `${col} = ${this.params.add(filter.value)}`;
+      }
+      case "neq": {
+        return `${col} <> ${this.params.add(filter.value)}`;
+      }
+      case "lt": {
+        return `${col} < ${this.params.add(filter.value)}`;
+      }
+      case "lte": {
+        return `${col} <= ${this.params.add(filter.value)}`;
+      }
+      case "gt": {
+        return `${col} > ${this.params.add(filter.value)}`;
+      }
+      case "gte": {
+        return `${col} >= ${this.params.add(filter.value)}`;
+      }
+      case "like": {
+        return `${col} LIKE ${this.params.add(filter.value)}`;
+      }
+      case "ilike": {
+        return `${col} ILIKE ${this.params.add(filter.value)}`;
+      }
+      case "is-null": {
+        return `${col} IS NULL`;
+      }
+      case "is-not-null": {
+        return `${col} IS NOT NULL`;
+      }
+      case "in": {
+        return this.buildInClause(col, filter.value, "FALSE", "IN");
+      }
+      case "not-in": {
+        return this.buildInClause(col, filter.value, "TRUE", "NOT IN");
+      }
+      case "between": {
+        return this.buildBetween(col, filter.value);
+      }
+      default: {
+        const exhaustive = filter.operator;
+        throw new Error(`Unknown filter operator: ${String(exhaustive)}`);
+      }
+    }
+  }
+  buildInClause(col, value, emptyFallback, keyword) {
+    if (!Array.isArray(value)) {
+      throw new Error(
+        `Operator '${keyword.toLowerCase()}' requires an array value.`
+      );
+    }
+    const values = value;
+    if (values.length === 0) {
+      return emptyFallback;
+    }
+    const placeholders = this.params.addAll(values);
+    return `${col} ${keyword} (${placeholders.join(", ")})`;
+  }
+  buildBetween(col, value) {
+    if (!Array.isArray(value) || value.length !== 2) {
+      throw new Error("Operator 'between' requires a [min, max] tuple.");
+    }
+    const tuple = value;
+    const lo = this.params.add(tuple[0]);
+    const hi = this.params.add(tuple[1]);
+    return `${col} BETWEEN ${lo} AND ${hi}`;
+  }
+};
+
+// src/adapters/postgres/query/SqlParamList.ts
+var SqlParamList = class {
+  values = [];
+  /**
+   * Append a value and return its placeholder (`$N`, where N is the
+   * 1-based position of the value in the list).
+   */
+  add(value) {
+    this.values.push(value);
+    return `$${this.values.length}`;
+  }
+  /**
+   * Append many values and return their placeholders in order.
+   */
+  addAll(values) {
+    return values.map((v) => this.add(v));
+  }
+  /** Number of values currently bound. */
+  get size() {
+    return this.values.length;
+  }
+  /**
+   * Return a read-only copy of the bound values. The returned array
+   * is not backed by the internal storage.
+   */
+  toArray() {
+    return [...this.values];
+  }
+};
+
+// src/adapters/postgres/PostgresQueryEngine.ts
+var PostgresQueryEngine = class {
+  name = POSTGRES_ADAPTER_NAME;
+  kind = "relational";
+  build(spec, model) {
+    const entity = model.getEntity(spec.namespace, spec.entity);
+    if (!entity) {
+      throw new Error(
+        `Entity "${spec.namespace}.${spec.entity}" not found in the data model.`
+      );
+    }
+    const fieldNames = new Set(entity.fields.map((f) => f.name));
+    const selectedFields = spec.select && spec.select.length > 0 ? [...spec.select] : entity.fields.map((f) => f.name);
+    for (const field of selectedFields) {
+      if (!fieldNames.has(field)) {
+        throw new Error(
+          `Field "${field}" does not exist on "${spec.namespace}.${spec.entity}".`
+        );
+      }
+    }
+    const params = new SqlParamList();
+    const filterBuilder = new FilterBuilder(params);
+    const selectClause = selectedFields.map(SqlIdentifier.quote).join(", ");
+    const fromClause = SqlIdentifier.qualified(spec.namespace, spec.entity);
+    let sql = `SELECT ${selectClause} FROM ${fromClause}`;
+    if (spec.filters && spec.filters.length > 0) {
+      const wherePieces = spec.filters.map((filter) => {
+        if (!fieldNames.has(filter.field)) {
+          throw new Error(
+            `Filter field "${filter.field}" does not exist on "${spec.namespace}.${spec.entity}".`
+          );
+        }
+        return filterBuilder.build(filter);
+      });
+      sql += ` WHERE ${wherePieces.join(" AND ")}`;
+    }
+    if (spec.orderBy && spec.orderBy.length > 0) {
+      const orderPieces = spec.orderBy.map((order) => {
+        if (!fieldNames.has(order.field)) {
+          throw new Error(
+            `Order field "${order.field}" does not exist on "${spec.namespace}.${spec.entity}".`
+          );
+        }
+        return `${SqlIdentifier.quote(order.field)} ${order.direction.toUpperCase()}`;
+      });
+      sql += ` ORDER BY ${orderPieces.join(", ")}`;
+    }
+    if (spec.limit !== void 0) {
+      sql += ` LIMIT ${params.add(spec.limit)}`;
+    }
+    if (spec.offset !== void 0) {
+      sql += ` OFFSET ${params.add(spec.offset)}`;
+    }
+    return {
+      command: sql,
+      params: params.toArray(),
+      metadata: {
+        engine: POSTGRES_ADAPTER_NAME,
+        paramCount: params.size
+      }
+    };
+  }
+};
+
+// src/parsing/DefaultRecordParser.ts
+var DefaultRecordParser = class {
+  parse(entity, row) {
+    const result = {};
+    for (const field of entity.fields) {
+      if (field.name in row) {
+        result[field.name] = this.coerce(field, row[field.name]);
+      }
+    }
+    return result;
+  }
+  parseMany(entity, rows) {
+    return rows.map((row) => this.parse(entity, row));
+  }
+  coerce(field, raw) {
+    if (raw === null || raw === void 0) {
+      return null;
+    }
+    switch (field.type.category) {
+      case "string":
+      case "uuid":
+      case "enum": {
+        return String(raw);
+      }
+      case "integer": {
+        if (typeof raw === "bigint") {
+          return raw;
+        }
+        if (typeof raw === "number") {
+          return raw;
+        }
+        return Number(raw);
+      }
+      case "decimal": {
+        return typeof raw === "string" ? raw : String(raw);
+      }
+      case "boolean": {
+        return Boolean(raw);
+      }
+      case "date":
+      case "timestamp":
+      case "time": {
+        if (raw instanceof Date) {
+          return raw;
+        }
+        if (typeof raw === "string" || typeof raw === "number") {
+          return new Date(raw);
+        }
+        return null;
+      }
+      case "json":
+      case "binary":
+      case "reference":
+      case "unknown": {
+        return raw;
+      }
+      case "array": {
+        return Array.isArray(raw) ? raw : [];
+      }
+      default: {
+        const exhaustive = field.type.category;
+        return exhaustive;
+      }
+    }
+  }
+};
+
+// src/adapters/postgres/PostgresRecordParser.ts
+var BIGINT_NATIVE_TYPES = /* @__PURE__ */ new Set(["int8", "bigint"]);
+var PostgresRecordParser = class extends DefaultRecordParser {
+  coerce(field, raw) {
+    if (raw === null || raw === void 0) {
+      return null;
+    }
+    if (field.type.category === "integer" && BIGINT_NATIVE_TYPES.has(field.type.nativeType.toLowerCase())) {
+      if (typeof raw === "bigint") {
+        return raw;
+      }
+      if (typeof raw === "string" || typeof raw === "number") {
+        return BigInt(raw);
+      }
+      return null;
+    }
+    if (field.type.category === "json" && typeof raw === "string") {
+      try {
+        return JSON.parse(raw);
+      } catch {
+        return raw;
+      }
+    }
+    return super.coerce(field, raw);
+  }
+};
+
+// src/adapters/postgres/PostgresRawQueryRunner.ts
+var PostgresRawQueryRunner = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  async run(built) {
+    const result = await this.client.query(built.command, [
+      ...built.params
+    ]);
+    return result.rows;
+  }
+};
+
+// src/adapters/postgres/postgresAdapter.ts
+var postgresAdapter = {
+  name: POSTGRES_ADAPTER_NAME,
+  urlSchemes: POSTGRES_URL_SCHEMES,
+  create(client) {
+    return {
+      name: POSTGRES_ADAPTER_NAME,
+      introspector: new PostgresIntrospector(client),
+      engine: new PostgresQueryEngine(),
+      runner: new PostgresRawQueryRunner(client),
+      parser: new PostgresRecordParser(),
+      urlSchemes: POSTGRES_URL_SCHEMES
+    };
+  }
+};
+function isPostgresAdapter(adapter) {
+  return adapter.name === POSTGRES_ADAPTER_NAME;
+}
+
+// src/codegen/OverridesScaffold.ts
+var SCAFFOLD = `// biref.schema.overrides.ts - edit freely, regen will NOT touch this file.
+//
+// Use this file to attach concrete TypeScript types to columns whose
+// shape the database scanner cannot see - typically jsonb payloads.
+// Key each override by qualified entity name ('namespace.entity')
+// and list the fields you want to type.
+//
+// @example
+// export interface Overrides {
+//   'identity.users': {
+//     profile: { plan: 'free' | 'pro'; prefs: { darkMode: boolean } };
+//   };
+// }
+
+export interface Overrides {}
+`;
+function overridesScaffold() {
+  return SCAFFOLD;
+}
+
+// src/codegen/TsTypeMapper.ts
+function tsTypeFor(type, nullable) {
+  const base = baseType(type);
+  return nullable ? `${base} | null` : base;
+}
+function baseType(type) {
+  switch (type.category) {
+    case "string":
+    case "uuid": {
+      return "string";
+    }
+    case "enum": {
+      if (type.enumValues && type.enumValues.length > 0) {
+        return type.enumValues.map((value) => `'${escapeSingleQuote(value)}'`).join(" | ");
+      }
+      return "string";
+    }
+    case "integer": {
+      return "number";
+    }
+    case "decimal": {
+      return "string";
+    }
+    case "boolean": {
+      return "boolean";
+    }
+    case "date":
+    case "timestamp":
+    case "time": {
+      return "Date";
+    }
+    case "json": {
+      return "unknown";
+    }
+    case "binary": {
+      return "Uint8Array";
+    }
+    case "array": {
+      const element = type.elementType ? baseType(type.elementType) : "unknown";
+      return `ReadonlyArray<${element}>`;
+    }
+    case "reference":
+    case "unknown": {
+      return "unknown";
+    }
+    default: {
+      return assertNever(type.category);
+    }
+  }
+}
+function escapeSingleQuote(value) {
+  return value.replace(/\\/g, "\\\\").replace(/'/g, "\\'");
+}
+function assertNever(value) {
+  throw new Error(`Unhandled FieldTypeCategory: ${String(value)}`);
+}
+
+// src/query/relationNaming.ts
+function buildRelationNameMap(entity) {
+  const result = /* @__PURE__ */ new Map();
+  const used = /* @__PURE__ */ new Set();
+  const proposals = [];
+  entity.relationships.forEach((rel, order) => {
+    const other = rel.direction === "outbound" ? rel.reference.toEntity : rel.reference.fromEntity;
+    const isSelfRef = other.namespace === entity.namespace && other.name === entity.name;
+    let name;
+    if (isSelfRef) {
+      name = rel.direction === "outbound" ? "parent" : "children";
+    } else if (rel.direction === "outbound") {
+      name = nameFromColumns(rel.reference.fromFields) ?? other.name;
+    } else {
+      name = other.name;
+    }
+    proposals.push({ rel, name, order });
+  });
+  proposals.sort((a, b) => {
+    if (a.rel.direction !== b.rel.direction) {
+      return a.rel.direction === "outbound" ? -1 : 1;
+    }
+    return a.order - b.order;
+  });
+  for (const { rel, name } of proposals) {
+    let final = name;
+    if (used.has(final)) {
+      final = disambiguate(rel, name, used);
+    }
+    used.add(final);
+    result.set(final, rel);
+  }
+  return result;
+}
+function nameFromColumns(columns) {
+  if (columns.length === 0) {
+    return null;
+  }
+  const pieces = columns.map(stripIdSuffix).map((piece) => piece.trim()).filter((piece) => piece.length > 0 && piece.toLowerCase() !== "id");
+  if (pieces.length === 0) {
+    return null;
+  }
+  return pieces.join("_");
+}
+function stripIdSuffix(column) {
+  const underscore = column.match(/^(.*)_id$/i);
+  if (underscore?.[1] !== void 0) {
+    return underscore[1];
+  }
+  const camel = column.match(/^(.*)Id$/);
+  if (camel?.[1] !== void 0) {
+    return camel[1];
+  }
+  return column;
+}
+function disambiguate(rel, base, used) {
+  if (rel.direction === "inbound") {
+    const suffix = nameFromColumns(rel.reference.fromFields);
+    if (suffix) {
+      const candidate2 = `${base}_by_${suffix}`;
+      if (!used.has(candidate2)) {
+        return candidate2;
+      }
+    }
+  } else {
+    const targetName = rel.direction === "outbound" ? rel.reference.toEntity.name : null;
+    if (targetName) {
+      const candidate2 = `${base}_${targetName}`;
+      if (!used.has(candidate2)) {
+        return candidate2;
+      }
+    }
+  }
+  let candidate = rel.reference.name;
+  if (!used.has(candidate)) {
+    return candidate;
+  }
+  let counter = 2;
+  while (used.has(candidate)) {
+    candidate = `${rel.reference.name}_${counter}`;
+    counter += 1;
+  }
+  return candidate;
+}
+
+// src/codegen/SchemaEmitter.ts
+var GENERATED_BANNER = `// This file is generated by @biref/scanner. Do not edit by hand.
+// Re-run \`biref gen\` to regenerate it from a live database scan.
+//
+// Overrides live in the sibling \`biref.schema.overrides.ts\` file
+// (never regenerated) and are deep-merged into \`BirefSchema\` via
+// \`ApplySchemaOverrides\`.`;
+function generateSchema(model) {
+  const namespaces = groupByNamespace(model);
+  const sortedNamespaces = [...namespaces.keys()].sort();
+  const lines = [];
+  lines.push(GENERATED_BANNER);
+  lines.push("");
+  lines.push("import type { ApplySchemaOverrides } from '@biref/scanner';");
+  lines.push("import type { Overrides } from './biref.schema.overrides';");
+  lines.push("");
+  lines.push("export interface RawBirefSchema {");
+  for (const namespace of sortedNamespaces) {
+    const entities = namespaces.get(namespace);
+    if (!entities) {
+      continue;
+    }
+    lines.push(`  readonly ${quoteKey(namespace)}: {`);
+    const sortedEntities = [...entities].sort(
+      (a, b) => a.name.localeCompare(b.name)
+    );
+    for (const entity of sortedEntities) {
+      lines.push(`    readonly ${quoteKey(entity.name)}: {`);
+      lines.push("      readonly fields: {");
+      for (const field of entity.fields) {
+        lines.push(indent(formatFieldDescriptor(field), 4));
+      }
+      lines.push("      };");
+      lines.push(`      readonly identifier: ${formatIdentifier(entity)};`);
+      const relations = sortedRelations(entity);
+      if (relations.length === 0) {
+        lines.push("      readonly relations: Record<string, never>;");
+      } else {
+        lines.push("      readonly relations: {");
+        for (const [name, relationship] of relations) {
+          lines.push(indent(formatRelationDescriptor(name, relationship), 4));
+        }
+        lines.push("      };");
+      }
+      lines.push("    };");
+    }
+    lines.push("  };");
+  }
+  lines.push("}");
+  lines.push("");
+  lines.push(
+    "export type BirefSchema = ApplySchemaOverrides<RawBirefSchema, Overrides>;"
+  );
+  lines.push("");
+  return lines.join("\n");
+}
+function generateSchemaFiles(model) {
+  const namespaces = groupByNamespace(model);
+  const sortedNamespaces = [...namespaces.keys()].sort();
+  const files = [];
+  for (const namespace of sortedNamespaces) {
+    const entities = namespaces.get(namespace);
+    if (!entities) {
+      continue;
+    }
+    const sortedEntities = [...entities].sort(
+      (a, b) => a.name.localeCompare(b.name)
+    );
+    for (const entity of sortedEntities) {
+      files.push({
+        path: `${safeSegment(namespace)}/${safeSegment(entity.name)}.ts`,
+        content: emitEntityFile(entity)
+      });
+    }
+  }
+  files.push({
+    path: "index.ts",
+    content: emitIndexFile(model)
+  });
+  return files;
+}
+function emitEntityFile(entity) {
+  const interfaceName = entityInterfaceName(entity.namespace, entity.name);
+  const lines = [];
+  lines.push(GENERATED_BANNER);
+  lines.push("");
+  lines.push(`export interface ${interfaceName} {`);
+  lines.push("  readonly fields: {");
+  for (const field of entity.fields) {
+    lines.push(indent(formatFieldDescriptor(field), 2));
+  }
+  lines.push("  };");
+  lines.push(`  readonly identifier: ${formatIdentifier(entity)};`);
+  const relations = sortedRelations(entity);
+  if (relations.length === 0) {
+    lines.push("  readonly relations: Record<string, never>;");
+  } else {
+    lines.push("  readonly relations: {");
+    for (const [name, relationship] of relations) {
+      lines.push(indent(formatRelationDescriptor(name, relationship), 2));
+    }
+    lines.push("  };");
+  }
+  lines.push("}");
+  lines.push("");
+  return lines.join("\n");
+}
+function emitIndexFile(model) {
+  const namespaces = groupByNamespace(model);
+  const sortedNamespaces = [...namespaces.keys()].sort();
+  const lines = [];
+  lines.push(GENERATED_BANNER);
+  lines.push("");
+  lines.push("import type { ApplySchemaOverrides } from '@biref/scanner';");
+  lines.push("import type { Overrides } from './biref.schema.overrides';");
+  lines.push("");
+  const allEntities = [];
+  for (const namespace of sortedNamespaces) {
+    const entities = namespaces.get(namespace);
+    if (!entities) {
+      continue;
+    }
+    for (const entity of [...entities].sort(
+      (a, b) => a.name.localeCompare(b.name)
+    )) {
+      allEntities.push({ namespace, entity });
+    }
+  }
+  for (const { namespace, entity } of allEntities) {
+    const iface = entityInterfaceName(namespace, entity.name);
+    lines.push(
+      `import type { ${iface} } from './${safeSegment(namespace)}/${safeSegment(entity.name)}';`
+    );
+  }
+  lines.push("");
+  for (const { namespace, entity } of allEntities) {
+    const iface = entityInterfaceName(namespace, entity.name);
+    lines.push(
+      `export type { ${iface} } from './${safeSegment(namespace)}/${safeSegment(entity.name)}';`
+    );
+  }
+  lines.push("");
+  lines.push("export interface RawBirefSchema {");
+  for (const namespace of sortedNamespaces) {
+    const entities = namespaces.get(namespace);
+    if (!entities) {
+      continue;
+    }
+    lines.push(`  readonly ${quoteKey(namespace)}: {`);
+    const sortedEntities = [...entities].sort(
+      (a, b) => a.name.localeCompare(b.name)
+    );
+    for (const entity of sortedEntities) {
+      const iface = entityInterfaceName(namespace, entity.name);
+      lines.push(`    readonly ${quoteKey(entity.name)}: ${iface};`);
+    }
+    lines.push("  };");
+  }
+  lines.push("}");
+  lines.push("");
+  lines.push(
+    "export type BirefSchema = ApplySchemaOverrides<RawBirefSchema, Overrides>;"
+  );
+  lines.push("");
+  return lines.join("\n");
+}
+function groupByNamespace(model) {
+  const map = /* @__PURE__ */ new Map();
+  for (const entity of model.entities) {
+    const bucket = map.get(entity.namespace);
+    if (bucket) {
+      bucket.push(entity);
+    } else {
+      map.set(entity.namespace, [entity]);
+    }
+  }
+  return map;
+}
+function sortedRelations(entity) {
+  return [...buildRelationNameMap(entity).entries()].sort(
+    ([a], [b]) => a.localeCompare(b)
+  );
+}
+function formatFieldDescriptor(field) {
+  const ts = tsTypeFor(field.type, field.nullable);
+  const nullable = field.nullable ? "true" : "false";
+  const isIdentifier = field.isIdentifier ? "true" : "false";
+  const category = `'${field.type.category}'`;
+  return `  readonly ${quoteKey(field.name)}: { readonly ts: ${ts}; readonly nullable: ${nullable}; readonly isIdentifier: ${isIdentifier}; readonly category: ${category} };`;
+}
+function formatIdentifier(entity) {
+  if (entity.identifier.length === 0) {
+    return "readonly []";
+  }
+  const items = entity.identifier.map((name) => `'${escapeString(name)}'`);
+  return `readonly [${items.join(", ")}]`;
+}
+function formatRelationDescriptor(name, relationship) {
+  const target = relationship.direction === "outbound" ? relationship.reference.toEntity : relationship.reference.fromEntity;
+  const qualifiedTarget = `'${escapeString(target.namespace)}.${escapeString(target.name)}'`;
+  const fromFields = formatStringArray(relationship.reference.fromFields);
+  const toFields = formatStringArray(relationship.reference.toFields);
+  const cardinality = relationship.direction === "outbound" ? "'one'" : "'many'";
+  const direction = `'${relationship.direction}'`;
+  return `  readonly ${quoteKey(name)}: { readonly direction: ${direction}; readonly target: ${qualifiedTarget}; readonly fromFields: ${fromFields}; readonly toFields: ${toFields}; readonly cardinality: ${cardinality} };`;
+}
+function formatStringArray(values) {
+  if (values.length === 0) {
+    return "readonly []";
+  }
+  return `readonly [${values.map((v) => `'${escapeString(v)}'`).join(", ")}]`;
+}
+function quoteKey(key) {
+  if (/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(key)) {
+    return key;
+  }
+  return `'${escapeString(key)}'`;
+}
+function escapeString(value) {
+  return value.replace(/\\/g, "\\\\").replace(/'/g, "\\'");
+}
+function entityInterfaceName(namespace, entity) {
+  return toPascalCase(namespace) + toPascalCase(entity);
+}
+function toPascalCase(value) {
+  return value.split(/[^A-Za-z0-9]+/).filter((segment) => segment.length > 0).map(
+    (segment) => segment.charAt(0).toUpperCase() + segment.slice(1).toLowerCase()
+  ).join("");
+}
+function safeSegment(name) {
+  return name.replace(/[^A-Za-z0-9_-]/g, "_");
+}
+function indent(text, spaces) {
+  const pad = " ".repeat(spaces);
+  return text.split("\n").map((line) => line.length === 0 ? line : `${pad}${line}`).join("\n");
+}
+
+// src/core/AdapterRegistry.ts
+var AdapterRegistry = class {
+  adapters = /* @__PURE__ */ new Map();
+  register(adapter) {
+    if (this.adapters.has(adapter.name)) {
+      throw new Error(`Adapter "${adapter.name}" is already registered.`);
+    }
+    this.adapters.set(adapter.name, adapter);
+  }
+  unregister(name) {
+    return this.adapters.delete(name);
+  }
+  get(name) {
+    const adapter = this.adapters.get(name);
+    if (!adapter) {
+      const known = [...this.adapters.keys()].join(", ") || "(none)";
+      throw new Error(
+        `No adapter registered under "${name}". Registered adapters: ${known}.`
+      );
+    }
+    return adapter;
+  }
+  has(name) {
+    return this.adapters.has(name);
+  }
+  list() {
+    return [...this.adapters.keys()];
+  }
+  /**
+   * Find an adapter that claims the given URL scheme. Case-insensitive.
+   * Returns `undefined` if no adapter handles it.
+   */
+  findByUrlScheme(scheme) {
+    const normalized = scheme.toLowerCase();
+    for (const adapter of this.adapters.values()) {
+      const matches = adapter.urlSchemes?.some(
+        (s) => s.toLowerCase() === normalized
+      );
+      if (matches) {
+        return adapter;
+      }
+    }
+    return void 0;
+  }
+  /**
+   * Same as `findByUrlScheme` but throws a helpful error listing the
+   * known schemes when no match is found.
+   */
+  getByUrlScheme(scheme) {
+    const adapter = this.findByUrlScheme(scheme);
+    if (!adapter) {
+      const known = [...this.adapters.values()].flatMap((a) => a.urlSchemes ?? []).join(", ") || "(none)";
+      throw new Error(
+        `No adapter registered for URL scheme "${scheme}". Known schemes: ${known}.`
+      );
+    }
+    return adapter;
+  }
+};
+
+// src/core/QueryPlanExecutor.ts
+var QueryPlanExecutor = class _QueryPlanExecutor {
+  constructor(engine, runner, parser) {
+    this.engine = engine;
+    this.runner = runner;
+    this.parser = parser;
+  }
+  engine;
+  runner;
+  parser;
+  async execute(plan, model) {
+    const entity = model.getEntity(plan.spec.namespace, plan.spec.entity);
+    if (!entity) {
+      throw new Error(
+        `Entity "${plan.spec.namespace}.${plan.spec.entity}" not found in the data model.`
+      );
+    }
+    const exposedKeys = _QueryPlanExecutor.resolveExposedKeys(
+      plan.spec,
+      entity,
+      plan.includes
+    );
+    const normalizedSpec = _QueryPlanExecutor.injectFields(
+      plan.spec,
+      _QueryPlanExecutor.collectParentKeys(plan.includes)
+    );
+    const built = this.engine.build(normalizedSpec, model);
+    const rawRows = await this.runner.run(built);
+    const parentRecords = this.parser.parseMany(entity, rawRows);
+    if (plan.includes.length === 0) {
+      return _QueryPlanExecutor.project(parentRecords, exposedKeys);
+    }
+    return this.attachIncludes(
+      parentRecords,
+      plan.includes,
+      exposedKeys,
+      model
+    );
+  }
+  async attachIncludes(parents, includes, parentUserSelect, model) {
+    const working = parents.map((p) => ({
+      ...p
+    }));
+    for (const include of includes) {
+      const childPlan = _QueryPlanExecutor.prepareChildPlan(include, working);
+      if (childPlan === null) {
+        for (const parent of working) {
+          parent[include.relationName] = include.cardinality === "one" ? null : [];
+        }
+        continue;
+      }
+      const rawChildren = await this.execute(childPlan, model);
+      const childExposedKeys = _QueryPlanExecutor.resolveChildExposedKeys(
+        include.plan,
+        model
+      );
+      const indexingKeys = new Set(childExposedKeys);
+      for (const key of include.childKeys) {
+        indexingKeys.add(key);
+      }
+      const byKey = _QueryPlanExecutor.indexByKey(
+        rawChildren.map((c) => _QueryPlanExecutor.filterKeys(c, indexingKeys)),
+        include.childKeys
+      );
+      for (const parent of working) {
+        const lookupKey = _QueryPlanExecutor.buildKey(
+          parent,
+          include.parentKeys
+        );
+        const matches = lookupKey === null ? [] : byKey.get(lookupKey) ?? [];
+        const projectedMatches = _QueryPlanExecutor.project(
+          matches,
+          childExposedKeys
+        );
+        parent[include.relationName] = include.cardinality === "one" ? projectedMatches[0] ?? null : [...projectedMatches];
+      }
+    }
+    return working.map(
+      (parent) => _QueryPlanExecutor.filterKeys(parent, parentUserSelect)
+    );
+  }
+  static prepareChildPlan(include, parents) {
+    if (parents.length === 0) {
+      return null;
+    }
+    if (include.parentKeys.length === 0 || include.childKeys.length === 0) {
+      return null;
+    }
+    const collected = include.parentKeys.map(() => []);
+    let anyMatch = false;
+    for (const parent of parents) {
+      let hasAll = true;
+      const tuple = [];
+      for (const key of include.parentKeys) {
+        const value = parent[key];
+        if (value === null || value === void 0) {
+          hasAll = false;
+          break;
+        }
+        tuple.push(value);
+      }
+      if (!hasAll) {
+        continue;
+      }
+      for (let i = 0; i < tuple.length; i += 1) {
+        const bucket = collected[i];
+        if (bucket) {
+          bucket.push(tuple[i]);
+        }
+      }
+      anyMatch = true;
+    }
+    if (!anyMatch) {
+      return null;
+    }
+    let plan = {
+      ...include.plan,
+      spec: _QueryPlanExecutor.injectFields(
+        include.plan.spec,
+        include.childKeys
+      )
+    };
+    for (let i = 0; i < include.childKeys.length; i += 1) {
+      const childKey = include.childKeys[i];
+      const bucket = collected[i];
+      if (childKey === void 0 || bucket === void 0) {
+        return null;
+      }
+      const unique = Array.from(new Set(bucket));
+      const filter = {
+        field: childKey,
+        operator: "in",
+        value: unique
+      };
+      plan = {
+        ...plan,
+        spec: {
+          ...plan.spec,
+          filters: [...plan.spec.filters ?? [], filter]
+        }
+      };
+    }
+    return plan;
+  }
+  static injectFields(spec, fields) {
+    if (!spec.select || spec.select.length === 0) {
+      return spec;
+    }
+    if (fields.length === 0) {
+      return spec;
+    }
+    const seen = new Set(spec.select);
+    const extras = [];
+    for (const field of fields) {
+      if (!seen.has(field)) {
+        seen.add(field);
+        extras.push(field);
+      }
+    }
+    if (extras.length === 0) {
+      return spec;
+    }
+    return { ...spec, select: [...spec.select, ...extras] };
+  }
+  static collectParentKeys(includes) {
+    const keys = [];
+    for (const include of includes) {
+      for (const key of include.parentKeys) {
+        keys.push(key);
+      }
+    }
+    return keys;
+  }
+  /**
+   * Compute the set of keys a hydrated record should expose to the
+   * caller: the user's selected fields (or every entity field when
+   * no select was given) plus every nested include's relation name
+   * so attached children survive the final filter step.
+   */
+  static resolveExposedKeys(spec, entity, includes) {
+    const set = /* @__PURE__ */ new Set();
+    if (spec.select && spec.select.length > 0) {
+      for (const field of spec.select) {
+        set.add(field);
+      }
+    } else {
+      for (const field of entity.fields) {
+        set.add(field.name);
+      }
+    }
+    for (const include of includes) {
+      set.add(include.relationName);
+    }
+    return set;
+  }
+  /**
+   * Resolve the exposed-keys set for an include's nested plan.
+   *
+   * Uses the ORIGINAL include.plan (not the mutated child plan we
+   * handed to the executor) so injected join keys do not leak into
+   * the final output.
+   */
+  static resolveChildExposedKeys(plan, model) {
+    const entity = model.getEntity(plan.spec.namespace, plan.spec.entity);
+    if (!entity) {
+      return /* @__PURE__ */ new Set();
+    }
+    return _QueryPlanExecutor.resolveExposedKeys(
+      plan.spec,
+      entity,
+      plan.includes
+    );
+  }
+  static project(records, allow) {
+    return records.map((record) => _QueryPlanExecutor.filterKeys(record, allow));
+  }
+  static indexByKey(records, keys) {
+    const map = /* @__PURE__ */ new Map();
+    for (const record of records) {
+      const key = _QueryPlanExecutor.buildKey(record, keys);
+      if (key === null) {
+        continue;
+      }
+      const bucket = map.get(key);
+      if (bucket) {
+        bucket.push(record);
+      } else {
+        map.set(key, [record]);
+      }
+    }
+    return map;
+  }
+  static buildKey(record, keys) {
+    if (keys.length === 0) {
+      return "";
+    }
+    const parts = [];
+    for (const key of keys) {
+      const value = record[key];
+      if (value === null || value === void 0) {
+        return null;
+      }
+      parts.push(
+        typeof value === "bigint" ? `bigint:${value.toString()}` : value
+      );
+    }
+    return JSON.stringify(parts);
+  }
+  static filterKeys(record, allow) {
+    const result = {};
+    for (const [key, value] of Object.entries(record)) {
+      if (allow.has(key)) {
+        result[key] = value;
+      }
+    }
+    return result;
+  }
+};
+
+// src/query/ChainBuilder.ts
+var ChainBuilder = class _ChainBuilder {
+  constructor(ctx, plan) {
+    this.ctx = ctx;
+    this.plan = plan;
+  }
+  ctx;
+  plan;
+  /**
+   * Narrow the projection to a specific set of fields.
+   *
+   *   .select('id', 'email')  -- only these two columns
+   *   .select('*')            -- every field of the entity
+   *   .select()               -- equivalent to '*', kept for ergonomic parity
+   *
+   * Unknown field names throw immediately with a clear error; the
+   * wildcard sentinel skips validation and leaves the plan's `select`
+   * undefined so the engine emits every column the adapter reported.
+   */
+  select(...fields) {
+    if (fields.length === 0 || fields.some((f) => f === "*")) {
+      if (fields.some((f) => f !== "*")) {
+        throw new Error(
+          "select('*') cannot be combined with other field names. Pass either '*' or the specific columns you want."
+        );
+      }
+      return new _ChainBuilder(this.ctx, {
+        ...this.plan,
+        spec: { ...this.plan.spec, select: void 0 }
+      });
+    }
+    const entity = this.requireEntity();
+    const known = new Set(entity.fields.map((f) => f.name));
+    for (const field of fields) {
+      if (!known.has(field)) {
+        throw new Error(
+          `Field "${field}" does not exist on "${this.plan.spec.namespace}.${this.plan.spec.entity}".`
+        );
+      }
+    }
+    return new _ChainBuilder(this.ctx, {
+      ...this.plan,
+      spec: { ...this.plan.spec, select: [...fields] }
+    });
+  }
+  where(field, operator, value) {
+    const entity = this.requireEntity();
+    if (!entity.fields.some((f) => f.name === field)) {
+      throw new Error(
+        `Filter field "${field}" does not exist on "${this.plan.spec.namespace}.${this.plan.spec.entity}".`
+      );
+    }
+    const filter = {
+      field,
+      operator,
+      value: value ?? null
+    };
+    return new _ChainBuilder(this.ctx, {
+      ...this.plan,
+      spec: {
+        ...this.plan.spec,
+        filters: [...this.plan.spec.filters ?? [], filter]
+      }
+    });
+  }
+  orderBy(field, direction = "asc") {
+    const entity = this.requireEntity();
+    if (!entity.fields.some((f) => f.name === field)) {
+      throw new Error(
+        `Order field "${field}" does not exist on "${this.plan.spec.namespace}.${this.plan.spec.entity}".`
+      );
+    }
+    const order = { field, direction };
+    return new _ChainBuilder(this.ctx, {
+      ...this.plan,
+      spec: {
+        ...this.plan.spec,
+        orderBy: [...this.plan.spec.orderBy ?? [], order]
+      }
+    });
+  }
+  limit(count) {
+    return new _ChainBuilder(this.ctx, {
+      ...this.plan,
+      spec: { ...this.plan.spec, limit: count }
+    });
+  }
+  offset(count) {
+    return new _ChainBuilder(this.ctx, {
+      ...this.plan,
+      spec: { ...this.plan.spec, offset: count }
+    });
+  }
+  /**
+   * Attach a nested include to the plan.
+   *
+   * Three call shapes are supported:
+   *
+   *   .include('orders')                                 -- all fields, no nested
+   *   .include('orders', (q) => q.select('id', 'total')) -- narrow the child
+   *   .include('*')                                      -- every relation on this entity
+   *
+   * The callback is optional. When omitted, the child plan uses the
+   * default projection (all fields of the related entity) and no
+   * further includes. Pass a callback when you want to narrow the
+   * projection or chain additional nested includes.
+   *
+   * The wildcard `'*'` expands to one include per relation discovered
+   * on the current entity. Each expanded include uses the default
+   * projection. Combining `'*'` with a callback is not supported -
+   * the sub-builder's shape differs per relation, so a single
+   * callback cannot narrow all of them coherently.
+   */
+  include(relationName, build) {
+    const entity = this.requireEntity();
+    const relationMap = buildRelationNameMap(entity);
+    if (relationName === "*") {
+      if (build) {
+        throw new Error(
+          "Wildcard include '*' does not accept a builder callback. Use named includes to narrow individual relations."
+        );
+      }
+      let current = this;
+      for (const name of relationMap.keys()) {
+        current = current.include(name);
+      }
+      return current;
+    }
+    const relationship = relationMap.get(relationName);
+    if (!relationship) {
+      const known = [...relationMap.keys()].join(", ") || "(none)";
+      throw new Error(
+        `Relation "${relationName}" does not exist on "${this.plan.spec.namespace}.${this.plan.spec.entity}". Known relations: ${known}.`
+      );
+    }
+    const target = relationship.direction === "outbound" ? relationship.reference.toEntity : relationship.reference.fromEntity;
+    const childSpec = {
+      namespace: target.namespace,
+      entity: target.name
+    };
+    const childBuilder = new _ChainBuilder(this.ctx, {
+      spec: childSpec,
+      includes: []
+    });
+    const finishedChild = build ? build(childBuilder) : childBuilder;
+    const parentKeys = relationship.direction === "outbound" ? relationship.reference.fromFields : relationship.reference.toFields;
+    const childKeys = relationship.direction === "outbound" ? relationship.reference.toFields : relationship.reference.fromFields;
+    const include = {
+      relationName,
+      plan: finishedChild.plan,
+      direction: relationship.direction,
+      parentKeys,
+      childKeys,
+      cardinality: relationship.direction === "outbound" ? "one" : "many"
+    };
+    return new _ChainBuilder(this.ctx, {
+      ...this.plan,
+      includes: [...this.plan.includes, include]
+    });
+  }
+  async findMany() {
+    return this.ctx.executor.execute(this.plan, this.ctx.model);
+  }
+  async findFirst() {
+    const limited = {
+      ...this.plan,
+      spec: { ...this.plan.spec, limit: 1 }
+    };
+    const rows = await this.ctx.executor.execute(limited, this.ctx.model);
+    return rows[0] ?? null;
+  }
+  /**
+   * Escape hatch for advanced callers (tests, tooling): exposes the
+   * accumulated plan without executing it. The typed builder's public
+   * surface does not reference this directly.
+   */
+  toPlan() {
+    return this.plan;
+  }
+  requireEntity() {
+    const entity = this.ctx.model.getEntity(
+      this.plan.spec.namespace,
+      this.plan.spec.entity
+    );
+    if (!entity) {
+      throw new Error(
+        `Entity "${this.plan.spec.namespace}.${this.plan.spec.entity}" not found in the data model.`
+      );
+    }
+    return entity;
+  }
+};
+
+// src/query/NamespaceProxy.ts
+function createNamespaceProxy(ctx) {
+  const namespaces = collectNamespaces(ctx.model);
+  return new Proxy(/* @__PURE__ */ Object.create(null), {
+    get(_target, prop) {
+      if (typeof prop !== "string") {
+        return void 0;
+      }
+      if (!namespaces.has(prop)) {
+        return void 0;
+      }
+      return createEntityProxy(ctx, prop);
+    },
+    has(_target, prop) {
+      return typeof prop === "string" && namespaces.has(prop);
+    },
+    ownKeys() {
+      return [...namespaces];
+    },
+    getOwnPropertyDescriptor(_target, prop) {
+      if (typeof prop !== "string" || !namespaces.has(prop)) {
+        return void 0;
+      }
+      return {
+        enumerable: true,
+        configurable: true,
+        value: createEntityProxy(ctx, prop)
+      };
+    }
+  });
+}
+function createEntityProxy(ctx, namespace) {
+  const entities = collectEntities(ctx.model, namespace);
+  return new Proxy(/* @__PURE__ */ Object.create(null), {
+    get(_target, prop) {
+      if (typeof prop !== "string") {
+        return void 0;
+      }
+      if (!entities.has(prop)) {
+        return void 0;
+      }
+      return new ChainBuilder(ctx, {
+        spec: { namespace, entity: prop },
+        includes: []
+      });
+    },
+    has(_target, prop) {
+      return typeof prop === "string" && entities.has(prop);
+    },
+    ownKeys() {
+      return [...entities];
+    },
+    getOwnPropertyDescriptor(_target, prop) {
+      if (typeof prop !== "string" || !entities.has(prop)) {
+        return void 0;
+      }
+      return {
+        enumerable: true,
+        configurable: true,
+        value: new ChainBuilder(ctx, {
+          spec: { namespace, entity: prop },
+          includes: []
+        })
+      };
+    }
+  });
+}
+function collectNamespaces(model) {
+  const namespaces = /* @__PURE__ */ new Set();
+  for (const entity of model.entities) {
+    namespaces.add(entity.namespace);
+  }
+  return namespaces;
+}
+function collectEntities(model, namespace) {
+  const entities = /* @__PURE__ */ new Set();
+  for (const entity of model.entities) {
+    if (entity.namespace === namespace) {
+      entities.add(entity.name);
+    }
+  }
+  return entities;
+}
+
+// src/core/Biref.ts
+var Biref = class {
+  constructor(registry) {
+    this.registry = registry;
+  }
+  registry;
+  /** Entry point for the fluent builder. */
+  static builder() {
+    return new BirefBuilder();
+  }
+  async scan(adapterNameOrOptions, maybeOptions) {
+    const { adapter, options } = this.resolveScanArgs(
+      adapterNameOrOptions,
+      maybeOptions
+    );
+    return adapter.introspector.introspect(options);
+  }
+  /**
+   * Introspect a data store using whichever registered adapter handles
+   * the URL's scheme. The URL is only used to pick the adapter; the
+   * actual connection is still owned by the client the user passed to
+   * the adapter at construction time.
+   */
+  async scanByUrl(url, options) {
+    const scheme = parseUrlScheme(url);
+    return this.registry.getByUrlScheme(scheme).introspector.introspect(options);
+  }
+  /**
+   * Typed query entry point. Returns a namespace-level Proxy over the
+   * given `DataModel`:
+   *
+   *   biref.query(model).public.users
+   *     .select('id', 'email')
+   *     .where('active', 'eq', true)
+   *     .include('orders', (q) => q.select('id', 'total'))
+   *     .findMany();
+   *
+   * The Proxy layers (`namespace` → `entity`) enumerate what's
+   * actually in the scanned model, so `Object.keys(biref.query(model))`
+   * returns the discovered namespaces. Access to a non-existent
+   * namespace or entity returns `undefined`; the chain methods throw
+   * with a clear error when given unknown fields or relations.
+   *
+   * With a single registered adapter, the adapter is picked
+   * automatically. Pass `adapterName` explicitly to target a specific
+   * adapter when more than one is registered.
+   */
+  query(model, adapterName) {
+    const adapter = adapterName ? this.registry.get(adapterName) : this.requireSingleAdapter("query");
+    const executor = this.executorFor(adapter);
+    const proxy = createNamespaceProxy({ model, executor });
+    return proxy;
+  }
+  /** Direct access to the underlying registry. */
+  get adapters() {
+    return this.registry;
+  }
+  executorFor(adapter) {
+    if (!adapter.runner) {
+      throw new Error(
+        `Adapter "${adapter.name}" does not expose a RawQueryRunner. Update the adapter factory to attach one before calling biref.query(...).`
+      );
+    }
+    if (!adapter.parser) {
+      throw new Error(
+        `Adapter "${adapter.name}" does not expose a RecordParser. Update the adapter factory to attach one before calling biref.query(...).`
+      );
+    }
+    return new QueryPlanExecutor(
+      adapter.engine,
+      adapter.runner,
+      adapter.parser
+    );
+  }
+  resolveScanArgs(adapterNameOrOptions, maybeOptions) {
+    if (typeof adapterNameOrOptions === "string") {
+      return {
+        adapter: this.registry.get(adapterNameOrOptions),
+        options: maybeOptions
+      };
+    }
+    return {
+      adapter: this.requireSingleAdapter("scan"),
+      options: adapterNameOrOptions
+    };
+  }
+  requireSingleAdapter(operation) {
+    const names = this.registry.list();
+    if (names.length === 0) {
+      throw new Error(
+        `Biref.${operation}() called with no adapter argument, but no adapters are registered. Register one via Biref.builder().withAdapter(...).`
+      );
+    }
+    if (names.length > 1) {
+      throw new Error(
+        `Biref.${operation}() called with no adapter argument, but multiple adapters are registered (${names.join(", ")}). Pass an adapter name explicitly.`
+      );
+    }
+    const onlyName = names[0];
+    if (onlyName === void 0) {
+      throw new Error(
+        "Internal error: adapter list reported a length of 1 but produced no name."
+      );
+    }
+    return this.registry.get(onlyName);
+  }
+};
+var BirefBuilder = class {
+  pending = [];
+  /**
+   * Register an adapter. The adapter's `name` is used as the lookup
+   * key when calling `Biref.scan(name)`. Its optional `urlSchemes` are
+   * used by `Biref.scanByUrl(url)`.
+   */
+  withAdapter(adapter) {
+    this.pending.push(adapter);
+    return this;
+  }
+  /** Convenience for registering multiple adapters in one call. */
+  withAdapters(...adapters) {
+    for (const adapter of adapters) {
+      this.pending.push(adapter);
+    }
+    return this;
+  }
+  /**
+   * Materialize the builder into a `Biref` facade. Throws if any
+   * adapter has a duplicate name.
+   */
+  build() {
+    const registry = new AdapterRegistry();
+    for (const adapter of this.pending) {
+      registry.register(adapter);
+    }
+    return new Biref(registry);
+  }
+};
+function parseUrlScheme(url) {
+  const match = /^([a-zA-Z][a-zA-Z0-9+.-]*):/.exec(url);
+  if (!match?.[1]) {
+    throw new Error(`Cannot determine driver scheme from URL: "${url}"`);
+  }
+  return match[1].toLowerCase();
+}
+
+// src/core/Scanner.ts
+var Scanner = class {
+  constructor(registry) {
+    this.registry = registry;
+  }
+  registry;
+  /**
+   * Scan a data store using the named adapter and return a paradigm-
+   * neutral `DataModel`.
+   */
+  async scan(adapterName, options) {
+    return this.registry.get(adapterName).introspector.introspect(options);
+  }
+};
+
+// src/output/CsvFormatter.ts
+var CsvFormatter = class {
+  constructor(options = {}) {
+    this.options = options;
+  }
+  options;
+  format = "csv";
+  contentType = "text/csv";
+  serialize(records, options) {
+    const delimiter = this.options.delimiter ?? ",";
+    const lineTerminator = this.options.lineTerminator ?? "\n";
+    const includeHeader = this.options.includeHeader ?? true;
+    const fields = this.resolveFields(records, options);
+    if (fields.length === 0) {
+      return "";
+    }
+    const lines = [];
+    if (includeHeader) {
+      lines.push(fields.map((f) => this.escape(f, delimiter)).join(delimiter));
+    }
+    for (const record of records) {
+      const cells = fields.map(
+        (field) => this.serializeCell(record[field], delimiter)
+      );
+      lines.push(cells.join(delimiter));
+    }
+    return lines.join(lineTerminator);
+  }
+  resolveFields(records, options) {
+    if (options?.fields && options.fields.length > 0) {
+      return options.fields;
+    }
+    const first = records[0];
+    return first ? Object.keys(first) : [];
+  }
+  serializeCell(value, delimiter) {
+    if (value === null || value === void 0) {
+      return "";
+    }
+    if (value instanceof Date) {
+      return this.escape(value.toISOString(), delimiter);
+    }
+    if (typeof value === "bigint") {
+      return this.escape(value.toString(), delimiter);
+    }
+    if (typeof value === "object") {
+      return this.escape(JSON.stringify(value), delimiter);
+    }
+    return this.escape(String(value), delimiter);
+  }
+  escape(value, delimiter) {
+    if (value.includes(delimiter) || value.includes('"') || value.includes("\n") || value.includes("\r")) {
+      return `"${value.replace(/"/g, '""')}"`;
+    }
+    return value;
+  }
+};
+
+// src/output/JsonFormatter.ts
+var JsonFormatter = class _JsonFormatter {
+  constructor(options = {}) {
+    this.options = options;
+  }
+  options;
+  format = "json";
+  contentType = "application/json";
+  serialize(records) {
+    const indent2 = this.options.pretty ? 2 : void 0;
+    return JSON.stringify(records, _JsonFormatter.replacer, indent2);
+  }
+  static replacer(_key, value) {
+    if (value instanceof Date) {
+      return value.toISOString();
+    }
+    if (typeof value === "bigint") {
+      return value.toString();
+    }
+    return value;
+  }
+};
+
+// src/output/RawFormatter.ts
+var RawFormatter = class {
+  format = "raw";
+  contentType = "application/javascript";
+  serialize(records) {
+    return records;
+  }
+};
+
+export { AdapterRegistry, Biref, BirefBuilder, ChainBuilder, CsvFormatter, DataModel, DefaultRecordParser, JsonFormatter, POSTGRES_ADAPTER_NAME, POSTGRES_URL_SCHEMES, PostgresIntrospector, PostgresQueryEngine, PostgresRecordParser, QueryPlanExecutor, RawFormatter, Scanner, generateSchema, generateSchemaFiles, isPostgresAdapter, overridesScaffold, postgresAdapter, tsTypeFor };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map