@danceroutine/tango-orm 1.11.1 → 1.11.2

package/dist/QuerySetState-CjyvAUBs.d.ts

@@ -0,0 +1,1310 @@
+import { t as DBClient } from "./DBClient-DuYcXolQ.js";
+import { i as Dialect, t as Adapter } from "./Adapter-DKxAaL4l.js";
+import { SqlSafetyEngine } from "@danceroutine/tango-core";
+import { z } from "zod";
+import { Model, PersistedModelOutput } from "@danceroutine/tango-schema/domain";
+import { DecoratedFieldKind, InternalDecoratedFieldKind, RelationDecoratedSchema } from "@danceroutine/tango-schema/model";
+
+//#region src/query/domain/QueryResult.d.ts
+/**
+ * Values materialized by {@link QuerySet.fetch}, iterable like an array plus `length`, `map`, `at`, and `toArray`.
+ *
+ * Prefer iteration or `items` over the deprecated `results` getter, which warns once per process when accessed.
+ */
+declare class QueryResult<T> implements Iterable<T> {
+  static readonly BRAND: "tango.orm.query_result";
+  readonly __tangoBrand: typeof QueryResult.BRAND;
+  readonly items: readonly T[];
+  constructor(items: readonly T[]);
+  /**
+   * Runtime narrowing for values that may be a plain array or a `QueryResult` instance.
+   */
+  static isQueryResult<T>(value: unknown): value is QueryResult<T>;
+  /**
+   * Sync iteration over materialized rows.
+   */
+  [Symbol.iterator](): Iterator<T>;
+  /** Number of materialized rows. */
+  get length(): number;
+  /** Same as `Array#map` on the materialized rows. */
+  map<U>(callbackfn: (value: T, index: number, array: readonly T[]) => U, thisArg?: unknown): U[];
+  /** Indexed read with support for negative indices, like `Array#at`. */
+  at(index: number): T | undefined;
+  /** Returns a shallow copy of the materialized rows as a plain array. */
+  toArray(): T[];
+  /**
+   * @deprecated Use iteration, `length`, `map`, or `toArray()` instead.
+   */
+  get results(): readonly T[];
+}
+//#endregion
+//#region src/query/domain/internal/InternalRelationKind.d.ts
+declare const InternalRelationKind: {
+  readonly HAS_MANY: "hasMany";
+  readonly BELONGS_TO: "belongsTo";
+  readonly HAS_ONE: "hasOne";
+  readonly MANY_TO_MANY: "manyToMany";
+};
+//#endregion
+//#region src/query/domain/TableMeta.d.ts
+/**
+ * SQL-facing model metadata visible to the ORM layer.
+ */
+interface TableMeta {
+  /** Stable model key when the table comes from a registered Tango model. */
+  modelKey?: string;
+  /** Physical table name used in compiled SQL. */
+  table: string;
+  /** Primary key column name. */
+  pk: string;
+  /** Base columns and their storage types. */
+  columns: Record<string, string>;
+  /** Relation metadata keyed by public relation name. */
+  relations?: Record<string, RelationMeta>;
+}
+//#endregion
+//#region src/query/compiler/QueryCompiler.d.ts
+/**
+ * Compiles immutable `QuerySet` state into parameterized SQL and recursive
+ * hydration execution artifacts.
+ */
+declare class QueryCompiler {
+  private meta;
+  private adapter;
+  static readonly BRAND: "tango.orm.query_compiler";
+  readonly __tangoBrand: typeof QueryCompiler.BRAND;
+  private readonly placeholders;
+  constructor(meta: TableMeta, adapter: Adapter);
+  static isQueryCompiler(value: unknown): value is QueryCompiler;
+  compile<T, TSourceModel = unknown>(state: QuerySetState<T, TSourceModel>): CompiledQuery;
+  compilePrefetch(node: CompiledHydrationNode, sourceValues: readonly (string | number)[]): CompiledPrefetchQuery;
+  compileManyToManyTargets(node: CompiledHydrationNode, targetIds: readonly (string | number)[]): {
+    sql: string;
+    params: readonly unknown[];
+  };
+  private compileManyToManyPrefetch;
+  private compileHydrationNode;
+  private validateHydrationRelation;
+  private buildRootHiddenSelects;
+  private validatePrefetchTarget;
+  private collectNestedJoinSql;
+  private validatePrefetchJoinTarget;
+  private validateInternalAlias;
+  private buildJoinAlias;
+  private buildPrefetchBaseAlias;
+  private buildHydrationColumnAlias;
+  private buildPrefetchSourceAlias;
+  private buildFilterAlias;
+  private sanitizeRelationPath;
+  private assertInternalAliasDoesNotCollide;
+  private compileQNode;
+  private compileAtom;
+  private compileAnd;
+  private compileOr;
+  private compileNot;
+  private compileRelationFilter;
+  private buildRelationFilterExists;
+  private lookupToSQL;
+  private normalizeParam;
+  private collectStateFilterKeys;
+  private collectNodeFilterKeys;
+}
+declare namespace index_d_exports$2 {
+  export { QueryCompiler };
+}
+//#endregion
+//#region src/query/domain/internal/InternalLookupType.d.ts
+declare const InternalLookupType: {
+  readonly EXACT: "exact";
+  readonly LT: "lt";
+  readonly LTE: "lte";
+  readonly GT: "gt";
+  readonly GTE: "gte";
+  readonly IN: "in";
+  readonly ISNULL: "isnull";
+  readonly CONTAINS: "contains";
+  readonly ICONTAINS: "icontains";
+  readonly STARTSWITH: "startswith";
+  readonly ISTARTSWITH: "istartswith";
+  readonly ENDSWITH: "endswith";
+  readonly IENDSWITH: "iendswith";
+};
+//#endregion
+//#region src/query/domain/LookupType.d.ts
+type LookupType = (typeof InternalLookupType)[keyof typeof InternalLookupType];
+//#endregion
+//#region src/query/domain/FilterKey.d.ts
+type ScalarFilterKey<T> = Extract<keyof T, string> | `${Extract<keyof T, string>}__${LookupType}`;
+type FilterKey<T, _TSourceModel = unknown> = ScalarFilterKey<T> | string;
+//#endregion
+//#region src/query/domain/FilterValue.d.ts
+type FilterValue = string | number | boolean | Date | null | undefined | Array<string | number>;
+//#endregion
+//#region src/query/domain/FilterInput.d.ts
+type FilterInput<T, TSourceModel = unknown> = Partial<Record<FilterKey<T, TSourceModel>, FilterValue>>;
+//#endregion
+//#region src/query/domain/internal/InternalQNodeType.d.ts
+declare const InternalQNodeType: {
+  readonly ATOM: "atom";
+  readonly AND: "and";
+  readonly OR: "or";
+  readonly NOT: "not";
+};
+//#endregion
+//#region src/query/domain/QNode.d.ts
+type QNodeType = (typeof InternalQNodeType)[keyof typeof InternalQNodeType];
+interface QNode<T, TSourceModel = unknown> {
+  kind: QNodeType;
+  where?: FilterInput<T, TSourceModel>;
+  nodes?: QNode<T, TSourceModel>[];
+  node?: QNode<T, TSourceModel>;
+}
+//#endregion
+//#region src/query/domain/OrderToken.d.ts
+type OrderToken<T> = keyof T | `-${string & keyof T}`;
+//#endregion
+//#region src/query/QuerySet.d.ts
+/**
+ * Query execution seam consumed by `QuerySet`.
+ *
+ * Application code usually reaches this through `Model.objects` or testing
+ * fixtures rather than implementing it directly.
+ *
+ * @template TModel - The model row type returned by the database client
+ */
+interface QueryExecutor<TModel> {
+  meta: TableMeta;
+  client: DBClient;
+  adapter: Adapter;
+  run(compiled: CompiledQuery): Promise<TModel[]>;
+  /**
+   * Optional hook invoked by `QuerySet` after a record has been
+   * materialized so executors can attach related-manager accessors
+   * (such as the many-to-many related manager) onto the record.
+   *
+   * The optional `modelKey` argument lets the executor route the attach
+   * call to the correct model when the record belongs to a related
+   * model rather than the executor's own source model. Implementations
+   * must not overwrite existing properties on the record so prior
+   * hydration assignments survive the attach pass.
+   */
+  attachPersistedRecordAccessors?(record: Record<string, unknown>, modelKey?: string): void;
+}
+type QueryShapeFunction<TInput, TOutput> = (row: TInput) => TOutput;
+type QueryShapeParser<TInput, TOutput> = {
+  parse: (row: TInput) => TOutput;
+};
+type QueryShape<TInput> = QueryShapeFunction<TInput, unknown> | QueryShapeParser<TInput, unknown>;
+type QueryShapeOutput<TInput, TShape> = TShape extends QueryShapeFunction<TInput, infer TOutput> ? TOutput : TShape extends QueryShapeParser<TInput, infer TOutput> ? TOutput : never;
+type ProjectedResult<TModel extends Record<string, unknown>, TKeys extends readonly (keyof TModel)[]> = number extends TKeys['length'] ? TModel : [TKeys[number]] extends [never] ? TModel : Pick<TModel, TKeys[number]>;
+/**
+ * Django-inspired query builder for constructing and executing database queries.
+ * Provides a fluent API for filtering, ordering, pagination, projection, and
+ * nested relation hydration.
+ *
+ * @template TModel - The full model row type used for query composition
+ * @template TBaseResult - The selected base-row shape returned by execution methods
+ * @template TSourceModel - The source Tango model used for typed relation metadata
+ * @template THydrated - Relation properties accumulated by eager-loading calls
+ *
+ * @example
+ * ```typescript
+ * const users = await TodoModel.objects
+ *   .query()
+ *   .filter({ active: true })
+ *   .filter(Q.or({ role: 'admin' }, { role: 'moderator' }))
+ *   .orderBy('-createdAt')
+ *   .limit(10)
+ *   .fetch();
+ * ```
+ */
+declare abstract class QuerySet<TModel extends Record<string, unknown>, TBaseResult extends Record<string, unknown> = TModel, TSourceModel = unknown, THydrated extends Record<string, unknown> = Record<never, never>> implements AsyncIterable<HydratedQueryResult<TBaseResult, THydrated>> {
+  protected executor: QueryExecutor<TModel>;
+  protected state: QuerySetState<TModel, TSourceModel>;
+  static readonly BRAND: "tango.orm.query_set";
+  readonly __tangoBrand: typeof QuerySet.BRAND;
+  private evaluationCache?;
+  constructor(executor: QueryExecutor<TModel>, state?: QuerySetState<TModel, TSourceModel>);
+  /**
+   * Create another queryset of the same runtime family with the supplied
+   * query state. Concrete subclasses implement this so fluent calls keep
+   * their subclass-specific execution behavior instead of falling back to
+   * the standard queryset implementation.
+   */
+  protected abstract spawn<TNextBaseResult extends Record<string, unknown> = TBaseResult, TNextHydrated extends Record<string, unknown> = THydrated>(state: QuerySetState<TModel, TSourceModel>): QuerySet<TModel, TNextBaseResult, TSourceModel, TNextHydrated>;
+  /**
+   * Narrow an unknown value to `QuerySet`.
+   */
+  static isQuerySet<TModel extends Record<string, unknown>, TResult extends Record<string, unknown> = TModel>(value: unknown): value is QuerySet<TModel, TResult>;
+  /**
+   * Translate user-facing order tokens like `'name'` or `'-createdAt'` into
+   * the internal `OrderSpec` array used by `QuerySetState`.
+   *
+   * Exposed as `protected` so subclasses can compose the same parse logic
+   * when they need to return their own concrete type from `orderBy` without
+   * reaching into a base-class instance's protected state.
+   */
+  protected static buildOrderSpecs<T extends Record<string, unknown>>(tokens: readonly OrderToken<T>[]): OrderSpec<T>[];
+  private static invertOrderSpec;
+  /**
+   * Add a filter expression to the query.
+   *
+   * Multiple `filter()` calls are composed with `AND`.
+   */
+  filter(q: FilterInput<TModel, TSourceModel> | QNode<TModel, TSourceModel>): QuerySet<TModel, TBaseResult, TSourceModel, THydrated>;
+  /**
+   * Add an exclusion expression to the query.
+   *
+   * Exclusions are translated to `NOT (...)` predicates.
+   */
+  exclude(q: FilterInput<TModel, TSourceModel> | QNode<TModel, TSourceModel>): QuerySet<TModel, TBaseResult, TSourceModel, THydrated>;
+  /**
+   * Apply ordering tokens such as `'name'` or `'-createdAt'`.
+   */
+  orderBy(...tokens: OrderToken<TModel>[]): QuerySet<TModel, TBaseResult, TSourceModel, THydrated>;
+  /**
+   * Limit the maximum number of rows returned.
+   */
+  limit(n: number): QuerySet<TModel, TBaseResult, TSourceModel, THydrated>;
+  /**
+   * Skip the first `n` rows.
+   */
+  offset(n: number): QuerySet<TModel, TBaseResult, TSourceModel, THydrated>;
+  /**
+   * Restrict selected fields and narrow the fetched row type when the
+   * selected keys are known precisely at the call site.
+   *
+   * Empty selections reset back to the full model row, and repeated
+   * `select(...)` calls replace the previous projection rather than
+   * intersecting it.
+   */
+  select<const TKeys extends readonly (keyof TModel)[]>(fields: TKeys): QuerySet<TModel, ProjectedResult<TModel, TKeys>, TSourceModel, THydrated>;
+  select(fields: readonly (keyof TModel)[]): QuerySet<TModel, ProjectedResult<TModel, readonly (keyof TModel)[]>, TSourceModel, THydrated>;
+  /**
+   * Hydrate single-valued relation paths through SQL joins.
+   *
+   * Forward `belongsTo` relations can be inferred from the source model's
+   * field-authored relation metadata. Reverse `hasOne` relations can be
+   * selected with a target model generic when the target model points back to
+   * the source model. Generated relation typing also enables nested `__`
+   * path keys for applications that keep the app-local registry current.
+   */
+  selectRelated<TTargetModel = undefined, const TRelationName extends RelationKeys<SelectRelatedRelations<TSourceModel, NoInfer<TTargetModel>>> | GeneratedSelectRelatedPathKeys<TSourceModel> = RelationKeys<SelectRelatedRelations<TSourceModel, NoInfer<TTargetModel>>> | GeneratedSelectRelatedPathKeys<TSourceModel>>(...rels: readonly TRelationName[]): QuerySet<TModel, TBaseResult, TSourceModel, THydrated & MaybeHydratedRelationMap<TSourceModel, SelectRelatedRelations<TSourceModel, NoInfer<TTargetModel>>, Extract<TRelationName, RelationKeys<SelectRelatedRelations<TSourceModel, NoInfer<TTargetModel>>>>, SingleRelationHydrationCardinality> & GeneratedHydratedRelationMap<TSourceModel, Extract<TRelationName, GeneratedSelectRelatedPathKeys<TSourceModel>>>>;
+  /**
+   * Hydrate collection-rooted relation paths with follow-up queries.
+   *
+   * Reverse `hasMany` relations can be prefetched with a target model generic
+   * when the target model points back to the source model. Generated relation
+   * typing also enables nested `__` path keys for applications that keep the
+   * app-local registry current.
+   */
+  prefetchRelated<TTargetModel = undefined, const TRelationName extends RelationKeys<PrefetchRelatedRelations<TSourceModel, NoInfer<TTargetModel>>> | GeneratedPrefetchRelatedPathKeys<TSourceModel> = RelationKeys<PrefetchRelatedRelations<TSourceModel, NoInfer<TTargetModel>>> | GeneratedPrefetchRelatedPathKeys<TSourceModel>>(...rels: readonly TRelationName[]): QuerySet<TModel, TBaseResult, TSourceModel, THydrated & MaybeHydratedRelationMap<TSourceModel, PrefetchRelatedRelations<TSourceModel, NoInfer<TTargetModel>>, Extract<TRelationName, RelationKeys<PrefetchRelatedRelations<TSourceModel, NoInfer<TTargetModel>>>>, ManyRelationHydrationCardinality> & GeneratedHydratedRelationMap<TSourceModel, Extract<TRelationName, GeneratedPrefetchRelatedPathKeys<TSourceModel>>>>;
+  all(): QuerySet<TModel, TBaseResult, TSourceModel, THydrated>;
+  /**
+   * Execute the query and optionally shape each row.
+   *
+   * When the queryset has been narrowed by `select(...)`, rows passed to the
+   * shaping callback or parser use that narrowed fetched-row type.
+   */
+  fetch(): Promise<QueryResult<HydratedQueryResult<TBaseResult, THydrated>>>;
+  fetch<Out>(shape: QueryShapeFunction<HydratedQueryResult<TBaseResult, THydrated>, Out>): Promise<QueryResult<Out>>;
+  fetch<Out>(shape: QueryShapeParser<HydratedQueryResult<TBaseResult, THydrated>, Out>): Promise<QueryResult<Out>>;
+  fetch<TShape extends QueryShape<HydratedQueryResult<TBaseResult, THydrated>> | undefined>(shape: TShape): Promise<QueryResult<HydratedQueryResult<TBaseResult, THydrated> | QueryShapeOutput<HydratedQueryResult<TBaseResult, THydrated>, NonNullable<TShape>>>>;
+  /**
+   * Async iterable surface for `for await (... of queryset)`.
+   *
+   * Evaluates this queryset on first use by awaiting `fetch()` without
+   * arguments, then yields each element from that materialized result.
+   * Later async iterations over the same queryset instance reuse the cached
+   * materialized result instead of issuing another database round-trip.
+   */
+  [Symbol.asyncIterator](): AsyncIterator<HydratedQueryResult<TBaseResult, THydrated>>;
+  /**
+   * Execute the query and return the first row, or `null`.
+   *
+   * As with `fetch(...)`, parser and function overloads receive the current
+   * fetched-row type after any `select(...)` projection narrowing.
+   */
+  fetchOne(): Promise<HydratedQueryResult<TBaseResult, THydrated> | null>;
+  fetchOne<Out>(shape: QueryShapeFunction<HydratedQueryResult<TBaseResult, THydrated>, Out>): Promise<Out | null>;
+  fetchOne<Out>(shape: QueryShapeParser<HydratedQueryResult<TBaseResult, THydrated>, Out>): Promise<Out | null>;
+  fetchOne<TShape extends QueryShape<HydratedQueryResult<TBaseResult, THydrated>> | undefined>(shape: TShape): Promise<HydratedQueryResult<TBaseResult, THydrated> | QueryShapeOutput<HydratedQueryResult<TBaseResult, THydrated>, NonNullable<TShape>> | null>;
+  first(): Promise<HydratedQueryResult<TBaseResult, THydrated> | null>;
+  first<Out>(shape: QueryShapeFunction<HydratedQueryResult<TBaseResult, THydrated>, Out>): Promise<Out | null>;
+  first<Out>(shape: QueryShapeParser<HydratedQueryResult<TBaseResult, THydrated>, Out>): Promise<Out | null>;
+  last(): Promise<HydratedQueryResult<TBaseResult, THydrated> | null>;
+  last<Out>(shape: QueryShapeFunction<HydratedQueryResult<TBaseResult, THydrated>, Out>): Promise<Out | null>;
+  last<Out>(shape: QueryShapeParser<HydratedQueryResult<TBaseResult, THydrated>, Out>): Promise<Out | null>;
+  get(q: FilterInput<TModel, TSourceModel> | QNode<TModel, TSourceModel>): Promise<HydratedQueryResult<TBaseResult, THydrated>>;
+  get<Out>(q: FilterInput<TModel, TSourceModel> | QNode<TModel, TSourceModel>, shape: QueryShapeFunction<HydratedQueryResult<TBaseResult, THydrated>, Out>): Promise<Out>;
+  get<Out>(q: FilterInput<TModel, TSourceModel> | QNode<TModel, TSourceModel>, shape: QueryShapeParser<HydratedQueryResult<TBaseResult, THydrated>, Out>): Promise<Out>;
+  /**
+   * Execute a `COUNT(*)` query for the current filtered state.
+   */
+  count(): Promise<number>;
+  /**
+   * Return whether at least one row matches the current query state.
+   */
+  exists(): Promise<boolean>;
+  private shapeFetchedRow;
+  private getOrCreateEvaluationCache;
+  private evaluateRows;
+  private normalizeRowsForSchemaParsing;
+  private normalizeHydratedRowsForParserShape;
+  private hydrateRows;
+  private primeManyToManyOwnerCache;
+  private attachRootRecordAccessors;
+  private hydrateJoinNodesForOwner;
+  private hydratePrefetchNode;
+  private chunkValues;
+  private groupOwnersByAccessor;
+  private canonicalizeEntity;
+  private normalizeTargetRow;
+  private normalizeColumnValue;
+  private isBooleanColumnType;
+  private normalizeSqliteBoolean;
+  private normalizeBooleanColumns;
+  private withoutHydrationState;
+}
+//#endregion
+//#region src/query/ModelQuerySet.d.ts
+/**
+ * Concrete `QuerySet` implementation returned by `Model.objects.query()`.
+ *
+ * It executes the accumulated queryset state directly against the bound
+ * model executor.
+ */
+declare class ModelQuerySet<TModel extends Record<string, unknown>, TBaseResult extends Record<string, unknown> = TModel, TSourceModel = unknown, THydrated extends Record<string, unknown> = Record<never, never>> extends QuerySet<TModel, TBaseResult, TSourceModel, THydrated> {
+  constructor(executor: QueryExecutor<TModel>, state?: QuerySetState<TModel, TSourceModel>);
+  protected spawn<TNextBaseResult extends Record<string, unknown> = TBaseResult, TNextHydrated extends Record<string, unknown> = THydrated>(state: QuerySetState<TModel, TSourceModel>): ModelQuerySet<TModel, TNextBaseResult, TSourceModel, TNextHydrated>;
+}
+//#endregion
+//#region src/query/QBuilder.d.ts
+/**
+ * Static builder for composing boolean query expressions.
+ *
+ * This mirrors Django's `Q(...)` composition patterns and is intended
+ * for ergonomic construction of nested `AND`/`OR`/`NOT` trees.
+ */
+declare class QBuilder {
+  static readonly BRAND: "tango.orm.q_builder";
+  readonly __tangoBrand: typeof QBuilder.BRAND;
+  /**
+   * Narrow an unknown value to `QBuilder`.
+   */
+  static isQBuilder(value: unknown): value is QBuilder;
+  /**
+   * Combine multiple filter fragments using logical `AND`.
+   */
+  static and<T, TSourceModel = unknown>(...nodes: Array<FilterInput<T, TSourceModel> | QNode<T, TSourceModel>>): QNode<T, TSourceModel>;
+  /**
+   * Combine multiple filter fragments using logical `OR`.
+   */
+  static or<T, TSourceModel = unknown>(...nodes: Array<FilterInput<T, TSourceModel> | QNode<T, TSourceModel>>): QNode<T, TSourceModel>;
+  /**
+   * Negate a filter fragment using logical `NOT`.
+   */
+  static not<T, TSourceModel = unknown>(node: FilterInput<T, TSourceModel> | QNode<T, TSourceModel>): QNode<T, TSourceModel>;
+  private static wrapNode;
+}
+declare namespace index_d_exports$1 {
+  export { CompiledQuery, Dialect, Direction, FilterInput, FilterKey, FilterValue, ForwardSingleRelations, GeneratedHydratedRelationMap, GeneratedPrefetchRelatedPathKeys, GeneratedRelationFilterKeys, GeneratedSelectRelatedPathKeys, HydratedQueryResult, HydratedRelationMap, InternalRelationHydrationCardinality, LookupType, ManyRelationHydrationCardinality, MaybeHydratedRelationMap, ModelQuerySet, OrderSpec, OrderToken, PrefetchRelatedRelations, QBuilder as Q, QBuilder, QNode, QueryCompiler, QueryExecutor, QueryResult, QuerySet, QuerySetState, RelationHydrationCardinality, RelationKeys, RelationMeta, ReverseCollectionRelations, ReverseSingleRelations, SelectRelatedRelations, SingleRelationHydrationCardinality, TableMeta, TableMetaFactory, WhereClause, index_d_exports$2 as compiler, index_d_exports as domain };
+}
+//#endregion
+//#region src/validation/internal/InternalSqlValidationPlanKind.d.ts
+/**
+ * Discriminator strings for {@link SqlValidationPlan} / {@link ValidatedSqlPlan}: which validation
+ * branch {@link OrmSqlSafetyAdapter} runs before SQL is assembled or executed.
+ */
+declare const InternalSqlValidationPlanKind: {
+  /**
+   * Read/query validation: table metadata, projected columns, `WHERE` filter keys, ordering, and
+   * optional relation handles. Used when compiling selects (including M2M through-table selects
+   * issued inside prefetch compilation).
+   */
+  readonly SELECT: "select";
+  /**
+   * Insert validation: resolved write columns for `INSERT … VALUES`.
+   */
+  readonly INSERT: "insert";
+  /**
+   * Update validation: resolved write columns for `UPDATE … SET`.
+   */
+  readonly UPDATE: "update";
+  /**
+   * Delete validation: scope delete-by-primary-key against validated table metadata.
+   */
+  readonly DELETE: "delete";
+};
+//#endregion
+//#region src/validation/SqlValidationPlan.d.ts
+/**
+ * Validation request for read/query compilation.
+ *
+ * The ORM uses this plan to validate selected fields, filter keys, ordering,
+ * and relation names before SQL is assembled.
+ */
+type SelectSqlValidationPlan = {
+  kind: typeof InternalSqlValidationPlanKind.SELECT;
+  meta: TableMeta;
+  selectFields?: readonly string[];
+  filterKeys?: readonly string[];
+  orderFields?: readonly string[];
+  relationNames?: readonly string[];
+};
+/**
+ * Validation request for insert statements.
+ */
+type InsertSqlValidationPlan = {
+  kind: typeof InternalSqlValidationPlanKind.INSERT;
+  meta: TableMeta;
+  writeKeys: readonly string[];
+};
+/**
+ * Validation request for update statements.
+ */
+type UpdateSqlValidationPlan = {
+  kind: typeof InternalSqlValidationPlanKind.UPDATE;
+  meta: TableMeta;
+  writeKeys: readonly string[];
+};
+/**
+ * Validation request for delete statements.
+ */
+type DeleteSqlValidationPlan = {
+  kind: typeof InternalSqlValidationPlanKind.DELETE;
+  meta: TableMeta;
+};
+/**
+ * ORM-local SQL validation requests routed through `OrmSqlSafetyAdapter`.
+ */
+type SqlValidationPlan = SelectSqlValidationPlan | InsertSqlValidationPlan | UpdateSqlValidationPlan | DeleteSqlValidationPlan;
+//#endregion
+//#region src/validation/internal/InternalValidatedFilterDescriptorKind.d.ts
+declare const InternalValidatedFilterDescriptorKind: {
+  readonly COLUMN: "column";
+  readonly RELATION: "relation";
+};
+//#endregion
+//#region src/validation/SQLValidationEngine.d.ts
+type ValidatedRelationMeta = RelationMeta & {
+  table: string;
+  alias: string;
+  sourceKey: string;
+  targetKey: string;
+  targetPrimaryKey: string;
+  targetColumns: Record<string, string>;
+  throughTable?: string;
+  throughSourceKey?: string;
+  throughTargetKey?: string;
+};
+type ValidatedTableMeta = {
+  table: string;
+  pk: string;
+  columns: Record<string, string>;
+  relations?: Record<string, ValidatedRelationMeta>;
+};
+type ValidatedColumnFilterDescriptor = {
+  kind: typeof InternalValidatedFilterDescriptorKind.COLUMN;
+  rawKey: string;
+  field: string;
+  lookup: LookupType;
+  qualifiedColumn: string;
+};
+type ValidatedRelationFilterDescriptor = {
+  kind: typeof InternalValidatedFilterDescriptorKind.RELATION;
+  rawKey: string;
+  field: string;
+  lookup: LookupType;
+  relationPath: string;
+  relationChain: ValidatedRelationMeta[];
+  terminalColumn: string;
+};
+type ValidatedFilterDescriptor = ValidatedColumnFilterDescriptor | ValidatedRelationFilterDescriptor;
+type ValidatedSelectSqlPlan = {
+  kind: typeof InternalSqlValidationPlanKind.SELECT;
+  meta: ValidatedTableMeta;
+  selectFields: Record<string, string>;
+  filterKeys: Record<string, ValidatedFilterDescriptor>;
+  orderFields: Record<string, string>;
+  relations: Record<string, ValidatedRelationMeta>;
+};
+type ValidatedInsertSqlPlan = {
+  kind: typeof InternalSqlValidationPlanKind.INSERT;
+  meta: ValidatedTableMeta;
+  writeKeys: string[];
+};
+type ValidatedUpdateSqlPlan = {
+  kind: typeof InternalSqlValidationPlanKind.UPDATE;
+  meta: ValidatedTableMeta;
+  writeKeys: string[];
+};
+type ValidatedDeleteSqlPlan = {
+  kind: typeof InternalSqlValidationPlanKind.DELETE;
+  meta: ValidatedTableMeta;
+};
+type ValidatedSqlPlan = ValidatedSelectSqlPlan | ValidatedInsertSqlPlan | ValidatedUpdateSqlPlan | ValidatedDeleteSqlPlan;
+interface SQLValidationEngine {
+  validate(plan: SelectSqlValidationPlan): ValidatedSelectSqlPlan;
+  validate(plan: InsertSqlValidationPlan): ValidatedInsertSqlPlan;
+  validate(plan: UpdateSqlValidationPlan): ValidatedUpdateSqlPlan;
+  validate(plan: DeleteSqlValidationPlan): ValidatedDeleteSqlPlan;
+  validate(plan: SqlValidationPlan): ValidatedSqlPlan;
+}
+//#endregion
+//#region src/validation/OrmSqlSafetyAdapter.d.ts
+/**
+ * ORM-local adapter that translates query validation plans into the
+ * shared Tango SQL safety engine.
+ */
+declare class OrmSqlSafetyAdapter implements SQLValidationEngine {
+  private readonly engine;
+  static readonly BRAND: "tango.orm.orm_sql_safety_adapter";
+  readonly __tangoBrand: typeof OrmSqlSafetyAdapter.BRAND;
+  constructor(engine?: SqlSafetyEngine);
+  validate(plan: SelectSqlValidationPlan): ValidatedSelectSqlPlan;
+  validate(plan: InsertSqlValidationPlan): ValidatedInsertSqlPlan;
+  validate(plan: UpdateSqlValidationPlan): ValidatedUpdateSqlPlan;
+  validate(plan: DeleteSqlValidationPlan): ValidatedDeleteSqlPlan;
+  private validateTableMeta;
+  private validateRelationMeta;
+  private validateFilterKey;
+  private resolveColumn;
+  private resolveRelation;
+}
+//#endregion
+//#region src/manager/internal/MutationCompiler.d.ts
+declare const InternalDuplicateInsertPolicy: {
+  readonly ERROR: "error";
+  readonly IGNORE: "ignore";
+};
+type DuplicateInsertPolicy = (typeof InternalDuplicateInsertPolicy)[keyof typeof InternalDuplicateInsertPolicy];
+/**
+ * Internal compiler for manager-owned INSERT/UPDATE/DELETE statements.
+ */
+declare class MutationCompiler {
+  private readonly adapter;
+  private readonly placeholders;
+  constructor(adapter: Adapter);
+  compileInsert(plan: ValidatedInsertSqlPlan, values: readonly unknown[]): CompiledQuery;
+  compileUpdate(plan: ValidatedUpdateSqlPlan, values: readonly unknown[], id: unknown): CompiledQuery;
+  compileDelete(plan: ValidatedDeleteSqlPlan, id: unknown): CompiledQuery;
+  compileDeleteByJoinKeys(plan: ValidatedSelectSqlPlan, leftFilterKey: string, rightFilterKey: string, leftValue: unknown, rightValue: unknown): CompiledQuery;
+  compileBulkInsert(plan: ValidatedInsertSqlPlan, valueRows: ReadonlyArray<ReadonlyArray<unknown>>): CompiledQuery;
+  compileInsertJoinLinks(plan: ValidatedInsertSqlPlan, sourceKey: string, targetKey: string, ownerValue: unknown, targetValues: readonly unknown[], duplicatePolicy: DuplicateInsertPolicy): CompiledQuery;
+  compileDeleteJoinLinks(plan: ValidatedSelectSqlPlan, leftFilterKey: string, rightFilterKey: string, leftValue: unknown, rightValues: readonly unknown[]): CompiledQuery;
+}
+//#endregion
+//#region src/manager/relations/internal/ThroughTableManager.d.ts
+/**
+ * Resolved through-table descriptor used by {@link ThroughTableManager}. The
+ * descriptor is derived once from a relation edge plus its through-model
+ * metadata, then reused for every link insert, delete, and read.
+ */
+interface ThroughTableLinkDescriptor {
+  /** Physical join-table name validated against SQL identifier safety rules. */
+  table: string;
+  /** Primary-key column name on the join table. */
+  primaryKey: string;
+  /** Full column map for the join table, used by the SQL safety adapter. */
+  columns: Record<string, string>;
+  /** Join-table column that stores the owner-side primary-key value. */
+  sourceColumn: string;
+  /** Join-table column that stores the target-side primary-key value. */
+  targetColumn: string;
+}
+/**
+ * Inputs accepted by {@link ThroughTableManager.fromRelation}.
+ */
+interface ThroughTableManagerFromRelationInputs {
+  relation: NonNullable<TableMeta['relations']>[string];
+  throughModelFields: ReadonlyArray<{
+    name: string;
+    type: string;
+    primaryKey?: boolean;
+  }>;
+  client: DBClient;
+  mutationCompiler: MutationCompiler;
+  adapter: Adapter;
+  sqlSafetyAdapter: OrmSqlSafetyAdapter;
+}
+interface InsertLinkOptions {
+  onDuplicate?: DuplicateInsertPolicy;
+}
+/**
+ * Internal helper that issues the INSERT, DELETE, and SELECT statements for
+ * a single many-to-many join table. Centralizes SQL safety validation and
+ * compilation so {@link ManyToManyRelatedManager} implementations only deal
+ * in primary-key values.
+ */
+declare class ThroughTableManager {
+  private readonly client;
+  private readonly mutationCompiler;
+  private readonly descriptor;
+  private readonly adapter;
+  private readonly sqlSafetyAdapter;
+  constructor(client: DBClient, mutationCompiler: MutationCompiler, descriptor: ThroughTableLinkDescriptor, adapter: Adapter, sqlSafetyAdapter?: OrmSqlSafetyAdapter);
+  /**
+   * Derive a {@link ThroughTableLinkDescriptor} from the through-model
+   * metadata exposed by a many-to-many relation edge.
+   */
+  static buildLinkDescriptor(relation: NonNullable<TableMeta['relations']>[string], throughModelFields: ReadonlyArray<{
+    name: string;
+    type: string;
+    primaryKey?: boolean;
+  }>): ThroughTableLinkDescriptor;
+  /**
+   * Convenience factory that derives the join-table descriptor from the
+   * relation edge and instantiates a {@link ThroughTableManager} in one
+   * step.
+   */
+  static fromRelation(inputs: ThroughTableManagerFromRelationInputs): ThroughTableManager;
+  /**
+   * Read every target primary-key value linked to the supplied owner via
+   * the join table. Used by ManyToManyRelatedManager.all to scope
+   * follow-up target queries to the current owner.
+   */
+  selectTargetIdsForOwner(ownerPrimaryKey: unknown): Promise<readonly (string | number)[]>;
+  insertLink(ownerPrimaryKey: unknown, targetPrimaryKey: unknown, options?: InsertLinkOptions): Promise<void>;
+  insertLinks(ownerPrimaryKey: unknown, targetPrimaryKeys: readonly unknown[], options?: InsertLinkOptions): Promise<void>;
+  deleteLink(ownerPrimaryKey: unknown, targetPrimaryKey: unknown): Promise<void>;
+  deleteLinks(ownerPrimaryKey: unknown, targetPrimaryKeys: readonly unknown[]): Promise<void>;
+  /**
+   * Delete every join-table row linked to one owner record. Used by
+   * `ManyToManyRelatedManager.clear()` so the related manager can clear a
+   * relation without first loading the current target ids.
+   */
+  deleteAllLinksForOwner(ownerPrimaryKey: unknown): Promise<void>;
+}
+//#endregion
+//#region src/manager/relations/ManyToManyRelatedManager.d.ts
+/**
+ * Accepted target reference shapes for {@link ManyToManyRelatedManager.add},
+ * {@link ManyToManyRelatedManager.remove}, and
+ * {@link ManyToManyRelatedManager.set}.
+ *
+ * Application code may pass a target record, a primary-key carrier object, or
+ * a bare primary-key value.
+ *
+ * @template TTarget - The persisted target record shape.
+ */
+type ManyToManyTargetRef<TTarget extends Record<string, unknown>> = TTarget | {
+  readonly [pk: string]: unknown;
+} | string | number;
+/**
+ * Inputs accepted by the {@link ManyToManyRelatedManager.create} factory. The
+ * factory owns the wiring between relation metadata, the SQL safety adapter,
+ * and the {@link ThroughTableManager}, so callers only supply context they
+ * already have on hand.
+ */
+interface ManyToManyRelatedManagerCreateInputs<TTarget extends Record<string, unknown>> {
+  /** Persisted primary-key value of the owning record. */
+  ownerPrimaryKey: unknown;
+  /** Relation name on the owning model (for error messages). */
+  relationName: string;
+  /** Display name of the owning model (for error messages). */
+  ownerModelLabel: string;
+  /** Resolved relation edge metadata for the many-to-many relation. */
+  relation: NonNullable<TableMeta['relations']>[string];
+  /** Through-model column metadata used to derive the join-table descriptor. */
+  throughModelFields: ReadonlyArray<{
+    name: string;
+    type: string;
+    primaryKey?: boolean;
+  }>;
+  /** Runtime-bound database client shared with the owning manager. */
+  client: DBClient;
+  /** Shared {@link MutationCompiler} configured for the active dialect. */
+  mutationCompiler: MutationCompiler;
+  /** Active database adapter. Supplies placeholder formatting and dialect flags. */
+  adapter: Adapter;
+  /** SQL safety adapter shared with the owning manager. */
+  sqlSafetyAdapter: OrmSqlSafetyAdapter;
+  /** Lazy resolver returning the target model's {@link QueryExecutor}. */
+  targetExecutorProvider: () => QueryExecutor<TTarget> | null;
+  /** Model-manager-backed create path for new target records. */
+  createTarget: (input: Partial<TTarget>) => Promise<TTarget>;
+  /** Internal transaction runner used for multi-target membership writes. */
+  runAtomic: <T>(work: () => Promise<T>) => Promise<T>;
+}
+interface ManyToManyRelatedManagerInternalInputs<TTarget extends Record<string, unknown>> {
+  ownerPrimaryKey: unknown;
+  relationName: string;
+  ownerModelLabel: string;
+  targetPrimaryKeyField: string;
+  throughTableManager: ThroughTableManager;
+  targetExecutorProvider: () => QueryExecutor<TTarget> | null;
+  createTarget: (input: Partial<TTarget>) => Promise<TTarget>;
+  runAtomic: <T>(work: () => Promise<T>) => Promise<T>;
+}
+/**
+ * Django-style related manager exposed on materialized model records for each
+ * many-to-many relation.
+ *
+ * Use the manager to add or remove join-table membership and to query the
+ * related target rows. The owning record's primary key and the relation name
+ * are bound when the manager is attached, so application code does not need
+ * to pass them on every call.
+ *
+ * Prefetched memberships seed an internal cache that the queryset returned
+ * from `all()` short-circuits to without re-querying. Mutations through
+ * `add`, `remove`, `set`, `clear`, and `create` invalidate the cache so
+ * subsequent reads observe the updated membership. `set(...)` applies
+ * Django-shaped replacement semantics:
+ * it diffs the current relation membership against the supplied targets,
+ * removes any missing links, and inserts any new links inside one atomic
+ * write boundary. `clear()` removes every join row for the owner, and
+ * `create(...)` persists a new target row plus its join-row link inside one
+ * atomic boundary.
+ *
+ * @template TTarget - The persisted target record shape returned by `all()`.
+ */
+declare class ManyToManyRelatedManager<TTarget extends Record<string, unknown>> {
+  private readonly inputs;
+  private static readonly BRAND;
+  readonly __tangoBrand: typeof ManyToManyRelatedManager.BRAND;
+  private prefetchCache;
+  /**
+   * Constructor is internal. Application and ORM code must build instances
+   * through {@link ManyToManyRelatedManager.create}, which owns the wiring
+   * between relation metadata and the backing through-table mutator. The
+   * testing package exposes a fixture for unit tests that need a custom
+   * mutator.
+   */
+  constructor(inputs: ManyToManyRelatedManagerInternalInputs<TTarget>);
+  /**
+   * Narrow an unknown value to {@link ManyToManyRelatedManager}.
+   */
+  static isManyToManyRelatedManager<TTarget extends Record<string, unknown>>(value: unknown): value is ManyToManyRelatedManager<TTarget>;
+  /**
+   * Build a {@link ManyToManyRelatedManager} bound to a single owner record.
+   * The factory derives the join-table descriptor from the relation edge and
+   * through-model fields, wires a {@link ThroughTableManager} against the
+   * supplied runtime-bound client, and returns a manager whose `add`,
+   * `remove`, `clear`, `create`, and `all` methods enroll in any active
+   * `transaction.atomic(...)` boundary.
+   */
+  static create<TTarget extends Record<string, unknown>>(inputs: ManyToManyRelatedManagerCreateInputs<TTarget>): ManyToManyRelatedManager<TTarget>;
+  /**
+   * Insert join-table rows linking the owning record to the supplied
+   * targets. Duplicate links are ignored so repeated `add(...)` calls are
+   * idempotent. When multiple targets are supplied, Tango performs the
+   * membership write inside one `transaction.atomic(...)` boundary.
+   */
+  add(...targets: ManyToManyTargetRef<TTarget>[]): Promise<void>;
+  /**
+   * Delete join-table rows linking the owning record to the supplied
+   * targets. When multiple targets are supplied, Tango performs the
+   * membership write inside one `transaction.atomic(...)` boundary.
+   */
+  remove(...targets: ManyToManyTargetRef<TTarget>[]): Promise<void>;
+  /**
+   * Delete every join-table row linked to the owning record and invalidate
+   * any prefetched membership cache after the delete succeeds.
+   */
+  clear(): Promise<void>;
+  /**
+   * Create a new target record through the related model's manager and link
+   * it to the owning record inside one `transaction.atomic(...)` boundary.
+   * This preserves target-manager hooks and defaults while preventing a
+   * created target row from leaking if the join-row insert fails.
+   */
+  create(input: Partial<TTarget>): Promise<TTarget>;
+  /**
+   * Replace the current relation membership with exactly the supplied
+   * targets. Duplicate inputs are collapsed before diffing against the
+   * current through-table rows, so repeated values do not trigger extra
+   * writes. Calling `set()` with no targets clears the relation.
+   *
+   * When replacement requires writes, Tango performs the delete/insert
+   * sequence inside one `transaction.atomic(...)` boundary.
+   */
+  set(...targets: ManyToManyTargetRef<TTarget>[]): Promise<void>;
+  /**
+   * Return a {@link QuerySet} for the related target rows of this many-to-many
+   * relation. When the relation was already loaded by `prefetchRelated(...)`,
+   * the first `fetch()` resolves with the cached materialization without
+   * re-querying. Mutating the membership through `add`/`remove`/`set`/
+   * `clear`/`create` invalidates that cache.
+   */
+  all(): QuerySet<TTarget>;
+  /**
+   * Replace the prefetch cache with the supplied target rows. Called by the
+   * many-to-many prefetch path so a follow-up `all()` resolves without an
+   * extra database round-trip.
+   */
+  primePrefetchCache(targets: readonly TTarget[]): void;
+  /**
+   * Drop any cached prefetch results. Mutating helpers call this so reads
+   * after an `add`/`remove`/`set`/`clear`/`create` go back to the database.
+   */
+  invalidateCache(): void;
+  /**
+   * Snapshot of the current prefetch cache, exposed for diagnostics and
+   * focused unit testing. Returns a fresh array copy so callers cannot
+   * mutate the manager's internal state.
+   */
+  snapshotCache(): readonly TTarget[] | null;
+  private insertTargetPrimaryKeys;
+  private deleteTargetPrimaryKeys;
+  private resolveTargetPrimaryKeys;
+  private resolveTargetPrimaryKey;
+  private canonicalizePrimaryKey;
+}
+//#endregion
+//#region src/query/domain/RelationTyping.d.ts
+declare const InternalRelationHydrationCardinality: {
+  readonly SINGLE: "single";
+  readonly MANY: "many";
+};
+type RelationHydrationCardinality = (typeof InternalRelationHydrationCardinality)[keyof typeof InternalRelationHydrationCardinality];
+type SingleRelationHydrationCardinality = typeof InternalRelationHydrationCardinality.SINGLE;
+type ManyRelationHydrationCardinality = typeof InternalRelationHydrationCardinality.MANY;
+type HydratedQueryResult<TBase extends Record<string, unknown>, THydrated extends Record<string, unknown>> = [keyof THydrated] extends [never] ? TBase : Omit<TBase, keyof THydrated> & THydrated;
+declare global {
+  interface TangoGeneratedRelationRegistry {}
+}
+type AnyModel = Model<z.ZodObject<z.ZodRawShape>, string>;
+type ModelSchema<TModel> = TModel extends Model<infer TSchema extends z.ZodObject<z.ZodRawShape>, string> ? TSchema : never;
+type ModelShape<TModel> = ModelSchema<TModel> extends z.ZodObject<infer TShape> ? TShape : never;
+type ModelRow<TModel> = TModel extends Model<infer TSchema extends z.ZodObject<z.ZodRawShape>, string> ? PersistedModelOutput<TSchema> : never;
+type IsLiteralString<TValue> = TValue extends string ? (string extends TValue ? false : true) : false;
+type HasStrictModelKey<TModel> = TModel extends Model<z.ZodObject<z.ZodRawShape>, infer TKey> ? IsLiteralString<TKey> : false;
+type ModelKey<TModel> = TModel extends Model<z.ZodObject<z.ZodRawShape>, infer TKey extends string> ? TKey : never;
+type UnionToIntersection<TValue> = (TValue extends unknown ? (value: TValue) => void : never) extends ((value: infer TIntersection) => void) ? TIntersection : never;
+type JoinPathSegments<TSegments extends readonly string[]> = TSegments extends readonly [infer THead extends string, ...infer TRest extends string[]] ? TRest['length'] extends 0 ? THead : `${THead}__${JoinPathSegments<TRest>}` : never;
+type SplitPath<TPath extends string> = TPath extends `${infer THead}__${infer TRest}` ? [THead, ...SplitPath<TRest>] : [TPath];
+type TailTuple<TTuple extends readonly unknown[]> = TTuple extends readonly [unknown, ...infer TRest] ? TRest : [];
+type DefaultGeneratedCycleBudget = readonly [1, 1, 1, 1];
+type GeneratedRelationRegistry = TangoGeneratedRelationRegistry;
+type GeneratedRelationKeys<TSourceModel> = Extract<keyof GeneratedRelations<TSourceModel>, string>;
+type GeneratedRelations<TSourceModel> = HasStrictModelKey<TSourceModel> extends true ? ModelKey<TSourceModel> extends keyof GeneratedRelationRegistry ? GeneratedRelationRegistry[ModelKey<TSourceModel>] : {} : {};
+type NextSeenModels<TSeen extends readonly string[], TTargetModel> = ModelKey<TTargetModel> extends string ? [...TSeen, ModelKey<TTargetModel>] : TSeen;
+type CanTraverseGeneratedTarget<TTargetModel, TSeen extends readonly string[], TCycleBudget extends readonly unknown[]> = ModelKey<TTargetModel> extends TSeen[number] ? (TCycleBudget extends [] ? false : true) : true;
+type NextGeneratedCycleBudget<TTargetModel, TSeen extends readonly string[], TCycleBudget extends readonly unknown[]> = ModelKey<TTargetModel> extends TSeen[number] ? TailTuple<TCycleBudget> : TCycleBudget;
+type GeneratedCardinalityIncludesMany<TCardinality extends RelationHydrationCardinality> = TCardinality extends typeof InternalRelationHydrationCardinality.MANY ? true : false;
+/**
+ * Generated path keys accepted by `selectRelated(...)`.
+ *
+ * Walks the ambient relation registry one hop at a time. Each hop contributes:
+ *   (a) the bare relation key (e.g. `author`) as a valid path terminus, and
+ *   (b) a dunder-joined extension (`author__profile`, ...) that recurses into
+ *       the target model.
+ *
+ * Because `selectRelated` only composes single-valued hops, the mapped type
+ * filters relations whose `cardinality` is not `SINGLE`. The `TSeen` tuple
+ * tracks which model keys the recursion has visited so cyclic schemas
+ * (`manager -> manager`) are allowed a bounded number of revisits before
+ * typing falls back to `never`. `TCycleBudget` is that revisit budget; see
+ * `CanTraverseGeneratedTarget` / `NextGeneratedCycleBudget` for how it
+ * shrinks only when the next hop actually re-enters a seen model.
+ */
+type GeneratedSelectRelatedPathKeys<TSourceModel, TSeen extends readonly string[] = [ModelKey<TSourceModel>], TCycleBudget extends readonly unknown[] = DefaultGeneratedCycleBudget> = { [TKey in GeneratedRelationKeys<TSourceModel>]: GeneratedRelations<TSourceModel>[TKey] extends {
+  target: infer TTarget extends AnyModel;
+  cardinality: typeof InternalRelationHydrationCardinality.SINGLE;
+} ? TKey | (CanTraverseGeneratedTarget<TTarget, TSeen, TCycleBudget> extends true ? `${TKey}__${GeneratedSelectRelatedPathKeys<TTarget, NextSeenModels<TSeen, TTarget>, NextGeneratedCycleBudget<TTarget, TSeen, TCycleBudget>>}` : never) : never }[GeneratedRelationKeys<TSourceModel>];
+/**
+ * Generated path keys accepted by `prefetchRelated(...)`.
+ *
+ * Similar in shape to {@link GeneratedSelectRelatedPathKeys}, but relaxes two
+ * constraints because prefetch can cross and continue past collection edges:
+ *   1. Any hop whose cardinality is `MANY` is a valid terminus. The
+ *      `THasMany` flag threads through recursion so once a collection edge
+ *      has been crossed, every subsequent hop is also a valid terminus
+ *      (matches Django's `prefetch_related` semantics).
+ *   2. Single-valued hops are still accepted as terminators so paths like
+ *      `posts__author` survive the join.
+ *
+ * Cycle handling reuses the same `TSeen` / `TCycleBudget` machinery described
+ * in {@link GeneratedSelectRelatedPathKeys}: cyclic schemas are typed up to
+ * the bound, then fall back to weaker typing rather than failing.
+ */
+type GeneratedPrefetchRelatedPathKeys<TSourceModel, THasMany extends boolean = false, TSeen extends readonly string[] = [ModelKey<TSourceModel>], TCycleBudget extends readonly unknown[] = DefaultGeneratedCycleBudget> = { [TKey in GeneratedRelationKeys<TSourceModel>]: GeneratedRelations<TSourceModel>[TKey] extends {
+  target: infer TTarget extends AnyModel;
+  cardinality: infer TCardinality extends RelationHydrationCardinality;
+} ? (THasMany extends true ? TKey : GeneratedCardinalityIncludesMany<TCardinality> extends true ? TKey : never) | (CanTraverseGeneratedTarget<TTarget, TSeen, TCycleBudget> extends true ? `${TKey}__${GeneratedPrefetchRelatedPathKeys<TTarget, THasMany extends true ? true : GeneratedCardinalityIncludesMany<TCardinality>, NextSeenModels<TSeen, TTarget>, NextGeneratedCycleBudget<TTarget, TSeen, TCycleBudget>>}` : never) : never }[GeneratedRelationKeys<TSourceModel>];
+/**
+ * Generated relation-path filter keys accepted by `filter(...)`, `exclude(...)`,
+ * and `Q(...)`.
+ *
+ * This stays intentionally lighter than the eager-loading path typing:
+ * applications with generated relation registries get completion for the
+ * relation path prefix, while the terminal field and lookup suffix remain a
+ * string tail so the compiler does not explode on deep recursive field
+ * extraction.
+ */
+type GeneratedRelationFilterKeys<TSourceModel> = `${GeneratedSelectRelatedPathKeys<TSourceModel>}__${string}` | `${GeneratedPrefetchRelatedPathKeys<TSourceModel>}__${string}`;
+type GeneratedHydratedTarget<TDescriptor, TPath extends string | never> = TDescriptor extends {
+  target: infer TTarget extends AnyModel;
+} ? [TPath] extends [never] ? ModelRow<TTarget> : HydratedQueryResult<ModelRow<TTarget>, GeneratedHydratedRelationMap<TTarget, TPath>> : never;
+type GeneratedHydratedValue<TDescriptor, TPath extends string | never> = TDescriptor extends {
+  target: infer TTarget extends AnyModel;
+  kind: 'manyToMany';
+} ? ManyToManyRelatedManager<ModelRow<TTarget>> : TDescriptor extends {
+  cardinality: infer TCardinality extends RelationHydrationCardinality;
+} ? TCardinality extends typeof InternalRelationHydrationCardinality.SINGLE ? GeneratedHydratedTarget<TDescriptor, TPath> | null : GeneratedHydratedTarget<TDescriptor, TPath>[] : never;
+type GeneratedHydrationForPath<TSourceModel, TPath extends string> = SplitPath<TPath> extends [infer THead extends string, ...infer TRest extends string[]] ? THead extends GeneratedRelationKeys<TSourceModel> ? { [TKey in THead]: GeneratedHydratedValue<GeneratedRelations<TSourceModel>[THead], JoinPathSegments<TRest>> } : {} : {};
+type GeneratedHydratedRelationMap<TSourceModel, TPaths extends string | never> = ([TPaths] extends [never] ? Record<never, never> : UnionToIntersection<TPaths extends string ? GeneratedHydrationForPath<TSourceModel, TPaths> : never>) & Record<never, never>;
+type ModelKeysMatch<TCandidate, TExpected> = TCandidate extends Model<z.ZodObject<z.ZodRawShape>, infer TCandidateKey> ? TExpected extends Model<z.ZodObject<z.ZodRawShape>, infer TExpectedKey> ? IsLiteralString<TCandidateKey> extends true ? IsLiteralString<TExpectedKey> extends true ? [TCandidateKey] extends [TExpectedKey] ? true : false : false : false : false : false;
+type FieldNamingHint<TKey extends string> = TKey extends `${infer TBase}Id` ? TBase : TKey extends `${infer TBase}_id` ? TBase : TKey;
+type RelationName<TKey extends string, TName> = TName extends string ? TName : FieldNamingHint<TKey>;
+type RelatedName<TName> = TName extends string ? TName : never;
+type RelationTarget<TField> = TField extends RelationDecoratedSchema<z.ZodTypeAny, DecoratedFieldKind, infer TTarget, string | undefined, string | undefined> ? TTarget : never;
+type RelationConfiguredName<TField> = TField extends RelationDecoratedSchema<z.ZodTypeAny, DecoratedFieldKind, AnyModel, infer TName, string | undefined> ? TName : undefined;
+type RelationConfiguredRelatedName<TField> = TField extends RelationDecoratedSchema<z.ZodTypeAny, DecoratedFieldKind, AnyModel, string | undefined, infer TRelatedName> ? TRelatedName : undefined;
+type RelationKindOf<TField> = TField extends RelationDecoratedSchema<z.ZodTypeAny, infer TKind, AnyModel, string | undefined, string | undefined> ? TKind : never;
+type ForwardSingleRelations<TSourceModel> = HasStrictModelKey<TSourceModel> extends true ? { [TKey in keyof ModelShape<TSourceModel> as TKey extends string ? [RelationKindOf<ModelShape<TSourceModel>[TKey]>] extends [never] ? never : RelationKindOf<ModelShape<TSourceModel>[TKey]> extends typeof InternalDecoratedFieldKind.FOREIGN_KEY | typeof InternalDecoratedFieldKind.ONE_TO_ONE ? RelationTarget<ModelShape<TSourceModel>[TKey]> extends AnyModel ? RelationName<TKey, RelationConfiguredName<ModelShape<TSourceModel>[TKey]>> : never : never : never]: {
+  kind: typeof InternalDecoratedFieldKind.FOREIGN_KEY;
+  target: RelationTarget<ModelShape<TSourceModel>[TKey]>;
+} } : Record<string, {
+  kind: typeof InternalDecoratedFieldKind.FOREIGN_KEY;
+  target: AnyModel;
+}>;
+type ReverseSingleRelations<TSourceModel, TTargetModel> = HasStrictModelKey<TSourceModel> extends true ? HasStrictModelKey<TTargetModel> extends true ? { [TKey in keyof ModelShape<TTargetModel> as [RelationKindOf<ModelShape<TTargetModel>[TKey]>] extends [never] ? never : RelationKindOf<ModelShape<TTargetModel>[TKey]> extends typeof InternalDecoratedFieldKind.ONE_TO_ONE ? ModelKeysMatch<RelationTarget<ModelShape<TTargetModel>[TKey]>, TSourceModel> extends true ? RelatedName<RelationConfiguredRelatedName<ModelShape<TTargetModel>[TKey]>> : never : never]: {
+  kind: typeof InternalDecoratedFieldKind.ONE_TO_ONE;
+  target: TTargetModel;
+} } : {} : Record<string, {
+  kind: typeof InternalDecoratedFieldKind.ONE_TO_ONE;
+  target: AnyModel;
+}>;
+type ReverseCollectionRelations<TSourceModel, TTargetModel> = HasStrictModelKey<TSourceModel> extends true ? HasStrictModelKey<TTargetModel> extends true ? { [TKey in keyof ModelShape<TTargetModel> as [RelationKindOf<ModelShape<TTargetModel>[TKey]>] extends [never] ? never : RelationKindOf<ModelShape<TTargetModel>[TKey]> extends typeof InternalDecoratedFieldKind.FOREIGN_KEY ? ModelKeysMatch<RelationTarget<ModelShape<TTargetModel>[TKey]>, TSourceModel> extends true ? RelatedName<RelationConfiguredRelatedName<ModelShape<TTargetModel>[TKey]>> : never : never]: {
+  kind: typeof InternalDecoratedFieldKind.FOREIGN_KEY;
+  target: TTargetModel;
+} } : {} : Record<string, {
+  kind: typeof InternalDecoratedFieldKind.FOREIGN_KEY;
+  target: AnyModel;
+}>;
+type SelectRelatedRelations<TSourceModel, TTargetModel> = [TTargetModel] extends [undefined] ? ForwardSingleRelations<TSourceModel> : // Target generic supplied: include reverse hasOne relations discovered on that target model.
+ForwardSingleRelations<TSourceModel> & ReverseSingleRelations<TSourceModel, TTargetModel>;
+type PrefetchRelatedRelations<TSourceModel, TTargetModel> = ReverseCollectionRelations<TSourceModel, TTargetModel>;
+type RelationKeys<TRelations> = Extract<keyof TRelations, string>;
+type HydratedRelationMap<TRelations, TKeys extends string, TCardinality extends RelationHydrationCardinality> = { [TKey in TKeys]: TKey extends keyof TRelations ? TRelations[TKey] extends {
+  target: infer TTarget;
+} ? TCardinality extends typeof InternalRelationHydrationCardinality.SINGLE ? ModelRow<TTarget> | null : ModelRow<TTarget>[] : never : never };
+type MaybeHydratedRelationMap<TSourceModel, TRelations, TKeys extends string, TCardinality extends RelationHydrationCardinality> = HasStrictModelKey<TSourceModel> extends true ? HydratedRelationMap<TRelations, TKeys, TCardinality> : Record<never, never>;
+//#endregion
+//#region src/query/domain/RelationMeta.d.ts
+type RelationKind = (typeof InternalRelationKind)[keyof typeof InternalRelationKind];
+declare const InternalRelationHydrationLoadMode: {
+  readonly JOIN: "join";
+  readonly PREFETCH: "prefetch";
+};
+type RelationHydrationLoadMode = (typeof InternalRelationHydrationLoadMode)[keyof typeof InternalRelationHydrationLoadMode];
+interface RelationHydrationCapabilities {
+  queryable: boolean;
+  hydratable: boolean;
+  joinable: boolean;
+  prefetchable: boolean;
+}
+/**
+ * Runtime relation metadata consumed by validation, planning, compilation, and
+ * hydration.
+ */
+interface RelationMeta {
+  /** Stable edge identity from the resolved relation graph. */
+  edgeId: string;
+  /** Model key that owns the public relation name. */
+  sourceModelKey: string;
+  /** Model key reached by traversing this relation. */
+  targetModelKey: string;
+  /** Public relation kind such as belongsTo or hasMany. */
+  kind: RelationKind;
+  /** Hydration cardinality used by eager-loading APIs. */
+  cardinality: RelationHydrationCardinality;
+  /** Capability flags distilled from the resolved relation graph. */
+  capabilities: RelationHydrationCapabilities;
+  /** Physical table storing the target model rows. */
+  table: string;
+  /** Owner-side column used to attach or query related rows. */
+  sourceKey: string;
+  /** Target-side column matched against the source key. */
+  targetKey: string;
+  /** Many-to-many through table name when applicable. */
+  throughTable?: string;
+  throughModelKey?: string;
+  /** Many-to-many through column that matches the owner source key. */
+  throughSourceKey?: string;
+  /** Many-to-many through column that matches the target primary key. */
+  throughTargetKey?: string;
+  throughSourceColumnType?: string;
+  throughTargetColumnType?: string;
+  /** Primary key column for the target model. */
+  targetPrimaryKey: string;
+  /** Target model columns and their storage types. */
+  targetColumns: Record<string, string>;
+  /** Deterministic alias base used by join compilation. */
+  alias: string;
+  /** Recursive target metadata used for nested planning. */
+  targetMeta?: TableMeta;
+}
+//#endregion
+//#region src/query/domain/internal/InternalPrefetchQueryKind.d.ts
+/**
+ * Discriminator strings for compiled prefetch hydration: how `QueryCompiler.compilePrefetch`
+ * batches related rows for hydration (`CompiledPrefetchQuery`).
+ */
+declare const InternalPrefetchQueryKind: {
+  /**
+   * Single-query prefetch against the related table (`SELECT … FROM target WHERE fk IN (...)`).
+   * Used when each related row is reachable from one physical table via a foreign key or
+   * symmetric join path (belongsTo, hasMany, hasOne, reverse one-to-one).
+   */
+  readonly DIRECT: "direct";
+  /**
+   * Two-phase many-to-many prefetch: first query reads join (through) rows pairing owner ids to
+   * target ids (`throughSql`), then target rows load by primary key (`compileManyToManyTargets`).
+   * Distinct from relation metadata’s `manyToMany` relation *kind* on an endpoint—this marks the
+   * compiled prefetch *strategy*, not the schema edge type.
+   */
+  readonly MANY_TO_MANY: "manyToMany";
+};
+//#endregion
+//#region src/query/domain/CompiledQuery.d.ts
+/**
+ * Result of compiling a {@link QuerySet} into an executable SQL statement plus
+ * the hydration plan the executor needs to reshape flat rows into nested
+ * relation graphs.
+ */
+interface CompiledQuery {
+  /**
+   * Parameterized SQL string ready for `client.query(...)`. Identifiers and
+   * relation names are pre-validated; values never appear inline.
+   */
+  sql: string;
+  /**
+   * Parameter values bound to the SQL statement in the same order the
+   * placeholders appear.
+   */
+  params: readonly unknown[];
+  /**
+   * Optional hydration plan produced when the query declared selected or
+   * prefetched relations. Absent for plain row reads that do no
+   * relation-shaping work.
+   */
+  hydrationPlan?: CompiledHydrationPlanRoot;
+}
+/**
+ * Top-level hydration plan for a compiled query. Groups the join-time
+ * hydration nodes (emitted inline with the root query) with the prefetch
+ * hydration nodes (executed as follow-up queries after the root rows land).
+ */
+interface CompiledHydrationPlanRoot {
+  /**
+   * The relation paths the caller originally requested via
+   * `selectRelated(...)` / `prefetchRelated(...)`. Retained for diagnostic
+   * messages and snapshot stability.
+   */
+  requestedPaths: readonly string[];
+  /**
+   * Column aliases on the root query that exist solely to support hydration
+   * (for example, join-mirrored primary keys). The hydrator strips these
+   * before handing rows back to application code.
+   */
+  hiddenRootAliases: readonly string[];
+  /**
+   * Hydration nodes whose rows arrive joined into the root query's result
+   * set. Each node describes how to fold those joined columns back into a
+   * nested relation attribute.
+   */
+  joinNodes: readonly CompiledHydrationNode[];
+  /**
+   * Hydration nodes that require a follow-up prefetch query after the root
+   * rows land. Each node drives one or more `compilePrefetch(...)` calls.
+   */
+  prefetchNodes: readonly CompiledHydrationNode[];
+}
+/**
+ * Recursive description of how to hydrate one relation edge and its
+ * descendants. The same node shape is used for join-loaded and
+ * prefetch-loaded relations; {@link loadMode} distinguishes them.
+ */
+interface CompiledHydrationNode {
+  /** Stable identifier for this node in the plan. */
+  nodeId: string;
+  /**
+   * Public relation name as declared in the schema, mirrored onto the
+   * hydrated record (for example, `author` or `tags`).
+   */
+  relationName: string;
+  /**
+   * Dot-less path expression that reaches this node from the root, used in
+   * error messages and plan diagnostics.
+   */
+  relationPath: string;
+  /** Model key of the owner side of this edge. */
+  ownerModelKey: string;
+  /** Model key of the target side of this edge. */
+  targetModelKey: string;
+  /** Join-inline vs follow-up prefetch load strategy. */
+  loadMode: RelationHydrationLoadMode;
+  /** Whether this edge yields one target or many. */
+  cardinality: RelationHydrationCardinality;
+  /**
+   * Owner-side column whose value scopes the hydration read. For
+   * foreign-key relations this is the local column; for many-to-many this
+   * is the owner primary key.
+   */
+  sourceKey: string;
+  /**
+   * Column alias on the root SQL row that surfaces `sourceKey` to the
+   * hydrator after projection.
+   */
+  ownerSourceAccessor: string;
+  /**
+   * Target-side column that matches `sourceKey` during resolution.
+   */
+  targetKey: string;
+  /** Target table name for the related rows. */
+  targetTable: string;
+  /** Primary-key column name on the target table. */
+  targetPrimaryKey: string;
+  /** Join table name for many-to-many edges. */
+  throughTable?: string;
+  /**
+   * Join-table column storing the owner-side primary key for many-to-many
+   * edges.
+   */
+  throughSourceKey?: string;
+  /**
+   * Join-table column storing the target-side primary key for many-to-many
+   * edges.
+   */
+  throughTargetKey?: string;
+  /**
+   * SQL type of the owner-side join column, used to validate compiled
+   * placeholder values.
+   */
+  throughSourceColumnType?: string;
+  /**
+   * SQL type of the target-side join column, used to validate compiled
+   * placeholder values.
+   */
+  throughTargetColumnType?: string;
+  /**
+   * Column map for the target table keyed by column name. Used by the
+   * hydrator to materialize target rows and by the compiler to emit a
+   * stable projection.
+   */
+  targetColumns: Record<string, string>;
+  /**
+   * Ordered trail of relation names that led to this node. Used to produce
+   * precise error messages when a hydration plan fails to compile.
+   */
+  provenance: readonly string[];
+  /** Child nodes whose rows arrive joined with this node's rows. */
+  joinChildren: readonly CompiledHydrationNode[];
+  /** Child nodes that require their own follow-up prefetch. */
+  prefetchChildren: readonly CompiledHydrationNode[];
+  /** SQL join descriptor attached when this node is loaded inline. */
+  join?: CompiledJoinHydrationDescriptor;
+}
+/**
+ * Join-specific details for a hydration node loaded inline with its parent
+ * query. Captures the alias the compiler emitted for the joined table and
+ * the column aliases under which each projected column appears in the result
+ * row.
+ */
+interface CompiledJoinHydrationDescriptor {
+  /** SQL alias emitted for the joined table. */
+  alias: string;
+  /**
+   * Aliases for each projected target column, keyed by column name.
+   * Ensures the hydrator can pull the column out of the flat SQL row.
+   */
+  columns: Record<string, string>;
+}
+/**
+ * Discriminated union describing a prefetch query that must run after the
+ * root rows load. `direct` is a one-shot select against the target table;
+ * `manyToMany` is a two-phase plan that first reads join rows, then loads
+ * the target rows by primary key.
+ */
+type CompiledPrefetchQuery = {
+  /** Marks a single-query prefetch against the target table. */kind: typeof InternalPrefetchQueryKind.DIRECT; /** Parameterized select statement to execute. */
+  sql: string; /** Parameter values bound to the statement. */
+  params: readonly unknown[];
+  /**
+   * Target column whose value matches the owner-side `sourceKey`. The
+   * hydrator buckets the returned rows by this column.
+   */
+  targetKey: string; /** Column map for the target rows the hydrator will materialize. */
+  targetColumns: Record<string, string>;
+} | {
+  /**
+   * Marks a two-phase many-to-many prefetch: the join-row query runs
+   * first, then a follow-up target query resolves the actual rows by
+   * primary key.
+   */
+  kind: typeof InternalPrefetchQueryKind.MANY_TO_MANY;
+  /**
+   * SQL for the first phase: select owner/target id pairs from the
+   * join table.
+   */
+  throughSql: string; /** Parameter values bound to the join-row statement. */
+  throughParams: readonly unknown[];
+  /**
+   * Alias the compiler assigned to the owner-side join column in the
+   * join-row result set. The hydrator uses it to group targets by
+   * owner.
+   */
+  ownerAlias: string;
+  /**
+   * Alias the compiler assigned to the target-side join column in
+   * the join-row result set. The hydrator uses it to assemble the
+   * target primary-key list for phase two.
+   */
+  targetAlias: string; /** Target table name for the phase-two read. */
+  targetTable: string; /** Primary-key column on the target table for the phase-two read. */
+  targetPrimaryKey: string; /** Column map for the target rows the hydrator will materialize. */
+  targetColumns: Record<string, string>;
+};
+//#endregion
+//#region src/query/domain/internal/InternalDirection.d.ts
+declare const InternalDirection: {
+  readonly ASC: "asc";
+  readonly DESC: "desc";
+};
+//#endregion
+//#region src/query/domain/Direction.d.ts
+type Direction = (typeof InternalDirection)[keyof typeof InternalDirection];
+//#endregion
+//#region src/query/domain/TableMetaFactory.d.ts
+/**
+ * Build registry-backed recursive table metadata for query planning and
+ * hydration execution.
+ */
+declare class TableMetaFactory {
+  static create(model: Model): TableMeta;
+  private static createWithCache;
+}
+//#endregion
+//#region src/query/domain/WhereClause.d.ts
+interface WhereClause {
+  sql: string;
+  params: readonly unknown[];
+}
+declare namespace index_d_exports {
+  export { CompiledQuery, Dialect, Direction, FilterInput, FilterKey, FilterValue, ForwardSingleRelations, GeneratedHydratedRelationMap, GeneratedPrefetchRelatedPathKeys, GeneratedRelationFilterKeys, GeneratedSelectRelatedPathKeys, HydratedQueryResult, HydratedRelationMap, InternalRelationHydrationCardinality, LookupType, ManyRelationHydrationCardinality, MaybeHydratedRelationMap, OrderSpec, OrderToken, PrefetchRelatedRelations, QNode, QueryResult, QuerySetState, RelationHydrationCardinality, RelationKeys, RelationMeta, ReverseCollectionRelations, ReverseSingleRelations, SelectRelatedRelations, SingleRelationHydrationCardinality, TableMeta, TableMetaFactory, WhereClause };
+}
+//#endregion
+//#region src/query/domain/OrderSpec.d.ts
+interface OrderSpec<T> {
+  by: keyof T;
+  dir: Direction;
+}
+//#endregion
+//#region src/query/domain/QuerySetState.d.ts
+interface QuerySetState<T, TSourceModel = unknown> {
+  q?: QNode<T, TSourceModel>;
+  excludes?: QNode<T, TSourceModel>[];
+  order?: OrderSpec<T>[];
+  limit?: number;
+  offset?: number;
+  cursor?: string | null;
+  selectRelated?: string[];
+  prefetchRelated?: string[];
+  select?: (keyof T)[];
+}
+//#endregion
+export { QBuilder as A, index_d_exports$2 as B, ReverseSingleRelations as C, ManyToManyRelatedManagerCreateInputs as D, ManyToManyRelatedManager as E, QNode as F, TableMeta as H, FilterInput as I, FilterValue as L, QueryExecutor as M, QuerySet as N, ManyToManyTargetRef as O, OrderToken as P, FilterKey as R, ReverseCollectionRelations as S, SingleRelationHydrationCardinality as T, QueryResult as U, QueryCompiler as V, ManyRelationHydrationCardinality as _, TableMetaFactory as a, RelationHydrationCardinality as b, RelationMeta as c, GeneratedPrefetchRelatedPathKeys as d, GeneratedRelationFilterKeys as f, InternalRelationHydrationCardinality as g, HydratedRelationMap as h, WhereClause as i, ModelQuerySet as j, index_d_exports$1 as k, ForwardSingleRelations as l, HydratedQueryResult as m, OrderSpec as n, Direction as o, GeneratedSelectRelatedPathKeys as p, index_d_exports as r, CompiledQuery as s, QuerySetState as t, GeneratedHydratedRelationMap as u, MaybeHydratedRelationMap as v, SelectRelatedRelations as w, RelationKeys as x, PrefetchRelatedRelations as y, LookupType as z };
+//# sourceMappingURL=QuerySetState-CjyvAUBs.d.ts.map