@danceroutine/tango-orm 1.4.0 → 1.6.0

package/dist/index.d.ts

@@ -14,9 +14,9 @@ export type { Adapter, AdapterConfig, DBClient } from './connection/index';
 export { PostgresAdapter, SqliteAdapter } from './connection/index';
 export { ModelManager } from './manager/index';
 export type { ManagerLike } from './manager/index';
-export { Q, QBuilder, QueryCompiler, QuerySet } from './query/index';
+export { Q, QBuilder, QueryCompiler, QueryResult, QuerySet } from './query/index';
 export type { QueryExecutor } from './query/index';
-export type { CompiledQuery, Dialect, Direction, FilterInput, FilterKey, FilterValue, LookupType, OrderSpec, OrderToken, QNode, QueryResult, QuerySetState, RelationMeta, TableMeta, WhereClause, } from './query/domain/index';
+export type { CompiledQuery, Dialect, Direction, FilterInput, FilterKey, FilterValue, LookupType, OrderSpec, OrderToken, QNode, QuerySetState, RelationMeta, TableMeta, WhereClause, } from './query/domain/index';
 export { getTangoRuntime, initializeTangoRuntime, resetTangoRuntime, TangoRuntime } from './runtime/index';
 export { atomic, UnitOfWork } from './transaction/index';
 export type { AtomicTransaction, OnCommitOptions, SavepointOptions, SavepointResult } from './transaction/index';

package/dist/index.js

@@ -3,11 +3,11 @@ import { PostgresAdapter } from "./PostgresAdapter-CMiEpHya.js";
 import "./SqliteClient-CjOK9-ki.js";
 import { SqliteAdapter } from "./SqliteAdapter-CeqhyrPC.js";
 import { AdapterRegistry, connectDB, connection_exports, getDefaultAdapterRegistry } from "./connection-B_K2ZAf7.js";
-import { QBuilder, QueryCompiler, QuerySet, query_exports } from "./query-CWZ1cfjo.js";
+import { QBuilder, QueryCompiler, QueryResult, QuerySet, query_exports } from "./query-C6So1r6H.js";
 import { TangoRuntime, getTangoRuntime, initializeTangoRuntime, resetTangoRuntime } from "./defaultRuntime-BPK9kWEW.js";
-import { ModelManager } from "./registerModelObjects-Bva_f-Qh.js";
+import { ModelManager } from "./registerModelObjects-BKMpfc4Z.js";
 import { manager_exports } from "./manager-C6oJ2tAF.js";
 import { runtime_exports } from "./runtime-ByXbpVBS.js";
 import { UnitOfWork, atomic, transaction_exports } from "./transaction-Cs0Z9tbW.js";
 
-export { AdapterRegistry, ModelManager, PostgresAdapter, QBuilder as Q, QBuilder, QueryCompiler, QuerySet, SqliteAdapter, TangoRuntime, UnitOfWork, atomic, connectDB, connection_exports as connection, getDefaultAdapterRegistry, getTangoRuntime, initializeTangoRuntime, manager_exports as manager, query_exports as query, resetTangoRuntime, runtime_exports as runtime, transaction_exports as transaction };
+export { AdapterRegistry, ModelManager, PostgresAdapter, QBuilder as Q, QBuilder, QueryCompiler, QueryResult, QuerySet, SqliteAdapter, TangoRuntime, UnitOfWork, atomic, connectDB, connection_exports as connection, getDefaultAdapterRegistry, getTangoRuntime, initializeTangoRuntime, manager_exports as manager, query_exports as query, resetTangoRuntime, runtime_exports as runtime, transaction_exports as transaction };

package/dist/manager/ModelManager.d.ts

@@ -1,20 +1,20 @@
-import { type ModelWriteHooks } from '@danceroutine/tango-schema';
+import type { ModelWriteHooks } from '@danceroutine/tango-schema';
+import type { Model as SchemaModel } from '@danceroutine/tango-schema/domain';
 import type { TableMeta } from '../query/domain/index';
 import type { QuerySet } from '../query/index';
 import type { TangoRuntime } from '../runtime/TangoRuntime';
 import type { ManagerLike } from './ManagerLike';
-type FieldLike = {
-    name: string;
-    type: string;
-    primaryKey?: boolean;
+type ModelMetadataLike = Omit<SchemaModel['metadata'], 'key' | 'namespace' | 'fields'> & {
+    key?: string;
+    namespace?: string;
+    fields: Array<{
+        name: string;
+        type: string;
+        primaryKey?: boolean;
+    }>;
 };
 type ModelLike<TModelRow extends Record<string, unknown>> = {
-    metadata: {
-        key?: string;
-        name: string;
-        table: string;
-        fields: FieldLike[];
-    };
+    metadata: ModelMetadataLike;
     schema: {
         parse(input: unknown): TModelRow;
     };

package/dist/manager/index.js

@@ -1,8 +1,8 @@
 import "../PostgresClient-BQJZfEOT.js";
 import "../SqliteClient-CjOK9-ki.js";
-import "../query-CWZ1cfjo.js";
+import "../query-C6So1r6H.js";
 import "../defaultRuntime-BPK9kWEW.js";
-import { ModelManager, registerModelObjects } from "../registerModelObjects-Bva_f-Qh.js";
+import { ModelManager, registerModelObjects } from "../registerModelObjects-BKMpfc4Z.js";
 import "../manager-C6oJ2tAF.js";
 
 export { ModelManager, registerModelObjects };

package/dist/manager-C6oJ2tAF.js

@@ -1,5 +1,5 @@
 import { __export } from "./chunk-DLY2FNSh.js";
-import { ModelManager, registerModelObjects } from "./registerModelObjects-Bva_f-Qh.js";
+import { ModelManager, registerModelObjects } from "./registerModelObjects-BKMpfc4Z.js";
 
 //#region src/manager/index.ts
 var manager_exports = {};

package/dist/query/QuerySet.d.ts

@@ -3,11 +3,11 @@ import type { Dialect } from './domain/Dialect';
 import type { QuerySetState } from './domain/QuerySetState';
 import type { TableMeta } from './domain/TableMeta';
 import type { QNode } from './domain/QNode';
-import type { QueryResult } from './domain/QueryResult';
 import type { OrderToken } from './domain/OrderToken';
 import type { FilterInput } from './domain/FilterInput';
 import type { CompiledQuery } from './domain/CompiledQuery';
-import type { HydratedQueryResult, ManyRelationHydrationCardinality, MaybeHydratedRelationMap, PrefetchRelatedRelations, RelationKeys, SelectRelatedRelations, SingleRelationHydrationCardinality } from './domain/RelationTyping';
+import { QueryResult } from './domain/QueryResult';
+import type { GeneratedHydratedRelationMap, GeneratedPrefetchRelatedPathKeys, GeneratedSelectRelatedPathKeys, HydratedQueryResult, ManyRelationHydrationCardinality, MaybeHydratedRelationMap, PrefetchRelatedRelations, RelationKeys, SelectRelatedRelations, SingleRelationHydrationCardinality } from './domain/RelationTyping';
 /**
  * Query execution seam consumed by `QuerySet`.
  *
@@ -32,7 +32,13 @@ type ProjectedResult<TModel extends Record<string, unknown>, TKeys extends reado
 /**
  * Django-inspired query builder for constructing and executing database queries.
  * Provides a fluent API for filtering, ordering, pagination, projection, and
- * one-level relation hydration.
+ * nested relation hydration.
+ *
+ * Refinements such as `filter`, `orderBy`, `select`, and relation loaders build
+ * query state only. SQL runs when you call an evaluation method (`fetch`,
+ * `fetchOne`, `count`, `exists`, or `for await` over this queryset). After the
+ * first row-returning evaluation, this queryset instance reuses its cached
+ * materialized result on later `fetch()` or async-iteration calls.
  *
  * @template TModel - The full model row type used for query composition
  * @template TBaseResult - The selected base-row shape returned by execution methods
@@ -50,11 +56,13 @@ type ProjectedResult<TModel extends Record<string, unknown>, TKeys extends reado
  *   .fetch();
  * ```
  */
-export declare class QuerySet<TModel extends Record<string, unknown>, TBaseResult extends Record<string, unknown> = TModel, TSourceModel = unknown, THydrated extends Record<string, unknown> = Record<never, never>> {
+export declare 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>> {
+    [Symbol.asyncIterator]: () => AsyncIterator<HydratedQueryResult<TBaseResult, THydrated>>;
     private executor;
     private state;
     static readonly BRAND: "tango.orm.query_set";
     readonly __tangoBrand: typeof QuerySet.BRAND;
+    private evaluationCache?;
     constructor(executor: QueryExecutor<TModel>, state?: QuerySetState<TModel>);
     /**
      * Narrow an unknown value to `QuerySet`.
@@ -95,21 +103,24 @@ export declare class QuerySet<TModel extends Record<string, unknown>, TBaseResul
     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 relations through SQL joins.
+     * 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.
+     * 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>>> = RelationKeys<SelectRelatedRelations<TSourceModel, NoInfer<TTargetModel>>>>(...rels: readonly TRelationName[]): QuerySet<TModel, TBaseResult, TSourceModel, THydrated & MaybeHydratedRelationMap<TSourceModel, SelectRelatedRelations<TSourceModel, NoInfer<TTargetModel>>, TRelationName, SingleRelationHydrationCardinality>>;
+    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 relations with a follow-up query.
+     * 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.
+     * 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>>> = RelationKeys<PrefetchRelatedRelations<TSourceModel, NoInfer<TTargetModel>>>>(...rels: readonly TRelationName[]): QuerySet<TModel, TBaseResult, TSourceModel, THydrated & MaybeHydratedRelationMap<TSourceModel, PrefetchRelatedRelations<TSourceModel, NoInfer<TTargetModel>>, TRelationName, ManyRelationHydrationCardinality>>;
+    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>>>>;
     /**
      * Execute the query and optionally shape each row.
      *
@@ -120,6 +131,14 @@ export declare class QuerySet<TModel extends Record<string, unknown>, TBaseResul
     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 {@link QuerySet.fetch} without arguments, then
+     * yields each element from that {@link QueryResult}. 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`.
      *
@@ -138,16 +157,19 @@ export declare class QuerySet<TModel extends Record<string, unknown>, TBaseResul
      * Return whether at least one row matches the current query state.
      */
     exists(): Promise<boolean>;
-    private normalizeRowsForSchemaParsing;
-    private validateHydrationState;
+    private getOrCreateEvaluationCache;
+    private evaluateRows;
+    private normalizeHydratedRowsForParserShape;
     private hydrateRows;
-    private hydrateSelectedRows;
-    private hydratePrefetchedRows;
-    private fetchPrefetchGroup;
+    private hydrateJoinNodesForOwner;
+    private hydratePrefetchNode;
+    private groupOwnersByAccessor;
+    private canonicalizeEntity;
     private normalizeTargetRow;
-    private normalizeTargetValue;
+    private normalizeColumnValue;
     private isBooleanColumnType;
     private normalizeSqliteBoolean;
     private normalizeBooleanColumns;
+    private withoutHydrationState;
 }
 export {};

package/dist/query/compiler/QueryCompiler.d.ts

@@ -1,39 +1,32 @@
 import type { QuerySetState } from '../domain/QuerySetState';
 import type { TableMeta } from '../domain/TableMeta';
-import type { CompiledPrefetchHydration, CompiledPrefetchQuery, CompiledQuery } from '../domain/CompiledQuery';
+import type { CompiledHydrationNode, CompiledPrefetchQuery, CompiledQuery } from '../domain/CompiledQuery';
 import type { Dialect } from '../domain/Dialect';
 /**
- * Compiles immutable `QuerySet` state into parameterized SQL.
- *
- * The compiler is intentionally stateless with respect to execution and only
- * produces SQL + params artifacts that can be executed by a `DBClient`.
+ * Compiles immutable `QuerySet` state into parameterized SQL and recursive
+ * hydration execution artifacts.
  */
 export declare class QueryCompiler {
     private meta;
     private dialect;
     static readonly BRAND: "tango.orm.query_compiler";
     readonly __tangoBrand: typeof QueryCompiler.BRAND;
-    /**
-     * Build a compiler for the given repository metadata and SQL dialect.
-     */
     constructor(meta: TableMeta, dialect?: Dialect);
-    /**
-     * Narrow an unknown value to `QueryCompiler`.
-     */
     static isQueryCompiler(value: unknown): value is QueryCompiler;
-    /**
-     * Compile a query state tree into a SQL statement and bound parameters.
-     */
     compile<T>(state: QuerySetState<T>): CompiledQuery;
-    /**
-     * Compile the follow-up query used by `prefetchRelated(...)`.
-     *
-     * The base query cannot bind source values until after it has returned rows,
-     * but SQL rendering and validation still belong to the compiler.
-     */
-    compilePrefetch(prefetch: CompiledPrefetchHydration, sourceValues: readonly (string | number)[]): CompiledPrefetchQuery;
+    compilePrefetch(node: CompiledHydrationNode, sourceValues: readonly (string | number)[]): CompiledPrefetchQuery;
+    private compileHydrationNode;
+    private validateHydrationRelation;
+    private buildRootHiddenSelects;
+    private validatePrefetchTarget;
+    private collectNestedJoinSql;
+    private validatePrefetchJoinTarget;
+    private validateInternalAlias;
+    private buildJoinAlias;
+    private buildPrefetchBaseAlias;
     private buildHydrationColumnAlias;
     private buildPrefetchSourceAlias;
+    private sanitizeRelationPath;
     private assertInternalAliasDoesNotCollide;
     private compileQNode;
     private compileAtom;

package/dist/query/domain/CompiledQuery.d.ts

@@ -1,21 +1,38 @@
+import type { RelationHydrationLoadMode } from './RelationMeta';
+import type { RelationHydrationCardinality } from './RelationTyping';
 export interface CompiledQuery {
     sql: string;
     params: readonly unknown[];
-    hydrations?: readonly CompiledRelationHydration[];
-    prefetches?: readonly CompiledPrefetchHydration[];
+    hydrationPlan?: CompiledHydrationPlanRoot;
 }
-export interface CompiledRelationHydration {
-    relationName: string;
-    alias: string;
-    columns: Record<string, string>;
+export interface CompiledHydrationPlanRoot {
+    requestedPaths: readonly string[];
+    hiddenRootAliases: readonly string[];
+    joinNodes: readonly CompiledHydrationNode[];
+    prefetchNodes: readonly CompiledHydrationNode[];
 }
-export interface CompiledPrefetchHydration {
+export interface CompiledHydrationNode {
+    nodeId: string;
     relationName: string;
+    relationPath: string;
+    ownerModelKey: string;
+    targetModelKey: string;
+    loadMode: RelationHydrationLoadMode;
+    cardinality: RelationHydrationCardinality;
     sourceKey: string;
-    sourceKeyAlias?: string;
-    table: string;
+    ownerSourceAccessor: string;
     targetKey: string;
+    targetTable: string;
+    targetPrimaryKey: string;
     targetColumns: Record<string, string>;
+    provenance: readonly string[];
+    joinChildren: readonly CompiledHydrationNode[];
+    prefetchChildren: readonly CompiledHydrationNode[];
+    join?: CompiledJoinHydrationDescriptor;
+}
+export interface CompiledJoinHydrationDescriptor {
+    alias: string;
+    columns: Record<string, string>;
 }
 export interface CompiledPrefetchQuery {
     sql: string;

package/dist/query/domain/QueryResult.d.ts

@@ -1,4 +1,35 @@
-export interface QueryResult<T> {
-    results: T[];
-    nextCursor?: string | null;
+/**
+ * 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.
+ */
+export declare class QueryResult<T> implements Iterable<T> {
+    /**
+     * Sync iteration over materialized rows.
+     */
+    [Symbol.iterator]: () => Iterator<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[];
 }

package/dist/query/domain/RelationMeta.d.ts

@@ -1,10 +1,47 @@
 import type { InternalRelationKind } from './internal/InternalRelationKind';
+import type { RelationHydrationCardinality } from './RelationTyping';
+import type { TableMeta } from './TableMeta';
 export type RelationKind = (typeof InternalRelationKind)[keyof typeof InternalRelationKind];
+export declare const InternalRelationHydrationLoadMode: {
+    readonly JOIN: "join";
+    readonly PREFETCH: "prefetch";
+};
+export type RelationHydrationLoadMode = (typeof InternalRelationHydrationLoadMode)[keyof typeof InternalRelationHydrationLoadMode];
+export interface RelationHydrationCapabilities {
+    queryable: boolean;
+    hydratable: boolean;
+    joinable: boolean;
+    prefetchable: boolean;
+}
+/**
+ * Runtime relation metadata consumed by validation, planning, compilation, and
+ * hydration.
+ */
 export 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;
+    /** 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;
 }

package/dist/query/domain/RelationTyping.d.ts

@@ -11,12 +11,54 @@ export type ManyRelationHydrationCardinality = typeof InternalRelationHydrationC
 export 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;
+export 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>];
+export 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>];
+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 {
+    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>>;
+} : {} : {};
+export type GeneratedHydratedRelationMap<TSourceModel, TPaths extends string | never> = ([TPaths] extends [never] ? Record<never, never> : UnionToIntersection<TPaths extends string ? GeneratedHydrationForPath<TSourceModel, TPaths> : never>) & Record<never, never>;
 export type HasStrictRelationTyping<TSourceModel> = HasStrictModelKey<TSourceModel>;
 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

package/dist/query/domain/TableMeta.d.ts

@@ -1,7 +1,16 @@
 import type { RelationMeta } from './RelationMeta';
+/**
+ * SQL-facing model metadata visible to the ORM layer.
+ */
 export 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>;
 }

package/dist/query/domain/TableMetaFactory.d.ts

@@ -0,0 +1,23 @@
+import type { Model as SchemaModel } from '@danceroutine/tango-schema/domain';
+import type { TableMeta } from './TableMeta';
+type ModelMetadataLike = Omit<SchemaModel['metadata'], 'key' | 'namespace' | 'fields'> & {
+    key?: string;
+    namespace?: string;
+    fields: Array<{
+        name: string;
+        type: string;
+        primaryKey?: boolean;
+    }>;
+};
+type TableMetaModel = {
+    metadata: ModelMetadataLike;
+};
+/**
+ * Build registry-backed recursive table metadata for query planning and
+ * hydration execution.
+ */
+export declare class TableMetaFactory {
+    static create(model: TableMetaModel): TableMeta;
+    private static createWithCache;
+}
+export {};

package/dist/query/domain/index.d.ts

@@ -11,10 +11,11 @@ export type { LookupType } from './LookupType';
 export type { OrderSpec } from './OrderSpec';
 export type { OrderToken } from './OrderToken';
 export type { QNode } from './QNode';
-export type { QueryResult } from './QueryResult';
+export { QueryResult } from './QueryResult';
 export type { QuerySetState } from './QuerySetState';
 export type { RelationMeta } from './RelationMeta';
-export type { ForwardSingleRelations, HydratedQueryResult, HydratedRelationMap, ManyRelationHydrationCardinality, MaybeHydratedRelationMap, PrefetchRelatedRelations, RelationKeys, RelationHydrationCardinality, ReverseCollectionRelations, ReverseSingleRelations, SelectRelatedRelations, SingleRelationHydrationCardinality, } from './RelationTyping';
+export type { ForwardSingleRelations, GeneratedHydratedRelationMap, GeneratedPrefetchRelatedPathKeys, GeneratedSelectRelatedPathKeys, HydratedQueryResult, HydratedRelationMap, ManyRelationHydrationCardinality, MaybeHydratedRelationMap, PrefetchRelatedRelations, RelationKeys, RelationHydrationCardinality, ReverseCollectionRelations, ReverseSingleRelations, SelectRelatedRelations, SingleRelationHydrationCardinality, } from './RelationTyping';
 export { InternalRelationHydrationCardinality } from './RelationTyping';
 export type { TableMeta } from './TableMeta';
+export { TableMetaFactory } from './TableMetaFactory';
 export type { WhereClause } from './WhereClause';

package/dist/query/index.d.ts

@@ -6,6 +6,7 @@ export * as compiler from './compiler/index';
 export * as domain from './domain/index';
 export type * from './domain/index';
 export type { TableMeta } from './domain/index';
+export { QueryResult } from './domain/index';
 export { QuerySet } from './QuerySet';
 export type { QueryExecutor } from './QuerySet';
 export { QBuilder, QBuilder as Q } from './QBuilder';

package/dist/query/index.js

@@ -1,3 +1,3 @@
-import { QBuilder, QueryCompiler, QuerySet, compiler_exports, domain_exports } from "../query-CWZ1cfjo.js";
+import { QBuilder, QueryCompiler, QueryResult, QuerySet, compiler_exports, domain_exports } from "../query-C6So1r6H.js";
 
-export { QBuilder as Q, QBuilder, QueryCompiler, QuerySet, compiler_exports as compiler, domain_exports as domain };
+export { QBuilder as Q, QBuilder, QueryCompiler, QueryResult, QuerySet, compiler_exports as compiler, domain_exports as domain };

package/dist/query/planning/QueryPlanner.d.ts

@@ -0,0 +1,16 @@
+import type { QuerySetState } from '../domain/QuerySetState';
+import type { TableMeta } from '../domain/TableMeta';
+import type { QueryHydrationPlanRoot } from './domain/QueryHydrationPlan';
+/**
+ * Parse, validate, normalize, and plan recursive relation hydration paths.
+ */
+export declare class QueryPlanner {
+    private readonly meta;
+    static readonly BRAND: "tango.orm.query_planner";
+    readonly __tangoBrand: typeof QueryPlanner.BRAND;
+    constructor(meta: TableMeta);
+    static isQueryPlanner(value: unknown): value is QueryPlanner;
+    plan<T>(state: QuerySetState<T>): QueryHydrationPlanRoot;
+    private addPath;
+    private buildPlannedChildren;
+}

package/dist/query/planning/domain/QueryHydrationPlan.d.ts

@@ -0,0 +1,20 @@
+import type { RelationHydrationLoadMode, RelationMeta } from '../../domain/RelationMeta';
+export type QueryHydrationLoadMode = RelationHydrationLoadMode;
+export interface QueryHydrationPlanRoot {
+    joinNodes: readonly QueryHydrationPlanNode[];
+    prefetchNodes: readonly QueryHydrationPlanNode[];
+    requestedPaths: readonly string[];
+}
+export interface QueryHydrationPlanNode {
+    nodeId: string;
+    relationName: string;
+    relationPath: string;
+    ownerModelKey: string;
+    relationEdge: RelationMeta;
+    targetModelKey: string;
+    loadMode: QueryHydrationLoadMode;
+    cardinality: RelationMeta['cardinality'];
+    provenance: readonly string[];
+    joinChildren: readonly QueryHydrationPlanNode[];
+    prefetchChildren: readonly QueryHydrationPlanNode[];
+}

package/dist/query/planning/index.d.ts

@@ -0,0 +1,2 @@
+export { QueryPlanner } from './QueryPlanner';
+export type { QueryHydrationPlanNode, QueryHydrationPlanRoot, QueryHydrationLoadMode, } from './domain/QueryHydrationPlan';