@kurotako/ir 0.1.0 → 0.3.0

package/dist/index.d.cts

@@ -19,16 +19,18 @@ declare const ScalarTypeSchema: v.PicklistSchema<["string", "boolean", "int", "b
 declare const StringFormatSchema: v.PicklistSchema<["email", "url", "uuid", "cuid", "cuid2", "ulid", "datetime", "date", "time", "duration", "ipv4", "ipv6"], undefined>;
 declare const ReferentialActionSchema: v.PicklistSchema<["cascade", "restrict", "setNull", "setDefault", "noAction"], undefined>;
 declare const IndexTypeSchema: v.PicklistSchema<["btree", "hash", "gin", "gist", "brin", "spgist"], undefined>;
-declare const FieldTypeSchema: v.VariantSchema<"kind", [v.ObjectSchema<{
-    readonly kind: v.LiteralSchema<"scalar", undefined>;
-    readonly scalar: v.PicklistSchema<["string", "boolean", "int", "bigint", "float", "decimal", "date", "datetime", "uuid", "bytes", "json"], undefined>;
-}, undefined>, v.ObjectSchema<{
-    readonly kind: v.LiteralSchema<"enum", undefined>;
-    readonly ref: v.StringSchema<undefined>;
-}, undefined>, v.ObjectSchema<{
-    readonly kind: v.LiteralSchema<"unknown", undefined>;
-    readonly hint: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
-}, undefined>], undefined>;
+/**
+ * Recursive because of the `union` variant — wrapped in `v.lazy` with an explicit
+ * `v.GenericSchema<FieldType>` annotation, exactly like `JsonValueSchema`. The
+ * schema does **not** enforce `variants.length >= 2`: degenerate unions are
+ * tolerated on read and normalised in the cross-reference pass.
+ */
+declare const FieldTypeSchema: v.GenericSchema<FieldType>;
+declare const TypeAliasSchema: v.ObjectSchema<{
+    readonly name: v.StringSchema<undefined>;
+    readonly type: v.GenericSchema<FieldType>;
+    readonly doc: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+}, undefined>;
 declare const ConstraintsSchema: v.ObjectSchema<{
     readonly min: v.OptionalSchema<v.NumberSchema<undefined>, undefined>;
     readonly max: v.OptionalSchema<v.NumberSchema<undefined>, undefined>;
@@ -48,16 +50,7 @@ declare const DefaultValueSchema: v.VariantSchema<"kind", [v.ObjectSchema<{
 }, undefined>], undefined>;
 declare const FieldSchema: v.ObjectSchema<{
     readonly name: v.StringSchema<undefined>;
-    readonly type: v.VariantSchema<"kind", [v.ObjectSchema<{
-        readonly kind: v.LiteralSchema<"scalar", undefined>;
-        readonly scalar: v.PicklistSchema<["string", "boolean", "int", "bigint", "float", "decimal", "date", "datetime", "uuid", "bytes", "json"], undefined>;
-    }, undefined>, v.ObjectSchema<{
-        readonly kind: v.LiteralSchema<"enum", undefined>;
-        readonly ref: v.StringSchema<undefined>;
-    }, undefined>, v.ObjectSchema<{
-        readonly kind: v.LiteralSchema<"unknown", undefined>;
-        readonly hint: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
-    }, undefined>], undefined>;
+    readonly type: v.GenericSchema<FieldType>;
     readonly list: v.BooleanSchema<undefined>;
     readonly optional: v.BooleanSchema<undefined>;
     readonly nullable: v.BooleanSchema<undefined>;
@@ -128,16 +121,7 @@ declare const EntitySchema: v.ObjectSchema<{
     readonly name: v.StringSchema<undefined>;
     readonly fields: v.ArraySchema<v.ObjectSchema<{
         readonly name: v.StringSchema<undefined>;
-        readonly type: v.VariantSchema<"kind", [v.ObjectSchema<{
-            readonly kind: v.LiteralSchema<"scalar", undefined>;
-            readonly scalar: v.PicklistSchema<["string", "boolean", "int", "bigint", "float", "decimal", "date", "datetime", "uuid", "bytes", "json"], undefined>;
-        }, undefined>, v.ObjectSchema<{
-            readonly kind: v.LiteralSchema<"enum", undefined>;
-            readonly ref: v.StringSchema<undefined>;
-        }, undefined>, v.ObjectSchema<{
-            readonly kind: v.LiteralSchema<"unknown", undefined>;
-            readonly hint: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
-        }, undefined>], undefined>;
+        readonly type: v.GenericSchema<FieldType>;
         readonly list: v.BooleanSchema<undefined>;
         readonly optional: v.BooleanSchema<undefined>;
         readonly nullable: v.BooleanSchema<undefined>;
@@ -161,6 +145,7 @@ declare const EntitySchema: v.ObjectSchema<{
         readonly doc: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
         readonly dbName: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
     }, undefined>, undefined>;
+    readonly additionalProperties: v.OptionalSchema<v.GenericSchema<FieldType>, undefined>;
     readonly relations: v.ArraySchema<v.ObjectSchema<{
         readonly name: v.StringSchema<undefined>;
         readonly target: v.ObjectSchema<{
@@ -207,16 +192,7 @@ declare const SourceIrSchema: v.ObjectSchema<{
         readonly name: v.StringSchema<undefined>;
         readonly fields: v.ArraySchema<v.ObjectSchema<{
             readonly name: v.StringSchema<undefined>;
-            readonly type: v.VariantSchema<"kind", [v.ObjectSchema<{
-                readonly kind: v.LiteralSchema<"scalar", undefined>;
-                readonly scalar: v.PicklistSchema<["string", "boolean", "int", "bigint", "float", "decimal", "date", "datetime", "uuid", "bytes", "json"], undefined>;
-            }, undefined>, v.ObjectSchema<{
-                readonly kind: v.LiteralSchema<"enum", undefined>;
-                readonly ref: v.StringSchema<undefined>;
-            }, undefined>, v.ObjectSchema<{
-                readonly kind: v.LiteralSchema<"unknown", undefined>;
-                readonly hint: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
-            }, undefined>], undefined>;
+            readonly type: v.GenericSchema<FieldType>;
             readonly list: v.BooleanSchema<undefined>;
             readonly optional: v.BooleanSchema<undefined>;
             readonly nullable: v.BooleanSchema<undefined>;
@@ -240,6 +216,7 @@ declare const SourceIrSchema: v.ObjectSchema<{
             readonly doc: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
             readonly dbName: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
         }, undefined>, undefined>;
+        readonly additionalProperties: v.OptionalSchema<v.GenericSchema<FieldType>, undefined>;
         readonly relations: v.ArraySchema<v.ObjectSchema<{
             readonly name: v.StringSchema<undefined>;
             readonly target: v.ObjectSchema<{
@@ -288,6 +265,11 @@ declare const SourceIrSchema: v.ObjectSchema<{
         readonly doc: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
         readonly dbName: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
     }, undefined>, undefined>;
+    readonly typeAliases: v.OptionalSchema<v.RecordSchema<v.StringSchema<undefined>, v.ObjectSchema<{
+        readonly name: v.StringSchema<undefined>;
+        readonly type: v.GenericSchema<FieldType>;
+        readonly doc: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+    }, undefined>, undefined>, undefined>;
 }, undefined>;
 declare const IrSchema: v.ObjectSchema<{
     readonly irVersion: v.StringSchema<undefined>;
@@ -299,16 +281,7 @@ declare const IrSchema: v.ObjectSchema<{
             readonly name: v.StringSchema<undefined>;
             readonly fields: v.ArraySchema<v.ObjectSchema<{
                 readonly name: v.StringSchema<undefined>;
-                readonly type: v.VariantSchema<"kind", [v.ObjectSchema<{
-                    readonly kind: v.LiteralSchema<"scalar", undefined>;
-                    readonly scalar: v.PicklistSchema<["string", "boolean", "int", "bigint", "float", "decimal", "date", "datetime", "uuid", "bytes", "json"], undefined>;
-                }, undefined>, v.ObjectSchema<{
-                    readonly kind: v.LiteralSchema<"enum", undefined>;
-                    readonly ref: v.StringSchema<undefined>;
-                }, undefined>, v.ObjectSchema<{
-                    readonly kind: v.LiteralSchema<"unknown", undefined>;
-                    readonly hint: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
-                }, undefined>], undefined>;
+                readonly type: v.GenericSchema<FieldType>;
                 readonly list: v.BooleanSchema<undefined>;
                 readonly optional: v.BooleanSchema<undefined>;
                 readonly nullable: v.BooleanSchema<undefined>;
@@ -332,6 +305,7 @@ declare const IrSchema: v.ObjectSchema<{
                 readonly doc: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
                 readonly dbName: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
             }, undefined>, undefined>;
+            readonly additionalProperties: v.OptionalSchema<v.GenericSchema<FieldType>, undefined>;
             readonly relations: v.ArraySchema<v.ObjectSchema<{
                 readonly name: v.StringSchema<undefined>;
                 readonly target: v.ObjectSchema<{
@@ -380,6 +354,11 @@ declare const IrSchema: v.ObjectSchema<{
             readonly doc: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
             readonly dbName: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
         }, undefined>, undefined>;
+        readonly typeAliases: v.OptionalSchema<v.RecordSchema<v.StringSchema<undefined>, v.ObjectSchema<{
+            readonly name: v.StringSchema<undefined>;
+            readonly type: v.GenericSchema<FieldType>;
+            readonly doc: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+        }, undefined>, undefined>, undefined>;
     }, undefined>, undefined>;
 }, undefined>;
 
@@ -389,12 +368,44 @@ declare const IrSchema: v.ObjectSchema<{
  * hand-written interface here.
  */
 
+/**
+ * Hand-written because `FieldTypeSchema` is recursive (`union` variant) and
+ * `v.lazy` needs an explicit type — same pattern as `JsonValue`.
+ * `ref` is a bare name resolved against the same source (`entities` then
+ * `typeAliases`); there is no namespace qualifier in v1.
+ */
+type FieldType = {
+    kind: 'scalar';
+    scalar: ScalarType;
+} | {
+    kind: 'enum';
+    ref: string;
+} | {
+    kind: 'unknown';
+    hint?: string;
+} | {
+    kind: 'ref';
+    ref: string;
+} | {
+    kind: 'map';
+    value: FieldType;
+} | {
+    kind: 'array';
+    element: FieldType;
+} | {
+    kind: 'union';
+    variants: FieldType[];
+    discriminator?: {
+        propertyName: string;
+        mapping?: Record<string, string>;
+    };
+};
 type IR = v.InferOutput<typeof IrSchema>;
 type SourceIR = v.InferOutput<typeof SourceIrSchema>;
 type Entity = v.InferOutput<typeof EntitySchema>;
 type Field = v.InferOutput<typeof FieldSchema>;
-type FieldType = v.InferOutput<typeof FieldTypeSchema>;
 type ScalarType = v.InferOutput<typeof ScalarTypeSchema>;
+type TypeAlias = v.InferOutput<typeof TypeAliasSchema>;
 type StringFormat = v.InferOutput<typeof StringFormatSchema>;
 type ReferentialAction = v.InferOutput<typeof ReferentialActionSchema>;
 type IndexType = v.InferOutput<typeof IndexTypeSchema>;
@@ -407,7 +418,7 @@ type EnumValue = v.InferOutput<typeof EnumValueSchema>;
 type IndexDef = v.InferOutput<typeof IndexDefSchema>;
 type CompositeUnique = v.InferOutput<typeof CompositeUniqueSchema>;
 
-type IrIssueCode = 'version_incompatible' | 'namespace_key_mismatch' | 'entity_key_mismatch' | 'duplicate_field' | 'duplicate_enum_value' | 'unresolved_enum_ref' | 'unresolved_field_ref' | 'unresolved_relation_target' | 'unresolved_back_relation' | 'invalid_constraint' | 'invalid_regex' | 'shape';
+type IrIssueCode = 'version_incompatible' | 'namespace_key_mismatch' | 'entity_key_mismatch' | 'duplicate_field' | 'duplicate_enum_value' | 'unresolved_enum_ref' | 'unresolved_field_ref' | 'unresolved_relation_target' | 'unresolved_back_relation' | 'unresolved_ref' | 'unresolved_type_alias' | 'type_alias_key_mismatch' | 'degenerate_union' | 'union_cycle' | 'invalid_constraint' | 'invalid_regex' | 'shape';
 interface IrIssue {
     path: string;
     code: IrIssueCode;
@@ -416,6 +427,7 @@ interface IrIssue {
 type IrValidation<T> = {
     ok: true;
     value: T;
+    info?: IrIssue[];
 } | {
     ok: false;
     issues: IrIssue[];
@@ -443,9 +455,30 @@ interface EnumBuilder {
     doc(text: string): this;
     dbName(name: string): this;
 }
+/** Type-setters shared by `UnionBuilder` and `TypeAliasBuilder`. */
+interface TypeVariantBuilder {
+    scalar(t: ScalarType): this;
+    enum(ref: string): this;
+    ref(name: string): this;
+    union(build: (u: UnionBuilder) => void): this;
+    map(build: (value: TypeVariantBuilder) => void): this;
+    array(build: (element: TypeVariantBuilder) => void): this;
+    unknown(hint?: string): this;
+}
+interface UnionBuilder extends TypeVariantBuilder {
+    /** `mapping` values must name a `ref` variant of this union. */
+    discriminator(propertyName: string, mapping?: Record<string, string>): this;
+}
+interface TypeAliasBuilder extends TypeVariantBuilder {
+    doc(text: string): this;
+}
 interface FieldBuilder {
     scalar(t: ScalarType): this;
     enum(ref: string): this;
+    ref(name: string): this;
+    union(build: (u: UnionBuilder) => void): this;
+    map(build: (value: TypeVariantBuilder) => void): this;
+    array(build: (element: TypeVariantBuilder) => void): this;
     unknown(hint?: string): this;
     list(): this;
     optional(): this;
@@ -476,6 +509,7 @@ interface RelationBuilder {
 }
 interface EntityBuilder {
     field(name: string, def: (f: FieldBuilder) => void): this;
+    additionalProperties(def: (value: TypeVariantBuilder) => void): this;
     relation(name: string, def: (r: RelationBuilder) => void): this;
     localEnum(name: string, def: (e: EnumBuilder) => void): this;
     primaryKey(...fields: string[]): this;
@@ -492,6 +526,7 @@ interface EntityBuilder {
 interface SourceIrBuilder {
     addEnum(name: string, def: (e: EnumBuilder) => void): this;
     addEntity(name: string, def: (e: EntityBuilder) => void): this;
+    addTypeAlias(name: string, def: (t: TypeAliasBuilder) => void): this;
     build(): SourceIR;
 }
 declare function createSourceIR(init: {
@@ -510,6 +545,35 @@ declare function getSource(ir: IR, namespace: string): SourceIR | undefined;
 declare function resolveEntity(ir: IR, namespace: string, name: string): Entity | undefined;
 /** Entity-local enums shadow source-level enums of the same name. */
 declare function resolveEnum(source: SourceIR, entity: Entity | undefined, ref: string): EnumDef | undefined;
+/**
+ * Resolve a `{ kind: 'ref' }` name against the same source: an entity first,
+ * then a type alias. Same-namespace only — v1 has no namespace qualifier.
+ */
+declare function resolveRef(source: SourceIR, ref: string): Entity | TypeAlias | undefined;
+declare function resolveTypeAlias(source: SourceIR, name: string): TypeAlias | undefined;
+declare function iterTypeAliases(ir: IR): Iterable<{
+    namespace: string;
+    alias: TypeAlias;
+}>;
+/** Every `{ kind: 'ref' }` name reachable from a field type (through unions). */
+declare function collectRefNames(type: FieldType, into?: Set<string>): Set<string>;
+/**
+ * Names of entities / type aliases that take part in at least one `ref` cycle
+ * within `source` — following field-type `ref`, alias `type` `ref` and union
+ * variant `ref` edges. Mirrors the informational `union_cycle` pass in
+ * `validate.ts`; a generator consumes this (through `GenerateContext.cycles`)
+ * to decide which references must be `z.lazy`-wrapped / widened rather than
+ * emitted as a bare forward reference.
+ */
+declare function refCycleMembers(source: SourceIR): Set<string>;
+/**
+ * Flatten nested unions into a single variant list and drop
+ * structurally-identical duplicates, preserving first-seen order. The
+ * discriminator of a nested union is not carried up.
+ */
+declare function flattenUnion(type: Extract<FieldType, {
+    kind: 'union';
+}>): FieldType[];
 /**
  * A relation is cross-source when its target namespace is anything other than
  * the entity's own namespace — including the "absent" (empty) namespace, which
@@ -566,11 +630,11 @@ declare function scalarTsType(type: FieldType): string;
  * (independent versioning): a single string, bumped only on a breaking change
  * to the format itself.
  */
-declare const IR_VERSION = "1";
+declare const IR_VERSION = "4";
 /**
  * Whether an IR produced against `irVersion` can be consumed by this build.
  * v1 rule: strict equality.
  */
 declare function isCompatible(irVersion: string): boolean;
 
-export { type CompositeUnique, CompositeUniqueSchema, type Constraints, ConstraintsSchema, type DefaultValue, DefaultValueSchema, type Entity, type EntityBuilder, EntitySchema, type EnumBuilder, type EnumDef, EnumDefSchema, type EnumValue, EnumValueSchema, type Field, type FieldBuilder, FieldSchema, type FieldType, FieldTypeSchema, type IR, IR_VERSION, type IndexDef, IndexDefSchema, type IndexType, IndexTypeSchema, IrBuildError, type IrIssue, type IrIssueCode, IrSchema, type IrValidation, IrValidationError, type JsonValue, JsonValueSchema, type ReferentialAction, ReferentialActionSchema, type Relation, type RelationBuilder, RelationSchema, type RelationTarget, RelationTargetSchema, type ScalarTsType, type ScalarType, ScalarTypeSchema, type SourceIR, type SourceIrBuilder, SourceIrSchema, type StringFormat, StringFormatSchema, assertIR, assertSourceIR, createFields, createSourceIR, getSource, isCompatible, isCreateOptional, isCrossSource, isDbAssigned, iterEntities, iterFields, parseIR, primaryKeyFields, resolveEntity, resolveEnum, resolveRelationTarget, scalarTsType, updateFields, validateIR, validateSourceIR };
+export { type CompositeUnique, CompositeUniqueSchema, type Constraints, ConstraintsSchema, type DefaultValue, DefaultValueSchema, type Entity, type EntityBuilder, EntitySchema, type EnumBuilder, type EnumDef, EnumDefSchema, type EnumValue, EnumValueSchema, type Field, type FieldBuilder, FieldSchema, type FieldType, FieldTypeSchema, type IR, IR_VERSION, type IndexDef, IndexDefSchema, type IndexType, IndexTypeSchema, IrBuildError, type IrIssue, type IrIssueCode, IrSchema, type IrValidation, IrValidationError, type JsonValue, JsonValueSchema, type ReferentialAction, ReferentialActionSchema, type Relation, type RelationBuilder, RelationSchema, type RelationTarget, RelationTargetSchema, type ScalarTsType, type ScalarType, ScalarTypeSchema, type SourceIR, type SourceIrBuilder, SourceIrSchema, type StringFormat, StringFormatSchema, type TypeAlias, type TypeAliasBuilder, TypeAliasSchema, type TypeVariantBuilder, type UnionBuilder, assertIR, assertSourceIR, collectRefNames, createFields, createSourceIR, flattenUnion, getSource, isCompatible, isCreateOptional, isCrossSource, isDbAssigned, iterEntities, iterFields, iterTypeAliases, parseIR, primaryKeyFields, refCycleMembers, resolveEntity, resolveEnum, resolveRef, resolveRelationTarget, resolveTypeAlias, scalarTsType, updateFields, validateIR, validateSourceIR };

package/dist/index.d.ts

@@ -19,16 +19,18 @@ declare const ScalarTypeSchema: v.PicklistSchema<["string", "boolean", "int", "b
 declare const StringFormatSchema: v.PicklistSchema<["email", "url", "uuid", "cuid", "cuid2", "ulid", "datetime", "date", "time", "duration", "ipv4", "ipv6"], undefined>;
 declare const ReferentialActionSchema: v.PicklistSchema<["cascade", "restrict", "setNull", "setDefault", "noAction"], undefined>;
 declare const IndexTypeSchema: v.PicklistSchema<["btree", "hash", "gin", "gist", "brin", "spgist"], undefined>;
-declare const FieldTypeSchema: v.VariantSchema<"kind", [v.ObjectSchema<{
-    readonly kind: v.LiteralSchema<"scalar", undefined>;
-    readonly scalar: v.PicklistSchema<["string", "boolean", "int", "bigint", "float", "decimal", "date", "datetime", "uuid", "bytes", "json"], undefined>;
-}, undefined>, v.ObjectSchema<{
-    readonly kind: v.LiteralSchema<"enum", undefined>;
-    readonly ref: v.StringSchema<undefined>;
-}, undefined>, v.ObjectSchema<{
-    readonly kind: v.LiteralSchema<"unknown", undefined>;
-    readonly hint: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
-}, undefined>], undefined>;
+/**
+ * Recursive because of the `union` variant — wrapped in `v.lazy` with an explicit
+ * `v.GenericSchema<FieldType>` annotation, exactly like `JsonValueSchema`. The
+ * schema does **not** enforce `variants.length >= 2`: degenerate unions are
+ * tolerated on read and normalised in the cross-reference pass.
+ */
+declare const FieldTypeSchema: v.GenericSchema<FieldType>;
+declare const TypeAliasSchema: v.ObjectSchema<{
+    readonly name: v.StringSchema<undefined>;
+    readonly type: v.GenericSchema<FieldType>;
+    readonly doc: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+}, undefined>;
 declare const ConstraintsSchema: v.ObjectSchema<{
     readonly min: v.OptionalSchema<v.NumberSchema<undefined>, undefined>;
     readonly max: v.OptionalSchema<v.NumberSchema<undefined>, undefined>;
@@ -48,16 +50,7 @@ declare const DefaultValueSchema: v.VariantSchema<"kind", [v.ObjectSchema<{
 }, undefined>], undefined>;
 declare const FieldSchema: v.ObjectSchema<{
     readonly name: v.StringSchema<undefined>;
-    readonly type: v.VariantSchema<"kind", [v.ObjectSchema<{
-        readonly kind: v.LiteralSchema<"scalar", undefined>;
-        readonly scalar: v.PicklistSchema<["string", "boolean", "int", "bigint", "float", "decimal", "date", "datetime", "uuid", "bytes", "json"], undefined>;
-    }, undefined>, v.ObjectSchema<{
-        readonly kind: v.LiteralSchema<"enum", undefined>;
-        readonly ref: v.StringSchema<undefined>;
-    }, undefined>, v.ObjectSchema<{
-        readonly kind: v.LiteralSchema<"unknown", undefined>;
-        readonly hint: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
-    }, undefined>], undefined>;
+    readonly type: v.GenericSchema<FieldType>;
     readonly list: v.BooleanSchema<undefined>;
     readonly optional: v.BooleanSchema<undefined>;
     readonly nullable: v.BooleanSchema<undefined>;
@@ -128,16 +121,7 @@ declare const EntitySchema: v.ObjectSchema<{
     readonly name: v.StringSchema<undefined>;
     readonly fields: v.ArraySchema<v.ObjectSchema<{
         readonly name: v.StringSchema<undefined>;
-        readonly type: v.VariantSchema<"kind", [v.ObjectSchema<{
-            readonly kind: v.LiteralSchema<"scalar", undefined>;
-            readonly scalar: v.PicklistSchema<["string", "boolean", "int", "bigint", "float", "decimal", "date", "datetime", "uuid", "bytes", "json"], undefined>;
-        }, undefined>, v.ObjectSchema<{
-            readonly kind: v.LiteralSchema<"enum", undefined>;
-            readonly ref: v.StringSchema<undefined>;
-        }, undefined>, v.ObjectSchema<{
-            readonly kind: v.LiteralSchema<"unknown", undefined>;
-            readonly hint: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
-        }, undefined>], undefined>;
+        readonly type: v.GenericSchema<FieldType>;
         readonly list: v.BooleanSchema<undefined>;
         readonly optional: v.BooleanSchema<undefined>;
         readonly nullable: v.BooleanSchema<undefined>;
@@ -161,6 +145,7 @@ declare const EntitySchema: v.ObjectSchema<{
         readonly doc: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
         readonly dbName: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
     }, undefined>, undefined>;
+    readonly additionalProperties: v.OptionalSchema<v.GenericSchema<FieldType>, undefined>;
     readonly relations: v.ArraySchema<v.ObjectSchema<{
         readonly name: v.StringSchema<undefined>;
         readonly target: v.ObjectSchema<{
@@ -207,16 +192,7 @@ declare const SourceIrSchema: v.ObjectSchema<{
         readonly name: v.StringSchema<undefined>;
         readonly fields: v.ArraySchema<v.ObjectSchema<{
             readonly name: v.StringSchema<undefined>;
-            readonly type: v.VariantSchema<"kind", [v.ObjectSchema<{
-                readonly kind: v.LiteralSchema<"scalar", undefined>;
-                readonly scalar: v.PicklistSchema<["string", "boolean", "int", "bigint", "float", "decimal", "date", "datetime", "uuid", "bytes", "json"], undefined>;
-            }, undefined>, v.ObjectSchema<{
-                readonly kind: v.LiteralSchema<"enum", undefined>;
-                readonly ref: v.StringSchema<undefined>;
-            }, undefined>, v.ObjectSchema<{
-                readonly kind: v.LiteralSchema<"unknown", undefined>;
-                readonly hint: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
-            }, undefined>], undefined>;
+            readonly type: v.GenericSchema<FieldType>;
             readonly list: v.BooleanSchema<undefined>;
             readonly optional: v.BooleanSchema<undefined>;
             readonly nullable: v.BooleanSchema<undefined>;
@@ -240,6 +216,7 @@ declare const SourceIrSchema: v.ObjectSchema<{
             readonly doc: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
             readonly dbName: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
         }, undefined>, undefined>;
+        readonly additionalProperties: v.OptionalSchema<v.GenericSchema<FieldType>, undefined>;
         readonly relations: v.ArraySchema<v.ObjectSchema<{
             readonly name: v.StringSchema<undefined>;
             readonly target: v.ObjectSchema<{
@@ -288,6 +265,11 @@ declare const SourceIrSchema: v.ObjectSchema<{
         readonly doc: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
         readonly dbName: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
     }, undefined>, undefined>;
+    readonly typeAliases: v.OptionalSchema<v.RecordSchema<v.StringSchema<undefined>, v.ObjectSchema<{
+        readonly name: v.StringSchema<undefined>;
+        readonly type: v.GenericSchema<FieldType>;
+        readonly doc: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+    }, undefined>, undefined>, undefined>;
 }, undefined>;
 declare const IrSchema: v.ObjectSchema<{
     readonly irVersion: v.StringSchema<undefined>;
@@ -299,16 +281,7 @@ declare const IrSchema: v.ObjectSchema<{
             readonly name: v.StringSchema<undefined>;
             readonly fields: v.ArraySchema<v.ObjectSchema<{
                 readonly name: v.StringSchema<undefined>;
-                readonly type: v.VariantSchema<"kind", [v.ObjectSchema<{
-                    readonly kind: v.LiteralSchema<"scalar", undefined>;
-                    readonly scalar: v.PicklistSchema<["string", "boolean", "int", "bigint", "float", "decimal", "date", "datetime", "uuid", "bytes", "json"], undefined>;
-                }, undefined>, v.ObjectSchema<{
-                    readonly kind: v.LiteralSchema<"enum", undefined>;
-                    readonly ref: v.StringSchema<undefined>;
-                }, undefined>, v.ObjectSchema<{
-                    readonly kind: v.LiteralSchema<"unknown", undefined>;
-                    readonly hint: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
-                }, undefined>], undefined>;
+                readonly type: v.GenericSchema<FieldType>;
                 readonly list: v.BooleanSchema<undefined>;
                 readonly optional: v.BooleanSchema<undefined>;
                 readonly nullable: v.BooleanSchema<undefined>;
@@ -332,6 +305,7 @@ declare const IrSchema: v.ObjectSchema<{
                 readonly doc: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
                 readonly dbName: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
             }, undefined>, undefined>;
+            readonly additionalProperties: v.OptionalSchema<v.GenericSchema<FieldType>, undefined>;
             readonly relations: v.ArraySchema<v.ObjectSchema<{
                 readonly name: v.StringSchema<undefined>;
                 readonly target: v.ObjectSchema<{
@@ -380,6 +354,11 @@ declare const IrSchema: v.ObjectSchema<{
             readonly doc: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
             readonly dbName: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
         }, undefined>, undefined>;
+        readonly typeAliases: v.OptionalSchema<v.RecordSchema<v.StringSchema<undefined>, v.ObjectSchema<{
+            readonly name: v.StringSchema<undefined>;
+            readonly type: v.GenericSchema<FieldType>;
+            readonly doc: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+        }, undefined>, undefined>, undefined>;
     }, undefined>, undefined>;
 }, undefined>;
 
@@ -389,12 +368,44 @@ declare const IrSchema: v.ObjectSchema<{
  * hand-written interface here.
  */
 
+/**
+ * Hand-written because `FieldTypeSchema` is recursive (`union` variant) and
+ * `v.lazy` needs an explicit type — same pattern as `JsonValue`.
+ * `ref` is a bare name resolved against the same source (`entities` then
+ * `typeAliases`); there is no namespace qualifier in v1.
+ */
+type FieldType = {
+    kind: 'scalar';
+    scalar: ScalarType;
+} | {
+    kind: 'enum';
+    ref: string;
+} | {
+    kind: 'unknown';
+    hint?: string;
+} | {
+    kind: 'ref';
+    ref: string;
+} | {
+    kind: 'map';
+    value: FieldType;
+} | {
+    kind: 'array';
+    element: FieldType;
+} | {
+    kind: 'union';
+    variants: FieldType[];
+    discriminator?: {
+        propertyName: string;
+        mapping?: Record<string, string>;
+    };
+};
 type IR = v.InferOutput<typeof IrSchema>;
 type SourceIR = v.InferOutput<typeof SourceIrSchema>;
 type Entity = v.InferOutput<typeof EntitySchema>;
 type Field = v.InferOutput<typeof FieldSchema>;
-type FieldType = v.InferOutput<typeof FieldTypeSchema>;
 type ScalarType = v.InferOutput<typeof ScalarTypeSchema>;
+type TypeAlias = v.InferOutput<typeof TypeAliasSchema>;
 type StringFormat = v.InferOutput<typeof StringFormatSchema>;
 type ReferentialAction = v.InferOutput<typeof ReferentialActionSchema>;
 type IndexType = v.InferOutput<typeof IndexTypeSchema>;
@@ -407,7 +418,7 @@ type EnumValue = v.InferOutput<typeof EnumValueSchema>;
 type IndexDef = v.InferOutput<typeof IndexDefSchema>;
 type CompositeUnique = v.InferOutput<typeof CompositeUniqueSchema>;
 
-type IrIssueCode = 'version_incompatible' | 'namespace_key_mismatch' | 'entity_key_mismatch' | 'duplicate_field' | 'duplicate_enum_value' | 'unresolved_enum_ref' | 'unresolved_field_ref' | 'unresolved_relation_target' | 'unresolved_back_relation' | 'invalid_constraint' | 'invalid_regex' | 'shape';
+type IrIssueCode = 'version_incompatible' | 'namespace_key_mismatch' | 'entity_key_mismatch' | 'duplicate_field' | 'duplicate_enum_value' | 'unresolved_enum_ref' | 'unresolved_field_ref' | 'unresolved_relation_target' | 'unresolved_back_relation' | 'unresolved_ref' | 'unresolved_type_alias' | 'type_alias_key_mismatch' | 'degenerate_union' | 'union_cycle' | 'invalid_constraint' | 'invalid_regex' | 'shape';
 interface IrIssue {
     path: string;
     code: IrIssueCode;
@@ -416,6 +427,7 @@ interface IrIssue {
 type IrValidation<T> = {
     ok: true;
     value: T;
+    info?: IrIssue[];
 } | {
     ok: false;
     issues: IrIssue[];
@@ -443,9 +455,30 @@ interface EnumBuilder {
     doc(text: string): this;
     dbName(name: string): this;
 }
+/** Type-setters shared by `UnionBuilder` and `TypeAliasBuilder`. */
+interface TypeVariantBuilder {
+    scalar(t: ScalarType): this;
+    enum(ref: string): this;
+    ref(name: string): this;
+    union(build: (u: UnionBuilder) => void): this;
+    map(build: (value: TypeVariantBuilder) => void): this;
+    array(build: (element: TypeVariantBuilder) => void): this;
+    unknown(hint?: string): this;
+}
+interface UnionBuilder extends TypeVariantBuilder {
+    /** `mapping` values must name a `ref` variant of this union. */
+    discriminator(propertyName: string, mapping?: Record<string, string>): this;
+}
+interface TypeAliasBuilder extends TypeVariantBuilder {
+    doc(text: string): this;
+}
 interface FieldBuilder {
     scalar(t: ScalarType): this;
     enum(ref: string): this;
+    ref(name: string): this;
+    union(build: (u: UnionBuilder) => void): this;
+    map(build: (value: TypeVariantBuilder) => void): this;
+    array(build: (element: TypeVariantBuilder) => void): this;
     unknown(hint?: string): this;
     list(): this;
     optional(): this;
@@ -476,6 +509,7 @@ interface RelationBuilder {
 }
 interface EntityBuilder {
     field(name: string, def: (f: FieldBuilder) => void): this;
+    additionalProperties(def: (value: TypeVariantBuilder) => void): this;
     relation(name: string, def: (r: RelationBuilder) => void): this;
     localEnum(name: string, def: (e: EnumBuilder) => void): this;
     primaryKey(...fields: string[]): this;
@@ -492,6 +526,7 @@ interface EntityBuilder {
 interface SourceIrBuilder {
     addEnum(name: string, def: (e: EnumBuilder) => void): this;
     addEntity(name: string, def: (e: EntityBuilder) => void): this;
+    addTypeAlias(name: string, def: (t: TypeAliasBuilder) => void): this;
     build(): SourceIR;
 }
 declare function createSourceIR(init: {
@@ -510,6 +545,35 @@ declare function getSource(ir: IR, namespace: string): SourceIR | undefined;
 declare function resolveEntity(ir: IR, namespace: string, name: string): Entity | undefined;
 /** Entity-local enums shadow source-level enums of the same name. */
 declare function resolveEnum(source: SourceIR, entity: Entity | undefined, ref: string): EnumDef | undefined;
+/**
+ * Resolve a `{ kind: 'ref' }` name against the same source: an entity first,
+ * then a type alias. Same-namespace only — v1 has no namespace qualifier.
+ */
+declare function resolveRef(source: SourceIR, ref: string): Entity | TypeAlias | undefined;
+declare function resolveTypeAlias(source: SourceIR, name: string): TypeAlias | undefined;
+declare function iterTypeAliases(ir: IR): Iterable<{
+    namespace: string;
+    alias: TypeAlias;
+}>;
+/** Every `{ kind: 'ref' }` name reachable from a field type (through unions). */
+declare function collectRefNames(type: FieldType, into?: Set<string>): Set<string>;
+/**
+ * Names of entities / type aliases that take part in at least one `ref` cycle
+ * within `source` — following field-type `ref`, alias `type` `ref` and union
+ * variant `ref` edges. Mirrors the informational `union_cycle` pass in
+ * `validate.ts`; a generator consumes this (through `GenerateContext.cycles`)
+ * to decide which references must be `z.lazy`-wrapped / widened rather than
+ * emitted as a bare forward reference.
+ */
+declare function refCycleMembers(source: SourceIR): Set<string>;
+/**
+ * Flatten nested unions into a single variant list and drop
+ * structurally-identical duplicates, preserving first-seen order. The
+ * discriminator of a nested union is not carried up.
+ */
+declare function flattenUnion(type: Extract<FieldType, {
+    kind: 'union';
+}>): FieldType[];
 /**
  * A relation is cross-source when its target namespace is anything other than
  * the entity's own namespace — including the "absent" (empty) namespace, which
@@ -566,11 +630,11 @@ declare function scalarTsType(type: FieldType): string;
  * (independent versioning): a single string, bumped only on a breaking change
  * to the format itself.
  */
-declare const IR_VERSION = "1";
+declare const IR_VERSION = "4";
 /**
  * Whether an IR produced against `irVersion` can be consumed by this build.
  * v1 rule: strict equality.
  */
 declare function isCompatible(irVersion: string): boolean;
 
-export { type CompositeUnique, CompositeUniqueSchema, type Constraints, ConstraintsSchema, type DefaultValue, DefaultValueSchema, type Entity, type EntityBuilder, EntitySchema, type EnumBuilder, type EnumDef, EnumDefSchema, type EnumValue, EnumValueSchema, type Field, type FieldBuilder, FieldSchema, type FieldType, FieldTypeSchema, type IR, IR_VERSION, type IndexDef, IndexDefSchema, type IndexType, IndexTypeSchema, IrBuildError, type IrIssue, type IrIssueCode, IrSchema, type IrValidation, IrValidationError, type JsonValue, JsonValueSchema, type ReferentialAction, ReferentialActionSchema, type Relation, type RelationBuilder, RelationSchema, type RelationTarget, RelationTargetSchema, type ScalarTsType, type ScalarType, ScalarTypeSchema, type SourceIR, type SourceIrBuilder, SourceIrSchema, type StringFormat, StringFormatSchema, assertIR, assertSourceIR, createFields, createSourceIR, getSource, isCompatible, isCreateOptional, isCrossSource, isDbAssigned, iterEntities, iterFields, parseIR, primaryKeyFields, resolveEntity, resolveEnum, resolveRelationTarget, scalarTsType, updateFields, validateIR, validateSourceIR };
+export { type CompositeUnique, CompositeUniqueSchema, type Constraints, ConstraintsSchema, type DefaultValue, DefaultValueSchema, type Entity, type EntityBuilder, EntitySchema, type EnumBuilder, type EnumDef, EnumDefSchema, type EnumValue, EnumValueSchema, type Field, type FieldBuilder, FieldSchema, type FieldType, FieldTypeSchema, type IR, IR_VERSION, type IndexDef, IndexDefSchema, type IndexType, IndexTypeSchema, IrBuildError, type IrIssue, type IrIssueCode, IrSchema, type IrValidation, IrValidationError, type JsonValue, JsonValueSchema, type ReferentialAction, ReferentialActionSchema, type Relation, type RelationBuilder, RelationSchema, type RelationTarget, RelationTargetSchema, type ScalarTsType, type ScalarType, ScalarTypeSchema, type SourceIR, type SourceIrBuilder, SourceIrSchema, type StringFormat, StringFormatSchema, type TypeAlias, type TypeAliasBuilder, TypeAliasSchema, type TypeVariantBuilder, type UnionBuilder, assertIR, assertSourceIR, collectRefNames, createFields, createSourceIR, flattenUnion, getSource, isCompatible, isCreateOptional, isCrossSource, isDbAssigned, iterEntities, iterFields, iterTypeAliases, parseIR, primaryKeyFields, refCycleMembers, resolveEntity, resolveEnum, resolveRef, resolveRelationTarget, resolveTypeAlias, scalarTsType, updateFields, validateIR, validateSourceIR };