typesea 0.1.0 → 0.2.0

package/dist/schema/freeze.js

@@ -1,17 +1,23 @@
 /**
  * @file schema/freeze.ts
  * @brief Schema freezing and collection hardening.
+ * @details Freezing hardens builder output before execution engines or exporters rely on
+ * schema identity and shape stability.
  */
 import { SchemaTag, StringCheckTag } from "../kind/index.js";
 import { isPlainRegExp } from "./common.js";
 /**
  * @brief freeze schema.
+ * @details Freezing hardens builder output before execution engines or exporters rely on
+ * schema identity and shape stability.
  */
 export function freezeSchema(schema) {
     return freezeSchemaInner(schema, new WeakSet());
 }
 /**
  * @brief freeze schema inner.
+ * @details Freezing hardens builder output before execution engines or exporters rely on
+ * schema identity and shape stability.
  */
 function freezeSchemaInner(schema, frozen) {
     if (frozen.has(schema)) {
@@ -72,6 +78,8 @@ function freezeSchemaInner(schema, frozen) {
 }
 /**
  * @brief freeze array.
+ * @details Freezing hardens builder output before execution engines or exporters rely on
+ * schema identity and shape stability.
  */
 function freezeArray(values, frozen) {
     for (let index = 0; index < values.length; index += 1) {
@@ -85,6 +93,8 @@ function freezeArray(values, frozen) {
 }
 /**
  * @brief freeze string checks.
+ * @details Freezing hardens builder output before execution engines or exporters rely on
+ * schema identity and shape stability.
  */
 function freezeStringChecks(values, frozen) {
     for (let index = 0; index < values.length; index += 1) {
@@ -102,6 +112,8 @@ function freezeStringChecks(values, frozen) {
 }
 /**
  * @brief freeze regex check.
+ * @details Freezing hardens builder output before execution engines or exporters rely on
+ * schema identity and shape stability.
  */
 function freezeRegexCheck(check) {
     const regex = check.regex;
@@ -125,6 +137,8 @@ function freezeRegexCheck(check) {
 }
 /**
  * @brief freeze schema array.
+ * @details Freezing hardens builder output before execution engines or exporters rely on
+ * schema identity and shape stability.
  */
 function freezeSchemaArray(values, frozen) {
     for (let index = 0; index < values.length; index += 1) {
@@ -137,6 +151,8 @@ function freezeSchemaArray(values, frozen) {
 }
 /**
  * @brief freeze object entries.
+ * @details Freezing hardens builder output before execution engines or exporters rely on
+ * schema identity and shape stability.
  */
 function freezeObjectEntries(entries, frozen) {
     for (let index = 0; index < entries.length; index += 1) {
@@ -150,6 +166,8 @@ function freezeObjectEntries(entries, frozen) {
 }
 /**
  * @brief freeze discriminated union cases.
+ * @details Freezing hardens builder output before execution engines or exporters rely on
+ * schema identity and shape stability.
  */
 function freezeDiscriminatedUnionCases(cases, frozen) {
     for (let index = 0; index < cases.length; index += 1) {

package/dist/schema/index.d.ts

@@ -1,6 +1,8 @@
 /**
  * @file schema/index.ts
  * @brief Schema module aggregate.
+ * @details Schema helpers enforce construction-time invariants before values reach
+ * validation, compilation, or export.
  */
 export type { ArraySchema, BigIntSchema, BooleanSchema, BrandSchema, DiscriminatedUnionCase, DiscriminatedUnionSchema, IntersectionSchema, LazySchema, LiteralSchema, LiteralValue, NeverSchema, NullableSchema, NumberCheck, NumberGteCheck, NumberIntegerCheck, NumberLteCheck, NumberSchema, ObjectEntry, ObjectKeyLookup, ObjectSchema, OptionalSchema, RecordSchema, RefineSchema, Schema, StringCheck, StringMaxCheck, StringMinCheck, StringRegexCheck, StringSchema, StringUuidCheck, SymbolSchema, TupleSchema, UndefinedableSchema, UnionSchema, UnknownSchema } from "./types.js";
 export { UUID_PATTERN } from "./types.js";
@@ -8,4 +10,5 @@ export { isLiteralValue } from "./literal.js";
 export { isSchemaValue } from "./validate.js";
 export { freezeSchema } from "./freeze.js";
 export { resolveLazySchema } from "./lazy.js";
+export { schemaCanAcceptUndefined } from "./undefined.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/schema/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/schema/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,YAAY,EACV,WAAW,EACX,YAAY,EACZ,aAAa,EACb,WAAW,EACX,sBAAsB,EACtB,wBAAwB,EACxB,kBAAkB,EAClB,UAAU,EACV,aAAa,EACb,YAAY,EACZ,WAAW,EACX,cAAc,EACd,WAAW,EACX,cAAc,EACd,kBAAkB,EAClB,cAAc,EACd,YAAY,EACZ,WAAW,EACX,eAAe,EACf,YAAY,EACZ,cAAc,EACd,YAAY,EACZ,YAAY,EACZ,MAAM,EACN,WAAW,EACX,cAAc,EACd,cAAc,EACd,gBAAgB,EAChB,YAAY,EACZ,eAAe,EACf,YAAY,EACZ,WAAW,EACX,mBAAmB,EACnB,WAAW,EACX,aAAa,EACd,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/schema/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,YAAY,EACR,WAAW,EACX,YAAY,EACZ,aAAa,EACb,WAAW,EACX,sBAAsB,EACtB,wBAAwB,EACxB,kBAAkB,EAClB,UAAU,EACV,aAAa,EACb,YAAY,EACZ,WAAW,EACX,cAAc,EACd,WAAW,EACX,cAAc,EACd,kBAAkB,EAClB,cAAc,EACd,YAAY,EACZ,WAAW,EACX,eAAe,EACf,YAAY,EACZ,cAAc,EACd,YAAY,EACZ,YAAY,EACZ,MAAM,EACN,WAAW,EACX,cAAc,EACd,cAAc,EACd,gBAAgB,EAChB,YAAY,EACZ,eAAe,EACf,YAAY,EACZ,WAAW,EACX,mBAAmB,EACnB,WAAW,EACX,aAAa,EAChB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAC9C,OAAO,EAAE,wBAAwB,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/schema/index.js

@@ -1,9 +1,12 @@
 /**
  * @file schema/index.ts
  * @brief Schema module aggregate.
+ * @details Schema helpers enforce construction-time invariants before values reach
+ * validation, compilation, or export.
  */
 export { UUID_PATTERN } from "./types.js";
 export { isLiteralValue } from "./literal.js";
 export { isSchemaValue } from "./validate.js";
 export { freezeSchema } from "./freeze.js";
 export { resolveLazySchema } from "./lazy.js";
+export { schemaCanAcceptUndefined } from "./undefined.js";

package/dist/schema/lazy.d.ts

@@ -1,10 +1,14 @@
 /**
  * @file schema/lazy.ts
  * @brief Lazy schema resolution.
+ * @details Schema helpers enforce construction-time invariants before values reach
+ * validation, compilation, or export.
  */
 import type { LazySchema, Schema } from "./types.js";
 /**
  * @brief resolve lazy schema.
+ * @details Schema helpers enforce construction-time invariants before values reach
+ * validation, compilation, or export.
  */
 export declare function resolveLazySchema(schema: LazySchema, resolving: WeakSet<object>): Schema;
 //# sourceMappingURL=lazy.d.ts.map

package/dist/schema/lazy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"lazy.d.ts","sourceRoot":"","sources":["../../src/schema/lazy.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAErD;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,UAAU,EAClB,SAAS,EAAE,OAAO,CAAC,MAAM,CAAC,GACzB,MAAM,CAcR"}
+{"version":3,"file":"lazy.d.ts","sourceRoot":"","sources":["../../src/schema/lazy.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAErD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC7B,MAAM,EAAE,UAAU,EAClB,SAAS,EAAE,OAAO,CAAC,MAAM,CAAC,GAC3B,MAAM,CAcR"}

package/dist/schema/lazy.js

@@ -1,12 +1,16 @@
 /**
  * @file schema/lazy.ts
  * @brief Lazy schema resolution.
+ * @details Schema helpers enforce construction-time invariants before values reach
+ * validation, compilation, or export.
  */
 import { SchemaTag } from "../kind/index.js";
 import { freezeSchema } from "./freeze.js";
 import { isSchemaValue } from "./validate.js";
 /**
  * @brief resolve lazy schema.
+ * @details Schema helpers enforce construction-time invariants before values reach
+ * validation, compilation, or export.
  */
 export function resolveLazySchema(schema, resolving) {
     if (resolving.has(schema)) {

package/dist/schema/literal.d.ts

@@ -1,10 +1,16 @@
 /**
  * @file schema/literal.ts
  * @brief Literal-value boundary checks.
+ * @details Schema helpers enforce construction-time invariants before values reach
+ * validation, compilation, or export.
  */
 import type { LiteralValue } from "./types.js";
 /**
- * @brief is literal value.
+ * @brief Validate values that TypeSea can store as exact literals.
+ * @param value Candidate literal payload.
+ * @returns True for JavaScript primitive literal values plus null and undefined.
+ * @details Objects are excluded because literal matching uses `Object.is`.
+ * Keeping literals primitive preserves stable interpreter and codegen behavior.
  */
 export declare function isLiteralValue(value: unknown): value is LiteralValue;
 //# sourceMappingURL=literal.d.ts.map

package/dist/schema/literal.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"literal.d.ts","sourceRoot":"","sources":["../../src/schema/literal.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C;;GAEG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,YAAY,CAWpE"}
+{"version":3,"file":"literal.d.ts","sourceRoot":"","sources":["../../src/schema/literal.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,YAAY,CAWpE"}

package/dist/schema/literal.js

@@ -1,9 +1,15 @@
 /**
  * @file schema/literal.ts
  * @brief Literal-value boundary checks.
+ * @details Schema helpers enforce construction-time invariants before values reach
+ * validation, compilation, or export.
  */
 /**
- * @brief is literal value.
+ * @brief Validate values that TypeSea can store as exact literals.
+ * @param value Candidate literal payload.
+ * @returns True for JavaScript primitive literal values plus null and undefined.
+ * @details Objects are excluded because literal matching uses `Object.is`.
+ * Keeping literals primitive preserves stable interpreter and codegen behavior.
  */
 export function isLiteralValue(value) {
     const valueType = typeof value;

package/dist/schema/types.d.ts

@@ -1,146 +1,89 @@
 /**
  * @file schema/types.ts
  * @brief Schema tags and structural TypeSea schema records.
+ * @details Schema helpers enforce construction-time invariants before values reach
+ * validation, compilation, or export.
  */
 import { NumberCheckTag, ObjectModeTag, PresenceTag, SchemaTag, StringCheckTag } from "../kind/index.js";
-/**
- * @brief literal value.
- */
 export type LiteralValue = string | number | bigint | boolean | symbol | null | undefined;
 /**
- * @brief schema.
+ * @brief Frozen schema tree consumed by interpreters, IR lowering, and codegen.
+ * @details These records are deliberately data-only. Builder methods normalize
+ * unsafe inputs before they enter this representation.
  */
 export type Schema = UnknownSchema | NeverSchema | StringSchema | NumberSchema | BigIntSchema | SymbolSchema | BooleanSchema | LiteralSchema | ArraySchema | ObjectSchema | UnionSchema | IntersectionSchema | OptionalSchema | UndefinedableSchema | NullableSchema | DiscriminatedUnionSchema | BrandSchema | TupleSchema | RecordSchema | LazySchema | RefineSchema;
-/**
- * @brief unknown schema.
- */
 export interface UnknownSchema {
     readonly tag: typeof SchemaTag.Unknown;
 }
-/**
- * @brief never schema.
- */
 export interface NeverSchema {
     readonly tag: typeof SchemaTag.Never;
 }
-/**
- * @brief string schema.
- */
 export interface StringSchema {
     readonly tag: typeof SchemaTag.String;
     readonly checks: readonly StringCheck[];
 }
-/**
- * @brief string check.
- */
 export type StringCheck = StringMinCheck | StringMaxCheck | StringRegexCheck | StringUuidCheck;
-/**
- * @brief string min check.
- */
 export interface StringMinCheck {
     readonly tag: typeof StringCheckTag.Min;
     readonly value: number;
 }
-/**
- * @brief string max check.
- */
 export interface StringMaxCheck {
     readonly tag: typeof StringCheckTag.Max;
     readonly value: number;
 }
-/**
- * @brief string regex check.
- */
 export interface StringRegexCheck {
     readonly tag: typeof StringCheckTag.Regex;
     readonly regex: RegExp;
     readonly name: string;
 }
-/**
- * @brief string uuid check.
- */
 export interface StringUuidCheck {
     readonly tag: typeof StringCheckTag.Uuid;
 }
-/**
- * @brief number schema.
- */
 export interface NumberSchema {
     readonly tag: typeof SchemaTag.Number;
     readonly checks: readonly NumberCheck[];
 }
-/**
- * @brief big int schema.
- */
 export interface BigIntSchema {
     readonly tag: typeof SchemaTag.BigInt;
 }
-/**
- * @brief symbol schema.
- */
 export interface SymbolSchema {
     readonly tag: typeof SchemaTag.Symbol;
 }
-/**
- * @brief number check.
- */
 export type NumberCheck = NumberIntegerCheck | NumberGteCheck | NumberLteCheck;
-/**
- * @brief number integer check.
- */
 export interface NumberIntegerCheck {
     readonly tag: typeof NumberCheckTag.Integer;
 }
-/**
- * @brief number gte check.
- */
 export interface NumberGteCheck {
     readonly tag: typeof NumberCheckTag.Gte;
     readonly value: number;
 }
-/**
- * @brief number lte check.
- */
 export interface NumberLteCheck {
     readonly tag: typeof NumberCheckTag.Lte;
     readonly value: number;
 }
-/**
- * @brief boolean schema.
- */
 export interface BooleanSchema {
     readonly tag: typeof SchemaTag.Boolean;
 }
-/**
- * @brief literal schema.
- */
 export interface LiteralSchema {
     readonly tag: typeof SchemaTag.Literal;
     readonly value: LiteralValue;
 }
-/**
- * @brief array schema.
- */
 export interface ArraySchema {
     readonly tag: typeof SchemaTag.Array;
     readonly item: Schema;
 }
-/**
- * @brief tuple schema.
- */
 export interface TupleSchema {
     readonly tag: typeof SchemaTag.Tuple;
     readonly items: readonly Schema[];
 }
-/**
- * @brief record schema.
- */
 export interface RecordSchema {
     readonly tag: typeof SchemaTag.Record;
     readonly value: Schema;
 }
 /**
- * @brief object schema.
+ * @brief Object schema with both ordered entries and an O(1) key lookup.
+ * @details Codegen uses entries for stable field order and keyLookup for strict
+ * unknown-key checks.
  */
 export interface ObjectSchema {
     readonly tag: typeof SchemaTag.Object;
@@ -149,86 +92,65 @@ export interface ObjectSchema {
     readonly keyLookup: ObjectKeyLookup;
     readonly mode: ObjectModeTag;
 }
-/**
- * @brief object key lookup.
- */
 export type ObjectKeyLookup = Readonly<Record<string, true>>;
-/**
- * @brief object entry.
- */
 export interface ObjectEntry {
     readonly key: string;
     readonly schema: Schema;
     readonly presence: PresenceTag;
 }
-/**
- * @brief union schema.
- */
 export interface UnionSchema {
     readonly tag: typeof SchemaTag.Union;
     readonly options: readonly Schema[];
 }
-/**
- * @brief intersection schema.
- */
 export interface IntersectionSchema {
     readonly tag: typeof SchemaTag.Intersection;
     readonly left: Schema;
     readonly right: Schema;
 }
-/**
- * @brief optional schema.
- */
 export interface OptionalSchema {
     readonly tag: typeof SchemaTag.Optional;
     readonly inner: Schema;
 }
-/**
- * @brief undefinedable schema.
- */
 export interface UndefinedableSchema {
     readonly tag: typeof SchemaTag.Undefinedable;
     readonly inner: Schema;
 }
-/**
- * @brief nullable schema.
- */
 export interface NullableSchema {
     readonly tag: typeof SchemaTag.Nullable;
     readonly inner: Schema;
 }
 /**
- * @brief discriminated union schema.
+ * @brief Tagged union schema whose cases share one discriminant key.
+ * @details Schema helpers enforce construction-time invariants before values reach
+ * validation, compilation, or export.
  */
 export interface DiscriminatedUnionSchema {
     readonly tag: typeof SchemaTag.DiscriminatedUnion;
     readonly key: string;
     readonly cases: readonly DiscriminatedUnionCase[];
 }
-/**
- * @brief discriminated union case.
- */
 export interface DiscriminatedUnionCase {
     readonly literal: string;
     readonly schema: Schema;
 }
-/**
- * @brief brand schema.
- */
 export interface BrandSchema {
     readonly tag: typeof SchemaTag.Brand;
     readonly inner: Schema;
     readonly brand: string;
 }
 /**
- * @brief lazy schema.
+ * @brief Lazy schema thunk for recursive shapes.
+ * @details Builders cache resolved schemas before validation so recursion does
+ * not allocate a fresh schema tree per input node.
  */
 export interface LazySchema {
     readonly tag: typeof SchemaTag.Lazy;
     readonly get: () => Schema;
 }
 /**
- * @brief refine schema.
+ * @brief User predicate fallback.
+ * @details Refinements are intentionally opaque to IR optimization; codegen can
+ * only call the predicate after the inner schema succeeds.
  */
 export interface RefineSchema {
     readonly tag: typeof SchemaTag.Refine;
@@ -237,7 +159,9 @@ export interface RefineSchema {
     readonly name: string;
 }
 /**
- * @brief uuid pattern.
+ * @brief UUID pattern shared by interpreter and generated validators.
+ * @details Schema helpers enforce construction-time invariants before values reach
+ * validation, compilation, or export.
  */
 export declare const UUID_PATTERN: RegExp;
 //# sourceMappingURL=types.d.ts.map

package/dist/schema/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/schema/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/schema/types.ts"],"names":[],"mappings":"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"}

package/dist/schema/types.js

@@ -1,9 +1,13 @@
 /**
  * @file schema/types.ts
  * @brief Schema tags and structural TypeSea schema records.
+ * @details Schema helpers enforce construction-time invariants before values reach
+ * validation, compilation, or export.
  */
 import { NumberCheckTag, ObjectModeTag, PresenceTag, SchemaTag, StringCheckTag } from "../kind/index.js";
 /**
- * @brief uuid pattern.
+ * @brief UUID pattern shared by interpreter and generated validators.
+ * @details Schema helpers enforce construction-time invariants before values reach
+ * validation, compilation, or export.
  */
 export const UUID_PATTERN = /^(?:00000000-0000-0000-0000-000000000000|[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12})$/iu;

package/dist/schema/undefined.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @file undefined.ts
+ * @brief Conservative undefined-acceptance analysis for schema slots.
+ * @details Schema helpers enforce construction-time invariants before values reach
+ * validation, compilation, or export.
+ */
+import type { Schema } from "./types.js";
+/**
+ * @brief Return whether `undefined` may satisfy a schema.
+ * @details This is intentionally conservative for lazy and refine schemas because
+ * the caller may not have a recursion state or a safe way to run user predicates.
+ * @param schema Schema node whose static acceptance set is inspected.
+ * @returns True when an absent array slot can be treated as already accepted.
+ * @invariant This routine never executes user predicates or lazy factories.
+ */
+export declare function schemaCanAcceptUndefined(schema: Schema): boolean;
+//# sourceMappingURL=undefined.d.ts.map

package/dist/schema/undefined.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"undefined.d.ts","sourceRoot":"","sources":["../../src/schema/undefined.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAEzC;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAwChE"}

package/dist/schema/undefined.js

@@ -0,0 +1,72 @@
+/**
+ * @file undefined.ts
+ * @brief Conservative undefined-acceptance analysis for schema slots.
+ * @details Schema helpers enforce construction-time invariants before values reach
+ * validation, compilation, or export.
+ */
+import { SchemaTag } from "../kind/index.js";
+/**
+ * @brief Return whether `undefined` may satisfy a schema.
+ * @details This is intentionally conservative for lazy and refine schemas because
+ * the caller may not have a recursion state or a safe way to run user predicates.
+ * @param schema Schema node whose static acceptance set is inspected.
+ * @returns True when an absent array slot can be treated as already accepted.
+ * @invariant This routine never executes user predicates or lazy factories.
+ */
+export function schemaCanAcceptUndefined(schema) {
+    switch (schema.tag) {
+        case SchemaTag.Unknown:
+        case SchemaTag.Optional:
+        case SchemaTag.Undefinedable:
+            return true;
+        case SchemaTag.Lazy:
+        case SchemaTag.Refine:
+            /*
+             * Opaque child logic may reject undefined. A sparse hole must flow
+             * through the child validator instead of being skipped up front.
+             */
+            return false;
+        case SchemaTag.Literal:
+            return schema.value === undefined;
+        case SchemaTag.Union:
+            return schemaArrayCanAcceptUndefined(schema.options);
+        case SchemaTag.Intersection:
+            /*
+             * Intersections require both branches to accept the same value. If
+             * either branch rejects undefined, a sparse hole must stay visible.
+             */
+            return schemaCanAcceptUndefined(schema.left) &&
+                schemaCanAcceptUndefined(schema.right);
+        case SchemaTag.Nullable:
+        case SchemaTag.Brand:
+            return schemaCanAcceptUndefined(schema.inner);
+        case SchemaTag.Never:
+        case SchemaTag.String:
+        case SchemaTag.Number:
+        case SchemaTag.BigInt:
+        case SchemaTag.Symbol:
+        case SchemaTag.Boolean:
+        case SchemaTag.Array:
+        case SchemaTag.Object:
+        case SchemaTag.DiscriminatedUnion:
+        case SchemaTag.Tuple:
+        case SchemaTag.Record:
+            return false;
+    }
+}
+/**
+ * @brief Return whether at least one schema in a closed array may accept undefined.
+ * @details Schema helpers enforce construction-time invariants before values reach
+ * validation, compilation, or export.
+ * @param schemas Closed schema list owned by a union-like node.
+ * @returns True when one member admits undefined without evaluating input data.
+ */
+function schemaArrayCanAcceptUndefined(schemas) {
+    for (let index = 0; index < schemas.length; index += 1) {
+        const schema = schemas[index];
+        if (schema !== undefined && schemaCanAcceptUndefined(schema)) {
+            return true;
+        }
+    }
+    return false;
+}

package/dist/schema/validate.d.ts

@@ -1,10 +1,17 @@
 /**
  * @file schema/validate.ts
  * @brief Runtime validators for direct schema objects.
+ * @details Schema helpers enforce construction-time invariants before values reach
+ * validation, compilation, or export.
  */
 import type { Schema } from "./types.js";
 /**
- * @brief is schema value.
+ * @brief Validate an unknown value as a TypeSea schema tree.
+ * @param value Candidate schema object from a public boundary.
+ * @returns True when the complete tree satisfies the internal schema layout.
+ * @details This routine is intentionally stricter than normal JavaScript object
+ * access: every record and vector must be data-only so later consumers can read
+ * fields without invoking user code.
  */
 export declare function isSchemaValue(value: unknown): value is Schema;
 //# sourceMappingURL=validate.d.ts.map

package/dist/schema/validate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/schema/validate.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAkBH,OAAO,KAAK,EAEV,MAAM,EAEP,MAAM,YAAY,CAAC;AAEpB;;GAEG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAK7D"}
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/schema/validate.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAoBH,OAAO,KAAK,EAER,MAAM,EAET,MAAM,YAAY,CAAC;AAEpB;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAK7D"}