@danceroutine/tango-schema 1.1.3 → 1.2.0

package/dist/domain/Model.d.ts

@@ -1,6 +1,7 @@
 import type { z } from 'zod';
 import type { ModelMetadata } from './ModelMetadata';
 import type { ModelWriteHooks } from './ModelWriteHooks';
+import type { ManyToManyDecoratedSchema } from '../model/decorators/domain/ManyToManyDecoratedSchema';
 declare const MODEL_AUGMENTATION_SCHEMA: unique symbol;
 type ModelAugmentationCarrier<TSchema extends z.ZodObject<z.ZodRawShape>> = {
     readonly [MODEL_AUGMENTATION_SCHEMA]?: TSchema;
@@ -9,6 +10,11 @@ declare global {
     interface TangoSchemaModelAugmentations<TSchema extends z.ZodObject<z.ZodRawShape> = z.ZodObject<z.ZodRawShape>> {
     }
 }
+type ManyToManyFieldKeys<TShape extends z.ZodRawShape> = {
+    [K in keyof TShape]: TShape[K] extends ManyToManyDecoratedSchema<z.ZodTypeAny> ? K : never;
+}[keyof TShape];
+type PersistedShape<TShape extends z.ZodRawShape> = Omit<z.output<z.ZodObject<TShape>>, ManyToManyFieldKeys<TShape>>;
+export type PersistedModelOutput<TSchema extends z.ZodObject<z.ZodRawShape>> = TSchema extends z.ZodObject<infer TShape> ? PersistedShape<TShape> : z.output<TSchema>;
 export interface ModelAugmentations<TSchema extends z.ZodObject<z.ZodRawShape> = z.ZodObject<z.ZodRawShape>> extends ModelAugmentationCarrier<TSchema>, TangoSchemaModelAugmentations<TSchema> {
 }
 export interface Model<TSchema extends z.ZodObject<z.ZodRawShape> = z.ZodObject<z.ZodRawShape>> extends ModelAugmentations<TSchema> {
@@ -17,6 +23,6 @@ export interface Model<TSchema extends z.ZodObject<z.ZodRawShape> = z.ZodObject<
     /**
      * Model-owned write lifecycle hooks preserved from the definition.
      */
-    hooks?: ModelWriteHooks<z.output<TSchema>>;
+    hooks?: ModelWriteHooks<PersistedModelOutput<TSchema>>;
 }
 export {};

package/dist/domain/index.d.ts

@@ -9,5 +9,5 @@ export type { Field } from './Field';
 export type { IndexDef } from './IndexDef';
 export type { RelationDef } from './RelationDef';
 export type { ModelMetadata } from './ModelMetadata';
-export type { Model, ModelAugmentations } from './Model';
+export type { Model, ModelAugmentations, PersistedModelOutput } from './Model';
 export type { ModelHookModel, ModelWriteHookManager, ModelWriteHooks, BeforeCreateHookArgs, AfterCreateHookArgs, BeforeUpdateHookArgs, AfterUpdateHookArgs, BeforeDeleteHookArgs, AfterDeleteHookArgs, BeforeBulkCreateHookArgs, AfterBulkCreateHookArgs, } from './ModelWriteHooks';

package/dist/domain-Cufz6y1q.js.map

@@ -1 +1 @@
-{"version":3,"file":"domain-Cufz6y1q.js","names":[],"sources":["../src/domain/index.ts"],"sourcesContent":["/**\n * Domain boundary barrel: centralizes this subdomain's public contract.\n */\n\nexport type { FieldType } from './FieldType';\nexport type { DeleteReferentialAction } from './DeleteReferentialAction';\nexport type { UpdateReferentialAction } from './UpdateReferentialAction';\nexport type { RelationType } from './RelationType';\nexport type { Field } from './Field';\nexport type { IndexDef } from './IndexDef';\nexport type { RelationDef } from './RelationDef';\nexport type { ModelMetadata } from './ModelMetadata';\nexport type { Model, ModelAugmentations } from './Model';\nexport type {\n    ModelHookModel,\n    ModelWriteHookManager,\n    ModelWriteHooks,\n    BeforeCreateHookArgs,\n    AfterCreateHookArgs,\n    BeforeUpdateHookArgs,\n    AfterUpdateHookArgs,\n    BeforeDeleteHookArgs,\n    AfterDeleteHookArgs,\n    BeforeBulkCreateHookArgs,\n    AfterBulkCreateHookArgs,\n} from './ModelWriteHooks';\n"],"mappings":""}
+{"version":3,"file":"domain-Cufz6y1q.js","names":[],"sources":["../src/domain/index.ts"],"sourcesContent":["/**\n * Domain boundary barrel: centralizes this subdomain's public contract.\n */\n\nexport type { FieldType } from './FieldType';\nexport type { DeleteReferentialAction } from './DeleteReferentialAction';\nexport type { UpdateReferentialAction } from './UpdateReferentialAction';\nexport type { RelationType } from './RelationType';\nexport type { Field } from './Field';\nexport type { IndexDef } from './IndexDef';\nexport type { RelationDef } from './RelationDef';\nexport type { ModelMetadata } from './ModelMetadata';\nexport type { Model, ModelAugmentations, PersistedModelOutput } from './Model';\nexport type {\n    ModelHookModel,\n    ModelWriteHookManager,\n    ModelWriteHooks,\n    BeforeCreateHookArgs,\n    AfterCreateHookArgs,\n    BeforeUpdateHookArgs,\n    AfterUpdateHookArgs,\n    BeforeDeleteHookArgs,\n    AfterDeleteHookArgs,\n    BeforeBulkCreateHookArgs,\n    AfterBulkCreateHookArgs,\n} from './ModelWriteHooks';\n"],"mappings":""}

package/dist/index.d.ts

@@ -4,5 +4,5 @@
  */
 export * as domain from './domain/index';
 export * as model from './model/index';
-export type { DeleteReferentialAction, Field, FieldType, IndexDef, ModelHookModel, ModelAugmentations, ModelMetadata, ModelWriteHookManager, ModelWriteHooks, BeforeCreateHookArgs, AfterCreateHookArgs, BeforeUpdateHookArgs, AfterUpdateHookArgs, BeforeDeleteHookArgs, AfterDeleteHookArgs, BeforeBulkCreateHookArgs, AfterBulkCreateHookArgs, RelationDef, RelationType, UpdateReferentialAction, } from './domain/index';
-export { Model, RelationBuilder, ModelRegistry, registerModelAugmentor, Constraints, Decorators, Indexes, Meta, c, i, m, t, type ModelDefinition, } from './model/index';
+export type { DeleteReferentialAction, Field, FieldType, IndexDef, ModelHookModel, ModelAugmentations, ModelMetadata, PersistedModelOutput, ModelWriteHookManager, ModelWriteHooks, BeforeCreateHookArgs, AfterCreateHookArgs, BeforeUpdateHookArgs, AfterUpdateHookArgs, BeforeDeleteHookArgs, AfterDeleteHookArgs, BeforeBulkCreateHookArgs, AfterBulkCreateHookArgs, RelationDef, RelationType, UpdateReferentialAction, } from './domain/index';
+export { Model, RelationBuilder, ModelRegistry, registerModelAugmentor, Constraints, Decorators, Indexes, Meta, c, i, m, t, type ModelDefinition, type ForeignKeyDecoratorConfig, type FieldDecoratorBuilder, type ManyToManyDecoratorConfig, type OneToOneDecoratorConfig, } from './model/index';

package/dist/index.js

@@ -1,4 +1,4 @@
-import { Constraints, Decorators, Indexes, Meta, Model, ModelRegistry, RelationBuilder, model_exports, registerModelAugmentor } from "./model-DI8lQH1W.js";
+import { Constraints, Decorators, Indexes, Meta, Model, ModelRegistry, RelationBuilder, model_exports, registerModelAugmentor } from "./model-CJbsYdkM.js";
 import { domain_exports } from "./domain-Cufz6y1q.js";
 
 export { Constraints, Decorators, Indexes, Meta, Model, ModelRegistry, RelationBuilder, Constraints as c, domain_exports as domain, Indexes as i, Meta as m, model_exports as model, registerModelAugmentor, Decorators as t };

package/dist/model/Model.d.ts

@@ -3,6 +3,6 @@ import type { Model as SchemaModel } from '../domain/Model';
 import type { ModelDefinition } from './ModelDefinition';
 /**
  * Creates a model definition with metadata and schema validation.
- * Automatically infers field types from Zod schema if fields are not explicitly provided.
+ * Automatically finalizes field types through the owning model registry.
  */
 export declare function Model<TSchema extends z.ZodObject<z.ZodRawShape>>(definition: ModelDefinition<TSchema>): SchemaModel<TSchema>;

package/dist/model/ModelDefinition.d.ts

@@ -1,12 +1,14 @@
 import { z } from 'zod';
-import type { Field, IndexDef, RelationDef } from '../domain/index';
+import type { Field, IndexDef, PersistedModelOutput, RelationDef } from '../domain/index';
 import type { ModelWriteHooks } from '../domain/index';
-import type { RelationBuilder } from './RelationBuilder';
+import type { RelationBuilder } from './relations/RelationBuilder';
+import type { ModelRegistry } from './registry/ModelRegistry';
 export interface ModelDefinition<TSchema extends z.ZodObject<z.ZodRawShape>> {
     namespace: string;
     name: string;
     table?: string;
     schema: TSchema;
+    registry?: ModelRegistry;
     fields?: Field[];
     indexes?: IndexDef[];
     relations?: (builder: RelationBuilder) => Record<string, RelationDef>;
@@ -17,5 +19,5 @@ export interface ModelDefinition<TSchema extends z.ZodObject<z.ZodRawShape>> {
     /**
      * Model-owned write lifecycle hooks that run inside `Model.objects`.
      */
-    hooks?: ModelWriteHooks<z.output<TSchema>>;
+    hooks?: ModelWriteHooks<PersistedModelOutput<TSchema>>;
 }

package/dist/model/decorators/Decorators.d.ts

@@ -1,18 +1,58 @@
 import { z } from 'zod';
-import type { ModelRef, ReferentialOptions, ZodTypeAny } from './types';
+import type { ZodTypeAny } from './domain/ZodTypeAny';
+import type { ModelRef } from './domain/ModelRef';
+import type { ReferentialOptions } from './domain/TangoFieldMeta';
+import type { ForeignKeyDecoratorConfig, ManyToManyDecoratorConfig, OneToOneDecoratorConfig } from './domain/RelationDecoratorConfig';
+import type { RelationDecoratedSchema } from './domain/RelationDecoratedSchema';
+export interface FieldDecoratorBuilder<TField extends ZodTypeAny> {
+    defaultValue(value: string | {
+        now: true;
+    } | null): FieldDecoratorBuilder<TField>;
+    dbDefault(value: string): FieldDecoratorBuilder<TField>;
+    dbColumn(name: string): FieldDecoratorBuilder<TField>;
+    dbIndex(): FieldDecoratorBuilder<TField>;
+    choices(values: readonly unknown[]): FieldDecoratorBuilder<TField>;
+    validators(...values: readonly ((value: unknown) => unknown)[]): FieldDecoratorBuilder<TField>;
+    helpText(text: string): FieldDecoratorBuilder<TField>;
+    errorMessages(map: Record<string, string>): FieldDecoratorBuilder<TField>;
+    build(): TField;
+}
 type UnaryFieldDecorator = {
     <T extends ZodTypeAny>(schema: T): T;
     <T extends ZodTypeAny>(): (input: T) => T;
 };
 type RelationshipDecorator = {
-    <T extends ZodTypeAny>(target: ModelRef, schema: T, options?: ReferentialOptions): T;
-    (target: ModelRef, options?: ReferentialOptions): z.ZodNumber;
+    <T extends ZodTypeAny>(target: ModelRef, config: ForeignKeyDecoratorConfig<T> & {
+        field: T;
+    }): RelationDecoratedSchema<T, 'foreignKey'>;
+    (target: ModelRef, config?: ForeignKeyDecoratorConfig): z.ZodNumber;
+    /**
+     * @deprecated Use `t.foreignKey(target, { field: schema, ...options })` instead.
+     */
+    <T extends ZodTypeAny>(target: ModelRef, schema: T, options?: ReferentialOptions): RelationDecoratedSchema<T, 'foreignKey'>;
+};
+type OneToOneRelationshipDecorator = {
+    <T extends ZodTypeAny>(target: ModelRef, config: OneToOneDecoratorConfig<T> & {
+        field: T;
+    }): RelationDecoratedSchema<T, 'oneToOne'>;
+    (target: ModelRef, config?: OneToOneDecoratorConfig): z.ZodNumber;
+    /**
+     * @deprecated Use `t.oneToOne(target, { field: schema, ...options })` instead.
+     */
+    <T extends ZodTypeAny>(target: ModelRef, schema: T, options?: ReferentialOptions): RelationDecoratedSchema<T, 'oneToOne'>;
 };
 type ManyToManyDecorator = {
-    <T extends ZodTypeAny>(target: ModelRef, schema: T): T;
-    (target: ModelRef): z.ZodArray<z.ZodNumber>;
+    <T extends ZodTypeAny>(target: ModelRef, config: ManyToManyDecoratorConfig<T> & {
+        field: T;
+    }): RelationDecoratedSchema<T, 'manyToMany'>;
+    (target: ModelRef, config?: ManyToManyDecoratorConfig): z.ZodArray<z.ZodNumber>;
+    /**
+     * @deprecated Use `t.manyToMany(target, { field: schema, name })` instead.
+     */
+    <T extends ZodTypeAny>(target: ModelRef, schema: T): RelationDecoratedSchema<T, 'manyToMany'>;
 };
 export interface TangoDecorators {
+    field: <T extends ZodTypeAny>(schema: T) => FieldDecoratorBuilder<T>;
     primaryKey: UnaryFieldDecorator;
     unique: UnaryFieldDecorator;
     null: UnaryFieldDecorator;
@@ -28,7 +68,7 @@ export interface TangoDecorators {
     helpText: <T extends ZodTypeAny>(schema: T, text: string) => T;
     errorMessages: <T extends ZodTypeAny>(schema: T, map: Record<string, string>) => T;
     foreignKey: RelationshipDecorator;
-    oneToOne: RelationshipDecorator;
+    oneToOne: OneToOneRelationshipDecorator;
     manyToMany: ManyToManyDecorator;
 }
 export declare const Decorators: TangoDecorators;

package/dist/model/decorators/domain/DecoratedFieldKind.d.ts

@@ -0,0 +1,6 @@
+export declare const INTERNAL_DECORATED_FIELD_KIND: {
+    readonly FOREIGN_KEY: "foreignKey";
+    readonly ONE_TO_ONE: "oneToOne";
+    readonly MANY_TO_MANY: "manyToMany";
+};
+export type DecoratedFieldKind = (typeof INTERNAL_DECORATED_FIELD_KIND)[keyof typeof INTERNAL_DECORATED_FIELD_KIND];

package/dist/model/decorators/domain/ManyToManyDecoratedSchema.d.ts

@@ -0,0 +1,4 @@
+import type { INTERNAL_DECORATED_FIELD_KIND } from './DecoratedFieldKind';
+import type { RelationDecoratedSchema } from './RelationDecoratedSchema';
+import type { ZodTypeAny } from './ZodTypeAny';
+export type ManyToManyDecoratedSchema<TSchema extends ZodTypeAny> = RelationDecoratedSchema<TSchema, typeof INTERNAL_DECORATED_FIELD_KIND.MANY_TO_MANY>;

package/dist/model/decorators/domain/ModelRef.d.ts

@@ -0,0 +1,2 @@
+import type { Model } from '../../../domain';
+export type ModelRef = string | Model | (() => Model);

package/dist/model/decorators/domain/RelationDecoratedSchema.d.ts

@@ -0,0 +1,9 @@
+import type { DecoratedFieldKind } from './DecoratedFieldKind';
+import type { ZodTypeAny } from './ZodTypeAny';
+declare const TANGO_DECORATED_FIELD_KIND: unique symbol;
+export type RelationDecoratedSchema<TSchema extends ZodTypeAny, TKind extends DecoratedFieldKind> = TSchema & {
+    readonly [TANGO_DECORATED_FIELD_KIND]: {
+        readonly relationKind: TKind;
+    };
+};
+export {};

package/dist/model/decorators/domain/RelationDecoratorConfig.d.ts

@@ -0,0 +1,35 @@
+import type { ZodTypeAny } from './ZodTypeAny';
+import type { ReferentialOptions } from './TangoFieldMeta';
+/**
+ * Config object for `t.foreignKey(...)`.
+ *
+ * The config object is the preferred second-argument form for relation
+ * decorators. Omit `field` to keep Tango's default schema inference.
+ */
+export interface ForeignKeyDecoratorConfig<TField extends ZodTypeAny = ZodTypeAny> extends ReferentialOptions {
+    field?: TField;
+    name?: string;
+    relatedName?: string;
+}
+/**
+ * Config object for `t.oneToOne(...)`.
+ *
+ * The config object is the preferred second-argument form for relation
+ * decorators. Omit `field` to keep Tango's default schema inference.
+ */
+export interface OneToOneDecoratorConfig<TField extends ZodTypeAny = ZodTypeAny> extends ReferentialOptions {
+    field?: TField;
+    name?: string;
+    relatedName?: string;
+}
+/**
+ * Config object for `t.manyToMany(...)`.
+ *
+ * The config object is the preferred second-argument form for relation
+ * decorators. Omit `field` to keep Tango's default schema inference.
+ */
+export interface ManyToManyDecoratorConfig<TField extends ZodTypeAny = ZodTypeAny> {
+    field?: TField;
+    name?: string;
+    relatedName?: never;
+}

package/dist/model/decorators/{types.d.ts → domain/TangoFieldMeta.d.ts}

@@ -1,6 +1,6 @@
-import type { z } from 'zod';
-import type { DeleteReferentialAction, Model, UpdateReferentialAction } from '../../domain/index';
-export type ModelRef = string | Model | (() => Model);
+import type { DeleteReferentialAction, UpdateReferentialAction } from '../../../domain';
+import type { DecoratedFieldKind } from './DecoratedFieldKind';
+import type { ModelRef } from './ModelRef';
 export interface ReferentialOptions {
     column?: string;
     onDelete?: DeleteReferentialAction;
@@ -24,6 +24,7 @@ export interface TangoFieldMeta {
         target: ModelRef;
         options?: ReferentialOptions;
     };
-    relationKind?: 'foreignKey' | 'oneToOne' | 'manyToMany';
+    relationKind?: DecoratedFieldKind;
+    forwardName?: string;
+    reverseName?: string;
 }
-export type ZodTypeAny = z.ZodTypeAny;

package/dist/model/decorators/domain/ZodTypeAny.d.ts

@@ -0,0 +1,2 @@
+import type { z } from 'zod';
+export type ZodTypeAny = z.ZodTypeAny;

package/dist/model/decorators/index.d.ts

@@ -2,5 +2,8 @@
  * Domain boundary barrel: centralizes this subdomain's public contract.
  */
 export { Decorators, Decorators as t } from './Decorators';
-export type { TangoDecorators } from './Decorators';
-export type { ModelRef, ReferentialOptions, TangoFieldMeta, ZodTypeAny } from './types';
+export type { FieldDecoratorBuilder, TangoDecorators } from './Decorators';
+export type { ModelRef } from './domain/ModelRef';
+export type { ForeignKeyDecoratorConfig, OneToOneDecoratorConfig, ManyToManyDecoratorConfig, } from './domain/RelationDecoratorConfig';
+export type { ReferentialOptions, TangoFieldMeta } from './domain/TangoFieldMeta';
+export type { ZodTypeAny } from './domain/ZodTypeAny';

package/dist/model/{internal → fields}/FieldMetadataStore.d.ts

@@ -1,3 +1,4 @@
-import type { TangoFieldMeta, ZodTypeAny } from '../decorators/types';
+import type { ZodTypeAny } from '../decorators/domain/ZodTypeAny';
+import type { TangoFieldMeta } from '../decorators/domain/TangoFieldMeta';
 export declare function getFieldMetadata(schema: ZodTypeAny): TangoFieldMeta | undefined;
 export declare function setFieldMetadata(schema: ZodTypeAny, meta: TangoFieldMeta): void;

package/dist/model/fields/FinalizedStorageArtifacts.d.ts

@@ -0,0 +1,11 @@
+import type { Field } from '../../domain/index';
+export interface FinalizedStorageModel {
+    key: string;
+    table: string;
+    fields: readonly Field[];
+    pk: string;
+}
+export interface FinalizedStorageArtifacts {
+    version: number;
+    byModel: ReadonlyMap<string, FinalizedStorageModel>;
+}

package/dist/model/{inferFields.d.ts → fields/inferFieldsFromSchema.d.ts}

@@ -1,8 +1,13 @@
 import { z } from 'zod';
-import type { Field } from '../domain/index';
-import { ModelRegistry } from './registry/ModelRegistry';
+import type { Field } from '../../domain/index';
+import type { ModelRef } from '../decorators/domain/ModelRef';
+import { ModelRegistry } from '../registry/ModelRegistry';
 export type InferFieldsOptions = {
     registry?: ModelRegistry;
+    resolveReferenceTarget?: (target: ModelRef) => {
+        table: string;
+        pk: string;
+    };
 };
 /**
  * Infer Tango field metadata from a Zod object schema and any attached field decorators.

package/dist/model/index.d.ts

@@ -1,14 +1,23 @@
 /**
  * Domain boundary barrel: centralizes this subdomain's public contract.
+ *
+ * Tango keeps both flat exports and namespaced subdomain barrels here so
+ * callers can choose TS-native direct imports or Django-style drill-down
+ * access through the bundled `model` namespace at the package root.
  */
+export * as decorators from './decorators/index';
+export * as meta from './meta/index';
+export * as constraints from './constraints/index';
+export * as registry from './registry/index';
+export * as relations from './relations/index';
 export type { ModelDefinition } from './ModelDefinition';
-export { RelationBuilder } from './RelationBuilder';
+export { RelationBuilder } from './relations/index';
 export { Model } from './Model';
 export { registerModelAugmentor } from './ModelAugmentorRegistry';
 export { Decorators, t } from './decorators/index';
-export type { TangoDecorators } from './decorators/index';
+export type { TangoDecorators, FieldDecoratorBuilder, ForeignKeyDecoratorConfig, OneToOneDecoratorConfig, ManyToManyDecoratorConfig, } from './decorators/index';
 export { Meta, m } from './meta/index';
 export type { ModelConstraint, ModelMetaFragment } from './meta/index';
 export { Constraints, Indexes, c, i } from './constraints/index';
 export type { ConstraintDefinition } from './constraints/index';
-export { ModelRegistry } from './registry/ModelRegistry';
+export { ModelRegistry } from './registry/index';

package/dist/model/index.js

@@ -1,3 +1,3 @@
-import { Constraints, Decorators, Indexes, Meta, Model, ModelRegistry, RelationBuilder, registerModelAugmentor } from "../model-DI8lQH1W.js";
+import { Constraints, Decorators, Indexes, Meta, Model, ModelRegistry, RelationBuilder, constraints_exports, decorators_exports, meta_exports, registerModelAugmentor, registry_exports, relations_exports } from "../model-CJbsYdkM.js";
 
-export { Constraints, Decorators, Indexes, Meta, Model, ModelRegistry, RelationBuilder, Constraints as c, Indexes as i, Meta as m, registerModelAugmentor, Decorators as t };
+export { Constraints, Decorators, Indexes, Meta, Model, ModelRegistry, RelationBuilder, Constraints as c, constraints_exports as constraints, decorators_exports as decorators, Indexes as i, Meta as m, meta_exports as meta, registerModelAugmentor, registry_exports as registry, relations_exports as relations, Decorators as t };

package/dist/model/internal/InternalSchemaModel.d.ts

@@ -0,0 +1,31 @@
+import { z } from 'zod';
+import type { Field, Model, ModelAugmentations, ModelMetadata, ModelWriteHooks, PersistedModelOutput, RelationDef } from '../../domain/index';
+import type { ModelDefinition } from '../ModelDefinition';
+import type { ModelRegistry } from '../registry/ModelRegistry';
+import type { NormalizedRelationStorageDescriptor } from '../relations/NormalizedRelationStorageDescriptor';
+type AnySchemaModel = Model<z.ZodObject<z.ZodRawShape>>;
+type AnyInternalSchemaModel = InternalSchemaModel<z.ZodObject<z.ZodRawShape>>;
+export declare class InternalSchemaModel<TSchema extends z.ZodObject<z.ZodRawShape>> implements Model<TSchema> {
+    static readonly BRAND: "tango.schema.internal_schema_model";
+    readonly __tangoBrand: typeof InternalSchemaModel.BRAND;
+    readonly metadata: ModelMetadata;
+    readonly schema: TSchema;
+    readonly hooks?: ModelWriteHooks<PersistedModelOutput<TSchema>>;
+    readonly objects: ModelAugmentations<TSchema> extends {
+        readonly objects: infer TObject;
+    } ? TObject : never;
+    private readonly registry;
+    private readonly normalizedRelations;
+    private readonly explicitFields?;
+    private readonly explicitRelations?;
+    private constructor();
+    static create<TSchema extends z.ZodObject<z.ZodRawShape>>(definition: ModelDefinition<TSchema>, registry: ModelRegistry): InternalSchemaModel<TSchema>;
+    static isInternalSchemaModel(value: unknown): value is AnyInternalSchemaModel;
+    static getRegistryOwner(model: AnySchemaModel): ModelRegistry;
+    static getNormalizedRelations(model: AnySchemaModel): readonly NormalizedRelationStorageDescriptor[];
+    static getExplicitFields(model: AnySchemaModel): readonly Field[] | undefined;
+    static getExplicitRelations(model: AnySchemaModel): Readonly<Record<string, RelationDef>> | undefined;
+    private static validateDefinition;
+    private static require;
+}
+export {};

package/dist/model/registry/ModelRegistry.d.ts

@@ -1,5 +1,7 @@
-import type { Model } from '../../domain/index';
-import type { ModelRef } from '../decorators/types';
+import type { Field, Model } from '../../domain/index';
+import type { ModelRef } from '../decorators/domain/ModelRef';
+import type { FinalizedStorageArtifacts } from '../fields/FinalizedStorageArtifacts';
+import type { ResolvedRelationGraph } from '../relations/ResolvedRelationGraph';
 /**
  * Registry that resolves Tango models by stable identity.
  *
@@ -9,10 +11,21 @@ import type { ModelRef } from '../decorators/types';
 export declare class ModelRegistry {
     private static globalRegistry?;
     private readonly models;
+    private version;
+    private storageCache?;
+    private relationGraphCache?;
     /**
      * Return the shared process-wide registry used by `Model(...)`.
      */
     static global(): ModelRegistry;
+    /**
+     * Return the registry currently bound to model construction work.
+     */
+    static active(): ModelRegistry;
+    /**
+     * Run work with a specific registry bound as the active construction target.
+     */
+    static runWithRegistry<T>(registry: ModelRegistry, work: () => Promise<T> | T): Promise<T>;
     /**
      * Register a model on the shared global registry.
      */
@@ -37,6 +50,10 @@ export declare class ModelRegistry {
      * Clear the shared registry, which is mainly useful in tests.
      */
     static clear(): void;
+    /**
+     * Return the owning registry for a model.
+     */
+    static getOwner(model: Model): ModelRegistry;
     /**
      * Register a model on this registry instance.
      */
@@ -57,6 +74,18 @@ export declare class ModelRegistry {
      * Resolve a string, callback, or direct model reference into a model object.
      */
     resolveRef(ref: ModelRef): Model;
+    /**
+     * Finalize storage-only artifacts for all models in this registry.
+     */
+    finalizeStorageArtifacts(): FinalizedStorageArtifacts;
+    /**
+     * Return finalized storage fields for a specific model.
+     */
+    getFinalizedFields(model: Model | string): readonly Field[];
+    /**
+     * Resolve the registry's relation graph from finalized storage artifacts.
+     */
+    getResolvedRelationGraph(): ResolvedRelationGraph;
     /**
      * Remove all registered models from this registry instance.
      */
@@ -65,4 +94,8 @@ export declare class ModelRegistry {
      * Return all registered models in insertion order.
      */
     values(): readonly Model[];
+    private bumpVersion;
+    private freezeFields;
+    private inferPrimaryKeyName;
+    private mergeStorageFields;
 }

package/dist/model/registry/index.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Domain boundary barrel: centralizes this subdomain's public contract.
+ */
+export { ModelRegistry } from './ModelRegistry';

package/dist/model/relations/NormalizedRelationStorageDescriptor.d.ts

@@ -0,0 +1,36 @@
+import type { DeleteReferentialAction, UpdateReferentialAction } from '../../domain/index';
+import type { ModelRef } from '../decorators/domain/ModelRef';
+export declare const INTERNAL_NORMALIZED_RELATION_ORIGIN: {
+    readonly FOREIGN_KEY: "foreignKey";
+    readonly ONE_TO_ONE: "oneToOne";
+    readonly MANY_TO_MANY: "manyToMany";
+};
+export type NormalizedRelationOrigin = (typeof INTERNAL_NORMALIZED_RELATION_ORIGIN)[keyof typeof INTERNAL_NORMALIZED_RELATION_ORIGIN];
+/**
+ * Registry-independent relation descriptor produced immediately after model
+ * construction.
+ *
+ * This is the handoff object between relation authoring and relation
+ * resolution. It preserves field-authored relation intent in a normalized form
+ * without yet assigning public reverse names or resolved graph edges.
+ */
+export interface NormalizedRelationStorageDescriptor {
+    edgeId: string;
+    sourceModelKey: string;
+    sourceSchemaFieldKey: string;
+    targetRef: ModelRef;
+    origin: NormalizedRelationOrigin;
+    localFieldName: string;
+    dbColumnName: string;
+    referencedTargetColumn?: string;
+    onDelete?: DeleteReferentialAction;
+    onUpdate?: UpdateReferentialAction;
+    unique?: boolean;
+    explicitForwardName?: string;
+    explicitReverseName?: string;
+    namingHint: string;
+    throughModelRef?: ModelRef;
+    throughSourceFieldName?: string;
+    throughTargetFieldName?: string;
+    provenance: 'field-decorator';
+}

package/dist/model/relations/RelationBuilder.d.ts

@@ -0,0 +1,19 @@
+import type { RelationDef } from '../../domain/index';
+/**
+ * Public authoring DSL for model-level named relations.
+ *
+ * This is the first stage of the relations subdomain. Application code uses it
+ * inside `relations: (r) => ({ ... })` to declare stable relation names and
+ * resolve ambiguity that field decorators alone cannot express.
+ *
+ * Later internal stages normalize these authored definitions and combine them
+ * with field-authored relation metadata to build the resolved relation graph.
+ */
+export declare class RelationBuilder {
+    /** Declare a one-to-many relation from this model to `target`. */
+    hasMany(target: string, foreignKey: string): RelationDef;
+    /** Declare an owning relation to a parent model. */
+    belongsTo(target: string, foreignKey: string, localKey?: string): RelationDef;
+    /** Declare a one-to-one relation from this model to `target`. */
+    hasOne(target: string, foreignKey: string): RelationDef;
+}

package/dist/model/relations/RelationDescriptorNormalizer.d.ts

@@ -0,0 +1,30 @@
+import { z } from 'zod';
+import type { NormalizedRelationStorageDescriptor } from './NormalizedRelationStorageDescriptor';
+/**
+ * Normalizes field-authored relation declarations from a model schema into the
+ * shared descriptor shape consumed by storage and relation finalization.
+ *
+ * This is the normalization stage of the relations subdomain. It sits between
+ * authoring and resolution:
+ *
+ * - authoring: decorators attach relation intent to schema fields
+ * - normalization: this class converts that intent into a registry-independent
+ *   descriptor shape
+ * - resolution: the graph builder combines those descriptors with finalized
+ *   storage artifacts and explicit relation names
+ */
+export declare class RelationDescriptorNormalizer {
+    private readonly sourceModelKey;
+    private readonly schema;
+    constructor(sourceModelKey: string, schema: z.ZodObject<z.ZodRawShape>);
+    static normalize(sourceModelKey: string, schema: z.ZodObject<z.ZodRawShape>): readonly NormalizedRelationStorageDescriptor[];
+    /**
+     * Run the field-authored relation normalization pipeline for one model
+     * schema and emit descriptors that later relation stages can resolve.
+     */
+    normalize(): readonly NormalizedRelationStorageDescriptor[];
+    private collectRelationCandidates;
+    private normalizeCandidate;
+    private buildEdgeId;
+    private deriveNamingHint;
+}

package/dist/model/relations/RelationSpec.d.ts

@@ -0,0 +1,48 @@
+export declare const INTERNAL_RELATION_PUBLIC_KIND: {
+    readonly BELONGS_TO: "belongsTo";
+    readonly HAS_ONE: "hasOne";
+    readonly HAS_MANY: "hasMany";
+    readonly MANY_TO_MANY: "manyToMany";
+};
+export declare const INTERNAL_RELATION_STORAGE_STRATEGY: {
+    readonly REFERENCE: "reference";
+    readonly REVERSE_REFERENCE: "reverse_reference";
+    readonly MANY_TO_MANY: "many_to_many";
+};
+export declare const INTERNAL_RELATION_CARDINALITY: {
+    readonly SINGLE: "single";
+    readonly MANY: "many";
+};
+export declare const INTERNAL_RELATION_PROVENANCE: {
+    readonly FIELD_DECORATOR: "field-decorator";
+    readonly RELATIONS_API: "relations-api";
+    readonly SYNTHESIZED_REVERSE: "synthesized-reverse";
+};
+export type RelationPublicKind = (typeof INTERNAL_RELATION_PUBLIC_KIND)[keyof typeof INTERNAL_RELATION_PUBLIC_KIND];
+export type RelationStorageStrategy = (typeof INTERNAL_RELATION_STORAGE_STRATEGY)[keyof typeof INTERNAL_RELATION_STORAGE_STRATEGY];
+export type RelationCardinality = (typeof INTERNAL_RELATION_CARDINALITY)[keyof typeof INTERNAL_RELATION_CARDINALITY];
+export type RelationProvenance = (typeof INTERNAL_RELATION_PROVENANCE)[keyof typeof INTERNAL_RELATION_PROVENANCE];
+/**
+ * Author-time relation intent after target resolution but before full graph
+ * pairing and naming.
+ *
+ * This type is the conceptual bridge between normalized descriptors and the
+ * fully resolved graph. It exists so the relations subdomain has a stable
+ * vocabulary for relation kinds, storage strategies, and provenance as the
+ * pipeline becomes more sophisticated.
+ */
+export interface RelationSpec {
+    edgeId: string;
+    sourceModelKey: string;
+    sourceSchemaFieldKey?: string;
+    targetModelKey: string;
+    kind: RelationPublicKind;
+    storageStrategy: RelationStorageStrategy;
+    localFieldName?: string;
+    targetFieldName?: string;
+    nameHint?: string;
+    throughModelKey?: string;
+    throughSourceFieldName?: string;
+    throughTargetFieldName?: string;
+    provenance: RelationProvenance;
+}

package/dist/model/relations/ResolvedRelationGraph.d.ts

@@ -0,0 +1,43 @@
+import type { RelationCardinality, RelationProvenance, RelationStorageStrategy, RelationPublicKind } from './RelationSpec';
+/**
+ * Fully resolved relation edge published by the registry after storage
+ * artifacts are finalized.
+ *
+ * This is the resolution-stage shape consumed by ORM-facing relation metadata.
+ * Each descriptor has final naming, cardinality, key mapping, and capability
+ * flags that describe whether the edge is currently migratable, queryable, and
+ * hydratable.
+ */
+export interface ResolvedRelationDescriptor {
+    edgeId: string;
+    sourceModelKey: string;
+    targetModelKey: string;
+    name: string;
+    inverseEdgeId?: string;
+    kind: RelationPublicKind;
+    storageStrategy: RelationStorageStrategy;
+    cardinality: RelationCardinality;
+    localFieldName?: string;
+    targetFieldName?: string;
+    capabilities: {
+        migratable: boolean;
+        queryable: boolean;
+        hydratable: boolean;
+    };
+    provenance: RelationProvenance;
+    alias: string;
+    ambiguity?: string;
+}
+/**
+ * Registry-scoped relation graph built from normalized relation descriptors,
+ * explicit relation names, and finalized storage artifacts.
+ *
+ * This is the canonical resolved relation view for query planning and future
+ * hydration work. It is versioned because relation resolution is scoped to a
+ * specific registry snapshot.
+ */
+export interface ResolvedRelationGraph {
+    version: number;
+    byModel: ReadonlyMap<string, ReadonlyMap<string, ResolvedRelationDescriptor>>;
+    byEdgeId: ReadonlyMap<string, ResolvedRelationDescriptor>;
+}