typesea 0.1.0 → 0.2.0

package/dist/builders/composite.d.ts

@@ -1,31 +1,62 @@
 /**
  * @file composite.ts
  * @brief Composite guard builders.
+ * @details Builder helpers normalize user-facing fluent calls into immutable schema nodes
+ * with stable metadata.
  */
 import { BaseGuard, type Guard, type Infer, type Presence } from "../guard/index.js";
 import type { DiscriminatedUnionCases, InferTuple, TupleShape, UnionInput } from "./types.js";
 /**
- * @brief array.
+ * @brief Build an array guard.
+ * @details Builder helpers normalize user-facing fluent calls into immutable schema nodes
+ * with stable metadata.
+ * @param item Guard used for each logical array slot.
+ * @returns Fresh array guard.
  */
 export declare function array<TGuard extends Guard<unknown, Presence>>(item: TGuard): BaseGuard<Infer<TGuard>[]>;
 /**
- * @brief tuple.
+ * @brief Build a fixed-length tuple guard.
+ * @details Builder helpers normalize user-facing fluent calls into immutable schema nodes
+ * with stable metadata.
+ * @param shape Ordered guard list for tuple indexes.
+ * @returns Fresh tuple guard preserving item order.
+ * @throws TypeError when shape is not an array-like tuple input.
  */
 export declare function tuple<const TShape extends TupleShape>(shape: TShape): BaseGuard<InferTuple<TShape>>;
 /**
- * @brief record.
+ * @brief Build a string-keyed record guard.
+ * @details Builder helpers normalize user-facing fluent calls into immutable schema nodes
+ * with stable metadata.
+ * @param value Guard used for each enumerable own record value.
+ * @returns Fresh record guard.
  */
 export declare function record<TGuard extends Guard<unknown, Presence>>(value: TGuard): BaseGuard<Readonly<Record<string, Infer<TGuard>>>>;
 /**
- * @brief union.
+ * @brief Build a union guard from one or more guards.
+ * @details Builder helpers normalize user-facing fluent calls into immutable schema nodes
+ * with stable metadata.
+ * @param guards Non-empty guard list.
+ * @returns Fresh union guard.
+ * @throws TypeError when called without guards.
  */
 export declare function union<const TGuards extends UnionInput>(...guards: TGuards): BaseGuard<Infer<TGuards[number]>>;
 /**
- * @brief intersect.
+ * @brief Build an intersection guard.
+ * @details Builder helpers normalize user-facing fluent calls into immutable schema nodes
+ * with stable metadata.
+ * @param left Left-hand guard.
+ * @param right Right-hand guard.
+ * @returns Fresh guard requiring both schemas to accept the value.
  */
 export declare function intersect<TLeft extends Guard<unknown, Presence>, TRight extends Guard<unknown, Presence>>(left: TLeft, right: TRight): BaseGuard<Infer<TLeft> & Infer<TRight>>;
 /**
- * @brief discriminated union.
+ * @brief Build a union whose branch can be selected by one literal property.
+ * @details This shape lowers to a dispatch table instead of a linear union
+ * scan, which is the fast path object unions should use.
+ * @param key Discriminant object key.
+ * @param cases Record from discriminant literal to branch guard.
+ * @returns Fresh discriminated-union guard.
+ * @throws TypeError when cases are empty or branch schemas do not require the tag.
  */
 export declare function discriminatedUnion<const TKey extends string, const TCases extends Readonly<Record<string, Guard<unknown, Presence>>>>(key: TKey, cases: TCases & DiscriminatedUnionCases<TKey, TCases>): BaseGuard<Infer<TCases[keyof TCases]>>;
 //# sourceMappingURL=composite.d.ts.map

package/dist/builders/composite.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"composite.d.ts","sourceRoot":"","sources":["../../src/builders/composite.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAMH,OAAO,EACL,SAAS,EACT,KAAK,KAAK,EACV,KAAK,KAAK,EACV,KAAK,QAAQ,EACd,MAAM,mBAAmB,CAAC;AAM3B,OAAO,KAAK,EACV,uBAAuB,EACvB,UAAU,EACV,UAAU,EACV,UAAU,EACX,MAAM,YAAY,CAAC;AAEpB;;GAEG;AACH,wBAAgB,KAAK,CAAC,MAAM,SAAS,KAAK,CAAC,OAAO,EAAE,QAAQ,CAAC,EAC3D,IAAI,EAAE,MAAM,GACX,SAAS,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,CAK5B;AAED;;GAEG;AACH,wBAAgB,KAAK,CAAC,KAAK,CAAC,MAAM,SAAS,UAAU,EACnD,KAAK,EAAE,MAAM,GACZ,SAAS,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAc/B;AAED;;GAEG;AACH,wBAAgB,MAAM,CAAC,MAAM,SAAS,KAAK,CAAC,OAAO,EAAE,QAAQ,CAAC,EAC5D,KAAK,EAAE,MAAM,GACZ,SAAS,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAKpD;AAED;;GAEG;AACH,wBAAgB,KAAK,CAAC,KAAK,CAAC,OAAO,SAAS,UAAU,EACpD,GAAG,MAAM,EAAE,OAAO,GACjB,SAAS,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAanC;AAED;;GAEG;AACH,wBAAgB,SAAS,CACvB,KAAK,SAAS,KAAK,CAAC,OAAO,EAAE,QAAQ,CAAC,EACtC,MAAM,SAAS,KAAK,CAAC,OAAO,EAAE,QAAQ,CAAC,EAEvC,IAAI,EAAE,KAAK,EACX,KAAK,EAAE,MAAM,GACZ,SAAS,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAMzC;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,CAAC,IAAI,SAAS,MAAM,EACzB,KAAK,CAAC,MAAM,SAAS,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC,CAAC,EAEvE,GAAG,EAAE,IAAI,EACT,KAAK,EAAE,MAAM,GAAG,uBAAuB,CAAC,IAAI,EAAE,MAAM,CAAC,GACpD,SAAS,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,MAAM,CAAC,CAAC,CAAC,CA6BxC"}
+{"version":3,"file":"composite.d.ts","sourceRoot":"","sources":["../../src/builders/composite.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,OAAO,EACH,SAAS,EACT,KAAK,KAAK,EACV,KAAK,KAAK,EACV,KAAK,QAAQ,EAChB,MAAM,mBAAmB,CAAC;AAM3B,OAAO,KAAK,EACR,uBAAuB,EACvB,UAAU,EACV,UAAU,EACV,UAAU,EACb,MAAM,YAAY,CAAC;AAEpB;;;;;;GAMG;AACH,wBAAgB,KAAK,CAAC,MAAM,SAAS,KAAK,CAAC,OAAO,EAAE,QAAQ,CAAC,EACzD,IAAI,EAAE,MAAM,GACb,SAAS,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,CAK5B;AAED;;;;;;;GAOG;AACH,wBAAgB,KAAK,CAAC,KAAK,CAAC,MAAM,SAAS,UAAU,EACjD,KAAK,EAAE,MAAM,GACd,SAAS,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAkB/B;AAED;;;;;;GAMG;AACH,wBAAgB,MAAM,CAAC,MAAM,SAAS,KAAK,CAAC,OAAO,EAAE,QAAQ,CAAC,EAC1D,KAAK,EAAE,MAAM,GACd,SAAS,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAKpD;AAED;;;;;;;GAOG;AACH,wBAAgB,KAAK,CAAC,KAAK,CAAC,OAAO,SAAS,UAAU,EAClD,GAAG,MAAM,EAAE,OAAO,GACnB,SAAS,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAiBnC;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CACrB,KAAK,SAAS,KAAK,CAAC,OAAO,EAAE,QAAQ,CAAC,EACtC,MAAM,SAAS,KAAK,CAAC,OAAO,EAAE,QAAQ,CAAC,EAEvC,IAAI,EAAE,KAAK,EACX,KAAK,EAAE,MAAM,GACd,SAAS,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAMzC;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAC9B,KAAK,CAAC,IAAI,SAAS,MAAM,EACzB,KAAK,CAAC,MAAM,SAAS,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC,CAAC,EAEvE,GAAG,EAAE,IAAI,EACT,KAAK,EAAE,MAAM,GAAG,uBAAuB,CAAC,IAAI,EAAE,MAAM,CAAC,GACtD,SAAS,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,MAAM,CAAC,CAAC,CAAC,CAiCxC"}

package/dist/builders/composite.js

@@ -1,12 +1,18 @@
 /**
  * @file composite.ts
  * @brief Composite guard builders.
+ * @details Builder helpers normalize user-facing fluent calls into immutable schema nodes
+ * with stable metadata.
  */
 import { PresenceTag, SchemaTag } from "../kind/index.js";
 import { BaseGuard } from "../guard/index.js";
 import { isRecord, readGuardSchema } from "../internal/index.js";
 /**
- * @brief array.
+ * @brief Build an array guard.
+ * @details Builder helpers normalize user-facing fluent calls into immutable schema nodes
+ * with stable metadata.
+ * @param item Guard used for each logical array slot.
+ * @returns Fresh array guard.
  */
 export function array(item) {
     return new BaseGuard({
@@ -15,13 +21,22 @@ export function array(item) {
     });
 }
 /**
- * @brief tuple.
+ * @brief Build a fixed-length tuple guard.
+ * @details Builder helpers normalize user-facing fluent calls into immutable schema nodes
+ * with stable metadata.
+ * @param shape Ordered guard list for tuple indexes.
+ * @returns Fresh tuple guard preserving item order.
+ * @throws TypeError when shape is not an array-like tuple input.
  */
 export function tuple(shape) {
     const rawShape = shape;
     if (!Array.isArray(rawShape)) {
         throw new TypeError("tuple shape must be an array");
     }
+    /*
+     * Tuple indexes are read in order and stored as schemas, not guard objects,
+     * so later validation cannot observe mutation on user-held guard wrappers.
+     */
     const items = new Array(shape.length);
     for (let index = 0; index < shape.length; index += 1) {
         const guard = shape[index];
@@ -33,7 +48,11 @@ export function tuple(shape) {
     });
 }
 /**
- * @brief record.
+ * @brief Build a string-keyed record guard.
+ * @details Builder helpers normalize user-facing fluent calls into immutable schema nodes
+ * with stable metadata.
+ * @param value Guard used for each enumerable own record value.
+ * @returns Fresh record guard.
  */
 export function record(value) {
     return new BaseGuard({
@@ -42,12 +61,21 @@ export function record(value) {
     });
 }
 /**
- * @brief union.
+ * @brief Build a union guard from one or more guards.
+ * @details Builder helpers normalize user-facing fluent calls into immutable schema nodes
+ * with stable metadata.
+ * @param guards Non-empty guard list.
+ * @returns Fresh union guard.
+ * @throws TypeError when called without guards.
  */
 export function union(...guards) {
     if (guards.length === 0) {
         throw new TypeError("union requires at least one guard");
     }
+    /*
+     * Preserve option order. Diagnostics and generated dispatch use this order
+     * when probing branches and constructing graph children.
+     */
     const options = new Array(guards.length);
     for (let index = 0; index < guards.length; index += 1) {
         const guard = guards[index];
@@ -59,7 +87,12 @@ export function union(...guards) {
     });
 }
 /**
- * @brief intersect.
+ * @brief Build an intersection guard.
+ * @details Builder helpers normalize user-facing fluent calls into immutable schema nodes
+ * with stable metadata.
+ * @param left Left-hand guard.
+ * @param right Right-hand guard.
+ * @returns Fresh guard requiring both schemas to accept the value.
  */
 export function intersect(left, right) {
     return new BaseGuard({
@@ -69,7 +102,13 @@ export function intersect(left, right) {
     });
 }
 /**
- * @brief discriminated union.
+ * @brief Build a union whose branch can be selected by one literal property.
+ * @details This shape lowers to a dispatch table instead of a linear union
+ * scan, which is the fast path object unions should use.
+ * @param key Discriminant object key.
+ * @param cases Record from discriminant literal to branch guard.
+ * @returns Fresh discriminated-union guard.
+ * @throws TypeError when cases are empty or branch schemas do not require the tag.
  */
 export function discriminatedUnion(key, cases) {
     if (typeof key !== "string") {
@@ -82,6 +121,10 @@ export function discriminatedUnion(key, cases) {
     if (entries.length === 0) {
         throw new TypeError("discriminated union requires at least one case");
     }
+    /*
+     * Object.entries defines the dispatch order. The literal string is taken
+     * from the case key and must be required by the branch schema below.
+     */
     const unionCases = new Array(entries.length);
     for (let index = 0; index < entries.length; index += 1) {
         const pair = entries[index];
@@ -102,7 +145,15 @@ export function discriminatedUnion(key, cases) {
     });
 }
 /**
- * @brief read discriminated union case schema.
+ * @brief Extract and validate one discriminated-union branch schema.
+ * @details A branch is accepted only when its object schema itself proves the
+ * discriminant literal. Without that proof, dispatch by table key could select
+ * a branch whose validator later accepts a different tag shape.
+ * @param guard Branch guard from the cases table.
+ * @param key Discriminant key shared by all cases.
+ * @param literal Literal value assigned to this case.
+ * @returns Branch schema after discriminant proof.
+ * @throws TypeError when the branch does not require its literal tag.
  */
 function readDiscriminatedUnionCaseSchema(guard, key, literal) {
     const schema = readGuardSchema(guard, `case ${literal}`);
@@ -112,7 +163,15 @@ function readDiscriminatedUnionCaseSchema(guard, key, literal) {
     return schema;
 }
 /**
- * @brief case requires discriminant.
+ * @brief Prove that a branch structurally requires the requested tag literal.
+ * @details Dispatch tables are only sound when accepting a branch implies that
+ * the discriminant key is present and equal to its table literal. The proof is
+ * intentionally structural and refuses schemas whose tag requirement is hidden
+ * behind runtime-only logic.
+ * @param schema Branch schema to inspect.
+ * @param key Discriminant key.
+ * @param literal Required literal value.
+ * @returns True when the branch structurally requires `key: literal`.
  */
 function caseRequiresDiscriminant(schema, key, literal) {
     const objectSchema = unwrapCaseObjectSchema(schema);
@@ -131,13 +190,22 @@ function caseRequiresDiscriminant(schema, key, literal) {
     return false;
 }
 /**
- * @brief unwrap case object schema.
+ * @brief Find the object schema that can prove a discriminant requirement.
+ * @details Brand and refinement wrappers do not change object shape, and either
+ * side of an intersection may supply the tag field. Other schema forms cannot
+ * provide the required object-field proof.
+ * @param schema Branch schema possibly wrapped by brand/refine/intersection.
+ * @returns Object schema used for discriminant inspection, or undefined.
  */
 function unwrapCaseObjectSchema(schema) {
     switch (schema.tag) {
         case SchemaTag.Object:
             return schema;
         case SchemaTag.Intersection:
+            /*
+             * A discriminant can be supplied by either side of an intersection.
+             * Search both sides before rejecting the case.
+             */
             return unwrapCaseObjectSchema(schema.left) ?? unwrapCaseObjectSchema(schema.right);
         case SchemaTag.Brand:
         case SchemaTag.Refine:
@@ -147,7 +215,13 @@ function unwrapCaseObjectSchema(schema) {
     }
 }
 /**
- * @brief schema requires literal.
+ * @brief Prove that a discriminant field schema accepts only one literal.
+ * @details Intersections may prove the literal from either side, while brand
+ * and refinement wrappers preserve the underlying literal requirement. Broader
+ * schemas are rejected because they would make table dispatch unsound.
+ * @param schema Schema attached to the discriminant property.
+ * @param literal Literal value required by the case.
+ * @returns True when the schema accepts only the requested literal.
  */
 function schemaRequiresLiteral(schema, literal) {
     switch (schema.tag) {

package/dist/builders/index.d.ts

@@ -1,6 +1,8 @@
 /**
  * @file index.ts
  * @brief Public builder module aggregation.
+ * @details This barrel keeps public import paths stable while implementation files remain
+ * split by responsibility.
  */
 export { array, discriminatedUnion, intersect, record, tuple, union } from "./composite.js";
 export { lazy, nullable, optional, refine, undefinedable } from "./modifier.js";

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/builders/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EACL,KAAK,EACL,kBAAkB,EAClB,SAAS,EACT,MAAM,EACN,KAAK,EACL,KAAK,EACN,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,IAAI,EACJ,QAAQ,EACR,QAAQ,EACR,MAAM,EACN,aAAa,EACd,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,WAAW,EACX,MAAM,EACN,MAAM,EACN,IAAI,EACJ,OAAO,EACP,IAAI,EACJ,YAAY,EACZ,KAAK,WAAW,EAChB,KAAK,iBAAiB,EACtB,KAAK,eAAe,EACpB,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,KAAK,kBAAkB,EACvB,KAAK,eAAe,EACrB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,WAAW,EACX,OAAO,EACP,UAAU,EACV,WAAW,EACX,YAAY,EACb,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,CAAC,EAAE,MAAM,YAAY,CAAC;AAC/B,YAAY,EACV,UAAU,EACV,UAAU,EACX,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/builders/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EACH,KAAK,EACL,kBAAkB,EAClB,SAAS,EACT,MAAM,EACN,KAAK,EACL,KAAK,EACR,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACH,IAAI,EACJ,QAAQ,EACR,QAAQ,EACR,MAAM,EACN,aAAa,EAChB,MAAM,eAAe,CAAC;AACvB,OAAO,EACH,WAAW,EACX,MAAM,EACN,MAAM,EACN,IAAI,EACJ,OAAO,EACP,IAAI,EACJ,YAAY,EACZ,KAAK,WAAW,EAChB,KAAK,iBAAiB,EACtB,KAAK,eAAe,EACpB,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,KAAK,kBAAkB,EACvB,KAAK,eAAe,EACvB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACH,WAAW,EACX,OAAO,EACP,UAAU,EACV,WAAW,EACX,YAAY,EACf,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,CAAC,EAAE,MAAM,YAAY,CAAC;AAC/B,YAAY,EACR,UAAU,EACV,UAAU,EACb,MAAM,YAAY,CAAC"}

package/dist/builders/index.js

@@ -1,6 +1,8 @@
 /**
  * @file index.ts
  * @brief Public builder module aggregation.
+ * @details This barrel keeps public import paths stable while implementation files remain
+ * split by responsibility.
  */
 export { array, discriminatedUnion, intersect, record, tuple, union } from "./composite.js";
 export { lazy, nullable, optional, refine, undefinedable } from "./modifier.js";

package/dist/builders/modifier.d.ts

@@ -1,26 +1,51 @@
 /**
  * @file modifier.ts
  * @brief Presence, lazy, and refinement guard builders.
+ * @details Builder helpers normalize user-facing fluent calls into immutable schema nodes
+ * with stable metadata.
  */
 import { BaseGuard, type Guard, type GuardPresence, type GuardValue, type Infer, type Presence } from "../guard/index.js";
 /**
- * @brief optional.
+ * @brief Mark a guard optional for object shape construction.
+ * @details Builder helpers normalize user-facing fluent calls into immutable schema nodes
+ * with stable metadata.
+ * @param guard Guard whose value type is preserved.
+ * @returns Fresh optional guard.
  */
 export declare function optional<TGuard extends Guard<unknown, Presence>>(guard: TGuard): BaseGuard<GuardValue<TGuard>, "optional">;
 /**
- * @brief undefinedable.
+ * @brief Allow explicit undefined as a value.
+ * @details Builder helpers normalize user-facing fluent calls into immutable schema nodes
+ * with stable metadata.
+ * @param guard Guard to wrap.
+ * @returns Fresh undefinedable guard preserving original presence.
  */
 export declare function undefinedable<TGuard extends Guard<unknown, Presence>>(guard: TGuard): BaseGuard<GuardValue<TGuard> | undefined, GuardPresence<TGuard>>;
 /**
- * @brief nullable.
+ * @brief Allow explicit null as a value.
+ * @details Builder helpers normalize user-facing fluent calls into immutable schema nodes
+ * with stable metadata.
+ * @param guard Guard to wrap.
+ * @returns Fresh nullable guard preserving original presence.
  */
 export declare function nullable<TGuard extends Guard<unknown, Presence>>(guard: TGuard): BaseGuard<GuardValue<TGuard> | null, GuardPresence<TGuard>>;
 /**
- * @brief lazy.
+ * @brief Resolve recursive schemas once and reuse the frozen schema handle.
+ * @details Builder helpers normalize user-facing fluent calls into immutable schema nodes
+ * with stable metadata.
+ * @param get Resolver returning the recursive guard.
+ * @returns Fresh lazy guard.
+ * @throws TypeError when the resolver is not callable.
  */
 export declare function lazy<TGuard extends Guard<unknown, Presence>>(get: () => TGuard): BaseGuard<Infer<TGuard>>;
 /**
- * @brief refine.
+ * @brief Attach a boolean refinement while preserving TypeSea's strict true contract.
+ * @details Builder helpers normalize user-facing fluent calls into immutable schema nodes
+ * with stable metadata.
+ * @param guard Guard that must pass before the predicate runs.
+ * @param predicate User predicate that must return the boolean literal true.
+ * @param name Diagnostic name for refinement failures.
+ * @returns Fresh refined guard.
  */
 export declare function refine<TGuard extends Guard<unknown, Presence>>(guard: TGuard, predicate: (value: Infer<TGuard>) => boolean, name: string): BaseGuard<GuardValue<TGuard>, GuardPresence<TGuard>>;
 //# sourceMappingURL=modifier.d.ts.map

package/dist/builders/modifier.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"modifier.d.ts","sourceRoot":"","sources":["../../src/builders/modifier.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EACL,SAAS,EACT,KAAK,KAAK,EACV,KAAK,aAAa,EAClB,KAAK,UAAU,EACf,KAAK,KAAK,EACV,KAAK,QAAQ,EACd,MAAM,mBAAmB,CAAC;AAI3B;;GAEG;AACH,wBAAgB,QAAQ,CAAC,MAAM,SAAS,KAAK,CAAC,OAAO,EAAE,QAAQ,CAAC,EAC9D,KAAK,EAAE,MAAM,GACZ,SAAS,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,UAAU,CAAC,CAK3C;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,MAAM,SAAS,KAAK,CAAC,OAAO,EAAE,QAAQ,CAAC,EACnE,KAAK,EAAE,MAAM,GACZ,SAAS,CAAC,UAAU,CAAC,MAAM,CAAC,GAAG,SAAS,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC,CAKlE;AAED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,MAAM,SAAS,KAAK,CAAC,OAAO,EAAE,QAAQ,CAAC,EAC9D,KAAK,EAAE,MAAM,GACZ,SAAS,CAAC,UAAU,CAAC,MAAM,CAAC,GAAG,IAAI,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC,CAK7D;AAED;;GAEG;AACH,wBAAgB,IAAI,CAAC,MAAM,SAAS,KAAK,CAAC,OAAO,EAAE,QAAQ,CAAC,EAC1D,GAAG,EAAE,MAAM,MAAM,GAChB,SAAS,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAY1B;AAED;;GAEG;AACH,wBAAgB,MAAM,CAAC,MAAM,SAAS,KAAK,CAAC,OAAO,EAAE,QAAQ,CAAC,EAC5D,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC,KAAK,OAAO,EAC5C,IAAI,EAAE,MAAM,GACX,SAAS,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC,CActD"}
+{"version":3,"file":"modifier.d.ts","sourceRoot":"","sources":["../../src/builders/modifier.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EACH,SAAS,EACT,KAAK,KAAK,EACV,KAAK,aAAa,EAClB,KAAK,UAAU,EACf,KAAK,KAAK,EACV,KAAK,QAAQ,EAChB,MAAM,mBAAmB,CAAC;AAI3B;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,MAAM,SAAS,KAAK,CAAC,OAAO,EAAE,QAAQ,CAAC,EAC5D,KAAK,EAAE,MAAM,GACd,SAAS,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,UAAU,CAAC,CAK3C;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,MAAM,SAAS,KAAK,CAAC,OAAO,EAAE,QAAQ,CAAC,EACjE,KAAK,EAAE,MAAM,GACd,SAAS,CAAC,UAAU,CAAC,MAAM,CAAC,GAAG,SAAS,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC,CAKlE;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,MAAM,SAAS,KAAK,CAAC,OAAO,EAAE,QAAQ,CAAC,EAC5D,KAAK,EAAE,MAAM,GACd,SAAS,CAAC,UAAU,CAAC,MAAM,CAAC,GAAG,IAAI,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC,CAK7D;AAED;;;;;;;GAOG;AACH,wBAAgB,IAAI,CAAC,MAAM,SAAS,KAAK,CAAC,OAAO,EAAE,QAAQ,CAAC,EACxD,GAAG,EAAE,MAAM,MAAM,GAClB,SAAS,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAgB1B;AAED;;;;;;;;GAQG;AACH,wBAAgB,MAAM,CAAC,MAAM,SAAS,KAAK,CAAC,OAAO,EAAE,QAAQ,CAAC,EAC1D,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC,KAAK,OAAO,EAC5C,IAAI,EAAE,MAAM,GACb,SAAS,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC,CAkBtD"}

package/dist/builders/modifier.js

@@ -1,12 +1,18 @@
 /**
  * @file modifier.ts
  * @brief Presence, lazy, and refinement guard builders.
+ * @details Builder helpers normalize user-facing fluent calls into immutable schema nodes
+ * with stable metadata.
  */
 import { SchemaTag } from "../kind/index.js";
 import { BaseGuard } from "../guard/index.js";
 import { isStrictTrue, readGuardSchema } from "../internal/index.js";
 /**
- * @brief optional.
+ * @brief Mark a guard optional for object shape construction.
+ * @details Builder helpers normalize user-facing fluent calls into immutable schema nodes
+ * with stable metadata.
+ * @param guard Guard whose value type is preserved.
+ * @returns Fresh optional guard.
  */
 export function optional(guard) {
     return new BaseGuard({
@@ -15,7 +21,11 @@ export function optional(guard) {
     });
 }
 /**
- * @brief undefinedable.
+ * @brief Allow explicit undefined as a value.
+ * @details Builder helpers normalize user-facing fluent calls into immutable schema nodes
+ * with stable metadata.
+ * @param guard Guard to wrap.
+ * @returns Fresh undefinedable guard preserving original presence.
  */
 export function undefinedable(guard) {
     return new BaseGuard({
@@ -24,7 +34,11 @@ export function undefinedable(guard) {
     });
 }
 /**
- * @brief nullable.
+ * @brief Allow explicit null as a value.
+ * @details Builder helpers normalize user-facing fluent calls into immutable schema nodes
+ * with stable metadata.
+ * @param guard Guard to wrap.
+ * @returns Fresh nullable guard preserving original presence.
  */
 export function nullable(guard) {
     return new BaseGuard({
@@ -33,7 +47,12 @@ export function nullable(guard) {
     });
 }
 /**
- * @brief lazy.
+ * @brief Resolve recursive schemas once and reuse the frozen schema handle.
+ * @details Builder helpers normalize user-facing fluent calls into immutable schema nodes
+ * with stable metadata.
+ * @param get Resolver returning the recursive guard.
+ * @returns Fresh lazy guard.
+ * @throws TypeError when the resolver is not callable.
  */
 export function lazy(get) {
     if (typeof get !== "function") {
@@ -43,13 +62,23 @@ export function lazy(get) {
     return new BaseGuard({
         tag: SchemaTag.Lazy,
         get: () => {
+            /*
+             * Cache the resolved schema rather than the guard wrapper. This keeps
+             * recursive validation stable after the first successful resolution.
+             */
             cached ??= readGuardSchema(get(), "lazy result");
             return cached;
         }
     });
 }
 /**
- * @brief refine.
+ * @brief Attach a boolean refinement while preserving TypeSea's strict true contract.
+ * @details Builder helpers normalize user-facing fluent calls into immutable schema nodes
+ * with stable metadata.
+ * @param guard Guard that must pass before the predicate runs.
+ * @param predicate User predicate that must return the boolean literal true.
+ * @param name Diagnostic name for refinement failures.
+ * @returns Fresh refined guard.
  */
 export function refine(guard, predicate, name) {
     if (typeof predicate !== "function") {
@@ -61,6 +90,10 @@ export function refine(guard, predicate, name) {
     return new BaseGuard({
         tag: SchemaTag.Refine,
         inner: readGuardSchema(guard, "refine inner"),
+        /*
+         * Truthy non-boolean values are rejected. This keeps refinement behavior
+         * identical between interpreted and compiled validation paths.
+         */
         predicate: (value) => isStrictTrue(predicate(value)),
         name
     });

package/dist/builders/object/guard.d.ts

@@ -1,6 +1,8 @@
 /**
  * @file guard.ts
  * @brief Object guard class and object builder API.
+ * @details Builder helpers normalize user-facing fluent calls into immutable schema nodes
+ * with stable metadata.
  */
 import type { ObjectSchema } from "../../schema/index.js";
 import { ObjectModeTag } from "../../kind/index.js";
@@ -8,55 +10,49 @@ import { BaseGuard } from "../../guard/index.js";
 import type { ObjectGuardMode, ObjectShape, InferObject, MergeObjectShapes, OmitObjectShape, PartialObjectShape, PickObjectShape, StringKeyOf } from "./types.js";
 /**
  * @brief Guard subclass with object-specific shape operations.
+ * @details Builder helpers normalize user-facing fluent calls into immutable schema nodes
+ * with stable metadata.
  *
  * @invariant Methods preserve the original object mode. Strict schemas stay
  * strict after shape edits; passthrough schemas stay passthrough.
  */
 export declare class ObjectGuard<TShape extends ObjectShape, TMode extends ObjectGuardMode> extends BaseGuard<InferObject<TShape>> {
-    /**
-     * @brief constructor.
-         * @post The receiver is initialized according to the class invariant before it can be observed.
-     */
     constructor(schema: ObjectSchema);
-    /**
-     * @brief extend.
-           */
     extend<const TExtension extends ObjectShape>(extension: TExtension): ObjectGuard<MergeObjectShapes<TShape, TExtension>, TMode>;
-    /**
-     * @brief pick.
-           */
     pick<const TKeys extends readonly StringKeyOf<TShape>[]>(keys: TKeys): ObjectGuard<PickObjectShape<TShape, TKeys[number]>, TMode>;
-    /**
-     * @brief omit.
-           */
     omit<const TKeys extends readonly StringKeyOf<TShape>[]>(keys: TKeys): ObjectGuard<OmitObjectShape<TShape, TKeys[number]>, TMode>;
-    /**
-     * @brief partial.
-         */
     partial(): ObjectGuard<PartialObjectShape<TShape>, TMode>;
 }
 /**
- * @brief object.
+ * @brief Build an object guard that accepts unspecified enumerable keys.
+ * @details Builder helpers normalize user-facing fluent calls into immutable schema nodes
+ * with stable metadata.
  */
 export declare function object<const TShape extends ObjectShape>(shape: TShape): ObjectGuard<TShape, typeof ObjectModeTag.Passthrough>;
 /**
- * @brief strict object.
+ * @brief Build an object guard that rejects unspecified own keys.
+ * @details Builder helpers normalize user-facing fluent calls into immutable schema nodes
+ * with stable metadata.
  */
 export declare function strictObject<const TShape extends ObjectShape>(shape: TShape): ObjectGuard<TShape, typeof ObjectModeTag.Strict>;
 /**
- * @brief extend.
+ * @brief Execute extend.
+ * @details This helper keeps a local invariant explicit at the module boundary.
  */
 export declare function extend<const TShape extends ObjectShape, TMode extends ObjectGuardMode, const TExtension extends ObjectShape>(guard: ObjectGuard<TShape, TMode>, extension: TExtension): ObjectGuard<MergeObjectShapes<TShape, TExtension>, TMode>;
 /**
- * @brief pick.
+ * @brief Execute pick.
+ * @details This helper keeps a local invariant explicit at the module boundary.
  */
 export declare function pick<const TShape extends ObjectShape, TMode extends ObjectGuardMode, const TKeys extends readonly StringKeyOf<TShape>[]>(guard: ObjectGuard<TShape, TMode>, keys: TKeys): ObjectGuard<PickObjectShape<TShape, TKeys[number]>, TMode>;
 /**
- * @brief omit.
+ * @brief Execute omit.
+ * @details This helper keeps a local invariant explicit at the module boundary.
  */
 export declare function omit<const TShape extends ObjectShape, TMode extends ObjectGuardMode, const TKeys extends readonly StringKeyOf<TShape>[]>(guard: ObjectGuard<TShape, TMode>, keys: TKeys): ObjectGuard<OmitObjectShape<TShape, TKeys[number]>, TMode>;
 /**
- * @brief partial.
+ * @brief Execute partial.
+ * @details This helper keeps a local invariant explicit at the module boundary.
  */
 export declare function partial<const TShape extends ObjectShape, TMode extends ObjectGuardMode>(guard: ObjectGuard<TShape, TMode>): ObjectGuard<PartialObjectShape<TShape>, TMode>;
 //# sourceMappingURL=guard.d.ts.map

package/dist/builders/object/guard.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"guard.d.ts","sourceRoot":"","sources":["../../../src/builders/object/guard.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"guard.d.ts","sourceRoot":"","sources":["../../../src/builders/object/guard.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAC1D,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACjD,OAAO,KAAK,EACR,eAAe,EACf,WAAW,EACX,WAAW,EACX,iBAAiB,EACjB,eAAe,EACf,kBAAkB,EAClB,eAAe,EACf,WAAW,EACd,MAAM,YAAY,CAAC;AAYpB;;;;;;;GAOG;AACH,qBAAa,WAAW,CACpB,MAAM,SAAS,WAAW,EAC1B,KAAK,SAAS,eAAe,CAC/B,SAAQ,SAAS,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;gBAEjB,MAAM,EAAE,YAAY;IAKhC,MAAM,CAAC,KAAK,CAAC,UAAU,SAAS,WAAW,EAC9C,SAAS,EAAE,UAAU,GACtB,WAAW,CAAC,iBAAiB,CAAC,MAAM,EAAE,UAAU,CAAC,EAAE,KAAK,CAAC;IAIrD,IAAI,CAAC,KAAK,CAAC,KAAK,SAAS,SAAS,WAAW,CAAC,MAAM,CAAC,EAAE,EAC1D,IAAI,EAAE,KAAK,GACZ,WAAW,CAAC,eAAe,CAAC,MAAM,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC,EAAE,KAAK,CAAC;IAItD,IAAI,CAAC,KAAK,CAAC,KAAK,SAAS,SAAS,WAAW,CAAC,MAAM,CAAC,EAAE,EAC1D,IAAI,EAAE,KAAK,GACZ,WAAW,CAAC,eAAe,CAAC,MAAM,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC,EAAE,KAAK,CAAC;IAItD,OAAO,IAAI,WAAW,CAAC,kBAAkB,CAAC,MAAM,CAAC,EAAE,KAAK,CAAC;CAGnE;AAED;;;;GAIG;AACH,wBAAgB,MAAM,CAAC,KAAK,CAAC,MAAM,SAAS,WAAW,EACnD,KAAK,EAAE,MAAM,GACd,WAAW,CAAC,MAAM,EAAE,OAAO,aAAa,CAAC,WAAW,CAAC,CAIvD;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,CAAC,MAAM,SAAS,WAAW,EACzD,KAAK,EAAE,MAAM,GACd,WAAW,CAAC,MAAM,EAAE,OAAO,aAAa,CAAC,MAAM,CAAC,CAIlD;AAED;;;GAGG;AACH,wBAAgB,MAAM,CAClB,KAAK,CAAC,MAAM,SAAS,WAAW,EAChC,KAAK,SAAS,eAAe,EAC7B,KAAK,CAAC,UAAU,SAAS,WAAW,EAEpC,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,KAAK,CAAC,EACjC,SAAS,EAAE,UAAU,GACtB,WAAW,CAAC,iBAAiB,CAAC,MAAM,EAAE,UAAU,CAAC,EAAE,KAAK,CAAC,CAE3D;AAED;;;GAGG;AACH,wBAAgB,IAAI,CAChB,KAAK,CAAC,MAAM,SAAS,WAAW,EAChC,KAAK,SAAS,eAAe,EAC7B,KAAK,CAAC,KAAK,SAAS,SAAS,WAAW,CAAC,MAAM,CAAC,EAAE,EAElD,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,KAAK,CAAC,EACjC,IAAI,EAAE,KAAK,GACZ,WAAW,CAAC,eAAe,CAAC,MAAM,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC,EAAE,KAAK,CAAC,CAE5D;AAED;;;GAGG;AACH,wBAAgB,IAAI,CAChB,KAAK,CAAC,MAAM,SAAS,WAAW,EAChC,KAAK,SAAS,eAAe,EAC7B,KAAK,CAAC,KAAK,SAAS,SAAS,WAAW,CAAC,MAAM,CAAC,EAAE,EAElD,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,KAAK,CAAC,EACjC,IAAI,EAAE,KAAK,GACZ,WAAW,CAAC,eAAe,CAAC,MAAM,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC,EAAE,KAAK,CAAC,CAE5D;AAED;;;GAGG;AACH,wBAAgB,OAAO,CACnB,KAAK,CAAC,MAAM,SAAS,WAAW,EAChC,KAAK,SAAS,eAAe,EAE7B,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,KAAK,CAAC,GAClC,WAAW,CAAC,kBAAkB,CAAC,MAAM,CAAC,EAAE,KAAK,CAAC,CAEhD"}